Module capsules::ieee802154::framer

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 == ReturnCode::SUCCESS {
            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, kernel::Grant::create(), &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);

Reexports

use core::cell::Cell;

use ieee802154::device::MacDevice;

use ieee802154::device::RxClient;

use ieee802154::device::TxClient;

use ieee802154::mac::Mac;

use kernel::ReturnCode;

use kernel::common::take_cell::MapCell;

use kernel::hil::radio;

use kernel::hil::symmetric_encryption::AES128CCM;

use kernel::hil::symmetric_encryption::CCMClient;

use net::ieee802154::*;

use net::stream::encode_bytes;

use net::stream::encode_u32;

use net::stream::encode_u8;

use net::stream::SResult;

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.
FrameInfo	This contains just enough information about a frame to determine
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.

Enums

RxState
TxState	This state enum describes the state of the transmission pipeline. Conditionally-present state is also included as fields in the enum variants. We can view the transmission process as a state machine driven by the following events:

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

get_ccm_nonce