IEEE 802.15.4 MAC library

This information applies to the nRF52840 SoC only.

The IEEE 802.15.4 MAC library is a quick starting point for developing wireless applications that conform with the IEEE 802.15.4-2006 standard specification. This library implements every feature described in the IEEE standard.

Follow this link for the full specification of the IEEE 802.15.4 standard.

Note

Before you initialize the 802.15.4 MAC library, make sure that HFCLK (high-frequency crystal oscillator) and LFCLK (low-frequency crystal oscillator) are started. Both oscillators must be running, when the library is used.

While working with the 802.15.4 MAC library, you cannot use the following peripherals in your application as they are exclusively used by the library:

• RADIO
• TIMER0
• RTC0
• UART0

Some peripherals are used by this library in a specific manner. They are managed by external drivers that are not compiled into the library. Your application can override the driver's behavior, but must ensure that its API functions that are called by the library, are defined. The following peripherals belong to this group:

• RNG
• ECB

The 802.15.4 MAC library assertion handlers use default implementation, which can be overridden by custom assertion handlers, defined at the application level.

Physical layer

The Physical (PHY) layer provides the stack with software implementation of the PHY layer primitives of the IEEE 802.15.4 standard.

For API documentation, refer to PHY layer.

MAC layer

The Link (MAC) layer provides the stack with software implementation of the MAC sublayer primitives of the IEEE 802.15.4 standard.

For API documentation, refer to MAC layer.

Initialization and starting

The MAC layer does not require any specific initialization. Each module, however, may have a specific initialization routine, which is usually called by the sys_init() function.

Security abstraction library

The security abstraction library provides the stack with support for different security methods by abstracting the implementation layer.

Main features:

• Supports software implementation.
• Covers the security engine implemented by the hardware.

Note

As the implementation of the IEEE 802.15.4 security features is configured at compile time, there are two versions of the IEEE 802.15.4 MAC library in the nRF5 SDK:

• Raw, where no security is included.
  The raw library version is located in <InstallFolder>\components\802_15_4\raw.
• Secure, which includes the security abstraction implementation according to the IEEE 802.15.4-2006 standard.
  The secure library version is located in <InstallFolder>\components\802_15_4\secure.

If you want to use the security features supported by the IEEE 802.15.4 stack, include the library from the secure folder in your project and make sure the following preprocessor definition is present in your stack configuration header file (<InstallFolder>\components\802_15_4\secure\802_15_4_config.h):

#define CONFIG_SECURE 1

For API documentation, refer to Security abstraction library.

Implementation details

There are two APIs for the security engine. The first one supports plain AES engine via the sec_aes_entity.h file. It only uses the aes_handle() encryption routine that is called for encryption of a block of text. The other option is a more sophisticated CCM engine available via the sec_aes_ccm.h header. Note that both engines require initialization first that is supported by a call to dedicated routines defined in the appropriate headers.

The calls to this library are synchronous only.

Initialization and starting

The AES engine is initialized by a call to aes_entity_init(). The CCM engine is initialized by a call to sec_init(). Note that both routines are called by the sys_init() global routine.

The following is an example of initialization of the Security CCM engine:

static void sec_start(void)
{
 sec_init();
}

Similar code for the AES engine is below:

static void aes_start(void)
{
 aes_entity_init();
}

Encrypting and decrypting

The code snippet below presents initialization with CCM encrypting/decrypting:

#define BLOCK_SIZE 16
#define NONCE_SIZE 13

uint8_t key[BLOCK_SIZE] = {0xC0, 0xC1, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, 0xCA, 0xCB, 0xCC, 0xCD, 0xCE, 0xCF};
uint8_t nonce[NONCE_SIZE] = {0xAC, 0xDE, 0x48, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x05, 0x06};
uint8_t m[] = {0xCE};
uint8_t a[] = {0x2B, 0xDC, 0x84, 0x21, 0x43, 0x02, 0x00, 0x00, 0x00, 0x00, 0x48, 0xDE, 0xAC, 0xFF, 0xFF, 0x01,
 0x00, 0x00, 0x00, 0x00, 0x48, 0xDE, 0xAC, 0x06, 0x05, 0x00, 0x00, 0x00, 0x01};
uint8_t mic[8];

sec_aes_ccm_req_t request;
sec_aes_ccm_status_t value;

int main(void)
{
 sys_init(); /* calls sec_init */

 request.auth_data = a;
 request.auth_data_len = sizeof(a);
 request.text_data = m;
 request.text_data_len = sizeof(m);
 request.nonce = nonce;
 request.key = key;
 request.level = 0x06;
 request.mic = mic;

 value = sec_aes_ccm_enc(&request);

 /* (...) check value here */

 request.auth_data = a;
 request.auth_data_len = sizeof(a);
 request.text_data = m;
 request.text_data_len = sizeof(m) + sizeof(mic);
 request.nonce = nonce;
 request.key = key;
 request.level = 0x06;
 request.mic = mic;

 value = sec_aes_ccm_dec(&request);

 /* (...) check value here */

 return 0;
}

The code snippet below presents initialization with added AES encrypting:

#define BLOCK_SIZE 16

uint8_t key_appb[BLOCK_SIZE] = {0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6, 0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c};
uint8_t data_appb[BLOCK_SIZE] = {0x32, 0x43, 0xf6, 0xa8, 0x88, 0x5a, 0x30, 0x8d, 0x31, 0x31, 0x98, 0xa2, 0xe0, 0x37, 0x07, 0x34};
uint8_t output_appb[BLOCK_SIZE] = {0x39, 0x25, 0x84, 0x1d, 0x02, 0xdc, 0x09, 0xfb, 0xdc, 0x11, 0x85, 0x97, 0x19, 0x6a, 0x0b, 0x32};

int main(void)
{
 sys_init(); /* calls aes_entity_init */

 aes_handle(key_appb, data_appb);

 if (0 == memcmp(data_appb, output_appb, BLOCK_SIZE))
 {
 /* (...) Succeeded */
 }

 return 0;
}

System abstraction library

The System abstraction library provides the stack with common system interface like finite state machine API, memory management, queue, and events.

For API documentation, refer to System abstraction library.

Initialization and starting

The system abstraction library is initialized by a call to sys_init(). The following is an example of the library initialization:

static void app_start(void)
{
 sys_init();
}

802.15.4 MAC library usage example

For a usage example of the 802.15.4 MAC library, see Wireless UART Example.