IMCInter Module Communication
v5.5.11

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

The packet header contains handling information in the form of supplemental fields, it is always placed at the beginning of a packet.

Offset FieldTypeUnitRangeDescription
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.

The packet footer contains validation information in the form of supplemental fields, it is always placed at the end of a packet.

FieldTypeUnitRangeDescription
#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.

TypeSizeDescriptionSerialization
int8_t1 byte

8 bit signed integer.

As is.
uint8_t1 byte

8 bit unsigned integer.

As is.
int16_t2 bytes

16 bit signed integer.

As is.
uint16_t2 bytes

16 bit unsigned integer.

As is.
int32_t4 bytes

32 bit signed integer.

As is.
uint32_t4 bytes

32 bit unsigned integer.

As is.
int64_t8 bytes

A 64 bit signed integer

As is.
fp32_t4 bytes

32 bit single precision floating point number in IEEE 754 format.

As is.
fp64_t8 bytes

64 bit double precision floating point number in IEEE 754 format.

As is.
rawdatavariable

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.

plaintextvariable

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.

messagevariable

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-listvariable

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.

AbbreviationName
AAmpere
bitBit
bpsBits per second
byteByte
gGravity acceleration
cmCentimeter
cm/sCentimeter per second
dmDecimeter
dBDecibel
dB/mDecibel per meter
dBHzDecibel hertz
dBmDecibel milliwatts.
°Degree
°CDegree Celsius
GGauss
hPaHectopascal
HzHertz
kg/m/m/mKilogram per cubic metre
MiBMebibyte
KiBKiloibyte
mAhMilliampere hour
mMeter
m/sMeter per second
m/s/sMeter per square second
MbpsMegabits per second
msMillisecond
µsMicrosecond
minMinute
nsNanosecond
S/mSiemens per meter
kgKilogram
knKnots
NmNewton meter
NTUNephelometric Turbidity Unit
NNewton
PaPascal
%Percent
PPMParts per million
PPBParts per billion
PSUPratical Salinity Unit
1/mInverse Meter
pxPixel
mg/LMilligram per liter
µg/LMicrogram per liter
µMMicromolar
radRadian
rad/sRadian per second
rpmRevolutions per minute
rpm/sRevolutions per minute per second
sSecond
VVolt
mVMillivolt
EnumeratedEnumeration of integer values
ListComma separated list of values
BitfieldBit field
TupleListList of key/value tuples