Baloo control packet

Objective

Describe in details the elements of the control information (struct gmw_control_t) and their intended usage in Baloo.

Overview

The control packet sent by the host in the control slot plays a key role in Baloo: It is constructed such that if a node receives a control packet from the host, this nodes knows exactly

• how to execute the current communication round, and
• when to wake up for the next round.

It is important to distinguish between the control structure (containing all the sections that we describe in this page), from the control packet payload, which typically consists of a subset of these sections. Which sections are eventually included in the control packet depends on some of Baloo settings and one field in the schedule section.

Each node maintains locally two copies of the full control structure. One at the NET layer, on which the user has full control, and one at the middleware layer, which is updated automatically when new control packets are received (i.e., at the beginning of each round).

The control packet structure (type gmw_control_t) is composed of up to 6 sections.
1. The schedule section
2. The configuration section
3. The slot configuration section
4. The slot time list section
5. The user bytes section
6. The magic number section

The rest of these page goes through each section in details and describes their intended purpose.

The footprint of the control structure is provided at the end of this page (implemented and documented in os/net/mac/gmw/gmw-types.h).

1. The schedule section

The schedule section (a struct with type gmw_schedule_t) contains generic information about the round schedule, as illustrated below.

time and period

The time and period fields respectively hold the absolute network time and the time interval until the next round. Both variable are expressed as multiple of the same time base (see more details about different time management in Baloo). By default, time and period are expressed in second.

The time is not used by the middleware to schedule communication in Baloo: Everything is organised based on the relative time from a previous round. In other words, the middleware schedule a future round based on the start time of the current round and the period contained in the schedule. The time field is included in the schedule structure mostly for timestamping purposes (e.g., in a data collection scenario, distributed nodes may use the global time information to timestamp their sensor readings). It is not necessary to the correct behavior of Baloo.

n_slots

The n_slots fields has a double role. By default, the schedule is the only compulsory section sent in the control packet (except when using the static control feature). The three most significant bits of the n_slots field are flags that announce the inclusion of some optional sections.

• If bit 15 is set, the configuration section is included in the control packet,
• If bit 14 is set, the slot configuration section and the slot time array are included in the control packet,
• If bit 13 is set, the user bytes section is included in the control packet.

The access to these 3 special bits is facilitated by a set of macros packet a pointer to a gmw_control_t struct as argument (see gmw-control.h):

#define GMW_CONTROL_{HAS,SET,CLR}_{CONFIG,SLOT_CONFIG,USER_BYTES}(c)

The rest of the bits are used to encode the number of slots in the current round (from 0 to a theoretical maximum of 8191 slots).

slot array

