Simple framing (marking packet start/stop) with self-synchronisation. More...

#include <stddef.h>
#include <stdint.h>
#include <span>
#include <iterator>

Classes
class	Cobs::Encoder
class	Cobs::Decoder
	Decodes data as a state-machine. More...

Functions
constexpr size_t	Cobs::maxEncodedSize (size_t dataSize)

Variables
constexpr uint8_t	Cobs::maxRunLength = 254

Detailed Description

Simple framing (marking packet start/stop) with self-synchronisation.

Constant Overhead Byte Stuffing (COBS)

If you have packets and you want to mark their end, you have two choices:

Put size at the start: this is not self-synchronizing, that is if you miss the start (or have an error in it) then you can't recover.
Delimit them, say with the zero byte. This is what we do.

However, the zero byte may appear in the packet, so you need to escape it somehow. The simple solution of using an escape character (say '\', then the ASCII digit '0' for zero, and '\' for an escaped escape) can end up doubling the encoded data size in some cases.

Another approach is byte-stuffing: instead of using the zero byte, put an extra byte at the start, with a value which is the count to the next escaped zero byte. Then at that position you put the count to the next zero byte and so on. If there is no zero byte, then you put the count to the end of the packet.

The remaining issue now is that a byte can only represent the range [0, 255] so the value 0xFF doesn't represent that there is a zero after 255 bytes, but that there are no zeros for 255 bytes, after which there is another extra byte.

This way the overhead is at most one extra byte every 255 bytes. And if there are zeros more frequently than that, then the overhead can be just one extra byte!

Function Documentation

◆ maxEncodedSize()

size_t Cobs::maxEncodedSize ( size_t dataSize )

constexpr

Returns the maximum size required for encoding data of the given size.

Variable Documentation

◆ maxRunLength

uint8_t Cobs::maxRunLength = 254

constexpr

Because we output runLength + 1, i.e. the pointer to the null not the last non-null byte, the maximum is 254

Classes