Microchip® Advanced Software Framework

radio_interface.h File Reference

This is the Radio Interface header file which contains LoRa-specific Radio interface functions declarations and defines.

Copyright (c) 2018-2020 Microchip Technology Inc. and its subsidiaries.

#include <stdint.h>
#include "stdbool.h"

Data Structures

struct  _RadioCallbackParam_t
 A structure for storing the callback parameters. More...
 
struct  _RadioConfiguration_t
 A structure for storing all the attributes of the radio and the transceiver. More...
 
struct  _RadioLBT_t
 A structure for storing all Listen Before Talk parameters. More...
 
struct  _RadioLBTParams_t
 A structure for storing the Listen Before Talk parameters for get and set. More...
 
struct  _RadioModeModulation_t
 A structure for storing the modes and modulations supported as parameters for get and set. More...
 
struct  _RadioReceiveParam_t
 A structure for storing the receive parameters. More...
 
struct  _RadioTransmitParam_t
 A structure for storing the transmit parameters. More...
 

Macros

#define RADIO_DEFAULT_CALLBACK_MASK
 
#define RADIO_FHSS_NEXT_FREQ_CALLBACK_MASK   (1 << 5)
 
#define RADIO_OPMODE_MASK   (0x07)
 
#define RADIO_PHY_FSK_PREAMBLE_BYTES_LENGTH   (5u)
 
#define RADIO_PHY_PREAMBLE_LENGTH   (8u)
 
#define RADIO_RX_DONE_CALLBACK_MASK   (1 << 0)
 
#define RADIO_RX_ERROR_CALLBACK_MASK   (1 << 4)
 
#define RADIO_RX_TIMEOUT_CALLBACK_MASK   (1 << 3)
 
#define RADIO_TX_DONE_CALLBACK_MASK   (1 << 1)
 
#define RADIO_TX_TIMEOUT_CALLBACK_MASK   (1 << 2)
 
#define RADIO_WATCHDOG_TIMEOUT   ((uint32_t)15000)
 
#define TIME_ON_AIR_LOAD_VALUE   ((uint32_t)20000)
 

Typedefs

typedef enum _RadioAttribute_t RadioAttribute_t
 A list of all the attributes. More...
 
typedef void(* RadioCallback_t )(RadioCallbackID_t callback, void *param)
 The radio callback typedef used to declare callback functions from the radio layer. More...
 
typedef enum _RadioCallbackID_t RadioCallbackID_t
 Possible callbacks that can registered to by the upper layer. More...
 
typedef struct
_RadioCallbackParam_t 
RadioCallbackParam_t
 A structure for storing the callback parameters. More...
 
typedef struct
_RadioConfiguration_t 
RadioConfiguration_t
 A structure for storing all the attributes of the radio and the transceiver. More...
 
typedef enum _RadioDataRate_t RadioDataRate_t
 Possible spread factors supported. More...
 
typedef enum _RadioError_t RadioError_t
 Possible error states returned by the radio. More...
 
typedef enum
_RadioErrorCodingRate_t 
RadioErrorCodingRate_t
 Possible error coding rate supported. More...
 
typedef enum _RadioFSKBandWidth_t RadioFSKBandWidth_t
 Possible FSK bandWidth supported. More...
 
typedef enum _RadioFSKShaping_t RadioFSKShaping_t
 Possible FSK shaping supported. More...
 
typedef struct _RadioLBT_t RadioLBT_t
 A structure for storing all Listen Before Talk parameters. More...
 
typedef struct _RadioLBTParams_t RadioLBTParams_t
 A structure for storing the Listen Before Talk parameters for get and set. More...
 
typedef enum _RadioLoRaBandWidth_t RadioLoRaBandWidth_t
 Possible LoRa bandWidth supported. More...
 
typedef enum _RadioMode_t RadioMode_t
 
typedef struct
_RadioModeModulation_t 
RadioModeModulation_t
 A structure for storing the modes and modulations supported as parameters for get and set. More...
 
typedef enum _RadioModulation_t RadioModulation_t
 Possible modulations supported. More...
 
typedef enum _RadioReceive_t RadioReceive_t
 Attributes for starting and stopping the receive operation. More...
 
