ieee802154

https://docs.rs/ieee802154/0.6.1/ieee802154/
Admin
ieee802154 is a partial Rust implementation of the IEEE 802.15.4 standard for low-rate wireless...
Tokens:10,315
Snippets:134
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Initialize PanId

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/struct.PanId.html

Example showing how to instantiate a new PanId.

```rust
use ieee802154::mac::PanId;

let pan_id = PanId(0x0123);
```

--------------------------------

### Initialize ExtendedAddress

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/struct.ExtendedAddress.html

Example of creating an instance of ExtendedAddress with a 64-bit value.

```rust
use ieee802154::mac::ExtendedAddress;

let ext_address = ExtendedAddress(0x0123456789abcdef);
```

--------------------------------

### Define a ShortAddress

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/struct.ShortAddress.html

Example of initializing a ShortAddress instance with a 16-bit value.

```rust
use ieee802154::mac::ShortAddress;

let short_address = ShortAddress(0x0123);
```

--------------------------------

### Implementing Frame Security with AES-128

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/index.html

This example shows how to define custom key and device lookup structures, initialize a security context, and perform frame encryption and decryption.

```rust
use ieee802154::mac::{
    frame::security::{
        KeyDescriptorLookup,
        DeviceDescriptorLookup,
        DeviceDescriptor,
        SecurityContext,
        AddressingMode,
        U16,
        KeyIdentifier,
        SecurityControl,
        AuxiliarySecurityHeader,
        SecurityLevel,
        KeySource,
    },
    Address,
    ExtendedAddress,
    PanId,
    Header,
    Frame,
    FrameVersion,
    FrameContent,
    FrameType,
    FrameSerDesContext,
    FooterMode,
};
use ccm::aead::generic_array::GenericArray;
use aes::Aes128;
use byte::TryWrite;

/// Static key descriptor lookup struct that always returns
/// the same key, given that the input address is
/// an extended address
struct StaticKeyLookup;

impl KeyDescriptorLookup<U16> for StaticKeyLookup {
    fn lookup_key_descriptor(
        &self,
        _address_mode: AddressingMode,
        _key_identifier: Option<KeyIdentifier>,
        device_address: Option<Address>,
    ) -> Option<(u64, GenericArray<u8, U16>)> {
        let key = GenericArray::default();
        if let Some(Address::Extended(pan_id, ExtendedAddress(u64_id))) = device_address {
            Some((u64_id, key))
        } else {
            None
        }
    }
}

/// A device descriptor lookup that always returns the same
/// device descriptor
struct BasicDevDescriptorLookup<'a> {
    descriptor: &'a mut DeviceDescriptor,
}

impl<'a> BasicDevDescriptorLookup<'a> {
    pub fn new(descriptor: &'a mut DeviceDescriptor) -> Self {
        Self { descriptor }
    }
}

impl<'a> DeviceDescriptorLookup for BasicDevDescriptorLookup<'a> {
    fn lookup_device(
        &mut self,
        _addressing_mode: AddressingMode,
        _address: Address,
    ) -> Option<&mut DeviceDescriptor> {
        Some(self.descriptor)
    }
}

const STATIC_KEY_LOOKUP: StaticKeyLookup = StaticKeyLookup {};
const FRAME_CTR: u32 = 0x00000000;

/// Get a new security context that uses the Aes128 block cipher for CCM operations,
/// and the static key lookup for determining the key to use
fn aes_sec_ctx<'a>(source_euid: u64, frame_counter: u32) -> SecurityContext<Aes128, StaticKeyLookup> {
    SecurityContext::new(source_euid, frame_counter, STATIC_KEY_LOOKUP)
}

fn main() {
    let source_euid = 0x01;
    let source = Some(Address::Extended(PanId(0x111), ExtendedAddress(source_euid)));
    let destination = Some(Address::Extended(PanId(0x111), ExtendedAddress(0x02)));

    let device_desc = &mut DeviceDescriptor {
        frame_counter: FRAME_CTR,
        exempt: false,
    };

    let mut sec_ctx = aes_sec_ctx(source_euid, FRAME_CTR);
    let auxiliary_security_header = Some(AuxiliarySecurityHeader::new(
        SecurityControl::new(SecurityLevel::ENCMIC128),
        Some(KeyIdentifier {
            key_source: Some(KeySource::Long(0xAA)),
            key_index: 48,
        }),
    ));

    let payload = &[0u8, 1u8, 2u8, 3u8, 4u8];
    let frame_to_secure = Frame {
        header: Header {
            ie_present: false,
            seq_no_suppress: false,
            frame_type: FrameType::Data,
            frame_pending: false,
            ack_request: false,
            pan_id_compress: false,
            version: FrameVersion::Ieee802154,
            seq: 127,
            destination,
            source,
            auxiliary_security_header,
        },
        content: FrameContent::Data,
        payload,
        footer: [0x00, 0x00],
    };
    let mut buffer = [0u8; 128];
    // Write/"send" a MAC frame. Security is applied if an auxiliary security header
    // is present (which it is, in this case)
    // Note that this does _not_ change the contents of the frame, the secured data
    // is only written to the buffer
    let len = match frame_to_secure.try_write(
        &mut buffer,
        &mut FrameSerDesContext::new(FooterMode::None, Some(&mut sec_ctx)),
    ) {
        Ok(size) => size,
        Err(e) => 0,
    };

    // Verify that encryption succeeded and tag was appended correctly
    assert_eq!(&buffer[..len], &[
        0x9, 0xec, 0x7f, 0x11, 0x1, 0x2, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x11, 0x1, 0x1, 0x0, 0x0,
        0x0, 0x0, 0x0, 0x0, 0x0, 0x1f, 0x0, 0x0, 0x0, 0x0, 0xaa, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0,
        0x30, 0xf8, 0x58, 0x90, 0xd2, 0x7f, 0x46, 0xcf, 0x1a, 0x73, 0xd3, 0xad, 0x65, 0xda, 0x6c, 0xd1,
        0x4b, 0x73, 0xef, 0xbe, 0x79, 0x31,
    ]);
    // Read/"receive" a MAC frame. Unsecuring it is attempted if the header
    // has security enabled
    let unsecured_frame = match Frame::try_read_and_unsecure(
        &mut buffer[..len],
        &mut FrameSerDesContext::new(FooterMode::None, Some(&mut sec_ctx)),
        &mut BasicDevDescriptorLookup::new(device_desc),
    ) {
        Ok((frame, _)) => frame,
        Err(e) => panic!("Could not unsecure frame! {:?}", e),
    };
    assert_eq!(unsecured_frame.payload, &[0u8, 1u8, 2u8, 3u8, 4u8])
}
```

