Crate dot15d4_frame

Expand description

Zero-copy read and write structures for handling IEEE 802.15.4 MAC frames.

Each reader contains the following functions:

new: Create a new reader.
check_len: Check if the buffer is long enough to contain a valid frame.
new_unchecked: Create a new reader without checking the buffer length.

The most important reader is the Frame reader, which is used to read a full IEEE 802.15.4 frame. The reader provides the following functions:

frame_control: returns a FrameControl reader.
sequence_number: returns the sequence number if not suppressed.
addressing: returns an AddressingFields reader.
auxiliary_security_header: returns an AuxiliarySecurityHeader reader.
information_elements: returns an InformationElements reader.
payload: returns the payload of the frame.

§Reading a frame

For an incoming frame, use the Frame structure to read its content.

let frame = Frame::new(&frame).unwrap();
let fc = frame.frame_control();
let src_addr = frame.addressing().unwrap().src_address();
let dst_addr = frame.addressing().unwrap().dst_address();

assert_eq!(fc.frame_type(), FrameType::Beacon);

let Some(ie) = frame.information_elements() else { return; };

for payload in ie.payload_information_elements() {
     if matches!(payload.group_id(), PayloadGroupId::Mlme) {
        for nested in payload.nested_information_elements() {
             match nested.sub_id() {
                 NestedSubId::Short(NestedSubIdShort::TschTimeslot) => {
                     let time_slot = TschTimeslot::new(nested.content()).unwrap();
                     assert_eq!(time_slot.id(), 0);
                 }
                 _ => (),
             }
         }
     }
 }

§Writing a frame

Work in progress!

§Information Elements

The IEEE 802.15.4 standard defines a set of Information Elements (IEs) that can be included in the frame. These IEs are used to provide additional information about the frame, such as timestamping, channel hopping, and more. The IEs are divided into two groups: Header IEs and Payload IEs. Calling information_elements on a Frame reader returns an InformationElements reader. The reader provides access to the Header and Payload IEs, via the header_information_elements and payload_information_elements functions.

§Header Information Elements

The Header IEs are located in the frame header, and are used to provide information about the frame itself. The following IEs are defined in the standard:

VendorSpecific
Csl
Rit
DsmePanDescriptor
RendezvousTime
TimeCorrection
ExtededDsmePanDescriptor
FragmentSequencecontextDescription
SimplifiedSuperframeSpecification
SimplifiedGtsSpecification
LecimCapabilities
TrleDescriptor
RccCapabilities
RccnDescriptor
GlobalTime
Da
HeaderTermination1
HeaderTermination2

§Payload Information Elements

The Payload IEs are located in the frame payload, and are used to provide information about the payload itself. The following IEs are defined in the standard:

Esdu
Mlme: The MLME group contains a set of nested IEs. Call nested_information_elements to get an iterator over the nested IEs.
VendorSpecific
PayloadTermination

§Nested Information Elements

Some IEs contain nested IEs. The NestedInformationElementsIterator provides an iterator over the nested IEs. The iterator is used to parse the nested IEs.

The Nested IEs are split into two groups: Short and Long. The following short IEs are defined in the standard:

TschSynchronization
TschSlotframeAndLink
TschTimeslot
HoppingTiming
EnhancedBeaconFilter
MacMetrics
AllMacMetrics
CoexistenceSpecification
SunDeviceCapabilities
SunFskGenericPhy
ModeSwitchParameter
PhyParameterChange
OQpskPhyMode
PcaAllocation
LecimDsssOperatingMode
LecimFskOperatingMode
TvwsPhyOperatingMode
TvwsDeviceCapabilities
TvwsDeviceCategory
TvwsDeviceIdentification
TvwsDeviceLocation
TvwsChannelInformationQuery
TvwsChannelInformationSource
Ctm
Timestamp
TimestampDifference
TmctpSpecification
RccPhyOperatingMode
LinkMargin
RsGfskDeviceCapabilities
MultiPhy
VendorSpecific
Srm

The following long IEs are defined in the standard:

VendorSpecificNested
ChannelHopping

Structs§

