Technology Careers Contact
Documentation Community Download Support

Modules communication is based on messages

Warning: Make sure to read and understand how to Create Luos modules before reading this page.

As a developer, you will have to create and use Luos messages to exchange informations between modulesSoftware element run by Luos that can communicate with other modules. Can be driver or app.. In order to do that, you have to understand how messages works.

Message structure

Luos messages are managed by the msg_t structure:

typedef struct{
    header_t header;
    unsigned char data[MAX_DATA_MSG_SIZE];
}msg_t;

All messages have a header. A header is a 7-byte field containing all information allowing modules to understand messages context. All modules on the network catch and decode the header of each sent and received message.

data is a table containing informations.

Info: MAX_DATA_MSG_SIZE represenst the maximum size of messages (default value is 128 bytes);

Header

To send data to any modules you want, you will have to fill some information on the header.

here is the header_t structure:

typedef struct{
    unsigned short protocol : 4;       /*!< RESERVED Protocol version. */
    unsigned short target : 12;        /*!< Target address, it can be (ID, Multicast/Broadcast, Type). */
    unsigned short target_mode : 4;    /*!< Select targeting mode (ID, ID+ACK, Multicast/Broadcast, Type). */
    unsigned short source : 12;        /*!< Source address, it can be (ID, Multicast/Broadcast, Type). */
    unsigned char cmd;                 /*!< msg definition. */
    unsigned short size;                /*!< Size of the data field. */
}header_t;
  • Protocol (4 bits): This field provides the protocol revision. This field is automatically filled, you don't have to deal with it.
  • Target (12 bits): This field contains the target address. Make sure to understand the real destination of this field, you have to know the addressing mode contained on the Target_mode field.
  • Target_mode (4 bits): This field indicates the addressing mode and how to understand the Target field. It can take different values:
    • ID: This mode allows to communicate with a unique module using its ID without acknowledgment return.
    • ID_ACK: This mode allows to communicate with a unique module using its ID with acknowledgment return.
    • Multicast/Broadcast: This mode allows multiple modules to catch a message. In this case, the message contains a type of data used by multiple modules.
    • Type: This mode sends a message to all modules with a given type, for example all "Sharp digital distance sensor".
  • Source (12 bits): The unique ID of the transmitter module.
  • CMD (8 bits): The command defines the transmitted data's type.
  • Size (16 bits): Size of the incoming data.

Receive and send a basic message

To send a message you have to:

  1. Create a message variable
  2. Set the target_mode
  3. Set the target
  4. Set the cmd
  5. Set your data size
  6. Set your data
  7. Send it.

Here is a basic reply example that you can find in a module reception callback:

void modules_cb(module_t *module, msg_t *msg) {
    if (msg->header.cmd == ASK_PUB_CMD) {
        // fill the message info
        msg_t pub_msg;
        pub_msg.header.target_mode = ID;
        pub_msg.header.target = msg->header.source;
        pub_msg.header.cmd = IO_STATE;
        pub_msg.header.size = sizeof(char);
        pub_msg.data[0] = 0x01;
        luos_send(module, &pub_msg);
        return;
    }
}

Module exclusion

Luos includes an acknowledgement management using the ID_ACK target_mode. This mode guaranties the proper reception of critical messages.

If Luos fails to reach its target using ID_ACK, it will retries 10 times. If the acknowledgement still fails, the targeted module is declared excluded. Excluded modules are removed from the routing table to avoid any messaging by any modules, preserving bandwidth for the rest of the system.

Large data

You will sometimes have to deal with large data that could be larger than the maximum 128-byte data on a Luos message. Fortunately, Luos is able to automatically fragment and de-fragment the data above this side. To do that, you will have to use another send function that will take care of setting the messages' size, and the data fields.

For example, here is how to send a picture:

// fill the large message info
msg_t msg;
color_t picture[300*300] = {/*Your favorite cat picture data*/};
msg.header.target_mode = ID_ACK;
msg.header.target = 12;
msg.header.cmd = COLOR;
luos_send_data(module, &msg, picture, sizeof(color_t)*300*300);
return;

In the reception callback, here is the code for retrieve the message with the receiving module (the one with ID 12):

color_t picture[300*300];
void modules_cb(module_t *module, msg_t *msg) {
    if (msg->header.cmd == COLOR) {
        luos_get_data(module, msg, (void*)picture);
    }
}

Note: If you have to deal with high-frequency real-time data, please read the Streaming page.

Time-triggered update messages

Luos provides a standard command to ask a module to retrieve values from a sensor, called ASK_PUB_CMD. However, sometimes apps need to poll values from sensors, but the act of repeatedly retriving a value using the ASK_PUB_CMD command may result in the use of a lot bandwidth and take useless resources. In this kind of polling situation, you can use the time-triggered auto-update features available from any Luos module. This feature allows you to ask a module to send you an update of any value each X milliseconds. To use it, you have to setup targeted module with a message containing a standard time object dictionarySet of objects based on SI metric system that can be transmitted through Luos messages. Any object can easily be converted in other units., but with a specific command associated to it.

For example, to update a module each 10ms:

time_luos_t time = time_from_ms(10);
msg_t msg;
msg.header.target = id;
msg.header.target_mode = IDACK;
time_to_msg(&time, &msg);
msg.header.cmd = UPDATE_PUB;
luos_send(app, &msg);

Info: Modules can handle only one time-triggered target, 2 modules of the same network can't ask a time-triggered value from the same module.

Warning: To prevent any ID movement, auto-update configuration is reseted on all modules at each detection (see Routing table page for more information).


Follow Watch Star

Luos is constantly evolving! Keep in touch to follow the last updates: