radio.h

00001 /*
00002   ______                              _
00003  / _____)             _              | |
00004 ( (____  _____ ____ _| |_ _____  ____| |__
00005  \____ \| ___ |    (_   _) ___ |/ ___)  _ \
00006  _____) ) ____| | | || |_| ____( (___| | | |
00007 (______/|_____)_|_|_| \__)_____)\____)_| |_|
00008     (C)2016 Semtech
00009 
00010 Description: Handling of the node configuration protocol
00011 
00012 License: Revised BSD License, see LICENSE.TXT file include in the project
00013 
00014 Maintainer: Miguel Luis, Gregory Cristian and Matthieu Verdy
00015 */
00016 #ifndef __RADIO_H__
00017 #define __RADIO_H__
00018 
00019 #include "mbed.h"
00020 
00021 /*!
00022  * \brief Structure describing the radio status
00023  */
00024 typedef union
00025 {
00026     /*!
00027      * \brief Structure of the radio status
00028      */
00029     struct
00030     {
00031         uint8_t CpuBusy   : 1;  //!< Flag for CPU radio busy
00032         uint8_t DmaBusy   : 1;  //!< Flag for DMA busy
00033         uint8_t CmdStatus : 3;  //!< Command status
00034         uint8_t ChipMode  : 3;  //!< Chip mode
00035     }Fields;
00036 
00037     /*!
00038      * \brief Serialized radio status
00039      */
00040     uint8_t Value;
00041 }RadioStatus_t;
00042 
00043 /*!
00044  * \brief Structure describing the ranging codes for callback functions
00045  */
00046 typedef enum
00047 {
00048     IRQ_RANGING_SLAVE_ERROR_CODE            = 0x00,
00049     IRQ_RANGING_SLAVE_VALID_CODE,
00050     IRQ_RANGING_MASTER_ERROR_CODE,
00051     IRQ_RANGING_MASTER_VALID_CODE,
00052 }IrqRangingCode_t;
00053 
00054 /*!
00055  * \brief Structure describing the error codes for callback functions
00056  */
00057 typedef enum
00058 {
00059     IRQ_HEADER_ERROR_CODE                   = 0x00,
00060     IRQ_SYNCWORD_ERROR_CODE,
00061     IRQ_CRC_ERROR_CODE,
00062     IRQ_RANGING_ON_LORA_ERROR_CODE,
00063 }IrqErrorCode_t;
00064 
00065 /*!
00066  * \brief Structure describing the validity codes for callback function rxValid
00067  */
00068 typedef enum
00069 {
00070     IRQ_HEADER_VALID_CODE                   = 0x00,
00071     IRQ_SYNCWORD_VALID_CODE,
00072 }IrqValidCode_t;
00073 
00074 /*!
00075  * \brief Represents all possible opcode understood by the radio
00076  */
00077 typedef enum RadioCommands_u
00078 {
00079     RADIO_GET_STATUS                        = 0xC0,
00080     RADIO_WRITE_REGISTER                    = 0x18,
00081     RADIO_READ_REGISTER                     = 0x19,
00082     RADIO_WRITE_BUFFER                      = 0x1A,
00083     RADIO_READ_BUFFER                       = 0x1B,
00084     RADIO_SET_SLEEP                         = 0x84,
00085     RADIO_SET_STANDBY                       = 0x80,
00086     RADIO_SET_FS                            = 0xC1,
00087     RADIO_SET_TX                            = 0x83,
00088     RADIO_SET_RX                            = 0x82,
00089     RADIO_SET_RXDUTYCYCLE                   = 0x94,
00090     RADIO_SET_CAD                           = 0xC5,
00091     RADIO_SET_TXCONTINUOUSWAVE              = 0xD1,
00092     RADIO_SET_TXCONTINUOUSPREAMBLE          = 0xD2,
00093     RADIO_SET_PACKETTYPE                    = 0x8A,
00094     RADIO_GET_PACKETTYPE                    = 0x03,
00095     RADIO_SET_RFFREQUENCY                   = 0x86,
00096     RADIO_SET_TXPARAMS                      = 0x8E,
00097     RADIO_SET_CADPARAMS                     = 0x88,
00098     RADIO_SET_BUFFERBASEADDRESS             = 0x8F,
00099     RADIO_SET_MODULATIONPARAMS              = 0x8B,
00100     RADIO_SET_PACKETPARAMS                  = 0x8C,
00101     RADIO_GET_RXBUFFERSTATUS                = 0x17,
00102     RADIO_GET_PACKETSTATUS                  = 0x1D,
00103     RADIO_GET_RSSIINST                      = 0x1F,
00104     RADIO_SET_DIOIRQPARAMS                  = 0x8D,
00105     RADIO_GET_IRQSTATUS                     = 0x15,
00106     RADIO_CLR_IRQSTATUS                     = 0x97,
00107     RADIO_CALIBRATE                         = 0x89,
00108     RADIO_SET_REGULATORMODE                 = 0x96,
00109     RADIO_SET_SAVECONTEXT                   = 0xD5,
00110     RADIO_SET_AUTOTX                        = 0x98,
00111     RADIO_SET_AUTOFS                        = 0x9E,
00112     RADIO_SET_LONGPREAMBLE                  = 0x9B,
00113     RADIO_SET_UARTSPEED                     = 0x9D,
00114     RADIO_SET_RANGING_ROLE                  = 0xA3,
00115 }RadioCommands_t;
00116 
00117 /*!
00118  * \brief The radio callbacks structure
00119  * Holds function pointers to be called on radio interrupts
00120  */
00121 typedef struct
00122 {
00123     void ( *txDone )( void );                       //!< Pointer to a function run on successful transmission
00124     void ( *rxDone )( void );                       //!< Pointer to a function run on successful reception
00125     void ( *rxSyncWordDone )( void );               //!< Pointer to a function run on successful SyncWord reception
00126     void ( *rxHeaderDone )( void );                 //!< Pointer to a function run on successful Header reception
00127     void ( *txTimeout )( void );                    //!< Pointer to a function run on transmission timeout
00128     void ( *rxTimeout )( void );                    //!< Pointer to a function run on reception timeout
00129     void ( *rxError )( IrqErrorCode_t errCode );    //!< Pointer to a function run on reception error
00130     void ( *rangingDone )( IrqRangingCode_t val );  //!< Pointer to a function run on ranging terminated
00131     void ( *cadDone )( bool cadFlag );              //!< Pointer to a function run on channel activity detected
00132 }RadioCallbacks_t;
00133 
00134 /*!
00135  * \brief Class holding the basic communications with a radio
00136  *
00137  * It sets the functions to read/write registers, send commands and read/write
00138  * payload.
00139  * It also provides functions to run callback functions depending on the
00140  * interrupts generated from the radio.
00141  */
00142 class Radio
00143 {
00144 protected:
00145     /*!
00146      * \brief Callback on Tx done interrupt
00147      */
00148     void ( *txDone )( void );
00149 
00150     /*!
00151      * \brief Callback on Rx done interrupt
00152      */
00153     void ( *rxDone )( void );
00154 
00155     /*!
00156      * \brief Callback on Rx SyncWord interrupt
00157      */
00158     void ( *rxSyncWordDone )( void );
00159 
00160     /*!
00161      * \brief Callback on Rx header received interrupt
00162      */
00163     void ( *rxHeaderDone )( void );
00164 
00165     /*!
00166      * \brief Callback on Tx timeout interrupt
00167      */
00168     void ( *txTimeout )( void );
00169 
00170     /*!
00171      * \brief Callback on Rx timeout interrupt
00172      */
00173     void ( *rxTimeout )( void );
00174 
00175     /*!
00176      * \brief Callback on Rx error interrupt
00177      *
00178      * \param [out] errCode       A code indicating the type of interrupt (SyncWord error or CRC error)
00179      */
00180     void ( *rxError )( IrqErrorCode_t errCode );
00181 
00182     /*!
00183      * \brief Callback on ranging done interrupt
00184      *
00185      * \param [out] val           A flag indicating the type of interrupt (Master/Slave and Valid/Error)
00186      */
00187     void ( *rangingDone )( IrqRangingCode_t val );
00188 
00189     /*!
00190      * \brief Callback on Channel Activity Detection done interrupt
00191      *
00192      * \param [out] cadFlag       Flag for channel activity detected or not
00193      */
00194     void ( *cadDone )( bool cadFlag );
00195 
00196 public:
00197     /*!
00198      * \brief Constructor for radio class
00199      * Sets the callbacks functions pointers
00200      *
00201      * \param [in]  callbacks     The structure of callbacks function pointers
00202      *                            to be called on radio interrupts
00203      *
00204      */
00205     Radio( RadioCallbacks_t *callbacks )
00206     {
00207         this->txDone = callbacks->txDone;
00208         this->rxDone = callbacks->rxDone;
00209         this->rxSyncWordDone = callbacks->rxSyncWordDone;
00210         this->rxHeaderDone = callbacks->rxHeaderDone;
00211         this->txTimeout = callbacks->txTimeout;
00212         this->rxTimeout = callbacks->rxTimeout;
00213         this->rxError = callbacks->rxError;
00214         this->rangingDone = callbacks->rangingDone;
00215         this->cadDone = callbacks->cadDone;
00216     }
00217     virtual ~Radio( void ){ };
00218 
00219     /*!
00220      * \brief Resets the radio
00221      */
00222     virtual void Reset( void ) = 0;
00223 
00224     /*!
00225      * \brief Gets the current radio status
00226      *
00227      * \retval      status        Radio status
00228      */
00229     virtual RadioStatus_t GetStatus( void ) = 0;
00230 
00231     /*!
00232      * \brief Writes the given command to the radio
00233      *
00234      * \param [in]  opcode        Command opcode
00235      * \param [in]  buffer        Command parameters byte array
00236      * \param [in]  size          Command parameters byte array size
00237      */
00238     virtual void WriteCommand( RadioCommands_t opcode, uint8_t *buffer, uint16_t size ) = 0;
00239 
00240     /*!
00241      * \brief Reads the given command from the radio
00242      *
00243      * \param [in]  opcode        Command opcode
00244      * \param [in]  buffer        Command parameters byte array
00245      * \param [in]  size          Command parameters byte array size
00246      */
00247     virtual void ReadCommand( RadioCommands_t opcode, uint8_t *buffer, uint16_t size ) = 0;
00248 
00249     /*!
00250      * \brief Writes multiple radio registers starting at address
00251      *
00252      * \param [in]  address       First Radio register address
00253      * \param [in]  buffer        Buffer containing the new register's values
00254      * \param [in]  size          Number of registers to be written
00255      */
00256     virtual void WriteRegister( uint16_t address, uint8_t *buffer, uint16_t size ) = 0;
00257 
00258     /*!
00259      * \brief Writes the radio register at the specified address
00260      *
00261      * \param [in]  address       Register address
00262      * \param [in]  value         New register value
00263      */
00264     virtual void WriteRegister( uint16_t address, uint8_t value ) = 0;
00265 
00266     /*!
00267      * \brief Reads multiple radio registers starting at address
00268      *
00269      * \param [in]  address       First Radio register address
00270      * \param [out] buffer        Buffer where to copy the registers data
00271      * \param [in]  size          Number of registers to be read
00272      */
00273     virtual void ReadRegister( uint16_t address, uint8_t *buffer, uint16_t size ) = 0;
00274 
00275     /*!
00276      * \brief Reads the radio register at the specified address
00277      *
00278      * \param [in]  address       Register address
00279      *
00280      * \retval      value         The register value
00281      */
00282     virtual uint8_t ReadRegister( uint16_t address ) = 0;
00283 
00284     /*!
00285      * \brief Writes Radio Data Buffer with buffer of size starting at offset.
00286      *
00287      * \param [in]  offset        Offset where to start writing
00288      * \param [in]  buffer        Buffer pointer
00289      * \param [in]  size          Buffer size
00290      */
00291     virtual void WriteBuffer( uint8_t offset, uint8_t *buffer, uint8_t size ) = 0;
00292 
00293     /*!
00294      * \brief Reads Radio Data Buffer at offset to buffer of size
00295      *
00296      * \param [in]  offset        Offset where to start reading
00297      * \param [out] buffer        Buffer pointer
00298      * \param [in]  size          Buffer size
00299      */
00300     virtual void ReadBuffer( uint8_t offset, uint8_t *buffer, uint8_t size ) = 0;
00301 
00302     /*!
00303      * \brief Return firmware version
00304      *
00305      * \retval      firmware      The firmware version
00306      */
00307     virtual uint16_t GetFirmwareVersion( void ) = 0;
00308 };
00309 
00310 #endif // __RADIO_H__