typedef struct _RadioReceiveParam_t RadioReceiveParam_t
 A structure for storing the receive parameters. More...
 
typedef enum _RadioState_t RadioState_t
 Possible Radio states. More...
 
typedef struct
_RadioTransmitParam_t 
RadioTransmitParam_t
 A structure for storing the transmit parameters. More...
 

Enumerations

enum  _RadioAttribute_t {
  LORA_SYNC_WORD,
  CHANNEL_FREQUENCY,
  CHANNEL_FREQUENCY_DEVIATION,
  PREAMBLE_LEN,
  OUTPUT_POWER,
  CRC,
  IQINVERTED,
  BANDWIDTH,
  PABOOST,
  MODULATION,
  FREQUENCY_HOP_PERIOD,
  ERROR_CODING_RATE,
  WATCHDOG_TIMEOUT,
  FSK_BIT_RATE,
  PACKET_SNR,
  FSK_DATA_SHAPING,
  FSK_RX_BW,
  FSK_AFC_BW,
  FSK_SYNC_WORD,
  FSK_SYNC_WORD_LEN,
  CRC_ON,
  MAX_POWER,
  SPREADING_FACTOR,
  GET_RANDOM,
  GET_MAX_POWER,
  SYMBOL_TIMEOUT,
  RADIO_CALLBACK,
  MODE_MODULATION,
  MAX_RADIO_ATTRIBUTES,
  RADIO_LBT_PARAMS,
  RADIO_CLOCK_STABLE_DELAY,
  PACKET_RSSI_VALUE
}
 A list of all the attributes. More...
 
enum  _RadioCallbackID_t {
  RADIO_RX_DONE_CALLBACK = (1 << 0),
  RADIO_TX_DONE_CALLBACK = (1 << 1),
  RADIO_TX_TIMEOUT_CALLBACK = (1 << 2),
  RADIO_RX_TIMEOUT_CALLBACK = (1 << 3),
  RADIO_RX_ERROR_CALLBACK = (1 << 4),
  RADIO_FHSS_NEXT_FREQ_CALLBACK = (1 << 5)
}
 Possible callbacks that can registered to by the upper layer. More...
 
enum  _RadioDataRate_t {
  SF_7 = 7,
  SF_8,
  SF_9,
  SF_10,
  SF_11,
  SF_12
}
 Possible spread factors supported. More...
 
enum  _RadioError_t {
  ERR_NONE = 0,
  ERR_NO_DATA,
  ERR_DATA_SIZE,
  ERR_INVALID_REQ,
  ERR_RADIO_BUSY,
  ERR_OUT_OF_RANGE,
  ERR_UNSUPPORTED_ATTR,
  ERR_CHANNEL_BUSY
}
 Possible error states returned by the radio. More...
 
enum  _RadioErrorCodingRate_t {
  CR_4_5 = 1,
  CR_4_6,
  CR_4_7,
  CR_4_8
}
 Possible error coding rate supported. More...
 
enum  _RadioFSKBandWidth_t {
  FSKBW_250_0KHZ = 1,
  FSKBW_125_0KHZ,
  FSKBW_62_5KHZ,
  FSKBW_31_3KHZ,
  FSKBW_15_6KHZ,
  FSKBW_7_8KHZ,
  FSKBW_3_9KHZ,
  FSKBW_INVALID_PADDING_0,
  FSKBW_200_0KHZ,
  FSKBW_100_0KHZ,
  FSKBW_50_0KHZ,
  FSKBW_25_0KHZ,
  FSKBW_12_5KHZ,
  FSKBW_6_3KHZ,
  FSKBW_3_1KHZ,
  FSKBW_INVALID_PADDING_1,
  FSKBW_166_7KHZ,
  FSKBW_83_3KHZ,
  FSKBW_41_7KHZ,
  FSKBW_20_8KHZ,
  FSKBW_10_4KHZ,
  FSKBW_5_2KHZ,
  FSKBW_2_6KHZ
}
 Possible FSK bandWidth supported. More...
 
enum  _RadioFSKShaping_t {
  FSK_SHAPING_NONE = 0,
  FSK_SHAPING_GAUSS_BT_1_0,
  FSK_SHAPING_GAUSS_BT_0_5,
  FSK_SHAPING_GAUSS_BT_0_3
}
 Possible FSK shaping supported. More...
 
