Send and receive data over lossy streams of bytes.
Living in / inspired by the data link layer or layer 2 in the OSI networking model, this module enables sending slices of bytes of definite length over an underlying lossy transport that only supports sending an unstructured stream of bytes (a physical layer, such as ITM, UART or SPI).
The transport may corrupt the stream by dropping or modifying some bytes en route. When the transport returns corrupt data the decoder may return errors or corrupted payloads, but if the transport starts operating without losses again the decoder should return new uncorrupted frames.
typed modules to send and receive raw slices
of bytes or serialized structs respectively.
Currently the encoding is:
- Frame COBS-encoded to remove bytes equal to zero
- Payload: supplied by user
- A checksum computed over the payload. The type of checksum depends
on the configuration in
- A checksum computed over the payload. The type of checksum depends on the configuration in
- A terminating zero byte.
The encoding is not stable at the moment, i.e. it can and will change between minor versions. Consequently encoded data from this crate is unsuitable for long-term storage or transmission between different versions of an application. The API should be kept stable between versions where possible and the crate version will follow Rust semver rules on API changes.
use_std: Use standard library. Enabled by default, disable for no_std.
use_nightly: Enables unstable features that only work on nightly rust.
Required for practical no_std use.
trace: Enable to print all data to stdout for testing.
Payload data and encoded frame data are both slices of bytes but have separate types to help avoid mixing them up. You are encouraged to use these types in your own code when integrating with this crate. Definitions:
/// Arbitrary user data. pub type Payload = [u8]; /// Data that is encoded as a frame. It is ready to send, or may have /// just been received. pub type Encoded = [u8]; /// A buffer that is used as temporary storage. /// There are no guarantees on its contents after use. pub type TempBuffer = [u8]; /// Heap-allocated user data used as a return type. #[cfg(feature = "use_std")] pub struct BoxPayload(_); /// Heap-allocated frame data used as a return type. #[cfg(feature = "use_std")] pub struct BoxEncoded(_);
Note that data typed as
Encoded may be
efficiently passed as a function argument by reference, but is
returned using an opaque struct (
containing a heap-allocated value instead. Consequently
decode_* variants that require this are only available with
use_std Cargo feature.
Sending and receiving slices of bytes.
Representations of errors returned by this crate.
Sending and receiving serde-serialized structs.
Heap-allocated frame data used as a return type.
Heap-allocated user data used as a return type.
The frame ends with (and includes) this byte.
Data that is encoded as a frame. It is ready to send, or may have just been received.
Arbitrary user data.
A buffer that is used as temporary storage. There are no guarantees on its contents after use.