EZRADIODRV
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
-
Plugin System Layer
-
Plugin Manager
- plugins/src/ezradio_plugin_manager.c
-
plugins/inc/ezradio_plugin_manager.h
-
Transmit Plugin
- plugins/src/ezradio_transmit_plugin.c
-
plugins/inc/ezradio_transmit_plugin.h
-
Receive & CRC Error Plugins
- plugins/src/ezradio_receive_plugin.c
-
plugins/inc/ezradio_receive_plugin.h
- plugins/src/ezradio_crcerror_plugin.c
-
plugins/inc/ezradio_crcerror_plugin.h
-
Auto Acknowledge Plugin
- plugins/src/ezradio_auto_ack_plugin.c
-
plugins/inc/ezradio_auto_ack_plugin.h
-
RF Test Plugins
- plugins/src/ezradio_unmod_carrier_plugin.c
-
plugins/inc/ezradio_unmod_carrier_plugin.h
- plugins/src/ezradio_pn9_plugin.c
-
plugins/inc/ezradio_pn9_plugin.h
- plugins/src/ezradio_direct_transmit_plugin.c
-
plugins/inc/ezradio_direct_transmit_plugin.h
- plugins/src/ezradio_direct_receive_plugin.c
-
plugins/inc/ezradio_direct_receive_plugin.h
-
Plugin Manager
-
Radio API Layer
- common/src/ezradio_api_lib.c
-
common/inc/ezradio_api_lib.h
-
Si4x55
- common/src/si4x55/ezradio_api_lib_add.c
-
common/inc/si4x55/ezradio_api_lib_add.h
-
Si4455
-
si4455/inc/ezradio_cmd.h
-
si4455/inc/ezradio_prop.h
-
-
Si4x6x
- common/src/si4x6x/ezradio_api_lib_add.c
-
common/inc/si4x6x/ezradio_api_lib_add.h
-
Si4460
-
si4460/inc/ezradio_cmd.h
-
si4460/inc/ezradio_prop.h
-
-
Si4461
-
si4461/inc/ezradio_cmd.h
-
si4461/inc/ezradio_prop.h
-
-
Si4463
-
si4463/inc/ezradio_cmd.h
-
si4463/inc/ezradio_prop.h
-
-
Communication Layer
- common/src/ezradio_comm.c
-
common/inc/ezradio_comm.h
-
Radio HAL Layer
- common/src/ezradio_hal.c
-
common/inc/ezradio_hal.h
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.
|
|