pcobs 1.0.0

Binary encoding for structured data communication
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

<div align="center">

# 📦 pcobs

**postcard + crc + cobs = structured data over anything**

[![Crates.io](https://img.shields.io/crates/v/pcobs)](https://crates.io/crates/pcobs)
[![Documentation](https://docs.rs/pcobs/badge.svg)](https://docs.rs/pcobs)
[![Rust](https://img.shields.io/badge/rust-1.83%2B-orange.svg)](https://www.rust-lang.org)
[![no_std](https://img.shields.io/badge/no__std-support-brightgreen.svg)](https://github.com/rust-embedded/wg)
[![zero-alloc](https://img.shields.io/badge/alloc--free-brightgreen.svg)](https://github.com/rust-embedded/wg)

**`no_std` • zero-allocation • embedded-ready**

</div>

---

## 💡 Why?

You've got structs. You need to send them over UART/TCP/USB/whatever.

**pcobs** gives you:
- 📝 **postcard** — compact serde serialization, `no_std` friendly
- 🔐 **CRC-16** — catch corrupted packets
- 🧱 **COBS framing** — zero-byte delimiters, no escaping hell
- 💾 **Zero allocations** — stack-only, no `Vec`/`Box`/`HashMap`
- ⚡ **`no_std`** — works on bare-metal, no OS required

Two functions. That's it.

```rust
let len = serialize(&my_struct, &mut buf)?;
let my_struct = deserialize::<MyStruct>(&mut buf, len)?;
```

---

## 🚀 Quick Start

```toml
[dependencies]
pcobs = "1"
serde = { version = "1", features = ["derive"] }
```

```rust
use pcobs::{serialize, deserialize};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct SensorData {
    id: u8,
    value: f32,
    flags: u16,
}

// Sender
let data = SensorData { id: 1, value: 23.5, flags: 0xABCD };
let mut buf = [0u8; 256];
let len = serialize(&data, &mut buf)?;
stream.write_all(&buf[..len])?;
stream.write_all(&[0x00])?; // COBS delimiter

// Receiver
let mut buf = [0u8; 256];
let n = read_until_delimiter(stream, &mut buf)?;
let decoded: SensorData = deserialize(&mut buf, n)?;
```

---

## 📐 Packet Format

```
┌────────────────────────────────────────┬──────┐
│ Payload                     │ CRC-16   │ 0x00 │
│ postcard(your data)         │ checksum │      │
│────────────────────────────────────────│      │
│ COBS frame                             │ delim│
│ no zeros in encoded data               │      │
└────────────────────────────────────────┴──────┘
```
Steps:
1. Serialize your struct with **postcard**
2. Append **CRC-16** checksum (2 bytes)
3. COBS-encode the whole thing
4. Send over your transport, appending a **0x00** delimiter

---

## 📏 Buffer Math

Encoding is done **in-place** - no buffer splitting needed. COBS adds minimal overhead (at most 1 byte per 254 bytes), plus 2 bytes for CRC.

| Buffer | Max Payload |
|--------|-------------|
| 64 B   | ~60 B       |
| 256 B  | ~252 B      |
| 512 B  | ~508 B      |
| 1024 B | ~1018 B     |

---

## 🛠️ Transport Agnostic

Works over anything that moves bytes:

- 📡 UART / Serial
- 🌐 TCP sockets
- 🔌 USB bulk endpoints
- 📻 Radio (LoRa, BLE, etc.)
- 🧪 Pipes / files for testing

---

## ⚡ Features

- **`no_std`** — works on bare-metal, no OS required
- **Zero allocations** — stack-only, no heap, embedded-friendly
- `serde` — derive your structs
- Single-pass encoding
- In-place decoding