enum  _RadioLoRaBandWidth_t {
  BW_125KHZ = 7,
  BW_250KHZ,
  BW_500KHZ,
  BW_UNDEFINED
}
 Possible LoRa bandWidth supported. More...
 
enum  _RadioMode_t {
  MODE_SLEEP = 0,
  MODE_STANDBY,
  MODE_FSTX,
  MODE_TX,
  MODE_FSRX,
  MODE_RXCONT,
  MODE_RXSINGLE,
  MODE_CAD
}
 
enum  _RadioModulation_t {
  MODULATION_FSK = 0,
  MODULATION_LORA
}
 Possible modulations supported. More...
 
enum  _RadioReceive_t {
  RECEIVE_START,
  RECEIVE_STOP
}
 Attributes for starting and stopping the receive operation. More...
 
enum  _RadioState_t {
  RADIO_STATE_SLEEP = 0,
  RADIO_STATE_IDLE,
  RADIO_STATE_TX,
  RADIO_STATE_SCAN,
  RADIO_STATE_RX,
  RADIO_STATE_RX_BUSY,
  RADIO_STATE_CAD
}
 Possible Radio states. More...
 

Functions

void RADIO_ClearCallbackBitmask (uint8_t bitmask)
 The function disables the callbacks by setting masks. More...
 
void RADIO_DIO0 (void)
 This function is called when a hardware radio interrupt DIO0 occurs. More...
 
void RADIO_DIO1 (void)
 This function is called when a hardware radio interrupt DIO1 occurs. More...
 
void RADIO_DIO2 (void)
 This function is called when a hardware radio interrupt DIO2 occurs. More...
 
void RADIO_DIO3 (void)
 This function is called when a hardware radio interrupt DIO3 occurs. More...
 
void RADIO_DIO4 (void)
 This function is called when a hardware radio interrupt DIO4 occurs. More...
 
void RADIO_DIO5 (void)
 This function is called when a hardware radio interrupt DIO5 occurs. More...
 
void RADIO_FHSSChangeChannel (void)
 This function sets the receive frequency of the transceiver while hopping in FHSS. More...
 
void RADIO_FSKFifoEmpty (void)
 This function is triggered when the FIFO is empty. More...
 
void RADIO_FSKFifoLevel (void)
 This function is triggered when the FIFO is above the threshold value. More...
 
void RADIO_FSKPacketSent (void)
 This function is triggered by hardware interrupt when a FSK is transmitted. More...
 
void RADIO_FSKPayloadReady (void)
 This function is triggered by hardware interrupt when a FSK is received. More...
 
void RADIO_FSKSyncAddr (void)
 This function is called when a sync address match happens or when packet collision happens. More...
 
RadioError_t RADIO_GetAttr (RadioAttribute_t attribute, void *value)
 This function gets the radio attribute. More...
 
uint8_t RADIO_GetCallbackBitmask (void)
 The function enables or disables the callbacks by setting masks. More...
 
RadioError_t RADIO_GetData (uint8_t **data, uint16_t *dataLen)
 This function can be called by MAC to read radio buffer pointer and length of a receive frame(typically in rxdone) More...
 
RadioState_t RADIO_GetState (void)
 This function gets the radio state. More...
 
void RADIO_Init (void)
 The Radio Init initializes the transceiver. More...
 
void RADIO_InitDefaultAttributes (void)
 The function initializes the default attributes depending on region chosen. More...
 
uint16_t RADIO_ReadRandom (void)
 This function generates random number using the transceiver and returns it. More...
 
RadioError_t RADIO_Receive (RadioReceiveParam_t *param)
 This function receives the data and stores it in the buffer pointer space by doing a task post to the RADIO_RxHandler. More...
 
void RADIO_RxDone (void)
 This function is triggered by hardware interrupt when a LoRa is received. More...
 
void RADIO_RxTimeout (void)
 This function is triggered when no packets are received within a specified Rx window. More...
 
RadioError_t RADIO_SetAttr (RadioAttribute_t attribute, void *value)
 This function sets the radio attribute. More...
 
