postcard

Postcard is a #![no_std]-first serializer/deserializer built on serde that produces a compact, documented, stable binary wire format designed for microcontrollers and other resource-constrained environments. It supports a full range of serde features, a pluggable Flavors system for composing serialization behavior (e.g. COBS framing, CRC checksums), and works identically whether the code runs on an embedded target or a desktop/server.

What You Get

• A serde-compatible to_vec/from_bytes API producing/parsing a compact variable-length-integer-based binary format
• A documented, stable wire specification (postcard.jamesmunns.com) so the format is portable across languages and versions
• A Flavors system letting you compose serialization behavior like COBS framing or CRC checksums as pluggable middleware
• First-class no_std support with heapless::Vec output, plus an optional alloc feature for alloc::vec::Vec output
• Companion crates (postcard-schema, postcard-derive) for schema generation and dynamic (de)serialization

Common Use Cases

• Serializing structured messages between a microcontroller and a host application over UART/BLE/USB
• Defining a stable wire protocol for embedded firmware that must remain compatible across releases
• Compact binary encoding for resource-constrained IoT devices where JSON/CBOR overhead is too costly
• Sharing the same serde data model between embedded firmware and a desktop/cloud counterpart

Under The Hood

Architecture - Postcard’s core lives in source/postcard/src, where ser/mod.rs and de/mod.rs implement serde’s Serializer/Deserializer traits against a variable-length-integer encoding (varint.rs) for all multi-byte integers, lengths, and enum discriminants; a Flavors abstraction (ser/flavors.rs, de/flavors.rs) lets callers layer additional processing — such as COBS framing or CRC — around the core (de)serialization without changing the format itself, and the repo is a Cargo workspace housing companion crates (postcard-schema, postcard-derive, postcard-dyn, and an in-progress postcard2) alongside the flagship crate.

Tech Stack - Nearly 100% Rust (edition 2021), with a minimal default dependency footprint (serde, cobs) and a large set of optional integrations gated behind Cargo features: heapless (multiple pinned versions for compatibility), embedded-io (0.4/0.6), defmt, crc, nalgebra, and an experimental postcard-derive macro crate; criterion is used for benchmarking varint encoding performance.

Code Quality - The postcard crate has 8+ dedicated test files under source/postcard/tests/ alongside inline unit tests, and the project maintains a published, versioned wire-format specification (in the spec/ directory and hosted docs) that acts as a contract tests are checked against; the README explicitly documents unsupported/risky serde attributes (serde(flatten), serde(skip_serializing_if)) with a tracking issue, showing an unusually candid accounting of edge-case limitations rather than silent gaps.

API Design - The API mirrors familiar serde-ecosystem conventions (to_vec/from_bytes, analogous to serde_json’s to_string/from_str), so existing serde users can adopt it with minimal new concepts beyond selecting a Flavor; feature-gating keeps the dependency surface small for embedded builds while still exposing a rich set of opt-in capabilities (schema derivation, dynamic serialization, numeric library interop) for users who need them.