File content as of revision 3:7e3595a9ebe0:

/*
 / _____)             _              | |
( (____  _____ ____ _| |_ _____  ____| |__
 \____ \| ___ |    (_   _) ___ |/ ___)  _ \
 _____) ) ____| | | || |_| ____( (___| | | |
(______/|_____)_|_|_| \__)_____)\____)_| |_|
    (C)2016 Semtech

Description: Handling of the node configuration protocol

License: Revised BSD License, see LICENSE.TXT file include in the project

Maintainer: Miguel Luis, Gregory Cristian and Matthieu Verdy
*/
#ifndef __SX126x_H__
#define __SX126x_H__

#include "radio.h"

/*!
 * \brief Enables/disables driver debug features
 */
#define SX126x_DEBUG                                0



/*!
 * \brief Hardware IO IRQ callback function definition
 */
class SX126x;
typedef void ( SX126x::*DioIrqHandler )( void );

/*!
 * \brief IRQ triggers callback function definition
 */
class SX126xHal;
typedef void ( SX126xHal::*Trigger )( void );

/*!
 * \brief Provides the frequency of the chip running on the radio and the frequency step
 *
 * \remark These defines are used for computing the frequency divider to set the RF frequency
 */
#define XTAL_FREQ                                   32000000
#define FREQ_STEP                                   ( ( double )( XTAL_FREQ / pow( 2.0, 25.0 ) ) )

/*!
 * \brief Compensation delay for SetAutoTx/Rx functions in 15.625 microseconds
 */
#define AUTO_RX_TX_OFFSET                           2

/*!
 * \brief LFSR initial value to compute IBM type CRC
 */
#define CRC_IBM_SEED                                0xFFFF

/*!
 * \brief LFSR initial value to compute CCIT type CRC
 */
#define CRC_CCITT_SEED                              0x1D0F

/*!
 * \brief Polynomial used to compute IBM CRC
 */
#define CRC_POLYNOMIAL_IBM                          0x8005

/*!
 * \brief Polynomial used to compute CCIT CRC
 */
#define CRC_POLYNOMIAL_CCITT                        0x1021

/*!
 * \brief The address of the register holding the first byte defining the CRC seed
 *
 */
#define REG_LR_CRCSEEDBASEADDR                      0x06B9

/*!
 * \brief The address of the register holding the first byte defining the CRC polynomial
 *
 */
#define REG_LR_CRCPOLYBASEADDR                      0x06BB

/*!
 * \brief The address of the register holding the first byte defining the whitening seed
 */
#define REG_LR_WHITSEEDBASEADDR                     0x06B6

/*!
 * \brief The address of the instruction RAM and its size
 */
#define IRAM_START_ADDRESS                          0x8000
#define IRAM_SIZE                                   0x6000

/*!
 * \brief The addresses of the registers holding SyncWords values
 */
#define REG_LR_SYNCWORDBASEADDRESS                  0x06BD


/*!
 * \brief Represents the states of the radio
 */
typedef enum RadioState
{
    RF_IDLE                                 = 0,            //!< The radio is idle
    RF_RX_RUNNING,                                          //!< The radio is in reception state
    RF_TX_RUNNING,                                          //!< The radio is in transmission state
    RF_CAD,                                                 //!< The radio is doing channel activity detection
} RadioStates_t;

/*!
 * \brief Represents the operating mode the radio is actually running
 */
enum RadioOperatingModes_t
{
    MODE_SLEEP                              = 0,            //! The radio is in sleep mode
    MODE_STDBY_RC,                                          //! The radio is in standby mode with RC oscillator
    MODE_STDBY_XOSC,                                        //! The radio is in standby mode with XOSC oscillator
    MODE_FS,                                                //! The radio is in frequency synthesis mode
    MODE_TX,                                                //! The radio is in transmit mode
    MODE_RX,                                                //! The radio is in receive mode
    MODE_CAD                                                //! The radio is in channel activity detection mode
};

/*!
 * \brief Declares the oscillator in use while in standby mode
 *
 * Using the STDBY_RC standby mode allow to reduce the energy consumption
 * STDBY_XOSC should be used for time critical applications
 */
enum RadioStandbyModes_t
{
    STDBY_RC                                = 0,
    STDBY_XOSC                              = 1,
};
/*!
 * \brief Declares the power regulation used to power the device
 *
 * This command allows the user to specify if DC-DC or LDO is used for power regulation.
 * Using only LDO implies that the Rx or Tx current is doubled
 */
enum RadioRegulatorMode_t
{
    USE_LDO                               = 0x00, // default
    USE_DCDC                              = 0x01,
};

/*!
 * \brief Represents the possible packet type (i.e. modem) used
 */
enum RadioPacketType_t
{
    PACKET_TYPE_GFSK                        = 0,
    PACKET_TYPE_LORA                        = 1,
    PACKET_TYPE_RESERVED                    = 0x0F,
};

/*!
 * \brief Represents the ramping time for power amplifier
 */