--------------------------------

### Create FrameVersion from bits

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/enum.FrameVersion.html

Example usage of the from_bits method to convert raw bits into a FrameVersion instance.

```rust
use ieee802154::mac::FrameVersion;

let version = FrameVersion::from_bits(0b0);
assert_eq!(version, Some(FrameVersion::Ieee802154_2003));
```

--------------------------------

### Decode a MAC frame

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/struct.Frame.html

Example demonstrating how to read and decode a raw byte array into a Frame structure using the byte crate.

```rust
use ieee802154::mac::{
    Frame,
    Address,
    ShortAddress,
    FrameType,
    FooterMode,
    PanId,
    FrameSerDesContext,
};
use byte::BytesExt;

// Construct a simple MAC frame. The CRC checksum (the last 2 bytes) is
// invalid, for the sake of convenience.
let bytes = [
    0x01u8, 0x98,           // frame control
    0x00,                   // sequence number
    0x12, 0x34, 0x56, 0x78, // PAN identifier and address of destination
    0x12, 0x34, 0x9a, 0xbc, // PAN identifier and address of source
    0xde, 0xf0,             // payload
    0x12, 0x34,             // payload
];

let frame: Frame = bytes.read_with(&mut 0, FooterMode::Explicit).unwrap();
let header = frame.header;

assert_eq!(frame.header.seq,       0x00);
assert_eq!(header.frame_type,      FrameType::Data);
assert_eq!(header.has_security(),  false);
assert_eq!(header.frame_pending,   false);
assert_eq!(header.ack_request,     false);
assert_eq!(header.pan_id_compress, false);

assert_eq!(
    frame.header.destination,
    Some(Address::Short(PanId(0x3412), ShortAddress(0x7856)))
);
assert_eq!(
    frame.header.source,
    Some(Address::Short(PanId(0x3412), ShortAddress(0xbc9a)))
);

assert_eq!(frame.payload, &[0xde, 0xf0]);

assert_eq!(frame.footer, [0x12, 0x34]);
```

--------------------------------

### Convert Bits to FrameType

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/enum.FrameType.html

Example of converting a raw bit value into a FrameType variant using from_bits.

```rust
use ieee802154::mac::FrameType;

let frame_type = FrameType::from_bits(0b001);
assert_eq!(frame_type, Some(FrameType::Data));
```

--------------------------------

### Unimplemented BlockCipher Implementation

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/trait.BlockCipher.html

Example of an implementation for the Unimplemented type, defining specific associated types for block size and parallel blocks.

```rust
impl BlockCipher for Unimplemented
{
    type BlockSize = UInt<UInt<UInt<UInt<UInt<UTerm, B1>, B0>, B0>, B0>, B0>;
    type ParBlocks = UInt<UTerm, B1>;
}
```

--------------------------------

### Serialize an IEEE 802.15.4 Data Frame

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/struct.Frame.html

