pw_hdlc: Design#

Pigweed AI summary: The pw_hdlc module is a lightweight and simple serial communication protocol that implements a subset of the HDLC protocol. It supports only HDLC unnumbered information frames, which are encoded with an initial frame delimiter byte, escaped special bytes, payload data, an escaped and calculated frame check sequence, and a final frame delimiter byte. Frames may be received in multiple parts and are decoded by unescaping the data and verifying the frame check sequence. If the verification fails, the frame is discarded and an error

pw_hdlc implements a subset of the HDLC protocol.

Protocol Description#

Pigweed AI summary: The HDLC implementation in pw_hdlc only supports HDLC unnumbered information frames, which are encoded with a flag byte, address field, control field, frame check sequence (CRC-32), and payload. Before sending payload data through serial, special bytes are escaped and the frame check sequence is calculated and escaped. Frames may be received in multiple parts, so the pw_hdlc decoder stores received data in a buffer until the ending frame delimiter is read. If the checksum verification fails, the frame

Frames#

Pigweed AI summary: The HDLC implementation in pw_hdlc only supports HDLC unnumbered information frames, which are encoded with a flag byte, address field, control field, payload, and frame check sequence.

The HDLC implementation in pw_hdlc supports only HDLC unnumbered information frames. These frames are encoded as follows:

_________________________________________
| | | |                          |    | |...
| | | |                          |    | |... [More frames]
|_|_|_|__________________________|____|_|...
 F A C       Payload              FCS  F

 F = flag byte (0x7e, the ~ character)
 A = address field
 C = control field
 FCS = frame check sequence (CRC-32)

Encoding and sending data#

Pigweed AI summary: This module explains the process of encoding and sending data through serial communication. It begins by writing an initial frame delimiter byte and then escaping special bytes before sending the payload data. The escaped bytes are listed in a table. The payload data is then written in a single pass, followed by the calculation and writing of the frame check sequence. Finally, a final frame delimiter byte is written to mark the end of the frame.

This module first writes an initial frame delimiter byte (0x7E) to indicate the beginning of the frame. Before sending any of the payload data through serial, the special bytes are escaped:

Unescaped Special Bytes

Escaped Special Bytes

7E

7D 5E

7D

7D 5D

The bytes of the payload are escaped and written in a single pass. The frame check sequence is calculated, escaped, and written after. After this, a final frame delimiter byte (0x7E) is written to mark the end of the frame.

Decoding received bytes#

Pigweed AI summary: This section explains how frames may be received in multiple parts and need to be stored in a buffer until the ending frame delimiter is read. The decoder unescapes the data and adds it to the buffer, then calculates and verifies the frame check sequence. If the verification is correct, the decoded frame is returned. If the checksum verification fails, the frame is discarded and an error is reported.

Frames may be received in multiple parts, so we need to store the received data in a buffer until the ending frame delimiter (0x7E) is read. When the pw_hdlc decoder receives data, it unescapes it and adds it to a buffer. When the frame is complete, it calculates and verifies the frame check sequence and does the following:

  • If correctly verified, the decoder returns the decoded frame.

  • If the checksum verification fails, the frame is discarded and an error is reported.