1 /*! 2 * \file sx1272.h 3 * 4 * \brief SX1272 driver implementation 5 * 6 * \copyright Revised BSD License, see section \ref LICENSE. 7 * 8 * \code 9 * ______ _ 10 * / _____) _ | | 11 * ( (____ _____ ____ _| |_ _____ ____| |__ 12 * \____ \| ___ | (_ _) ___ |/ ___) _ \ 13 * _____) ) ____| | | || |_| ____( (___| | | | 14 * (______/|_____)_|_|_| \__)_____)\____)_| |_| 15 * (C)2013-2017 Semtech 16 * 17 * \endcode 18 * 19 * \author Miguel Luis ( Semtech ) 20 * 21 * \author Gregory Cristian ( Semtech ) 22 */ 23 #ifndef __SX1272_H__ 24 #define __SX1272_H__ 25 26 #ifdef __cplusplus 27 extern "C" 28 { 29 #endif 30 31 #include <stdint.h> 32 #include <stdbool.h> 33 #include "gpio.h" 34 #include "spi.h" 35 #include "radio.h" 36 #include "sx1272Regs-Fsk.h" 37 #include "sx1272Regs-LoRa.h" 38 39 /*! 40 * Radio wake-up time from sleep 41 */ 42 #define RADIO_WAKEUP_TIME 1 // [ms] 43 44 /*! 45 * Sync word for Private LoRa networks 46 */ 47 #define LORA_MAC_PRIVATE_SYNCWORD 0x12 48 49 /*! 50 * Sync word for Public LoRa networks 51 */ 52 #define LORA_MAC_PUBLIC_SYNCWORD 0x34 53 54 /*! 55 * Radio FSK modem parameters 56 */ 57 typedef struct 58 { 59 int8_t Power; 60 uint32_t Fdev; 61 uint32_t Bandwidth; 62 uint32_t BandwidthAfc; 63 uint32_t Datarate; 64 uint16_t PreambleLen; 65 bool FixLen; 66 uint8_t PayloadLen; 67 bool CrcOn; 68 bool IqInverted; 69 bool RxContinuous; 70 uint32_t TxTimeout; 71 uint32_t RxSingleTimeout; 72 }RadioFskSettings_t; 73 74 /*! 75 * Radio FSK packet handler state 76 */ 77 typedef struct 78 { 79 uint8_t PreambleDetected; 80 uint8_t SyncWordDetected; 81 int8_t RssiValue; 82 int32_t AfcValue; 83 uint8_t RxGain; 84 uint16_t Size; 85 uint16_t NbBytes; 86 uint8_t FifoThresh; 87 uint8_t ChunkSize; 88 }RadioFskPacketHandler_t; 89 90 /*! 91 * Radio LoRa modem parameters 92 */ 93 typedef struct 94 { 95 int8_t Power; 96 uint32_t Bandwidth; 97 uint32_t Datarate; 98 bool LowDatarateOptimize; 99 uint8_t Coderate; 100 uint16_t PreambleLen; 101 bool FixLen; 102 uint8_t PayloadLen; 103 bool CrcOn; 104 bool FreqHopOn; 105 uint8_t HopPeriod; 106 bool IqInverted; 107 bool RxContinuous; 108 uint32_t TxTimeout; 109 bool PublicNetwork; 110 }RadioLoRaSettings_t; 111 112 /*! 113 * Radio LoRa packet handler state 114 */ 115 typedef struct 116 { 117 int8_t SnrValue; 118 int16_t RssiValue; 119 uint8_t Size; 120 }RadioLoRaPacketHandler_t; 121 122 /*! 123 * Radio Settings 124 */ 125 typedef struct 126 { 127 RadioState_t State; 128 RadioModems_t Modem; 129 uint32_t Channel; 130 RadioFskSettings_t Fsk; 131 RadioFskPacketHandler_t FskPacketHandler; 132 RadioLoRaSettings_t LoRa; 133 RadioLoRaPacketHandler_t LoRaPacketHandler; 134 }RadioSettings_t; 135 136 /*! 137 * Radio hardware and global parameters 138 */ 139 typedef struct SX1272_s 140 { 141 Gpio_t Reset; 142 Gpio_t DIO0; 143 Gpio_t DIO1; 144 Gpio_t DIO2; 145 Gpio_t DIO3; 146 Gpio_t DIO4; 147 Gpio_t DIO5; 148 Spi_t Spi; 149 RadioSettings_t Settings; 150 }SX1272_t; 151 152 /*! 153 * Hardware IO IRQ callback function definition 154 */ 155 typedef void ( DioIrqHandler )( void* context ); 156 157 /* 158 * SX1272 definitions 159 */ 160 161 /*! 162 * ============================================================================ 163 * Public functions prototypes 164 * ============================================================================ 165 */ 166 167 /*! 168 * \brief Initializes the radio 169 * 170 * \param [IN] events Structure containing the driver callback functions 171 */ 172 void SX1272Init( RadioEvents_t *events ); 173 174 /*! 175 * Return current radio status 176 * 177 * \param status Radio status.[RF_IDLE, RF_RX_RUNNING, RF_TX_RUNNING] 178 */ 179 RadioState_t SX1272GetStatus( void ); 180 181 /*! 182 * \brief Configures the radio with the given modem 183 * 184 * \param [IN] modem Modem to be used [0: FSK, 1: LoRa] 185 */ 186 void SX1272SetModem( RadioModems_t modem ); 187 188 /*! 189 * \brief Sets the channel configuration 190 * 191 * \param [IN] freq Channel RF frequency 192 */ 193 void SX1272SetChannel( uint32_t freq ); 194 195 /*! 196 * \brief Checks if the channel is free for the given time 197 * 198 * \remark The FSK modem is always used for this task as we can select the Rx bandwidth at will. 199 * 200 * \param [IN] freq Channel RF frequency in Hertz 201 * \param [IN] rxBandwidth Rx bandwidth in Hertz 202 * \param [IN] rssiThresh RSSI threshold in dBm 203 * \param [IN] maxCarrierSenseTime Max time in milliseconds while the RSSI is measured 204 * 205 * \retval isFree [true: Channel is free, false: Channel is not free] 206 */ 207 bool SX1272IsChannelFree( uint32_t freq, uint32_t rxBandwidth, int16_t rssiThresh, uint32_t maxCarrierSenseTime ); 208 209 /*! 210 * \brief Generates a 32 bits random value based on the RSSI readings 211 * 212 * \remark This function sets the radio in LoRa modem mode and disables 213 * all interrupts. 214 * After calling this function either SX1272SetRxConfig or 215 * SX1272SetTxConfig functions must be called. 216 * 217 * \retval randomValue 32 bits random value 218 */ 219 uint32_t SX1272Random( void ); 220 221 /*! 222 * \brief Sets the reception parameters 223 * 224 * \param [IN] modem Radio modem to be used [0: FSK, 1: LoRa] 225 * \param [IN] bandwidth Sets the bandwidth 226 * FSK : >= 2600 and <= 250000 Hz 227 * LoRa: [0: 125 kHz, 1: 250 kHz, 228 * 2: 500 kHz, 3: Reserved] 229 * \param [IN] datarate Sets the Datarate 230 * FSK : 600..300000 bits/s 231 * LoRa: [6: 64, 7: 128, 8: 256, 9: 512, 232 * 10: 1024, 11: 2048, 12: 4096 chips] 233 * \param [IN] coderate Sets the coding rate (LoRa only) 234 * FSK : N/A ( set to 0 ) 235 * LoRa: [1: 4/5, 2: 4/6, 3: 4/7, 4: 4/8] 236 * \param [IN] bandwidthAfc Sets the AFC Bandwidth (FSK only) 237 * FSK : >= 2600 and <= 250000 Hz 238 * LoRa: N/A ( set to 0 ) 239 * \param [IN] preambleLen Sets the Preamble length 240 * FSK : Number of bytes 241 * LoRa: Length in symbols (the hardware adds 4 more symbols) 242 * \param [IN] symbTimeout Sets the RxSingle timeout value 243 * FSK : timeout number of bytes 244 * LoRa: timeout in symbols 245 * \param [IN] fixLen Fixed length packets [0: variable, 1: fixed] 246 * \param [IN] payloadLen Sets payload length when fixed length is used 247 * \param [IN] crcOn Enables/Disables the CRC [0: OFF, 1: ON] 248 * \param [IN] freqHopOn Enables disables the intra-packet frequency hopping 249 * FSK : N/A ( set to 0 ) 250 * LoRa: [0: OFF, 1: ON] 251 * \param [IN] hopPeriod Number of symbols between each hop 252 * FSK : N/A ( set to 0 ) 253 * LoRa: Number of symbols 254 * \param [IN] iqInverted Inverts IQ signals (LoRa only) 255 * FSK : N/A ( set to 0 ) 256 * LoRa: [0: not inverted, 1: inverted] 257 * \param [IN] rxContinuous Sets the reception in continuous mode 258 * [false: single mode, true: continuous mode] 259 */ 260 void SX1272SetRxConfig( RadioModems_t modem, uint32_t bandwidth, 261 uint32_t datarate, uint8_t coderate, 262 uint32_t bandwidthAfc, uint16_t preambleLen, 263 uint16_t symbTimeout, bool fixLen, 264 uint8_t payloadLen, 265 bool crcOn, bool freqHopOn, uint8_t hopPeriod, 266 bool iqInverted, bool rxContinuous ); 267 268 /*! 269 * \brief Sets the transmission parameters 270 * 271 * \param [IN] modem Radio modem to be used [0: FSK, 1: LoRa] 272 * \param [IN] power Sets the output power [dBm] 273 * \param [IN] fdev Sets the frequency deviation (FSK only) 274 * FSK : [Hz] 275 * LoRa: 0 276 * \param [IN] bandwidth Sets the bandwidth (LoRa only) 277 * FSK : 0 278 * LoRa: [0: 125 kHz, 1: 250 kHz, 279 * 2: 500 kHz, 3: Reserved] 280 * \param [IN] datarate Sets the Datarate 281 * FSK : 600..300000 bits/s 282 * LoRa: [6: 64, 7: 128, 8: 256, 9: 512, 283 * 10: 1024, 11: 2048, 12: 4096 chips] 284 * \param [IN] coderate Sets the coding rate (LoRa only) 285 * FSK : N/A ( set to 0 ) 286 * LoRa: [1: 4/5, 2: 4/6, 3: 4/7, 4: 4/8] 287 * \param [IN] preambleLen Sets the preamble length 288 * FSK : Number of bytes 289 * LoRa: Length in symbols (the hardware adds 4 more symbols) 290 * \param [IN] fixLen Fixed length packets [0: variable, 1: fixed] 291 * \param [IN] crcOn Enables disables the CRC [0: OFF, 1: ON] 292 * \param [IN] freqHopOn Enables disables the intra-packet frequency hopping 293 * FSK : N/A ( set to 0 ) 294 * LoRa: [0: OFF, 1: ON] 295 * \param [IN] hopPeriod Number of symbols between each hop 296 * FSK : N/A ( set to 0 ) 297 * LoRa: Number of symbols 298 * \param [IN] iqInverted Inverts IQ signals (LoRa only) 299 * FSK : N/A ( set to 0 ) 300 * LoRa: [0: not inverted, 1: inverted] 301 * \param [IN] timeout Transmission timeout [ms] 302 */ 303 void SX1272SetTxConfig( RadioModems_t modem, int8_t power, uint32_t fdev, 304 uint32_t bandwidth, uint32_t datarate, 305 uint8_t coderate, uint16_t preambleLen, 306 bool fixLen, bool crcOn, bool freqHopOn, 307 uint8_t hopPeriod, bool iqInverted, uint32_t timeout ); 308 309 /*! 310 * \brief Computes the packet time on air in ms for the given payload 311 * 312 * \Remark Can only be called once SetRxConfig or SetTxConfig have been called 313 * 314 * \param [IN] modem Radio modem to be used [0: FSK, 1: LoRa] 315 * \param [IN] bandwidth Sets the bandwidth 316 * FSK : >= 2600 and <= 250000 Hz 317 * LoRa: [0: 125 kHz, 1: 250 kHz, 318 * 2: 500 kHz, 3: Reserved] 319 * \param [IN] datarate Sets the Datarate 320 * FSK : 600..300000 bits/s 321 * LoRa: [6: 64, 7: 128, 8: 256, 9: 512, 322 * 10: 1024, 11: 2048, 12: 4096 chips] 323 * \param [IN] coderate Sets the coding rate (LoRa only) 324 * FSK : N/A ( set to 0 ) 325 * LoRa: [1: 4/5, 2: 4/6, 3: 4/7, 4: 4/8] 326 * \param [IN] preambleLen Sets the Preamble length 327 * FSK : Number of bytes 328 * LoRa: Length in symbols (the hardware adds 4 more symbols) 329 * \param [IN] fixLen Fixed length packets [0: variable, 1: fixed] 330 * \param [IN] payloadLen Sets payload length when fixed length is used 331 * \param [IN] crcOn Enables/Disables the CRC [0: OFF, 1: ON] 332 * 333 * \retval airTime Computed airTime (ms) for the given packet payload length 334 */ 335 uint32_t SX1272GetTimeOnAir( RadioModems_t modem, uint32_t bandwidth, 336 uint32_t datarate, uint8_t coderate, 337 uint16_t preambleLen, bool fixLen, uint8_t payloadLen, 338 bool crcOn ); 339 340 /*! 341 * \brief Sends the buffer of size. Prepares the packet to be sent and sets 342 * the radio in transmission 343 * 344 * \param [IN]: buffer Buffer pointer 345 * \param [IN]: size Buffer size 346 */ 347 void SX1272Send( uint8_t *buffer, uint8_t size ); 348 349 /*! 350 * \brief Sets the radio in sleep mode 351 */ 352 void SX1272SetSleep( void ); 353 354 /*! 355 * \brief Sets the radio in standby mode 356 */ 357 void SX1272SetStby( void ); 358 359 /*! 360 * \brief Sets the radio in reception mode for the given time 361 * \param [IN] timeout Reception timeout [ms] [0: continuous, others timeout] 362 */ 363 void SX1272SetRx( uint32_t timeout ); 364 365 /*! 366 * \brief Start a Channel Activity Detection 367 */ 368 void SX1272StartCad( void ); 369 370 /*! 371 * \brief Sets the radio in continuous wave transmission mode 372 * 373 * \param [IN]: freq Channel RF frequency 374 * \param [IN]: power Sets the output power [dBm] 375 * \param [IN]: time Transmission mode timeout [s] 376 */ 377 void SX1272SetTxContinuousWave( uint32_t freq, int8_t power, uint16_t time ); 378 379 /*! 380 * \brief Reads the current RSSI value 381 * 382 * \retval rssiValue Current RSSI value in [dBm] 383 */ 384 int16_t SX1272ReadRssi( RadioModems_t modem ); 385 386 /*! 387 * \brief Writes the radio register at the specified address 388 * 389 * \param [IN]: addr Register address 390 * \param [IN]: data New register value 391 */ 392 void SX1272Write( uint32_t addr, uint8_t data ); 393 394 /*! 395 * \brief Reads the radio register at the specified address 396 * 397 * \param [IN]: addr Register address 398 * \retval data Register value 399 */ 400 uint8_t SX1272Read( uint32_t addr ); 401 402 /*! 403 * \brief Writes multiple radio registers starting at address 404 * 405 * \param [IN] addr First Radio register address 406 * \param [IN] buffer Buffer containing the new register's values 407 * \param [IN] size Number of registers to be written 408 */ 409 void SX1272WriteBuffer( uint32_t addr, uint8_t *buffer, uint8_t size ); 410 411 /*! 412 * \brief Reads multiple radio registers starting at address 413 * 414 * \param [IN] addr First Radio register address 415 * \param [OUT] buffer Buffer where to copy the registers data 416 * \param [IN] size Number of registers to be read 417 */ 418 void SX1272ReadBuffer( uint32_t addr, uint8_t *buffer, uint8_t size ); 419 420 /*! 421 * \brief Sets the maximum payload length. 422 * 423 * \param [IN] modem Radio modem to be used [0: FSK, 1: LoRa] 424 * \param [IN] max Maximum payload length in bytes 425 */ 426 void SX1272SetMaxPayloadLength( RadioModems_t modem, uint8_t max ); 427 428 /*! 429 * \brief Sets the network to public or private. Updates the sync byte. 430 * 431 * \remark Applies to LoRa modem only 432 * 433 * \param [IN] enable if true, it enables a public network 434 */ 435 void SX1272SetPublicNetwork( bool enable ); 436 437 /*! 438 * \brief Gets the time required for the board plus radio to get out of sleep.[ms] 439 * 440 * \retval time Radio plus board wakeup time in ms. 441 */ 442 uint32_t SX1272GetWakeupTime( void ); 443 444 #ifdef __cplusplus 445 } 446 #endif 447 448 #endif // __SX1272_H__ 449
