Detailed Description

EZR32 EzRadio Peripheral Interface Driver.

The source files for the EzRadio driver library resides in the emdrv/ezradiodrv folder. The file hierarchy is shown in the File List.

Introduction

The EzRadio driver supports the on-chip EzRadio radio of EZR32 devices. The driver system provides several access layer levels to the radio. In the order of hierarchy they are the Plugin System Layer, the Radio API Layer, the Communication Layer and the Radio HAL Layer. Although, all these layers are supported and documented here, it is highly advised to use the plugin system as the primary access to the radio, since this is the highest and easiest interface to it.

File List

Driver Layers

In the following subsections the different layers of the EzRadio driver hierarchy are shown. The Plugin System Layer is in the highest and the Radio HAL Layer is in the lowest level of the hierarchy.

Plugin System Layer

This is the highest level control layer of the on-chip EzRadio device. In normal scenarios it is enough to use only this layer to manage and control the operation of the radio. In some special scenarios you might consider using lower level driver functionalities, such as Radio API Layer, Communication Layer or even Radio HAL Layer. The main concept of the EzRadio plugin system is to let the user easily configure and manage high level radio operations such as transmission, reception, CRC error or auto acknowledge management. Each functionalities provided by plugins can be used side by side.

Plugin Manager Configuration

There are two main compile-time configuration inputs of the plugin manager, they are the plugin configuration and the radio configuration.
The plugin configuration is a set of definitions that enables the required plugins. Plugin configuration normally resides in the app-config.h header file and generated by Simplicity Studio.
The radio configuration is a set of generated configurations that configures the radio for the required operations. Radio configuration normally resides in a radio-config-wds-gen.h header file and generated by Simplicity Studio.

Simplicity Studio can generate both the app-config.h and the radio-config-wds-gen.h header files using the EzRadio Configurator tool. You can use this tool to configure either the plugin system and the radio according to your needs.

Note: Each EzRadio sample application contains the EzRadio Configurator tool (radio-configurator_*.isc) and pre-generated configuration files with default values.

Plugin System API

This section contains brief descriptions of the functions in the API of each plugins. You will find detailed information on input and output parameters and return values by clicking on the hyperlinked function names. Most functions return an error code, ECODE_EMDRV_EZRADIODRV_OK is returned on success, see ecode.h and ezradio_plugin_manager.h for other error codes.

Plugin Manager

The core of the plugin system is the plugin manager that handles the behavior of the enabled plugins.

ezradioInit()
This function initializes or deinitializes the EZRADIODRV driver. Typically ezradioInit() is called once in your startup code. Each enabled plugin is configured through its input parameter.

ezradioPluginManager()
This function manages the behavior of each enabled plugin. This has to be called in a cyclic manner in your code. It can be either repeated asyncronously or in a timed fashion.

Transmit Plugin

Start transmission functions.
ezradioStartTransmitBasic(), ezradioStartTransmitConfigured(), ezradioStartTransmitCustom(), ezradioStartTransmitDefault() and ezradioStartTransmitSmart()
Each provides different level of configuration for the transmission. Each starts an asynchronous transmission. The registered callback function is called at the end of the transmission.

Receive & CRC Error Plugins

ezradioStartRx()
Starts an asynchronous reception. The registered callback function is called at the end of the transmission.
If the CRC Error plugin is enabled its configured callback is called in case of a packet is received with CRC error.

Auto Acknowledge Plugin

ezradioEnableAutoAck(), ezradioDisableAutoAck()
These functions enables or disables auto acknowledge transmission. The ACK packet is sent asynchronously after a properly received packet.

ezradioSkipAutoAck()
This function can be used to issue the plugin manager to skip transmit the acknowledge packet for the next cycle. Has to be used in links where both nodes transmits an ACK packet. See the corresponding example for more information.

RF Test Plugins

This paragraph covers the Unmodulated Carrier, PN9, Direct Transmit and Direct Receive plugins. These plugins are used to issue transmission or reception that is mostly used to test the RF parameters of the radio.