enum RadioRampTimes_t
{
    RAMP_10_US                              = 0x00,
    RAMP_20_US                              = 0x01,
    RAMP_40_US                              = 0x02,
    RAMP_80_US                              = 0x03,
    RAMP_200_US                             = 0x04,
    RAMP_800_US                             = 0x05,
    RAMP_1700_US                            = 0x06,
    RAMP_3400_US                            = 0x07,
};

/*!
 * \brief Represents the number of symbols to be used for channel activity detection operation
 */
enum RadioLoRaCadSymbols_t
{
    LORA_CAD_01_SYMBOL                      = 0x00,
    LORA_CAD_02_SYMBOL                      = 0x01,
    LORA_CAD_04_SYMBOL                      = 0x02,
    LORA_CAD_08_SYMBOL                      = 0x03,
    LORA_CAD_16_SYMBOL                      = 0x04,
};






/*!
 * \brief Represents the modulation shaping parameter
 */
enum RadioModShapings_t
{
    MOD_SHAPING_G_BT_03                     = 0x08,
    MOD_SHAPING_G_BT_05                     = 0x09,
    MOD_SHAPING_G_BT_07                     = 0x0A,
    MOD_SHAPING_G_BT_1                      = 0x0B,
    
    MOD_SHAPING_G_BT_03_D                   = 0x0C,
    MOD_SHAPING_G_BT_05_D                   = 0x0D,
    MOD_SHAPING_G_BT_07_D                   = 0x0E,
    MOD_SHAPING_G_BT_1_D                    = 0x0F,
    
    MOD_SHAPING_RC_BT_03                    = 0x10,
    MOD_SHAPING_RC_BT_05                    = 0x11,
    MOD_SHAPING_RC_BT_07                    = 0x12,
    MOD_SHAPING_RC_BT_1                     = 0x13,
    
    MOD_SHAPING_RC_BT_03_D                  = 0x14,
    MOD_SHAPING_RC_BT_05_D                  = 0x15,
    MOD_SHAPING_RC_BT_07_D                  = 0x16,
    MOD_SHAPING_RC_BT_1_D                   = 0x17,
    
    MOD_SHAPING_RRC_BT_03                   = 0x18,
    MOD_SHAPING_RRC_BT_05                   = 0x19,
    MOD_SHAPING_RRC_BT_07                   = 0x1A,
    MOD_SHAPING_RRC_BT_1                    = 0x1B,
    
    MOD_SHAPING_RRC_BT_03_D                 = 0x1C,
    MOD_SHAPING_RRC_BT_05_D                 = 0x1D,
    MOD_SHAPING_RRC_BT_07_D                 = 0x1E,
    MOD_SHAPING_RRC_BT_1_D                  = 0x1F,
};

/*!
 * \brief Represents the modulation shaping parameter
 */
enum RadioRxBandwidth_t
{
    RX_BW_4800                              = 0x1F,
    RX_BW_5800                              = 0x17,
    RX_BW_7300                              = 0x0F,
    RX_BW_9700                              = 0x1E,
    RX_BW_11700                             = 0x16,
    RX_BW_14600                             = 0x0E,
    RX_BW_19500                             = 0x1D,
    RX_BW_23400                             = 0x15,
    RX_BW_29300                             = 0x0D,
    RX_BW_39000                             = 0x1C,
    RX_BW_46900                             = 0x14,
    RX_BW_58600                             = 0x0C,
    RX_BW_78200                             = 0x1B,
    RX_BW_93800                             = 0x13,
    RX_BW_117300                            = 0x0B,
    RX_BW_156200                            = 0x1A,
    RX_BW_187200                            = 0x12,
    RX_BW_234300                            = 0x0A,
    RX_BW_312000                            = 0x18,
    RX_BW_373600                            = 0x11,
    RX_BW_467000                            = 0x1F,
    RX_BW_619300                            = 0x18,
    RX_BW_742400                            = 0x10,
    RX_BW_929000                            = 0x08,
};

/*!
 * \brief Represents the possible spreading factor values in LoRa packet types
 */
enum RadioLoRaSpreadingFactors_t
{
    LORA_SF5                                = 0x05,
    LORA_SF6                                = 0x06,
    LORA_SF7                                = 0x07,
    LORA_SF8                                = 0x08,
    LORA_SF9                                = 0x09,
    LORA_SF10                               = 0x0A,
    LORA_SF11                               = 0x0B,
    LORA_SF12                               = 0x0C,
};

/*!
 * \brief Represents the bandwidth values for LoRa packet type
 */
enum RadioLoRaBandwidths_t
{
    LORA_BW_500                             = 6,
    LORA_BW_250                             = 5,
    LORA_BW_125                             = 4,
    LORA_BW_062                             = 3,
    LORA_BW_041                             = 10,
    LORA_BW_031                             = 2,
    LORA_BW_020                             = 9,
    LORA_BW_015                             = 1,
    LORA_BW_010                             = 8,
    LORA_BW_007                             = 0,  
};

/*!
 * \brief Represents the coding rate values for LoRa packet type
 */
enum RadioLoRaCodingRates_t
{
    LORA_CR_4_5                             = 0x01,
    LORA_CR_4_6                             = 0x02,
    LORA_CR_4_7                             = 0x03,
    LORA_CR_4_8                             = 0x04,
    LORA_CR_LI_4_5                          = 0x05,
    LORA_CR_LI_4_6                          = 0x06,
    LORA_CR_LI_4_7                          = 0x07,
};