Demonstrates how to construct a Frame instance and serialize it into a byte buffer using FrameSerDesContext.

```rust
use ieee802154::mac::{
  Frame,
  FrameContent,
  FooterMode,
  Address,
  ShortAddress,
  FrameType,
  FrameVersion,
  Header,
  PanId,
  FrameSerDesContext,
};
use byte::BytesExt;

let frame = Frame {
    header: Header {
        ie_present:      false,
        seq_no_suppress: false,
        frame_type:      FrameType::Data,
        frame_pending:   false,
        ack_request:     false,
        pan_id_compress: false,
        version:         FrameVersion::Ieee802154_2006,

        seq:             0x00,
        destination: Some(Address::Short(PanId(0x1234), ShortAddress(0x5678))),
        source:      Some(Address::Short(PanId(0x1234), ShortAddress(0x9abc))),
        auxiliary_security_header: None,
    },
    content: FrameContent::Data,
    payload: &[0xde, 0xf0],
    footer:  [0x12, 0x34]
};

// Work also with `let mut bytes = Vec::new()`;
let mut bytes = [0u8; 32];
let mut len = 0usize;

bytes.write_with(&mut len, frame, &mut FrameSerDesContext::no_security(FooterMode::Explicit)).unwrap();

let expected_bytes = [
    0x01, 0x98,             // frame control
    0x00,                   // sequence number
    0x34, 0x12, 0x78, 0x56, // PAN identifier and address of destination
    0x34, 0x12, 0xbc, 0x9a, // PAN identifier and address of source
    0xde, 0xf0,             // payload
    0x12, 0x34              // footer
];
assert_eq!(bytes[..len], expected_bytes);
```

--------------------------------

### SecurityContext Implementation Methods

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/struct.SecurityContext.html

Methods for initializing a new security context or creating one without security capabilities.

```rust
pub fn new(euid: u64, frame_counter: u32, key_provider: KEYDESCLO) -> Self
```

```rust
pub fn no_security() -> Self
```

--------------------------------

### SecurityControl::new

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/struct.SecurityControl.html

Creates a new instance of SecurityControl with the specified security level.

```APIDOC
## pub fn new(security_level: SecurityLevel) -> Self

### Description
Creates a new SecurityControl instance with the provided security level. The key identifier mode is determined at a later stage.

### Parameters
- **security_level** (SecurityLevel) - Required - The security level to be applied to the frame.
```

--------------------------------

### SecurityContext::new

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/struct.SecurityContext.html

Creates a new security context instance with the specified EUID, frame counter, and key provider.

```APIDOC
## SecurityContext::new

### Description
Creates a new security context using the provided key provider and frame counter.

### Signature
`pub fn new(euid: u64, frame_counter: u32, key_provider: KEYDESCLO) -> Self`

### Parameters
- **euid** (u64) - The EUID used for calculating the nonce of outgoing frames.
- **frame_counter** (u32) - The current frame counter.
- **key_provider** (KEYDESCLO) - The key descriptor lookup to use to look up keys.
```

--------------------------------

### PendingAddress::new

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/beacon/struct.PendingAddress.html

Creates a new, empty PendingAddress instance.

```APIDOC
### pub fn new() -> Self

Creates a new empty PendingAddress struct.
```

--------------------------------

### Convert Address to AddressMode

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/enum.AddressMode.html

Demonstrates converting an optional Address into an AddressMode.

```rust
use ieee802154::mac::{Address, AddressMode, PanId, ShortAddress};

let example_addr = Some(Address::Short(PanId(0x3412), ShortAddress(0x7856)));
let address_mode = AddressMode::from(example_addr);
assert_eq!(address_mode, AddressMode::Short);
```

--------------------------------

### Initialize FrameSerDesContext

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/struct.FrameSerDesContext.html

Methods for creating a new context, either with a security context or without security functionality.

```rust
pub fn new( mode: FooterMode, security_ctx: Option<&'a mut SecurityContext<AEADBLKCIPH, KEYDESCLO>>, ) -> Self
```

```rust
pub fn no_security(mode: FooterMode) -> Self
```

--------------------------------

### GuaranteedTimeSlotDescriptor::new

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/beacon/struct.GuaranteedTimeSlotDescriptor.html

Creates a new, empty instance of the GuaranteedTimeSlotDescriptor.

```APIDOC
### pub fn new() -> Self

Creates a new empty GuaranteedTimeSlotDescriptor.
```

--------------------------------

### FrameSerDesContext::new

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/struct.FrameSerDesContext.html

Creates a new frame serialization/deserialization context with the specified footer mode and security context.

