feat slot repeat

Objective

Describe the slot repeat feature in Baloo.

Description

It may be useful to repeat the execution of specific slots, or even entire communication rounds (e.g., when the number of slots required in a round is dynamic) or to retransmit lost packets. The slot repeat feature in Baloo caters for such needs.

This feature is always enabled.

Availability

Available for all supported platforms.

Compatibility

Compatible with all features and communication primitives.

Using the feature

Beware!
As described below, the repetition decisions are taken independently by every node. This is therefore a dangerous feature to use: all nodes must take decisions in a deterministic and/or compatible manner.
Otherwise, nodes may start executing different schedules, which will likely result in chaos!

Baloo allows the user to trigger repeating slots or rounds using the return values of the on_slot_post() callback function. The return type of this callback is gmw_repeat_event_t, which is a enum containing the following values:

typedef enum {
  GMW_EVT_NO_REPEAT      = 0,  /* No repetition */
  GMW_EVT_REPEAT_SLOT    = 1,  /* Repeat the last data slot */
  GMW_EVT_REPEAT_ROUND   = 2,  /* Start over the complete round */
  GMW_EVT_REPEAT_DEFAULT = 0   /* Set default same as 'NO_REPEAT' */
} gmw_repeat_event_t;

• If the user returns GMW_EVT_REPEAT_SLOT, the middleware executes again the same data slot (on_slot_pre() callback; data slot; then on_slot_post() callback). The same data slot may be repeated over and over again if the user keeps returning GMW_EVT_REPEAT_SLOT in the on_slot_post() callback.
• If the user returns GMW_EVT_REPEAT_ROUND, the middleware starts over the round execution with the first data slot (starting with the on_slot_pre() callback of the first slot).

Using this feature implies that the actual length of a round is dynamic. More precisely, it may vary in ways which are beyond the control of the middleware. Potentially, a round/slot could be repeated many times, until the round becomes larger than the round period.

Baloo addresses this issue as follows: The middleware does not control the number of repetitions, but it monitors the total length of the round. After each data slot (i.e., after the on_slot_post() callback has returned), the round length is checked against a given threshold. If the threshold is exceeded, the round is terminated immediately: the NET layer is notified with an error message, the on_round_finished() callback is executed, and the next round is scheduled.

The round length threshold is computed dynamically as follow:

threshold = period - GMW_CONF_T_PREPROCESS - GMW_CONF_T_POSTPROCESS_MIN

where GMW_CONF_T_PREPROCESS and GMW_CONF_T_POSTPROCESS_MIN are configuration parameters for Baloo pre- and post-processes. Informally, the threshold correspond to "the available time" between two rounds: the round period minus the reserved time for the pre- and post-processes.

Example

The baloo-crystal application (see \examples) provides an example use this feature. In this protocol, the schedule contains only two slots: one for sources to send application data, and another for the sink node to send back an acknowledgement. The NET layer repeats these two slots until no source has application data to send anymore (i.e., complete rounds are repeated).