/*!
 * \brief Represents the preamble length values
 */
enum RadioPreambleLengths_t
{
    RADIO_PREAMBLE_LENGTH_04_BITS           = 0x00,         //!< Preamble length: 04 bits
    RADIO_PREAMBLE_LENGTH_08_BITS           = 0x01,         //!< Preamble length: 08 bits
    RADIO_PREAMBLE_LENGTH_12_BITS           = 0x02,         //!< Preamble length: 12 bits
    RADIO_PREAMBLE_LENGTH_16_BITS           = 0x03,         //!< Preamble length: 16 bits
    RADIO_PREAMBLE_LENGTH_20_BITS           = 0x04,         //!< Preamble length: 20 bits
    RADIO_PREAMBLE_LENGTH_24_BITS           = 0x05,         //!< Preamble length: 24 bits
    RADIO_PREAMBLE_LENGTH_28_BITS           = 0x06,         //!< Preamble length: 28 bits
    RADIO_PREAMBLE_LENGTH_32_BITS           = 0x07,         //!< Preamble length: 32 bits
};

/*!
 * \brief Represents the preamble length used to detect the packet on Rx side
 */
enum RadioPreambleDetection_t
{
    RADIO_PREAMBLE_DETECTOR_OFF             = 0x00,         //!< Preamble detection length off
    RADIO_PREAMBLE_DETECTOR_08_BITS         = 0x04,         //!< Preamble detection length 8 bits
    RADIO_PREAMBLE_DETECTOR_12_BITS         = 0x05,         //!< Preamble detection length 12 bits
    RADIO_PREAMBLE_DETECTOR_16_BITS         = 0x06,         //!< Preamble detection length 16 bits
    RADIO_PREAMBLE_DETECTOR_20_BITS         = 0x07,         //!< Preamble detection length 20 bits
};

/*!
 * \brief The length of sync words 
 */
enum RadioSyncWordLengths_t
{
    RADIO_SYNCWORD_LENGTH_1_BYTE            = 0x00,         //!< Sync word length: 1 byte
    RADIO_SYNCWORD_LENGTH_2_BYTE            = 0x01,         //!< Sync word length: 2 bytes
    RADIO_SYNCWORD_LENGTH_3_BYTE            = 0x02,         //!< Sync word length: 3 bytes
    RADIO_SYNCWORD_LENGTH_4_BYTE            = 0x03,         //!< Sync word length: 4 bytes
    RADIO_SYNCWORD_LENGTH_5_BYTE            = 0x04,         //!< Sync word length: 5 bytes
    RADIO_SYNCWORD_LENGTH_6_BYTE            = 0x05,         //!< Sync word length: 6 bytes
    RADIO_SYNCWORD_LENGTH_7_BYTE            = 0x06,         //!< Sync word length: 7 bytes
    RADIO_SYNCWORD_LENGTH_8_BYTE            = 0x07,         //!< Sync word length: 8 bytes
};

/*!
 * \brief Represents the possible combinations of SyncWord correlators activated
 */
enum RadioAddressComp_t
{
    RADIO_ADDRESSCOMP_FILT_OFF              = 0x00,         //!< No correlator turned on, i.e. do not search for SyncWord
    RADIO_ADDRESSCOMP_FILT_NODE             = 0x01,
    RADIO_ADDRESSCOMP_FILT_NODE_BROAD       = 0x02,

};

/*!
 *  \brief Radio packet length mode
 */
enum RadioPacketLengthModes_t
{
    RADIO_PACKET_FIXED_LENGTH               = 0x00,         //!< The packet is known on both sides, no header included in the packet
    RADIO_PACKET_VARIABLE_LENGTH            = 0x01,         //!< The packet is on variable size, header included
};

/*!
 * \brief Represents the CRC length
 */
enum RadioCrcTypes_t
{
    RADIO_CRC_OFF                           = 0x01,         //!< No CRC in use
    RADIO_CRC_1_BYTES                       = 0x00,
    RADIO_CRC_2_BYTES                       = 0x02,
    RADIO_CRC_1_BYTES_INV                   = 0x04,
    RADIO_CRC_2_BYTES_INV                   = 0x06,
};

/*!
 * \brief Radio whitening mode activated or deactivated
 */
enum RadioDcFree_t
{
    RADIO_DC_FREE_OFF                       = 0x00,
    RADIO_DC_FREEMANCHESTER                 = 0x02,
    RADIO_DC_FREEWHITENING                  = 0x01,
};

/*!
 * \brief Holds the lengths mode of a LoRa packet type
 */
enum RadioLoRaPacketLengthsMode_t
{
    LORA_PACKET_VARIABLE_LENGTH             = 0x00,         //!< The packet is on variable size, header included
    LORA_PACKET_FIXED_LENGTH                = 0x01,         //!< The packet is known on both sides, no header included in the packet
    LORA_PACKET_EXPLICIT                    = LORA_PACKET_VARIABLE_LENGTH,
    LORA_PACKET_IMPLICIT                    = LORA_PACKET_FIXED_LENGTH,
};

