feat adv state machine

Objective

Describe the advanced state machine feature in Baloo.

Description

The middleware layer in Baloo implements a minimal state machine, in which a node is either in Bootstrapping, Suspended, or Running state. By default, the state transitions are driven by the reception of control packets.

However, the user can modify the default behavior (described here) using the on_control_post() callback function, by simply returning the desired state for the coming round.

This feature is always active.

Availability

Available for all supported platforms.

Compatibility

Compatible with all features and communication primitives.

Using the feature

The advanced state machine is implemented in the middleware layer. The on_control_post() callback function informs the NET layer of the (un)successful reception of control packets. The NET layer is responsible for updating the node internal state accordingly (e.g., updating some configuration parameters, triggering external processes, etc.)

In addition, the user can set the desired middleware state (i.e., Bootstrapping, Suspended, or Running) as return value of the callback. The following return values are available.

typedef enum {
  GMW_BOOTSTRAP = 0,
  GMW_RUNNING,
  GMW_SUSPENDED,
  GMW_DEFAULT,              /* State is decided on following the standard GMW
                             * state-machine */
} gmw_sync_state_t;

There is one return value per middleware state. GMW_DEFAULT results in following the minimal middleware state machine.

Example
This allows the user to force a node to be in the Running state, even though the control packet has been missed; according to the middleware state machine, the node should normally transition to the Suspended or Bootstrapping state.

It is important to keep in mind that using this feature nulls the guarantee given by Baloo that a node never disturbs the execution of the rest of the network.

Example (continued)
When a node misses a control packet but is forced in the Running state, if the control packet contained new information, this node does not know it and may start operating differently than the rest of the network...

Thus, this feature should be used with care. Here are some cases where it may be useful:

• To postpone a transition to the Bootstrapping state
  If there is intereference (e.g., detected using the corresponding feature), the user may want to leave nodes in the Suspended state, even after two consecutive control packet misses.
• To maintain nodes in the Running state
  If the control packet content never changes, the nodes do not need to receive the control packet in order to know how to operate (since it does not change, by design of the NET layer). The reception of the control packet only serves for synchronization. Similarly, if the control changes according to a static policy, nodes can recompute the control information locally. In such a case, it is common to use the static control feature as well.
• To momentarily turn off some nodes
  If there are many nodes in the network, some may be redundant and can be turned off, e.g., to save energy. This is the main purpose of the slot skipping feature.

Example

The baloo-crystal application (see \examples) provides an example use this feature: once synchronized (i.e., one control packet has been received), the source nodes always remain in the Running state.