|0.1.3||Nov 10, 2022|
|0.1.1||Feb 6, 2022|
|0.1.0||Feb 6, 2022|
#147 in Embedded development
6,794 downloads per month
Used in 2 crates (via electricui-embedded)
corncobs: Corny COBS encoding/decoding in Rust
This crate provides Consistent Overhead Byte Stuffing (COBS) support for
Rust programs, with a particular focus on resource-limited embedded
Provides both fast (buffer-to-buffer) and small (in-place or iterator-based) versions of both encode and decode routines.
const fnfor computing the maximum encoded size for a given input size, so you can define fixed-size buffers precisely without magic numbers.
No features are enabled by default. Embedded programmers do not need to specify
default-features = false when using
corncobs because who said
be the default anyhow? People with lots of RAM, that's who.
std: if you're on one of them "big computers" with "infinite memory" and can afford the inherent nondeterminism of dynamic memory allocation, this feature enables routines for encoding to-from
Vec, and an
When to use COBS
COBS lets us take an arbitrary blob of bytes and turn it into a slightly
longer blob that doesn't contain a certain byte, except as a terminator at
the very end.
corncobs implements the version of this where the byte is zero.
corncobs can take a sequence of arbitrary bytes, and turn it into a
slightly longer sequence that doesn't contain zero except at the end.
The main reason you'd want to do this is framing. If you're transmitting a series of messages over a stream, you need some way to tell where the messages begin and end. There are many ways to do this -- such as by transmitting a length before every message -- but most of them don't support sync recovery. Sync recovery lets a receiver tune in anywhere in a stream and figure out (correctly) where the next message boundary is. The easiest way to provide sync recovery is to use a marker at the beginning/end of each message that you can reliably tell apart from the data in the messages. To find message boundaries in an arbitrary data stream, you only need to hunt for the end of the current message and start parsing from there. COBS can do this by ensuring that the message terminator character (0) only appears between messages.
Unlike a lot of framing methods (particularly SLIP), COBS guarantees an upper
bound to the size of the encoded output: the original length, plus two bytes,
plus one byte per 254 input bytes.
corncobs provides the
function for sizing buffers to allow for worst-case encoding overhead, at
When to use this implementation of COBS
corncobs for an art project that required streaming video over a 3-10
Mbit/s RS485 link on an 80MHz Cortex-M4. Its performance is more than sufficient
for this task.
At the time, I had identified two main alternatives:
postcard-cobs says it's a fork of
cobs-rs, but it
isn't, it's a fork of
cobs. This confused me too.) They didn't
quite work for my application:
At about 8 CPU cycles per incoming bit, I needed decoding to be very, very fast.
corncobsdecoding is about 60x faster and met my needs. (Encode is about 3x faster. Both numbers are for non-pathological data, i.e. not all zeroes. See the benchmark suite for details.)
I was receiving messages in a circular buffer via DMA, where they'd be concatenated but separated with zeroes. This meant I couldn't express the length of incoming messages at compile time, and I needed an exact number of bytes consumed for each message, both of which made using
I was operating in an environment where data transmission was not perfectly reliable, and needed the firmware to recover gracefully from corruption or lost data, i.e. not panic. This made using
postcard-cobsdifficult. (They don't have a public bug tracker, so I was unable to report the panics.)
postcard-cobs are compatible; the
test suite in
corncobs proves this. (Note that you need to make sure to strip
trailing zeroes before handing data to
postcard-cobs to avoid panics.)
corncobs is also mostly compatible with
cobs-rs with the exception of the
encoding of empty messages, an area where I think
cobs-rs has a bug. So, you
can mix and match -- if you would like the slower-but-more-predictable encoding
postcard-cobs and the faster decode of
corncobs, go for it.
The performance tests I used to reach these conclusions are checked in. I keep an eye on them, in case I can stop maintaining my own crate some day. :-) You can run them with:
$ cargo bench comparison
Tips for using COBS
If you're designing a protocol or message format and considering using COBS, you have some options.
Optimizing for size: COBS encoding has the least overhead when the data
being encoded contains
0x00 bytes, at least one for every 254 bytes sent. In
practice, most data formats achieve this. However...
Optimizing for speed: COBS encode/decode, and particularly the
implementation, goes fastest when data contains as few
0x00 bytes as
possible -- ideally none. If you can adjust the data you're encoding to avoid
zero, you can achieve higher encode/decode rates. For instance, in one of my
projects that sends RGB video data, I just declared that red/green/blue value 1
is the same as 0, and made all the 0s into 1s, for a large performance
Running the tests and stuff
For my future self, when I have forgotten the incantations. Or for you!
cargo bench (easy enough so far)
cargo install honggfuzz cargo hfuzz run encode # or... cargo hfuzz run decode