/*!
 * \brief Represents the CRC mode for LoRa packet type
 */
enum RadioLoRaCrcModes_t
{
    LORA_CRC_ON                             = 0x01,         //!< CRC activated
    LORA_CRC_OFF                            = 0x00,         //!< CRC not used
};

/*!
 * \brief Represents the IQ mode for LoRa packet type
 */
enum RadioLoRaIQModes_t
{
    LORA_IQ_NORMAL                          = 0x00,
    LORA_IQ_INVERTED                        = 0x01,
};

/*!
 * \brief Represents the interruption masks available for the radio
 *
 * \remark Note that not all these interruptions are available for all packet types
 */
enum RadioIrqMasks_t
{
    IRQ_RADIO_NONE                          = 0x0000,
    IRQ_TX_DONE                             = 0x0001,
    IRQ_RX_DONE                             = 0x0002,
    IRQ_PREAMBLE_DETECTED                   = 0x0004,
    IRQ_SYNCWORD_VALID                      = 0x0008,
    IRQ_HEADER_VALID                        = 0x0010,
    IRQ_HEADER_ERROR                        = 0x0020,      
    IRQ_CRC_ERROR                           = 0x0040,
    IRQ_CAD_DONE                            = 0x0080,
    IRQ_CAD_ACTIVITY_DETECTED               = 0x0100,
    IRQ_RX_TX_TIMEOUT                       = 0x0200,
    IRQ_RANGING_SLAVE_REQUEST_VALID         = 0x0400,
    IRQ_RANGING_SLAVE_REQUEST_DISCARDED     = 0x0800,
    IRQ_RANGING_SLAVE_RESPONSE_DONE         = 0x1000,
    IRQ_RANGING_MASTER_RESULT_VALID         = 0x2000,
    IRQ_RANGING_MASTER_RESULT_TIMEOUT       = 0x4000,
     
    IRQ_RADIO_ALL                           = 0xFFFF,
};




/*!
 * \brief Represents all possible opcode understood by the radio
 */
enum RadioCommands_t
{
    RADIO_GET_STATUS                        = 0xC0,
    RADIO_WRITE_REGISTER                    = 0x0D,
    RADIO_READ_REGISTER                     = 0x1D, 
    RADIO_WRITE_BUFFER                      = 0x0E,
    RADIO_READ_BUFFER                       = 0x1E,  
    RADIO_SET_SLEEP                         = 0x84,
    RADIO_SET_STANDBY                       = 0x80,
    RADIO_SET_FS                            = 0xC1,
    RADIO_SET_TX                            = 0x83,
    RADIO_SET_RX                            = 0x82,
    RADIO_SET_RXDUTYCYCLE                   = 0x94,
    RADIO_SET_CAD                           = 0xC5,
    RADIO_SET_AUTOTXRX                      = 0x87,  
    RADIO_SET_TXCONTINUOUSWAVE              = 0xD1,
    RADIO_SET_TXCONTINUOUSPREAMBLE          = 0xD2,
    RADIO_SET_PACKETTYPE                    = 0x8A,
    RADIO_GET_PACKETTYPE                    = 0x11,
    RADIO_SET_RFFREQUENCY                   = 0x86,
    RADIO_SET_TXPARAMS                      = 0x8E,
    RADIO_SET_PA_OPT                        = 0x95,
    RADIO_SET_CADPARAMS                     = 0x88,
    RADIO_SET_BUFFERBASEADDRESS             = 0x8F,
    RADIO_SET_MODULATIONPARAMS              = 0x8B,
    RADIO_SET_PACKETPARAMS                  = 0x8C,
    RADIO_GET_RXBUFFERSTATUS                = 0x13,
    RADIO_GET_PACKETSTATUS                  = 0x14,
    RADIO_GET_RSSIINST                      = 0x15,
    RADIO_GET_STATS                         = 0x10,
    RADIO_RESET_STATS                       = 0x00,         
    RADIO_CFG_DIOIRQ                        = 0x08,   
    RADIO_GET_IRQSTATUS                     = 0x12,
    RADIO_CLR_IRQSTATUS                     = 0x02,
    RADIO_CALIBRATE                         = 0x89,
    RADIO_SET_REGULATORMODE                 = 0x96,
    RADIO_SET_PRAMSWAPCMD                   = 0x8D,
    RADIO_GET_ERROR                         = 0x17,
    RADIO_SET_LONGPREAMBLE                  = 0x90,
    RADIO_SET_TXFALLBACKMODE                = 0x93,
};

/*!
* \brief RX_TX_CONTINUOUS and RX_TX_SINGLE are two particular values for TickTime.
* The former keep the radio in Rx or Tx mode, even after successfull reception
* or transmission. It should never generate Timeout interrupt.
* The later let the radio enought time to make one reception or transmission.
* No Timeout interrupt is generated, and the radio fall in StandBy mode after
* reception or transmission.
*/
#define RX_TX_CONTINUOUS ( TickTime_t ){ RADIO_TICK_SIZE_0015_US, 0xFFFF }
#define RX_TX_SINGLE     ( TickTime_t ){ RADIO_TICK_SIZE_0015_US, 0 }

