docs: add a Protobuf + COBS framing example

Runnable device->host protobuf-over-COBS demo (prost dev-dep); shows resync.

Author: ajsb85

Cargo.lock

@@ -29,6 +29,11 @@ alloc = []
 # Enables `std` (implies `alloc`). Reserved for future std-only conveniences.
 std = ["alloc"]
 
+[dev-dependencies]
+# Real Protocol Buffers, used only by the `protobuf_cobs` example. Dev-only, so
+# the published crate stays dependency-free for library users.
+prost = "0.14"
+
 [lints.rust]
 missing_docs = "warn"
 unsafe_code = "forbid"

Cargo.toml

@@ -136,6 +136,15 @@ rx.push(&chunk, |frame| match frame {
 });
 ```
 
+### Framing Protocol Buffers over serial
+
+COBS is the standard way to frame **Protobuf** on a UART/RS-485 link: protobuf
+serializes a message but doesn't delimit it, and COBS supplies the missing
+`0x00`-delimited framing — with instant resync after line noise, unlike
+length-prefixing. See [`examples/protobuf_cobs.rs`](examples/protobuf_cobs.rs)
+for a runnable device→host demo (`cargo run --example protobuf_cobs`) that
+survives a corrupted frame.
+
 ## Overhead
 
 COBS overhead is *data-independent*. Encoding an `n`-byte packet produces at most

README.md

@@ -0,0 +1,116 @@
+//! Framing Protocol Buffers over a serial link with COBS.
+//!
+//! Protobuf is a *serialization* format, not a *wire* format: it turns a message
+//! into a compact byte string but says nothing about where one message ends and
+//! the next begins. Push raw protobuf bytes down a UART and the receiver sees an
+//! undifferentiated stream. COBS supplies the missing framing:
+//!
+//! 1. **Serialize** the message with protobuf (the bytes usually contain `0x00`).
+//! 2. **COBS-encode** it so the payload contains no `0x00`, then append a single
+//!    `0x00` **delimiter**. That byte now unambiguously marks the end of a frame.
+//! 3. On the far end, split the stream on `0x00`, COBS-decode each frame, and hand
+//!    the bytes back to protobuf.
+//!
+//! The payoff over length-prefixing: if line noise corrupts a packet, the receiver
+//! just waits for the next `0x00` and **resynchronises on the very next message**,
+//! discarding only the broken frame instead of losing sync forever. This example
+//! shows exactly that.
+//!
+//! Run it with `cargo run --example protobuf_cobs`.
+//!
+//! On a microcontroller you would use the allocation-free API — [`framing::frame`]
+//! to encode into a fixed `[u8; N]`, and [`framing::StreamDecoder`] to decode an
+//! incoming stream into another fixed buffer — for the same result with zero heap.
+//!
+//! [`framing::frame`]: cobs_codec_rs::framing::frame
+//! [`framing::StreamDecoder`]: cobs_codec_rs::framing::StreamDecoder
+#![allow(missing_docs)]
+
+use cobs_codec_rs::framing::{FrameDecoder, frame_to_vec};
+use prost::Message;
+
+/// A telemetry packet a sensor node might stream to a host computer.
+#[derive(Clone, PartialEq, prost::Message)]
+struct SensorReading {
+    #[prost(uint32, tag = "1")]
+    node_id: u32,
+    #[prost(float, tag = "2")]
+    temperature_c: f32,
+    #[prost(uint64, tag = "3")]
+    uptime_ms: u64,
+    #[prost(string, tag = "4")]
+    label: String,
+}
+
+fn main() {
+    let readings = [
+        SensorReading {
+            node_id: 1,
+            temperature_c: 21.5,
+            uptime_ms: 1_000,
+            label: "cabin".into(),
+        },
+        SensorReading {
+            node_id: 2,
+            temperature_c: 100.0,
+            uptime_ms: 1_256,
+            label: "boiler".into(),
+        },
+        SensorReading {
+            node_id: 7,
+            temperature_c: -4.25,
+            uptime_ms: 99_999,
+            label: "outside".into(),
+        },
+    ];
+
+    // --- Device side: serialize each reading with protobuf, then COBS-frame it. ---
+    let mut wire: Vec<u8> = Vec::new();
+    let mut frame_starts: Vec<usize> = Vec::new();
+    for reading in &readings {
+        frame_starts.push(wire.len());
+        let payload = reading.encode_to_vec(); // protobuf bytes (the float alone brings 0x00s)
+        wire.extend_from_slice(&frame_to_vec(&payload)); // COBS-encode + trailing 0x00
+    }
+    // COBS guarantees a zero-free payload, so every 0x00 on the wire is a frame
+    // delimiter — provably one per frame.
+    println!(
+        "device: {} readings -> {} wire bytes; the only zeros are the {} frame delimiters",
+        readings.len(),
+        wire.len(),
+        readings.len(),
+    );
+
+    // --- Inject line noise: corrupt reading #2's leading COBS code byte. ---
+    // A bogus code byte makes the frame claim more data than it holds, so it fails
+    // to decode — a stand-in for any bit-flip a noisy UART might introduce.
+    wire[frame_starts[1]] = 0xFF;
+    println!("noise:  flipped a byte inside reading #2's frame\n");
+
+    // --- Host side: reassemble across misaligned UART reads and protobuf-decode. ---
+    let mut rx = FrameDecoder::new().max_frame_len(256);
+    let mut received = 0usize;
+    // A UART hands you whatever bytes have arrived, never aligned to frames.
+    for chunk in wire.chunks(5) {
+        rx.push(chunk, |frame| match frame {
+            Ok(bytes) => match SensorReading::decode(&*bytes) {
+                Ok(msg) => {
+                    received += 1;
+                    println!(
+                        "host <- node {:>2}: {:+6.2} C, up {:>6} ms, \"{}\"",
+                        msg.node_id, msg.temperature_c, msg.uptime_ms, msg.label,
+                    );
+                }
+                Err(err) => println!("host <- valid COBS frame but bad protobuf: {err}"),
+            },
+            Err(err) => println!("host <- dropped a corrupt frame ({err}); resyncing on next 0x00"),
+        });
+    }
+
+    println!(
+        "\nreceived {received}/{} readings: the corrupted frame was skipped and the \
+         stream resynced on the next delimiter.",
+        readings.len(),
+    );
+    assert_eq!(received, readings.len() - 1);
+}