Baloo callbacks

Objective

Describe the different callbacks used in Baloo, their footprint and intended usage.

Overview

Baloo facilitates the implementation of NET layer protocols with a well-defined programming interface, which is based on callback functions. At specific time points during a communication round, the middleware layer executes a set of callback functions, which contain the implementation of the protocol logic of the NET layer.

Five different callback functions are defined:
1. on_control_slot_post()
2. on_slot_pre()
3. on_slot_post()
4. on_round_finished()
5. on_bootstrap_timeout()

The protocol logic, i.e., the handling of application payloads and the definition of the desired control parameters, is implemented in callback functions. These callbacks are triggered by the middleware before and after each slot and at the end of a round. The middleware schedules the wake-up of the radio core and executes the ST primitives.

The middleware protothread is initialized using the gmw_init() function, which has the following prototype

void
gmw_init(gmw_protocol_impl_t* host_protocol_impl,
         gmw_protocol_impl_t* src_protocol_impl,
         gmw_control_t* control);

gmw_protocol_impl_t is a struct of function pointers, pointing to Baloo's callbacks. As shown by the prototype, the middleware supports having a specific gmw_protocol_impl_t for the host node.

The rest of this page describes each of Baloo's callbacks in more details.

1. The on_control_slot_post callback

The on control slot post() callback is executed at the end of the control slot. It is used to process the received control information and prepare for the round.

typedef gmw_sync_state_t (*gmw_on_control_slot_post_callback)(
              gmw_control_t*    in_out_control,
              gmw_sync_event_t  sync_event,
              gmw_pkt_event_t   pkt_event);

As shown in the prototype, this callback has three input parameters:

• A pointer to the control structure of the middleware layer informing the NET layer of the (potentially) new control information that have been received in the control slot.
• A synchronization event informing the NET layer whether the control packet was successfully received of missed.
• A packet event informing the NET layer of possible interference during the control slot. This is an advanced feature of Baloo, described in details in its dedicated page.

The callback allows the user to return the desired gmw_sync_state_t for the node in this round; that is, whether the node should be set in the Bootstrapping, Running, or Suspended state (see the middleware state machine description). This is an advanced feature of Baloo, described in details in its dedicated page.

The default is to return GMW_DEFAULT with this callback. The resulting state is then selected according to the middleware state machine.

2. The on_slot_pre callback

The on slot pre() callback is executed before each data slot. It is used to pass the payload to send to the middleware, if any.

typedef gmw_skip_event_t (*gmw_on_slot_pre_callback)(
                      uint8_t   slot_index,
                      uint16_t  slot_assignee,
                      uint8_t*  out_len,
                      uint8_t*  out_payload,
                      uint8_t   is_initiator,
                      uint8_t   is_contention_slot);

As shown in the prototype, this callback has six input parameters:

• The slot index identifying the upcoming data slot.
• The node ID assigned to this slot according to this round's schedule
• A pointer to the length of the payload to send in the upcoming data slot, if any.
• A pointer to the payload to send in the upcoming data slot, if any.
• A helper variable checking if the node ID matches the slot_assignee.
• A helper variable checking if the upcoming data slot is a contention slot. Contention is an advanced feature further described in its dedicated page.

The on slot pre() callback returns an event (type gmw_skip_event_t) which informs the middleware whether this slot should be skipped. Slot skipping is an advanced feature further described in its dedicated page.

The default is to return GMW_EVT_SKIP_DEFAULT with this callback, which results in the slot being executed normally.

The middleware will schedule the transmission or reception in the upcoming slot using the following logic:

• The slot is skipped if the user instructs so.
• Else, if the callback(s) overrun and the node is too late to start at the scheduled time, the slot is skipped.
• If the node is set the initiator for the slot, the middleware starts sending.
• If the slot is set as a contention slot and the payload length (out_len) is non-zero, the middleware starts sending.
• Otherwise, the middleware starts receiving.

3. The on_slot_post callback

The on slot post() callback is executed at the end of each data slot. It is used to process the received payload, if any.

typedef gmw_repeat_event_t (*gmw_on_slot_post_callback)(
                       uint8_t  slot_index,
                       uint16_t slot_assignee,
                       uint8_t  len,
                       uint8_t* payload,
                       uint8_t  is_initiator,
                       uint8_t  is_contention_slot,
                gmw_pkt_event_t pkt_event);

As shown in the prototype, this callback has seven input parameters:

• The slot index identifying the last data slot.
• The node ID assigned to this slot according to this round's schedule
• The length of the payload received in the last data slot, if any.
• A pointer to the payload received in the last data slot, if any.
• A helper variable checking if the node ID matches the slot_assignee.
• A helper variable checking if the last data slot was a contention slot. Contention is an advanced feature further described in its dedicated page.
• A packet event informing the NET layer of possible interference during the control slot (if the interference detection feature is used), or if the slot was missed (because of timing issues), or skipped (because on instructed to do so with the on_slot_pre() callback).

The on slot post() callback returns an event (type gmw_repeat_event_t) which informs the middleware whether this slot should be repeated. Slot repeat is an advanced feature further described in its dedicated page.

The default is to return GMW_EVT_REPEAT_DEFAULT with this callback, which results in the slot being not repeated.

4. The on_round_finished callback

The on round finished() callback is executed at the end of the round. It is used to do more time consuming state management or data processing.

typedef void (*gmw_on_round_finish_callback)(
     gmw_pre_post_processes_t* in_out_pre_post_processes);

This callback allows the user to specify the processes that should be polled at the end of this round and before the next round; the so-called pre- and post-processes.

5. The on_bootstrap_timeout callback

The on bootstrap timeout() callback is executed when a node fails to bootstrap (see the middleware's state-machine description).

typedef uint32_t (*gmw_on_bootstrap_timeout_callback)(void);

The callback allows the user to return the desired amount of time the middleware should wait before attempting to bootstrap again, which is thought of as a mean to save energy for example if the conditions are deemed bad for bootstrapping (e.g., heavy interference detected, host appears unreachable, etc.).

The returned value is interpreted as time in ms, thus supporting a range from 0 to a theoretical maximum of 4'294'967'295 ms, or 1193 hours, or 49 days. When 0 is returned, the middleware retries to bootstrap immediately.

---

Next > Baloo - Pre- and Post-Processes