/*!
 * \brief The type describing the modulation parameters for every packet types
 */
typedef struct
{
    RadioPacketType_t                    PacketType;        //!< Packet to which the modulation parameters are referring to.
    union
    {
        uint8_t Buffer[8];
        struct
        {
            uint32_t                     BitRate;
            uint32_t                     Fdev;
            RadioModShapings_t           PulseShape:8;
            uint8_t                      BW;
        }Gfsk;
        struct
        {
            RadioLoRaSpreadingFactors_t  SpreadingFactor;   //!< Spreading Factor for the LoRa modulation
            RadioLoRaBandwidths_t        Bandwidth;         //!< Bandwidth for the LoRa modulation
            RadioLoRaCodingRates_t       CodingRate;        //!< Coding rate for the LoRa modulation
        }LoRa;
    }Params;                                                //!< Holds the modulation parameters structure
}ModulationParams_t;

/*!
 * \brief The type describing the packet parameters for every packet types
 */
typedef struct
{
    RadioPacketType_t                    PacketType;        //!< Packet to which the packet parameters are referring to.
    union
    {
        uint8_t Buffer[8];
        
        /*!
         * \brief Holds the GFSK packet parameters
         */
        struct
        {
            uint8_t PreambleTxLength;       //!< The preamble tx length for GFSK packet type
            uint8_t PreambleDetectLength;   //!< The preamble rx length for GFSK packet type
            
            RadioSyncWordLengths_t       SyncWordLength;    //!< The synchronization word length for GFSK packet type
            RadioAddressComp_t           AddrComp;          
            RadioPacketLengthModes_t     HeaderType;        //!< If the header is explicit, it will be transmitted in the GFSK packet. If the header is implicit, it will not be transmitted
            uint8_t                      PayloadLength;     //!< Size of the payload in the GFSK packet
            RadioCrcTypes_t              CrcLength;         //!< Size of the CRC block in the GFSK packet
            RadioDcFree_t                DcFree;            
        }Gfsk;
        /*!
         * \brief Holds the LoRa packet parameters
         */
        struct
        {
            uint8_t                      PreambleLength;    //!< The preamble length is the number of LoRa symbols in the preamble. To set it, use the following formula @code Number of symbols = PreambleLength[3:0] * ( 2^PreambleLength[7:4] ) @endcode
            RadioLoRaPacketLengthsMode_t HeaderType;        //!< If the header is explicit, it will be transmitted in the LoRa packet. If the header is implicit, it will not be transmitted
            uint8_t                      PayloadLength;     //!< Size of the payload in the LoRa packet
            RadioLoRaCrcModes_t          CrcMode;           //!< Size of CRC block in LoRa packet
            RadioLoRaIQModes_t           InvertIQ;          //!< Allows to swap IQ for LoRa packet
        }LoRa;

    }Params;                                                //!< Holds the packet parameters structure
}PacketParams_t;

/*!
 * \brief Represents the packet status for every packet type
 */
typedef struct
{
    RadioPacketType_t                    packetType;        //!< Packet to which the packet status are referring to.
    union
    {
        struct
        {
            uint8_t RxStatus;
            int8_t RssiAvg;                                //!< The averaged RSSI
            int8_t RssiSync;                               //!< The RSSI measured on last packet
        }Gfsk;
        struct
        {
            int8_t RssiPkt;                                //!< The RSSI of the last packet
            int8_t SnrPkt;                                 //!< The SNR of the last packet
            int8_t SignalRssiPkt;
        }LoRa;

    };
}PacketStatus_t;

/*!
 * \brief Represents the Rx internal counters values when GFSK or LoRa packet type is used
 */
typedef struct
{
    RadioPacketType_t                    packetType;        //!< Packet to which the packet status are referring to.
    uint16_t NbPktReceived;
    uint16_t NbPktCrcOk;
    uint16_t NbPktLengthError;
}RxCounter_t;

/*!
 * \brief Represents a calibration configuration
 */
typedef union
{
    uint8_t Value;
    struct
    {
        uint8_t Reserved       : 1;
        uint8_t ImgEnable      : 1;
        uint8_t ADCBulkPEnable : 1;                             //!< Calibrate ADC bulkP
        uint8_t ADCBulkNEnable : 1;                             //!< Calibrate ADC bulkN
        uint8_t ADCPulseEnable : 1;                             //!< Calibrate ADC Pulse
        uint8_t PLLEnable      : 1;                             //!< Calibrate PLL
        uint8_t RC13MEnable    : 1;                             //!< Calibrate RC13M clock
        uint8_t RC64KEnable    : 1;                             //!< Calibrate RC64K clock  
    } Fields;
}CalibrationParams_t;

/*!
 * \brief Represents a sleep mode configuration
 */
typedef union
{
    uint8_t Value;
    struct
    {
        uint8_t WakeUpRTC               : 1;                    //!< Get out of sleep mode if wakeup signal received from RTC
        uint8_t Reset                   : 1;
        uint8_t WarmStart               : 1;
        uint8_t Reserved                : 5;
    } Fields;

}SleepParams_t;


