pw_cobs#

Consistent Overhead Byte Stuffing (COBS) codec and zero-copy frame streamer

Experimental C++

  • Predictable wire overhead: Adds at most 1 byte per 254 payload bytes

  • In-place & streaming encoding: Encode in-place with EncodeBuffer or stream zero-copy payload chunks with Streamer

  • One-shot & streaming decoding: Decode complete 0x00-delimited frames or feed incoming serial bytes incrementally with Decoder

pw_cobs implements Consistent Overhead Byte Stuffing (COBS) for framing binary data over byte streams such as UART, USB CDC, or SPI. COBS transforms arbitrary payloads into blocks of non-zero bytes (0x01..0xFF) so that 0x00 unambiguously marks frame boundaries on the wire.

Quick start#

Encode a payload in-place using EncodeBuffer:

#include "pw_cobs/cobs.h"

void SendPacket(pw::ConstByteSpan payload) {
  pw::cobs::EncodeBuffer<256> buffer(payload);
  pw::ConstByteSpan encoded = buffer.Encode();
  WriteToSerial(encoded);
}

Decode incoming wire bytes incrementally with DecoderBuffer:

#include "pw_cobs/cobs.h"

constexpr size_t kMaxPayloadBytes = 256;
pw::cobs::DecoderBuffer<kMaxPayloadBytes> decoder;

void OnSerialBytesReceived(pw::ConstByteSpan rx_bytes) {
  decoder.Process(rx_bytes, [](pw::Result<pw::ByteSpan> frame) {
    if (frame.ok()) {
      HandlePacket(*frame);
    }
  });
}

Where to go next#

Get started & guides

Integrate pw_cobs into your build and learn how to encode, iterate blocks, and decode frames.

Get started & guides
API reference

Doxygen reference for the classes and functions in pw_cobs/cobs.h.

../api/cc/group__pw__cobs.html
Design

Wire format, block structure, and comparison with pw_hdlc.

Design
Code size analysis

Flash footprint of pw_cobs encoding and decoding primitives.

Code size analysis