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|
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.
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.
|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
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)
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.
The message type indicates the specific message type within a message class.
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.
Indicates the length of the data field in bytes (octets).
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)|
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.|
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
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.
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
Likewise, when the escape character
0xE2 needs to be used within a message, it will be escaped in the same way:
|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|