/*!
 * \brief Represents the SX126x and its features
 *
 * It implements the commands the SX126x can understands
 */
class SX126x : public Radio
{
public:
    /*!
     * \brief Instantiates a SX126x object and provides API functions to communicates with the radio
     *
     * \param [in]  txDone                Pointer to a function run on successful transmission
     * \param [in]  rxDone                Pointer to a function run on successful reception
     * \param [in]  rxPblSyncWordHeader   Pointer to a function run on successful SyncWord, pbl or header reception
     * \param [in]  rxtxTimeout           Pointer to a function run on transmission/reception timeout
     * \param [in]  rxError               Pointer to a function run on reception error
     * \param [in]  rangingDone           Pointer to a function run on ranging terminated
     * \param [in]  cadDone               Pointer to a function run on channel activity detected
     *
     */
    SX126x( void ( *txDone )( ), void ( *rxDone )( ), void ( *rxPblSyncWordHeader )(IrqPblSyncHeaderCode_t val ),
            void ( *rxTxTimeout )( IrqTimeoutCode_t timeoutCode ), void ( *rxError )( IrqErrorCode_t errorCode ),
            void ( *cadDone )( bool channelActivityDetected ),  void ( *onDioIrq )( ) ): Radio( txDone, rxDone, rxPblSyncWordHeader, rxTxTimeout, rxError, cadDone )
    {

        this->dioIrq = &SX126x::OnDioIrq;
      
        this->onCustomDioIrq = onDioIrq;
  
        this->PacketType = PACKET_TYPE_RESERVED;
    }

    virtual ~SX126x( )
    {
    }

    /*!
     * \brief Holds the internal operating mode of the radio
     */
    RadioOperatingModes_t OperatingMode;
    
    uint16_t LastIrqs;

private:


    /*!
     * \brief Stores the current packet type set in the radio
     */
    RadioPacketType_t PacketType;


    /*!
     * \brief Hardware DIO IRQ functions
     */
    DioIrqHandler dioIrq;

protected:

    void ( *onCustomDioIrq )( );

    /*!
     * \brief Sets a function to be triggered on radio interrupt
     *
     * \param [in]  irqHandler    A pointer to a function to be run on interrupt
     *                            from the radio
     */
    virtual void IoIrqInit( DioIrqHandler irqHandler ) = 0;

public:
    /*!
     * \brief Initializes the radio driver
     */
    void Init( void );

    /*!
     * \brief Initializes the radio registers to the recommended default values
     */
    void SetRegistersDefault( void );

    /*!
     * \brief Returns the current device firmware version
     *
     * \retval      version       Firmware version
     */
    virtual uint16_t GetFirmwareVersion( void );

    /*!
     * \brief Resets the radio
     */
    virtual void Reset( void ) = 0;

    /*!
     * \brief Wake-ups the radio from Sleep mode
     */
    virtual void Wakeup( void ) = 0;

    /*!
     * \brief Writes the given command to the radio
     *
     * \param [in]  opcode        Command opcode
     * \param [in]  buffer        Command parameters byte array
     * \param [in]  size          Command parameters byte array size
     */
    virtual void WriteCommand( RadioCommands_t opcode, uint8_t *buffer, uint16_t size ) = 0;

    /*!
     * \brief Reads the given command from the radio
     *
     * \param [in]  opcode        Command opcode
     * \param [in]  buffer        Command parameters byte array
     * \param [in]  size          Command parameters byte array size
     */
    virtual void ReadCommand( RadioCommands_t opcode, uint8_t *buffer, uint16_t size ) = 0;

    /*!
     * \brief Writes multiple radio registers starting at address
     *
     * \param [in]  address       First Radio register address
     * \param [in]  buffer        Buffer containing the new register's values
     * \param [in]  size          Number of registers to be written
     */
    virtual void WriteRegister( uint16_t address, uint8_t *buffer, uint16_t size ) = 0;

    /*!
     * \brief Writes the radio register at the specified address
     *
     * \param [in]  address       Register address
     * \param [in]  value         New register value
     */
    virtual void WriteRegister( uint16_t address, uint8_t value ) = 0;

    /*!
     * \brief Reads multiple radio registers starting at address
     *
     * \param [in]  address       First Radio register address
     * \param [out] buffer        Buffer where to copy the registers data
     * \param [in]  size          Number of registers to be read
     */
    virtual void ReadRegister( uint16_t address, uint8_t *buffer, uint16_t size ) = 0;

    /*!
     * \brief Reads the radio register at the specified address
     *
     * \param [in]  address       Register address
     *
     * \retval      data          Register value
     */
    virtual uint8_t ReadRegister( uint16_t address ) = 0;

    /*!
     * \brief Writes Radio Data Buffer with buffer of size starting at offset.
     *
     * \param [in]  offset        Offset where to start writing
     * \param [in]  buffer        Buffer pointer
     * \param [in]  size          Buffer size
     */
    virtual void WriteBuffer( uint8_t offset, uint8_t *buffer, uint8_t size ) = 0;