```APIDOC
## pub fn new(mode: FooterMode, security_ctx: Option<&'a mut SecurityContext<AEADBLKCIPH, KEYDESCLO>>) -> Self

### Description
Creates a new frame serialization/deserialization context with the specified footer mode and security context.

### Parameters
- **mode** (FooterMode) - The footer mode to use.
- **security_ctx** (Option<&'a mut SecurityContext<AEADBLKCIPH, KEYDESCLO>>) - An optional mutable reference to a security context.
```

--------------------------------

### FrameVersion::from_bits

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/enum.FrameVersion.html

Creates an instance of FrameVersion from the provided bits. Returns None if the provided bits do not encode a valid FrameVersion.

```APIDOC
## FrameVersion::from_bits(bits: u8) -> Option<Self>

### Description
Creates an instance of `FrameVersion` from the provided bits. Returns `None` if the provided bits do not encode a valid value of `FrameVersion`.

### Parameters
- **bits** (u8) - Required - The raw bits representing the frame version.

### Returns
- **Option<Self>** - The corresponding `FrameVersion` variant, or `None` if invalid.

### Example
```rust
use ieee802154::mac::FrameVersion;

let version = FrameVersion::from_bits(0b0);
assert_eq!(version, Some(FrameVersion::Ieee802154_2003));
```
```

--------------------------------

### Write Frame to Byte Slice

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/struct.FrameSerDesContext.html

Implementation of the try_write method for serializing a frame into a byte slice using the context.

```rust
fn try_write( self, bytes: &mut [u8], context: &mut FrameSerDesContext<'_, AEADBLKCIPH, KEYDESCLO>, ) -> Result<usize>
```

--------------------------------

### lookup_key_descriptor

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/trait.KeyDescriptorLookup.html

Look up a key from a key identifier and a device address. This method is used to perform procedure 7.2.2.

```APIDOC
## fn lookup_key_descriptor

### Description
Look up a key from a key identifier and a device address. This function returns None if the key lookup fails, and Some containing the 64-bit UID and the key descriptor if the lookup succeeds.

### Signature
`fn lookup_key_descriptor(&self, address_mode: AddressingMode, key_identifier: Option<KeyIdentifier>, device_address: Option<Address>) -> Option<(u64, GenericArray<u8, N>)>`

### Parameters
- **address_mode** (AddressingMode) - The addressing mode used for the lookup.
- **key_identifier** (Option<KeyIdentifier>) - The identifier for the security key.
- **device_address** (Option<Address>) - The address of the device associated with the key.

### Returns
- **Option<(u64, GenericArray<u8, N>)>** - Returns Some with the 64-bit UID and key descriptor on success, or None if the lookup fails.
```

--------------------------------

### Define Frame struct

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/struct.Frame.html

The structure definition for an IEEE 802.15.4 MAC frame.

```rust
pub struct Frame<'p> {
    pub header: Header,
    pub content: FrameContent,
    pub payload: &'p [u8],
    pub footer: [u8; 2],
}
```

--------------------------------

### SecurityContext::no_security

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/struct.SecurityContext.html

Creates a security context that is not capable of providing any security.

```APIDOC
## SecurityContext::no_security

### Description
A security context that is not actually capable of providing any security.

### Signature
`pub fn no_security() -> Self`
```

--------------------------------

### AddressMode::from_bits

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/enum.AddressMode.html

Creates an instance of AddressMode from the provided bits. Returns an error if the bits do not correspond to a valid address mode.

```APIDOC
## fn from_bits(bits: u8) -> Result<Self, DecodeError>

### Description
Creates an instance of `AddressMode` from the provided bits. Returns `None` (as a DecodeError), if the provided bits don't encode a valid value of `AddressMode`.

### Parameters
- **bits** (u8) - Required - The bit representation of the address mode.

### Returns
- **Result<Self, DecodeError>** - The corresponding AddressMode variant or a decoding error.
```

--------------------------------

### Command Enum Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/command/enum.Command.html

The definition of the Command enum, listing all supported MAC command variants.

```rust
pub enum Command {
    AssociationRequest(CapabilityInformation),
    AssociationResponse(ShortAddress, AssociationStatus),
    DisassociationNotification(DisassociationReason),
    DataRequest,
    PanIdConflictNotification,
    OrphanNotification,
    BeaconRequest,
    CoordinatorRealignment(CoordinatorRealignmentData),
    GuaranteedTimeSlotRequest(GuaranteedTimeSlotCharacteristics),
}
```

--------------------------------

### CapabilityInformation Struct Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/command/struct.CapabilityInformation.html

The structure definition representing device capabilities in the IEEE 802.15.4 MAC layer.

```rust
pub struct CapabilityInformation {
    pub full_function_device: bool,
    pub mains_power: bool,
    pub idle_receive: bool,
    pub frame_protection: bool,
    pub allocate_address: bool,
}
```

--------------------------------

### Decode AddressMode from bits

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/enum.AddressMode.html

