framed 0.3.0

Send and receive data over lossy streams of bytes.
Documentation

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.

See the bytes or typed modules to send and receive raw slices of bytes or serialized structs respectively.

Encoding

Currently the encoding is:

  • Header:
    • Nothing here yet.
  • Body: payload COBS-encoded to remove bytes equal to zero
  • Footer:
    • A 2 byte checksum.
    • 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.

Cargo feature flags

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.

Byte slice wrapper types

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 Payload or Encoded may be efficiently passed as a function argument by reference, but is returned using an opaque struct (BoxPayload, BoxEncoded) containing a heap-allocated value instead. Consequently encode_* and decode_* variants that require this are only available with the use_std Cargo feature.