Message structure
Message structure¶
This section describes the general structure of all messages being send to/from the Mira module.
| Start character | Message header | Message type | Message index | Data size | Address | Data | CRC | |
|---|---|---|---|---|---|---|---|---|
| Size (octets) | 1 | 1 | 1 | 1 | 1 | Dynamic | Dynamic | 2 |
Start Character¶
The start character 0xE1 indicates the start of a new message. This may not exist anywhere else in the message, hence it must be escaped. You can read more
about character escaping in the corresponding section of this guide.
Message Header¶
The message header contains the message class, as well as a an indication if the message is a request or a response. Note: the request flag has nothing to do with application layer requests, these must be handled by the application if needed.
| Bit | 7 | 6 | 5-4 | 3-0 |
|---|---|---|---|---|
| Description | Response flag | Address flag | Reserved | Message class |
Response flag (Bit 7)
This bit indicates if the message is a request or a response. The value 0 means request, the value 1 means response. This relates only to messages on the
serial interface and does not relate to any application layer requests or responses.
Address flag (Bit 6)
This bit indicates if there is an address included in the message. The value 0 means no address (address field has length 0) and the value 1 indicates
that there is address information before the payload. For more information about the use of addresses please see the Addressing field.
Reserved (Bit 5 to 4)
These bits are reserved for future use and shall be set to (and tested for) 0.
Message Class (Bit 3 to 0)
The following table lists and describes the message classes used in the API. For a complete summary of all message classes and messages, please see the dedicated message class and messages list.
Message Type¶
The message type indicates the specific message type within a message class.
Message Index¶
The message index counter is a sequence counter and should be incremented for every message. This gives the ability to send multiple messages without waiting for a response from the the Mira module and then later be able to pair the responses with result codes later.
Data Size¶
Indicates the length of the data field in bytes (octets).
Address field¶
This field is optional and includes address information. If the field exists then the size of it depends on which type of address that is included in the address field. When this field is available it consists of one octet defining the addressing mode and address type followed by 0 to 16 octets containing the actual address. The address mode is defined in the four most significant bits (high nibble) and the address type is defined in the four least significant bits (low nibble) of the first octet of this field.
Available addressing modes
| Address mode | Value (Hex) | Description |
|---|---|---|
| Address | 0x1 | Address contained in the following bytes in address field |
| To Network Root | 0x2 | Send the message to the network root (aka. coordinator) |
| Link local | 0x4 | Local broadcast (to neighbour nodes) |
| Broadcast | 0x8 | Broadcast (to all nodes in network) |
Address types
Addressing modes are combined with the following types of addresses to fully describe the way messages are addressed:
| Address type | Value (Hex) | Address size (octets) | Description |
|---|---|---|---|
| No address | 0x1 | 0 | No address used. (Typically used with Broadcast or To Network Root modes.) |
| EUI64 address | 0x2 | 8 | The EUI64 address of a node. |
Examples
Send to network root will define the address as 0x21, sending to a specific node defines the address as 0x12followed by the EUI64 of the device.
Broadcasting to all nodes in the network defines the address as 0x81.
Data¶
Payload data.
CRC¶
This is a CRC16 value. The checksum shall be calculated using the CRC-16 CCITT/KERMIT version. Calculation shall be performed over the entire message except the start character (and CRC field). If special characters (characters that needs escaping) exist in the message, the CRC will be calculated for the non-escaped byte sequence. The CRC can also contain special characters. Any escaping shall be performed after the CRC is calculated, read more in the escaping section of this guide. CRC data shall be transfered in little endian byte order.
Escaping¶
The value of the start character is 0xE1 and it will always indicate the start of a message. If the start character is identified in a byte string the possible
incomplete previous message shall be discarded and a new message reception shall be initiated.
Whenever the octet value 0xE1 occurs in a message that shall be sent, it needs to be escaped to avoid ambiguity on the serial line.
Escaping is performed by replacing the special character with the concatenation of 0xE2 and the special character's 1's complement (bit-wise inverse).
So, the special character 0xE1 is escaped by replacing it with 0xE21E
Likewise, when the escape character 0xE2 needs to be used within a message, it will be escaped in the same way: 0xE2 becomes 0xE21D.
| Character | Abbreviation | Value | Description | Escaped sequence |
|---|---|---|---|---|
| Start Character | STC | 0xE1 | Indicates start of a message | 0xE21E |
| Escape Character | ESC | 0xE2 | Precedes a special character’s 1’s complement inside a message | 0xE21D |