1 /*! 2 * \file Region.h 3 * 4 * \brief Region 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 * ___ _____ _ ___ _ _____ ___ ___ ___ ___ 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 * \defgroup REGION Region implementation 32 * This is the common API to access the specific 33 * regional implementations. 34 * 35 * Preprocessor options: 36 * - LoRaWAN regions can be activated by defining the related preprocessor 37 * definition. It is possible to define more than one region. 38 * The following regions are supported: 39 * - #define REGION_AS923 40 * - #define REGION_AU915 41 * - #define REGION_CN470 42 * - #define REGION_CN779 43 * - #define REGION_EU433 44 * - #define REGION_EU868 45 * - #define REGION_KR920 46 * - #define REGION_IN865 47 * - #define REGION_US915 48 * - #define REGION_RU864 49 * 50 * \{ 51 */ 52 #ifndef __REGION_H__ 53 #define __REGION_H__ 54 55 #ifdef __cplusplus 56 extern "C" 57 { 58 #endif 59 60 #include <stdint.h> 61 #include <stdbool.h> 62 #include "utilities.h" 63 #include "LoRaMac.h" 64 #include "timer.h" 65 #include "RegionCommon.h" 66 67 /*! 68 * Macro to compute bit of a channel index. 69 */ 70 #define LC( channelIndex ) ( uint16_t )( 1 << ( channelIndex - 1 ) ) 71 72 #ifndef REGION_VERSION 73 /*! 74 * Regional parameters version definition. 75 * RP002-1.0.3 76 */ 77 #define REGION_VERSION 0x02010003 78 #endif 79 80 81 82 /*! 83 * Enumeration of phy attributes. 84 */ 85 typedef enum ePhyAttribute 86 { 87 /*! 88 * Frequency. It is available 89 * to perform a verification with RegionVerify(). 90 */ 91 PHY_FREQUENCY, 92 /*! 93 * Minimum RX datarate. 94 */ 95 PHY_MIN_RX_DR, 96 /*! 97 * Minimum TX datarate. 98 */ 99 PHY_MIN_TX_DR, 100 /*! 101 * Maximum RX datarate. 102 */ 103 PHY_MAX_RX_DR, 104 /*! 105 * Maximum TX datarate. 106 */ 107 PHY_MAX_TX_DR, 108 /*! 109 * TX datarate. 110 * This is a parameter which can't be queried. It is available 111 * to perform a verification with RegionVerify(). 112 */ 113 PHY_TX_DR, 114 /*! 115 * Default TX datarate. 116 */ 117 PHY_DEF_TX_DR, 118 /*! 119 * RX datarate. It is available 120 * to perform a verification with RegionVerify(). 121 */ 122 PHY_RX_DR, 123 /*! 124 * Maximum TX power. 125 */ 126 PHY_MAX_TX_POWER, 127 /*! 128 * TX power. It is available 129 * to perform a verification with RegionVerify(). 130 */ 131 PHY_TX_POWER, 132 /*! 133 * Default TX power. 134 */ 135 PHY_DEF_TX_POWER, 136 /*! 137 * Default ADR_ACK_LIMIT value. 138 */ 139 PHY_DEF_ADR_ACK_LIMIT, 140 /*! 141 * Default ADR_ACK_DELAY value. 142 */ 143 PHY_DEF_ADR_ACK_DELAY, 144 /*! 145 * Maximum payload possible. 146 */ 147 PHY_MAX_PAYLOAD, 148 /*! 149 * Duty cycle. 150 */ 151 PHY_DUTY_CYCLE, 152 /*! 153 * Maximum receive window duration. 154 */ 155 PHY_MAX_RX_WINDOW, 156 /*! 157 * Receive delay for window 1. 158 */ 159 PHY_RECEIVE_DELAY1, 160 /*! 161 * Receive delay for window 2. 162 */ 163 PHY_RECEIVE_DELAY2, 164 /*! 165 * Join accept delay for window 1. 166 */ 167 PHY_JOIN_ACCEPT_DELAY1, 168 /*! 169 * Join accept delay for window 2. 170 */ 171 PHY_JOIN_ACCEPT_DELAY2, 172 /*! 173 * Acknowledgement time out. 174 */ 175 PHY_RETRANSMIT_TIMEOUT, 176 /*! 177 * Default datarate offset for window 1. 178 */ 179 PHY_DEF_DR1_OFFSET, 180 /*! 181 * Default receive window 2 frequency. 182 */ 183 PHY_DEF_RX2_FREQUENCY, 184 /*! 185 * Default receive window 2 datarate. 186 */ 187 PHY_DEF_RX2_DR, 188 /*! 189 * Channels mask. 190 */ 191 PHY_CHANNELS_MASK, 192 /*! 193 * Channels default mask. 194 */ 195 PHY_CHANNELS_DEFAULT_MASK, 196 /*! 197 * Maximum number of supported channels 198 */ 199 PHY_MAX_NB_CHANNELS, 200 /*! 201 * Channels. 202 */ 203 PHY_CHANNELS, 204 /*! 205 * Default value of the uplink dwell time. 206 */ 207 PHY_DEF_UPLINK_DWELL_TIME, 208 /*! 209 * Default value of the downlink dwell time. 210 */ 211 PHY_DEF_DOWNLINK_DWELL_TIME, 212 /*! 213 * Default value of the MaxEIRP. 214 */ 215 PHY_DEF_MAX_EIRP, 216 /*! 217 * Default value of the antenna gain. 218 */ 219 PHY_DEF_ANTENNA_GAIN, 220 /*! 221 * Next lower datarate. 222 */ 223 PHY_NEXT_LOWER_TX_DR, 224 /*! 225 * Beacon interval in ms. 226 */ 227 PHY_BEACON_INTERVAL, 228 /*! 229 * Beacon reserved time in ms. 230 */ 231 PHY_BEACON_RESERVED, 232 /*! 233 * Beacon guard time in ms. 234 */ 235 PHY_BEACON_GUARD, 236 /*! 237 * Beacon window time in ms. 238 */ 239 PHY_BEACON_WINDOW, 240 /*! 241 * Beacon window time in numer of slots. 242 */ 243 PHY_BEACON_WINDOW_SLOTS, 244 /*! 245 * Ping slot length time in ms. 246 */ 247 PHY_PING_SLOT_WINDOW, 248 /*! 249 * Default symbol timeout for beacons and ping slot windows. 250 */ 251 PHY_BEACON_SYMBOL_TO_DEFAULT, 252 /*! 253 * Maximum symbol timeout for beacons. 254 */ 255 PHY_BEACON_SYMBOL_TO_EXPANSION_MAX, 256 /*! 257 * Maximum symbol timeout for ping slots. 258 */ 259 PHY_PING_SLOT_SYMBOL_TO_EXPANSION_MAX, 260 /*! 261 * Symbol expansion value for beacon windows in case of beacon 262 * loss in symbols. 263 */ 264 PHY_BEACON_SYMBOL_TO_EXPANSION_FACTOR, 265 /*! 266 * Symbol expansion value for ping slot windows in case of beacon 267 * loss in symbols. 268 */ 269 PHY_PING_SLOT_SYMBOL_TO_EXPANSION_FACTOR, 270 /*! 271 * Maximum allowed beacon less time in ms. 272 */ 273 PHY_MAX_BEACON_LESS_PERIOD, 274 /*! 275 * Delay time for the BeaconTimingAns in ms. 276 */ 277 PHY_BEACON_DELAY_BEACON_TIMING_ANS, 278 /*! 279 * Beacon channel frequency. 280 */ 281 PHY_BEACON_CHANNEL_FREQ, 282 /*! 283 * The format of the beacon. 284 */ 285 PHY_BEACON_FORMAT, 286 /*! 287 * The beacon channel datarate. 288 */ 289 PHY_BEACON_CHANNEL_DR, 290 /*! 291 * The number of channels for the beacon reception. 292 */ 293 PHY_BEACON_NB_CHANNELS, 294 /*! 295 * The static offset for the downlink channel calculation. 296 */ 297 PHY_BEACON_CHANNEL_OFFSET, 298 /*! 299 * Ping slot channel frequency. 300 */ 301 PHY_PING_SLOT_CHANNEL_FREQ, 302 /*! 303 * The datarate of a ping slot channel. 304 */ 305 PHY_PING_SLOT_CHANNEL_DR, 306 /*! 307 * The number of channels for the ping slot reception. 308 */ 309 PHY_PING_SLOT_NB_CHANNELS, 310 /*! 311 * The equivalent spreading factor value from datarate 312 */ 313 PHY_SF_FROM_DR, 314 /*! 315 * The equivalent bandwith index from datarate 316 */ 317 PHY_BW_FROM_DR, 318 }PhyAttribute_t; 319 320 /*! 321 * Enumeration of initialization types. 322 */ 323 typedef enum eInitType 324 { 325 /*! 326 * Initializes the regional default settings for the band, 327 * channel and default channels mask. Some regions also initiate 328 * other default configurations. In general, this type is intended 329 * to be called once during the initialization. 330 */ 331 INIT_TYPE_DEFAULTS, 332 /*! 333 * Resets the channels mask to the default channels. Deactivates 334 * all other channels. 335 */ 336 INIT_TYPE_RESET_TO_DEFAULT_CHANNELS, 337 /*! 338 * Activates the default channels. Leaves all other active channels 339 * active. 340 */ 341 INIT_TYPE_ACTIVATE_DEFAULT_CHANNELS 342 }InitType_t; 343 344 typedef enum eChannelsMask 345 { 346 /*! 347 * The channels mask. 348 */ 349 CHANNELS_MASK, 350 /*! 351 * The channels default mask. 352 */ 353 CHANNELS_DEFAULT_MASK 354 }ChannelsMask_t; 355 356 /*! 357 * Structure containing the beacon format 358 */ 359 typedef struct sBeaconFormat 360 { 361 /*! 362 * Size of the beacon 363 */ 364 uint8_t BeaconSize; 365 /*! 366 * Size of the RFU 1 data field 367 */ 368 uint8_t Rfu1Size; 369 /*! 370 * Size of the RFU 2 data field 371 */ 372 uint8_t Rfu2Size; 373 }BeaconFormat_t; 374 375 /*! 376 * Union for the structure uGetPhyParams 377 */ 378 typedef union uPhyParam 379 { 380 /*! 381 * A parameter value. 382 */ 383 uint32_t Value; 384 /*! 385 * A floating point value. 386 */ 387 float fValue; 388 /*! 389 * Pointer to the channels mask. 390 */ 391 uint16_t* ChannelsMask; 392 /*! 393 * Pointer to the channels. 394 */ 395 ChannelParams_t* Channels; 396 /*! 397 * Beacon format 398 */ 399 BeaconFormat_t BeaconFormat; 400 /*! 401 * Duty Cycle Period 402 */ 403 TimerTime_t DutyCycleTimePeriod; 404 }PhyParam_t; 405 406 /*! 407 * Parameter structure for the function RegionGetPhyParam. 408 */ 409 typedef struct sGetPhyParams 410 { 411 /*! 412 * Setup the parameter to get. 413 */ 414 PhyAttribute_t Attribute; 415 /*! 416 * Datarate. 417 * The parameter is needed for the following queries: 418 * PHY_MAX_PAYLOAD, PHY_NEXT_LOWER_TX_DR, PHY_SF_FROM_DR, PHY_BW_FROM_DR. 419 */ 420 int8_t Datarate; 421 /*! 422 * Uplink dwell time. This parameter must be set to query: 423 * PHY_MAX_PAYLOAD, PHY_MIN_TX_DR. 424 * The parameter is needed for the following queries: 425 * PHY_MIN_TX_DR, PHY_MAX_PAYLOAD, PHY_NEXT_LOWER_TX_DR. 426 */ 427 uint8_t UplinkDwellTime; 428 /*! 429 * Downlink dwell time. This parameter must be set to query: 430 * PHY_MAX_PAYLOAD, PHY_MIN_RX_DR. 431 * The parameter is needed for the following queries: 432 * PHY_MIN_RX_DR, PHY_MAX_PAYLOAD. 433 */ 434 uint8_t DownlinkDwellTime; 435 /*! 436 * Specification of the downlink channel. Used in Class B only. 437 * The parameter is needed for the following queries: 438 * PHY_BEACON_CHANNEL_FREQ, PHY_PING_SLOT_CHANNEL_FREQ 439 */ 440 uint8_t Channel; 441 }GetPhyParams_t; 442 443 /*! 444 * Parameter structure for the function RegionSetBandTxDone. 445 */ 446 typedef struct sSetBandTxDoneParams 447 { 448 /*! 449 * Channel to update. 450 */ 451 uint8_t Channel; 452 /*! 453 * Joined Set to true, if the node has joined the network 454 */ 455 bool Joined; 456 /*! 457 * Last TX done time. 458 */ 459 TimerTime_t LastTxDoneTime; 460 /*! 461 * Time-on-air of the last transmission. 462 */ 463 TimerTime_t LastTxAirTime; 464 /*! 465 * Elapsed time since initialization. 466 */ 467 SysTime_t ElapsedTimeSinceStartUp; 468 }SetBandTxDoneParams_t; 469 470 /*! 471 * Parameter structure for the function RegionInitDefaults. 472 */ 473 typedef struct sInitDefaultsParams 474 { 475 /*! 476 * Pointer to region NVM group1. 477 */ 478 void* NvmGroup1; 479 /*! 480 * Pointer to region NVM group2. 481 */ 482 void* NvmGroup2; 483 /*! 484 * Pointer to common region band storage. 485 */ 486 void* Bands; 487 /*! 488 * Sets the initialization type. 489 */ 490 InitType_t Type; 491 }InitDefaultsParams_t; 492 493 /*! 494 * Parameter structure for the function RegionVerify. 495 */ 496 typedef union uVerifyParams 497 { 498 /*! 499 * Channel frequency to verify 500 */ 501 uint32_t Frequency; 502 /*! 503 * TX power to verify. 504 */ 505 int8_t TxPower; 506 /*! 507 * Set to true, if the duty cycle is enabled, otherwise false. 508 */ 509 bool DutyCycle; 510 /*! 511 * Datarate to verify. 512 */ 513 struct sDatarateParams 514 { 515 /*! 516 * Datarate to verify. 517 */ 518 int8_t Datarate; 519 /*! 520 * The downlink dwell time. 521 */ 522 uint8_t DownlinkDwellTime; 523 /*! 524 * The up link dwell time. 525 */ 526 uint8_t UplinkDwellTime; 527 }DatarateParams; 528 }VerifyParams_t; 529 530 /*! 531 * Parameter structure for the function RegionApplyCFList. 532 */ 533 typedef struct sApplyCFListParams 534 { 535 uint8_t JoinChannel; 536 /*! 537 * Payload which contains the CF list. 538 */ 539 uint8_t* Payload; 540 /*! 541 * Size of the payload. 542 */ 543 uint8_t Size; 544 }ApplyCFListParams_t; 545 546 /*! 547 * Parameter structure for the function RegionChanMaskSet. 548 */ 549 typedef struct sChanMaskSetParams 550 { 551 /*! 552 * Pointer to the channels mask which should be set. 553 */ 554 uint16_t* ChannelsMaskIn; 555 /*! 556 * Pointer to the channels mask which should be set. 557 */ 558 ChannelsMask_t ChannelsMaskType; 559 }ChanMaskSetParams_t; 560 561 /*! 562 * Parameter structure for the function RegionRxConfig. 563 */ 564 typedef struct sRxConfigParams 565 { 566 /*! 567 * The RX channel. 568 */ 569 uint8_t Channel; 570 /*! 571 * RX datarate. 572 */ 573 int8_t Datarate; 574 /*! 575 * RX bandwidth. 576 */ 577 uint8_t Bandwidth; 578 /*! 579 * RX datarate offset. 580 */ 581 int8_t DrOffset; 582 /*! 583 * RX frequency. 584 */ 585 uint32_t Frequency; 586 /*! 587 * RX window timeout 588 */ 589 uint32_t WindowTimeout; 590 /*! 591 * RX window offset 592 */ 593 int32_t WindowOffset; 594 /*! 595 * Downlink dwell time. 596 */ 597 uint8_t DownlinkDwellTime; 598 /*! 599 * Set to true, if RX should be continuous. 600 */ 601 bool RxContinuous; 602 /*! 603 * Sets the RX window. 604 */ 605 LoRaMacRxSlot_t RxSlot; 606 /*! 607 * LoRaWAN Network End-Device Activation ( ACTIVATION_TYPE_NONE, ACTIVATION_TYPE_ABP 608 * or ACTIVATION_TYPE_OTTA ) 609 * 610 * Related MIB type: \ref MIB_NETWORK_ACTIVATION 611 */ 612 ActivationType_t NetworkActivation; 613 }RxConfigParams_t; 614 615 /*! 616 * Parameter structure for the function RegionTxConfig. 617 */ 618 typedef struct sTxConfigParams 619 { 620 /*! 621 * The TX channel. 622 */ 623 uint8_t Channel; 624 /*! 625 * The TX datarate. 626 */ 627 int8_t Datarate; 628 /*! 629 * The TX power. 630 */ 631 int8_t TxPower; 632 /*! 633 * The Max EIRP, if applicable. 634 */ 635 float MaxEirp; 636 /*! 637 * The antenna gain, if applicable. 638 */ 639 float AntennaGain; 640 /*! 641 * Frame length to setup. 642 */ 643 uint16_t PktLen; 644 }TxConfigParams_t; 645 646 /*! 647 * Parameter structure for the function RegionLinkAdrReq. 648 */ 649 typedef struct sLinkAdrReqParams 650 { 651 /*! 652 * Current LoRaWAN Version 653 */ 654 Version_t Version; 655 /*! 656 * Pointer to the payload which contains the MAC commands. 657 */ 658 uint8_t* Payload; 659 /*! 660 * Size of the payload. 661 */ 662 uint8_t PayloadSize; 663 /*! 664 * Uplink dwell time. 665 */ 666 uint8_t UplinkDwellTime; 667 /*! 668 * Set to true, if ADR is enabled. 669 */ 670 bool AdrEnabled; 671 /*! 672 * The current datarate. 673 */ 674 int8_t CurrentDatarate; 675 /*! 676 * The current TX power. 677 */ 678 int8_t CurrentTxPower; 679 /*! 680 * The current number of repetitions. 681 */ 682 uint8_t CurrentNbRep; 683 }LinkAdrReqParams_t; 684 685 /*! 686 * Parameter structure for the function RegionRxParamSetupReq. 687 */ 688 typedef struct sRxParamSetupReqParams 689 { 690 /*! 691 * The datarate to setup. 692 */ 693 int8_t Datarate; 694 /*! 695 * Datarate offset. 696 */ 697 int8_t DrOffset; 698 /*! 699 * The frequency to setup. 700 */ 701 uint32_t Frequency; 702 }RxParamSetupReqParams_t; 703 704 /*! 705 * Parameter structure for the function RegionNewChannelReq. 706 */ 707 typedef struct sNewChannelReqParams 708 { 709 /*! 710 * Pointer to the new channels. 711 */ 712 ChannelParams_t* NewChannel; 713 /*! 714 * Channel id. 715 */ 716 int8_t ChannelId; 717 }NewChannelReqParams_t; 718 719 /*! 720 * Parameter structure for the function RegionTxParamSetupReq. 721 */ 722 typedef struct sTxParamSetupReqParams 723 { 724 /*! 725 * Uplink dwell time. 726 */ 727 uint8_t UplinkDwellTime; 728 /*! 729 * Downlink dwell time. 730 */ 731 uint8_t DownlinkDwellTime; 732 /*! 733 * Max EIRP. 734 */ 735 uint8_t MaxEirp; 736 }TxParamSetupReqParams_t; 737 738 /*! 739 * Parameter structure for the function RegionDlChannelReq. 740 */ 741 typedef struct sDlChannelReqParams 742 { 743 /*! 744 * Channel Id to add the frequency. 745 */ 746 uint8_t ChannelId; 747 /*! 748 * Alternative frequency for the Rx1 window. 749 */ 750 uint32_t Rx1Frequency; 751 }DlChannelReqParams_t; 752 753 /*! 754 * Enumeration of alternation type 755 */ 756 typedef enum eAlternateDrType 757 { 758 /*! 759 * Type to use for an alternation 760 */ 761 ALTERNATE_DR, 762 /*! 763 * Type to use to restore one alternation 764 */ 765 ALTERNATE_DR_RESTORE 766 }AlternateDrType_t; 767 768 /*! 769 * Parameter structure for the function RegionNextChannel. 770 */ 771 typedef struct sNextChanParams 772 { 773 /*! 774 * Aggregated time-off time. 775 */ 776 TimerTime_t AggrTimeOff; 777 /*! 778 * Time of the last aggregated TX. 779 */ 780 TimerTime_t LastAggrTx; 781 /*! 782 * Current datarate. 783 */ 784 int8_t Datarate; 785 /*! 786 * Set to true, if the node has already joined a network, otherwise false. 787 */ 788 bool Joined; 789 /*! 790 * Set to true, if the duty cycle is enabled, otherwise false. 791 */ 792 bool DutyCycleEnabled; 793 /*! 794 * Elapsed time since the start of the node. 795 */ 796 SysTime_t ElapsedTimeSinceStartUp; 797 /*! 798 * Joined Set to true, if the last uplink was a join request 799 */ 800 bool LastTxIsJoinRequest; 801 /*! 802 * Payload length of the next frame 803 */ 804 uint16_t PktLen; 805 }NextChanParams_t; 806 807 /*! 808 * Parameter structure for the function RegionChannelsAdd. 809 */ 810 typedef struct sChannelAddParams 811 { 812 /*! 813 * Pointer to the new channel to add. 814 */ 815 ChannelParams_t* NewChannel; 816 /*! 817 * Channel id to add. 818 */ 819 uint8_t ChannelId; 820 }ChannelAddParams_t; 821 822 /*! 823 * Parameter structure for the function RegionChannelsRemove. 824 */ 825 typedef struct sChannelRemoveParams 826 { 827 /*! 828 * Channel id to remove. 829 */ 830 uint8_t ChannelId; 831 }ChannelRemoveParams_t; 832 833 /*! 834 * Parameter structure for the function RegionRxBeaconSetup 835 */ 836 typedef struct sRxBeaconSetupParams 837 { 838 /*! 839 * Symbol timeout. 840 */ 841 uint16_t SymbolTimeout; 842 /*! 843 * Receive time. 844 */ 845 uint32_t RxTime; 846 /*! 847 * The frequency to setup. 848 */ 849 uint32_t Frequency; 850 }RxBeaconSetup_t; 851 852 853 854 /*! 855 * \brief The function verifies if a region is active or not. If a region 856 * is not active, it cannot be used. 857 * 858 * \param [IN] region LoRaWAN region. 859 * 860 * \retval Return true, if the region is supported. 861 */ 862 bool RegionIsActive( LoRaMacRegion_t region ); 863 864 /*! 865 * \brief The function gets a value of a specific phy attribute. 866 * 867 * \param [IN] region LoRaWAN region. 868 * 869 * \param [IN] getPhy Pointer to the function parameters. 870 * 871 * \retval Returns a structure containing the PHY parameter. 872 */ 873 PhyParam_t RegionGetPhyParam( LoRaMacRegion_t region, GetPhyParams_t* getPhy ); 874 875 /*! 876 * \brief Updates the last TX done parameters of the current channel. 877 * 878 * \param [IN] region LoRaWAN region. 879 * 880 * \param [IN] txDone Pointer to the function parameters. 881 */ 882 void RegionSetBandTxDone( LoRaMacRegion_t region, SetBandTxDoneParams_t* txDone ); 883 884 /*! 885 * \brief Initializes the channels masks and the channels. 886 * 887 * \param [IN] region LoRaWAN region. 888 * 889 * \param [IN] params Pointer to the function parameters. 890 */ 891 void RegionInitDefaults( LoRaMacRegion_t region, InitDefaultsParams_t* params ); 892 893 /*! 894 * \brief Verifies a parameter. 895 * 896 * \param [IN] region LoRaWAN region. 897 * 898 * \param [IN] verify Pointer to the function parameters. 899 * 900 * \param [IN] type Sets the initialization type. 901 * 902 * \retval Returns true, if the parameter is valid. 903 */ 904 bool RegionVerify( LoRaMacRegion_t region, VerifyParams_t* verify, PhyAttribute_t phyAttribute ); 905 906 /*! 907 * \brief The function parses the input buffer and sets up the channels of the 908 * CF list. 909 * 910 * \param [IN] region LoRaWAN region. 911 * 912 * \param [IN] applyCFList Pointer to the function parameters. 913 */ 914 void RegionApplyCFList( LoRaMacRegion_t region, ApplyCFListParams_t* applyCFList ); 915 916 /*! 917 * \brief Sets a channels mask. 918 * 919 * \param [IN] region LoRaWAN region. 920 * 921 * \param [IN] chanMaskSet Pointer to the function parameters. 922 * 923 * \retval Returns true, if the channels mask could be set. 924 */ 925 bool RegionChanMaskSet( LoRaMacRegion_t region, ChanMaskSetParams_t* chanMaskSet ); 926 927 /*! 928 * \brief Configuration of the RX windows. 929 * 930 * \param [IN] region LoRaWAN region. 931 * 932 * \param [IN] rxConfig Pointer to the function parameters. 933 * 934 * \param [OUT] datarate The datarate index which was set. 935 * 936 * \retval Returns true, if the configuration was applied successfully. 937 */ 938 bool RegionRxConfig( LoRaMacRegion_t region, RxConfigParams_t* rxConfig, int8_t* datarate ); 939 940 /* 941 * Rx window precise timing 942 * 943 * For more details please consult the following document, chapter 3.1.2. 944 * https://www.semtech.com/uploads/documents/SX1272_settings_for_LoRaWAN_v2.0.pdf 945 * or 946 * https://www.semtech.com/uploads/documents/SX1276_settings_for_LoRaWAN_v2.0.pdf 947 * 948 * Downlink start: T = Tx + 1s (+/- 20 us) 949 * | 950 * TRxEarly | TRxLate 951 * | | | 952 * | | +---+---+---+---+---+---+---+---+ 953 * | | | Latest Rx window | 954 * | | +---+---+---+---+---+---+---+---+ 955 * | | | 956 * +---+---+---+---+---+---+---+---+ 957 * | Earliest Rx window | 958 * +---+---+---+---+---+---+---+---+ 959 * | 960 * +---+---+---+---+---+---+---+---+ 961 *Downlink preamble 8 symbols | | | | | | | | | 962 * +---+---+---+---+---+---+---+---+ 963 * 964 * Worst case Rx window timings 965 * 966 * TRxLate = DEFAULT_MIN_RX_SYMBOLS * tSymbol - RADIO_WAKEUP_TIME 967 * TRxEarly = 8 - DEFAULT_MIN_RX_SYMBOLS * tSymbol - RxWindowTimeout - RADIO_WAKEUP_TIME 968 * 969 * TRxLate - TRxEarly = 2 * DEFAULT_SYSTEM_MAX_RX_ERROR 970 * 971 * RxOffset = ( TRxLate + TRxEarly ) / 2 972 * 973 * RxWindowTimeout = ( 2 * DEFAULT_MIN_RX_SYMBOLS - 8 ) * tSymbol + 2 * DEFAULT_SYSTEM_MAX_RX_ERROR 974 * RxOffset = 4 * tSymbol - RxWindowTimeout / 2 - RADIO_WAKE_UP_TIME 975 * 976 * Minimal value of RxWindowTimeout must be 5 symbols which implies that the system always tolerates at least an error of 1.5 * tSymbol 977 */ 978 /*! 979 * Computes the Rx window timeout and offset. 980 * 981 * \param [IN] region LoRaWAN region. 982 * 983 * \param [IN] datarate Rx window datarate index to be used 984 * 985 * \param [IN] minRxSymbols Minimum required number of symbols to detect an Rx frame. 986 * 987 * \param [IN] rxError System maximum timing error of the receiver. In milliseconds 988 * The receiver will turn on in a [-rxError : +rxError] ms 989 * interval around RxOffset 990 * 991 * \param [OUT]rxConfigParams Returns updated WindowTimeout and WindowOffset fields. 992 */ 993 void RegionComputeRxWindowParameters( LoRaMacRegion_t region, int8_t datarate, uint8_t minRxSymbols, uint32_t rxError, RxConfigParams_t *rxConfigParams ); 994 995 /*! 996 * \brief TX configuration. 997 * 998 * \param [IN] region LoRaWAN region. 999 * 1000 * \param [IN] txConfig Pointer to the function parameters. 1001 * 1002 * \param [OUT] txPower The tx power index which was set. 1003 * 1004 * \param [OUT] txTimeOnAir The time-on-air of the frame. 1005 * 1006 * \retval Returns true, if the configuration was applied successfully. 1007 */ 1008 bool RegionTxConfig( LoRaMacRegion_t region, TxConfigParams_t* txConfig, int8_t* txPower, TimerTime_t* txTimeOnAir ); 1009 1010 /*! 1011 * \brief The function processes a Link ADR Request. 1012 * 1013 * \param [IN] region LoRaWAN region. 1014 * 1015 * \param [IN] linkAdrReq Pointer to the function parameters. 1016 * 1017 * \param [OUT] drOut The datarate which was applied. 1018 * 1019 * \param [OUT] txPowOut The TX power which was applied. 1020 * 1021 * \param [OUT] nbRepOut The number of repetitions to apply. 1022 * 1023 * \param [OUT] nbBytesParsed The number bytes which were parsed. 1024 * 1025 * \retval Returns the status of the operation, according to the LoRaMAC specification. 1026 */ 1027 uint8_t RegionLinkAdrReq( LoRaMacRegion_t region, LinkAdrReqParams_t* linkAdrReq, int8_t* drOut, int8_t* txPowOut, uint8_t* nbRepOut, uint8_t* nbBytesParsed ); 1028 1029 /*! 1030 * \brief The function processes a RX Parameter Setup Request. 1031 * 1032 * \param [IN] region LoRaWAN region. 1033 * 1034 * \param [IN] rxParamSetupReq Pointer to the function parameters. 1035 * 1036 * \retval Returns the status of the operation, according to the LoRaMAC specification. 1037 */ 1038 uint8_t RegionRxParamSetupReq( LoRaMacRegion_t region, RxParamSetupReqParams_t* rxParamSetupReq ); 1039 1040 /*! 1041 * \brief The function processes a New Channel Request. 1042 * 1043 * \param [IN] region LoRaWAN region. 1044 * 1045 * \param [IN] newChannelReq Pointer to the function parameters. 1046 * 1047 * \retval Returns the status of the operation, according to the LoRaMAC specification. 1048 */ 1049 int8_t RegionNewChannelReq( LoRaMacRegion_t region, NewChannelReqParams_t* newChannelReq ); 1050 1051 /*! 1052 * \brief The function processes a TX ParamSetup Request. 1053 * 1054 * \param [IN] region LoRaWAN region. 1055 * 1056 * \param [IN] txParamSetupReq Pointer to the function parameters. 1057 * 1058 * \retval Returns the status of the operation, according to the LoRaMAC specification. 1059 * Returns -1, if the functionality is not implemented. In this case, the end node 1060 * shall ignore the command. 1061 */ 1062 int8_t RegionTxParamSetupReq( LoRaMacRegion_t region, TxParamSetupReqParams_t* txParamSetupReq ); 1063 1064 /*! 1065 * \brief The function processes a DlChannel Request. 1066 * 1067 * \param [IN] region LoRaWAN region. 1068 * 1069 * \param [IN] dlChannelReq Pointer to the function parameters. 1070 * 1071 * \retval Returns the status of the operation, according to the LoRaMAC specification. 1072 */ 1073 int8_t RegionDlChannelReq( LoRaMacRegion_t region, DlChannelReqParams_t* dlChannelReq ); 1074 1075 /*! 1076 * \brief Alternates the datarate of the channel for the join request. 1077 * 1078 * \param [IN] region LoRaWAN region. 1079 * 1080 * \param [IN] currentDr Current datarate. 1081 * 1082 * \param [IN] type Alternation type. 1083 * 1084 * \retval Datarate to apply. 1085 */ 1086 int8_t RegionAlternateDr( LoRaMacRegion_t region, int8_t currentDr, AlternateDrType_t type ); 1087 1088 /*! 1089 * \brief Searches and set the next random available channel 1090 * 1091 * \param [IN] region LoRaWAN region. 1092 * 1093 * \param [OUT] channel Next channel to use for TX. 1094 * 1095 * \param [OUT] time Time to wait for the next transmission according to the duty 1096 * cycle. 1097 * 1098 * \param [OUT] aggregatedTimeOff Updates the aggregated time off. 1099 * 1100 * \retval Function status [1: OK, 0: Unable to find a channel on the current datarate]. 1101 */ 1102 LoRaMacStatus_t RegionNextChannel( LoRaMacRegion_t region, NextChanParams_t* nextChanParams, uint8_t* channel, TimerTime_t* time, TimerTime_t* aggregatedTimeOff ); 1103 1104 /*! 1105 * \brief Adds a channel. 1106 * 1107 * \param [IN] region LoRaWAN region. 1108 * 1109 * \param [IN] channelAdd Pointer to the function parameters. 1110 * 1111 * \retval Status of the operation. 1112 */ 1113 LoRaMacStatus_t RegionChannelAdd( LoRaMacRegion_t region, ChannelAddParams_t* channelAdd ); 1114 1115 /*! 1116 * \brief Removes a channel. 1117 * 1118 * \param [IN] region LoRaWAN region. 1119 * 1120 * \param [IN] channelRemove Pointer to the function parameters. 1121 * 1122 * \retval Returns true, if the channel was removed successfully. 1123 */ 1124 bool RegionChannelsRemove( LoRaMacRegion_t region, ChannelRemoveParams_t* channelRemove ); 1125 1126 /*! 1127 * \brief Computes new datarate according to the given offset 1128 * 1129 * \param [IN] downlinkDwellTime Downlink dwell time configuration. 0: No limit, 1: 400ms 1130 * 1131 * \param [IN] dr Current datarate 1132 * 1133 * \param [IN] drOffset Offset to be applied 1134 * 1135 * \retval newDr Computed datarate. 1136 */ 1137 uint8_t RegionApplyDrOffset( LoRaMacRegion_t region, uint8_t downlinkDwellTime, int8_t dr, int8_t drOffset ); 1138 1139 /*! 1140 * \brief Sets the radio into beacon reception mode 1141 * 1142 * \param [IN] rxBeaconSetup Pointer to the function parameters 1143 * 1144 * \param [out] outDr Datarate used to receive the beacon 1145 */ 1146 void RegionRxBeaconSetup( LoRaMacRegion_t region, RxBeaconSetup_t* rxBeaconSetup, uint8_t* outDr ); 1147 1148 /*! 1149 * \brief Gets the version of the regional parameters implementation. 1150 * 1151 * \retval Version of the regional parameters. 1152 */ 1153 Version_t RegionGetVersion( void ); 1154 1155 /*! \} defgroup REGION */ 1156 1157 #ifdef __cplusplus 1158 } 1159 #endif 1160 1161 #endif // __REGION_H__ 1162