void RADIO_SetCallbackBitmask (uint8_t bitmask)
 The function enables the callbacks by setting masks. More...
 
RadioError_t RADIO_StopCW (void)
 The function stops the transmission of a CW. More...
 
RadioError_t RADIO_Transmit (RadioTransmitParam_t *param)
 This function transmits the data by doing a task post to the RADIO_TxHandler. More...
 
RadioError_t RADIO_TransmitCW (void)
 The function transmits a CW and is supported only in LORA mode. More...
 
void RADIO_TxDone (void)
 This function is triggered by hardware interrupt when a LoRa is transmitted. More...
 
void RADIO_UnhandledInterrupt (RadioModulation_t modulation)
 This function handles the rogue radio interrupts. More...
 

#define RADIO_DEFAULT_CALLBACK_MASK
Value:
#define RADIO_RX_DONE_CALLBACK_MASK
Definition: radio_interface.h:60
#define RADIO_RX_TIMEOUT_CALLBACK_MASK
Definition: radio_interface.h:63
#define RADIO_TX_TIMEOUT_CALLBACK_MASK
Definition: radio_interface.h:62
#define RADIO_TX_DONE_CALLBACK_MASK
Definition: radio_interface.h:61
#define RADIO_RX_ERROR_CALLBACK_MASK
Definition: radio_interface.h:64
#define RADIO_FHSS_NEXT_FREQ_CALLBACK_MASK   (1 << 5)
#define RADIO_OPMODE_MASK   (0x07)
#define RADIO_PHY_FSK_PREAMBLE_BYTES_LENGTH   (5u)
#define RADIO_PHY_PREAMBLE_LENGTH   (8u)
#define RADIO_RX_DONE_CALLBACK_MASK   (1 << 0)
#define RADIO_RX_ERROR_CALLBACK_MASK   (1 << 4)
#define RADIO_RX_TIMEOUT_CALLBACK_MASK   (1 << 3)
#define RADIO_TX_DONE_CALLBACK_MASK   (1 << 1)
#define RADIO_TX_TIMEOUT_CALLBACK_MASK   (1 << 2)
#define RADIO_WATCHDOG_TIMEOUT   ((uint32_t)15000)
#define TIME_ON_AIR_LOAD_VALUE   ((uint32_t)20000)

A list of all the attributes.

typedef void(* RadioCallback_t)(RadioCallbackID_t callback, void *param)

The radio callback typedef used to declare callback functions from the radio layer.

Possible callbacks that can registered to by the upper layer.

A structure for storing the callback parameters.

A structure for storing all the attributes of the radio and the transceiver.

Possible spread factors supported.

Possible error states returned by the radio.

Possible error coding rate supported.

Possible FSK bandWidth supported.

Possible FSK shaping supported.

typedef struct _RadioLBT_t RadioLBT_t

A structure for storing all Listen Before Talk parameters.

A structure for storing the Listen Before Talk parameters for get and set.

Possible LoRa bandWidth supported.

typedef enum _RadioMode_t RadioMode_t

A structure for storing the modes and modulations supported as parameters for get and set.

Possible modulations supported.

Attributes for starting and stopping the receive operation.

A structure for storing the receive parameters.

Possible Radio states.

A structure for storing the transmit parameters.

A list of all the attributes.

Enumerator
LORA_SYNC_WORD 
CHANNEL_FREQUENCY 
CHANNEL_FREQUENCY_DEVIATION 
PREAMBLE_LEN 
OUTPUT_POWER 
CRC 
IQINVERTED 
BANDWIDTH 
PABOOST 
MODULATION 
FREQUENCY_HOP_PERIOD 
ERROR_CODING_RATE 
WATCHDOG_TIMEOUT 
FSK_BIT_RATE 
PACKET_SNR 
FSK_DATA_SHAPING 
FSK_RX_BW 
FSK_AFC_BW 
FSK_SYNC_WORD 
FSK_SYNC_WORD_LEN 
CRC_ON 
MAX_POWER 
SPREADING_FACTOR 
GET_RANDOM 
GET_MAX_POWER 
SYMBOL_TIMEOUT 
RADIO_CALLBACK 
MODE_MODULATION 
MAX_RADIO_ATTRIBUTES 
RADIO_LBT_PARAMS 
RADIO_CLOCK_STABLE_DELAY 
PACKET_RSSI_VALUE 

