Robust Frame Arduino Lib

中文

Overview

Robust Frame is a lightweight serial data frame transmission library that provides a complete and reliable communication encapsulation solution. By defining a clear frame structure, intelligent byte escaping, and an efficient CRC8 checksum, it ensures stable data transmission over serial links. Developers can easily achieve reliable data exchange between devices without worrying about underlying byte stream processing.

Features

• Automatic frame delineation: Uses fixed frame headers and trailers, allowing the receiver to accurately identify the start and end of each frame from a continuous byte stream without relying on fixed lengths or timeout mechanisms.
• Transparent data transmission: Using byte escaping ensures that any raw data (including bytes identical to control characters) can be transmitted losslessly without confusion with frame boundaries.
• Data integrity protection: Built-in CRC-8/MAXIM checksum. The sender automatically appends the checksum value, and the receiver strictly verifies it, effectively preventing data errors caused by signal interference.

---

Protocol Details

Frame Structure

Each frame consists of the following four parts (in transmission order):

Field	Size	Description
Frame Header	1 byte	Fixed to 0xAA, marking the start of a frame
Payload	N bytes	Data processed with escaping
CRC	1 byte	Checksum calculated from the raw data, also escaped
Frame Trailer	1 byte	Fixed to 0x55, marking the end of a frame

Complete frame format: [0xAA] [Escaped Data + CRC] [0x55]

Escaping Rules

• Reserved characters: 0xAA (Frame Header), 0x55 (Frame Trailer), 0xDB (Escape Character)
• Escape character: 0xDB
• Conversion logic: When the raw data or CRC contains any of the reserved bytes above, the sender inserts 0xDB, followed by the result of XORing the original byte with 0x20 (i.e., original byte ^ 0x20).

Raw Byte	Escaped Transmission
0xAA	0xDB 0x8A
0x55	0xDB 0x75
0xDB	0xDB 0xFB

When the receiver encounters 0xDB during parsing, it reads the next byte, XORs it with 0x20 to restore the original byte, and stores the remaining bytes directly.

CRC8 Checksum

• Algorithm: CRC‑8/MAXIM (polynomial 0x31, initial value 0xFF, final XOR 0xFF), implemented using a lookup table for extremely high speed.
• Calculation target: The raw payload without escaping (excluding the frame header, trailer, and CRC itself).
• Sender: Calculates the CRC of the raw data, appends the CRC byte to the end of the raw data, and then escapes the entire payload + CRC.
• Receiver: First unescapes to get the raw payload + CRC, extracts the last byte as the received CRC, recalculates the CRC of the raw data, and compares the two to determine if the frame is valid.

Parser State Machine

The receiver uses a finite state machine to recover valid frames from the byte stream. The parsing process is divided into four stages:

1. Waiting for Frame Header

   • The parser continuously scans incoming bytes until it finds the frame header. Once matched, it immediately enters the data reception stage.

2. Receiving Data

   • In this stage, the parser stores received bytes into an internal buffer, but performs the following checks:
     • If a new frame header is received, it indicates a potential abnormality in the previous frame. The buffer is immediately cleared, and the parsing of a new frame restarts.
     • If the buffer is full (reaching the preset maximum payload length + 1), the frame is considered too long. The parser discards the current frame, resets, and waits for a new frame header.
     • If an escape character is received, it enters the "Escape Processing" stage, waiting for the next byte to be restored.
     • If a frame trailer is received, the frame end processing is triggered:
       • Checks if the received data length is at least 1 (containing at least the CRC byte).
       • Extracts the last byte as the received CRC, recalculates the CRC for the preceding data, and compares them.
       • If verification passes, it transitions to the "Frame Complete" state; otherwise, it discards the current frame and resets.
     • Other normal bytes are directly stored in the buffer.

3. Escape Processing

   • When an escape character is encountered in the "Receiving Data" stage, the parser reads the immediately following byte, XORs it with 0x20, and restores the original byte.
   • If the restored byte is not one of the three reserved bytes (0xAA, 0x55, 0xDB), the escape sequence is considered invalid. The parser discards the current frame and resets.
   • Otherwise, the restored byte is stored in the buffer, and the parser returns to the "Receiving Data" stage to continue processing subsequent bytes.

4. Frame Complete

   • After the CRC verification passes, the parser enters this state. Users can retrieve the valid raw data (excluding CRC) via data() and data_length().
   • On the next call to Process(), the parser automatically resets and begins synchronizing the next frame.

Throughout the entire process, any error (invalid escape, frame too long, CRC mismatch) will cause the parser to automatically reset and re-sync to the subsequent byte stream, allowing for rapid recovery without external intervention.

---

Robust Frame Library Installation

1. Open the Arduino IDE Library Manager

   • Menu: Tools → Manage Libraries...
   • Shortcut: Ctrl+Shift+I (Windows/Linux) or Cmd+Shift+I (Mac)

2. Search and Install

   • Enter RobustFrame in the search box.
   • Find the RobustFrame library.
   • Ensure the latest version is selected in the dropdown menu.
   • Click the INSTALL button.

   

   📌 Note: The screenshot is for reference only. Please always install the latest available version.

3. Install Dependencies

   • When the dependency installation dialog appears, select INSTALL ALL.

   

⚠️ Important Version Information
Screenshots in this document may show older versions. Always install the latest versions of both:

• RobustFrame library
• ByteBuffer dependency

If you skipped the dependency installation, please manually install the latest ByteBuffer library:

1. Open the Library Manager again.
2. Search for ByteBuffer.
3. Select the latest version in the dropdown menu.
4. Install it

---

Example

Protocol Robustness Test Example (test)

• Example Location: In the Arduino IDE, find this example via File → Examples → RobustFrame → test.
• Example Description: Randomly generates payload data, serializes it, parses it, and compares it with the original data to verify the correctness of the library's encoding and decoding.

License

This project is licensed under the MIT License - see the LICENSE file for details.