Skip to content

Link Layer Protocol Documentation

Overview

This document describes the link layer protocol, which provides a common framing mechanism for communication over various transport methods (e.g., TCP, RS232). The link layer ensures integrity and interoperability of messages.

Frame Structure

Field Size (bytes) Description
STX 1 Start of Text (0x02).
MessageType 1 Type of the message (e.g., Request, Response, KeepAlive).
BODY Variable Encapsulated payload, structure depends on MessageType.
ETX 1 End of Text (0x03).

Body Structures

1. Request (MessageType 0x01)

Field Size (bytes) Description
API Key 4 4-byte unique key for authentication (e.g., 0x12 0x34 0xAB 0xCD).
Length (N) 4 Big-endian length of the JSON-RPC payload.
Payload N JSON-RPC payload as a UTF-8 encoded JSON string.
CRC16 2 CRC16 checksum (polynomial 0xA001) calculated over Length and Payload.

The network order for Length and CRC16 are big endian

2. Response & Event (MessageType 0x02 / 0x03)

Field Size (bytes) Description
Length (N) 4 Big-endian length of the JSON-RPC payload.
Payload N JSON-RPC payload as a UTF-8 encoded JSON string.
CRC16 2 CRC16 checksum (polynomial 0xA001) calculated over Length and Payload.

3. KeepAlive & ACK (MessageType 0x04 / 0x05)

  • No body.

4. Error (MessageType 0x06)

Field Size (bytes) Description
Error Code 1 Single byte indicating the error (see Error Codes).

Error Codes

Error Code Value (Hex) Description
INVALID_MESSAGE 0x01 Message frame is malformed.
INVALID_MSG_TYPE 0x02 Message type is unsupported.
CRC_ERROR 0x03 CRC16 checksum mismatch.
LEN_ERROR 0x04 Payload length is invalid.
NOT_AUTHENTICATED 0x05 API key is missing or invalid.

CRC16 Calculation

The CRC16 checksum is calculated using the polynomial 0xA001 over the concatenated Length and Payload fields of the body.

Example Pseudocode

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
def calculate_crc16(data):
    crc = 0xFFFF
    for byte in data:
        crc ^= byte
        for _ in range(8):
            if crc & 0x0001:
                crc = (crc >> 1) ^ 0xA001
            else:
                crc >>= 1
    return crc

Example

Consider the following request

1
2
3
4
5
6
{
    "jsonrpc": "2.0",
    "method": "getDeviceInfo",
    "id": "1234",
    "params": null
}
Payload Breakdown
1
{"jsonrpc":"2.0","method":"getDeviceInfo","id":"1234","params":null}
Payload

The UTF-8 encoded JSON payload is: 

1
7B 22 6A 73 6F 6E 72 70 63 22 3A 22 32 2E 30 22 2C 22 6D 65 74 68 6F 64 22 3A 22 67 65 74 44 65 76 69 63 65 49 6E 66 6F 22 2C 22 69 64 22 3A 22 31 32 33 34 22 2C 22 70 61 72 61 6D 73 22 3A 6E 75 6C 6C 7D

Example

For this example I trimmed all the white spaces, but they can stay in the request as the field is in ASCII

Frame Fields
Field Value (Hex) Description
STX 02 Start of Text.
MessageType 01 Request message type.
API Key 12 34 AB CD Example 4-byte API key.
Length 00 00 00 4B Payload length (75 bytes, big-endian).
Payload 7B 22 6A ... 6C 7D UTF-8 encoded JSON payload.
CRC16 40 A2 CRC16 checksum over Length and Payload.
ETX 03 End of Text. 
1
2
3
4
5
6
0000     02 01 12 34 AB CD 00 00 00 44 7B 22 6A 73 6F 6E      ...4.....D{"json
0010     72 70 63 22 3A 22 32 2E 30 22 2C 22 6D 65 74 68      rpc":"2.0","meth
0020     6F 64 22 3A 22 67 65 74 44 65 76 69 63 65 49 6E      od":"getDeviceIn
0030     66 6F 22 2C 22 69 64 22 3A 22 31 32 33 34 22 2C      fo","id":"1234",
0040     22 70 61 72 61 6D 73 22 3A 6E 75 6C 6C 7D 40 A2      "params":null}@.
0050     03                                                  .
Notes
  • CRC16 Calculation: The CRC16 checksum is calculated using the polynomial 0xA001 over the concatenated Length and Payload fields.
  • The payload length in this example is 68 bytes (decimal), represented as 0x00000044 in big-endian format.