AddressingFields: A reader/writer for the IEEE 802.15.4 Addressing Fields.
AddressingFieldsRepr: A high-level representation of the IEEE 802.15.4 Addressing Fields.
AuxiliarySecurityHeader: A reader/writer for the IEEE 802.15.4 Auxiliary Security Header.
CfpSpecification: A reader/writer for the IEEE 802.15.4 CFP Specification Header Information Element.
ChannelHopping: A reader/writer for the Channel Hopping IE.
ChannelHoppingRepr: A high-level representation of a Channel Hopping Nested Information Element.
ChannelHoppingSpecification: Channel Hopping Specification Header Information Element.
Csl: CSL Header Information Element.
DsmeSuperframeSpecification: DSME Superframe Specification Header Information Element.
Error: An error that can occur when reading or writing an IEEE 802.15.4 frame.
Frame: A reader/writer for an IEEE 802.15.4 frame.
FrameBuilder: A helper for building IEEE 802.15.4 frames.
FrameControl: A reader/writer for the IEEE 802.15.4 Frame Control field.
FrameControlRepr: A high-level representation of the IEEE 802.15.4 Frame Control field.
FrameRepr: A high-level representation of an IEEE 802.15.4 frame.
GtsSlot: Guaranteed Timeslot Descriptor
GtsSlotIterator: An Iterator over GTS slots.
GtsSpecification: Guaranteed Time Slot specification.
HeaderInformationElement: A reader/writer for the IEEE 802.15.4 Header Information Elements
HeaderInformationElementsIterator: An Iterator over HeaderInformationElement.
InformationElements: IEEE 802.15.4 Information Element reader.
InformationElementsRepr: A high-level representation of Information Elements.
KeyIdentifierField: A Key Identifier Mode field.
LinkDescriptor: A reader/writer for the Link Descriptor.
LinkDescriptorIterator: An Iterator over LinkDescriptor.
NestedInformationElement: A reader/writer for the IEEE 802.15.4 Nested Information Elements.
NestedInformationElementsIterator: An Iterator over NestedInformationElement.
PayloadInformationElement: A reader/writer for the IEEE 802.15.4 Payload Information Elements.
PayloadInformationElementsIterator: An Iterator over PayloadInformationElement.
RendezvousTime: Renzdevous Time Header Information Element.
Rit: RIT Header Information Element.
SecurityControl: A reader/writer for the IEEE 802.15.4 Security Control field.
SecurityLevel: A Security Level field.
SimplifiedSuperframeSpecification: A reader/writer for the IEEE 802.15.4 Simplified Superframe Specification Header Information Element.
SlotframeDescriptor: A reader/writer for the Slotframe Descriptor.
SlotframeDescriptorIterator: An Iterator over SlotframeDescriptor.
SuperframeSpecification: A reader/writer for the IEEE 802.15.4 Superframe Specification Header Information Element.
SupportedDsssDpskModulation: Supported DSSS DPSK Modulation values.
SupportedFrequencyBands: Supported Frequency Bands values.
SupportedRccPhyAndModulation: Supported Modulation values.
TimeCorrection: A reader/writer for the IEEE 802.15.4 Time Correction Header Information Element.
TimeCorrectionRepr: A high-level representation of a Time Correction Header Information Element.
TimeSynchronizationSpecification: Time Synchronization Specification Header Information Element.
TschLinkOption: TSCH link options bitfield.
TschSlotframeAndLink: A reader/writer for the TSCH slotframe and link IE.
TschSlotframeAndLinkRepr: A high-level representation of a TSCH Slotframe and Link Nested Information Element.
TschSynchronization: A reader/writer for the TSCH synchronization IE.
TschSynchronizationRepr: A high-level representation of a TSCH Synchronization Nested Information Element.
TschTimeslot: A reader/writer for the TSCH timeslot IE.
TschTimeslotRepr: A high-level representation of a TSCH Timeslot Nested Information Element.
TschTimeslotTimings: A TSCH time slot timings (figure 6-30 in IEEE 802.15.4-2020).
VendorSpecific: Vendor Specific Header Information Element.

Enums§

Address: An IEEE 802.15.4 address.
AddressingMode: IEEE 802.15.4 addressing mode.
BeaconOrder: Indicates the frequency at which the beacon is transmitted.
FrameType: IEEE 802.15.4 frame type.
FrameVersion: IEEE 802.15.4 frame version.
GtsDirection: GTS direciton.
HeaderElementId: Header Information Element ID.
HeaderInformationElementRepr: A high-level representation of a Header Information Element.
KeyIdentifierMode
NestedInformationElementRepr: A high-level representation of a MLME Payload Information Element.
NestedSubId: Nested Information Element ID.
NestedSubIdLong: Long Nested Information Element ID.
NestedSubIdShort: Short Nested Information Element ID.
PayloadGroupId: Payload Information Element ID.
PayloadInformationElementRepr: A high-level representation of a Payload Information Element.
SecurityAttributes
SuperframeOrder: The lenght of the active portion of the superframe.

Type Aliases§

Result: A type alias for Result<T, frame::Error>.