Crate framed [−] [src]
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
|
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 |
Sender |
Sends encoded frames over an inner |
Constants
FRAME_END_SYMBOL |
Functions
decode_from_reader |
Reads bytes from the supplied |
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 |
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 |
encode_to_writer |
Encode the supplied payload data as a frame and write it to the
supplied |
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. |