• Stars
    star
    555
  • Rank 80,213 (Top 2 %)
  • Language
    Rust
  • License
    Apache License 2.0
  • Created over 5 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A no_std + serde compatible message library for Rust

Postcard

Documentation

Postcard is a #![no_std] focused serializer and deserializer for Serde.

Postcard aims to be convenient for developers in constrained environments, while allowing for flexibility to customize behavior as needed.

Design Goals

  1. Design primarily for #![no_std] usage, in embedded or other constrained contexts
  2. Support a maximal set of serde features, so postcard can be used as a drop in replacement
  3. Avoid special differences in code between communication code written for a microcontroller or a desktop/server PC
  4. Be resource efficient - memory usage, code size, developer time, and CPU time; in that order
  5. Allow library users to customize the serialization and deserialization behavior to fit their bespoke needs

Format Stability

As of v1.0.0, postcard has a documented and stable wire format. More information about this wire format can be found in the spec/ folder of the Postcard repository, or viewed online at https://postcard.jamesmunns.com.

Work towards the Postcard Specification and portions of the Postcard 1.0 Release were sponsored by Mozilla Corporation.

Variable Length Data

All signed and unsigned integers larger than eight bits are encoded using a Varint. This includes the length of array slices, as well as the discriminant of enums.

For more information, see the Varint chapter of the wire specification.

Example - Serialization/Deserialization

Postcard can serialize and deserialize messages similar to other serde formats.

Using the default heapless feature to serialize to a heapless::Vec<u8>:

use core::ops::Deref;
use serde::{Serialize, Deserialize};
use postcard::{from_bytes, to_vec};
use heapless::Vec;

#[derive(Serialize, Deserialize, Debug, Eq, PartialEq)]
struct RefStruct<'a> {
    bytes: &'a [u8],
    str_s: &'a str,
}
let message = "hElLo";
let bytes = [0x01, 0x10, 0x02, 0x20];
let output: Vec<u8, 11> = to_vec(&RefStruct {
    bytes: &bytes,
    str_s: message,
}).unwrap();

assert_eq!(
    &[0x04, 0x01, 0x10, 0x02, 0x20, 0x05, b'h', b'E', b'l', b'L', b'o',],
    output.deref()
);

let out: RefStruct = from_bytes(output.deref()).unwrap();
assert_eq!(
    out,
    RefStruct {
        bytes: &bytes,
        str_s: message,
    }
);

Or the optional alloc feature to serialize to an alloc::vec::Vec<u8>:

use core::ops::Deref;
use serde::{Serialize, Deserialize};
use postcard::{from_bytes, to_allocvec};
extern crate alloc;
use alloc::vec::Vec;

#[derive(Serialize, Deserialize, Debug, Eq, PartialEq)]
struct RefStruct<'a> {
    bytes: &'a [u8],
    str_s: &'a str,
}
let message = "hElLo";
let bytes = [0x01, 0x10, 0x02, 0x20];
let output: Vec<u8> = to_allocvec(&RefStruct {
    bytes: &bytes,
    str_s: message,
}).unwrap();

assert_eq!(
    &[0x04, 0x01, 0x10, 0x02, 0x20, 0x05, b'h', b'E', b'l', b'L', b'o',],
    output.deref()
);

let out: RefStruct = from_bytes(output.deref()).unwrap();
assert_eq!(
    out,
    RefStruct {
        bytes: &bytes,
        str_s: message,
    }
);

Flavors

postcard supports a system called Flavors, which are used to modify the way postcard serializes or processes serialized data. These flavors act as "plugins" or "middlewares" during the serialization or deserialization process, and can be combined to obtain complex protocol formats.

See the documentation of the ser_flavors or de_flavors modules for more information on usage.

Setup - Cargo.toml

Don't forget to add the no-std subset of serde along with postcard to the [dependencies] section of your Cargo.toml!

[dependencies]
postcard = "1.0.0"

# By default, `serde` has the `std` feature enabled, which makes it unsuitable for embedded targets
# disabling default-features fixes this
serde = { version = "1.0.*", default-features = false }

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