Possible callbacks that can registered to by the upper layer.

Enumerator
RADIO_RX_DONE_CALLBACK 
RADIO_TX_DONE_CALLBACK 
RADIO_TX_TIMEOUT_CALLBACK 
RADIO_RX_TIMEOUT_CALLBACK 
RADIO_RX_ERROR_CALLBACK 
RADIO_FHSS_NEXT_FREQ_CALLBACK 

Possible spread factors supported.

Enumerator
SF_7 
SF_8 
SF_9 
SF_10 
SF_11 
SF_12 

Possible error states returned by the radio.

Enumerator
ERR_NONE 
ERR_NO_DATA 
ERR_DATA_SIZE 
ERR_INVALID_REQ 
ERR_RADIO_BUSY 
ERR_OUT_OF_RANGE 
ERR_UNSUPPORTED_ATTR 
ERR_CHANNEL_BUSY 

Possible error coding rate supported.

Enumerator
CR_4_5 
CR_4_6 
CR_4_7 
CR_4_8 

Possible FSK bandWidth supported.

Enumerator
FSKBW_250_0KHZ 
FSKBW_125_0KHZ 
FSKBW_62_5KHZ 
FSKBW_31_3KHZ 
FSKBW_15_6KHZ 
FSKBW_7_8KHZ 
FSKBW_3_9KHZ 
FSKBW_INVALID_PADDING_0 
FSKBW_200_0KHZ 
FSKBW_100_0KHZ 
FSKBW_50_0KHZ 
FSKBW_25_0KHZ 
FSKBW_12_5KHZ 
FSKBW_6_3KHZ 
FSKBW_3_1KHZ 
FSKBW_INVALID_PADDING_1 
FSKBW_166_7KHZ 
FSKBW_83_3KHZ 
FSKBW_41_7KHZ 
FSKBW_20_8KHZ 
FSKBW_10_4KHZ 
FSKBW_5_2KHZ 
FSKBW_2_6KHZ 

Possible FSK shaping supported.

Enumerator
FSK_SHAPING_NONE 
FSK_SHAPING_GAUSS_BT_1_0 
FSK_SHAPING_GAUSS_BT_0_5 
FSK_SHAPING_GAUSS_BT_0_3 

Possible LoRa bandWidth supported.

Enumerator
BW_125KHZ 
BW_250KHZ 
BW_500KHZ 
BW_UNDEFINED 
Enumerator
MODE_SLEEP 
MODE_STANDBY 
MODE_FSTX 
MODE_TX 
MODE_FSRX 
MODE_RXCONT 
MODE_RXSINGLE 
MODE_CAD 

Possible modulations supported.

Enumerator
MODULATION_FSK 
MODULATION_LORA 

Attributes for starting and stopping the receive operation.

Enumerator
RECEIVE_START 
RECEIVE_STOP 

Possible Radio states.

Enumerator
RADIO_STATE_SLEEP 
RADIO_STATE_IDLE 
RADIO_STATE_TX 
RADIO_STATE_SCAN 
RADIO_STATE_RX 
RADIO_STATE_RX_BUSY 
RADIO_STATE_CAD 

void RADIO_ClearCallbackBitmask ( uint8_t  bitmask)

The function disables the callbacks by setting masks.

Setting a bit to 1 means that the callback is enabled Setting a bit to 0 means that the callback is disabled

Parameters
bitmask- The bitmask for disabling callbacks.
void RADIO_DIO0 ( void  )

This function is called when a hardware radio interrupt DIO0 occurs.

void RADIO_DIO1 ( void  )

This function is called when a hardware radio interrupt DIO1 occurs.

void RADIO_DIO2 ( void  )

This function is called when a hardware radio interrupt DIO2 occurs.

void RADIO_DIO3 ( void  )

This function is called when a hardware radio interrupt DIO3 occurs.

void RADIO_DIO4 ( void  )

This function is called when a hardware radio interrupt DIO4 occurs.

void RADIO_DIO5 ( void  )

This function is called when a hardware radio interrupt DIO5 occurs.

void RADIO_FHSSChangeChannel ( void  )
void RADIO_FSKFifoEmpty ( void  )