    /*!
     * \brief Reads Radio Data Buffer at offset to buffer of size
     *
     * \param [in]  offset        Offset where to start reading
     * \param [out] buffer        Buffer pointer
     * \param [in]  size          Buffer size
     */
    virtual void ReadBuffer( uint8_t offset, uint8_t *buffer, uint8_t size ) = 0;

    /*!
     * \brief Gets the current status of the radio DIOs
     *
     * \retval      status        [Bit #3: DIO3, Bit #2: DIO2,
     *                             Bit #1: DIO1, Bit #0: DIO0]
     */
    virtual uint8_t GetDioStatus( void ) = 0;

    /*!
     * \brief Gets the current radio status
     *
     * \retval      status        Radio status
     */
    virtual RadioStatus_t GetStatus( void );

    /*!
     * \brief Sets the radio in sleep mode
     *
     * \param [in]  sleepConfig   The sleep configuration describing data
     *                            retention and RTC wake-up
     */
    void SetSleep( SleepParams_t sleepConfig );

    /*!
     * \brief Sets the radio in configuration mode
     *
     * \param [in]  mode          The standby mode to put the radio into
     */
    void SetStandby( RadioStandbyModes_t mode );

    /*!
     * \brief Sets the radio in FS mode
     */
    void SetFs( void );

    /*!
     * \brief Sets the radio in transmission mode
     *
     * \param [in]  timeout       Structure describing the transmission timeout value
     */
    void SetTx( uint32_t timeout );

    /*!
     * \brief Sets the radio in reception mode
     *
     * \param [in]  timeout       Structure describing the reception timeout value
     */
    void SetRx( uint32_t timeout );

    /*!
     * \brief Sets the Rx duty cycle management parameters
     *
     * \param [in]  rxTime        Structure describing reception timeout value
     * \param [in]  sleepTime     Structure describing sleep timeout value
     */
    void SetRxDutyCycle( uint32_t rxTime, uint32_t sleepTime );

    /*!
     * \brief Sets the radio in CAD mode
     */
    void SetCad( void );

    /*!
     * \brief Sets the radio in continuous wave transmission mode
     */
    void SetTxContinuousWave( void );

    /*!
     * \brief Sets the radio in continuous preamble transmission mode
     */
    void SetTxContinuousPreamble( void );

    /*!
     * \brief Sets the radio for the given protocol
     *
     * \param [in]  packetType    [PACKET_TYPE_GFSK, PACKET_TYPE_LORA]
     */
    void SetPacketType( RadioPacketType_t packetType );

    /*!
     * \brief Gets the current radio protocol
     *
     * \retval      packetType    [PACKET_TYPE_GFSK, PACKET_TYPE_LORA]
     */
    RadioPacketType_t GetPacketType( void );

    /*!
     * \brief Sets the RF frequency
     *
     * \param [in]  frequency     RF frequency [Hz]
     */
    void SetRfFrequency( uint32_t frequency );

    /*!
     * \brief Sets the transmission parameters
     *
     * \param [in]  power         RF output power [-18..13] dBm
     * \param [in]  rampTime      Transmission ramp up time
     */
    void SetTxParams( int8_t power, RadioRampTimes_t rampTime );

    /*!
     * \brief Sets the CAD parameters
     *
     * \param [in]  cadSymbolNum  The number of symbol to use for channel activity
     *                            detection operations [LORA_CAD_01_SYMBOL, LORA_CAD_02_SYMBOL,
     *                            LORA_CAD_04_SYMBOL, LORA_CAD_08_SYMBOL, LORA_CAD_16_SYMBOL]
     */
    void SetCadConfig( RadioLoRaCadSymbols_t cadSymbolNum , uint8_t cadExitMode, uint32_t cadRxTxTimeout);

    /*!
     * \brief Sets the data buffer base address for transmission and reception
     *
     * \param [in]  txBaseAddress Transmission base address
     * \param [in]  rxBaseAddress Reception base address
     */
    void SetBufferBaseAddresses( uint8_t txBaseAddress, uint8_t rxBaseAddress );

    /*!
     * \brief Set the modulation parameters
     *
     * \param [in]  modParams     A structure describing the modulation parameters
     */
    void SetModulationParams( ModulationParams_t *modParams );

    /*!
     * \brief Sets the packet parameters
     *
     * \param [in]  packetParams  A structure describing the packet parameters
     */
    void SetPacketParams( PacketParams_t *packetParams );

    /*!
     * \brief Gets the last received packet buffer status
     *
     * \param [out] payloadLength Last received packet payload length
     * \param [out] rxStartBuffer Last received packet buffer address pointer
     */
    void GetRxBufferStatus( uint8_t *payloadLength, uint8_t *rxStartBuffer );

    /*!
     * \brief Gets the last received packet payload length
     *
     * \param [out] pktStatus     A structure of packet status
     */
    void GetPacketStatus( PacketStatus_t *pktStatus );

    /*!
     * \brief Returns value of internal Rx counters when GFSK packet type is used
     *
     * \param [out] rxCounter     A structure holding Rx internal counters values
     *
     * \remark The Rx internal counters are only available for GFSK and LoRa packet types.
     */
    void GetStats( RxCounter_t *rxCounter );

