Porting IEEE 802.15.4 MAC driver

Nanostack has a lower-level API for the IEEE 802.15.4-2006 MAC standard. This enables developers to support different MACs for software- and hardware-based solutions. Nanostack offers SW MAC, which you can use when your board does not have 15.4 MAC available. SW MAC also supports a subset of IEEE 802.15.4-2015 MAC standard. Supported features are:

• IEEE 802.15.4-2015 enhanced ack.
• Header and payload information elements set by MAC user.

SW MAC

Nanostack includes an IEEE 802.15.4-based SW MAC class. You can use SW MAC when your board does not support MAC. To use the SW MAC service, you must have a working RF driver registered to Nanostack. To create SW MAC, call the following function:

ns_sw_mac_create()

This creates an SW MAC class and sets a callback function to be used by Nanostack.

Note: You must not call ns_sw_mac_create() more than once.

SW MAC IEEE 802.15.4-2015 subset extension

SW MAC supports a subset of the IEEE 802.15.4-2015 standard. The subset includes the following supported features:

• Data frame send with payload and header information elements defined by MAC user.
• Enhanced ACK generation and send by MAC.
• Enhanced ACK payload and Information elements write for MAC user.

The subset features need a proper supported RF driver with extended driver API commands.

Initializing SW MAC

Deploy SW MAC:

1. Call arm_net_phy_register() to register the configured RF driver class to Nanostack.

2. Call ns_sw_mac_create() to create SW MAC with needed list sizes:

   • A sleepy device needs only 1-4 as the size of the device_decription_table_size.
   • The recommended value for key_lookup_size is 1 and for key_usage_size 3.

3. Call arm_nwk_interface_lowpan_init() to create Nanostack with the created SW MAC class. Nanostack initializes SW MAC before using it.

Example

This code snippet creates SW MAC with a neighbor table of size 16 and three key descriptions:

int8_t generate_6lowpan_interface(int8_t rf_phy_device_register_id)
{
    mac_description_storage_size_t storage_sizes;
    storage_sizes.device_decription_table_size = 16;
    storage_sizes.key_description_table_size = 3;
    storage_sizes.key_lookup_size = 1;
    storage_sizes.key_usage_size = 3;
    mac_api_t *mac_api = ns_sw_mac_create(rf_phy_device_register_id, &storage_sizes);
    if (!mac_api) {
        tr_error("Mac create fail!");
        return -1;
    }
    return arm_nwk_interface_lowpan_init(mac_api, "6LoWPAN_ROUTER");
}

Enabling FHSS

SW MAC supports FHSS. To enable it, you need to do the following:

1. Call arm_net_phy_register() to register the configured RF driver class to Nanostack.
2. Call ns_sw_mac_create() to create SW MAC with needed list sizes.
3. Call ns_fhss_create() to configure and define the FHSS class.
4. Call ns_sw_mac_fhss_register() to register FHSS to SW MAC.
5. Call arm_nwk_interface_lowpan_init() to create Nanostack with the created SW MAC class.

IEEE 802.15.4 MAC sublayer APIs

The stack uses the IEEE 802.15.4 defined MAC management service entity (MLME-SAP) and MAC data service (MCPS-SAP) interfaces. MAC API follows MCPS and MLME primitives defined by the IEEE 802.15.4-2006 standard.

The following primitives are used in MAC layer:

The following header files define the MAC API:

• mac_api.h - Main header, which defines a transparent MAC API for Nanostack to use.
• mlme.h - Definitions for MLME-SAP primitives.
• mac_mcps.h - Definitions for MCPS-SAP primitives.
• mac_common_defines.h - Definitions for common MAC constants.

MCPS-SAP interface

MCPS-SAP defines 802.15.4 data flow API with the following primitives:

MLME-SAP interface

MLME-SAP defines a set of different management primitives, and this document introduces both supported and unsupported primitives in Nanostack.

Supported MLME APIs

MLME-SAP primitives used by Nanostack:

Unsupported MLME APIs

Unsupported MLME-SAP primitives:

MAC API class introduction

This chapter introduces MAC mesh interface mac_api_s. It is a structure that defines the function callbacks needed by a service user.

The base class defines the functions for two-way communications between an external MAC and service user. The application creates a mac_api_s object by calling the MAC adapter's create function. The newly created object is then passed to Nanostack, which initializes its own callback functions by calling the mac_api_initialize() function. A service user operates MAC by calling MLME or MCPS primitive functions.

The MAC API class structure mac_api_t is defined as:

