Senet
Fork of Semtech LoRaWAN stack
Fork of
LoRaWAN-lib
by 
canuck lehead
Embed:
(wiki syntax)
Show/hide line numbers
LoRaMac.h
Go to the documentation of this file.
00001 /*! 00002 * \file LoRaMac.h 00003 * 00004 * \brief LoRa MAC layer implementation 00005 * 00006 * \copyright Revised BSD License, see section \ref LICENSE. 00007 * 00008 * \code 00009 * ______ _ 00010 * / _____) _ | | 00011 * ( (____ _____ ____ _| |_ _____ ____| |__ 00012 * \____ \| ___ | (_ _) ___ |/ ___) _ \ 00013 * _____) ) ____| | | || |_| ____( (___| | | | 00014 * (______/|_____)_|_|_| \__)_____)\____)_| |_| 00015 * (C)2013 Semtech 00016 * 00017 * ___ _____ _ ___ _ _____ ___ ___ ___ ___ 00018 * / __|_ _/_\ / __| |/ / __/ _ \| _ \/ __| __| 00019 * \__ \ | |/ _ \ (__| ' <| _| (_) | / (__| _| 00020 * |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___| 00021 * embedded.connectivity.solutions=============== 00022 * 00023 * \endcode 00024 * 00025 * \author Miguel Luis ( Semtech ) 00026 * 00027 * \author Gregory Cristian ( Semtech ) 00028 * 00029 * \author Daniel Jäckle ( STACKFORCE ) 00030 * 00031 * \defgroup LORAMAC LoRa MAC layer implementation 00032 * This module specifies the API implementation of the LoRaMAC layer. 00033 * This is a placeholder for a detailed description of the LoRaMac 00034 * layer and the supported features. 00035 * \{ 00036 * 00037 * \example classA/LoRaMote/main.c 00038 * LoRaWAN class A application example for the LoRaMote. 00039 * 00040 * \example classB/LoRaMote/main.c 00041 * LoRaWAN class B application example for the LoRaMote. 00042 * 00043 * \example classC/LoRaMote/main.c 00044 * LoRaWAN class C application example for the LoRaMote. 00045 */ 00046 #ifndef __LORAMAC_H__ 00047 #define __LORAMAC_H__ 00048 00049 // Includes board dependent definitions such as channels frequencies 00050 #include "LoRaMac-board.h" 00051 00052 /*! 00053 * Stack Version Information 00054 */ 00055 #define LORAMAC_MAJOR_VERSION 4 00056 #define LORAMAC_MINOR_VERSION 2 00057 #define LORAMAC_POINT_VERSION 1 00058 00059 /*! 00060 * Beacon interval in us 00061 */ 00062 #define BEACON_INTERVAL 128000000 00063 00064 /*! 00065 * Class A&B receive delay 1 in us 00066 */ 00067 #define RECEIVE_DELAY1 1000000 00068 00069 /*! 00070 * Class A&B receive delay 2 in us 00071 */ 00072 #define RECEIVE_DELAY2 2000000 00073 00074 /*! 00075 * Join accept receive delay 1 in us 00076 */ 00077 #define JOIN_ACCEPT_DELAY1 5000000 00078 00079 /*! 00080 * Join accept receive delay 2 in us 00081 */ 00082 #define JOIN_ACCEPT_DELAY2 6000000 00083 00084 /*! 00085 * Class A&B maximum receive window delay in us 00086 */ 00087 #define MAX_RX_WINDOW 3000000 00088 00089 /*! 00090 * Maximum allowed gap for the FCNT field 00091 */ 00092 #define MAX_FCNT_GAP 16384 00093 00094 /*! 00095 * ADR acknowledgement counter limit 00096 */ 00097 #define ADR_ACK_LIMIT 64 00098 00099 /*! 00100 * Number of ADR acknowledgement requests before returning to default datarate 00101 */ 00102 #define ADR_ACK_DELAY 32 00103 00104 /*! 00105 * Number of seconds after the start of the second reception window without 00106 * receiving an acknowledge. 00107 * AckTimeout = \ref ACK_TIMEOUT + Random( -\ref ACK_TIMEOUT_RND, \ref ACK_TIMEOUT_RND ) 00108 */ 00109 #define ACK_TIMEOUT 2000000 00110 00111 /*! 00112 * Random number of seconds after the start of the second reception window without 00113 * receiving an acknowledge 00114 * AckTimeout = \ref ACK_TIMEOUT + Random( -\ref ACK_TIMEOUT_RND, \ref ACK_TIMEOUT_RND ) 00115 */ 00116 #define ACK_TIMEOUT_RND 1000000 00117 00118 /*! 00119 * Check the Mac layer state every MAC_STATE_CHECK_TIMEOUT in us 00120 */ 00121 #define MAC_STATE_CHECK_TIMEOUT 1000000 00122 00123 /*! 00124 * Maximum number of times the MAC layer tries to get an acknowledge. 00125 */ 00126 #define MAX_ACK_RETRIES 8 00127 00128 /*! 00129 * RSSI free threshold [dBm] 00130 */ 00131 #define RSSI_FREE_TH ( int8_t )( -90 ) 00132 00133 /*! 00134 * Frame direction definition for up-link communications 00135 */ 00136 #define UP_LINK 0 00137 00138 /*! 00139 * Frame direction definition for down-link communications 00140 */ 00141 #define DOWN_LINK 1 00142 00143 /*! 00144 * Sets the length of the LoRaMAC footer field. 00145 * Mainly indicates the MIC field length 00146 */ 00147 #define LORAMAC_MFR_LEN 4 00148 00149 /*! 00150 * Syncword for Private LoRa networks 00151 */ 00152 #define LORA_MAC_PRIVATE_SYNCWORD 0x12 00153 00154 /*! 00155 * Syncword for Public LoRa networks 00156 */ 00157 #define LORA_MAC_PUBLIC_SYNCWORD 0x34 00158 00159 00160 /*! 00161 * Sets the size of the Join Retransmission duty cycle 00162 * table 00163 */ 00164 #define JOIN_NB_RETRANSMISSION_DCYCLES 3 00165 00166 /*! 00167 * Join Aggregated duty cycle during the first hour 00168 */ 00169 #ifndef JOIN_RETRANSMISSION_DCYCLE1 00170 #define JOIN_RETRANSMISSION_DCYCLE1 { 3600, 36000000 } 00171 #endif 00172 00173 /*! 00174 * Join Aggregated duty cycle during the next 10 hours 00175 */ 00176 #ifndef JOIN_RETRANSMISSION_DCYCLE2 00177 #define JOIN_RETRANSMISSION_DCYCLE2 { 10*3600, 36000000 } 00178 #endif 00179 00180 /*! 00181 * Join Aggregated after the first 11 hours 00182 */ 00183 #ifndef JOIN_RETRANSMISSION_DCYCLE3 00184 #define JOIN_RETRANSMISSION_DCYCLE3 { 24*3600, 8700000 } 00185 #endif 00186 00187 /*! 00188 * LoRaMac internal state 00189 */ 00190 //uint32_t LoRaMacState; 00191 00192 /*! 00193 * LoRaWAN devices classes definition 00194 */ 00195 typedef enum eDeviceClass 00196 { 00197 /*! 00198 * LoRaWAN device class A 00199 * 00200 * LoRaWAN Specification V1.0, chapter 3ff 00201 */ 00202 CLASS_A , 00203 /*! 00204 * LoRaWAN device class B 00205 * 00206 * LoRaWAN Specification V1.0, chapter 8ff 00207 */ 00208 CLASS_B , 00209 /*! 00210 * LoRaWAN device class C 00211 * 00212 * LoRaWAN Specification V1.0, chapter 17ff 00213 */ 00214 CLASS_C , 00215 }DeviceClass_t ; 00216 00217 /*! 00218 * LoRaMAC channels parameters definition 00219 */ 00220 typedef union uDrRange 00221 { 00222 /*! 00223 * Byte-access to the bits 00224 */ 00225 int8_t Value ; 00226 /*! 00227 * Structure to store the minimum and the maximum datarate 00228 */ 00229 struct sFields 00230 { 00231 /*! 00232 * Minimum data rate 00233 * 00234 * EU868 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_5, DR_6, DR_7] 00235 * 00236 * US915 - [DR_0, DR_1, DR_2, DR_3, DR_4] 00237 */ 00238 int8_t Min : 4; 00239 /*! 00240 * Maximum data rate 00241 * 00242 * EU868 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_5, DR_6, DR_7] 00243 * 00244 * US915 - [DR_0, DR_1, DR_2, DR_3, DR_4] 00245 */ 00246 int8_t Max : 4; 00247 }Fields; 00248 }DrRange_t ; 00249 00250 /*! 00251 * LoRaMAC band parameters definition 00252 */ 00253 typedef struct sBand 00254 { 00255 /*! 00256 * Duty cycle 00257 */ 00258 uint16_t DCycle ; 00259 /*! 00260 * Maximum Tx power 00261 */ 00262 int8_t TxMaxPower ; 00263 /*! 00264 * Time stamp of the last Tx frame 00265 */ 00266 TimerTime_t LastTxDoneTime ; 00267 /*! 00268 * Holds the time where the device is off 00269 */ 00270 TimerTime_t TimeOff ; 00271 }Band_t ; 00272 00273 /*! 00274 * LoRaMAC channel definition 00275 */ 00276 typedef struct sChannelParams 00277 { 00278 /*! 00279 * Frequency in Hz 00280 */ 00281 uint32_t Frequency ; 00282 /*! 00283 * Data rate definition 00284 */ 00285 DrRange_t DrRange ; 00286 /*! 00287 * Band index 00288 */ 00289 uint8_t Band ; 00290 }ChannelParams_t ; 00291 00292 /*! 00293 * LoRaMAC receive window 2 channel parameters 00294 */ 00295 typedef struct sRx2ChannelParams 00296 { 00297 /*! 00298 * Frequency in Hz 00299 */ 00300 uint32_t Frequency ; 00301 /*! 00302 * Data rate 00303 * 00304 * EU868 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_5, DR_6, DR_7] 00305 * 00306 * US915 - [DR_8, DR_9, DR_10, DR_11, DR_12, DR_13] 00307 */ 00308 uint8_t Datarate ; 00309 }Rx2ChannelParams_t ; 00310 00311 /*! 00312 * LoRaMAC multicast channel parameter 00313 */ 00314 typedef struct sMulticastParams 00315 { 00316 /*! 00317 * Address 00318 */ 00319 uint32_t Address ; 00320 /*! 00321 * Network session key 00322 */ 00323 uint8_t NwkSKey [16]; 00324 /*! 00325 * Application session key 00326 */ 00327 uint8_t AppSKey [16]; 00328 /*! 00329 * Downlink counter 00330 */ 00331 uint32_t DownLinkCounter ; 00332 /*! 00333 * Reference pointer to the next multicast channel parameters in the list 00334 */ 00335 struct sMulticastParams *Next ; 00336 }MulticastParams_t ; 00337 00338 /*! 00339 * LoRaMAC frame types 00340 * 00341 * LoRaWAN Specification V1.0, chapter 4.2.1, table 1 00342 */ 00343 typedef enum eLoRaMacFrameType 00344 { 00345 /*! 00346 * LoRaMAC join request frame 00347 */ 00348 FRAME_TYPE_JOIN_REQ = 0x00, 00349 /*! 00350 * LoRaMAC join accept frame 00351 */ 00352 FRAME_TYPE_JOIN_ACCEPT = 0x01, 00353 /*! 00354 * LoRaMAC unconfirmed up-link frame 00355 */ 00356 FRAME_TYPE_DATA_UNCONFIRMED_UP = 0x02, 00357 /*! 00358 * LoRaMAC unconfirmed down-link frame 00359 */ 00360 FRAME_TYPE_DATA_UNCONFIRMED_DOWN = 0x03, 00361 /*! 00362 * LoRaMAC confirmed up-link frame 00363 */ 00364 FRAME_TYPE_DATA_CONFIRMED_UP = 0x04, 00365 /*! 00366 * LoRaMAC confirmed down-link frame 00367 */ 00368 FRAME_TYPE_DATA_CONFIRMED_DOWN = 0x05, 00369 /*! 00370 * LoRaMAC RFU frame 00371 */ 00372 FRAME_TYPE_RFU = 0x06, 00373 /*! 00374 * LoRaMAC proprietary frame 00375 */ 00376 FRAME_TYPE_PROPRIETARY = 0x07, 00377 }LoRaMacFrameType_t ; 00378 00379 /*! 00380 * LoRaMAC mote MAC commands 00381 * 00382 * LoRaWAN Specification V1.0, chapter 5, table 4 00383 */ 00384 typedef enum eLoRaMacMoteCmd 00385 { 00386 /*! 00387 * LinkCheckReq 00388 */ 00389 MOTE_MAC_LINK_CHECK_REQ = 0x02, 00390 /*! 00391 * LinkADRAns 00392 */ 00393 MOTE_MAC_LINK_ADR_ANS = 0x03, 00394 /*! 00395 * DutyCycleAns 00396 */ 00397 MOTE_MAC_DUTY_CYCLE_ANS = 0x04, 00398 /*! 00399 * RXParamSetupAns 00400 */ 00401 MOTE_MAC_RX_PARAM_SETUP_ANS = 0x05, 00402 /*! 00403 * DevStatusAns 00404 */ 00405 MOTE_MAC_DEV_STATUS_ANS = 0x06, 00406 /*! 00407 * NewChannelAns 00408 */ 00409 MOTE_MAC_NEW_CHANNEL_ANS = 0x07, 00410 /*! 00411 * RXTimingSetupAns 00412 */ 00413 MOTE_MAC_RX_TIMING_SETUP_ANS = 0x08, 00414 }LoRaMacMoteCmd_t ; 00415 00416 /*! 00417 * LoRaMAC server MAC commands 00418 * 00419 * LoRaWAN Specification V1.0, chapter 5, table 4 00420 */ 00421 typedef enum eLoRaMacSrvCmd 00422 { 00423 /*! 00424 * LinkCheckAns 00425 */ 00426 SRV_MAC_LINK_CHECK_ANS = 0x02, 00427 /*! 00428 * LinkADRReq 00429 */ 00430 SRV_MAC_LINK_ADR_REQ = 0x03, 00431 /*! 00432 * DutyCycleReq 00433 */ 00434 SRV_MAC_DUTY_CYCLE_REQ = 0x04, 00435 /*! 00436 * RXParamSetupReq 00437 */ 00438 SRV_MAC_RX_PARAM_SETUP_REQ = 0x05, 00439 /*! 00440 * DevStatusReq 00441 */ 00442 SRV_MAC_DEV_STATUS_REQ = 0x06, 00443 /*! 00444 * NewChannelReq 00445 */ 00446 SRV_MAC_NEW_CHANNEL_REQ = 0x07, 00447 /*! 00448 * RXTimingSetupReq 00449 */ 00450 SRV_MAC_RX_TIMING_SETUP_REQ = 0x08, 00451 }LoRaMacSrvCmd_t ; 00452 00453 /*! 00454 * LoRaMAC Battery level indicator 00455 */ 00456 typedef enum eLoRaMacBatteryLevel 00457 { 00458 /*! 00459 * External power source 00460 */ 00461 BAT_LEVEL_EXT_SRC = 0x00, 00462 /*! 00463 * Battery level empty 00464 */ 00465 BAT_LEVEL_EMPTY = 0x01, 00466 /*! 00467 * Battery level full 00468 */ 00469 BAT_LEVEL_FULL = 0xFE, 00470 /*! 00471 * Battery level - no measurement available 00472 */ 00473 BAT_LEVEL_NO_MEASURE = 0xFF, 00474 }LoRaMacBatteryLevel_t ; 00475 00476 /*! 00477 * LoRaMAC header field definition (MHDR field) 00478 * 00479 * LoRaWAN Specification V1.0, chapter 4.2 00480 */ 00481 typedef union uLoRaMacHeader 00482 { 00483 /*! 00484 * Byte-access to the bits 00485 */ 00486 uint8_t Value ; 00487 /*! 00488 * Structure containing single access to header bits 00489 */ 00490 struct sHdrBits 00491 { 00492 /*! 00493 * Major version 00494 */ 00495 uint8_t Major : 2; 00496 /*! 00497 * RFU 00498 */ 00499 uint8_t RFU : 3; 00500 /*! 00501 * Message type 00502 */ 00503 uint8_t MType : 3; 00504 }Bits; 00505 }LoRaMacHeader_t ; 00506 00507 /*! 00508 * LoRaMAC frame control field definition (FCtrl) 00509 * 00510 * LoRaWAN Specification V1.0, chapter 4.3.1 00511 */ 00512 typedef union uLoRaMacFrameCtrl 00513 { 00514 /*! 00515 * Byte-access to the bits 00516 */ 00517 uint8_t Value ; 00518 /*! 00519 * Structure containing single access to bits 00520 */ 00521 struct sCtrlBits 00522 { 00523 /*! 00524 * Frame options length 00525 */ 00526 uint8_t FOptsLen : 4; 00527 /*! 00528 * Frame pending bit 00529 */ 00530 uint8_t FPending : 1; 00531 /*! 00532 * Message acknowledge bit 00533 */ 00534 uint8_t Ack : 1; 00535 /*! 00536 * ADR acknowledgment request bit 00537 */ 00538 uint8_t AdrAckReq : 1; 00539 /*! 00540 * ADR control in frame header 00541 */ 00542 uint8_t Adr : 1; 00543 }Bits; 00544 }LoRaMacFrameCtrl_t ; 00545 00546 /*! 00547 * Enumeration containing the status of the operation of a MAC service 00548 */ 00549 typedef enum eLoRaMacEventInfoStatus 00550 { 00551 /*! 00552 * Service performed successfully 00553 */ 00554 LORAMAC_EVENT_INFO_STATUS_OK = 0, 00555 /*! 00556 * An error occured during the execution of the service 00557 */ 00558 LORAMAC_EVENT_INFO_STATUS_ERROR , 00559 /*! 00560 * A Tx timeouit occured 00561 */ 00562 LORAMAC_EVENT_INFO_STATUS_TX_TIMEOUT , 00563 /*! 00564 * An Rx timeout occured on receive window 2 00565 */ 00566 LORAMAC_EVENT_INFO_STATUS_RX2_TIMEOUT , 00567 /*! 00568 * An Rx error occured on receive window 2 00569 */ 00570 LORAMAC_EVENT_INFO_STATUS_RX2_ERROR , 00571 /*! 00572 * An error occured in the join procedure 00573 */ 00574 LORAMAC_EVENT_INFO_STATUS_JOIN_FAIL , 00575 /*! 00576 * A frame with an invalid downlink counter was received. The 00577 * downlink counter of the frame was equal to the local copy 00578 * of the downlink counter of the node. 00579 */ 00580 LORAMAC_EVENT_INFO_STATUS_DOWNLINK_REPEATED , 00581 /*! 00582 * The node has lost MAX_FCNT_GAP or more frames. 00583 */ 00584 LORAMAC_EVENT_INFO_STATUS_DOWNLINK_TOO_MANY_FRAMES_LOSS , 00585 /*! 00586 * An address error occured 00587 */ 00588 LORAMAC_EVENT_INFO_STATUS_ADDRESS_FAIL , 00589 /*! 00590 * message integrity check failure 00591 */ 00592 LORAMAC_EVENT_INFO_STATUS_MIC_FAIL , 00593 }LoRaMacEventInfoStatus_t ; 00594 00595 /*! 00596 * LoRaMac tx/rx operation state 00597 */ 00598 typedef union eLoRaMacFlags_t 00599 { 00600 /*! 00601 * Byte-access to the bits 00602 */ 00603 uint8_t Value ; 00604 /*! 00605 * Structure containing single access to bits 00606 */ 00607 struct sMacFlagBits 00608 { 00609 /*! 00610 * MCPS-Req pending 00611 */ 00612 uint8_t McpsReq : 1; 00613 /*! 00614 * MCPS-Ind pending 00615 */ 00616 uint8_t McpsInd : 1; 00617 /*! 00618 * MLME-Req pending 00619 */ 00620 uint8_t MlmeReq : 1; 00621 /*! 00622 * MAC cycle done 00623 */ 00624 uint8_t MacDone : 1; 00625 }Bits; 00626 }LoRaMacFlags_t ; 00627 00628 /*! 00629 * 00630 * \brief LoRaMAC data services 00631 * 00632 * \details The following table list the primitives which are supported by the 00633 * specific MAC data service: 00634 * 00635 * Name | Request | Indication | Response | Confirm 00636 * --------------------- | :-----: | :--------: | :------: | :-----: 00637 * \ref MCPS_UNCONFIRMED | YES | YES | NO | YES 00638 * \ref MCPS_CONFIRMED | YES | YES | NO | YES 00639 * \ref MCPS_MULTICAST | NO | YES | NO | NO 00640 * \ref MCPS_PROPRIETARY | YES | YES | NO | YES 00641 * 00642 * The following table provides links to the function implementations of the 00643 * related MCPS primitives: 00644 * 00645 * Primitive | Function 00646 * ---------------- | :---------------------: 00647 * MCPS-Request | \ref LoRaMacMlmeRequest 00648 * MCPS-Confirm | MacMcpsConfirm in \ref LoRaMacPrimitives_t 00649 * MCPS-Indication | MacMcpsIndication in \ref LoRaMacPrimitives_t 00650 */ 00651 typedef enum eMcps 00652 { 00653 /*! 00654 * Unconfirmed LoRaMAC frame 00655 */ 00656 MCPS_UNCONFIRMED , 00657 /*! 00658 * Confirmed LoRaMAC frame 00659 */ 00660 MCPS_CONFIRMED , 00661 /*! 00662 * Multicast LoRaMAC frame 00663 */ 00664 MCPS_MULTICAST , 00665 /*! 00666 * Proprietary frame 00667 */ 00668 MCPS_PROPRIETARY , 00669 }Mcps_t; 00670 00671 /*! 00672 * LoRaMAC MCPS-Request for an unconfirmed frame 00673 */ 00674 typedef struct sMcpsReqUnconfirmed 00675 { 00676 /*! 00677 * Frame port field. Must be set if the payload is not empty. Use the 00678 * application specific frame port values: [1...223] 00679 * 00680 * LoRaWAN Specification V1.0, chapter 4.3.2 00681 */ 00682 uint8_t fPort ; 00683 /*! 00684 * Pointer to the buffer of the frame payload 00685 */ 00686 void *fBuffer ; 00687 /*! 00688 * Size of the frame payload 00689 */ 00690 uint16_t fBufferSize ; 00691 /*! 00692 * Uplink datarate, if ADR is off 00693 */ 00694 int8_t Datarate ; 00695 }McpsReqUnconfirmed_t ; 00696 00697 /*! 00698 * LoRaMAC MCPS-Request for a confirmed frame 00699 */ 00700 typedef struct sMcpsReqConfirmed 00701 { 00702 /*! 00703 * Frame port field. Must be set if the payload is not empty. Use the 00704 * application specific frame port values: [1...223] 00705 * 00706 * LoRaWAN Specification V1.0, chapter 4.3.2 00707 */ 00708 uint8_t fPort ; 00709 /*! 00710 * Pointer to the buffer of the frame payload 00711 */ 00712 void *fBuffer ; 00713 /*! 00714 * Size of the frame payload 00715 */ 00716 uint16_t fBufferSize ; 00717 /*! 00718 * Uplink datarate, if ADR is off 00719 */ 00720 int8_t Datarate ; 00721 /*! 00722 * Number of trials to transmit the frame, if the LoRaMAC layer did not 00723 * receive an acknowledgment. The MAC performs a datarate adaptation, 00724 * according to the LoRaWAN Specification V1.0, chapter 18.4, according 00725 * to the following table: 00726 * 00727 * Transmission nb | Data Rate 00728 * ----------------|----------- 00729 * 1 (first) | DR 00730 * 2 | DR 00731 * 3 | max(DR-1,0) 00732 * 4 | max(DR-1,0) 00733 * 5 | max(DR-2,0) 00734 * 6 | max(DR-2,0) 00735 * 7 | max(DR-3,0) 00736 * 8 | max(DR-3,0) 00737 * 00738 * Note, that if NbTrials is set to 1 or 2, the MAC will not decrease 00739 * the datarate, in case the LoRaMAC layer did not receive an acknowledgment 00740 */ 00741 uint8_t NbTrials ; 00742 }McpsReqConfirmed_t ; 00743 00744 /*! 00745 * LoRaMAC MCPS-Request for a proprietary frame 00746 */ 00747 typedef struct sMcpsReqProprietary 00748 { 00749 /*! 00750 * Pointer to the buffer of the frame payload 00751 */ 00752 void *fBuffer ; 00753 /*! 00754 * Size of the frame payload 00755 */ 00756 uint16_t fBufferSize ; 00757 /*! 00758 * Uplink datarate, if ADR is off 00759 */ 00760 int8_t Datarate ; 00761 }McpsReqProprietary_t ; 00762 00763 /*! 00764 * LoRaMAC MCPS-Request structure 00765 */ 00766 typedef struct sMcpsReq 00767 { 00768 /*! 00769 * MCPS-Request type 00770 */ 00771 Mcps_t Type ; 00772 00773 /*! 00774 * MCPS-Request parameters 00775 */ 00776 union uMcpsParam 00777 { 00778 /*! 00779 * MCPS-Request parameters for an unconfirmed frame 00780 */ 00781 McpsReqUnconfirmed_t Unconfirmed ; 00782 /*! 00783 * MCPS-Request parameters for a confirmed frame 00784 */ 00785 McpsReqConfirmed_t Confirmed ; 00786 /*! 00787 * MCPS-Request parameters for a proprietary frame 00788 */ 00789 McpsReqProprietary_t Proprietary ; 00790 }Req; 00791 }McpsReq_t ; 00792 00793 /*! 00794 * LoRaMAC MCPS-Confirm 00795 */ 00796 typedef struct sMcpsConfirm 00797 { 00798 /*! 00799 * Holds the previously performed MCPS-Request 00800 */ 00801 Mcps_t McpsRequest ; 00802 /*! 00803 * Status of the operation 00804 */ 00805 LoRaMacEventInfoStatus_t Status ; 00806 /*! 00807 * Uplink datarate 00808 */ 00809 uint8_t Datarate ; 00810 /*! 00811 * Transmission power 00812 */ 00813 int8_t TxPower ; 00814 /*! 00815 * Set if an acknowledgement was received 00816 */ 00817 bool AckReceived ; 00818 /*! 00819 * Provides the number of retransmissions 00820 */ 00821 uint8_t NbRetries ; 00822 /*! 00823 * The transmission time on air of the frame 00824 */ 00825 TimerTime_t TxTimeOnAir ; 00826 /*! 00827 * The uplink counter value related to the frame 00828 */ 00829 uint32_t UpLinkCounter ; 00830 }McpsConfirm_t ; 00831 00832 /*! 00833 * LoRaMAC MCPS-Indication primitive 00834 */ 00835 typedef struct sMcpsIndication 00836 { 00837 /*! 00838 * MCPS-Indication type 00839 */ 00840 Mcps_t McpsIndication ; 00841 /*! 00842 * Status of the operation 00843 */ 00844 LoRaMacEventInfoStatus_t Status ; 00845 /*! 00846 * Multicast 00847 */ 00848 uint8_t Multicast ; 00849 /*! 00850 * Application port 00851 */ 00852 uint8_t Port ; 00853 /*! 00854 * Downlink datarate 00855 */ 00856 uint8_t RxDatarate ; 00857 /*! 00858 * Frame pending status 00859 */ 00860 uint8_t FramePending ; 00861 /*! 00862 * Pointer to the received data stream 00863 */ 00864 uint8_t *Buffer ; 00865 /*! 00866 * Size of the received data stream 00867 */ 00868 uint8_t BufferSize ; 00869 /*! 00870 * Indicates, if data is available 00871 */ 00872 bool RxData ; 00873 /*! 00874 * Rssi of the received packet 00875 */ 00876 int16_t Rssi ; 00877 /*! 00878 * Snr of the received packet 00879 */ 00880 uint8_t Snr ; 00881 /*! 00882 * Receive window 00883 * 00884 * [0: Rx window 1, 1: Rx window 2] 00885 */ 00886 uint8_t RxSlot ; 00887 /*! 00888 * Set if an acknowledgement was received 00889 */ 00890 bool AckReceived ; 00891 /*! 00892 * The downlink counter value for the received frame 00893 */ 00894 uint32_t DownLinkCounter ; 00895 }McpsIndication_t ; 00896 00897 /*! 00898 * \brief LoRaMAC management services 00899 * 00900 * \details The following table list the primitives which are supported by the 00901 * specific MAC management service: 00902 * 00903 * Name | Request | Indication | Response | Confirm 00904 * --------------------- | :-----: | :--------: | :------: | :-----: 00905 * \ref MLME_JOIN | YES | NO | NO | YES 00906 * \ref MLME_LINK_CHECK | YES | NO | NO | YES 00907 * 00908 * The following table provides links to the function implementations of the 00909 * related MLME primitives. 00910 * 00911 * Primitive | Function 00912 * ---------------- | :---------------------: 00913 * MLME-Request | \ref LoRaMacMlmeRequest 00914 * MLME-Confirm | MacMlmeConfirm in \ref LoRaMacPrimitives_t 00915 */ 00916 typedef enum eMlme 00917 { 00918 /*! 00919 * Initiates the Over-the-Air activation 00920 * 00921 * LoRaWAN Specification V1.0, chapter 6.2 00922 */ 00923 MLME_JOIN , 00924 /*! 00925 * LinkCheckReq - Connectivity validation 00926 * 00927 * LoRaWAN Specification V1.0, chapter 5, table 4 00928 */ 00929 MLME_LINK_CHECK , 00930 }Mlme_t; 00931 00932 /*! 00933 * LoRaMAC MLME-Request for the join service 00934 */ 00935 typedef struct sMlmeReqJoin 00936 { 00937 /*! 00938 * Globally unique end-device identifier 00939 * 00940 * LoRaWAN Specification V1.0, chapter 6.2.1 00941 */ 00942 uint8_t *DevEui ; 00943 /*! 00944 * Application identifier 00945 * 00946 * LoRaWAN Specification V1.0, chapter 6.1.2 00947 */ 00948 uint8_t *AppEui ; 00949 /*! 00950 * AES-128 application key 00951 * 00952 * LoRaWAN Specification V1.0, chapter 6.2.2 00953 */ 00954 uint8_t *AppKey ; 00955 }MlmeReqJoin_t ; 00956 00957 /*! 00958 * LoRaMAC MLME-Request structure 00959 */ 00960 typedef struct sMlmeReq 00961 { 00962 /*! 00963 * MLME-Request type 00964 */ 00965 Mlme_t Type ; 00966 00967 /*! 00968 * MLME-Request parameters 00969 */ 00970 union uMlmeParam 00971 { 00972 /*! 00973 * MLME-Request parameters for a join request 00974 */ 00975 MlmeReqJoin_t Join ; 00976 }Req; 00977 }MlmeReq_t ; 00978 00979 /*! 00980 * LoRaMAC MLME-Confirm primitive 00981 */ 00982 typedef struct sMlmeConfirm 00983 { 00984 /*! 00985 * Holds the previously performed MLME-Request 00986 */ 00987 Mlme_t MlmeRequest ; 00988 /*! 00989 * Status of the operation 00990 */ 00991 LoRaMacEventInfoStatus_t Status ; 00992 /*! 00993 * The transmission time on air of the frame 00994 */ 00995 TimerTime_t TxTimeOnAir ; 00996 /*! 00997 * Demodulation margin. Contains the link margin [dB] of the last 00998 * successfully received LinkCheckReq 00999 */ 01000 uint8_t DemodMargin ; 01001 /*! 01002 * Number of gateways which received the last LinkCheckReq 01003 */ 01004 uint8_t NbGateways ; 01005 }MlmeConfirm_t ; 01006 01007 /*! 01008 * LoRa Mac Information Base (MIB) 01009 * 01010 * The following table lists the MIB parameters and the related attributes: 01011 * 01012 * Attribute | Get | Set 01013 * --------------------------------- | :-: | :-: 01014 * \ref MIB_DEVICE_CLASS | YES | YES 01015 * \ref MIB_NETWORK_JOINED | YES | YES 01016 * \ref MIB_ADR | YES | YES 01017 * \ref MIB_NET_ID | YES | YES 01018 * \ref MIB_DEV_ADDR | YES | YES 01019 * \ref MIB_NWK_SKEY | YES | YES 01020 * \ref MIB_APP_SKEY | YES | YES 01021 * \ref MIB_PUBLIC_NETWORK | YES | YES 01022 * \ref MIB_REPEATER_SUPPORT | YES | YES 01023 * \ref MIB_CHANNELS | YES | NO 01024 * \ref MIB_RX2_CHANNEL | YES | YES 01025 * \ref MIB_CHANNELS_MASK | YES | YES 01026 * \ref MIB_CHANNELS_NB_REP | YES | YES 01027 * \ref MIB_MAX_RX_WINDOW_DURATION | YES | YES 01028 * \ref MIB_RECEIVE_DELAY_1 | YES | YES 01029 * \ref MIB_RECEIVE_DELAY_2 | YES | YES 01030 * \ref MIB_JOIN_ACCEPT_DELAY_1 | YES | YES 01031 * \ref MIB_JOIN_ACCEPT_DELAY_2 | YES | YES 01032 * \ref MIB_CHANNELS_DATARATE | YES | YES 01033 * \ref MIB_CHANNELS_DEFAULT_DATARATE| YES | YES 01034 * \ref MIB_CHANNELS_TX_POWER | YES | YES 01035 * \ref MIB_UPLINK_COUNTER | YES | YES 01036 * \ref MIB_DOWNLINK_COUNTER | YES | YES 01037 * \ref MIB_MULTICAST_CHANNEL | YES | NO 01038 * 01039 * The following table provides links to the function implementations of the 01040 * related MIB primitives: 01041 * 01042 * Primitive | Function 01043 * ---------------- | :---------------------: 01044 * MIB-Set | \ref LoRaMacMibSetRequestConfirm 01045 * MIB-Get | \ref LoRaMacMibGetRequestConfirm 01046 */ 01047 typedef enum eMib 01048 { 01049 /*! 01050 * LoRaWAN device class 01051 * 01052 * LoRaWAN Specification V1.0 01053 */ 01054 MIB_DEVICE_CLASS , 01055 /*! 01056 * LoRaWAN Network joined attribute 01057 * 01058 * LoRaWAN Specification V1.0 01059 */ 01060 MIB_NETWORK_JOINED , 01061 /*! 01062 * Adaptive data rate 01063 * 01064 * LoRaWAN Specification V1.0, chapter 4.3.1.1 01065 * 01066 * [true: ADR enabled, false: ADR disabled] 01067 */ 01068 MIB_ADR , 01069 /*! 01070 * Network identifier 01071 * 01072 * LoRaWAN Specification V1.0, chapter 6.2.5 01073 */ 01074 MIB_NET_ID , 01075 /*! 01076 * End-device address 01077 * 01078 * LoRaWAN Specification V1.0, chapter 6.1.2 01079 */ 01080 MIB_DEV_ADDR , 01081 /*! 01082 * Network session key 01083 * 01084 * LoRaWAN Specification V1.0, chapter 6.1.3 01085 */ 01086 MIB_NWK_SKEY , 01087 /*! 01088 * Application session key 01089 * 01090 * LoRaWAN Specification V1.0, chapter 6.1.4 01091 */ 01092 MIB_APP_SKEY , 01093 /*! 01094 * Set the network type to public or private 01095 * 01096 * LoRaWAN Specification V1.0, chapter 7 01097 * 01098 * [true: public network, false: private network] 01099 */ 01100 MIB_PUBLIC_NETWORK , 01101 /*! 01102 * Support the operation with repeaters 01103 * 01104 * LoRaWAN Specification V1.0, chapter 7 01105 * 01106 * [true: repeater support enabled, false: repeater support disabled] 01107 */ 01108 MIB_REPEATER_SUPPORT , 01109 /*! 01110 * Communication channels. A get request will return a 01111 * pointer which references the first entry of the channel list. The 01112 * list is of size LORA_MAX_NB_CHANNELS 01113 * 01114 * LoRaWAN Specification V1.0, chapter 7 01115 */ 01116 MIB_CHANNELS , 01117 /*! 01118 * Set receive window 2 channel 01119 * 01120 * LoRaWAN Specification V1.0, chapter 3.3.2 01121 */ 01122 MIB_RX2_CHANNEL , 01123 /*! 01124 * LoRaWAN channels mask 01125 * 01126 * LoRaWAN Specification V1.0, chapter 5.2 01127 */ 01128 MIB_CHANNELS_MASK , 01129 /*! 01130 * Set the number of repetitions on a channel 01131 * 01132 * LoRaWAN Specification V1.0, chapter 5.2 01133 */ 01134 MIB_CHANNELS_NB_REP , 01135 /*! 01136 * Maximum receive window duration in [us] 01137 * 01138 * LoRaWAN Specification V1.0, chapter 3.3.3 01139 */ 01140 MIB_MAX_RX_WINDOW_DURATION , 01141 /*! 01142 * Receive delay 1 in [us] 01143 * 01144 * LoRaWAN Specification V1.0, chapter 6 01145 */ 01146 MIB_RECEIVE_DELAY_1 , 01147 /*! 01148 * Receive delay 2 in [us] 01149 * 01150 * LoRaWAN Specification V1.0, chapter 6 01151 */ 01152 MIB_RECEIVE_DELAY_2 , 01153 /*! 01154 * Join accept delay 1 in [us] 01155 * 01156 * LoRaWAN Specification V1.0, chapter 6 01157 */ 01158 MIB_JOIN_ACCEPT_DELAY_1 , 01159 /*! 01160 * Join accept delay 2 in [us] 01161 * 01162 * LoRaWAN Specification V1.0, chapter 6 01163 */ 01164 MIB_JOIN_ACCEPT_DELAY_2 , 01165 /*! 01166 * Default Data rate of a channel 01167 * 01168 * LoRaWAN Specification V1.0, chapter 7 01169 * 01170 * EU868 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_5, DR_6, DR_7] 01171 * 01172 * US915 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_8, DR_9, DR_10, DR_11, DR_12, DR_13] 01173 */ 01174 MIB_CHANNELS_DEFAULT_DATARATE , 01175 /*! 01176 * Data rate of a channel 01177 * 01178 * LoRaWAN Specification V1.0, chapter 7 01179 * 01180 * EU868 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_5, DR_6, DR_7] 01181 * 01182 * US915 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_8, DR_9, DR_10, DR_11, DR_12, DR_13] 01183 */ 01184 MIB_CHANNELS_DATARATE , 01185 /*! 01186 * Transmission power of a channel 01187 * 01188 * LoRaWAN Specification V1.0, chapter 7 01189 * 01190 * EU868 - [TX_POWER_20_DBM, TX_POWER_14_DBM, TX_POWER_11_DBM, 01191 * TX_POWER_08_DBM, TX_POWER_05_DBM, TX_POWER_02_DBM] 01192 * 01193 * US915 - [TX_POWER_30_DBM, TX_POWER_28_DBM, TX_POWER_26_DBM, 01194 * TX_POWER_24_DBM, TX_POWER_22_DBM, TX_POWER_20_DBM, 01195 * TX_POWER_18_DBM, TX_POWER_14_DBM, TX_POWER_12_DBM, 01196 * TX_POWER_10_DBM] 01197 */ 01198 MIB_CHANNELS_TX_POWER , 01199 /*! 01200 * LoRaWAN Up-link counter 01201 * 01202 * LoRaWAN Specification V1.0, chapter 4.3.1.5 01203 */ 01204 MIB_UPLINK_COUNTER , 01205 /*! 01206 * LoRaWAN Down-link counter 01207 * 01208 * LoRaWAN Specification V1.0, chapter 4.3.1.5 01209 */ 01210 MIB_DOWNLINK_COUNTER , 01211 /*! 01212 * Multicast channels. A get request will return a pointer to the first 01213 * entry of the multicast channel linked list. If the pointer is equal to 01214 * NULL, the list is empty. 01215 */ 01216 MIB_MULTICAST_CHANNEL , 01217 }Mib_t ; 01218 01219 /*! 01220 * LoRaMAC MIB parameters 01221 */ 01222 typedef union uMibParam 01223 { 01224 /*! 01225 * LoRaWAN device class 01226 * 01227 * Related MIB type: \ref MIB_DEVICE_CLASS 01228 */ 01229 DeviceClass_t Class ; 01230 /*! 01231 * LoRaWAN network joined attribute 01232 * 01233 * Related MIB type: \ref MIB_NETWORK_JOINED 01234 */ 01235 bool IsNetworkJoined ; 01236 /*! 01237 * Activation state of ADR 01238 * 01239 * Related MIB type: \ref MIB_ADR 01240 */ 01241 bool AdrEnable ; 01242 /*! 01243 * Network identifier 01244 * 01245 * Related MIB type: \ref MIB_NET_ID 01246 */ 01247 uint32_t NetID ; 01248 /*! 01249 * End-device address 01250 * 01251 * Related MIB type: \ref MIB_DEV_ADDR 01252 */ 01253 uint32_t DevAddr ; 01254 /*! 01255 * Network session key 01256 * 01257 * Related MIB type: \ref MIB_NWK_SKEY 01258 */ 01259 uint8_t *NwkSKey ; 01260 /*! 01261 * Application session key 01262 * 01263 * Related MIB type: \ref MIB_APP_SKEY 01264 */ 01265 uint8_t *AppSKey ; 01266 /*! 01267 * Enable or disable a public network 01268 * 01269 * Related MIB type: \ref MIB_PUBLIC_NETWORK 01270 */ 01271 bool EnablePublicNetwork ; 01272 /*! 01273 * Enable or disable repeater support 01274 * 01275 * Related MIB type: \ref MIB_REPEATER_SUPPORT 01276 */ 01277 bool EnableRepeaterSupport ; 01278 /*! 01279 * LoRaWAN Channel 01280 * 01281 * Related MIB type: \ref MIB_CHANNELS 01282 */ 01283 ChannelParams_t * ChannelList ; 01284 /*! 01285 * Channel for the receive window 2 01286 * 01287 * Related MIB type: \ref MIB_RX2_CHANNEL 01288 */ 01289 Rx2ChannelParams_t Rx2Channel ; 01290 /*! 01291 * Channel mask 01292 * 01293 * Related MIB type: \ref MIB_CHANNELS_MASK 01294 */ 01295 uint16_t* ChannelsMask ; 01296 /*! 01297 * Number of frame repetitions 01298 * 01299 * Related MIB type: \ref MIB_CHANNELS_NB_REP 01300 */ 01301 uint8_t ChannelNbRep ; 01302 /*! 01303 * Maximum receive window duration 01304 * 01305 * Related MIB type: \ref MIB_MAX_RX_WINDOW_DURATION 01306 */ 01307 uint32_t MaxRxWindow ; 01308 /*! 01309 * Receive delay 1 01310 * 01311 * Related MIB type: \ref MIB_RECEIVE_DELAY_1 01312 */ 01313 uint32_t ReceiveDelay1 ; 01314 /*! 01315 * Receive delay 2 01316 * 01317 * Related MIB type: \ref MIB_RECEIVE_DELAY_2 01318 */ 01319 uint32_t ReceiveDelay2 ; 01320 /*! 01321 * Join accept delay 1 01322 * 01323 * Related MIB type: \ref MIB_JOIN_ACCEPT_DELAY_1 01324 */ 01325 uint32_t JoinAcceptDelay1 ; 01326 /*! 01327 * Join accept delay 2 01328 * 01329 * Related MIB type: \ref MIB_JOIN_ACCEPT_DELAY_2 01330 */ 01331 uint32_t JoinAcceptDelay2 ; 01332 /*! 01333 * Channels data rate 01334 * 01335 * Related MIB type: \ref MIB_CHANNELS_DEFAULT_DATARATE 01336 */ 01337 int8_t ChannelsDefaultDatarate ; 01338 /*! 01339 * Channels data rate 01340 * 01341 * Related MIB type: \ref MIB_CHANNELS_DATARATE 01342 */ 01343 int8_t ChannelsDatarate ; 01344 /*! 01345 * Channels TX power 01346 * 01347 * Related MIB type: \ref MIB_CHANNELS_TX_POWER 01348 */ 01349 int8_t ChannelsTxPower ; 01350 /*! 01351 * LoRaWAN Up-link counter 01352 * 01353 * Related MIB type: \ref MIB_UPLINK_COUNTER 01354 */ 01355 uint32_t UpLinkCounter ; 01356 /*! 01357 * LoRaWAN Down-link counter 01358 * 01359 * Related MIB type: \ref MIB_DOWNLINK_COUNTER 01360 */ 01361 uint32_t DownLinkCounter ; 01362 /*! 01363 * Multicast channel 01364 * 01365 * Related MIB type: \ref MIB_MULTICAST_CHANNEL 01366 */ 01367 MulticastParams_t * MulticastList ; 01368 }MibParam_t ; 01369 01370 /*! 01371 * LoRaMAC MIB-RequestConfirm structure 01372 */ 01373 typedef struct eMibRequestConfirm 01374 { 01375 /*! 01376 * MIB-Request type 01377 */ 01378 Mib_t Type ; 01379 01380 /*! 01381 * MLME-RequestConfirm parameters 01382 */ 01383 MibParam_t Param ; 01384 }MibRequestConfirm_t ; 01385 01386 /*! 01387 * LoRaMAC tx information 01388 */ 01389 typedef struct sLoRaMacTxInfo 01390 { 01391 /*! 01392 * Defines the size of the applicative payload which can be processed 01393 */ 01394 uint8_t MaxPossiblePayload ; 01395 /*! 01396 * The current payload size, dependent on the current datarate 01397 */ 01398 uint8_t CurrentPayloadSize ; 01399 }LoRaMacTxInfo_t ; 01400 01401 /*! 01402 * LoRaMAC Status 01403 */ 01404 typedef enum eLoRaMacStatus 01405 { 01406 /*! 01407 * Service started successfully 01408 */ 01409 LORAMAC_STATUS_OK , 01410 /*! 01411 * Service not started - LoRaMAC is busy 01412 */ 01413 LORAMAC_STATUS_BUSY , 01414 /*! 01415 * Service unknown 01416 */ 01417 LORAMAC_STATUS_SERVICE_UNKNOWN , 01418 /*! 01419 * Service not started - invalid parameter 01420 */ 01421 LORAMAC_STATUS_PARAMETER_INVALID , 01422 /*! 01423 * Service not started - invalid frequency 01424 */ 01425 LORAMAC_STATUS_FREQUENCY_INVALID , 01426 /*! 01427 * Service not started - invalid datarate 01428 */ 01429 LORAMAC_STATUS_DATARATE_INVALID , 01430 /*! 01431 * Service not started - invalid frequency and datarate 01432 */ 01433 LORAMAC_STATUS_FREQ_AND_DR_INVALID , 01434 /*! 01435 * Service not started - the device is not in a LoRaWAN 01436 */ 01437 LORAMAC_STATUS_NO_NETWORK_JOINED , 01438 /*! 01439 * Service not started - playload lenght error 01440 */ 01441 LORAMAC_STATUS_LENGTH_ERROR , 01442 /*! 01443 * Service not started - playload lenght error 01444 */ 01445 LORAMAC_STATUS_MAC_CMD_LENGTH_ERROR , 01446 /*! 01447 * Service not started - the device is switched off 01448 */ 01449 LORAMAC_STATUS_DEVICE_OFF , 01450 /*! 01451 * Service not started - transmit duty cycle exceeded 01452 */ 01453 LORAMAC_STATUS_TX_DCYCLE_EXCEEDED , 01454 }LoRaMacStatus_t ; 01455 01456 /*! 01457 * LoRaMAC events structure 01458 * Used to notify upper layers of MAC events 01459 */ 01460 typedef struct sLoRaMacPrimitives 01461 { 01462 /*! 01463 * \brief MCPS-Confirm primitive 01464 * 01465 * \param [OUT] MCPS-Confirm parameters 01466 */ 01467 void ( *MacMcpsConfirm )( McpsConfirm_t *McpsConfirm ); 01468 /*! 01469 * \brief MCPS-Indication primitive 01470 * 01471 * \param [OUT] MCPS-Indication parameters 01472 */ 01473 void ( *MacMcpsIndication )( McpsIndication_t *McpsIndication ); 01474 /*! 01475 * \brief MLME-Confirm primitive 01476 * 01477 * \param [OUT] MLME-Confirm parameters 01478 */ 01479 void ( *MacMlmeConfirm )( MlmeConfirm_t *MlmeConfirm ); 01480 }LoRaMacPrimitives_t ; 01481 01482 typedef struct sLoRaMacCallback 01483 { 01484 /*! 01485 * \brief Measures the battery level 01486 * 01487 * \retval Battery level [0: node is connected to an external 01488 * power source, 1..254: battery level, where 1 is the minimum 01489 * and 254 is the maximum value, 255: the node was not able 01490 * to measure the battery level] 01491 */ 01492 uint8_t ( *GetBatteryLevel )( void ); 01493 }LoRaMacCallback_t; 01494 01495 01496 /*! 01497 * LoRaMAC Join Retransmission duty cycle structure 01498 */ 01499 typedef struct sLoRaMacRetransmissionDCycle 01500 { 01501 TimerTime_t period; // Retransmission period in seconds 01502 TimerTime_t onAirTimeMax; // Max on air time in units returned by Radio.TimeOnAir() 01503 } LoRaMacRetransmissionDCycle_t ; 01504 01505 01506 /*! 01507 * \brief LoRaMAC layer initialization 01508 * 01509 * \details In addition to the initialization of the LoRaMAC layer, this 01510 * function initializes the callback primitives of the MCPS and 01511 * MLME services. Every data field of \ref LoRaMacPrimitives_t must be 01512 * set to a valid callback function. 01513 * 01514 * \param [IN] events - Pointer to a structure defining the LoRaMAC 01515 * event functions. Refer to \ref LoRaMacPrimitives_t. 01516 * 01517 * \param [IN] events - Pointer to a structure defining the LoRaMAC 01518 * callback functions. Refer to \ref LoRaMacCallback_t. 01519 * 01520 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 01521 * returns are: 01522 * \ref LORAMAC_STATUS_OK, 01523 * \ref LORAMAC_STATUS_PARAMETER_INVALID. 01524 */ 01525 LoRaMacStatus_t LoRaMacInitialization( LoRaMacPrimitives_t *primitives, LoRaMacCallback_t *callbacks ); 01526 01527 /*! 01528 * \brief Queries the LoRaMAC if it is possible to send the next frame with 01529 * a given payload size. The LoRaMAC takes scheduled MAC commands into 01530 * account and reports, when the frame can be send or not. 01531 * 01532 * \param [IN] size - Size of applicative payload to be send next 01533 * 01534 * \param [OUT] txInfo - The structure \ref LoRaMacTxInfo_t contains 01535 * information about the actual maximum payload possible 01536 * ( according to the configured datarate or the next 01537 * datarate according to ADR ), and the maximum frame 01538 * size, taking the scheduled MAC commands into account. 01539 * 01540 * \retval LoRaMacStatus_t Status of the operation. When the parameters are 01541 * not valid, the function returns \ref LORAMAC_STATUS_PARAMETER_INVALID. 01542 * In case of a length error caused by the applicative payload size, the 01543 * function returns LORAMAC_STATUS_LENGTH_ERROR. In case of a length error 01544 * due to additional MAC commands in the queue, the function returns 01545 * LORAMAC_STATUS_MAC_CMD_LENGTH_ERROR. In case the query is valid, and 01546 * the LoRaMAC is able to send the frame, the function returns LORAMAC_STATUS_OK. * 01547 */ 01548 LoRaMacStatus_t LoRaMacQueryTxPossible( uint8_t size, LoRaMacTxInfo_t * txInfo ); 01549 01550 /*! 01551 * \brief LoRaMAC channel add service 01552 * 01553 * \details Adds a new channel to the channel list and activates the id in 01554 * the channel mask. For the US915 band, all channels are enabled 01555 * by default. It is not possible to activate less than 6 125 kHz 01556 * channels. 01557 * 01558 * \param [IN] id - Id of the channel. Possible values are: 01559 * 01560 * 0-15 for EU868 01561 * 0-72 for US915 01562 * 01563 * \param [IN] params - Channel parameters to set. 01564 * 01565 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 01566 * \ref LORAMAC_STATUS_OK, 01567 * \ref LORAMAC_STATUS_BUSY, 01568 * \ref LORAMAC_STATUS_PARAMETER_INVALID. 01569 */ 01570 LoRaMacStatus_t LoRaMacChannelAdd( uint8_t id, ChannelParams_t params ); 01571 01572 /*! 01573 * \brief LoRaMAC channel remove service 01574 * 01575 * \details Deactivates the id in the channel mask. 01576 * 01577 * \param [IN] id - Id of the channel. 01578 * 01579 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 01580 * \ref LORAMAC_STATUS_OK, 01581 * \ref LORAMAC_STATUS_BUSY, 01582 * \ref LORAMAC_STATUS_PARAMETER_INVALID. 01583 */ 01584 LoRaMacStatus_t LoRaMacChannelRemove( uint8_t id ); 01585 01586 /*! 01587 * \brief LoRaMAC multicast channel link service 01588 * 01589 * \details Links a multicast channel into the linked list. 01590 * 01591 * \param [IN] channelParam - Multicast channel parameters to link. 01592 * 01593 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 01594 * \ref LORAMAC_STATUS_OK, 01595 * \ref LORAMAC_STATUS_BUSY, 01596 * \ref LORAMAC_STATUS_PARAMETER_INVALID. 01597 */ 01598 LoRaMacStatus_t LoRaMacMulticastChannelLink( MulticastParams_t *channelParam ); 01599 01600 /*! 01601 * \brief LoRaMAC multicast channel unlink service 01602 * 01603 * \details Unlinks a multicast channel from the linked list. 01604 * 01605 * \param [IN] channelParam - Multicast channel parameters to unlink. 01606 * 01607 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 01608 * \ref LORAMAC_STATUS_OK, 01609 * \ref LORAMAC_STATUS_BUSY, 01610 * \ref LORAMAC_STATUS_PARAMETER_INVALID. 01611 */ 01612 LoRaMacStatus_t LoRaMacMulticastChannelUnlink( MulticastParams_t *channelParam ); 01613 01614 /*! 01615 * \brief LoRaMAC MIB-Get 01616 * 01617 * \details The mac information base service to get attributes of the LoRaMac 01618 * layer. 01619 * 01620 * The following code-snippet shows how to use the API to get the 01621 * parameter AdrEnable, defined by the enumeration type 01622 * \ref MIB_ADR. 01623 * \code 01624 * MibRequestConfirm_t mibReq; 01625 * mibReq.Type = MIB_ADR; 01626 * 01627 * if( LoRaMacMibGetRequestConfirm( &mibReq ) == LORAMAC_STATUS_OK ) 01628 * { 01629 * // LoRaMAC updated the parameter mibParam.AdrEnable 01630 * } 01631 * \endcode 01632 * 01633 * \param [IN] mibRequest - MIB-GET-Request to perform. Refer to \ref MibRequestConfirm_t. 01634 * 01635 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 01636 * \ref LORAMAC_STATUS_OK, 01637 * \ref LORAMAC_STATUS_SERVICE_UNKNOWN, 01638 * \ref LORAMAC_STATUS_PARAMETER_INVALID. 01639 */ 01640 LoRaMacStatus_t LoRaMacMibGetRequestConfirm( MibRequestConfirm_t *mibGet ); 01641 01642 /*! 01643 * \brief LoRaMAC MIB-Set 01644 * 01645 * \details The mac information base service to set attributes of the LoRaMac 01646 * layer. 01647 * 01648 * The following code-snippet shows how to use the API to set the 01649 * parameter AdrEnable, defined by the enumeration type 01650 * \ref MIB_ADR. 01651 * 01652 * \code 01653 * MibRequestConfirm_t mibReq; 01654 * mibReq.Type = MIB_ADR; 01655 * mibReq.Param.AdrEnable = true; 01656 * 01657 * if( LoRaMacMibGetRequestConfirm( &mibReq ) == LORAMAC_STATUS_OK ) 01658 * { 01659 * // LoRaMAC updated the parameter 01660 * } 01661 * \endcode 01662 * 01663 * \param [IN] mibRequest - MIB-SET-Request to perform. Refer to \ref MibRequestConfirm_t. 01664 * 01665 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 01666 * \ref LORAMAC_STATUS_OK, 01667 * \ref LORAMAC_STATUS_BUSY, 01668 * \ref LORAMAC_STATUS_SERVICE_UNKNOWN, 01669 * \ref LORAMAC_STATUS_PARAMETER_INVALID. 01670 */ 01671 LoRaMacStatus_t LoRaMacMibSetRequestConfirm( MibRequestConfirm_t *mibSet ); 01672 01673 /*! 01674 * \brief LoRaMAC MLME-Request 01675 * 01676 * \details The Mac layer management entity handles management services. The 01677 * following code-snippet shows how to use the API to perform a 01678 * network join request. 01679 * 01680 * \code 01681 * static uint8_t DevEui[] = 01682 * { 01683 * 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 01684 * }; 01685 * static uint8_t AppEui[] = 01686 * { 01687 * 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 01688 * }; 01689 * static uint8_t AppKey[] = 01690 * { 01691 * 0x2B, 0x7E, 0x15, 0x16, 0x28, 0xAE, 0xD2, 0xA6, 01692 * 0xAB, 0xF7, 0x15, 0x88, 0x09, 0xCF, 0x4F, 0x3C 01693 * }; 01694 * 01695 * MlmeReq_t mlmeReq; 01696 * mlmeReq.Type = MLME_JOIN; 01697 * mlmeReq.Req.Join.DevEui = DevEui; 01698 * mlmeReq.Req.Join.AppEui = AppEui; 01699 * mlmeReq.Req.Join.AppKey = AppKey; 01700 * 01701 * if( LoRaMacMlmeRequest( &mlmeReq ) == LORAMAC_STATUS_OK ) 01702 * { 01703 * // Service started successfully. Waiting for the Mlme-Confirm event 01704 * } 01705 * \endcode 01706 * 01707 * \param [IN] mlmeRequest - MLME-Request to perform. Refer to \ref MlmeReq_t. 01708 * 01709 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 01710 * \ref LORAMAC_STATUS_OK, 01711 * \ref LORAMAC_STATUS_BUSY, 01712 * \ref LORAMAC_STATUS_SERVICE_UNKNOWN, 01713 * \ref LORAMAC_STATUS_PARAMETER_INVALID, 01714 * \ref LORAMAC_STATUS_NO_NETWORK_JOINED, 01715 * \ref LORAMAC_STATUS_LENGTH_ERROR, 01716 * \ref LORAMAC_STATUS_DEVICE_OFF. 01717 */ 01718 LoRaMacStatus_t LoRaMacMlmeRequest( MlmeReq_t *mlmeRequest ); 01719 01720 /*! 01721 * \brief LoRaMAC MCPS-Request 01722 * 01723 * \details The Mac Common Part Sublayer handles data services. The following 01724 * code-snippet shows how to use the API to send an unconfirmed 01725 * LoRaMAC frame. 01726 * 01727 * \code 01728 * uint8_t myBuffer[] = { 1, 2, 3 }; 01729 * 01730 * McpsReq_t mcpsReq; 01731 * mcpsReq.Type = MCPS_UNCONFIRMED; 01732 * mcpsReq.Req.Unconfirmed.fPort = 1; 01733 * mcpsReq.Req.Unconfirmed.fBuffer = myBuffer; 01734 * mcpsReq.Req.Unconfirmed.fBufferSize = sizeof( myBuffer ); 01735 * 01736 * if( LoRaMacMcpsRequest( &mcpsReq ) == LORAMAC_STATUS_OK ) 01737 * { 01738 * // Service started successfully. Waiting for the MCPS-Confirm event 01739 * } 01740 * \endcode 01741 * 01742 * \param [IN] mcpsRequest - MCPS-Request to perform. Refer to \ref McpsReq_t. 01743 * 01744 * \retval LoRaMacStatus_t Status of the operation. Possible returns are: 01745 * \ref LORAMAC_STATUS_OK, 01746 * \ref LORAMAC_STATUS_BUSY, 01747 * \ref LORAMAC_STATUS_SERVICE_UNKNOWN, 01748 * \ref LORAMAC_STATUS_PARAMETER_INVALID, 01749 * \ref LORAMAC_STATUS_NO_NETWORK_JOINED, 01750 * \ref LORAMAC_STATUS_LENGTH_ERROR, 01751 * \ref LORAMAC_STATUS_DEVICE_OFF. 01752 */ 01753 LoRaMacStatus_t LoRaMacMcpsRequest( McpsReq_t *mcpsRequest ); 01754 01755 /*! 01756 * \brief Get LoRaMAC Join Request Retransmission Backoff time 01757 * 01758 * \retval Retransmission backoff time remaining until next 01759 * join request can be sent 01760 */ 01761 TimerTime_t LoRaMacCalcJoinBackOff( ); 01762 01763 01764 01765 01766 /*! \} defgroup LORAMAC */ 01767 01768 #endif // __LORAMAC_H__
Generated on Tue Jul 12 2022 16:32:55 by
1.7.2