Protocol description

Frame properties

Every communication frame generated by telemetry follows the same convention and structure. In case of doubt, always refer to the C code in repository in src/telemetry/c/telemetry.c which is the source of truth.

The frame has the following structure.

   B0       B1    B2     B3       Bn    Bn+1     Bn+2        Bn+2+m       Bn+3+m    Bn+4+m     Bn+6+m
+-------+--------------+-------------+--------+-------------------------+------------------+----------+
|  SOF  |    Header    |    topic    |  '\0'  |        Payload          |        CRC       |    EOF   |

• Framing: Byte-stuffing is performed by the classic algorithm. In the future, this will be replaced by Consistent Overhead Byte stuffing. SOF = 0xF7 EOF = 0x7F and escaping character is ESC = 0x7D.
• Header: Header is a 2 bytes indicator. For now, B2 is used only for indicating the type of the payload (uint8_t, float, etc.). B1 might be used in the future for holding major protocol version.
• topic: Topic of the frame, encoded in ASCII. No restrictions on character set for now, in the future inputs will be sanitized to avoid some special characters.
• payload: Binary (little endian) or string payload (ASCII).
• CRC : See here for implementation details

More about the protocol

The protocol is loosely inspired on the Publish-Subscribe pattern. Compared to this pattern, with telemetry the main difference is that both ends of the channel are in the same time publishers and subscribers. Basically, both PC and embedded application can send and receive data.

Such approach enables an extremely clean architecture, and the very loose coupling between both devices makes the code and processing much simpler. Each end of the communication channel is not aware of the other one. It just processes any received data, and publishes its own data without worrying about the other.

Beyond code simplicity, there is one major advantage with telemetry. The same codebase is used both on laptop or embedded system.

There is no master, no slave, no client, no server. Simply because there is no need to enforce one. You can implement any communication model with telemetry. The consequence, even though the protocol is presented for PC <-> Embedded communications, is that it can actually be used for Embedded <-> Embedded communications or PC <-> PC communications.