Creates an AddressMode instance from raw bits.

```rust
use ieee802154::mac::AddressMode;
// decode
let address_mode = AddressMode::from_bits(0b10).unwrap();
assert_eq!(address_mode, AddressMode::Short);
```

--------------------------------

### ShortAddress Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/struct.ShortAddress.html

The internal structure of the ShortAddress type.

```rust
pub struct ShortAddress(pub u16);
```

--------------------------------

### CoordinatorRealignmentData Struct Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/command/struct.CoordinatorRealignmentData.html

The structure used to represent realignment data sent by a coordinator.

```rust
pub struct CoordinatorRealignmentData {
    pub pan_id: PanId,
    pub coordinator_address: ShortAddress,
    pub channel: u8,
    pub device_address: ShortAddress,
    pub channel_page: Option<u8>,
}
```

--------------------------------

### Beacon Struct Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/beacon/struct.Beacon.html

The structure definition for a Beacon frame, containing fields for superframe specification, GTS information, and pending addresses.

```rust
pub struct Beacon {
    pub superframe_spec: SuperframeSpecification,
    pub guaranteed_time_slot_info: GuaranteedTimeSlotInformation,
    pub pending_address: PendingAddress,
}
```

--------------------------------

### Define PendingAddress struct

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/beacon/struct.PendingAddress.html

The internal structure definition for PendingAddress.

```rust
pub struct PendingAddress { /* private fields */ }
```

--------------------------------

### Header Struct Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/struct.Header.html

The definition of the Header struct containing all fields for a MAC frame header.

```rust
pub struct Header {
    pub frame_type: FrameType,
    pub frame_pending: bool,
    pub ack_request: bool,
    pub pan_id_compress: bool,
    pub seq_no_suppress: bool,
    pub ie_present: bool,
    pub version: FrameVersion,
    pub seq: u8,
    pub destination: Option<Address>,
    pub source: Option<Address>,
    pub auxiliary_security_header: Option<AuxiliarySecurityHeader>,
}
```

--------------------------------

### lookup_device

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/trait.DeviceDescriptorLookup.html

Performs a lookup of a device descriptor based on the provided addressing mode and address.

```APIDOC
## fn lookup_device(&mut self, addressing_mode: AddressingMode, address: Address) -> Option<&mut DeviceDescriptor>

### Description
Performs a lookup of a device descriptor based on the provided address and addressing mode.

### Parameters
- **addressing_mode** (AddressingMode) - Required - The addressing mode to use for the lookup.
- **address** (Address) - Required - The address to look up.

### Returns
- **Option<&mut DeviceDescriptor>** - Returns a mutable reference to the DeviceDescriptor if found, otherwise None.
```

--------------------------------

### BlockCipher Implementation for References

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/trait.BlockCipher.html

Allows the BlockCipher trait to be implemented for references to types that already implement the trait.

```rust
impl<Alg> BlockCipher for &Alg
where Alg: BlockCipher,
```

--------------------------------

### has_security

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/struct.Header.html

Checks if the header has security enabled.

```APIDOC
## pub fn has_security(&self) -> bool

### Description
Determines whether the security field is enabled for this header.

### Returns
- **bool** - True if security is enabled, false otherwise.
```

--------------------------------

### PanId::broadcast

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/struct.PanId.html

Returns a new PanId instance representing the broadcast PAN identifier.

```APIDOC
## pub fn broadcast() -> Self

### Description
Returns the broadcast PAN identifier.

### Signature
`pub fn broadcast() -> Self`

### Example
```rust
use ieee802154::mac::PanId;

let broadcast_id = PanId::broadcast();
```
```

--------------------------------

### PendingAddress::short_addresses

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/beacon/struct.PendingAddress.html

Retrieves the list of short addresses associated with the PendingAddress instance.

```APIDOC
### pub fn short_addresses(&self) -> &[ShortAddress]

Get the short addresses.
```

--------------------------------

### FrameSerDesContext::no_security

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/struct.FrameSerDesContext.html

Creates a new frame serialization/deserialization context that does not facilitate any security functionality.

```APIDOC
## pub fn no_security(mode: FooterMode) -> Self

### Description
Creates a new frame serialization/deserialization context with the specified footer mode, that does not facilitate any security functionality.

### Parameters
- **mode** (FooterMode) - The footer mode to use.
```

--------------------------------

### SuperframeSpecification Struct Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/beacon/struct.SuperframeSpecification.html

The structure definition for SuperframeSpecification, detailing the fields used to configure beacon and superframe timing and coordinator status.

```rust
pub struct SuperframeSpecification {
    pub beacon_order: BeaconOrder,
    pub superframe_order: SuperframeOrder,
    pub final_cap_slot: u8,
    pub battery_life_extension: bool,
    pub pan_coordinator: bool,
    pub association_permit: bool,
}
```

