Crate postcard

Expand description

§Postcard

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

Design primarily for #![no_std] usage, in embedded or other constrained contexts
Support a maximal set of serde features, so postcard can be used as a drop in replacement
Avoid special differences in code between communication code written for a microcontroller or a desktop/server PC
Be resource efficient - memory usage, code size, developer time, and CPU time; in that order
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

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

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.

Modules§

accumulator
An accumulator used to collect chunked COBS data and deserialize it.
de_flavors
Deserialization Flavors
experimental
Experimental Postcard Features
fixint
Fixed Size Integers
ser_flavors
Serialization Flavors

Structs§

Deserializer
A serde compatible deserializer, generic over “Flavors” of deserializing plugins.
Serializer
A serde compatible serializer, generic over “Flavors” of serializing plugins.

Enums§

Error
This is the error type used by Postcard

Functions§

from_bytes
Deserialize a message of type T from a byte slice. The unused portion (if any) of the byte slice is not returned.
from_bytes_cobs
Deserialize a message of type T from a cobs-encoded byte slice. The unused portion (if any) of the byte slice is not returned. The used portion of the input slice is modified during deserialization (even if an error is returned). Therefore, if this is not desired, pass a clone of the original slice.
from_eio
Deserialize a message of type T from a embedded_io::blocking::Read.
from_io
Deserialize a message of type T from astd::io::Read.
serialize_with_flavor
serialize_with_flavor() has three generic parameters, T, F, O.
take_from_bytes
Deserialize a message of type T from a byte slice. The unused portion (if any) of the byte slice is returned for further usage
take_from_bytes_cobs
Deserialize a message of type T from a cobs-encoded byte slice. The unused portion (if any) of the byte slice is returned for further usage. The used portion of the input slice is modified during deserialization (even if an error is returned). Therefore, if this is not desired, pass a clone of the original slice.
to_allocvec
Serialize a T to an alloc::vec::Vec<u8>.
to_allocvec_cobs
Serialize and COBS encode a T to an alloc::vec::Vec<u8>.
to_eio
Serialize a T to a embedded_io::blocking::Write,
to_extend
Serialize a T to a core::iter::Extend,
to_io
Serialize a T to a std::io::Write,
to_slice
Serialize a T to the given slice, with the resulting slice containing data in a serialized format.
to_slice_cobs
Serialize a T to the given slice, with the resulting slice containing data in a serialized then COBS encoded format. The terminating sentinel 0x00 byte is included in the output buffer.
to_stdvec
Serialize a T to a std::vec::Vec<u8>.
to_stdvec_cobs
Serialize and COBS encode a T to a std::vec::Vec<u8>.
to_vec
Serialize a T to a heapless::Vec<u8>, with the Vec containing data in a serialized format.
to_vec_cobs
Serialize a T to a heapless::Vec<u8>, with the Vec containing data in a serialized then COBS encoded format. The terminating sentinel 0x00 byte is included in the output Vec.

Type Aliases§

Result
This is the Result type used by Postcard.

Crate postcardCopy item path