Specification
Message format
An IMC packet is a header of 20 bytes, the message payload, and a footer of 2 bytes. Messages are made of the field types below, serialized one after the other with no padding.
#Packet layout
header payload footer
#Header
The packet header contains handling information in the form of supplemental fields, it is always placed at the beginning of a packet.
| Offset | Field | Type | Unit | Range | Description |
|---|---|---|---|---|---|
| 0 | #syncSynchronization Number |
uint16_t |
– | value
0xFE55 |
The synchronization number marks the beginning of a packet. It denotes the packet API version and can be used to deduce the byte order of the sending host. It encodes value 0xFE[major][minor] where [major] equals the major version number of the protocol and [minor] equals the minor version of the protocol. The packet recipient is responsible for the correct interpretation of the synchronization number and byte order conversions. |
| 2 | #mgidMessage Identification Number |
uint16_t |
– | – | The identification number of the message contained in the packet. This field is used for correct message interpretation and deserialization. |
| 4 | #sizeMessage size |
uint16_t |
byte | – | The size of the message data in the packet. |
| 6 | #timestampTime stamp |
fp64_t |
s | – | The time when the packet was sent, as seen by the packet dispatcher. The number of seconds is represented in Universal Coordinated Time (UCT) in seconds since Jan 1, 1970 using IEEE double precision floating point numbers. |
| 14 | #srcSource Address |
uint16_t |
– | – | The Source IMC system ID. |
| 16 | #src_entSource Entity |
uint8_t |
– | – | The entity generating this message at the source address. |
| 17 | #dstDestination Address |
uint16_t |
– | – | The Destination IMC system ID. |
| 19 | #dst_entDestination Entity |
uint8_t |
– | – | The entity that should process this message at the destination address. |
#Footer
The packet footer contains validation information in the form of supplemental fields, it is always placed at the end of a packet.
| Field | Type | Unit | Range | Description |
|---|---|---|---|---|
#crc16Check Sum (CRC-16-IBM) |
uint16_t |
– | – | The check sum field is computed using the CRC-16-IBM with polynomial 0x8005 (x^16 + x^15 + x^2 + 1). The data contributing for the CRC includes all preceding header and message bytes. |
#Field types
Messages and packets can be viewed as a finite collection of fields. The list of valid field types is presented below.
| Type | Size | Description | Serialization |
|---|---|---|---|
int8_t | 1 byte | 8 bit signed integer. | As is. |
uint8_t | 1 byte | 8 bit unsigned integer. | As is. |
int16_t | 2 bytes | 16 bit signed integer. | As is. |
uint16_t | 2 bytes | 16 bit unsigned integer. | As is. |
int32_t | 4 bytes | 32 bit signed integer. | As is. |
uint32_t | 4 bytes | 32 bit unsigned integer. | As is. |
int64_t | 8 bytes | A 64 bit signed integer | As is. |
fp32_t | 4 bytes | 32 bit single precision floating point number in IEEE 754 format. | As is. |
fp64_t | 8 bytes | 64 bit double precision floating point number in IEEE 754 format. | As is. |
rawdata | variable | Variable length byte stream. | A sequence of type rawdata is serialized by prepending a value of type uint16_t, representing the length of the sequence, to the stream of bytes. On deserialization the prepended value is used to retrieve the correct size of data bytes. The rawdata type length is limited only by the communication protocol in use. |
plaintext | variable | Variable length ASCII character stream. | A sequence of type plaintext is serialized by prepending a value of type uint16_t, representing the length of the sequence, to the stream of ASCII characters. On deserialization the prepended value is used to retrieve the correct ASCII character sequence size. The plaintext type length is limited only by the communication protocol in use. |
message | variable | An inline message. Useful for encapsulating other messages. | A field of type message is serialized by prepending a value of type uint16_t, representing the identification number of the message, to the serialized message payload. The special identification number 65535 must be used when no message is present. On deserialization the prepended value is used to retrieve the correct message identification number. The message type length is limited only by the communication protocol in use. |
message-list | variable | A list of messages. | A field of type message-list is serialized by prepending a value of type uint16_t, representing the number of messages in the list, to the serialized message payload. On deserialization the prepended value is used to retrieve the correct number of messages |
#Serialization
To ensure accurate transportation some field types may require special treatment on transmission and reception. The operation of preparing a field type for transmission is called serialization, the inverse action is called deserialization. No special serialization is required for types that are not described in the table below, their values should be used as is.
#Units
The following table lists the units used in the subsequent chapters.
| Abbreviation | Name |
|---|---|
A | Ampere |
bit | Bit |
bps | Bits per second |
byte | Byte |
g | Gravity acceleration |
cm | Centimeter |
cm/s | Centimeter per second |
dm | Decimeter |
dB | Decibel |
dB/m | Decibel per meter |
dBHz | Decibel hertz |
dBm | Decibel milliwatts. |
° | Degree |
°C | Degree Celsius |
G | Gauss |
hPa | Hectopascal |
Hz | Hertz |
kg/m/m/m | Kilogram per cubic metre |
MiB | Mebibyte |
KiB | Kiloibyte |
mAh | Milliampere hour |
m | Meter |
m/s | Meter per second |
m/s/s | Meter per square second |
Mbps | Megabits per second |
ms | Millisecond |
µs | Microsecond |
min | Minute |
ns | Nanosecond |
S/m | Siemens per meter |
kg | Kilogram |
kn | Knots |
Nm | Newton meter |
NTU | Nephelometric Turbidity Unit |
N | Newton |
Pa | Pascal |
% | Percent |
PPM | Parts per million |
PPB | Parts per billion |
PSU | Pratical Salinity Unit |
1/m | Inverse Meter |
px | Pixel |
mg/L | Milligram per liter |
µg/L | Microgram per liter |
µM | Micromolar |
rad | Radian |
rad/s | Radian per second |
rpm | Revolutions per minute |
rpm/s | Revolutions per minute per second |
s | Second |
V | Volt |
mV | Millivolt |
Enumerated | Enumeration of integer values |
List | Comma separated list of values |
Bitfield | Bit field |
TupleList | List of key/value tuples |