Finally, the slot array contains the slot assignment for the round; that is, which node is set as initiator for each slot (see Baloo's callback). This array is sized based on the GMW_CONF_MAX_SLOTS macro, which the user can set freely.
By default, GMW_CONF_MAX_SLOTS is set to 10.

2. The configuration section

The configuration section (a struct with type gmw_schedule_t) contains global configuration parameters that apply to the whole communication round. As explained above, this section is included in the control packet if bit 15 is set in the n_slots field from the schedule section.

If the configuration section is not included in the control packet, the parameters from the previous round are used.

n_retransmissions

Many synchronous transmission primitives retransmit multiple times the same packet during communication (see e.g., Glossy). The number of retransmissions is a key parameter to trade reliability against energy consumption (which -roughly- grows linearly with the number of retransmissions).

The n_retransmissions field let the user select the desired number of retransmissions for all the data slots in the round. Unless configured otherwise, Baloo uses the GMW_CONF_TX_CNT_DATA macro, which has a default value of 3.

Note
The number of retansmissions for the control slot is controlled separately using the GMW_CONF_TX_CNT_CONTROL macro, which is set to 4 by default. The rationale is that since control packets are critical to the execution of Baloo, a high number of retransmissions might be desirable; whereas more energy-efficient settings might be interesting for the data slots (e.g, using only 2 retransmissions).

channel_hopping_mode

The feature is currently unused. It is left here as a place-holder for future developments.

max_packet_length

The max_packet_length field contains the maximal expected size of a packet at the radio level; that is, payload plus headers/footers. This value is used by the middleware to abort a failed reception (e.g., in case of interference); once max_packet_length have been received but reception is still ongoing, we know for sure the reception has failed. Aborting as soon as possible allows to save energy and leaves more time to (hopefully) receive another retransmission of the packet.

This field is set at initialisation to GMW_CONF_MAX_DATA_PKT_LEN + GMW_CONF_RF_OVERHEAD.

The user is expected to set the GMW_CONF_MAX_DATA_PKT_LEN macro to the maximal desired payload size for a Baloo packet (typically done in the project-conf.h file).

Note
This setting applies to the data packets only. The case of the control packet is handled separately by the middleware, and does not require any specific configuration from the user.

primitive

The primitive field contains the ID of the synchronous transmission primitive that is used in the data slots. By default, Glossy is used (primitive = 0). Using another primitive requires additional configurations, which are described in detailed in the Switching primitives feature page.

Note
The control packet is always sent using Glossy.

gap_time

The gap_time field lets the user select the desired time between two consecutive data slots, which must be large enough to execute the post- and pre-slot callbacks. The gap time and its interplay with other timing parameters is illustrated further down.

By default, the gap time can be set with a 100us precision, resulting in a value range of 0 to 25.5ms (see Baloo's time management for more details). The user can easily set the desired gap time with the following helper macro, which converts a numerical value in us into the corresponding setting (rounded up)

#define GMW_US_TO_GAP_TIME(t)

Unless configured otherwise, Baloo uses the GMW_CONF_T_GAP macro, which has a default value of 4000 us.

Note
The gap time after the control packet is set independently using the GMW_CONF_T_GAP_CONTROL macro. The rationale is that more processing might be required after the reception of the control packet than after a regular data slot. By default, GMW_CONF_T_GAP_CONTROL is set equal to GMW_CONF_T_GAP.

slot_time

The slot_time field lets the user select the desired time of a data slot. This corresponds to the maximal time a primitive is allowed to execute; in other words, the execution of a running primitive is interrupted if the slot time is exceeded. The slot time and its interplay with other timing parameters is illustrated further down.

By default, the slot time can be set with a 500us precision, resulting in a value range of 0 to 127.5ms (see Baloo's time management for more details). The user can easily set the desired slot time with the following helper macro, which converts a numerical value in us into the corresponding setting (rounded up)

#define GMW_US_TO_SLOT_TIME(t)

Unless configured otherwise, Baloo uses the GMW_CONF_T_DATA macro, which is set to the minimal slot length for a regular Glossy flood to compute (see gmw-conf.h and/or the description of Glossy).

Note
The slot time for the control packet is set independently using the GMW_CONF_T_CONTROL macro. By default, it is set to the minimal slot length for a regular Glossy flood to compute (see gmw-conf.h and/or the description of Glossy).

The slot, gap, and guard times define when the different nodes start the execution of the different slots in the round. More details about all the timing settings can be found in the Baloo's 's time management page.

3. The slot configuration section

In a given round, it may be that different slots would benefit from different configuration parameters. The slot configuration section (an array of type gmw_slot_config_t) caters for such cases. In the current implementation, the user can select on a per-slot basis

• the number of retransmissions,
• the slot time, and
• the primitive to execute.

This feature is described in details in the corresponding feature page. By default, this section is not present in the control structure. In this case, setting bit 14 of the n_slots field has no effect (see the schedule section description). The user can "activate" it with the following define (typically done in the project-conf.h file)

#define GMW_CONF_USE_CONTROL_SLOT_CONFIG

4. The slot time list section

The slot time list section contains - as the name suggests - a list of possible slot times. This section is used together with the slot configuration section, which is described in details in the corresponding feature page. By default, this section is not present in the control structure. In this case, setting bit 14 of the n_slots field has no effect (see the schedule section description).

5. The user bytes section

The user may have protocol-specific information to disseminate to the whole network (e.g., instruction to perform some local updates). The user bytes section (an array of uint8_t) caters for such cases. The user can easily set the desired number of user bytes with the following define (typically done in the project-conf.h file)

#define GMW_CONF_CONTROL_USER_BYTES

If the defined value is non-zero, the section is included in the control structure. It is included in the control packet by setting bit 13 of the n_slots field (see the schedule section description). By default, GMW_CONF_CONTROL_USER_BYTES is set to 0, thus this section is not present in the control structure.

6. The magic number section

A source node bootstraps by listening for a valid control packet (see Baloo's Program Flow). If multiple networks are running in parallel, a node could bootstrap on the "wrong" network. To prevent this, the magic number section lets the user define a 8-bit integer to the control packet, that serves as a network identifier.

By default, this section is not present in the control structure. The user can "activate" it and select the desired magic number with the following defines (typically done in the project-conf.h file)

#define GMW_CONF_USE_MAGIC_NUMBER
#define GMW_CONF_CONTROL_MAGIC_NUMBER 

Control structure footprint

typedef struct __attribute__((packed)) gmw_control {
  gmw_schedule_t schedule;
  gmw_config_t config;
#if GMW_CONF_USE_CONTROL_SLOT_CONFIG
  gmw_slot_config_t   slot_config[GMW_CONF_MAX_SLOTS];
  uint8_t             slot_time_list[GMW_CONTROL_SLOT_CONFIG_TIMELIST_SIZE];
#endif /* GMW_CONF_USE_CONTROL_SLOT_CONFIG */
#if GMW_CONF_CONTROL_USER_BYTES
  uint8_t user_bytes[GMW_CONF_CONTROL_USER_BYTES];
#endif /* GMW_CONF_CONTROL_USER_BYTES */
#if GMW_CONF_USE_MAGIC_NUMBER
  uint8_t magic_number;
#endif /*GMW_CONF_USE_MAGIC_NUMBER*/
} gmw_control_t;

---

Next > Baloo - State-machine