COBS (Consistent Overhead Byte Stuffing)

The COBS component provides efficient encoding and decoding for the Consistent Overhead Byte Stuffing algorithm, a packet framing protocol that ensures reliable packet boundaries in communication streams.

Key features: * Zero-byte elimination with consistent overhead (max ⌈n/254⌉ + 1 bytes) * Single packet API for basic encoding/decoding * Streaming API with thread-safe encoder/decoder classes * Support for fragmented data streams and packet batching

The component is designed for embedded communication protocols where reliable packet framing is essential, such as UART, SPI, or other serial interfaces.

• COBS Example
  • What This Example Tests
  • Detailed Test Coverage
    • Single Packet Test (Tests 1-12)
    • Streaming Encoder Test (Tests 1-5)
    • Streaming Decoder Test (Tests 1-6)
    • Edge Cases Test (Tests 1-4)
  • Test Scenario: 48-byte Packets
  • Build and Flash
  • Monitor Commands
  • Expected Output
  • Key Features Demonstrated
  • See Also

API Reference

Header File

• components/cobs/include/cobs.hpp

Classes

class Cobs

COBS (Consistent Overhead Byte Stuffing) encoder/decoder.

Provides single-packet encoding and decoding using the COBS algorithm with 0 as the delimiter. COBS encoding can add at most ⌈n/254⌉ + 1 bytes overhead. Plus 1 byte for the delimiter COBS changes the size of the packet by at least 1 byte, so it’s not possible to encode in place. MAX_BLOCK_SIZE = 254 is the maximum number of non-zero bytes in an encoded block.

See also

https://en.wikipedia.org/wiki/Consistent_Overhead_Byte_Stuffing

Public Static Functions

static inline constexpr size_t max_encoded_size(size_t payload_len)

Calculate maximum encoded size for a given payload length.

Parameters:

payload_len – Length of input data

Returns:

Maximum number of bytes needed for encoding (including delimiter)

static std::vector<uint8_t> encode_packet(std::span<const uint8_t> data)

Encode a single packet.

Parameters:

data – Input data to encode

Returns:

Encoded data with COBS encoding and delimiter

static size_t encode_packet(std::span<const uint8_t> data, std::span<uint8_t> output)

Encode a single packet to existing buffer.

Parameters:

• data – Input data to encode

• output – Output buffer span (must be at least max_encoded_size)

Returns:

Number of bytes written to output

static inline constexpr size_t max_decoded_size(size_t encoded_len)

Calculate maximum decoded size for a given encoded length.

Parameters:

encoded_len – Length of COBS-encoded data

Returns:

Maximum number of bytes needed for decoding (accounts for delimiter)

static std::vector<uint8_t> decode_packet(std::span<const uint8_t> encoded_data)

Decode a single packet from COBS-encoded data.

Parameters:

encoded_data – COBS-encoded data

Returns:

Decoded packet data, or empty if invalid

static size_t decode_packet(std::span<const uint8_t> encoded_data, std::span<uint8_t> output)

Decode a single packet to existing buffer.

Parameters:

• encoded_data – COBS-encoded data

• output – Output buffer span (must be at least max_decoded_size)

Returns:

Number of bytes written to output, or 0 if decoding failed

Header File

• components/cobs/include/cobs_stream.hpp

Classes

class CobsStreamDecoder

Streaming decoder for multiple COBS-encoded packets.

Useful for processing incoming data streams where packets may arrive in fragments or multiple packets may arrive together.

Public Functions

void add_data(std::span<const uint8_t> data)

Add encoded data to the decoder buffer.

Parameters:

data – New encoded data span

void add_data(std::vector<uint8_t> &&data)

Add encoded data to the decoder buffer (move semantics)

Parameters:

data – New encoded data vector (will be moved)

std::optional<std::vector<uint8_t>> extract_packet()

Try to extract the next complete packet. Removes the extracted data from the buffer.

Returns:

Decoded packet data, or empty if no complete packet found

const std::vector<uint8_t> &remaining_data() const

Access remaining unprocessed data for debug purposes.

Returns:

Const reference to buffered data that hasn’t been processed yet

size_t buffer_size() const

Get the size of buffered data.

Returns:

Number of bytes currently buffered

void clear()

Clear all buffered data.

class CobsStreamEncoder

Streaming encoder for multiple packets.

Useful for batching multiple packets together for transmission or for building up data to send in chunks.

Public Functions

void add_packet(std::span<const uint8_t> data)

Add a packet to be encoded.

Parameters:

data – Packet data span

void add_packet(std::vector<uint8_t> &&data)

Add a packet to be encoded (move semantics)

Parameters:

data – Packet data vector (will be moved)

const std::vector<uint8_t> &get_encoded_data() const

Get all encoded data as a single buffer for debug purposes.

Returns:

All encoded packets concatenated, const reference

std::vector<uint8_t> extract_data(size_t max_size)

Extract encoded data up to a maximum size.

Parameters:

max_size – Maximum number of bytes to extract

Returns:

Encoded data up to max_size bytes

size_t extract_data(uint8_t *output, size_t max_size)

Extract encoded data directly to a buffer.

Parameters:

• output – Output buffer to write data to

• max_size – Maximum number of bytes to extract

Returns:

Number of bytes actually written to output

size_t buffer_size() const

Get the current buffer size.

Returns:

Number of bytes currently buffered

void clear()

Clear all buffered data.