--------------------------------

### U16 Struct Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/type.U16.html

The internal structure definition for U16.

```rust
pub struct U16 { /* private fields */ }
```

--------------------------------

### GuaranteedTimeSlotInformation Struct Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/beacon/struct.GuaranteedTimeSlotInformation.html

The structure definition for GuaranteedTimeSlotInformation, containing the permit field.

```rust
pub struct GuaranteedTimeSlotInformation {
    pub permit: bool,
    /* private fields */
}
```

--------------------------------

### Define Unimplemented struct

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/default/struct.Unimplemented.html

The basic definition of the Unimplemented struct.

```rust
pub struct Unimplemented;
```

--------------------------------

### KeySource Enum Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/enum.KeySource.html

The definition of the KeySource enum, which provides variants for different key source lengths.

```rust
pub enum KeySource {
    Short(u32),
    Long(u64),
}
```

--------------------------------

### FrameType::from_bits

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/enum.FrameType.html

Creates an instance of FrameType from the provided bits. Returns None if the provided bits do not encode a valid frame type.

```APIDOC
## pub fn from_bits(bits: u8) -> Option<Self>

### Description
Creates an instance of `FrameType` from the provided bits. Returns `None` if the provided bits do not encode a valid frame type.

### Parameters
- **bits** (u8) - Required - The raw bits representing the frame type.

### Returns
- **Option<Self>** - The corresponding `FrameType` variant, or `None` if invalid.
```

--------------------------------

### AuxiliarySecurityHeader Struct Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/struct.AuxiliarySecurityHeader.html

The structure definition for the Auxiliary Security Header.

```rust
pub struct AuxiliarySecurityHeader {
    pub control: SecurityControl,
    pub key_identifier: Option<KeyIdentifier>,
    /* private fields */
}
```

--------------------------------

### DeviceDescriptorLookup Trait Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/trait.DeviceDescriptorLookup.html

Defines the required interface for looking up device descriptors within the security framework.

```rust
pub trait DeviceDescriptorLookup {
    // Required method
    fn lookup_device(
        &mut self,
        addressing_mode: AddressingMode,
        address: Address,
    ) -> Option<&mut DeviceDescriptor>;
}
```

--------------------------------

### DeviceDescriptor Struct Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/struct.DeviceDescriptor.html

The structure definition for DeviceDescriptor, including its public fields for frame counter and exemption status.

```rust
pub struct DeviceDescriptor {
    pub frame_counter: u32,
    pub exempt: bool,
}
```

--------------------------------

### U16 Type Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/type.U16.html

The definition of the U16 type alias.

```rust
pub type U16 = UInt<UInt<UInt<UInt<UInt<UTerm, B1>, B0>, B0>, B0>, B0>;
```

--------------------------------

### KeyIdentifier Struct Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/struct.KeyIdentifier.html

The structure definition for KeyIdentifier, which includes an optional key source and a mandatory key index.

```rust
pub struct KeyIdentifier {
    pub key_source: Option<KeySource>,
    pub key_index: u8,
}
```

--------------------------------

### Address Enum Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/enum.Address.html

The structure of the Address enum, defining Short and Extended variants.

```rust
pub enum Address {
    Short(PanId, ShortAddress),
    Extended(PanId, ExtendedAddress),
}
```

--------------------------------

### GuaranteedTimeSlotCharacteristics Struct Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/command/struct.GuaranteedTimeSlotCharacteristics.html

The structure definition for configuring guaranteed time slots in MAC commands.

```rust
pub struct GuaranteedTimeSlotCharacteristics {
    pub count: u8,
    pub receive_only: bool,
    pub allocation: bool,
}
```

--------------------------------

### Define AddressMode

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/enum.AddressMode.html

The definition of the AddressMode enum with its variants.

```rust
pub enum AddressMode {
    None = 0,
    Short = 2,
    Extended = 3,
}
```

--------------------------------

### BeaconOrder Enum Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/beacon/enum.BeaconOrder.html

The primary enum structure defining the beacon order configuration.

```rust
pub enum BeaconOrder {
    BeaconOrder(u8),
    OnDemand,
}
```

--------------------------------

### SecurityContext Struct Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/struct.SecurityContext.html

The structure definition for SecurityContext, requiring an AEAD block cipher and a key descriptor lookup.

```rust
pub struct SecurityContext<AEADBLKCIPH, KEYDESCLO>
where
    AEADBLKCIPH: NewBlockCipher + BlockCipher<BlockSize = U16>,
    KEYDESCLO: KeyDescriptorLookup<AEADBLKCIPH::KeySize>,
{
    pub euid: u64,
    pub frame_counter: u32,
    pub key_provider: KEYDESCLO,
    /* private fields */
}
```

--------------------------------

### Define ExtendedAddress

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/struct.ExtendedAddress.html

