Crate framed

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.

Encoding

Currently the encoding is:

• The "body": payload COBS-encoded to remove bytes equal to zero
• 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.

trace: Enable to print all data to stdout for testing.

typed: Enables the typed sub-module for sending and receiving structs serialized with serde.

API

Payload data and encoded frame data have separate types to 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];

/// 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(_);

Consumers have a choice of interfaces to enable usability, efficiency, and use from no_std crates.

See the decode_* and encode_* functions for simple uses with various input and output types.

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.

For sending or receiving a stream of frames, consider the Reader and Writer structs that wrap an io::Read or io::Write instance.

Modules

channel	Vec-backed FIFO buffer of bytes for testing.
error	Representations of errors returned by this crate.
typed	Sending and receiving structs serialized with serde and ssmarshal.

Structs

BoxEncoded	Heap-allocated frame data used as a return type.
BoxPayload	Heap-allocated user data used as a return type.
Receiver	Receives encoded frames from an inner io::Read instance.
Sender	Sends encoded frames over an inner io::Write instance.

Constants

FRAME_END_SYMBOL

Functions

decode_from_reader	Reads bytes from the supplied Read until it has a complete encoded frame, then decodes the frame, returning the payload on the heap.
decode_to_box	Decode the supplied encoded frame, returning the payload on the heap.
decode_to_slice	Decode the supplied encoded frame, placing the payload at the beginning of the supplied buffer dest.
encode_to_box	Encode the supplied payload data as a frame and return it on the heap.
encode_to_slice	Encode the supplied payload data as a frame at the beginning of the supplied buffer dest.
encode_to_writer	Encode the supplied payload data as a frame and write it to the supplied Write.
max_decoded_len	Returns the maximum possible decoded length given a frame with the encoded length supplied.
max_encoded_len	Returns the maximum possible encoded length for a frame with the payload length supplied.

Type Definitions

Encoded	Data that is encoded as a frame. It is ready to send, or may have just been received.
Payload	Arbitrary user data.