1 /*! 2 * \file LoRaMac.h 3 * 4 * \brief LoRa MAC layer 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 * \author Johannes Bruder ( STACKFORCE ) 32 * 33 * \defgroup LORAMAC LoRa MAC layer implementation 34 * This module specifies the API implementation of the LoRaMAC layer. 35 * This is a placeholder for a detailed description of the LoRaMac 36 * layer and the supported features. 37 * \{ 38 * 39 * \example periodic-uplink-lpp/B-L072Z-LRWAN1/main.c 40 * LoRaWAN class A/B/C application example for the B-L072Z-LRWAN1. 41 * 42 * \example periodic-uplink-lpp/NAMote72/main.c 43 * LoRaWAN class A/B/C application example for the NAMote72. 44 * 45 * \example periodic-uplink-lpp/NucleoL073/main.c 46 * LoRaWAN class A/B/C application example for the NucleoL073. 47 * 48 * \example periodic-uplink-lpp/NucleoL152/main.c 49 * LoRaWAN class A/B/C application example for the NucleoL152. 50 * 51 * \example periodic-uplink-lpp/NucleoL476/main.c 52 * LoRaWAN class A/B/C application example for the NucleoL476. 53 * 54 * \example periodic-uplink-lpp/SAMR34/main.c 55 * LoRaWAN class A/B/C application example for the SAMR34. 56 * 57 * \example periodic-uplink-lpp/SKiM880B/main.c 58 * LoRaWAN class A/B/C application example for the SKiM880B. 59 * 60 * \example periodic-uplink-lpp/SKiM881AXL/main.c 61 * LoRaWAN class A/B/C application example for the SKiM881AXL. 62 * 63 * \example periodic-uplink-lpp/SKiM980A/main.c 64 * LoRaWAN class A/B/C application example for the SKiM980A. 65 */ 66 #ifndef __LORAMAC_H__ 67 #define __LORAMAC_H__ 68 69 #ifdef __cplusplus 70 extern "C" 71 { 72 #endif 73 74 #include <stdint.h> 75 #include <stdbool.h> 76 77 #include "timer.h" 78 #include "systime.h" 79 #include "LoRaMacTypes.h" 80 81 #include "RegionNvm.h" 82 #include "LoRaMacCryptoNvm.h" 83 #include "secure-element-nvm.h" 84 #include "LoRaMacClassBNvm.h" 85 86 /*! 87 * Maximum number of times the MAC layer tries to get an acknowledge. 88 */ 89 #define MAX_ACK_RETRIES 8 90 91 /*! 92 * Frame direction definition for up-link communications 93 */ 94 #define UP_LINK 0 95 96 /*! 97 * Frame direction definition for down-link communications 98 */ 99 #define DOWN_LINK 1 100 101 /*! 102 * LoRaMac MLME-Confirm queue length 103 */ 104 #define LORA_MAC_MLME_CONFIRM_QUEUE_LEN 5 105 106 /*! 107 * Start value for multicast keys enumeration 108 */ 109 #define LORAMAC_CRYPTO_MULTICAST_KEYS 127 110 111 /*! 112 * Maximum MAC commands buffer size 113 */ 114 #define LORA_MAC_COMMAND_MAX_LENGTH 128 115 116 117 /*! 118 * Bitmap value 119 */ 120 #define LORAMAC_NVM_NOTIFY_FLAG_NONE 0x00 121 122 /*! 123 * Bitmap value for the NVM group crypto. 124 */ 125 #define LORAMAC_NVM_NOTIFY_FLAG_CRYPTO 0x01 126 127 /*! 128 * Bitmap value for the NVM group MAC 1. 129 */ 130 #define LORAMAC_NVM_NOTIFY_FLAG_MAC_GROUP1 0x02 131 132 /*! 133 * Bitmap value for the NVM group MAC 2. 134 */ 135 #define LORAMAC_NVM_NOTIFY_FLAG_MAC_GROUP2 0x04 136 137 /*! 138 * Bitmap value for the NVM group secure element. 139 */ 140 #define LORAMAC_NVM_NOTIFY_FLAG_SECURE_ELEMENT 0x08 141 142 /*! 143 * Bitmap value for the NVM group 1 region. 144 */ 145 #define LORAMAC_NVM_NOTIFY_FLAG_REGION_GROUP1 0x10 146 147 /*! 148 * Bitmap value for the NVM group 2 region. 149 */ 150 #define LORAMAC_NVM_NOTIFY_FLAG_REGION_GROUP2 0x20 151 152 /*! 153 * Bitmap value for the NVM group class b. 154 */ 155 #define LORAMAC_NVM_NOTIFY_FLAG_CLASS_B 0x40 156 157 /*! 158 * LoRaWAN compliance certification protocol port number. 159 * 160 * LoRaWAN Specification V1.x.x, chapter 4.3.2 161 */ 162 #define LORAMAC_CERT_FPORT 224 163 164 /*! 165 * End-Device activation type 166 */ 167 typedef enum eActivationType 168 { 169 /*! 170 * None 171 */ 172 ACTIVATION_TYPE_NONE = 0, 173 /*! 174 * Activation By Personalization (ACTIVATION_TYPE_ABP) 175 */ 176 ACTIVATION_TYPE_ABP = 1, 177 /*! 178 * Over-The-Air Activation (ACTIVATION_TYPE_OTAA) 179 */ 180 ACTIVATION_TYPE_OTAA = 2, 181 }ActivationType_t; 182 183 /*! 184 * LoRaMAC receive window channel parameters 185 */ 186 typedef struct sRxChannelParams 187 { 188 /*! 189 * Frequency in Hz 190 */ 191 uint32_t Frequency; 192 /*! 193 * Data rate 194 * 195 * LoRaWAN Regional Parameters V1.0.2rB 196 * 197 * The allowed ranges are region specific. Please refer to \ref DR_0 to \ref DR_15 for details. 198 */ 199 uint8_t Datarate; 200 }RxChannelParams_t; 201 202 /*! 203 * LoRaMAC receive window enumeration 204 */ 205 typedef enum eLoRaMacRxSlot 206 { 207 /*! 208 * LoRaMAC receive window 1 209 */ 210 RX_SLOT_WIN_1, 211 /*! 212 * LoRaMAC receive window 2 213 */ 214 RX_SLOT_WIN_2, 215 /*! 216 * LoRaMAC receive window 2 for class c - continuous listening 217 */ 218 RX_SLOT_WIN_CLASS_C, 219 /*! 220 * LoRaMAC class c multicast downlink 221 */ 222 RX_SLOT_WIN_CLASS_C_MULTICAST, 223 /*! 224 * LoRaMAC class b ping slot window 225 */ 226 RX_SLOT_WIN_CLASS_B_PING_SLOT, 227 /*! 228 * LoRaMAC class b multicast slot window 229 */ 230 RX_SLOT_WIN_CLASS_B_MULTICAST_SLOT, 231 /*! 232 * LoRaMAC no active receive window 233 */ 234 RX_SLOT_NONE, 235 }LoRaMacRxSlot_t; 236 237 /*! 238 * Global MAC layer parameters 239 */ 240 typedef struct sLoRaMacParams 241 { 242 /*! 243 * System overall timing error in milliseconds. 244 * [-SystemMaxRxError : +SystemMaxRxError] 245 * Default: +/-10 ms 246 */ 247 uint32_t SystemMaxRxError; 248 /*! 249 * Minimum required number of symbols to detect an Rx frame 250 * Default: 6 symbols 251 */ 252 uint8_t MinRxSymbols; 253 /*! 254 * LoRaMac maximum time a reception window stays open 255 */ 256 uint32_t MaxRxWindow; 257 /*! 258 * Receive delay 1 259 */ 260 uint32_t ReceiveDelay1; 261 /*! 262 * Receive delay 2 263 */ 264 uint32_t ReceiveDelay2; 265 /*! 266 * Join accept delay 1 267 */ 268 uint32_t JoinAcceptDelay1; 269 /*! 270 * Join accept delay 1 271 */ 272 uint32_t JoinAcceptDelay2; 273 /*! 274 * Number of uplink messages repetitions [1:15] (unconfirmed messages only) 275 */ 276 uint8_t ChannelsNbTrans; 277 /*! 278 * Datarate offset between uplink and downlink on first window 279 */ 280 uint8_t Rx1DrOffset; 281 /*! 282 * LoRaMAC 2nd reception window settings 283 */ 284 RxChannelParams_t Rx2Channel; 285 /*! 286 * LoRaMAC continuous reception window settings 287 */ 288 RxChannelParams_t RxCChannel; 289 /*! 290 * Uplink dwell time configuration. 0: No limit, 1: 400ms 291 */ 292 uint8_t UplinkDwellTime; 293 /*! 294 * Downlink dwell time configuration. 0: No limit, 1: 400ms 295 */ 296 uint8_t DownlinkDwellTime; 297 /*! 298 * Maximum possible EIRP 299 */ 300 float MaxEirp; 301 /*! 302 * Antenna gain of the node 303 */ 304 float AntennaGain; 305 }LoRaMacParams_t; 306 307 /*! 308 * LoRaMAC data structure for a PingSlotInfoReq \ref MLME_PING_SLOT_INFO 309 * 310 * LoRaWAN Specification 311 */ 312 typedef union uPingSlotInfo 313 { 314 /*! 315 * Parameter for byte access 316 */ 317 uint8_t Value; 318 /*! 319 * Structure containing the parameters for the PingSlotInfoReq 320 */ 321 struct sInfoFields 322 { 323 /*! 324 * Periodicity = 0: ping slot every second 325 * Periodicity = 7: ping slot every 128 seconds 326 */ 327 uint8_t Periodicity : 3; 328 /*! 329 * RFU 330 */ 331 uint8_t RFU : 5; 332 }Fields; 333 }PingSlotInfo_t; 334 335 /*! 336 * LoRaMAC data structure for the \ref MLME_BEACON MLME-Indication 337 * 338 * LoRaWAN Specification 339 */ 340 typedef struct sBeaconInfo 341 { 342 /*! 343 * Timestamp in seconds since 00:00:00, Sunday 6th of January 1980 344 * (start of the GPS epoch) modulo 2^32 345 */ 346 SysTime_t Time; 347 /*! 348 * Frequency 349 */ 350 uint32_t Frequency; 351 /*! 352 * Datarate 353 */ 354 uint8_t Datarate; 355 /*! 356 * RSSI 357 */ 358 int16_t Rssi; 359 /*! 360 * SNR 361 */ 362 int8_t Snr; 363 /*! 364 * Param 365 * | Bits | 7:2 | 1:0 | 366 * |-------|-----|------| 367 * | Param | RFU | Prec | 368 * 369 * Prec field is used to interpret the precision of beacon's transmit time 370 * as 10^(-6+prec) and the default value is 0. 371 * RFU will be set to Zero and Prec can take values between 0:3. 372 */ 373 uint8_t Param; 374 /*! 375 * Data structure for the gateway specific part. The 376 * content of the values may differ for each gateway 377 */ 378 struct sGwSpecific 379 { 380 /*! 381 * Info descriptor - can differ for each gateway 382 */ 383 uint8_t InfoDesc; 384 /*! 385 * Info - can differ for each gateway 386 */ 387 uint8_t Info[6]; 388 }GwSpecific; 389 }BeaconInfo_t; 390 391 /*! 392 * Enumeration containing the status of the operation of a MAC service 393 */ 394 typedef enum eLoRaMacEventInfoStatus 395 { 396 /*! 397 * Service performed successfully 398 */ 399 LORAMAC_EVENT_INFO_STATUS_OK = 0, 400 /*! 401 * An error occurred during the execution of the service 402 */ 403 LORAMAC_EVENT_INFO_STATUS_ERROR, 404 /*! 405 * A Tx timeout occurred 406 */ 407 LORAMAC_EVENT_INFO_STATUS_TX_TIMEOUT, 408 /*! 409 * An Rx timeout occurred on receive window 1 410 */ 411 LORAMAC_EVENT_INFO_STATUS_RX1_TIMEOUT, 412 /*! 413 * An Rx timeout occurred on receive window 2 414 */ 415 LORAMAC_EVENT_INFO_STATUS_RX2_TIMEOUT, 416 /*! 417 * An Rx error occurred on receive window 1 418 */ 419 LORAMAC_EVENT_INFO_STATUS_RX1_ERROR, 420 /*! 421 * An Rx error occurred on receive window 2 422 */ 423 LORAMAC_EVENT_INFO_STATUS_RX2_ERROR, 424 /*! 425 * An error occurred in the join procedure 426 */ 427 LORAMAC_EVENT_INFO_STATUS_JOIN_FAIL, 428 /*! 429 * A frame with an invalid downlink counter was received. The 430 * downlink counter of the frame was equal to the local copy 431 * of the downlink counter of the node. 432 */ 433 LORAMAC_EVENT_INFO_STATUS_DOWNLINK_REPEATED, 434 /*! 435 * The MAC could not retransmit a frame since the MAC decreased the datarate. The 436 * payload size is not applicable for the datarate. 437 */ 438 LORAMAC_EVENT_INFO_STATUS_TX_DR_PAYLOAD_SIZE_ERROR, 439 /*! 440 * An address error occurred 441 */ 442 LORAMAC_EVENT_INFO_STATUS_ADDRESS_FAIL, 443 /*! 444 * Message integrity check failure 445 */ 446 LORAMAC_EVENT_INFO_STATUS_MIC_FAIL, 447 /*! 448 * ToDo 449 */ 450 LORAMAC_EVENT_INFO_STATUS_MULTICAST_FAIL, 451 /*! 452 * ToDo 453 */ 454 LORAMAC_EVENT_INFO_STATUS_BEACON_LOCKED, 455 /*! 456 * ToDo 457 */ 458 LORAMAC_EVENT_INFO_STATUS_BEACON_LOST, 459 /*! 460 * ToDo 461 */ 462 LORAMAC_EVENT_INFO_STATUS_BEACON_NOT_FOUND, 463 }LoRaMacEventInfoStatus_t; 464 465 /*! 466 * LoRaMac tx/rx operation state 467 */ 468 typedef union eLoRaMacFlags_t 469 { 470 /*! 471 * Byte-access to the bits 472 */ 473 uint8_t Value; 474 /*! 475 * Structure containing single access to bits 476 */ 477 struct sMacFlagBits 478 { 479 /*! 480 * MCPS-Req pending 481 */ 482 uint8_t McpsReq : 1; 483 /*! 484 * MCPS-Ind pending 485 */ 486 uint8_t McpsInd : 1; 487 /*! 488 * MLME-Req pending 489 */ 490 uint8_t MlmeReq : 1; 491 /*! 492 * MLME-Ind pending 493 */ 494 uint8_t MlmeInd : 1; 495 /*! 496 * MLME-Ind to schedule an uplink pending 497 */ 498 uint8_t MlmeSchedUplinkInd : 1; 499 /*! 500 * MAC cycle done 501 */ 502 uint8_t MacDone : 1; 503 /*! 504 * Indicate if a NVM handling is required 505 */ 506 uint8_t NvmHandle : 1; 507 }Bits; 508 }LoRaMacFlags_t; 509 510 /*! 511 * LoRaMAC region enumeration 512 */ 513 typedef enum eLoRaMacRegion 514 { 515 /*! 516 * AS band on 923MHz 517 */ 518 LORAMAC_REGION_AS923, 519 /*! 520 * Australian band on 915MHz 521 */ 522 LORAMAC_REGION_AU915, 523 /*! 524 * Chinese band on 470MHz 525 */ 526 LORAMAC_REGION_CN470, 527 /*! 528 * Chinese band on 779MHz 529 */ 530 LORAMAC_REGION_CN779, 531 /*! 532 * European band on 433MHz 533 */ 534 LORAMAC_REGION_EU433, 535 /*! 536 * European band on 868MHz 537 */ 538 LORAMAC_REGION_EU868, 539 /*! 540 * South korean band on 920MHz 541 */ 542 LORAMAC_REGION_KR920, 543 /*! 544 * India band on 865MHz 545 */ 546 LORAMAC_REGION_IN865, 547 /*! 548 * North american band on 915MHz 549 */ 550 LORAMAC_REGION_US915, 551 /*! 552 * Russia band on 864MHz 553 */ 554 LORAMAC_REGION_RU864, 555 }LoRaMacRegion_t; 556 557 typedef struct sLoRaMacNvmDataGroup1 558 { 559 /*! 560 * Counts the number of missed ADR acknowledgements 561 */ 562 uint32_t AdrAckCounter; 563 /*! 564 * Last transmission time. 565 */ 566 TimerTime_t LastTxDoneTime; 567 /*! 568 * Aggregated time off. 569 */ 570 TimerTime_t AggregatedTimeOff; 571 /*! 572 * Last received Message integrity Code (MIC) 573 */ 574 uint32_t LastRxMic; 575 /*! 576 * Channels TX power 577 */ 578 int8_t ChannelsTxPower; 579 /*! 580 * Channels data rate 581 */ 582 int8_t ChannelsDatarate; 583 /*! 584 * If the server has sent a FRAME_TYPE_DATA_CONFIRMED_DOWN this variable indicates 585 * if the ACK bit must be set for the next transmission 586 */ 587 bool SrvAckRequested; 588 /*! 589 * CRC32 value of the MacGroup1 data structure. 590 */ 591 uint32_t Crc32; 592 }LoRaMacNvmDataGroup1_t; 593 594 typedef struct sLoRaMacNvmDataGroup2 595 { 596 /* 597 * LoRaMac region. 598 */ 599 LoRaMacRegion_t Region; 600 /* 601 * LoRaMac parameters 602 */ 603 LoRaMacParams_t MacParams; 604 /* 605 * LoRaMac default parameters 606 */ 607 LoRaMacParams_t MacParamsDefaults; 608 /*! 609 * Channels TX power 610 */ 611 int8_t ChannelsTxPowerDefault; 612 /*! 613 * Channels data rate 614 */ 615 int8_t ChannelsDatarateDefault; 616 /* 617 * Network ID ( 3 bytes ) 618 */ 619 uint32_t NetID; 620 /* 621 * Mote Address 622 */ 623 uint32_t DevAddr; 624 /*! 625 * Multicast channel list 626 */ 627 MulticastCtx_t MulticastChannelList[LORAMAC_MAX_MC_CTX]; 628 /* 629 * Actual device class 630 */ 631 DeviceClass_t DeviceClass; 632 /* 633 * Indicates if the node is connected to 634 * a private or public network 635 */ 636 bool PublicNetwork; 637 /* 638 * LoRaMac ADR control status 639 */ 640 bool AdrCtrlOn; 641 /* 642 * Maximum duty cycle 643 * \remark Possibility to shutdown the device. 644 */ 645 uint8_t MaxDCycle; 646 /* 647 * Enables/Disables duty cycle management (Test only) 648 */ 649 bool DutyCycleOn; 650 /* 651 * Set to true, if the datarate was increased 652 * with a link adr request. 653 */ 654 bool ChannelsDatarateChangedLinkAdrReq; 655 /* 656 * The stack will set this variable to true, if a downlink has been received. 657 */ 658 bool DownlinkReceived; 659 /* 660 * Enables/disable FPort 224 processing (certification port) 661 */ 662 bool IsCertPortOn; 663 /* 664 * Aggregated duty cycle management 665 */ 666 uint16_t AggregatedDCycle; 667 /* 668 * Stores the time at LoRaMac initialization. 669 * 670 * \remark Used for the BACKOFF_DC computation. 671 */ 672 SysTime_t InitializationTime; 673 /* 674 * Current LoRaWAN Version 675 */ 676 Version_t Version; 677 /* 678 * End-Device network activation 679 */ 680 ActivationType_t NetworkActivation; 681 /*! 682 * CRC32 value of the MacGroup2 data structure. 683 */ 684 uint32_t Crc32; 685 }LoRaMacNvmDataGroup2_t; 686 687 /*! 688 * LoRaMAC data structure for non-volatile memory (NVM). 689 * This structure contains data which must be stored in NVM. 690 */ 691 typedef struct sLoRaMacNvmData 692 { 693 /*! 694 * Parameters related to the crypto layer. Change with every TX/RX 695 * procedure. 696 */ 697 LoRaMacCryptoNvmData_t Crypto; 698 /*! 699 * Parameters related to the MAC which change with high probability after 700 * every TX/RX procedure. 701 */ 702 LoRaMacNvmDataGroup1_t MacGroup1; 703 /*! 704 * Parameters related to the MAC which do not change very likely with every 705 * TX/RX procedure. 706 */ 707 LoRaMacNvmDataGroup2_t MacGroup2; 708 /*! 709 * Parameters related to the secure-element. 710 */ 711 SecureElementNvmData_t SecureElement; 712 /*! 713 * Parameters related to the regional implementation which change with high 714 * probability after every TX/RX procedure. 715 */ 716 RegionNvmDataGroup1_t RegionGroup1; 717 /*! 718 * Parameters related to the regional implementation which do not change 719 * very likely with every TX/RX procedure. 720 */ 721 RegionNvmDataGroup2_t RegionGroup2; 722 /*! 723 * Parameters related to class b. 724 */ 725 LoRaMacClassBNvmData_t ClassB; 726 }LoRaMacNvmData_t; 727 728 /*! 729 * 730 * \brief LoRaMAC data services 731 * 732 * \details The following table list the primitives which are supported by the 733 * specific MAC data service: 734 * 735 * Name | Request | Indication | Response | Confirm 736 * --------------------- | :-----: | :--------: | :------: | :-----: 737 * \ref MCPS_UNCONFIRMED | YES | YES | NO | YES 738 * \ref MCPS_CONFIRMED | YES | YES | NO | YES 739 * \ref MCPS_MULTICAST | NO | YES | NO | NO 740 * \ref MCPS_PROPRIETARY | YES | YES | NO | YES 741 * 742 * The following table provides links to the function implementations of the 743 * related MCPS primitives: 744 * 745 * Primitive | Function 746 * ---------------- | :---------------------: 747 * MCPS-Request | \ref LoRaMacMlmeRequest 748 * MCPS-Confirm | MacMcpsConfirm in \ref LoRaMacPrimitives_t 749 * MCPS-Indication | MacMcpsIndication in \ref LoRaMacPrimitives_t 750 */ 751 typedef enum eMcps 752 { 753 /*! 754 * Unconfirmed LoRaMAC frame 755 */ 756 MCPS_UNCONFIRMED, 757 /*! 758 * Confirmed LoRaMAC frame 759 */ 760 MCPS_CONFIRMED, 761 /*! 762 * Multicast LoRaMAC frame 763 */ 764 MCPS_MULTICAST, 765 /*! 766 * Proprietary frame 767 */ 768 MCPS_PROPRIETARY, 769 }Mcps_t; 770 771 /*! 772 * Structure which defines return parameters for requests. 773 */ 774 typedef struct sRequestReturnParam 775 { 776 /*! 777 * This value reports the time in milliseconds which 778 * an application must wait before its possible to send 779 * the next uplink. 780 */ 781 TimerTime_t DutyCycleWaitTime; 782 }RequestReturnParam_t; 783 784 /*! 785 * LoRaMAC MCPS-Request for an unconfirmed frame 786 */ 787 typedef struct sMcpsReqUnconfirmed 788 { 789 /*! 790 * Frame port field. Must be set if the payload is not empty. Use the 791 * application specific frame port values: [1...223] 792 * 793 * LoRaWAN Specification V1.0.2, chapter 4.3.2 794 */ 795 uint8_t fPort; 796 /*! 797 * Pointer to the buffer of the frame payload 798 */ 799 void* fBuffer; 800 /*! 801 * Size of the frame payload 802 */ 803 uint16_t fBufferSize; 804 /*! 805 * Uplink datarate, if ADR is off 806 */ 807 int8_t Datarate; 808 }McpsReqUnconfirmed_t; 809 810 /*! 811 * LoRaMAC MCPS-Request for a confirmed frame 812 */ 813 typedef struct sMcpsReqConfirmed 814 { 815 /*! 816 * Frame port field. Must be set if the payload is not empty. Use the 817 * application specific frame port values: [1...223] 818 * 819 * LoRaWAN Specification V1.0.2, chapter 4.3.2 820 */ 821 uint8_t fPort; 822 /*! 823 * Pointer to the buffer of the frame payload 824 */ 825 void* fBuffer; 826 /*! 827 * Size of the frame payload 828 */ 829 uint16_t fBufferSize; 830 /*! 831 * Uplink datarate, if ADR is off 832 */ 833 int8_t Datarate; 834 }McpsReqConfirmed_t; 835 836 /*! 837 * LoRaMAC MCPS-Request for a proprietary frame 838 */ 839 typedef struct sMcpsReqProprietary 840 { 841 /*! 842 * Pointer to the buffer of the frame payload 843 */ 844 void* fBuffer; 845 /*! 846 * Size of the frame payload 847 */ 848 uint16_t fBufferSize; 849 /*! 850 * Uplink datarate, if ADR is off 851 */ 852 int8_t Datarate; 853 }McpsReqProprietary_t; 854 855 /*! 856 * LoRaMAC MCPS-Request structure 857 */ 858 typedef struct sMcpsReq 859 { 860 /*! 861 * MCPS-Request type 862 */ 863 Mcps_t Type; 864 865 /*! 866 * MCPS-Request parameters 867 */ 868 union uMcpsParam 869 { 870 /*! 871 * MCPS-Request parameters for an unconfirmed frame 872 */ 873 McpsReqUnconfirmed_t Unconfirmed; 874 /*! 875 * MCPS-Request parameters for a confirmed frame 876 */ 877 McpsReqConfirmed_t Confirmed; 878 /*! 879 * MCPS-Request parameters for a proprietary frame 880 */ 881 McpsReqProprietary_t Proprietary; 882 }Req; 883 884 /*! 885 * MCPS-Request return parameters 886 */ 887 RequestReturnParam_t ReqReturn; 888 }McpsReq_t; 889 890 /*! 891 * LoRaMAC MCPS-Confirm 892 */ 893 typedef struct sMcpsConfirm 894 { 895 /*! 896 * Holds the previously performed MCPS-Request 897 */ 898 Mcps_t McpsRequest; 899 /*! 900 * Status of the operation 901 */ 902 LoRaMacEventInfoStatus_t Status; 903 /*! 904 * Uplink datarate 905 */ 906 uint8_t Datarate; 907 /*! 908 * Transmission power 909 */ 910 int8_t TxPower; 911 /*! 912 * Set if an acknowledgement was received 913 */ 914 bool AckReceived; 915 /*! 916 * Provides the number of retransmissions 917 */ 918 uint8_t NbTrans; 919 /*! 920 * The transmission time on air of the frame 921 */ 922 TimerTime_t TxTimeOnAir; 923 /*! 924 * The uplink counter value related to the frame 925 */ 926 uint32_t UpLinkCounter; 927 /*! 928 * The uplink channel related to the frame 929 */ 930 uint32_t Channel; 931 }McpsConfirm_t; 932 933 /*! 934 * LoRaMAC MCPS-Indication primitive 935 */ 936 typedef struct sMcpsIndication 937 { 938 /*! 939 * MCPS-Indication type 940 */ 941 Mcps_t McpsIndication; 942 /*! 943 * Status of the operation 944 */ 945 LoRaMacEventInfoStatus_t Status; 946 /*! 947 * Multicast 948 */ 949 uint8_t Multicast; 950 /*! 951 * Application port 952 */ 953 uint8_t Port; 954 /*! 955 * Downlink datarate 956 */ 957 uint8_t RxDatarate; 958 /*! 959 * Frame pending status 960 */ 961 uint8_t FramePending; 962 /*! 963 * Pointer to the received data stream 964 */ 965 uint8_t* Buffer; 966 /*! 967 * Size of the received data stream 968 */ 969 uint8_t BufferSize; 970 /*! 971 * Indicates, if data is available 972 */ 973 bool RxData; 974 /*! 975 * Rssi of the received packet 976 */ 977 int16_t Rssi; 978 /*! 979 * Snr of the received packet 980 */ 981 int8_t Snr; 982 /*! 983 * Receive window 984 */ 985 LoRaMacRxSlot_t RxSlot; 986 /*! 987 * Set if an acknowledgement was received 988 */ 989 bool AckReceived; 990 /*! 991 * The downlink counter value for the received frame 992 */ 993 uint32_t DownLinkCounter; 994 /*! 995 * The device address of the frame 996 */ 997 uint32_t DevAddress; 998 /*! 999 * Set if a DeviceTimeAns MAC command was received. 1000 */ 1001 bool DeviceTimeAnsReceived; 1002 /*! 1003 * Response timeout for a class b or c device when a 1004 * confirmed downlink has been received. In all other 1005 * cases this variable is 0. 1006 */ 1007 TimerTime_t ResponseTimeout; 1008 }McpsIndication_t; 1009 1010 /*! 1011 * \brief LoRaMAC management services 1012 * 1013 * \details The following table list the primitives which are supported by the 1014 * specific MAC management service: 1015 * 1016 * Name | Request | Indication | Response | Confirm 1017 * ---------------------------- | :-----: | :--------: | :------: | :-----: 1018 * \ref MLME_JOIN | YES | NO | NO | YES 1019 * \ref MLME_LINK_CHECK | YES | NO | NO | YES 1020 * \ref MLME_TXCW | YES | NO | NO | YES 1021 * \ref MLME_SCHEDULE_UPLINK | NO | YES | NO | NO 1022 * \ref MLME_DERIVE_MC_KE_KEY | YES | NO | NO | YES 1023 * \ref MLME_DERIVE_MC_KEY_PAIR | YES | NO | NO | YES 1024 * 1025 * The following table provides links to the function implementations of the 1026 * related MLME primitives. 1027 * 1028 * Primitive | Function 1029 * ---------------- | :---------------------: 1030 * MLME-Request | \ref LoRaMacMlmeRequest 1031 * MLME-Confirm | MacMlmeConfirm in \ref LoRaMacPrimitives_t 1032 * MLME-Indication | MacMlmeIndication in \ref LoRaMacPrimitives_t 1033 */ 1034 typedef enum eMlme 1035 { 1036 /*! 1037 * An unknown MLME service 1038 */ 1039 MLME_UNKNOWN, 1040 /*! 1041 * Initiates the Over-the-Air activation 1042 * 1043 * LoRaWAN Specification V1.0.2, chapter 6.2 1044 */ 1045 MLME_JOIN, 1046 /*! 1047 * Initiates sending a ReJoin-request type 0 1048 * 1049 * LoRaWAN Specification V1.1.0, chapter 6.2.4.1 1050 */ 1051 MLME_REJOIN_0, 1052 /*! 1053 * Initiates sending a ReJoin-request type 1 1054 * 1055 * LoRaWAN Specification V1.1.0, chapter 6.2.4.2 1056 */ 1057 MLME_REJOIN_1, 1058 /*! 1059 * LinkCheckReq - Connectivity validation 1060 * 1061 * LoRaWAN Specification V1.0.2, chapter 5, table 4 1062 */ 1063 MLME_LINK_CHECK, 1064 /*! 1065 * Sets Tx continuous wave mode 1066 * 1067 * LoRaWAN end-device certification 1068 */ 1069 MLME_TXCW, 1070 /*! 1071 * Indicates that the application shall perform an uplink as 1072 * soon as possible. 1073 */ 1074 MLME_SCHEDULE_UPLINK, 1075 /*! 1076 * Derives the McKEKey from the AppKey or NwkKey. 1077 */ 1078 MLME_DERIVE_MC_KE_KEY, 1079 /*! 1080 * Derives a Multicast group key pair ( McAppSKey, McNwkSKey ) from McKey 1081 */ 1082 MLME_DERIVE_MC_KEY_PAIR, 1083 /*! 1084 * Initiates a DeviceTimeReq 1085 * 1086 * LoRaWAN end-device certification 1087 */ 1088 MLME_DEVICE_TIME, 1089 /*! 1090 * The MAC uses this MLME primitive to indicate a beacon reception 1091 * status. 1092 * 1093 * LoRaWAN end-device certification 1094 */ 1095 MLME_BEACON, 1096 /*! 1097 * Initiate a beacon acquisition. The MAC will search for a beacon. 1098 * It will search for XX_BEACON_INTERVAL milliseconds. 1099 * 1100 * LoRaWAN end-device certification 1101 */ 1102 MLME_BEACON_ACQUISITION, 1103 /*! 1104 * Initiates a PingSlotInfoReq 1105 * 1106 * LoRaWAN end-device certification 1107 */ 1108 MLME_PING_SLOT_INFO, 1109 /*! 1110 * Initiates a BeaconTimingReq 1111 * 1112 * LoRaWAN end-device certification 1113 */ 1114 MLME_BEACON_TIMING, 1115 /*! 1116 * Primitive which indicates that the beacon has been lost 1117 * 1118 * \remark The upper layer is required to switch the device class to ClassA 1119 * 1120 * LoRaWAN end-device certification 1121 */ 1122 MLME_BEACON_LOST, 1123 }Mlme_t; 1124 1125 /*! 1126 * LoRaMAC MLME-Request for the join service 1127 */ 1128 typedef struct sMlmeReqJoin 1129 { 1130 /*! 1131 * LoRaWAN Network End-Device Activation ( ACTIVATION_TYPE_NONE, ACTIVATION_TYPE_ABP or OTTA ) 1132 * 1133 * Related MIB type: \ref MIB_NETWORK_ACTIVATION 1134 */ 1135 ActivationType_t NetworkActivation; 1136 /*! 1137 * Datarate used for join request. 1138 */ 1139 uint8_t Datarate; 1140 }MlmeReqJoin_t; 1141 1142 /*! 1143 * LoRaMAC MLME-Request for Tx continuous wave mode 1144 */ 1145 typedef struct sMlmeReqTxCw 1146 { 1147 /*! 1148 * Time in seconds while the radio is kept in continuous wave mode 1149 */ 1150 uint16_t Timeout; 1151 /*! 1152 * RF frequency to set (Only used with new way) 1153 */ 1154 uint32_t Frequency; 1155 /*! 1156 * RF output power to set (Only used with new way) 1157 */ 1158 int8_t Power; 1159 }MlmeReqTxCw_t; 1160 1161 /*! 1162 * LoRaMAC MLME-Request for the ping slot info service 1163 */ 1164 typedef struct sMlmeReqPingSlotInfo 1165 { 1166 PingSlotInfo_t PingSlot; 1167 }MlmeReqPingSlotInfo_t; 1168 1169 /*! 1170 * LoRaMAC MLME-Request to derive the McKEKey from the AppKey or NwkKey 1171 */ 1172 typedef struct sMlmeReqDeriveMcKEKey 1173 { 1174 /*! 1175 * Key identifier of the root key to use to perform the derivation ( NwkKey or AppKey ) 1176 */ 1177 KeyIdentifier_t KeyID; 1178 /*! 1179 * Nonce value ( nonce <= 15) 1180 */ 1181 uint16_t Nonce; 1182 /*! 1183 * DevEUI Value 1184 */ 1185 uint8_t* DevEUI; 1186 }MlmeReqDeriveMcKEKey_t; 1187 1188 /*! 1189 * LoRaMAC MLME-Request to derive a Multicast group key pair ( McAppSKey, McNwkSKey ) from McKey 1190 */ 1191 typedef struct sMlmeReqDeriveMcSessionKeyPair 1192 { 1193 /*! 1194 * Address identifier to select the multicast group 1195 */ 1196 AddressIdentifier_t GroupID; 1197 }MlmeReqDeriveMcSessionKeyPair_t; 1198 1199 /*! 1200 * LoRaMAC MLME-Request structure 1201 */ 1202 typedef struct sMlmeReq 1203 { 1204 /*! 1205 * MLME-Request type 1206 */ 1207 Mlme_t Type; 1208 1209 /*! 1210 * MLME-Request parameters 1211 */ 1212 union uMlmeParam 1213 { 1214 /*! 1215 * MLME-Request parameters for a join request 1216 */ 1217 MlmeReqJoin_t Join; 1218 /*! 1219 * MLME-Request parameters for Tx continuous mode request 1220 */ 1221 MlmeReqTxCw_t TxCw; 1222 /*! 1223 * MLME-Request parameters for a ping slot info request 1224 */ 1225 MlmeReqPingSlotInfo_t PingSlotInfo; 1226 /*! 1227 * MLME-Request to derive the McKEKey from the AppKey or NwkKey 1228 */ 1229 MlmeReqDeriveMcKEKey_t DeriveMcKEKey; 1230 /*! 1231 * MLME-Request to derive a Multicast group key pair ( McAppSKey, McNwkSKey ) from McKey 1232 */ 1233 MlmeReqDeriveMcSessionKeyPair_t DeriveMcSessionKeyPair; 1234 }Req; 1235 1236 /*! 1237 * MLME-Request return parameters 1238 */ 1239 RequestReturnParam_t ReqReturn; 1240 }MlmeReq_t; 1241 1242 /*! 1243 * LoRaMAC MLME-Confirm primitive 1244 */ 1245 typedef struct sMlmeConfirm 1246 { 1247 /*! 1248 * Holds the previously performed MLME-Request 1249 */ 1250 Mlme_t MlmeRequest; 1251 /*! 1252 * Status of the operation 1253 */ 1254 LoRaMacEventInfoStatus_t Status; 1255 /*! 1256 * The transmission time on air of the frame 1257 */ 1258 TimerTime_t TxTimeOnAir; 1259 /*! 1260 * Demodulation margin. Contains the link margin [dB] of the last 1261 * successfully received LinkCheckReq 1262 */ 1263 uint8_t DemodMargin; 1264 /*! 1265 * Number of gateways which received the last LinkCheckReq 1266 */ 1267 uint8_t NbGateways; 1268 /*! 1269 * Provides the number of retransmissions 1270 */ 1271 uint8_t NbRetries; 1272 /*! 1273 * The delay which we have received through the 1274 * BeaconTimingAns 1275 */ 1276 TimerTime_t BeaconTimingDelay; 1277 /*! 1278 * The channel of the next beacon 1279 */ 1280 uint8_t BeaconTimingChannel; 1281 }MlmeConfirm_t; 1282 1283 /*! 1284 * LoRaMAC MLME-Indication primitive 1285 */ 1286 typedef struct sMlmeIndication 1287 { 1288 /*! 1289 * MLME-Indication type 1290 */ 1291 Mlme_t MlmeIndication; 1292 /*! 1293 * Status of the operation 1294 */ 1295 LoRaMacEventInfoStatus_t Status; 1296 /*! 1297 * Beacon information. Only valid for \ref MLME_BEACON, 1298 * status \ref LORAMAC_EVENT_INFO_STATUS_BEACON_LOCKED 1299 */ 1300 BeaconInfo_t BeaconInfo; 1301 }MlmeIndication_t; 1302 1303 /*! 1304 * LoRa Mac Information Base (MIB) 1305 * 1306 * The following table lists the MIB parameters and the related attributes: 1307 * 1308 * Attribute | Get | Set 1309 * ----------------------------------------------| :-: | :-: 1310 * \ref MIB_DEVICE_CLASS | YES | YES 1311 * \ref MIB_NETWORK_ACTIVATION | YES | YES 1312 * \ref MIB_DEV_EUI | YES | YES 1313 * \ref MIB_JOIN_EUI | YES | YES 1314 * \ref MIB_SE_PIN | YES | YES 1315 * \ref MIB_ADR | YES | YES 1316 * \ref MIB_NET_ID | YES | YES 1317 * \ref MIB_DEV_ADDR | YES | YES 1318 * \ref MIB_APP_KEY | NO | YES 1319 * \ref MIB_NWK_KEY | NO | YES 1320 * \ref MIB_J_S_INT_KEY | NO | YES 1321 * \ref MIB_J_S_ENC_KEY | NO | YES 1322 * \ref MIB_F_NWK_S_INT_KEY | NO | YES 1323 * \ref MIB_S_NWK_S_INT_KEY | NO | YES 1324 * \ref MIB_NWK_S_ENC_KEY | NO | YES 1325 * \ref MIB_APP_S_KEY | NO | YES 1326 * \ref MIB_MC_KE_KEY | NO | YES 1327 * \ref MIB_MC_KEY_0 | NO | YES 1328 * \ref MIB_MC_APP_S_KEY_0 | NO | YES 1329 * \ref MIB_MC_NWK_S_KEY_0 | NO | YES 1330 * \ref MIB_MC_KEY_1 | NO | YES 1331 * \ref MIB_MC_APP_S_KEY_1 | NO | YES 1332 * \ref MIB_MC_NWK_S_KEY_1 | NO | YES 1333 * \ref MIB_MC_KEY_2 | NO | YES 1334 * \ref MIB_MC_APP_S_KEY_2 | NO | YES 1335 * \ref MIB_MC_NWK_S_KEY_2 | NO | YES 1336 * \ref MIB_MC_KEY_3 | NO | YES 1337 * \ref MIB_MC_APP_S_KEY_3 | NO | YES 1338 * \ref MIB_MC_NWK_S_KEY_3 | NO | YES 1339 * \ref MIB_PUBLIC_NETWORK | YES | YES 1340 * \ref MIB_CHANNELS | YES | NO 1341 * \ref MIB_RX2_CHANNEL | YES | YES 1342 * \ref MIB_RX2_DFAULT_CHANNEL | YES | YES 1343 * \ref MIB_RXC_CHANNEL | YES | YES 1344 * \ref MIB_RXC_DFAULT_CHANNEL | YES | YES 1345 * \ref MIB_CHANNELS_MASK | YES | YES 1346 * \ref MIB_CHANNELS_DEFAULT_MASK | YES | YES 1347 * \ref MIB_CHANNELS_NB_TRANS | YES | YES 1348 * \ref MIB_MAX_RX_WINDOW_DURATION | YES | YES 1349 * \ref MIB_RECEIVE_DELAY_1 | YES | YES 1350 * \ref MIB_RECEIVE_DELAY_2 | YES | YES 1351 * \ref MIB_JOIN_ACCEPT_DELAY_1 | YES | YES 1352 * \ref MIB_JOIN_ACCEPT_DELAY_2 | YES | YES 1353 * \ref MIB_CHANNELS_DATARATE | YES | YES 1354 * \ref MIB_CHANNELS_MIN_TX_DATARATE | YES | NO 1355 * \ref MIB_CHANNELS_DEFAULT_DATARATE | YES | YES 1356 * \ref MIB_CHANNELS_TX_POWER | YES | YES 1357 * \ref MIB_CHANNELS_DEFAULT_TX_POWER | YES | YES 1358 * \ref MIB_SYSTEM_MAX_RX_ERROR | YES | YES 1359 * \ref MIB_MIN_RX_SYMBOLS | YES | YES 1360 * \ref MIB_BEACON_INTERVAL | YES | YES 1361 * \ref MIB_BEACON_RESERVED | YES | YES 1362 * \ref MIB_BEACON_GUARD | YES | YES 1363 * \ref MIB_BEACON_WINDOW | YES | YES 1364 * \ref MIB_BEACON_WINDOW_SLOTS | YES | YES 1365 * \ref MIB_PING_SLOT_WINDOW | YES | YES 1366 * \ref MIB_BEACON_SYMBOL_TO_DEFAULT | YES | YES 1367 * \ref MIB_BEACON_SYMBOL_TO_EXPANSION_MAX | YES | YES 1368 * \ref MIB_PING_SLOT_SYMBOL_TO_EXPANSION_MAX | YES | YES 1369 * \ref MIB_BEACON_SYMBOL_TO_EXPANSION_FACTOR | YES | YES 1370 * \ref MIB_PING_SLOT_SYMBOL_TO_EXPANSION_FACTOR | YES | YES 1371 * \ref MIB_MAX_BEACON_LESS_PERIOD | YES | YES 1372 * \ref MIB_ANTENNA_GAIN | YES | YES 1373 * \ref MIB_DEFAULT_ANTENNA_GAIN | YES | YES 1374 * \ref MIB_NVM_CTXS | YES | YES 1375 * \ref MIB_ABP_LORAWAN_VERSION | NO | YES 1376 * \ref MIB_LORAWAN_VERSION | YES | NO 1377 * \ref MIB_IS_CERT_FPORT_ON | YES | YES 1378 * 1379 * The following table provides links to the function implementations of the 1380 * related MIB primitives: 1381 * 1382 * Primitive | Function 1383 * ---------------- | :---------------------: 1384 * MIB-Set | \ref LoRaMacMibSetRequestConfirm 1385 * MIB-Get | \ref LoRaMacMibGetRequestConfirm 1386 */ 1387 typedef enum eMib 1388 { 1389 /*! 1390 * LoRaWAN device class 1391 * 1392 * LoRaWAN Specification V1.0.2 1393 */ 1394 MIB_DEVICE_CLASS, 1395 /*! 1396 * LoRaWAN Network End-Device Activation 1397 * 1398 * LoRaWAN Specification V1.0.2 1399 */ 1400 MIB_NETWORK_ACTIVATION, 1401 /*! 1402 * LoRaWAN device EUI 1403 * 1404 * LoRaWAN Specification V1.0.2 1405 */ 1406 MIB_DEV_EUI, 1407 /*! 1408 * LoRaWAN join EUI 1409 * 1410 * LoRaWAN Specification V1.0.2 1411 */ 1412 MIB_JOIN_EUI, 1413 /*! 1414 * Secure-element pin 1415 */ 1416 MIB_SE_PIN, 1417 /*! 1418 * Adaptive data rate 1419 * 1420 * LoRaWAN Specification V1.0.2, chapter 4.3.1.1 1421 * 1422 * [true: ADR enabled, false: ADR disabled] 1423 */ 1424 MIB_ADR, 1425 /*! 1426 * Network identifier 1427 * 1428 * LoRaWAN Specification V1.0.2, chapter 6.1.1 1429 */ 1430 MIB_NET_ID, 1431 /*! 1432 * End-device address 1433 * 1434 * LoRaWAN Specification V1.0.2, chapter 6.1.1 1435 */ 1436 MIB_DEV_ADDR, 1437 /*! 1438 * Application root key 1439 * 1440 * LoRaWAN Specification V1.1.0, chapter 6.1.1.3 1441 */ 1442 MIB_APP_KEY, 1443 /*! 1444 * Network root key 1445 * 1446 * LoRaWAN Specification V1.1.0, chapter 6.1.1.3 1447 */ 1448 MIB_NWK_KEY, 1449 /*! 1450 * Join session integrity key 1451 * 1452 * LoRaWAN Specification V1.1.0, chapter 6.1.1.4 1453 */ 1454 MIB_J_S_INT_KEY, 1455 /*! 1456 * Join session encryption key 1457 * 1458 * LoRaWAN Specification V1.1.0, chapter 6.1.1.4 1459 */ 1460 MIB_J_S_ENC_KEY, 1461 /*! 1462 * Forwarding Network session integrity key 1463 * 1464 * LoRaWAN Specification V1.1.0, chapter 6.1.2.2 1465 */ 1466 MIB_F_NWK_S_INT_KEY, 1467 /*! 1468 * Serving Network session integrity key 1469 * 1470 * LoRaWAN Specification V1.1.0, chapter 6.1.2.3 1471 */ 1472 MIB_S_NWK_S_INT_KEY, 1473 /*! 1474 * Network session encryption key 1475 * 1476 * LoRaWAN Specification V1.1.0, chapter 6.1.2.4 1477 */ 1478 MIB_NWK_S_ENC_KEY, 1479 /*! 1480 * Application session key 1481 * 1482 * LoRaWAN Specification V1.1.0, chapter 6.1.1.3 1483 */ 1484 MIB_APP_S_KEY, 1485 /*! 1486 * Multicast key encryption key 1487 * 1488 * LoRaWAN - Secure element specification v1 1489 */ 1490 MIB_MC_KE_KEY, 1491 /*! 1492 * Multicast root key index 0 1493 * 1494 * LoRaWAN - Secure element specification v1 1495 */ 1496 MIB_MC_KEY_0, 1497 /*! 1498 * Multicast Application session key index 0 1499 * 1500 * LoRaWAN - Secure element specification v1 1501 */ 1502 MIB_MC_APP_S_KEY_0, 1503 /*! 1504 * Multicast Network session key index 0 1505 * 1506 * LoRaWAN - Secure element specification v1 1507 */ 1508 MIB_MC_NWK_S_KEY_0, 1509 /*! 1510 * Multicast root key index 1 1511 * 1512 * LoRaWAN - Secure element specification v1 1513 */ 1514 MIB_MC_KEY_1, 1515 /*! 1516 * Multicast Application session key index 1 1517 * 1518 * LoRaWAN - Secure element specification v1 1519 */ 1520 MIB_MC_APP_S_KEY_1, 1521 /*! 1522 * Multicast Network session key index 1 1523 * 1524 * LoRaWAN - Secure element specification v1 1525 */ 1526 MIB_MC_NWK_S_KEY_1, 1527 /*! 1528 * Multicast root key index 2 1529 * 1530 * LoRaWAN - Secure element specification v1 1531 */ 1532 MIB_MC_KEY_2, 1533 /*! 1534 * Multicast Application session key index 2 1535 * 1536 * LoRaWAN - Secure element specification v1 1537 */ 1538 MIB_MC_APP_S_KEY_2, 1539 /*! 1540 * Multicast Network session key index 2 1541 * 1542 * LoRaWAN - Secure element specification v1 1543 */ 1544 MIB_MC_NWK_S_KEY_2, 1545 /*! 1546 * Multicast root key index 3 1547 * 1548 * LoRaWAN - Secure element specification v1 1549 */ 1550 MIB_MC_KEY_3, 1551 /*! 1552 * Multicast Application session key index 3 1553 * 1554 * LoRaWAN - Secure element specification v1 1555 */ 1556 MIB_MC_APP_S_KEY_3, 1557 /*! 1558 * Multicast Network session key index 3 1559 * 1560 * LoRaWAN - Secure element specification v1 1561 */ 1562 MIB_MC_NWK_S_KEY_3, 1563 /*! 1564 * Set the network type to public or private 1565 * 1566 * LoRaWAN Regional Parameters V1.0.2rB 1567 * 1568 * [true: public network, false: private network] 1569 */ 1570 MIB_PUBLIC_NETWORK, 1571 /*! 1572 * Communication channels. A get request will return a 1573 * pointer which references the first entry of the channel list. The 1574 * list is of size LORA_MAX_NB_CHANNELS 1575 * 1576 * LoRaWAN Regional Parameters V1.0.2rB 1577 */ 1578 MIB_CHANNELS, 1579 /*! 1580 * Set receive window 2 channel 1581 * 1582 * LoRaWAN Specification V1.0.2, chapter 3.3.1 1583 */ 1584 MIB_RX2_CHANNEL, 1585 /*! 1586 * Set receive window 2 channel 1587 * 1588 * LoRaWAN Specification V1.0.2, chapter 3.3.2 1589 */ 1590 MIB_RX2_DEFAULT_CHANNEL, 1591 /*! 1592 * Set receive window C channel 1593 * 1594 * LoRaWAN Specification V1.0.2, chapter 3.3.1 1595 */ 1596 MIB_RXC_CHANNEL, 1597 /*! 1598 * Set receive window C channel 1599 * 1600 * LoRaWAN Specification V1.0.2, chapter 3.3.2 1601 */ 1602 MIB_RXC_DEFAULT_CHANNEL, 1603 /*! 1604 * LoRaWAN channels mask 1605 * 1606 * LoRaWAN Regional Parameters V1.0.2rB 1607 */ 1608 MIB_CHANNELS_MASK, 1609 /*! 1610 * LoRaWAN default channels mask 1611 * 1612 * LoRaWAN Regional Parameters V1.0.2rB 1613 */ 1614 MIB_CHANNELS_DEFAULT_MASK, 1615 /*! 1616 * Set the number of repetitions on a channel 1617 * 1618 * LoRaWAN Specification V1.0.2, chapter 5.2 1619 */ 1620 MIB_CHANNELS_NB_TRANS, 1621 /*! 1622 * Maximum receive window duration in [ms] 1623 * 1624 * LoRaWAN Specification V1.0.2, chapter 3.3.3 1625 */ 1626 MIB_MAX_RX_WINDOW_DURATION, 1627 /*! 1628 * Receive delay 1 in [ms] 1629 * 1630 * LoRaWAN Regional Parameters V1.0.2rB 1631 */ 1632 MIB_RECEIVE_DELAY_1, 1633 /*! 1634 * Receive delay 2 in [ms] 1635 * 1636 * LoRaWAN Regional Parameters V1.0.2rB 1637 */ 1638 MIB_RECEIVE_DELAY_2, 1639 /*! 1640 * Join accept delay 1 in [ms] 1641 * 1642 * LoRaWAN Regional Parameters V1.0.2rB 1643 */ 1644 MIB_JOIN_ACCEPT_DELAY_1, 1645 /*! 1646 * Join accept delay 2 in [ms] 1647 * 1648 * LoRaWAN Regional Parameters V1.0.2rB 1649 */ 1650 MIB_JOIN_ACCEPT_DELAY_2, 1651 /*! 1652 * Minimum Data rate of a channel 1653 * 1654 * LoRaWAN Regional Parameters V1.0.2rB 1655 * 1656 * The possible values are region specific. Please refer to \ref DR_0 to \ref DR_15 for details. 1657 */ 1658 MIB_CHANNELS_MIN_TX_DATARATE, 1659 /*! 1660 * Default Data rate of a channel 1661 * 1662 * LoRaWAN Regional Parameters V1.0.2rB 1663 * 1664 * The allowed ranges are region specific. Please refer to \ref DR_0 to \ref DR_15 for details. 1665 */ 1666 MIB_CHANNELS_DEFAULT_DATARATE, 1667 /*! 1668 * Data rate of a channel 1669 * 1670 * LoRaWAN Regional Parameters V1.0.2rB 1671 * 1672 * The allowed ranges are region specific. Please refer to \ref DR_0 to \ref DR_15 for details. 1673 */ 1674 MIB_CHANNELS_DATARATE, 1675 /*! 1676 * Transmission power of a channel 1677 * 1678 * LoRaWAN Regional Parameters V1.0.2rB 1679 * 1680 * The allowed ranges are region specific. Please refer to \ref TX_POWER_0 to \ref TX_POWER_15 for details. 1681 */ 1682 MIB_CHANNELS_TX_POWER, 1683 /*! 1684 * Transmission power of a channel 1685 * 1686 * LoRaWAN Regional Parameters V1.0.2rB 1687 * 1688 * The allowed ranges are region specific. Please refer to \ref TX_POWER_0 to \ref TX_POWER_15 for details. 1689 */ 1690 MIB_CHANNELS_DEFAULT_TX_POWER, 1691 /*! 1692 * System overall timing error in milliseconds. 1693 * [-SystemMaxRxError : +SystemMaxRxError] 1694 * Default: +/-10 ms 1695 */ 1696 MIB_SYSTEM_MAX_RX_ERROR, 1697 /*! 1698 * Minimum required number of symbols to detect an Rx frame 1699 * Default: 6 symbols 1700 */ 1701 MIB_MIN_RX_SYMBOLS, 1702 /*! 1703 * Antenna gain of the node. Default value is region specific. 1704 * The antenna gain is used to calculate the TX power of the node. 1705 * The formula is: 1706 * radioTxPower = ( int8_t )floor( maxEirp - antennaGain ) 1707 * 1708 * \remark The antenna gain value is referenced to the isotropic antenna. 1709 * The value is in dBi. 1710 * MIB_ANTENNA_GAIN[dBi] = measuredAntennaGain[dBd] + 2.15 1711 */ 1712 MIB_ANTENNA_GAIN, 1713 /*! 1714 * Default antenna gain of the node. Default value is region specific. 1715 * The antenna gain is used to calculate the TX power of the node. 1716 * The formula is: 1717 * radioTxPower = ( int8_t )floor( maxEirp - antennaGain ) 1718 * 1719 * \remark The antenna gain value is referenced to the isotropic antenna. 1720 * The value is in dBi. 1721 * MIB_DEFAULT_ANTENNA_GAIN[dBi] = measuredAntennaGain[dBd] + 2.15 1722 */ 1723 MIB_DEFAULT_ANTENNA_GAIN, 1724 /*! 1725 * Structure holding pointers to internal contexts and its size 1726 */ 1727 MIB_NVM_CTXS, 1728 /*! 1729 * LoRaWAN MAC layer operating version when activated by ABP. 1730 */ 1731 MIB_ABP_LORAWAN_VERSION, 1732 /*! 1733 * LoRaWAN MAC and regional parameter version. 1734 */ 1735 MIB_LORAWAN_VERSION, 1736 /*! 1737 * Beacon interval in ms 1738 */ 1739 MIB_BEACON_INTERVAL, 1740 /*! 1741 * Beacon reserved time in ms 1742 */ 1743 MIB_BEACON_RESERVED, 1744 /*! 1745 * Beacon guard time in ms 1746 */ 1747 MIB_BEACON_GUARD, 1748 /*! 1749 * Beacon window time in ms 1750 */ 1751 MIB_BEACON_WINDOW, 1752 /*! 1753 * Beacon window time in number of slots 1754 */ 1755 MIB_BEACON_WINDOW_SLOTS, 1756 /*! 1757 * Ping slot length time in ms 1758 */ 1759 MIB_PING_SLOT_WINDOW, 1760 /*! 1761 * Default symbol timeout for beacons and ping slot windows 1762 */ 1763 MIB_BEACON_SYMBOL_TO_DEFAULT, 1764 /*! 1765 * Maximum symbol timeout for beacons 1766 */ 1767 MIB_BEACON_SYMBOL_TO_EXPANSION_MAX, 1768 /*! 1769 * Maximum symbol timeout for ping slots 1770 */ 1771 MIB_PING_SLOT_SYMBOL_TO_EXPANSION_MAX, 1772 /*! 1773 * Symbol expansion value for beacon windows in case of beacon 1774 * loss in symbols 1775 */ 1776 MIB_BEACON_SYMBOL_TO_EXPANSION_FACTOR, 1777 /*! 1778 * Symbol expansion value for ping slot windows in case of beacon 1779 * loss in symbols 1780 */ 1781 MIB_PING_SLOT_SYMBOL_TO_EXPANSION_FACTOR, 1782 /*! 1783 * Maximum allowed beacon less time in ms 1784 */ 1785 MIB_MAX_BEACON_LESS_PERIOD, 1786 /*! 1787 * Ping slot data rate 1788 * 1789 * LoRaWAN Regional Parameters V1.0.2rB 1790 * 1791 * The allowed ranges are region specific. Please refer to \ref DR_0 to \ref DR_15 for details. 1792 */ 1793 MIB_PING_SLOT_DATARATE, 1794 /*! 1795 * LoRaWAN certification FPort handling state (ON/OFF) 1796 */ 1797 MIB_IS_CERT_FPORT_ON, 1798 }Mib_t; 1799 1800 /*! 1801 * LoRaMAC MIB parameters 1802 */ 1803 typedef union uMibParam 1804 { 1805 /*! 1806 * LoRaWAN device class 1807 * 1808 * Related MIB type: \ref MIB_DEVICE_CLASS 1809 */ 1810 DeviceClass_t Class; 1811 /*! 1812 * LoRaWAN Network End-Device Activation ( ACTIVATION_TYPE_NONE, ACTIVATION_TYPE_ABP or OTTA ) 1813 * 1814 * Related MIB type: \ref MIB_NETWORK_ACTIVATION 1815 */ 1816 ActivationType_t NetworkActivation; 1817 /*! 1818 * LoRaWAN device EUI 1819 * 1820 * Related MIB type: \ref MIB_DEV_EUI 1821 */ 1822 uint8_t* DevEui; 1823 /*! 1824 * LoRaWAN Join server EUI 1825 * 1826 * Related MIB type: \ref MIB_JOIN_EUI 1827 */ 1828 uint8_t* JoinEui; 1829 /*! 1830 * Secure-element pin 1831 * 1832 * Related MIB type: \ref MIB_SE_PIN 1833 */ 1834 uint8_t* SePin; 1835 /*! 1836 * Activation state of ADR 1837 * 1838 * Related MIB type: \ref MIB_ADR 1839 */ 1840 bool AdrEnable; 1841 /*! 1842 * Network identifier 1843 * 1844 * Related MIB type: \ref MIB_NET_ID 1845 */ 1846 uint32_t NetID; 1847 /*! 1848 * End-device address 1849 * 1850 * Related MIB type: \ref MIB_DEV_ADDR 1851 */ 1852 uint32_t DevAddr; 1853 /*! 1854 * Application root key 1855 * 1856 * Related MIB type: \ref MIB_APP_KEY 1857 */ 1858 uint8_t* AppKey; 1859 /*! 1860 * Network root key 1861 * 1862 * Related MIB type: \ref MIB_NWK_KEY 1863 */ 1864 uint8_t* NwkKey; 1865 /*! 1866 * Join session integrity key 1867 * 1868 * Related MIB type: \ref MIB_J_S_INT_KEY 1869 */ 1870 uint8_t* JSIntKey; 1871 /*! 1872 * Join session encryption key 1873 * 1874 * Related MIB type: \ref MIB_J_S_ENC_KEY 1875 */ 1876 uint8_t* JSEncKey; 1877 /*! 1878 * Forwarding Network session integrity key 1879 * 1880 * Related MIB type: \ref MIB_F_NWK_S_INT_KEY 1881 */ 1882 uint8_t* FNwkSIntKey; 1883 /*! 1884 * Serving Network session integrity key 1885 * 1886 * Related MIB type: \ref MIB_S_NWK_S_INT_KEY 1887 */ 1888 uint8_t* SNwkSIntKey; 1889 /*! 1890 * Network session encryption key 1891 * 1892 * Related MIB type: \ref MIB_NWK_S_ENC_KEY 1893 */ 1894 uint8_t* NwkSEncKey; 1895 /*! 1896 * Application session key 1897 * 1898 * Related MIB type: \ref MIB_APP_S_KEY 1899 */ 1900 uint8_t* AppSKey; 1901 /*! 1902 * Multicast key encryption key 1903 * 1904 * Related MIB type: \ref MIB_MC_KE_KEY 1905 */ 1906 uint8_t* McKEKey; 1907 /*! 1908 * Multicast root key index 0 1909 * 1910 * Related MIB type: \ref MIB_MC_KEY_0 1911 */ 1912 uint8_t* McKey0; 1913 /*! 1914 * Multicast Application session key index 0 1915 * 1916 * Related MIB type: \ref MIB_MC_APP_S_KEY_0 1917 */ 1918 uint8_t* McAppSKey0; 1919 /*! 1920 * Multicast Network session key index 0 1921 * 1922 * Related MIB type: \ref MIB_MC_NWK_S_KEY_0 1923 */ 1924 uint8_t* McNwkSKey0; 1925 /*! 1926 * Multicast root key index 0 1927 * 1928 * Related MIB type: \ref MIB_MC_KEY_0 1929 */ 1930 uint8_t* McKey1; 1931 /*! 1932 * Multicast Application session key index 1 1933 * 1934 * Related MIB type: \ref MIB_MC_APP_S_KEY_1 1935 */ 1936 uint8_t* McAppSKey1; 1937 /*! 1938 * Multicast Network session key index 1 1939 * 1940 * Related MIB type: \ref MIB_MC_NWK_S_KEY_1 1941 */ 1942 uint8_t* McNwkSKey1; 1943 /*! 1944 * Multicast root key index 2 1945 * 1946 * Related MIB type: \ref MIB_MC_KEY_2 1947 */ 1948 uint8_t* McKey2; 1949 /*! 1950 * Multicast Application session key index 2 1951 * 1952 * Related MIB type: \ref MIB_MC_APP_S_KEY_2 1953 */ 1954 uint8_t* McAppSKey2; 1955 /*! 1956 * Multicast Network session key index 2 1957 * 1958 * Related MIB type: \ref MIB_MC_NWK_S_KEY_2 1959 */ 1960 uint8_t* McNwkSKey2; 1961 /*! 1962 * Multicast root key index 2 1963 * 1964 * Related MIB type: \ref MIB_MC_KEY_2 1965 */ 1966 uint8_t* McKey3; 1967 /*! 1968 * Multicast Application session key index 2 1969 * 1970 * Related MIB type: \ref MIB_MC_APP_S_KEY_2 1971 */ 1972 uint8_t* McAppSKey3; 1973 /*! 1974 * Multicast Network session key index 2 1975 * 1976 * Related MIB type: \ref MIB_MC_NWK_S_KEY_2 1977 */ 1978 uint8_t* McNwkSKey3; 1979 /*! 1980 * Enable or disable a public network 1981 * 1982 * Related MIB type: \ref MIB_PUBLIC_NETWORK 1983 */ 1984 bool EnablePublicNetwork; 1985 /*! 1986 * LoRaWAN Channel 1987 * 1988 * Related MIB type: \ref MIB_CHANNELS 1989 */ 1990 ChannelParams_t* ChannelList; 1991 /*! 1992 * Channel for the receive window 2 1993 * 1994 * Related MIB type: \ref MIB_RX2_CHANNEL 1995 */ 1996 RxChannelParams_t Rx2Channel; 1997 /*! 1998 * Channel for the receive window 2 1999 * 2000 * Related MIB type: \ref MIB_RX2_DEFAULT_CHANNEL 2001 */ 2002 RxChannelParams_t Rx2DefaultChannel; 2003 /*! 2004 * Channel for the receive window C 2005 * 2006 * Related MIB type: \ref MIB_RXC_CHANNEL 2007 */ 2008 RxChannelParams_t RxCChannel; 2009 /*! 2010 * Channel for the receive window C 2011 * 2012 * Related MIB type: \ref MIB_RXC_DEFAULT_CHANNEL 2013 */ 2014 RxChannelParams_t RxCDefaultChannel; 2015 /*! 2016 * Channel mask 2017 * 2018 * Related MIB type: \ref MIB_CHANNELS_MASK 2019 */ 2020 uint16_t* ChannelsMask; 2021 /*! 2022 * Default channel mask 2023 * 2024 * Related MIB type: \ref MIB_CHANNELS_DEFAULT_MASK 2025 */ 2026 uint16_t* ChannelsDefaultMask; 2027 /*! 2028 * Number of frame repetitions 2029 * 2030 * Related MIB type: \ref MIB_CHANNELS_NB_TRANS 2031 */ 2032 uint8_t ChannelsNbTrans; 2033 /*! 2034 * Maximum receive window duration 2035 * 2036 * Related MIB type: \ref MIB_MAX_RX_WINDOW_DURATION 2037 */ 2038 uint32_t MaxRxWindow; 2039 /*! 2040 * Receive delay 1 2041 * 2042 * Related MIB type: \ref MIB_RECEIVE_DELAY_1 2043 */ 2044 uint32_t ReceiveDelay1; 2045 /*! 2046 * Receive delay 2 2047 * 2048 * Related MIB type: \ref MIB_RECEIVE_DELAY_2 2049 */ 2050 uint32_t ReceiveDelay2; 2051 /*! 2052 * Join accept delay 1 2053 * 2054 * Related MIB type: \ref MIB_JOIN_ACCEPT_DELAY_1 2055 */ 2056 uint32_t JoinAcceptDelay1; 2057 /*! 2058 * Join accept delay 2 2059 * 2060 * Related MIB type: \ref MIB_JOIN_ACCEPT_DELAY_2 2061 */ 2062 uint32_t JoinAcceptDelay2; 2063 /*! 2064 * Channels minimum tx data rate 2065 * 2066 * Related MIB type: \ref MIB_CHANNELS_MIN_TX_DATARATE 2067 */ 2068 int8_t ChannelsMinTxDatarate; 2069 /*! 2070 * Channels data rate 2071 * 2072 * Related MIB type: \ref MIB_CHANNELS_DEFAULT_DATARATE 2073 */ 2074 int8_t ChannelsDefaultDatarate; 2075 /*! 2076 * Channels data rate 2077 * 2078 * Related MIB type: \ref MIB_CHANNELS_DATARATE 2079 */ 2080 int8_t ChannelsDatarate; 2081 /*! 2082 * Channels TX power 2083 * 2084 * Related MIB type: \ref MIB_CHANNELS_DEFAULT_TX_POWER 2085 */ 2086 int8_t ChannelsDefaultTxPower; 2087 /*! 2088 * Channels TX power 2089 * 2090 * Related MIB type: \ref MIB_CHANNELS_TX_POWER 2091 */ 2092 int8_t ChannelsTxPower; 2093 /*! 2094 * Multicast channels 2095 * 2096 * Related MIB type: \ref MIB_MULTICAST_CHANNEL 2097 */ 2098 McChannelParams_t MulticastChannel; 2099 /*! 2100 * System overall timing error in milliseconds. 2101 * 2102 * Related MIB type: \ref MIB_SYSTEM_MAX_RX_ERROR 2103 */ 2104 uint32_t SystemMaxRxError; 2105 /*! 2106 * Minimum required number of symbols to detect an Rx frame 2107 * 2108 * Related MIB type: \ref MIB_MIN_RX_SYMBOLS 2109 */ 2110 uint8_t MinRxSymbols; 2111 /*! 2112 * Antenna gain 2113 * 2114 * Related MIB type: \ref MIB_ANTENNA_GAIN 2115 */ 2116 float AntennaGain; 2117 /*! 2118 * Default antenna gain 2119 * 2120 * Related MIB type: \ref MIB_DEFAULT_ANTENNA_GAIN 2121 */ 2122 float DefaultAntennaGain; 2123 /*! 2124 * Returns a pointer to the structure holding all data which shall be stored 2125 * in the NVM. 2126 * 2127 * Related MIB type: \ref MIB_NVM_CTXS 2128 */ 2129 LoRaMacNvmData_t* Contexts; 2130 /* 2131 * LoRaWAN MAC layer operating version when activated by ABP. 2132 * 2133 * Related MIB type: \ref MIB_ABP_LORAWAN_VERSION 2134 */ 2135 Version_t AbpLrWanVersion; 2136 /* 2137 * LoRaWAN MAC regional parameter version. 2138 * 2139 * Related MIB type: \ref MIB_LORAWAN_VERSION 2140 */ 2141 struct sLrWanVersion 2142 { 2143 Version_t LoRaWan; 2144 Version_t LoRaWanRegion; 2145 }LrWanVersion; 2146 /*! 2147 * Beacon interval in ms 2148 * 2149 * Related MIB type: \ref MIB_BEACON_INTERVAL 2150 */ 2151 uint32_t BeaconInterval; 2152 /*! 2153 * Beacon reserved time in ms 2154 * 2155 * Related MIB type: \ref MIB_BEACON_RESERVED 2156 */ 2157 uint32_t BeaconReserved; 2158 /*! 2159 * Beacon guard time in ms 2160 * 2161 * Related MIB type: \ref MIB_BEACON_GUARD 2162 */ 2163 uint32_t BeaconGuard; 2164 /*! 2165 * Beacon window time in ms 2166 * 2167 * Related MIB type: \ref MIB_BEACON_WINDOW 2168 */ 2169 uint32_t BeaconWindow; 2170 /*! 2171 * Beacon window time in number of slots 2172 * 2173 * Related MIB type: \ref MIB_BEACON_WINDOW_SLOTS 2174 */ 2175 uint32_t BeaconWindowSlots; 2176 /*! 2177 * Ping slot length time in ms 2178 * 2179 * Related MIB type: \ref MIB_PING_SLOT_WINDOW 2180 */ 2181 uint32_t PingSlotWindow; 2182 /*! 2183 * Default symbol timeout for beacons and ping slot windows 2184 * 2185 * Related MIB type: \ref MIB_BEACON_SYMBOL_TO_DEFAULT 2186 */ 2187 uint32_t BeaconSymbolToDefault; 2188 /*! 2189 * Maximum symbol timeout for beacons 2190 * 2191 * Related MIB type: \ref MIB_BEACON_SYMBOL_TO_EXPANSION_MAX 2192 */ 2193 uint32_t BeaconSymbolToExpansionMax; 2194 /*! 2195 * Maximum symbol timeout for ping slots 2196 * 2197 * Related MIB type: \ref MIB_PING_SLOT_SYMBOL_TO_EXPANSION_MAX 2198 */ 2199 uint32_t PingSlotSymbolToExpansionMax; 2200 /*! 2201 * Symbol expansion value for beacon windows in case of beacon 2202 * loss in symbols 2203 * 2204 * Related MIB type: \ref MIB_BEACON_SYMBOL_TO_EXPANSION_FACTOR 2205 */ 2206 uint32_t BeaconSymbolToExpansionFactor; 2207 /*! 2208 * Symbol expansion value for ping slot windows in case of beacon 2209 * loss in symbols 2210 * 2211 * Related MIB type: \ref MIB_PING_SLOT_SYMBOL_TO_EXPANSION_FACTOR 2212 */ 2213 uint32_t PingSlotSymbolToExpansionFactor; 2214 /*! 2215 * Maximum allowed beacon less time in ms 2216 * 2217 * Related MIB type: \ref MIB_MAX_BEACON_LESS_PERIOD 2218 */ 2219 uint32_t MaxBeaconLessPeriod; 2220 /*! 2221 * Ping slots data rate 2222 * 2223 * Related MIB type: \ref MIB_PING_SLOT_DATARATE 2224 */ 2225 int8_t PingSlotDatarate; 2226 /*! 2227 * LoRaWAN certification FPort handling state (ON/OFF) 2228 * 2229 * Related MIB type: \ref MIB_IS_CERT_FPORT_ON 2230 */ 2231 bool IsCertPortOn; 2232 }MibParam_t; 2233 2234 /*! 2235 * LoRaMAC MIB-RequestConfirm structure 2236 */ 2237 typedef struct eMibRequestConfirm 2238 { 2239 /*! 2240 * MIB-Request type 2241 */ 2242 Mib_t Type; 2243 2244 /*! 2245 * MLME-RequestConfirm parameters 2246 */ 2247 MibParam_t Param; 2248 }MibRequestConfirm_t; 2249 2250 /*! 2251 * LoRaMAC tx information 2252 */ 2253 typedef struct sLoRaMacTxInfo 2254 { 2255 /*! 2256 * Size of the application data payload which can be transmitted. 2257 */ 2258 uint8_t MaxPossibleApplicationDataSize; 2259 /*! 2260 * The current maximum possible payload size without MAC commands 2261 * which is dependent on the current datarate. 2262 */ 2263 uint8_t CurrentPossiblePayloadSize; 2264 }LoRaMacTxInfo_t; 2265 2266 /*! 2267 * LoRaMAC Status 2268 */ 2269 typedef enum eLoRaMacStatus 2270 { 2271 /*! 2272 * Service started successfully 2273 */ 2274 LORAMAC_STATUS_OK, 2275 /*! 2276 * Service not started - LoRaMAC is busy 2277 */ 2278 LORAMAC_STATUS_BUSY, 2279 /*! 2280 * Service unknown 2281 */ 2282 LORAMAC_STATUS_SERVICE_UNKNOWN, 2283 /*! 2284 * Service not started - invalid parameter 2285 */ 2286 LORAMAC_STATUS_PARAMETER_INVALID, 2287 /*! 2288 * Service not started - invalid frequency 2289 */ 2290 LORAMAC_STATUS_FREQUENCY_INVALID, 2291 /*! 2292 * Service not started - invalid datarate 2293 */ 2294 LORAMAC_STATUS_DATARATE_INVALID, 2295 /*! 2296 * Service not started - invalid frequency and datarate 2297 */ 2298 LORAMAC_STATUS_FREQ_AND_DR_INVALID, 2299 /*! 2300 * Service not started - the device is not in a LoRaWAN 2301 */ 2302 LORAMAC_STATUS_NO_NETWORK_JOINED, 2303 /*! 2304 * Service not started - payload length error 2305 */ 2306 LORAMAC_STATUS_LENGTH_ERROR, 2307 /*! 2308 * Service not started - the specified region is not supported 2309 * or not activated with preprocessor definitions. 2310 */ 2311 LORAMAC_STATUS_REGION_NOT_SUPPORTED, 2312 /*! 2313 * The application data was not transmitted 2314 * because prioritized pending MAC commands had to be sent. 2315 */ 2316 LORAMAC_STATUS_SKIPPED_APP_DATA, 2317 /*! 2318 * An MCPS or MLME request can return this status. In this case, 2319 * the MAC cannot send the frame, as the duty cycle limits all 2320 * available bands. When a request returns this value, the 2321 * variable "DutyCycleWaitTime" in "ReqReturn" of the input 2322 * parameters contains the remaining time to wait. If the 2323 * value is constant and does not change, the expected time 2324 * on air for this frame is exceeding the maximum permitted 2325 * time according to the duty cycle time period, defined 2326 * in Region.h, DUTY_CYCLE_TIME_PERIOD. By default this time 2327 * is 1 hour, and a band with 1% duty cycle is then allowed 2328 * to use an air time of 36 seconds. 2329 */ 2330 LORAMAC_STATUS_DUTYCYCLE_RESTRICTED, 2331 /*! 2332 * 2333 */ 2334 LORAMAC_STATUS_NO_CHANNEL_FOUND, 2335 /*! 2336 * 2337 */ 2338 LORAMAC_STATUS_NO_FREE_CHANNEL_FOUND, 2339 /*! 2340 * ToDo 2341 */ 2342 LORAMAC_STATUS_BUSY_BEACON_RESERVED_TIME, 2343 /*! 2344 * ToDo 2345 */ 2346 LORAMAC_STATUS_BUSY_PING_SLOT_WINDOW_TIME, 2347 /*! 2348 * ToDo 2349 */ 2350 LORAMAC_STATUS_BUSY_UPLINK_COLLISION, 2351 /*! 2352 * An error in the cryptographic module is occurred 2353 */ 2354 LORAMAC_STATUS_CRYPTO_ERROR, 2355 /*! 2356 * An error in the frame counter handler module is occurred 2357 */ 2358 LORAMAC_STATUS_FCNT_HANDLER_ERROR, 2359 /*! 2360 * An error in the MAC command module is occurred 2361 */ 2362 LORAMAC_STATUS_MAC_COMMAD_ERROR, 2363 /*! 2364 * An error in the Class B module is occurred 2365 */ 2366 LORAMAC_STATUS_CLASS_B_ERROR, 2367 /*! 2368 * An error in the Confirm Queue module is occurred 2369 */ 2370 LORAMAC_STATUS_CONFIRM_QUEUE_ERROR, 2371 /*! 2372 * The multicast group doesn't exist 2373 */ 2374 LORAMAC_STATUS_MC_GROUP_UNDEFINED, 2375 /*! 2376 * Undefined error occurred 2377 */ 2378 LORAMAC_STATUS_ERROR 2379 }LoRaMacStatus_t; 2380 2381 /*! 2382 * LoRaMAC events structure 2383 * Used to notify upper layers of MAC events 2384 */ 2385 typedef struct sLoRaMacPrimitives 2386 { 2387 /*! 2388 * \brief MCPS-Confirm primitive 2389 * 2390 * \param [OUT] MCPS-Confirm parameters 2391 */ 2392 void ( *MacMcpsConfirm )( McpsConfirm_t* McpsConfirm ); 2393 /*! 2394 * \brief MCPS-Indication primitive 2395 * 2396 * \param [OUT] MCPS-Indication parameters 2397 */ 2398 void ( *MacMcpsIndication )( McpsIndication_t* McpsIndication ); 2399 /*! 2400 * \brief MLME-Confirm primitive 2401 * 2402 * \param [OUT] MLME-Confirm parameters 2403 */ 2404 void ( *MacMlmeConfirm )( MlmeConfirm_t* MlmeConfirm ); 2405 /*! 2406 * \brief MLME-Indication primitive 2407 * 2408 * \param [OUT] MLME-Indication parameters 2409 */ 2410 void ( *MacMlmeIndication )( MlmeIndication_t* MlmeIndication ); 2411 }LoRaMacPrimitives_t; 2412 2413 /*! 2414 * LoRaMAC callback structure 2415 */ 2416 typedef struct sLoRaMacCallback 2417 { 2418 /*! 2419 * \brief Measures the battery level 2420 * 2421 * \retval Battery level [0: node is connected to an external 2422 * power source, 1..254: battery level, where 1 is the minimum 2423 * and 254 is the maximum value, 255: the node was not able 2424 * to measure the battery level] 2425 */ 2426 uint8_t ( *GetBatteryLevel )( void ); 2427 /*! 2428 * \brief Measures the temperature level 2429 * 2430 * \retval Temperature level 2431 */ 2432 float ( *GetTemperatureLevel )( void ); 2433 /*! 2434 * \brief Will be called when an attribute has changed in one of the context. 2435 * 2436 * \param notifyFlags Bitmap that contains the modules which changed. 2437 * Refer to \ref LoRaMacNvmData_t. 2438 */ 2439 void ( *NvmDataChange )( uint16_t notifyFlags ); 2440 /*! 2441 *\brief Will be called each time a Radio IRQ is handled by the MAC 2442 * layer. 2443 * 2444 *\warning Runs in a IRQ context. Should only change variables state. 2445 */ 2446 void ( *MacProcessNotify )( void ); 2447 }LoRaMacCallback_t; 2448 2449 2450 /*! 2451 * LoRaMAC Max EIRP (dBm) table 2452 */ 2453 static const uint8_t LoRaMacMaxEirpTable[] = { 8, 10, 12, 13, 14, 16, 18, 20, 21, 24, 26, 27, 29, 30, 33, 36 }; 2454 2455 /*! 2456 * \brief LoRaMAC layer initialization 2457 * 2458 * \details In addition to the initialization of the LoRaMAC layer, this 2459 * function initializes the callback primitives of the MCPS and 2460 * MLME services. Every data field of \ref LoRaMacPrimitives_t must be 2461 * set to a valid callback function. 2462 * 2463 * \param [IN] primitives - Pointer to a structure defining the LoRaMAC 2464 * event functions. Refer to \ref LoRaMacPrimitives_t. 2465 * 2466 * \param [IN] callbacks - Pointer to a structure defining the LoRaMAC 2467 * callback functions. Refer to \ref LoRaMacCallback_t. 2468 * 2469 * \param [IN] region - The region to start. 2470 * 2471 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 2472 * returns are: 2473 * \ref LORAMAC_STATUS_OK, 2474 * \ref LORAMAC_STATUS_PARAMETER_INVALID, 2475 * \ref LORAMAC_STATUS_REGION_NOT_SUPPORTED. 2476 */ 2477 LoRaMacStatus_t LoRaMacInitialization( LoRaMacPrimitives_t* primitives, LoRaMacCallback_t* callbacks, LoRaMacRegion_t region ); 2478 2479 /*! 2480 * \brief Starts LoRaMAC layer 2481 * 2482 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 2483 * returns are: 2484 * \ref LORAMAC_STATUS_OK, 2485 */ 2486 LoRaMacStatus_t LoRaMacStart( void ); 2487 2488 /*! 2489 * \brief Stops LoRaMAC layer 2490 * 2491 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 2492 * returns are: 2493 * \ref LORAMAC_STATUS_OK, 2494 */ 2495 LoRaMacStatus_t LoRaMacStop( void ); 2496 2497 /*! 2498 * \brief Returns a value indicating if the MAC layer is busy or not. 2499 * 2500 * \retval isBusy Mac layer is busy. 2501 */ 2502 bool LoRaMacIsBusy( void ); 2503 2504 /*! 2505 * Processes the LoRaMac events. 2506 * 2507 * \remark This function must be called in the main loop. 2508 */ 2509 void LoRaMacProcess( void ); 2510 2511 /*! 2512 * \brief Queries the LoRaMAC if it is possible to send the next frame with 2513 * a given application data payload size. The LoRaMAC takes scheduled 2514 * MAC commands into account and reports, when the frame can be send or not. 2515 * 2516 * \param [IN] size - Size of application data payload to be send next 2517 * 2518 * \param [OUT] txInfo - The structure \ref LoRaMacTxInfo_t contains 2519 * information about the actual maximum payload possible 2520 * ( according to the configured datarate or the next 2521 * datarate according to ADR ), and the maximum frame 2522 * size, taking the scheduled MAC commands into account. 2523 * 2524 * \retval LoRaMacStatus_t Status of the operation. When the parameters are 2525 * not valid, the function returns \ref LORAMAC_STATUS_PARAMETER_INVALID. 2526 * In case of a length error caused by the application data payload in combination 2527 * with the MAC commands, the function returns \ref LORAMAC_STATUS_LENGTH_ERROR. 2528 * In this case its recommended to send a frame without application data to flush 2529 * the MAC commands. Otherwise the LoRaMAC will prioritize the MAC commands and 2530 * if needed it will skip the application data. Please note that if MAC commands do 2531 * not fit at all into the payload size on the related datarate, the LoRaMAC will 2532 * automatically clip the MAC commands. 2533 * In case the query is valid, and the LoRaMAC is able to send the frame, 2534 * the function returns \ref LORAMAC_STATUS_OK. 2535 */ 2536 LoRaMacStatus_t LoRaMacQueryTxPossible( uint8_t size, LoRaMacTxInfo_t* txInfo ); 2537 2538 /*! 2539 * \brief LoRaMAC channel add service 2540 * 2541 * \details Adds a new channel to the channel list and activates the id in 2542 * the channel mask. Please note that this functionality is not available 2543 * on all regions. Information about allowed ranges are available at the LoRaWAN Regional Parameters V1.0.2rB 2544 * 2545 * \param [IN] id - Id of the channel. 2546 * 2547 * \param [IN] params - Channel parameters to set. 2548 * 2549 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 2550 * \ref LORAMAC_STATUS_OK, 2551 * \ref LORAMAC_STATUS_BUSY, 2552 * \ref LORAMAC_STATUS_PARAMETER_INVALID. 2553 */ 2554 LoRaMacStatus_t LoRaMacChannelAdd( uint8_t id, ChannelParams_t params ); 2555 2556 /*! 2557 * \brief LoRaMAC channel remove service 2558 * 2559 * \details Deactivates the id in the channel mask. 2560 * 2561 * \param [IN] id - Id of the channel. 2562 * 2563 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 2564 * \ref LORAMAC_STATUS_OK, 2565 * \ref LORAMAC_STATUS_BUSY, 2566 * \ref LORAMAC_STATUS_PARAMETER_INVALID. 2567 */ 2568 LoRaMacStatus_t LoRaMacChannelRemove( uint8_t id ); 2569 2570 /*! 2571 * \brief LoRaMAC multicast channel setup service 2572 * 2573 * \details Sets up a multicast channel. 2574 * 2575 * \param [IN] channel - Multicast channel to set. 2576 * 2577 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 2578 * \ref LORAMAC_STATUS_OK, 2579 * \ref LORAMAC_STATUS_BUSY, 2580 * \ref LORAMAC_STATUS_PARAMETER_INVALID, 2581 * \ref LORAMAC_STATUS_MC_GROUP_UNDEFINED. 2582 */ 2583 LoRaMacStatus_t LoRaMacMcChannelSetup( McChannelParams_t *channel ); 2584 2585 /*! 2586 * \brief LoRaMAC multicast channel removal service 2587 * 2588 * \details Removes/Disables a multicast channel. 2589 * 2590 * \param [IN] groupID - Multicast channel ID to be removed/disabled 2591 * 2592 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 2593 * \ref LORAMAC_STATUS_OK, 2594 * \ref LORAMAC_STATUS_BUSY, 2595 * \ref LORAMAC_STATUS_MC_GROUP_UNDEFINED. 2596 */ 2597 LoRaMacStatus_t LoRaMacMcChannelDelete( AddressIdentifier_t groupID ); 2598 2599 /*! 2600 * \brief LoRaMAC multicast channel get groupId from MC address. 2601 * 2602 * \param [IN] mcAddress - Multicast address to be checked 2603 * 2604 * \retval groupID Multicast channel ID associated to the address. 2605 * Returns 0xFF if the address isn't found. 2606 */ 2607 uint8_t LoRaMacMcChannelGetGroupId( uint32_t mcAddress ); 2608 2609 /*! 2610 * \brief LoRaMAC multicast channel Rx parameters setup service 2611 * 2612 * \details Sets up a multicast channel reception parameters. 2613 * 2614 * \param [IN] groupID - Multicast channel ID 2615 * \param [IN] rxParams - Reception parameters 2616 * \param [OUT] status - Status mask [UNDEF_ID | FREQ_ERR | DR_ERR | GROUP_ID] 2617 * 2618 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 2619 * \ref LORAMAC_STATUS_OK, 2620 * \ref LORAMAC_STATUS_BUSY, 2621 * \ref LORAMAC_STATUS_PARAMETER_INVALID, 2622 * \ref LORAMAC_STATUS_MC_GROUP_UNDEFINED. 2623 */ 2624 LoRaMacStatus_t LoRaMacMcChannelSetupRxParams( AddressIdentifier_t groupID, McRxParams_t *rxParams, uint8_t *status ); 2625 2626 /*! 2627 * \brief LoRaMAC MIB-Get 2628 * 2629 * \details The mac information base service to get attributes of the LoRaMac 2630 * layer. 2631 * 2632 * The following code-snippet shows how to use the API to get the 2633 * parameter AdrEnable, defined by the enumeration type 2634 * \ref MIB_ADR. 2635 * \code 2636 * MibRequestConfirm_t mibReq; 2637 * mibReq.Type = MIB_ADR; 2638 * 2639 * if( LoRaMacMibGetRequestConfirm( &mibReq ) == LORAMAC_STATUS_OK ) 2640 * { 2641 * // LoRaMAC updated the parameter mibParam.AdrEnable 2642 * } 2643 * \endcode 2644 * 2645 * \param [IN] mibRequest - MIB-GET-Request to perform. Refer to \ref MibRequestConfirm_t. 2646 * 2647 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 2648 * \ref LORAMAC_STATUS_OK, 2649 * \ref LORAMAC_STATUS_SERVICE_UNKNOWN, 2650 * \ref LORAMAC_STATUS_PARAMETER_INVALID. 2651 */ 2652 LoRaMacStatus_t LoRaMacMibGetRequestConfirm( MibRequestConfirm_t* mibGet ); 2653 2654 /*! 2655 * \brief LoRaMAC MIB-Set 2656 * 2657 * \details The mac information base service to set attributes of the LoRaMac 2658 * layer. 2659 * 2660 * The following code-snippet shows how to use the API to set the 2661 * parameter AdrEnable, defined by the enumeration type 2662 * \ref MIB_ADR. 2663 * 2664 * \code 2665 * MibRequestConfirm_t mibReq; 2666 * mibReq.Type = MIB_ADR; 2667 * mibReq.Param.AdrEnable = true; 2668 * 2669 * if( LoRaMacMibGetRequestConfirm( &mibReq ) == LORAMAC_STATUS_OK ) 2670 * { 2671 * // LoRaMAC updated the parameter 2672 * } 2673 * \endcode 2674 * 2675 * \param [IN] mibRequest - MIB-SET-Request to perform. Refer to \ref MibRequestConfirm_t. 2676 * 2677 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 2678 * \ref LORAMAC_STATUS_OK, 2679 * \ref LORAMAC_STATUS_BUSY, 2680 * \ref LORAMAC_STATUS_SERVICE_UNKNOWN, 2681 * \ref LORAMAC_STATUS_PARAMETER_INVALID. 2682 */ 2683 LoRaMacStatus_t LoRaMacMibSetRequestConfirm( MibRequestConfirm_t* mibSet ); 2684 2685 /*! 2686 * \brief LoRaMAC MLME-Request 2687 * 2688 * \details The Mac layer management entity handles management services. The 2689 * following code-snippet shows how to use the API to perform a 2690 * network join request. Please note that for a join request, the 2691 * DevEUI and the JoinEUI must be set previously via the MIB. Please 2692 * also refer to the sample implementations. 2693 * 2694 * \code 2695 * 2696 * MlmeReq_t mlmeReq; 2697 * mlmeReq.Type = MLME_JOIN; 2698 * mlmeReq.Req.Join.Datarate = LORAWAN_DEFAULT_DATARATE; 2699 * 2700 * if( LoRaMacMlmeRequest( &mlmeReq ) == LORAMAC_STATUS_OK ) 2701 * { 2702 * // Service started successfully. Waiting for the Mlme-Confirm event 2703 * } 2704 * \endcode 2705 * 2706 * \param [IN] mlmeRequest - MLME-Request to perform. Refer to \ref MlmeReq_t. 2707 * 2708 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 2709 * \ref LORAMAC_STATUS_OK, 2710 * \ref LORAMAC_STATUS_BUSY, 2711 * \ref LORAMAC_STATUS_SERVICE_UNKNOWN, 2712 * \ref LORAMAC_STATUS_PARAMETER_INVALID, 2713 * \ref LORAMAC_STATUS_NO_NETWORK_JOINED, 2714 * \ref LORAMAC_STATUS_LENGTH_ERROR, 2715 */ 2716 LoRaMacStatus_t LoRaMacMlmeRequest( MlmeReq_t* mlmeRequest ); 2717 2718 /*! 2719 * \brief LoRaMAC MCPS-Request 2720 * 2721 * \details The Mac Common Part Sublayer handles data services. The following 2722 * code-snippet shows how to use the API to send an unconfirmed 2723 * LoRaMAC frame. 2724 * 2725 * \code 2726 * uint8_t myBuffer[] = { 1, 2, 3 }; 2727 * 2728 * McpsReq_t mcpsReq; 2729 * mcpsReq.Type = MCPS_UNCONFIRMED; 2730 * mcpsReq.Req.Unconfirmed.fPort = 1; 2731 * mcpsReq.Req.Unconfirmed.fBuffer = myBuffer; 2732 * mcpsReq.Req.Unconfirmed.fBufferSize = sizeof( myBuffer ); 2733 * 2734 * if( LoRaMacMcpsRequest( &mcpsReq ) == LORAMAC_STATUS_OK ) 2735 * { 2736 * // Service started successfully. Waiting for the MCPS-Confirm event 2737 * } 2738 * \endcode 2739 * 2740 * \param [IN] mcpsRequest - MCPS-Request to perform. Refer to \ref McpsReq_t. 2741 * 2742 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 2743 * \ref LORAMAC_STATUS_OK, 2744 * \ref LORAMAC_STATUS_BUSY, 2745 * \ref LORAMAC_STATUS_SERVICE_UNKNOWN, 2746 * \ref LORAMAC_STATUS_PARAMETER_INVALID, 2747 * \ref LORAMAC_STATUS_NO_NETWORK_JOINED, 2748 * \ref LORAMAC_STATUS_LENGTH_ERROR, 2749 */ 2750 LoRaMacStatus_t LoRaMacMcpsRequest( McpsReq_t* mcpsRequest ); 2751 2752 /*! 2753 * \brief LoRaMAC deinitialization 2754 * 2755 * \details This function stops the timers, re-initializes MAC & regional parameters to default 2756 * and sets radio into sleep state. 2757 * 2758 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 2759 * \ref LORAMAC_STATUS_OK, 2760 * \ref LORAMAC_STATUS_BUSY 2761 */ 2762 LoRaMacStatus_t LoRaMacDeInitialization( void ); 2763 2764 /*! \} defgroup LORAMAC */ 2765 2766 #ifdef __cplusplus 2767 } 2768 #endif 2769 2770 #endif // __LORAMAC_H__ 2771