The struct definition for ExtendedAddress.

```rust
pub struct ExtendedAddress(pub u64);
```

--------------------------------

### NewBlockCipher Trait Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/trait.NewBlockCipher.html

The trait definition including required associated types and methods for block cipher initialization.

```rust
pub trait NewBlockCipher: Sized {
    type KeySize: ArrayLength<u8>;

    // Required method
    fn new(key: &GenericArray<u8, Self::KeySize>) -> Self;

    // Provided method
    fn new_from_slice(key: &[u8]) -> Result<Self, InvalidLength> { ... }
}
```

--------------------------------

### get_octet_size

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/struct.Header.html

Returns the size of the header in octets.

```APIDOC
## pub fn get_octet_size(&self) -> usize

### Description
Returns the total size of the header in octets.

### Returns
- **usize** - The size of the header in octets.
```

--------------------------------

### BlockCipher Trait Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/trait.BlockCipher.html

Defines the core structure for block cipher implementations, specifying block size and parallel block count.

```rust
pub trait BlockCipher {
    type BlockSize: ArrayLength<u8>;
    type ParBlocks: ArrayLength<GenericArray<u8, Self::BlockSize>>;
}
```

--------------------------------

### CommandId Enum Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/command/enum.CommandId.html

The definition of the CommandId enum containing all supported MAC command variants.

```rust
pub enum CommandId {
    AssociationRequest,
    AssociationResponse,
    DisassociationNotification,
    DataRequest,
    PanIdConflictNotification,
    OrphanNotification,
    BeaconRequest,
    CoordinatorRealignment,
    GuaranteedTimeSlotRequest,
}
```

--------------------------------

### Define FrameSerDesContext Struct

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/struct.FrameSerDesContext.html

The structure definition for FrameSerDesContext, requiring block cipher and key descriptor lookup implementations.

```rust
pub struct FrameSerDesContext<'a, AEADBLKCIPH, KEYDESCLO>
where
    AEADBLKCIPH: NewBlockCipher + BlockCipher<BlockSize = U16>,
    KEYDESCLO: KeyDescriptorLookup<AEADBLKCIPH::KeySize>,
{ /* private fields */ }
```

--------------------------------

### BlockEncrypt Trait Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/trait.BlockEncrypt.html

The core trait definition for block cipher encryption, requiring implementation of encrypt_block and providing default implementations for parallel and slice-based encryption.

```rust
pub trait BlockEncrypt: BlockCipher {
    // Required method
    fn encrypt_block(&self, block: &mut GenericArray<u8, Self::BlockSize>);

    // Provided methods
    fn encrypt_par_blocks(
        &self,
        blocks: &mut GenericArray<GenericArray<u8, Self::BlockSize>, Self::ParBlocks>,
    ) { ... }
    fn encrypt_blocks(&self, blocks: &mut [GenericArray<u8, Self::BlockSize>]) { ... }
}
```

--------------------------------

### Define FrameVersion Enum

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/enum.FrameVersion.html

The structure of the FrameVersion enum with its variants corresponding to specific IEEE 802.15.4 standards.

```rust
pub enum FrameVersion {
    Ieee802154_2003 = 0,
    Ieee802154_2006 = 1,
    Ieee802154 = 2,
}
```

--------------------------------

### KeyIdentifierMode Enum Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/enum.KeyIdentifierMode.html

The enumeration defines the available key identifier modes with their corresponding integer values.

```rust
pub enum KeyIdentifierMode {
    None = 0,
    KeyIndex = 1,
    KeySource4 = 2,
    KeySource8 = 3,
}
```

--------------------------------

### Define FrameType Enum

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/enum.FrameType.html

The enumeration of valid MAC frame types with their corresponding bit values.

```rust
pub enum FrameType {
    Beacon = 0,
    Data = 1,
    Acknowledgement = 2,
    MacCommand = 3,
    Multipurpose = 5,
    FragOrFragAck = 6,
    Extended = 7,
}
```

--------------------------------

### PendingAddress::extended_addresses

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/beacon/struct.PendingAddress.html

Retrieves the list of extended addresses associated with the PendingAddress instance.

```APIDOC
### pub fn extended_addresses(&self) -> &[ExtendedAddress]

Get the extended address.
```

--------------------------------

### FrameContent Enum Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/enum.FrameContent.html

The definition of the FrameContent enum, which categorizes the different types of IEEE 802.15.4 MAC frames.

```rust
pub enum FrameContent {
    Beacon(Beacon),
    Data,
    Acknowledgement,
    Command(Command),
    Multipurpose,
    FragOrFragAck,
    Extended,
}
```

--------------------------------

### Define SecurityLevel Enum

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/enum.SecurityLevel.html

The SecurityLevel enum defines the available security configurations for frame payloads.

