a multi-purpose binary protocol for instruction interchange
Interchange formats like json or xml are great to keep data visible, but due to their parse and pack complexity they aren't used in embedded applications. There are alternatives like msgpack or Google's protocol buffer, which allow a more binary representation of data, but these protcols are still heavy and developers tend to rather implement their own 'simple' binary protocols instead of porting or using the big ones.
The protcol nstrct is designed to be an alternative in those situations where a tiny and versatile protocol is needed. The main transportable unit in nstrct are instructions which carry a dynamic amount of data in the form of arguments. Each instruction is identified by a code between 0-65535 which can be used by two communicating applications to identify the blueprint of the message. Arguments support all standard types of integers(boolean, int8-64, uint8-64, float32/64), strings, and arrays of integers or strings. There is no support for hashes by design to keep the pack and unpacking functions as small as possible. Check the main repository for the binary layout of the instructions.
Start using nstrct by getting the library for your favorite programming language:
This software has been open sourced by ElectricFeel Mobility Systems Gmbh and is further maintained by Joël Gähwiler.
Check the following tables and details to understand the binary structure of the protocol. Keep in mind that network byte order (BigEndian) is used by all implementations and libraries.
The default frame secures transport with a start and end byte plus the crc32 checksum of the payload.
The payload can be up to 64 KB.
+------+-----------------+~~~~~~~~~+-------------+------+
| 0x55 | payload_size 2B | payload | checksum 4B | 0xAA |
+------+-----------------+~~~~~~~~~+-------------+------+
- payload_size: the payload in amount of bytes
- payload: the payload
- checkusm: crc32 checksum of the payload
### Instruction
An instruction can have up to 255 arguments.
+-------------+---------------------+---------------------------+~~~~~~~~~~~~~+
| code uint16 | num_arguments uint8 | num_array_elements uint16 | [arguments] |
+-------------+---------------------+---------------------------+~~~~~~~~~~~~~+
- code: the instructions code
- num_arguments: the total of arguments following
- num_array_elements: the total number of array elements in all arguments following
- arguments: specified amount of arguments after each other
+------------+~~~~~~~+
| type uint8 | value |
+------------+~~~~~~~+
- type: the type of the value following
- value: the value
Argument Types:
Dec Type Length
--------------------
01 boolean 1B
10 int8 1B
11 int16 2B
12 int32 4B
13 int64 8B
14 uint8 1B
15 uint16 2B
16 uint32 4B
17 uint64 8B
20 float32 4B
21 float64 8B
31 string
32 array
A string can be up to 255 characters.
+--------------+~~~~~~+
| length uint8 | data |
+--------------+~~~~~~+
- length: the strings length
- data: the string itself
An array can have up to 255 elements.
+---------------------+--------------------+~~~~~~~~+
| elements_type uint8 | num_elements uint8 | values |
+---------------------+--------------------+~~~~~~~~+
- element_type: the type of the following elements
- num_elements: the total number of following elements
- values: all the elements values after each other