More Repositories

1

awesome-rust-streaming

A community curated list of Rust Language streamers
694
star
2

bbqueue

A SPSC, lockless, no_std, thread safe, queue, based on BipBuffers
Rust
408
star
3

internet-of-streams

An IoT project focused on teaching embedded, rustlang, and IoT concepts through coding streams
Rust
150
star
4

shell-hist

Inspect your shell history
Rust
93
star
5

nrf52dk-sys

A Rust Crate to develop on the Nordic nRF52-DK
C
87
star
6

cassette

A simple, single-future, non-blocking executor intended for building state machines. Designed to be no-std and embedded friendly.
Rust
81
star
7

teensy3-rs

Rust on the Teensy3
Rust
74
star
8

pellegrino

An aimless attempt at building a PC from scratch, in a vaguely eurorack/modular synth style.
Rust
66
star
9

pretty-hal-machine

Rust
59
star
10

postcard-rpc

An RPC layer for postcard based protocols
Rust
58
star
11

toml-cfg

A procedural macro for configuring constant values across crates
Rust
56
star
12

cobs.rs

Consistent Overhead Byte Stuffing
Rust
39
star
13

panic-persist

A panic handler that stores the panic message in RAM
Rust
37
star
14

brick-mount

Put your circuits on your plastic bricks of choice
HTML
36
star
15

tomlq

A tool for getting data from TOML files on the command line
Rust
30
star
16

trace-mutex

A mutex with timeout tracing
Rust
30
star
17

cmim

Cortex-M Interrupt Move
Rust
26
star
18

teensy3-rs-demo

Demo consumer of the teensy-rs library
Rust
22
star
19

frauth

Peer to Peer Friend Authentication
Rust
22
star
20

OtterPill-rs

Playing around with the OtterPill in Rust
Rust
21
star
21

trait-machine

A potentially interesting state machine PoC
20
star
22

blinq

A Blinking Queue
Rust
19
star
23

defmt-bbq

A generic bbqueue based transport for defmt log messages
Rust
19
star
24

yogslaw

An idea regarding non-commercial open source licensing
18
star
25

launch-rs

Rust tool/library for the Launchpad MK2
Rust
17
star
26

embedded-the-missing-parts

Sort of a book, sort of a twitter rant.
16
star
27

optional_c

Implementation of Rust's Optional Type in C
C
16
star
28

lipo-stamp

A tiny Li-Po/Li-Ion charging management SoM
Shell
16
star
29

forth3

A fresh take on an old forth. Intended to be rolled into anachro-forth (A4) in the future.
Rust
14
star
30

office-hours

Tracking Repo for James' Office Hours Livestreams
13
star
31

undroppable

Rust
13
star
32

mvdb-rs

Minimum Viable (Psuedo) Database
Rust
11
star
33

human-hash-rs

Create human readable hash digests
Rust
11
star
34

home-fleet

Devices on my home network
Rust
10
star
35

shared-rs

A macro for safely sharing data between application and interrupt context on cortex-m systems
Rust
9
star
36

soupstone

Rust
9
star
37

bbq2

An experimental next gen version of bbqueue
Rust
8
star
38

maxwell

A crate for gathering entropy from unreliable sources
Rust
8
star
39

signit

A CLI tool for signing messages with ed25519 keys
Rust
7
star
40

bluepill

Board Support Package in Rust for the STM32F103 "Blue Pill" board
Rust
7
star
41

mcf-config-demo

min_const_fn config
Rust
7
star
42

groundhog

A rolling timer abstraction
Rust
7
star
43

lab-notebook

James' public Labratory Notebook
7
star
44

grounded

Building blocks for handling potentially unsafe statics.
Rust
6
star
45

nrf52-hal

A Rust HAL for the nrf52 (nrf52832) chip
Rust
6
star
46

m60-keyboard

A Rust M60 Keyboard Firmware
Rust
6
star
47

rust-linking

Demo code interfacing Rust to other languages
C
5
star
48

simplebirb

