1 /* 2 ______ _ 3 / _____) _ | | 4 ( (____ _____ ____ _| |_ _____ ____| |__ 5 \____ \| ___ | (_ _) ___ |/ ___) _ \ 6 _____) ) ____| | | || |_| ____( (___| | | | 7 (______/|_____)_|_|_| \__)_____)\____)_| |_| 8 (C)2016 Semtech 9 10 Description: Handling of the node configuration protocol 11 12 License: Revised BSD License, see LICENSE.TXT file include in the project 13 14 Maintainer: Miguel Luis, Matthieu Verdy and Benjamin Boulet 15 */ 16 #ifndef __RADIO_H__ 17 #define __RADIO_H__ 18 19 /*! 20 * \brief Class holding the basic communications with a radio 21 * 22 * It sets the functions to read/write registers, send commands and read/write 23 * payload. 24 * It also provides functions to run callback functions depending on the 25 * interrupts generated from the radio. 26 */ 27 struct Radio_s 28 { 29 /*! 30 * \brief Initializes the radio 31 * 32 * \param [IN] callbacks Structure containing the driver callback functions 33 */ 34 void ( *Init )( RadioCallbacks_t *callbacks ); 35 36 /*! 37 * \brief Resets the radio 38 */ 39 void ( *Reset )( void ); 40 41 /*! 42 * \brief Gets the current radio status 43 * 44 * \retval status Radio status 45 */ 46 RadioStatus_t ( *GetStatus )( void ); 47 48 /*! 49 * \brief Writes the given command to the radio 50 * 51 * \param [in] opcode Command opcode 52 * \param [in] buffer Command parameters byte array 53 * \param [in] size Command parameters byte array size 54 */ 55 void ( *WriteCommand )( RadioCommands_t opcode, uint8_t *buffer, uint16_t size ); 56 57 /*! 58 * \brief Reads the given command from the radio 59 * 60 * \param [in] opcode Command opcode 61 * \param [in] buffer Command parameters byte array 62 * \param [in] size Command parameters byte array size 63 */ 64 void ( *ReadCommand )( RadioCommands_t opcode, uint8_t *buffer, uint16_t size ); 65 66 /*! 67 * \brief Writes multiple radio registers starting at address 68 * 69 * \param [in] address First Radio register address 70 * \param [in] buffer Buffer containing the new register's values 71 * \param [in] size Number of registers to be written 72 */ 73 void ( *WriteRegisters )( uint16_t address, uint8_t *buffer, uint16_t size ); 74 75 /*! 76 * \brief Writes the radio register at the specified address 77 * 78 * \param [in] address Register address 79 * \param [in] value New register value 80 */ 81 void ( *WriteRegister )( uint16_t address, uint8_t value ); 82 83 /*! 84 * \brief Reads multiple radio registers starting at address 85 * 86 * \param [in] address First Radio register address 87 * \param [out] buffer Buffer where to copy the registers data 88 * \param [in] size Number of registers to be read 89 */ 90 void ( *ReadRegisters )( uint16_t address, uint8_t *buffer, uint16_t size ); 91 92 /*! 93 * \brief Reads the radio register at the specified address 94 * 95 * \param [in] address Register address 96 * 97 * \retval value The register value 98 */ 99 uint8_t ( *ReadRegister )( uint16_t address ); 100 101 /*! 102 * \brief Writes Radio Data Buffer with buffer of size starting at offset. 103 * 104 * \param [in] offset Offset where to start writing 105 * \param [in] buffer Buffer pointer 106 * \param [in] size Buffer size 107 */ 108 void ( *WriteBuffer )( uint8_t offset, uint8_t *buffer, uint8_t size ); 109 110 /*! 111 * \brief Reads Radio Data Buffer at offset to buffer of size 112 * 113 * \param [in] offset Offset where to start reading 114 * \param [out] buffer Buffer pointer 115 * \param [in] size Buffer size 116 */ 117 void ( *ReadBuffer )( uint8_t offset, uint8_t *buffer, uint8_t size ); 118 119 /*! 120 * \brief Gets the current status of the radio DIOs 121 * 122 * \retval status [Bit #3: DIO3, Bit #2: DIO2, 123 * Bit #1: DIO1, Bit #0: BUSY] 124 */ 125 uint8_t ( *GetDioStatus )( void ); 126 127 /*! 128 * \brief Return firmware version 129 * 130 * \retval firmware The firmware version 131 */ 132 uint16_t ( *GetFirmwareVersion )( void ); 133 134 /*! 135 * \brief Sets the power regulators operating mode 136 * 137 * \param [in] mode [0: LDO, 1:DC_DC] 138 */ 139 void ( *SetRegulatorMode )( RadioRegulatorModes_t mode ); 140 141 /*! 142 * \brief Sets the radio in configuration mode 143 * 144 * \param [in] mode The standby mode to put the radio into 145 */ 146 void ( *SetStandby )( RadioStandbyModes_t mode ); 147 148 /*! 149 * \brief Sets the radio for the given protocol 150 * 151 * \param [in] packetType [PACKET_TYPE_GFSK, PACKET_TYPE_LORA, 152 * PACKET_TYPE_RANGING, PACKET_TYPE_FLRC, 153 * PACKET_TYPE_BLE] 154 * 155 * \remark This method has to be called before SetRfFrequency, 156 * SetModulationParams and SetPacketParams 157 */ 158 void ( *SetPacketType )( RadioPacketTypes_t packetType ); 159 160 /*! 161 * \brief Set the modulation parameters 162 * 163 * \param [in] modParams A structure describing the modulation parameters 164 */ 165 void ( *SetModulationParams )( ModulationParams_t *modParams ); 166 167 /*! 168 * \brief Sets the packet parameters 169 * 170 * \param [in] packetParams A structure describing the packet parameters 171 */ 172 void ( *SetPacketParams )( PacketParams_t *packetParams ); 173 174 /*! 175 * \brief Sets the RF frequency 176 * 177 * \param [in] frequency RF frequency [Hz] 178 */ 179 void ( *SetRfFrequency )( uint32_t frequency ); 180 181 /*! 182 * \brief Sets the data buffer base address for transmission and reception 183 * 184 * \param [in] txBaseAddress Transmission base address 185 * \param [in] rxBaseAddress Reception base address 186 */ 187 void ( *SetBufferBaseAddresses )( uint8_t txBaseAddress, uint8_t rxBaseAddress ); 188 189 /*! 190 * \brief Sets the transmission parameters 191 * 192 * \param [in] power RF output power [-18..13] dBm 193 * \param [in] rampTime Transmission ramp up time 194 */ 195 void ( *SetTxParams )( int8_t power, RadioRampTimes_t rampTime ); 196 197 /*! 198 * \brief Sets the IRQ mask and DIO masks 199 * 200 * \param [in] irqMask General IRQ mask 201 * \param [in] dio1Mask DIO1 mask 202 * \param [in] dio2Mask DIO2 mask 203 * \param [in] dio3Mask DIO3 mask 204 */ 205 void ( *SetDioIrqParams )( uint16_t irqMask, uint16_t dio1Mask, uint16_t dio2Mask, uint16_t dio3Mask ); 206 207 /*! 208 * \brief Sets the Sync Word given by index used in GFSK, FLRC and BLE protocols 209 * 210 * \remark 5th byte isn't used in FLRC and BLE protocols 211 * 212 * \param [in] syncWordIdx Index of SyncWord to be set [1..3] 213 * \param [in] syncWord SyncWord bytes ( 5 bytes ) 214 * 215 * \retval status [0: OK, 1: NOK] 216 */ 217 uint8_t ( *SetSyncWord )( uint8_t syncWordIdx, uint8_t *syncWord ); 218 219 /*! 220 * \brief Sets the radio in reception mode 221 * 222 * \param [in] timeout Structure describing the reception timeout value 223 */ 224 void ( *SetRx )( TickTime_t timeout ); 225 226 /*! 227 * \brief Reads the payload received. If the received payload is longer 228 * than maxSize, then the method returns 1 and do not set size and payload. 229 * 230 * \param [out] payload A pointer to a buffer into which the payload will be copied 231 * \param [out] size A pointer to the size of the payload received 232 * \param [in] maxSize The maximal size allowed to copy into the buffer 233 */ 234 uint8_t ( *GetPayload )( uint8_t *payload, uint8_t *size, uint8_t maxSize ); 235 236 /*! 237 * \brief Sends a payload 238 * 239 * \param [in] payload A pointer to the payload to send 240 * \param [in] size The size of the payload to send 241 * \param [in] timeout The timeout for Tx operation 242 */ 243 void ( *SendPayload )( uint8_t *payload, uint8_t size, TickTime_t timeout ); 244 245 /*! 246 * \brief Set the role of the radio during ranging operations 247 * 248 * \param [in] role Role of the radio 249 */ 250 void ( *SetRangingRole )( RadioRangingRoles_t role ); 251 252 /*! 253 * \brief Set the driver in polling mode. 254 * 255 * In polling mode the application is responsible to call ProcessIrqs( ) to 256 * execute callbacks functions. 257 * The default mode is Interrupt Mode. 258 * @code 259 * // Initializations and callbacks declaration/definition 260 * radio = SX1280( mosi, miso, sclk, nss, busy, int1, int2, int3, rst, &callbacks ); 261 * radio.Init( ); 262 * radio.SetPollingMode( ); 263 * 264 * while( true ) 265 * { 266 * // IRQ processing is automatically done 267 * radio.ProcessIrqs( ); // <-- here, as well as callback functions 268 * // calls 269 * // Do some applicative work 270 * } 271 * @endcode 272 * 273 * \see SX1280SetInterruptMode 274 */ 275 void ( *SetPollingMode )( void ); 276 277 /*! 278 * \brief Set the driver in interrupt mode. 279 * 280 * In interrupt mode, the driver communicate with the radio during the 281 * interruption by direct calls to ProcessIrqs( ). The main advantage is 282 * the possibility to have low power application architecture. 283 * This is the default mode. 284 * @code 285 * // Initializations and callbacks declaration/definition 286 * radio = SX1280( mosi, miso, sclk, nss, busy, int1, int2, int3, rst, &callbacks ); 287 * radio.Init( ); 288 * radio.SetInterruptMode( ); // Optionnal. Driver default behavior 289 * 290 * while( true ) 291 * { 292 * // Do some applicative work 293 * } 294 * @endcode 295 * 296 * \see SX1280SetPollingMode 297 */ 298 void ( *SetInterruptMode )( void ); 299 300 /*! 301 * \brief Initializes the radio registers to the recommended default values 302 */ 303 void ( *SetRegistersDefault )( void ); 304 305 /*! 306 * \brief Gets the current Operation Mode of the Radio 307 * 308 * \retval RadioOperatingModes_t last operating mode 309 */ 310 RadioOperatingModes_t ( *GetOpMode )( void ); 311 312 /*! 313 * \brief Sets the radio in sleep mode 314 * 315 * \param [in] sleepConfig The sleep configuration describing data 316 * retention and RTC wake-up 317 */ 318 void ( *SetSleep )( SleepParams_t sleepConfig ); 319 320 /*! 321 * \brief Sets the radio in FS mode 322 */ 323 void ( *SetFs )( void ); 324 325 /*! 326 * \brief Sets the radio in transmission mode 327 * 328 * \param [in] timeout Structure describing the transmission timeout value 329 */ 330 void ( *SetTx )( TickTime_t timeout ); 331 332 /*! 333 * \brief Sets the Rx duty cycle management parameters 334 * 335 * \param [in] rxTime Structure describing reception timeout value 336 * \param [in] sleepTime Structure describing sleep timeout value 337 */ 338 void ( *SetRxDutyCycle )( RadioTickSizes_t Step, uint16_t NbStepRx, uint16_t RxNbStepSleep ); 339 340 /*! 341 * \brief Sets the radio in CAD mode 342 * 343 * \see SX1280::SetCadParams 344 */ 345 void ( *SetCad )( void ); 346 347 /*! 348 * \brief Sets the radio in continuous wave transmission mode 349 */ 350 void ( *SetTxContinuousWave )( void ); 351 352 /*! 353 * \brief Sets the radio in continuous preamble transmission mode 354 */ 355 void ( *SetTxContinuousPreamble )( void ); 356 357 /*! 358 * \brief Gets the current radio protocol 359 * 360 * \retval packetType [PACKET_TYPE_GFSK, PACKET_TYPE_LORA, 361 * PACKET_TYPE_RANGING, PACKET_TYPE_FLRC, 362 * PACKET_TYPE_BLE, PACKET_TYPE_NONE] 363 */ 364 RadioPacketTypes_t ( *GetPacketType )( void ); 365 366 /*! 367 * \brief Sets the number of symbols to be used for Channel Activity 368 * Detection operation 369 * 370 * \param [in] cadSymbolNum The number of symbol to use for Channel Activity 371 * Detection operations [LORA_CAD_01_SYMBOL, LORA_CAD_02_SYMBOL, 372 * LORA_CAD_04_SYMBOL, LORA_CAD_08_SYMBOL, LORA_CAD_16_SYMBOL] 373 */ 374 void ( *SetCadParams )( RadioLoRaCadSymbols_t cadSymbolNum ); 375 376 /*! 377 * \brief Gets the last received packet buffer status 378 * 379 * \param [out] payloadLength Last received packet payload length 380 * \param [out] rxStartBuffer Last received packet buffer address pointer 381 */ 382 void ( *GetRxBufferStatus )( uint8_t *payloadLength, uint8_t *rxStartBuffer ); 383 384 /*! 385 * \brief Gets the last received packet payload length 386 * 387 * \param [out] pktStatus A structure of packet status 388 */ 389 void ( *GetPacketStatus )( PacketStatus_t *pktStatus ); 390 391 /*! 392 * \brief Returns the instantaneous RSSI value for the last packet received 393 * 394 * \retval rssiInst Instantaneous RSSI 395 */ 396 int8_t ( *GetRssiInst )( void ); 397 398 /*! 399 * \brief Returns the current IRQ status 400 * 401 * \retval irqStatus IRQ status 402 */ 403 uint16_t ( *GetIrqStatus )( void ); 404 405 /*! 406 * \brief Clears the IRQs 407 * 408 * \param [in] irq IRQ(s) to be cleared 409 */ 410 void ( *ClearIrqStatus )( uint16_t irq ); 411 412 /*! 413 * \brief Calibrates the given radio block 414 * 415 * \param [in] calibParam The description of blocks to be calibrated 416 */ 417 void ( *Calibrate )( CalibrationParams_t calibParam ); 418 419 /*! 420 * \brief Saves the current selected modem configuration into data RAM 421 */ 422 void ( *SetSaveContext )( void ); 423 424 /*! 425 * \brief Sets the chip to automatically send a packet after the end of a packet reception 426 * 427 * \remark The offset is automatically compensated inside the function 428 * 429 * \param [in] time The delay in us after which a Tx is done 430 */ 431 void ( *SetAutoTx )( uint16_t time ); 432 433 /*! 434 * \brief Stop the chip from automatically sending a packet after the end of a packet reception 435 * if previously activated with SX1280::SetAutoTx command 436 * 437 * \see SX1280::SetAutoTx 438 */ 439 void ( *StopAutoTx )(); 440 /*! 441 * \brief Sets the chip to automatically receive a packet after the end of a packet transmission 442 * 443 * \remark The offset is automatically compensated inside the function 444 * 445 * \param [in] time The delay in us after which a Rx is done 446 */ 447 void ( *SetAutoFS )( uint8_t enable ); 448 449 /*! 450 * \brief Enables or disables long preamble detection mode 451 * 452 * \param [in] enable [0: Disable, 1: Enable] 453 */ 454 void ( *SetLongPreamble )( uint8_t enable ); 455 456 /*! 457 * \brief Saves the payload to be send in the radio buffer 458 * 459 * \param [in] payload A pointer to the payload 460 * \param [in] size The size of the payload 461 */ 462 void ( *SetPayload )( uint8_t *payload, uint8_t size ); 463 464 /*! 465 * \brief Sets the Sync Word given by index used in GFSK, FLRC and BLE protocols 466 * 467 * \remark 5th byte isn't used in FLRC and BLE protocols 468 * 469 * \param [in] syncWordIdx Index of SyncWord to be set [1..3] 470 * \param [in] syncWord SyncWord bytes ( 5 bytes ) 471 * 472 * \retval status [0: OK, 1: NOK] 473 */ 474 void ( *SetSyncWordErrorTolerance )( uint8_t errorBits ); 475 476 /*! 477 * \brief Sets the Initial value for the LFSR used for the CRC calculation 478 * 479 * \param [in] seed Initial LFSR value ( 4 bytes ) 480 * 481 */ 482 void ( *SetCrcSeed )( uint16_t seed ); 483 484 /*! 485 * \brief Set the Access Address field of BLE packet 486 * 487 * \param [in] accessAddress The access address to be used for next BLE packet sent 488 * 489 * \see SX1280::SetBleAdvertizerAccessAddress 490 */ 491 void ( *SetBleAccessAddress )( uint32_t accessAddress ); 492 493 /*! 494 * \brief Set the Access Address for Advertizer BLE packets 495 * 496 * All advertizer BLE packets must use a particular value for Access 497 * Address field. This method sets it. 498 * 499 * \see SX1280::SetBleAccessAddress 500 */ 501 void ( *SetBleAdvertizerAccessAddress )( void ); 502 503 504 /*! 505 * \brief Sets the seed used for the CRC calculation 506 * 507 * \param [in] seed The seed value 508 * 509 */ 510 void ( *SetCrcPolynomial )( uint16_t seed ); 511 512 /*! 513 * \brief Sets the Initial value of the LFSR used for the whitening in GFSK, FLRC and BLE protocols 514 * 515 * \param [in] seed Initial LFSR value 516 */ 517 void ( *SetWhiteningSeed )( uint8_t seed ); 518 519 /*! 520 * \brief Enable manual gain and disable AGC 521 * 522 * \see SetManualGainValue, DisableManualGain 523 */ 524 void ( *EnableManualGain )( void ); 525 526 /*! 527 * \brief Disable the manual gain control and enable AGC 528 * 529 * \see EnableManualGain 530 */ 531 void ( *DisableManualGain )( void ); 532 533 /*! 534 * \brief Set the gain for LNA 535 * 536 * EnableManualGain must be call before using this function 537 * 538 * \param [in] gain The value of gain to set, refer to datasheet for value meaning 539 * 540 * \see EnableManualGain, DisableManualGain 541 */ 542 void ( *SetManualGainValue )( uint8_t gain ); 543 544 /*! 545 * \brief Configure the LNA regime of operation 546 * 547 * \param [in] lnaSetting The LNA setting. Possible values are 548 * LNA_LOW_POWER_MODE and 549 * LNA_HIGH_SENSITIVITY_MODE 550 */ 551 void ( *SetLNAGainSetting )( RadioLnaSettings_t lnaSetting ); 552 553 /*! 554 * \brief Sets the number of bits used to check that ranging request match ranging ID 555 * 556 * \param [in] length [0: 8 bits, 1: 16 bits, 557 * 2: 24 bits, 3: 32 bits] 558 */ 559 void ( *SetRangingIdLength )( RadioRangingIdCheckLengths_t length ); 560 561 /*! 562 * \brief Sets ranging device id 563 * 564 * \param [in] address Device address 565 */ 566 void ( *SetDeviceRangingAddress )( uint32_t address ); 567 568 /*! 569 * \brief Sets the device id to ping in a ranging request 570 * 571 * \param [in] address Address of the device to ping 572 */ 573 void ( *SetRangingRequestAddress )( uint32_t address ); 574 575 /*! 576 * \brief Return the ranging result value 577 * 578 * \param [in] resultType Specifies the type of result. 579 * [0: RAW, 1: Averaged, 580 * 2: De-biased, 3:Filtered] 581 * 582 * \retval ranging The ranging measure filtered according to resultType [m] 583 */ 584 double ( *GetRangingResult )( RadioRangingResultTypes_t resultType ); 585 586 /*! 587 * \brief Sets the standard processing delay between Master and Slave 588 * 589 * \param [in] cal RxTx delay offset for correcting ranging bias. 590 * 591 * The calibration value reflects the group delay of the radio front end and 592 * must be re-performed for each new SX1280 PCB design. The value is obtained 593 * empirically by either conducted measurement in a known electrical length 594 * coaxial RF cable (where the design is connectorised) or by radiated 595 * measurement, at a known distance, where an antenna is present. 596 * The result of the calibration process is that the SX1280 ranging result 597 * accurately reflects the physical range, the calibration procedure therefore 598 * removes the average timing error from the time-of-flight measurement for a 599 * given design. 600 * 601 * The values are Spreading Factor dependents, and depend also of the board 602 * design. Some typical values are provided in the next table. 603 * 604 * Spreading Factor | Calibration Value 605 * ---------------- | ----------------- 606 * SF5 | 12200 607 * SF6 | 12200 608 * SF7 | 12400 609 * SF8 | 12650 610 * SF9 | 12940 611 * SF10 | 13000 612 * SF11 | 13060 613 * SF12 | 13120 614 */ 615 void ( *SetRangingCalibration )( uint16_t cal ); 616 617 /*! 618 * \brief Return the last ranging result power indicator 619 * 620 * The value returned is not an absolute power measurement. It is 621 * a relative power measurement. 622 * 623 * \retval deltaThreshold A relative power indicator 624 */ 625 uint8_t ( *GetRangingPowerDeltaThresholdIndicator)( void ); 626 627 /*! 628 * \brief Clears the ranging filter 629 */ 630 void ( *RangingClearFilterResult )( void ); 631 632 /*! 633 * \brief Set the number of samples considered in the built-in filter 634 * 635 * \param [in] numSample The number of samples to use built-in filter 636 * [8..255] 637 * 638 * \remark Value inferior to 8 will be silently set to 8 639 */ 640 void ( *RangingSetFilterNumSamples )( uint8_t numSample ); 641 642 /*! 643 * \brief Return the Estimated Frequency Error in LORA and RANGING operations 644 * 645 * \retval efe The estimated frequency error [Hz] 646 */ 647 double ( *GetFrequencyError )( void ); 648 }; 649 650 /*! 651 * \brief Radio driver 652 * 653 * \remark This variable is defined and initialized in the specific radio 654 * board implementation 655 */ 656 extern const struct Radio_s Radio; 657 658 #endif // __RADIO_H__ 659