```rust
pub enum SecurityLevel {
    None = 0,
    MIC32 = 1,
    MIC64 = 2,
    MIC128 = 3,
    ENC = 4,
    ENCMIC32 = 5,
    ENCMIC64 = 6,
    ENCMIC128 = 7,
}
```

--------------------------------

### AddressingMode Enum Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/enum.AddressingMode.html

The definition of the AddressingMode enum showing its available variants.

```rust
pub enum AddressingMode {
    DstAddrMode,
    SrcAddrMode,
}
```

--------------------------------

### extended_enum Macro Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/macro.extended_enum.html

The macro definition for creating enums with trait support and default fallback behavior.

```rust
macro_rules! extended_enum {
    ($(#[$outer:meta])* $name:ident, $ty:ty, $($(#[$inner:meta])* $var:ident => $val:expr),+ $(,)*) => { ... };
}
```

--------------------------------

### KeyDescriptorLookup Trait Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/trait.KeyDescriptorLookup.html

The trait definition requiring an implementation of the lookup_key_descriptor method for a given array length N.

```rust
pub trait KeyDescriptorLookup<N>
where
    N: ArrayLength<u8>,
{
    // Required method
    fn lookup_key_descriptor(
        &self,
        address_mode: AddressingMode,
        key_identifier: Option<KeyIdentifier>,
        device_address: Option<Address>,
    ) -> Option<(u64, GenericArray<u8, N>)>;
}
```

--------------------------------

### DecodeError Enum Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/enum.DecodeError.html

The structure of the DecodeError enum, which lists all possible error variants during frame decoding.

```rust
pub enum DecodeError {
    NotEnoughBytes,
    InvalidFrameType(u8),
    SecurityEnabled,
    InvalidAddressMode(u8),
    InvalidFrameVersion(u8),
    InvalidSecurityLevel(u8),
    InvalidKeyIdentifierMode(u8),
    MissingSecurityCtx,
    AuxSecHeaderAbsent,
    InvalidValue,
}
```

--------------------------------

### get_mic_octet_size

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/enum.SecurityLevel.html

Retrieves the size of the message integrity code (MIC) in octets for the current security level.

```APIDOC
## pub fn get_mic_octet_size(&self) -> usize

### Description
Returns the size of the MIC that will be generated if this specific security level is used.

### Returns
- **usize** - The size of the MIC in octets.
```

--------------------------------

### SecurityError Enum Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/security/enum.SecurityError.html

The definition of the SecurityError enum, listing all possible error variants encountered during security processing.

```rust
pub enum SecurityError {
    SecurityNotEnabled,
    InvalidSecContext,
    FrameTooLong,
    CounterError,
    UnavailableKey,
    KeyFailure,
    NoSourceAddress,
    NoDestinationAddress,
    TransformationError,
    WriteError(Error),
    TagWriteError,
    NotImplemented,
    AuxSecHeaderAbsent,
    KeyIdentifierMismatch,
    UnsupportedLegacy,
    UnsupportedSecurity,
    UnavailableDevice,
    KeyLookupAddressTypeMismatch,
}
```

--------------------------------

### AssociationStatus Enum Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/command/enum.AssociationStatus.html

The definition of the AssociationStatus enum, which lists the possible status variants for association operations.

```rust
pub enum AssociationStatus {
    Successful,
    NetworkAtCapacity,
    AccessDenied,
    HoppingSequenceOffsetDuplication,
    FastAssociationSuccesful,
}
```

--------------------------------

### Define FooterMode Enum

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/enum.FooterMode.html

The FooterMode enum specifies whether the frame footer is ignored or explicitly read/written.

```rust
pub enum FooterMode {
    None,
    Explicit,
}
```

--------------------------------

### Define PanId struct

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/header/struct.PanId.html

The definition of the PanId struct as a tuple struct containing a u16.

```rust
pub struct PanId(pub u16);
```

--------------------------------

### DisassociationReason Enum Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/command/enum.DisassociationReason.html

The enum structure representing the possible reasons for disassociation.

```rust
pub enum DisassociationReason {
    CoordinatorLeave,
    DeviceLeave,
}
```

--------------------------------

### SuperframeOrder Enum Definition

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/beacon/enum.SuperframeOrder.html

The primary definition of the SuperframeOrder enum, which can either hold a u8 value for active duration or represent an inactive state.

```rust
pub enum SuperframeOrder {
    SuperframeOrder(u8),
    Inactive,
}
```

--------------------------------

### Define EncodeError Enum

Source: https://docs.rs/ieee802154/0.6.1/ieee802154/mac/frame/enum.EncodeError.html

The structure of the EncodeError enum used for handling frame encoding failures.

```rust
pub enum EncodeError {
    WriteError,
    MissingSecurityCtx,
    DisallowedPanIdCompress,
    UnknownError,
}
```
Tokens:
Raw