Module capsules_extra::ieee802154::framer

Expand description

Implements IEEE 802.15.4 MAC device abstraction over a 802.15.4 MAC interface. Allows its users to prepare and send frames in plaintext, handling 802.15.4 encoding and security procedures (in the future) transparently.

However, certain IEEE 802.15.4 MAC device concepts are not implemented in this layer of abstraction and instead handled in hardware for performance purposes. These include CSMA-CA backoff, FCS generation and authentication, and automatic acknowledgement. Radio power management and channel selection is also passed down to the MAC control layer.

§Usage

To use this capsule, we need an implementation of a hardware capsules::ieee802154::mac::Mac. Suppose we have such an implementation of type XMacDevice.

let xmac: &XMacDevice = /* ... */;
let mac_device = static_init!(
    capsules::ieee802154::mac::Framer<'static, XMacDevice>,
    capsules::ieee802154::mac::Framer::new(xmac));
xmac.set_transmit_client(mac_device);
xmac.set_receive_client(mac_device, &mut MAC_RX_BUF);
xmac.set_config_client(mac_device);

The mac_device device is now set up. Users of the MAC device can now configure the underlying radio, prepare and send frames:

mac_device.set_pan(0xABCD);
mac_device.set_address(0x1008);
mac_device.config_commit();

let frame = mac_device
    .prepare_data_frame(&mut STATIC_BUFFER,
                        0xABCD, MacAddress::Short(0x1008),
                        0xABCD, MacAddress::Short(0x1009),
                        None)
    .ok()
    .map(|frame| {
        let rval = frame.append_payload(&mut SOME_DATA[..10]);
        if rval == Ok(()) {
            let (rval, _) = mac_device.transmit(frame);
            rval
        } else {
            rval
        }
    });

You should also be able to set up the userspace driver for receiving/sending 802.15.4 frames:


let radio_capsule = static_init!(
    capsules::ieee802154::RadioDriver<'static>,
    capsules::ieee802154::RadioDriver::new(mac_device, board_kernel.create_grant(&grant_cap), &mut RADIO_BUF));
mac_device.set_key_procedure(radio_capsule);
mac_device.set_device_procedure(radio_capsule);
mac_device.set_transmit_client(radio_capsule);
mac_device.set_receive_client(radio_capsule);

Structs§

Frame
A Frame wraps a static mutable byte slice and keeps just enough information about its header contents to expose a restricted interface for modifying its payload. This enables the user to abdicate any concerns about where the payload should be placed in the buffer.
Framer
This struct wraps an IEEE 802.15.4 radio device kernel::hil::radio::Radio and exposes IEEE 802.15.4 MAC device functionality as the trait capsules::mac::Mac. It hides header preparation, transmission and processing logic from the user by essentially maintaining multiple state machines corresponding to the transmission, reception and encryption/decryption pipelines. See the documentation in capsules/src/mac.rs for more details.

Constants§

CRYPT_BUF_SIZE
The needed buffer size might be bigger than an MTU, because the CCM* authentication procedure

Traits§

DeviceProcedure
IEEE 802.15.4-2015, 9.2.5, DeviceDescriptor lookup procedure. Trait to be implemented by an upper layer that manages the list of 802.15.4 device descriptors. This trait interface enables the lookup procedure to be implemented either explicitly (managing a list of DeviceDescriptors) or implicitly with some equivalent logic.
KeyProcedure
IEEE 802.15.4-2015, 9.2.2, KeyDescriptor lookup procedure. Trait to be implemented by an upper layer that manages the list of 802.15.4 key descriptors. This trait interface enables the lookup procedure to be implemented either explicitly (managing a list of KeyDescriptors) or implicitly with some equivalent logic.

Functions§