A simple, static site, alternative to microblogging sites. Backwards compatible with RSS 2.0.
5
star
49

choreographer

A color pattern sequencer, intended for groups of RGB LEDs
Rust
5
star
50

tracing-serde-structured

An alternative, structured, adapter for serializing tracing types using serde
Rust
5
star
51

nRF5-sdk

Mirror of the Nordic nRF52 v13 SDK
C
5
star
52

nrf-smartled

nrf52 smartled driver
Rust
5
star
53

splitpea-sw

Splitpea software
Rust
5
star
54

jamesmunns-ng

My blog based on gutenberg/zola
HTML
4
star
55

postcard-forth

what if a different approach to ser/de?
HTML
4
star
56

shannon

An entropy-based session band
Rust
4
star
57

cc13x0-pac-demo

Rust
3
star
58

ecosystem-shake

A script for shaking out the embedded rust ecosystem
Rust
3
star
59

knurling-test-adapter

Rust
3
star
60

hello-armv5te

An example/template for Rust on the ARMv5TE (ARM9) platform
Rust
3
star
61

bitpool

Rust
3
star
62

tracing-serde-wire

A wire format for tracing-serde-structured
Rust
3
star
63

nrf52-bin-logger

A binary protocol for UARTE logging on the nRF52
Rust
3
star
64

nRF18650

An nRF52 breakout board based around an 18650 battery form factor
3
star
65

synthtoy

It's really not a thing.
Rust
3
star
66

splitpea

A split ortholinear keyboard. Smol.
3
star
67

bbq10kbd

An Embedded-HAL driver for @arturo182's bbq10kbd PMOD
Rust
3
star
68

elf-experiments

Rust
2
star
69

same70-experiments

Experiments with the "SAM E70 XPLAINED ULTRA"
Rust
2
star
70

irr-embedded-2018

Increasing Rust's Reach, Embedded Group, 2018
2
star
71

rustfactaday

Source of @rustfactaday on twitter
2
star
72

ztm-rust

Zero to Main in Rust
2
star
73

rustfest-iot-2017

Text Guide for the IoT Workshop at RustFest 2017
2
star
74

departure-rs

An experiment for managed interrupts on cortex-m in Rust
Rust
2
star
75

postcard-dyn

An experimental crate for dynamic ser/de with postcard + schemas
Rust
2
star
76

raumfahrer

Embedded Project in Rust
Rust
2
star
77

iot_first_principles

Internet of Things: From First Principles
2
star
78

pfg-rs

Podcast Feed Generator
Rust
2
star
79

fourpicsonewordsolver

Solves puzzles for the game 4pics1word or similar
Python
2
star
80

kolben

A collection of COBS
Rust
2
star
81

pigpio-i2c-rs

Reimplementation of I2C Sniffer in Rust
Rust
2
star
82

erdnuss-pub

Publicly known erdnuss bits
Rust
2
star
83

naught

Like Cargo Cross, but different
Shell
2
star
84

typeid-poc

Rust
1
star
85

git_crosstag

Tool for managing tags within and outside a git repository
Python
1
star
86

squid-node

squid node.
Rust
1
star
87

nrf52-blink-poc

Rust
1
star
88

doc-ctl

What if a document control system for personal projects
1
star
89

narrator

Experimental Tooling for the Intro To Embedded Workshop
Rust
1
star
90

squid-space

Rust
1
star
91

shall

An experiment in the direction of a Requirement Management Tool
Rust
1
star
92

lt-problem

Problem with lifetimes
Rust
1
star
93

sprue

A "form" like tool for creating Cargo Workspaces
Rust
1
star
94

feature-demo

Rust
1
star
95

Neotron-743-BIOS

A BIOS for the Neotron on an STM32H743 board
Rust
1
star
96

kuma-collar

A smartled collar for Kuma
Rust
1
star
97

splitalarm

A Stellaris Launchpad and XBee based alarm clock system
C
1
star
98

varint-shootout

Rust
1
star
99

delinkermap

Python
1
star
100

t9vm

Rust
1
star