pub struct Frame { /* private fields */ }Expand description
An addressed mesh packet.
A frame names where it came from and where it is going, carries a sequence number its origin assigns, counts down a hop limit as it is relayed, and ends with a checksum. The byte layout is fixed and big-endian:
0 version
1..=4 source node (u32)
5..=8 destination node (u32, BROADCAST for every node)
9..=10 sequence id (u16)
11 hop limit
12.. payload
last 2 checksum (u16)The checksum covers every byte except the hop limit, which changes at each relay. So the check is end to end: a node can confirm a flooded packet’s payload is intact no matter how many relays forwarded it, and a relay spends a hop without recomputing it. The whole frame lives in a fixed buffer, so neither building nor parsing allocates.
§Examples
use pamoja_mesh::Frame;
let frame = Frame::new(0x0A, 0x0B, 7, b"hello").unwrap();
assert_eq!(frame.src(), 0x0A);
assert_eq!(frame.dst(), 0x0B);
assert_eq!(frame.id(), 7);
assert_eq!(frame.payload(), b"hello");
let received = Frame::parse(frame.as_bytes()).unwrap();
assert_eq!(received.payload(), b"hello");Implementations§
Source§impl Frame
impl Frame
Sourcepub const MAX_LEN: usize = 250
pub const MAX_LEN: usize = 250
The largest a mesh frame may be, in bytes, sized to the payload of a connectionless ESP-NOW frame.
Sourcepub const HEADER_LEN: usize = 12
pub const HEADER_LEN: usize = 12
The fixed header length in bytes: version, source, destination, sequence id, and hop limit.
Sourcepub const OVERHEAD: usize
pub const OVERHEAD: usize
The non-payload bytes of a frame: the header plus the trailing checksum.
Sourcepub const MAX_PAYLOAD: usize
pub const MAX_PAYLOAD: usize
The largest payload a single frame can carry.
Sourcepub const DEFAULT_HOP_LIMIT: u8 = 3
pub const DEFAULT_HOP_LIMIT: u8 = 3
The hop limit a newly built frame starts with, enough for a small local mesh.
Sourcepub fn new(
src: u32,
dst: u32,
id: u16,
payload: &[u8],
) -> Result<Frame, MeshError>
pub fn new( src: u32, dst: u32, id: u16, payload: &[u8], ) -> Result<Frame, MeshError>
Builds a frame from a source, a destination, a sequence id, and a payload, starting
at DEFAULT_HOP_LIMIT.
§Arguments
src- the origin node’s address.dst- the destination node’s address, orBROADCASTfor every node.id- the sequence number the origin assigns, increasing per message; with the source it identifies a packet as it floods, fordedup_key.payload- the bytes to carry.
§Returns
The frame, ready to send.
§Errors
Returns MeshError::PayloadTooLong if payload is longer than
MAX_PAYLOAD.
Sourcepub fn broadcast(src: u32, id: u16, payload: &[u8]) -> Result<Frame, MeshError>
pub fn broadcast(src: u32, id: u16, payload: &[u8]) -> Result<Frame, MeshError>
Builds a frame addressed to every node, for flooding the whole mesh.
§Arguments
src- the origin node’s address.id- the sequence number the origin assigns.payload- the bytes to carry.
§Returns
The broadcast frame, ready to send.
§Errors
Returns MeshError::PayloadTooLong if payload is longer than
MAX_PAYLOAD.
Sourcepub fn with_hop_limit(self, hop_limit: u8) -> Frame
pub fn with_hop_limit(self, hop_limit: u8) -> Frame
Sets the hop limit, the number of further relays the frame is allowed.
The checksum does not cover the hop limit, so this needs no recomputation and leaves a parsed frame still valid.
§Arguments
hop_limit- the new hop limit.0means no node should relay the frame further.
§Returns
The frame with the hop limit set, for chaining.
Sourcepub fn parse(bytes: &[u8]) -> Result<Frame, MeshError>
pub fn parse(bytes: &[u8]) -> Result<Frame, MeshError>
Parses a received frame, verifying its version and checksum.
§Arguments
bytes- the raw frame as it came off the radio.
§Returns
The validated frame.
§Errors
Returns MeshError::FrameTooShort or MeshError::FrameTooLong if the length is
outside a frame’s bounds, MeshError::UnsupportedVersion if the version byte is
not VERSION, or MeshError::CrcMismatch if the checksum does
not match the contents.
Sourcepub fn as_bytes(&self) -> &[u8]
pub fn as_bytes(&self) -> &[u8]
Returns the whole frame, checksum included, ready for the radio.
§Returns
The frame as a byte slice.