This function is triggered when the FIFO is empty.

    This is triggered by a hardware interrupt. 
Parameters
-none
Returns
- none
void RADIO_FSKFifoLevel ( void  )

This function is triggered when the FIFO is above the threshold value.

This is triggered by a hardware interrupt.

Parameters
-none
Returns
- none
void RADIO_FSKPacketSent ( void  )

This function is triggered by hardware interrupt when a FSK is transmitted.

Parameters
-none
Returns
- none
void RADIO_FSKPayloadReady ( void  )

This function is triggered by hardware interrupt when a FSK is received.

Parameters
-none
Returns
- none
void RADIO_FSKSyncAddr ( void  )

This function is called when a sync address match happens or when packet collision happens.

In that case we clear the FSKPayload index and datalen variables to download the new packet.

Parameters
-none
Returns
- none.
RadioError_t RADIO_GetAttr ( RadioAttribute_t  attribute,
void *  value 
)

This function gets the radio attribute.

Parameters
attribute- The attribute to get.
value- The pointer that is used to get the value.
Returns
- The error condition for getting a given attribute.

Referenced by MSG_IsTxPossible().

uint8_t RADIO_GetCallbackBitmask ( void  )

The function enables or disables the callbacks by setting masks.

Setting a bit to 1 means that the callback is enabled Setting a bit to 0 means that the callback is disabled

Returns
- Returns the bit mask that is stored.
RadioError_t RADIO_GetData ( uint8_t **  data,
uint16_t *  dataLen 
)

This function can be called by MAC to read radio buffer pointer and length of a receive frame(typically in rxdone)

Parameters
-place holder for data pointer, length
Returns
- ERR_NONE. Other types are not used now.
RadioState_t RADIO_GetState ( void  )

This function gets the radio state.

Returns
- The current state of the radio.
void RADIO_Init ( void  )

The Radio Init initializes the transceiver.

void RADIO_InitDefaultAttributes ( void  )

The function initializes the default attributes depending on region chosen.

uint16_t RADIO_ReadRandom ( void  )
RadioError_t RADIO_Receive ( RadioReceiveParam_t param)

This function receives the data and stores it in the buffer pointer space by doing a task post to the RADIO_RxHandler.

Parameters
param- Stores the receive parameters.
Returns
- The error condition for the receive operation.
void RADIO_RxDone ( void  )

This function is triggered by hardware interrupt when a LoRa is received.

Parameters
-none
Returns
- none
void RADIO_RxTimeout ( void  )

This function is triggered when no packets are received within a specified Rx window.

This is triggered by a hardware interrupt.

Parameters
-none
Returns
- none
RadioError_t RADIO_SetAttr ( RadioAttribute_t  attribute,
void *  value 
)

This function sets the radio attribute.

Parameters
attribute- The attribute to set.
value- The pointer that is used to set the value.
Returns
- The error condition for setting a given attribute.

Referenced by enddevice_cpc_execute_command().

void RADIO_SetCallbackBitmask ( uint8_t  bitmask)

The function enables the callbacks by setting masks.

Setting a bit to 1 means that the callback is enabled Setting a bit to 0 means that the callback is disabled

Parameters
bitmask- The bitmask for enabling and disabling callbacks.
RadioError_t RADIO_StopCW ( void  )

The function stops the transmission of a CW.

Returns
- returns the status of the operation

Referenced by enddevice_txcw_callback().

RadioError_t RADIO_Transmit ( RadioTransmitParam_t param)

This function transmits the data by doing a task post to the RADIO_TxHandler.

Parameters
param- Stores the transmission parameters.
Returns
- The error condition for the transmit operation.
RadioError_t RADIO_TransmitCW ( void  )

The function transmits a CW and is supported only in LORA mode.

Returns
- returns the status of the operation

Referenced by enddevice_cpc_execute_command().

void RADIO_TxDone ( void  )

This function is triggered by hardware interrupt when a LoRa is transmitted.

Parameters
-none
Returns
- none
void RADIO_UnhandledInterrupt ( RadioModulation_t  modulation)

This function handles the rogue radio interrupts.

Parameters
modulation- modulation when this function is called.
Returns
- none.