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 The radio command opcodes
00076  */
00077 typedef enum RadioCommands_u RadioCommands_t;
00078 
00079 /*!
00080  * \brief The radio callbacks structure
00081  * Holds function pointers to be called on radio interrupts
00082  */
00083 typedef struct
00084 {
00085     void ( *txDone )( void );                       //!< Pointer to a function run on successful transmission
00086     void ( *rxDone )( void );                       //!< Pointer to a function run on successful reception
00087     void ( *rxSyncWordDone )( void );               //!< Pointer to a function run on successful SyncWord reception
00088     void ( *rxHeaderDone )( void );                 //!< Pointer to a function run on successful Header reception
00089     void ( *txTimeout )( void );                    //!< Pointer to a function run on transmission timeout
00090     void ( *rxTimeout )( void );                    //!< Pointer to a function run on reception timeout
00091     void ( *rxError )( IrqErrorCode_t errCode );    //!< Pointer to a function run on reception error
00092     void ( *rangingDone )( IrqRangingCode_t val );  //!< Pointer to a function run on ranging terminated
00093     void ( *cadDone )( bool cadFlag );              //!< Pointer to a function run on channel activity detected
00094 }RadioCallbacks_t;
00095 
00096 /*!
00097  * \brief Class holding the basic communications with a radio
00098  *
00099  * It sets the functions to read/write registers, send commands and read/write
00100  * payload.
00101  * It also provides functions to run callback functions depending on the
00102  * interrupts generated from the radio.
00103  */
00104 class Radio
00105 {
00106 protected:
00107     /*!
00108      * \brief Callback on Tx done interrupt
00109      */
00110     void ( *txDone )( void );
00111 
00112     /*!
00113      * \brief Callback on Rx done interrupt
00114      */
00115     void ( *rxDone )( void );
00116 
00117     /*!
00118      * \brief Callback on Rx SyncWord interrupt
00119      */
00120     void ( *rxSyncWordDone )( void );
00121 
00122     /*!
00123      * \brief Callback on Rx header received interrupt
00124      */
00125     void ( *rxHeaderDone )( void );
00126 
00127     /*!
00128      * \brief Callback on Tx timeout interrupt
00129      */
00130     void ( *txTimeout )( void );
00131 
00132     /*!
00133      * \brief Callback on Rx timeout interrupt
00134      */
00135     void ( *rxTimeout )( void );
00136 
00137     /*!
00138      * \brief Callback on Rx error interrupt
00139      *
00140      * \param [out] errCode       A code indicating the type of interrupt (SyncWord error or CRC error)
00141      */
00142     void ( *rxError )( IrqErrorCode_t errCode );
00143 
00144     /*!
00145      * \brief Callback on ranging done interrupt
00146      *
00147      * \param [out] val           A flag indicating the type of interrupt (Master/Slave and Valid/Error)
00148      */
00149     void ( *rangingDone )( IrqRangingCode_t val );
00150 
00151     /*!
00152      * \brief Callback on Channel Activity Detection done interrupt
00153      *
00154      * \param [out] cadFlag       Flag for channel activity detected or not
00155      */
00156     void ( *cadDone )( bool cadFlag );
00157 
00158 public:
00159     /*!
00160      * \brief Constructor for radio class
00161      * Sets the callbacks functions pointers
00162      *
00163      * \param [in]  callbacks     The structure of callbacks function pointers
00164      *                            to be called on radio interrupts
00165      *
00166      */
00167     Radio( RadioCallbacks_t *callbacks )
00168     {
00169         this->txDone = callbacks->txDone;
00170         this->rxDone = callbacks->rxDone;
00171         this->rxSyncWordDone = callbacks->rxSyncWordDone;
00172         this->rxHeaderDone = callbacks->rxHeaderDone;
00173         this->txTimeout = callbacks->txTimeout;
00174         this->rxTimeout = callbacks->rxTimeout;
00175         this->rxError = callbacks->rxError;
00176         this->rangingDone = callbacks->rangingDone;
00177         this->cadDone = callbacks->cadDone;
00178     }
00179     virtual ~Radio( void ){ };
00180 
00181     /*!
00182      * \brief Resets the radio
00183      */
00184     virtual void Reset( void ) = 0;
00185 
00186     /*!
00187      * \brief Gets the current radio status
00188      *
00189      * \retval      status        Radio status
00190      */
00191     virtual RadioStatus_t GetStatus( void ) = 0;
00192 
00193     /*!
00194      * \brief Writes the given command to the radio
00195      *
00196      * \param [in]  opcode        Command opcode
00197      * \param [in]  buffer        Command parameters byte array
00198      * \param [in]  size          Command parameters byte array size
00199      */
00200     virtual void WriteCommand( RadioCommands_t opcode, uint8_t *buffer, uint16_t size ) = 0;
00201 
00202     /*!
00203      * \brief Reads the given command from the radio
00204      *
00205      * \param [in]  opcode        Command opcode
00206      * \param [in]  buffer        Command parameters byte array
00207      * \param [in]  size          Command parameters byte array size
00208      */
00209     virtual void ReadCommand( RadioCommands_t opcode, uint8_t *buffer, uint16_t size ) = 0;
00210 
00211     /*!
00212      * \brief Writes multiple radio registers starting at address
00213      *
00214      * \param [in]  address       First Radio register address
00215      * \param [in]  buffer        Buffer containing the new register's values
00216      * \param [in]  size          Number of registers to be written
00217      */
00218     virtual void WriteRegister( uint16_t address, uint8_t *buffer, uint16_t size ) = 0;
00219 
00220     /*!
00221      * \brief Writes the radio register at the specified address
00222      *
00223      * \param [in]  address       Register address
00224      * \param [in]  value         New register value
00225      */
00226     virtual void WriteRegister( uint16_t address, uint8_t value ) = 0;
00227 
00228     /*!
00229      * \brief Reads multiple radio registers starting at address
00230      *
00231      * \param [in]  address       First Radio register address
00232      * \param [out] buffer        Buffer where to copy the registers data
00233      * \param [in]  size          Number of registers to be read
00234      */
00235     virtual void ReadRegister( uint16_t address, uint8_t *buffer, uint16_t size ) = 0;
00236 
00237     /*!
00238      * \brief Reads the radio register at the specified address
00239      *
00240      * \param [in]  address       Register address
00241      *
00242      * \retval      value         The register value
00243      */
00244     virtual uint8_t ReadRegister( uint16_t address ) = 0;
00245 
00246     /*!
00247      * \brief Writes Radio Data Buffer with buffer of size starting at offset.
00248      *
00249      * \param [in]  offset        Offset where to start writing
00250      * \param [in]  buffer        Buffer pointer
00251      * \param [in]  size          Buffer size
00252      */
00253     virtual void WriteBuffer( uint8_t offset, uint8_t *buffer, uint8_t size ) = 0;
00254 
00255     /*!
00256      * \brief Reads Radio Data Buffer at offset to buffer of size
00257      *
00258      * \param [in]  offset        Offset where to start reading
00259      * \param [out] buffer        Buffer pointer
00260      * \param [in]  size          Buffer size
00261      */
00262     virtual void ReadBuffer( uint8_t offset, uint8_t *buffer, uint8_t size ) = 0;
00263 
00264     /*!
00265      * \brief Return firmware version
00266      *
00267      * \retval      firmware      The firmware version
00268      */
00269     virtual uint16_t GetFirmwareVersion( void ) = 0;
00270 };
00271 
00272 #endif // __RADIO_H__