typedef struct mac_api_s {
    //Service user defined initialization function which is called when Nanostack takes MAC into use
    mac_api_initialize              *mac_initialize;
    mac_api_enable_mcps_ext     *mac_mcps_extension_enable;
    //MAC adapter function callbacks for MLME & MCPS SAP
    mlme_request                    *mlme_req;
    mcps_data_request               *mcps_data_req;
    mcps_data_request_ext       *mcps_data_req_ext;
    mcps_purge_request                  *mcps_purge_req;
    //Service user defined function callbacks
    mcps_data_confirm               *data_conf_cb;
    mcps_data_confirm_ext       *data_conf_ext_cb;
    mcps_data_indication                *data_ind_cb;
    mcps_data_indication_ext    *data_ind_ext_cb;
    mcps_ack_data_req_ext       *enhanced_ack_data_req_cb;
    mcps_purge_confirm                  *purge_conf_cb;
    mlme_confirm                        *mlme_conf_cb;
    mlme_indication                     *mlme_ind_cb;
    //MAC extension API for service user
    mac_ext_mac64_address_set           *mac64_set;
    mac_ext_mac64_address_get           *mac64_get;
    mac_storage_decription_sizes_get *mac_storage_sizes_get;
    int8_t                              parent_id;
    uint16_t                            phyMTU;
};

IEEE 802.15.4 MAC sublayer extended APIs

This document introduces how to use extented features.

Initialize API

typedef int8_t mac_api_enable_mcps_ext(mac_api_t *api, mcps_data_indication_ext *data_ind_cb, mcps_data_confirm_ext *data_cnf_cb, mcps_ack_data_req_ext *ack_data_req_cb);

Function can be called when SW MAC is created and initialization procedure is done. Enable could fail if delivered driver does not support required extensions.

Data Indication API

typedef void mcps_data_indication_ext(const mac_api_t* api, const mcps_data_ind_t *data, const mcps_data_ie_list_t *ie_ext);

Extended data indication handler includes an information element list, which is defined as:

typedef struct mcps_data_ie_list {
    uint8_t *headerIeList;
    uint8_t *payloadIeList;
    uint16_t headerIeListLength;
    uint16_t payloadIeListLength;
} mcps_data_ie_list_t;

Data request API

typedef void mcps_data_request_ext(const mac_api_t* api, const mcps_data_req_t *data, const mcps_data_req_ie_list_t *ie_ext, const struct channel_list_s *asynch_channel_list);

Asynch data request is MAC standard extension. asynch_channel_list includes a channel mask, which the channel message is requested to send.

Structure for IEEE 802.15.4-2015 MCPS data extension to Request.

typedef struct mcps_data_req_ie_list {
    ns_ie_iovec_t *headerIeVectorList;
    ns_ie_iovec_t *payloadIeVectorList;
    uint16_t headerIovLength;
    uint16_t payloadIovLength;
} mcps_data_req_ie_list_t;

IE element could be divided to multiple vector, which MAC just write to message direct. One vector could also include multiple information elements or just header part. That's enable flexible to way to generate list and should enable memory friendly way to share information elements.

Set headerIovLength or payloadIovLength to 0 if not send any element.

Scatter-gather descriptor for MCPS request IE element list:

typedef struct ns_ie_iovec {
    void *ieBase;
    uint_fast16_t iovLen;
} ns_ie_iovec_t;

Data confirmation API

typedef void mcps_data_confirm_ext(const mac_api_t* api, const mcps_data_conf_t *data, const mcps_data_conf_payload_t *conf_data);

Confirmation data is packet to next structure:

typedef struct mcps_data_conf_payload_s {
    uint8_t *headerIeList;
    uint8_t *payloadIeList;
    uint8_t *payloadPtr;
    uint16_t headerIeListLength;
    uint16_t payloadIeListLength;
    uint16_t payloadLength;
} mcps_data_conf_payload_t;

Enhanced ACK payload and IE write API

typedef void mcps_ack_data_req_ext(const mac_api_t* api, mcps_ack_data_payload_t *data, int8_t rssi, uint8_t lqi);

Signal strength and link quality are additional information that devices can share in an Ack message.

Structure for give Ack payload:

typedef struct mcps_ack_data_payload {
    struct mcps_data_req_ie_list ie_elements;
    uint8_t *payloadPtr;
    uint16_t payloadLength;
} mcps_ack_data_payload_t;

If payload length is zero, payloadPtr is NULL. Information element headers may also contain empty vectors.

MAC API standard extensions

This section introduces MAC API standard extensions.

MAC 64-bit address set and get

Nanostack uses 64-bit address set and get. There are two 64-bit addresses available:

• NVM EUI64.
• Dynamic 64-bit address used at the link layer.

Address set and get support two different 64-bit addresses:

MAC maximum storage information get

Usually, HW MAC and SW MAC have static keys and neighbor list sizes. Nanostack always asks the maximum size to limit its neighbor table size. The service user must define the mac_storage_sizes_get() function returning the following values:

• MAC device description list size (must be > 1).
• MAC key description list size (must be > 1).

MLME attribute extension

Nanostack uses MLME attribute extensions, which you must port to the HW MAC adapter. To configure the extensions, use the MLME-SET-REQ command.

HW MAC

To use HW MAC, you need to create an adapter class that links function calls between Nanostack and HW MAC. To create the adapter class, implement the functions defined in the mac_api_s structure. When HW MAC generates an event, the adapter must handle it and do a parameter adaptation before calling the correct function from the mac_api_s structure. You may need the same parameter adaptation for requests from Nanostack to HW MAC.

Note: Function calls from Nanostack to HW MAC must be nonblocking in the adapter layer.