PacketSerial Arduino Library

PacketSerial is a small, efficient Arduino library designed for packet-based serial communication. It allows Arduinos to send and receive serial data packets that can contain any byte value (0-255) by using encoding schemes to delimit packets.

Supported encoding schemes include:

• COBS (Consistent Overhead Byte Stuffing)
• SLIP (Serial Line IP)
• User-defined encoding

Standard Arduino Serial.print() methods convert numeric values into ASCII strings. For example, sending the byte 255 results in 3 bytes of ASCII data ('2', '5', '5') plus delimiters. This approach is inefficient for large or structured data because it increases the number of bytes transmitted (e.g., a 4-byte unsigned long can take up to 10 bytes in ASCII).

PacketSerial provides a way to send raw bytes directly, which is much more compact, while solving the problem of 'boundary collision' (where a data byte happens to have the same value as your packet delimiter).

PacketSerial is primarily an Arduino library but is compatible with any system that implements COBS or SLIP encoding.

Supported Platforms & Integrations

• Arduino: Requires Arduino IDE version 1.5 or higher.
• openFrameworks: Can be used via the ofx::IO::PacketSerial object within the ofxSerial addon.
• Python: Compatible with Python environments using the PySerial package combined with either the COBS or SLIP (e.g., sliplib) packages.
• General: Any library correctly implementing COBS or SLIP encoding is compatible.

The core PacketSerial_ class is templated, allowing you to define the encoder, packet marker, and buffer size at compile time.

Template Signature: template<typename EncoderType, uint8_t PacketMarker = 0, size_t BufferSize = 256> class PacketSerial_

Common Typedefs:

• PacketSerial: Uses COBS encoder, marker 0, buffer 256.
• COBSPacketSerial: Uses COBS encoder, marker 0, buffer 256.
• SLIPPacketSerial: Uses SLIP encoder, marker SLIP::END, buffer 256.

Customizing Parameters: To change the buffer size or marker, instantiate the template directly:

// COBS with 512 byte buffer
PacketSerial_<COBS, 0, 512> myPacketSerial;

// SLIP with 512 byte buffer
PacketSerial_<SLIP, SLIP::END, 512> myPacketSerial;

The PacketSerial class wraps an Arduino Stream object (like Serial, Serial1, or SoftwareSerial) to automatically encode and decode byte packets.

Important: PacketSerial should have exclusive access to the serial Stream. You should avoid calling standard Stream functions like Serial.print() or Serial.write() directly, as this will interfere with the packet framing. Instead, use myPacketSerial.send() to transmit data.

To allow compact raw byte transmission without accidentally triggering packet boundaries, PacketSerial uses Consistent Overhead Byte Stuffing (COBS).

In its default mode, COBS removes all zero values from the packet. This allows the sender and receiver to use the value zero as an unambiguous packet boundary marker.

Efficiency: For a raw packet of length SIZE, the maximum encoded buffer size is SIZE + SIZE / 254 + 1. This is significantly more efficient than ASCII encoding.

To process incoming serial packets, you must call the update() method within your main loop() function. This method handles receiving, decoding, and triggering the registered packet handler.

void loop()
{
    // Your program here.

    // Call update to receive, decode and process incoming packets.
    myPacketSerial.update();
}

To begin using PacketSerial, you should follow these steps:

1. Understand the motivation: Read the background introduction to understand why packet-based communication is necessary.
2. Setup: Follow the getting started guide for installation and initial configuration.
3. Learn via examples: Review the code in the examples directory to see practical implementations.
4. Reference API: For detailed technical specifications of the classes and methods, consult the official API documentation.

You can use PacketSerial with non-standard serial configurations, secondary hardware serial ports, or SoftwareSerial by using setStream(). Any class implementing the Stream interface is compatible.

// Using a non-standard configuration (e.g., 7N1)
PacketSerial myPacketSerial;
void setup() {
    Serial.begin(300, SERIAL_7N1);
    myPacketSerial.setStream(&Serial);
    myPacketSerial.setPacketHandler(&onPacketReceived);
}

// Using SoftwareSerial
SoftwareSerial mySoftwareSerial(10, 11);
void setup() {
    mySoftwareSerial.begin(38400);
    myPacketSerial.setStream(&mySoftwareSerial);
    myPacketSerial.setPacketHandler(&onPacketReceived);
}

You can install the library using the Arduino IDE:

1. Navigate to the Tools > Manage Libraries ... menu.
2. Search for PacketSerial.
3. Select the library and install it.

Alternatively, you can manually download or clone the repository from GitHub and place it in your Arduino libraries folder.

To use the default Serial object with default communication settings (usually SERIAL_8N1), initialize PacketSerial and call begin() with the desired baud rate. You must also register a packet handler using setPacketHandler().

PacketSerial myPacketSerial;

void setup()
{
    myPacketSerial.begin(9600);
    myPacketSerial.setPacketHandler(&onPacketReceived);
}