ezradioStartUnmodulatedCarrier(), ezradioStopUnmodulatedCarrier()
These functions starts and stops transmitting an unmodulated carrier signal.

ezradioStartPn9(), ezradioStopPn9()
These functions starts and stops transmitting an RF signal that is modulated by the output of the on-chip pseudo-random number generator.

ezradioStartDirectTransmit(), ezradioStopDirectTransmit()
These functions starts and stops a direct transmission, where the carrier signal is modulated by the configured data source input.

ezradioStartDirectReceive(), ezradioStopDirectReceive()
These functions starts and stops a direct reception.

Plugin System Example

#include "ezradio_plugin_manager.h"

//Buffers for packet reception and transmission.
uint8_t radioRxPkt[EZRADIO_FIFO_SIZE];
uint8_t radioTxPkt[EZRADIO_FIFO_SIZE] = RADIO_CONFIG_DATA_CUSTOM_PAYLOAD;

//Packet transmit user callback.
void appPacketTransmittedCallback ( EZRADIODRV_Handle_t handle, Ecode_t status )
{
  if ( status == ECODE_EMDRV_EZRADIODRV_OK )
  {
    printf("Packet sent.\n");

    //Start reception after packet is sent properly.
    ezradioStartRx( handle );
  }
}

//Packet receive user callback.
void appPacketReceivedCallback ( EZRADIODRV_Handle_t handle, Ecode_t status )
{
  if ( status == ECODE_EMDRV_EZRADIODRV_OK )
  {
    printf("Packet received.\n");
  }
}

int main(void)
{
  //Initialize EzRadio handler with default data.
  EZRADIODRV_HandleData_t appRadioInitData = EZRADIODRV_INIT_DEFAULT;

  //Add user callbacks for transmission and reception.
  appRadioInitData.packetTx.userCallback = &appPacketTransmittedCallback;
  appRadioInitData.packetRx.userCallback = &appPacketReceivedCallback;

  //Initialize EzRadio device.
  ezradioInit( &appRadioInitData );

  //Start a default transmission.
  ezradioStartTransmitDefault( &appRadioInitData, radioTxPkt );

  while (1) {}
}

Radio API Layer

The second radio access layer is the radio API layer. Basically, this layer implements the radio API documentation. Every command and property access that is documented in the radio API documentation is accessible through the radio API layer.
There are two main scenarios where the radio API layer is useful for the user. The first is where a specific radio API command has to be called and the second is where a specific radio API property or several properties have to be written or read.
In the ezradio_api.c and ezradio_api.h files contain those APIs that are common through all the supported parts. Also, ezradio_api_lib_add.c and ezradio_api_lib_add.h files contain those APIs that are specific to the corresponding radio.
The auto generated command and property lists can be found in the ezradio_cmd.h and ezradio_prop.h files per part.
For more information please refer to the radio API documentation.

Radio API Layer Example

  // EZRadio response structure union
  ezradio_cmd_reply_t ezradioReply;

  // Print EZRadio device number.
  ezradio_part_info(&ezradioReply);
  printf("   Device: Si%04x\n\n", ezradioReply.PART_INFO.PART);

  // Read radio interrupts, clear pending ones
  ezradio_get_int_status(0u, 0u, 0u, NULL);

Communication Layer

The third layer is the radio communication layer. It implements the specialities of the EzRadio SPI communication and contains APIs that hide the direct SPI communication from higher layers. This layer is rarely used alone, it is advised to use higher level layers instead.

Radio HAL Layer

The fourth layer is the radio HAL layer. It implements direct SPI and radio pin management functionalities. This layer is rarely used alone, it is advised to use higher level layers instead.

Modules
	API_Layer
	EzRadio API Layer .

	COMM_Layer
	EzRadio Communication Layer .

	HAL_Layer
	EzRadio HAL Layer .

	Plugin_System
	EzRadio Plugin System Layer, see Plugin System Layer for detailed documentation. .

Macros
#define	EZRADIODRV_COMM_CTS_RETRY 10000
	Number of wait-for-CTS retries.