    void ResetStats();

    uint8_t GetError();

    /*!
     * \brief Returns the instantaneous RSSI value for the last packet received
     *
     * \retval      rssiInst      Instantaneous RSSI
     */
    int8_t GetRssiInst( void );

    /*!
     * \brief   Sets the IRQ mask and DIO masks
     *
     * \param [in]  irqMask       General IRQ mask
     * \param [in]  dio1Mask      DIO1 mask
     * \param [in]  dio2Mask      DIO2 mask
     * \param [in]  dio3Mask      DIO3 mask
     */
    void SetDioIrqParams( uint16_t irqMask, uint16_t dio1Mask, uint16_t dio2Mask, uint16_t dio3Mask );

    /*!
     * \brief Returns the current IRQ status
     *
     * \retval      irqStatus     IRQ status
     */
    uint16_t GetIrqStatus( void );

    /*!
     * \brief Clears the IRQs
     *
     * \param [in]  irq           IRQ(s) to be cleared
     */
    void ClearIrqStatus( uint16_t irq );

    /*!
     * \brief Calibrates the given radio block
     *
     * \param [in]  calibParam    The description of blocks to be calibrated
     */
    void Calibrate( CalibrationParams_t calibParam );

    /*!
     * \brief Sets the power regulators operating mode
     *
     * \param [in]  mode          [0: LDO, 1:DC_DC]
     */
    void SetRegulatorMode( uint8_t mode );


    /*!
     * \brief Sets the chip to automatically receive a packet after the end of a packet transmission
     *
     * \remark The offset is automatically compensated inside the function
     *
     * \param [in]  time          The delay in 15.625us after which a Rx or Tx is done
     */
    void SetAutoTxRx( uint32_t time, uint8_t intMode, uint32_t timeout );

    /*!
     * \brief Enables or disables long preamble detection mode
     *
     * \param [in]  enable        [0: Disable, 1: Enable]
     */
    void SetLongPreamble( uint8_t enable );

    /*!
     * \brief Saves the payload to be send in the radio buffer
     *
     * \param [in]  payload       A pointer to the payload
     * \param [in]  size          The size of the payload
     */
    void SetPayload( uint8_t *payload, uint8_t size );

    /*!
     * \brief Reads the payload received. If the received payload is longer
     * than maxSize, then the method returns 1 and do not set size and payload.
     *
     * \param [out] payload       A pointer to a buffer into which the payload will be copied
     * \param [out] size          A pointer to the size of the payload received
     * \param [in]  maxSize       The maximal size allowed to copy into the buffer
     */
    uint8_t GetPayload( uint8_t *buffer, uint8_t *size, uint8_t maxSize );

    /*!
     * \brief Sends a payload
     *
     * \param [in]  payload       A pointer to the payload to send
     * \param [in]  size          The size of the payload to send
     * \param [in]  timeout       The timeout for Tx operation
     */
    void SendPayload( uint8_t *payload, uint8_t size, uint32_t timeout );

    /*!
     * \brief Sets the Sync Word given by index used in GFSK
     *
     * \param [in]  syncWord      SyncWord bytes ( 8 bytes )
     *
     * \retval      status        [0: OK, 1: NOK]
     */
    uint8_t SetSyncWord( uint8_t *syncWord );

    /*!
     * \brief Sets the Initial value for the LFSR used for the CRC calculation
     *
     * \param [in]  seed          Initial LFSR value ( 2 bytes )
     *
     */
    void SetCrcSeed( uint16_t seed );

    /*!
     * \brief Sets the seed used for the CRC calculation
     *
     * \param [in]  seed          The seed value
     *
     */
    void SetCrcPolynomial( uint16_t seed );

    /*!
     * \brief Sets the Initial value of the LFSR used for the whitening in GFSK, FloRa and BLE protocols
     *
     * \param [in]  seed          Initial LFSR value
     */
    void SetWhiteningSeed( uint8_t seed );

    /*!
     * \brief DIOs interrupt callback
     *
     * \remark Called to handle all 3 DIOs pins
     */
    void OnDioIrq( void );

    /*!
     * \brief Clears the instruction RAM
     */
    virtual void ClearInstructionRam( void ) = 0;

    /*!
     * \brief Parses 1 HEX file line and writes the content to the instruction memory
     *
     * \param [in]  line          HEX file line string
     *
     * \retval      status        [0: ERROR, 1:OK]
     */
    int8_t ParseHexFileLine( char* line );

    /*!
     * \brief Gets individual fields for the given HEX file line
     *
     * \param [in]  line          HEX file line string
     * \param [out] bytes         Bytes array to be written to the instruction memory
     * \param [out] addr          Instruction memory address where to write the bytes array
     * \param [out] num           Number of bytes in Bytes array
     * \param [out] code          HEX file line type [0: instruction, 1: end of file, 2: begin of file]
     *
     * \retval      status        [0: ERROR, 1:OK]
     */
     int8_t GetHexFileLineFields( char* line, uint8_t *bytes, uint16_t *addr, uint16_t *num, uint8_t *code );
};

#endif // __SX126x_H__