1 /*! 2 * \file RegionCommon.h 3 * 4 * \brief Region independent implementations which are common to all regions. 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 * ___ _____ _ ___ _ _____ ___ ___ ___ ___ 18 * / __|_ _/_\ / __| |/ / __/ _ \| _ \/ __| __| 19 * \__ \ | |/ _ \ (__| ' <| _| (_) | / (__| _| 20 * |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___| 21 * embedded.connectivity.solutions=============== 22 * 23 * \endcode 24 * 25 * \author Miguel Luis ( Semtech ) 26 * 27 * \author Gregory Cristian ( Semtech ) 28 * 29 * \author Daniel Jaeckle ( STACKFORCE ) 30 * 31 * \author Johannes Bruder ( STACKFORCE ) 32 * 33 * \defgroup REGIONCOMMON Common region implementation 34 * Region independent implementations which are common to all regions. 35 * \{ 36 */ 37 #ifndef __REGIONCOMMON_H__ 38 #define __REGIONCOMMON_H__ 39 40 #ifdef __cplusplus 41 extern "C" 42 { 43 #endif 44 45 #include "LoRaMacTypes.h" 46 #include "LoRaMacHeaderTypes.h" 47 #include "region/Region.h" 48 49 // Constants that are common to all the regions. 50 51 /*! 52 * Receive delay of 1 second. 53 */ 54 #define REGION_COMMON_DEFAULT_RECEIVE_DELAY1 1000 55 56 /*! 57 * Receive delay of 2 seconds. 58 */ 59 #define REGION_COMMON_DEFAULT_RECEIVE_DELAY2 ( REGION_COMMON_DEFAULT_RECEIVE_DELAY1 + 1000 ) 60 61 /*! 62 * Join accept delay of 5 seconds. 63 */ 64 #define REGION_COMMON_DEFAULT_JOIN_ACCEPT_DELAY1 5000 65 66 /*! 67 * Join accept delay of 6 seconds. 68 */ 69 #define REGION_COMMON_DEFAULT_JOIN_ACCEPT_DELAY2 ( REGION_COMMON_DEFAULT_JOIN_ACCEPT_DELAY1 + 1000 ) 70 71 /*! 72 * ADR ack limit. 73 */ 74 #define REGION_COMMON_DEFAULT_ADR_ACK_LIMIT 64 75 76 /*! 77 * ADR ack delay. 78 */ 79 #define REGION_COMMON_DEFAULT_ADR_ACK_DELAY 32 80 81 /*! 82 * Retransmission timeout for ACK in milliseconds. 83 */ 84 #define REGION_COMMON_DEFAULT_RETRANSMIT_TIMEOUT 2000 85 86 /*! 87 * Rounding limit for generating random retransmission timeout for ACK. 88 * In milliseconds. 89 */ 90 #define REGION_COMMON_DEFAULT_RETRANSMIT_TIMEOUT_RND 1000 91 92 /*! 93 * Default Rx1 receive datarate offset 94 */ 95 #define REGION_COMMON_DEFAULT_RX1_DR_OFFSET 0 96 97 /*! 98 * Default downlink dwell time configuration 99 */ 100 #define REGION_COMMON_DEFAULT_DOWNLINK_DWELL_TIME 0 101 102 /*! 103 * Default ping slots periodicity 104 * 105 * Periodicity is equal to 2^REGION_COMMON_DEFAULT_PING_SLOT_PERIODICITY seconds. 106 * Example: 2^7 = 128 seconds. The end-device will open an Rx slot every 128 seconds. 107 */ 108 #define REGION_COMMON_DEFAULT_PING_SLOT_PERIODICITY 7 109 110 /*! 111 * Default reponse timeout for class b and class c confirmed 112 * downlink frames in milli seconds. 113 * 114 * The value shall not be smaller than RETRANSMIT_TIMEOUT plus 115 * the maximum time on air. 116 */ 117 #define REGION_COMMON_CLASS_B_C_RESP_TIMEOUT 8000 118 119 120 typedef struct sRegionCommonLinkAdrParams 121 { 122 /*! 123 * Number of repetitions. 124 */ 125 uint8_t NbRep; 126 /*! 127 * Datarate. 128 */ 129 int8_t Datarate; 130 /*! 131 * Tx power. 132 */ 133 int8_t TxPower; 134 /*! 135 * Channels mask control field. 136 */ 137 uint8_t ChMaskCtrl; 138 /*! 139 * Channels mask field. 140 */ 141 uint16_t ChMask; 142 }RegionCommonLinkAdrParams_t; 143 144 typedef struct sRegionCommonLinkAdrReqVerifyParams 145 { 146 /*! 147 * LoRaWAN specification Version 148 */ 149 Version_t Version; 150 /*! 151 * The current status of the AdrLinkRequest. 152 */ 153 uint8_t Status; 154 /*! 155 * Set to true, if ADR is enabled. 156 */ 157 bool AdrEnabled; 158 /*! 159 * The datarate the AdrLinkRequest wants to set. 160 */ 161 int8_t Datarate; 162 /*! 163 * The TX power the AdrLinkRequest wants to set. 164 */ 165 int8_t TxPower; 166 /*! 167 * The number of repetitions the AdrLinkRequest wants to set. 168 */ 169 uint8_t NbRep; 170 /*! 171 * The current datarate the node is using. 172 */ 173 int8_t CurrentDatarate; 174 /*! 175 * The current TX power the node is using. 176 */ 177 int8_t CurrentTxPower; 178 /*! 179 * The current number of repetitions the node is using. 180 */ 181 int8_t CurrentNbRep; 182 /*! 183 * The number of channels. 184 */ 185 uint8_t NbChannels; 186 /*! 187 * Pointer to the first element of the channels mask. 188 */ 189 uint16_t* ChannelsMask; 190 /*! 191 * The minimum possible datarate. 192 */ 193 int8_t MinDatarate; 194 /*! 195 * The maximum possible datarate. 196 */ 197 int8_t MaxDatarate; 198 /*! 199 * Pointer to the channels. 200 */ 201 ChannelParams_t* Channels; 202 /*! 203 * The minimum possible TX power. 204 */ 205 int8_t MinTxPower; 206 /*! 207 * The maximum possible TX power. 208 */ 209 int8_t MaxTxPower; 210 }RegionCommonLinkAdrReqVerifyParams_t; 211 212 typedef struct sRegionCommonRxBeaconSetupParams 213 { 214 /*! 215 * A pointer to the available datarates. 216 */ 217 const uint8_t* Datarates; 218 /*! 219 * Frequency 220 */ 221 uint32_t Frequency; 222 /*! 223 * The size of the beacon frame. 224 */ 225 uint8_t BeaconSize; 226 /*! 227 * The datarate of the beacon. 228 */ 229 uint8_t BeaconDatarate; 230 /*! 231 * The channel bandwidth of the beacon. 232 */ 233 uint8_t BeaconChannelBW; 234 /*! 235 * The RX time. 236 */ 237 uint32_t RxTime; 238 /*! 239 * The symbol timeout of the RX procedure. 240 */ 241 uint16_t SymbolTimeout; 242 }RegionCommonRxBeaconSetupParams_t; 243 244 typedef struct sRegionCommonCountNbOfEnabledChannelsParams 245 { 246 /*! 247 * Set to true, if the device is joined. 248 */ 249 bool Joined; 250 /*! 251 * The datarate to count the available channels. 252 */ 253 uint8_t Datarate; 254 /*! 255 * A pointer to the channels mask to verify. 256 */ 257 uint16_t* ChannelsMask; 258 /*! 259 * A pointer to the channels. 260 */ 261 ChannelParams_t* Channels; 262 /*! 263 * A pointer to the bands. 264 */ 265 Band_t* Bands; 266 /*! 267 * The number of available channels. 268 */ 269 uint16_t MaxNbChannels; 270 /*! 271 * A pointer to the bitmask containing the 272 * join channels. Shall have the same dimension as the 273 * ChannelsMask with a number of MaxNbChannels channels. 274 */ 275 uint16_t* JoinChannels; 276 }RegionCommonCountNbOfEnabledChannelsParams_t; 277 278 typedef struct sRegionCommonIdentifyChannelsParam 279 { 280 /*! 281 * Aggregated time-off time. 282 */ 283 TimerTime_t AggrTimeOff; 284 /*! 285 * Time of the last aggregated TX. 286 */ 287 TimerTime_t LastAggrTx; 288 /*! 289 * Set to true, if the duty cycle is enabled, otherwise false. 290 */ 291 bool DutyCycleEnabled; 292 /*! 293 * Maximum number of bands. 294 */ 295 uint8_t MaxBands; 296 /*! 297 * Elapsed time since the start of the node. 298 */ 299 SysTime_t ElapsedTimeSinceStartUp; 300 /*! 301 * Joined Set to true, if the last uplink was a join request 302 */ 303 bool LastTxIsJoinRequest; 304 /*! 305 * Expected time-on-air 306 */ 307 TimerTime_t ExpectedTimeOnAir; 308 /*! 309 * Pointer to a structure of RegionCommonCountNbOfEnabledChannelsParams_t. 310 */ 311 RegionCommonCountNbOfEnabledChannelsParams_t* CountNbOfEnabledChannelsParam; 312 }RegionCommonIdentifyChannelsParam_t; 313 314 typedef struct sRegionCommonSetDutyCycleParams 315 { 316 /*! 317 * Duty cycle period. 318 */ 319 TimerTime_t DutyCycleTimePeriod; 320 /*! 321 * Number of bands available. 322 */ 323 uint8_t MaxBands; 324 /*! 325 * A pointer to the bands. 326 */ 327 Band_t* Bands; 328 }RegionCommonSetDutyCycleParams_t; 329 330 typedef struct sRegionCommonGetNextLowerTxDrParams 331 { 332 int8_t CurrentDr; 333 int8_t MaxDr; 334 int8_t MinDr; 335 uint8_t NbChannels; 336 uint16_t* ChannelsMask; 337 ChannelParams_t* Channels; 338 }RegionCommonGetNextLowerTxDrParams_t; 339 340 /*! 341 * \brief Verifies, if a value is in a given range. 342 * This is a generic function and valid for all regions. 343 * 344 * \param [IN] value Value to verify, if it is in range. 345 * 346 * \param [IN] min Minimum possible value. 347 * 348 * \param [IN] max Maximum possible value. 349 * 350 * \retval Returns 1 if the value is in range, otherwise 0. 351 */ 352 uint8_t RegionCommonValueInRange( int8_t value, int8_t min, int8_t max ); 353 354 /*! 355 * \brief Verifies, if a datarate is available on an active channel. 356 * This is a generic function and valid for all regions. 357 * 358 * \param [IN] nbChannels Number of channels. 359 * 360 * \param [IN] channelsMask The channels mask of the region. 361 * 362 * \param [IN] dr The datarate to verify. 363 * 364 * \param [IN] minDr Minimum datarate. 365 * 366 * \param [IN] maxDr Maximum datarate. 367 * 368 * \param [IN] channels The channels of the region. 369 * 370 * \retval Returns true if the datarate is supported, false if not. 371 */ 372 bool RegionCommonChanVerifyDr( uint8_t nbChannels, uint16_t* channelsMask, int8_t dr, 373 int8_t minDr, int8_t maxDr, ChannelParams_t* channels ); 374 375 /*! 376 * \brief Disables a channel in a given channels mask. 377 * This is a generic function and valid for all regions. 378 * 379 * \param [IN] channelsMask The channels mask of the region. 380 * 381 * \param [IN] id The id of the channels mask to disable. 382 * 383 * \param [IN] maxChannels Maximum number of channels. 384 * 385 * \retval Returns true if the channel could be disabled, false if not. 386 */ 387 bool RegionCommonChanDisable( uint16_t* channelsMask, uint8_t id, uint8_t maxChannels ); 388 389 /*! 390 * \brief Counts the number of active channels in a given channels mask. 391 * This is a generic function and valid for all regions. 392 * 393 * \param [IN] channelsMask The channels mask of the region. 394 * 395 * \param [IN] startIdx Start index. 396 * 397 * \param [IN] stopIdx Stop index ( the channels of this index will not be counted ). 398 * 399 * \retval Returns the number of active channels. 400 */ 401 uint8_t RegionCommonCountChannels( uint16_t* channelsMask, uint8_t startIdx, uint8_t stopIdx ); 402 403 /*! 404 * \brief Copy a channels mask. 405 * This is a generic function and valid for all regions. 406 * 407 * \param [IN] channelsMaskDest The destination channels mask. 408 * 409 * \param [IN] channelsMaskSrc The source channels mask. 410 * 411 * \param [IN] len The index length to copy. 412 */ 413 void RegionCommonChanMaskCopy( uint16_t* channelsMaskDest, uint16_t* channelsMaskSrc, uint8_t len ); 414 415 /*! 416 * \brief Sets the last tx done property. 417 * This is a generic function and valid for all regions. 418 * 419 * \param [IN] band The band to be updated. 420 * 421 * \param [IN] lastTxAirTime The time on air of the last TX frame. 422 * 423 * \param [IN] joined Set to true if the device has joined. 424 * 425 * \param [IN] elapsedTimeSinceStartup Elapsed time since initialization. 426 */ 427 void RegionCommonSetBandTxDone( Band_t* band, TimerTime_t lastTxAirTime, bool joined, SysTime_t elapsedTimeSinceStartup ); 428 429 /*! 430 * \brief Updates the time-offs of the bands. 431 * This is a generic function and valid for all regions. 432 * 433 * \param [IN] joined Set to true, if the node has joined the network 434 * 435 * \param [IN] bands A pointer to the bands. 436 * 437 * \param [IN] nbBands The number of bands available. 438 * 439 * \param [IN] dutyCycleEnabled Set to true, if the duty cycle is enabled. 440 * 441 * \param [IN] lastTxIsJoinRequest Set to true, if the last TX is a join request. 442 * 443 * \param [IN] elapsedTimeSinceStartup Elapsed time since start up. 444 * 445 * \param [IN] expectedTimeOnAir Expected time on air for the next transmission. 446 * 447 * \retval Returns the time which must be waited to perform the next uplink. 448 */ 449 TimerTime_t RegionCommonUpdateBandTimeOff( bool joined, Band_t* bands, 450 uint8_t nbBands, bool dutyCycleEnabled, 451 bool lastTxIsJoinRequest, SysTime_t elapsedTimeSinceStartup, 452 TimerTime_t expectedTimeOnAir ); 453 454 /*! 455 * \brief Parses the parameter of an LinkAdrRequest. 456 * This is a generic function and valid for all regions. 457 * 458 * \param [IN] payload Pointer to the payload containing the MAC commands. The payload 459 * must contain the CMD identifier, following by the parameters. 460 * 461 * \param [OUT] parseLinkAdr The function fills the structure with the ADR parameters. 462 * 463 * \retval Returns the length of the ADR request, if a request was found. Otherwise, the 464 * function returns 0. 465 */ 466 uint8_t RegionCommonParseLinkAdrReq( uint8_t* payload, RegionCommonLinkAdrParams_t* parseLinkAdr ); 467 468 /*! 469 * \brief Verifies and updates the datarate, the TX power and the number of repetitions 470 * of a LinkAdrRequest. This depends on the configuration of ADR also. 471 * 472 * \param [IN] verifyParams Pointer to a structure containing input parameters. 473 * 474 * \param [OUT] dr The updated datarate. 475 * 476 * \param [OUT] txPow The updated TX power. 477 * 478 * \param [OUT] nbRep The updated number of repetitions. 479 * 480 * \retval Returns the status according to the LinkAdrRequest definition. 481 */ 482 uint8_t RegionCommonLinkAdrReqVerifyParams( RegionCommonLinkAdrReqVerifyParams_t* verifyParams, int8_t* dr, int8_t* txPow, uint8_t* nbRep ); 483 484 /*! 485 * \brief Computes the symbol time for LoRa modulation. 486 * 487 * \param [IN] phyDr Physical datarate to use. 488 * 489 * \param [IN] bandwidth Bandwidth to use. 490 * 491 * \retval Returns the symbol time in microseconds. 492 */ 493 uint32_t RegionCommonComputeSymbolTimeLoRa( uint8_t phyDr, uint32_t bandwidthInHz ); 494 495 /*! 496 * \brief Computes the symbol time for FSK modulation. 497 * 498 * \param [IN] phyDr Physical datarate to use. 499 * 500 * \retval Returns the symbol time in microseconds. 501 */ 502 uint32_t RegionCommonComputeSymbolTimeFsk( uint8_t phyDrInKbps ); 503 504 /*! 505 * \brief Computes the RX window timeout and the RX window offset. 506 * 507 * \param [IN] tSymbolInUs Symbol timeout. 508 * 509 * \param [IN] minRxSymbols Minimum required number of symbols to detect an Rx frame. 510 * 511 * \param [IN] rxErrorInMs System maximum timing error of the receiver. In milliseconds 512 * The receiver will turn on in a [-rxErrorInMs : +rxErrorInMs] ms interval around RxOffset. 513 * 514 * \param [IN] wakeUpTimeInMs Wakeup time of the system. 515 * 516 * \param [OUT] windowTimeoutInSymbols RX window timeout. 517 * 518 * \param [OUT] windowOffsetInMs RX window time offset to be applied to the RX delay. 519 */ 520 void RegionCommonComputeRxWindowParameters( uint32_t tSymbolInUs, uint8_t minRxSymbols, uint32_t rxErrorInMs, uint32_t wakeUpTimeInMs, uint32_t* windowTimeoutInSymbols, int32_t* windowOffsetInMs ); 521 522 /*! 523 * \brief Computes the txPower, based on the max EIRP and the antenna gain. 524 * 525 * \remark US915 region uses a conducted power as input value for maxEirp. 526 * Thus, the antennaGain parameter must be set to 0. 527 * 528 * \param [IN] txPower TX power index. 529 * 530 * \param [IN] maxEirp Maximum EIRP. 531 * 532 * \param [IN] antennaGain Antenna gain. Referenced to the isotropic antenna. 533 * Value is in dBi. ( antennaGain[dBi] = measuredAntennaGain[dBd] + 2.15 ) 534 * 535 * \retval Returns the physical TX power. 536 */ 537 int8_t RegionCommonComputeTxPower( int8_t txPowerIndex, float maxEirp, float antennaGain ); 538 539 /*! 540 * \brief Sets up the radio into RX beacon mode. 541 * 542 * \param [IN] rxBeaconSetupParams A pointer to the input parameters. 543 */ 544 void RegionCommonRxBeaconSetup( RegionCommonRxBeaconSetupParams_t* rxBeaconSetupParams ); 545 546 /*! 547 * \brief Counts the number of enabled channels. 548 * 549 * \param [IN] countNbOfEnabledChannelsParams A pointer to the input parameters. 550 * 551 * \param [OUT] enabledChannels A pointer to an array of size XX_MAX_NB_CHANNELS. The function 552 * stores the available channels into this array. 553 * 554 * \param [OUT] nbEnabledChannels The number of available channels found. 555 * 556 * \param [OUT] nbRestrictedChannels It contains the number of channel 557 * which are available, but restricted due to duty cycle. 558 */ 559 void RegionCommonCountNbOfEnabledChannels( RegionCommonCountNbOfEnabledChannelsParams_t* countNbOfEnabledChannelsParams, 560 uint8_t* enabledChannels, uint8_t* nbEnabledChannels, uint8_t* nbRestrictedChannels ); 561 562 /*! 563 * \brief Identifies all channels which are available currently. 564 * 565 * \param [IN] identifyChannelsParam A pointer to the input parameters. 566 * 567 * \param [OUT] aggregatedTimeOff The new value of the aggregatedTimeOff. The function 568 * may resets it to 0. 569 * 570 * \param [OUT] enabledChannels A pointer to an array of size XX_MAX_NB_CHANNELS. The function 571 * stores the available channels into this array. 572 * 573 * \param [OUT] nbEnabledChannels The number of available channels found. 574 * 575 * \param [OUT] nbRestrictedChannels It contains the number of channel 576 * which are available, but restricted due to duty cycle. 577 * 578 * \param [OUT] nextTxDelay Holds the time which has to be waited for the next possible 579 * uplink transmission. 580 * 581 *\retval Status of the operation. 582 */ 583 LoRaMacStatus_t RegionCommonIdentifyChannels( RegionCommonIdentifyChannelsParam_t* identifyChannelsParam, 584 TimerTime_t* aggregatedTimeOff, uint8_t* enabledChannels, 585 uint8_t* nbEnabledChannels, uint8_t* nbRestrictedChannels, 586 TimerTime_t* nextTxDelay ); 587 588 /*! 589 * \brief Selects the next lower datarate. 590 * 591 * \param [IN] params Data structure providing parameters based on \ref RegionCommonGetNextLowerTxDrParams_t 592 * 593 * \retval The next lower datarate. 594 */ 595 int8_t RegionCommonGetNextLowerTxDr( RegionCommonGetNextLowerTxDrParams_t *params ); 596 597 /*! 598 * \brief Limits the TX power. 599 * 600 * \param [IN] txPower Current TX power. 601 * 602 * \param [IN] maxBandTxPower Maximum possible TX power. 603 * 604 * \retval Limited TX power. 605 */ 606 int8_t RegionCommonLimitTxPower( int8_t txPower, int8_t maxBandTxPower ); 607 608 /*! 609 * \brief Gets the bandwidth. 610 * 611 * \param [IN] drIndex Datarate index. 612 * 613 * \param [IN] bandwidths A pointer to the bandwidth table. 614 * 615 * \retval Bandwidth. 616 */ 617 uint32_t RegionCommonGetBandwidth( uint32_t drIndex, const uint32_t* bandwidths ); 618 619 /*! \} defgroup REGIONCOMMON */ 620 621 #ifdef __cplusplus 622 } 623 #endif 624 625 #endif // __REGIONCOMMON_H__ 626
