Akshay Mishra
/
LoRaWAN-lib
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of
LoRaWAN-lib
by 
S P
Embed:
(wiki syntax)
Show/hide line numbers
LoRaMac-api-v3.h
Go to the documentation of this file.
00001 /*! 00002 * \file LoRaMac-api-v3.h 00003 * 00004 * \brief LoRa MAC wrapper 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 #ifndef __LORAMAC_API_V3_H__ 00032 #define __LORAMAC_API_V3_H__ 00033 00034 // Includes board dependent definitions such as channels frequencies 00035 #include "LoRaMac.h" 00036 #include "LoRaMac-board.h" 00037 00038 /*! 00039 * Beacon interval in us 00040 */ 00041 #define BEACON_INTERVAL 128000000 00042 00043 /*! 00044 * Class A&B receive delay in us 00045 */ 00046 #define RECEIVE_DELAY1 1000000 00047 #define RECEIVE_DELAY2 2000000 00048 00049 /*! 00050 * Join accept receive delay in us 00051 */ 00052 #define JOIN_ACCEPT_DELAY1 5000000 00053 #define JOIN_ACCEPT_DELAY2 6000000 00054 00055 /*! 00056 * Class A&B maximum receive window delay in us 00057 */ 00058 #define MAX_RX_WINDOW 3000000 00059 00060 /*! 00061 * Maximum allowed gap for the FCNT field 00062 */ 00063 #define MAX_FCNT_GAP 16384 00064 00065 /*! 00066 * ADR acknowledgement counter limit 00067 */ 00068 #define ADR_ACK_LIMIT 64 00069 00070 /*! 00071 * Number of ADR acknowledgement requests before returning to default datarate 00072 */ 00073 #define ADR_ACK_DELAY 32 00074 00075 /*! 00076 * Number of seconds after the start of the second reception window without 00077 * receiving an acknowledge. 00078 * AckTimeout = ACK_TIMEOUT + Random( -ACK_TIMEOUT_RND, ACK_TIMEOUT_RND ) 00079 */ 00080 #define ACK_TIMEOUT 2000000 00081 00082 /*! 00083 * Random number of seconds after the start of the second reception window without 00084 * receiving an acknowledge 00085 * AckTimeout = ACK_TIMEOUT + Random( -ACK_TIMEOUT_RND, ACK_TIMEOUT_RND ) 00086 */ 00087 #define ACK_TIMEOUT_RND 1000000 00088 00089 /*! 00090 * Check the Mac layer state every MAC_STATE_CHECK_TIMEOUT 00091 */ 00092 #define MAC_STATE_CHECK_TIMEOUT 1000000 00093 00094 /*! 00095 * Maximum number of times the MAC layer tries to get an acknowledge. 00096 */ 00097 #define MAX_ACK_RETRIES 8 00098 00099 /*! 00100 * RSSI free threshold 00101 */ 00102 #define RSSI_FREE_TH ( int8_t )( -90 ) // [dBm] 00103 00104 /*! 00105 * Frame direction definition 00106 */ 00107 #define UP_LINK 0 00108 #define DOWN_LINK 1 00109 00110 /*! 00111 * Sets the length of the LoRaMAC footer field. 00112 * Mainly indicates the MIC field length 00113 */ 00114 #define LORAMAC_MFR_LEN 4 00115 00116 /*! 00117 * Syncword for Private LoRa networks 00118 */ 00119 #define LORA_MAC_PRIVATE_SYNCWORD 0x12 00120 00121 /*! 00122 * Syncword for Public LoRa networks 00123 */ 00124 #define LORA_MAC_PUBLIC_SYNCWORD 0x34 00125 00126 /*! 00127 * LoRaMAC event flags 00128 */ 00129 typedef union 00130 { 00131 uint8_t Value; 00132 struct 00133 { 00134 uint8_t Tx : 1; 00135 uint8_t Rx : 1; 00136 uint8_t RxData : 1; 00137 uint8_t Multicast : 1; 00138 uint8_t RxSlot : 2; 00139 uint8_t LinkCheck : 1; 00140 uint8_t JoinAccept : 1; 00141 }Bits; 00142 }LoRaMacEventFlags_t ; 00143 00144 /*! 00145 * LoRaMAC event information 00146 */ 00147 typedef struct 00148 { 00149 LoRaMacEventInfoStatus_t Status; 00150 bool TxAckReceived; 00151 uint8_t TxNbRetries; 00152 uint8_t TxDatarate; 00153 uint8_t RxPort; 00154 uint8_t *RxBuffer; 00155 uint8_t RxBufferSize; 00156 int16_t RxRssi; 00157 uint8_t RxSnr; 00158 uint16_t Energy; 00159 uint8_t DemodMargin; 00160 uint8_t NbGateways; 00161 }LoRaMacEventInfo_t ; 00162 00163 /*! 00164 * LoRaMAC events structure 00165 * Used to notify upper layers of MAC events 00166 */ 00167 typedef struct sLoRaMacCallbacks 00168 { 00169 /*! 00170 * MAC layer event callback prototype. 00171 * 00172 * \param [IN] flags Bit field indicating the MAC events occurred 00173 * \param [IN] info Details about MAC events occurred 00174 */ 00175 void ( *MacEvent )( LoRaMacEventFlags_t *flags, LoRaMacEventInfo_t *info ); 00176 /*! 00177 * Function callback to get the current battery level 00178 * 00179 * \retval batteryLevel Current battery level 00180 */ 00181 uint8_t ( *GetBatteryLevel )( void ); 00182 }LoRaMacCallbacks_t ; 00183 00184 /*! 00185 * LoRaMAC layer initialization 00186 * 00187 * \param [IN] callbacks Pointer to a structure defining the LoRaMAC 00188 * callback functions. 00189 */ 00190 void LoRaMacInit( LoRaMacCallbacks_t *callbacks ); 00191 00192 /*! 00193 * Enables/Disables the ADR (Adaptive Data Rate) 00194 * 00195 * \param [IN] enable [true: ADR ON, false: ADR OFF] 00196 */ 00197 void LoRaMacSetAdrOn( bool enable ); 00198 00199 /*! 00200 * Initializes the network IDs. Device address, 00201 * network session AES128 key and application session AES128 key. 00202 * 00203 * \remark To be only used when Over-the-Air activation isn't used. 00204 * 00205 * \param [IN] netID 24 bits network identifier 00206 * ( provided by network operator ) 00207 * \param [IN] devAddr 32 bits device address on the network 00208 * (must be unique to the network) 00209 * \param [IN] nwkSKey Pointer to the network session AES128 key array 00210 * ( 16 bytes ) 00211 * \param [IN] appSKey Pointer to the application session AES128 key array 00212 * ( 16 bytes ) 00213 */ 00214 void LoRaMacInitNwkIds( uint32_t netID, uint32_t devAddr, uint8_t *nwkSKey, uint8_t *appSKey ); 00215 00216 /* 00217 * Wrapper function which calls \ref LoRaMacMulticastChannelLink. 00218 */ 00219 void LoRaMacMulticastChannelAdd( MulticastParams_t *channelParam ); 00220 00221 /* 00222 * Wrapper function which calls \ref LoRaMacMulticastChannelUnlink. 00223 */ 00224 void LoRaMacMulticastChannelRemove( MulticastParams_t *channelParam ); 00225 00226 /*! 00227 * Initiates the Over-the-Air activation 00228 * 00229 * \param [IN] devEui Pointer to the device EUI array ( 8 bytes ) 00230 * \param [IN] appEui Pointer to the application EUI array ( 8 bytes ) 00231 * \param [IN] appKey Pointer to the application AES128 key array ( 16 bytes ) 00232 * 00233 * \retval status [0: OK, 1: Tx error, 2: Already joined a network] 00234 */ 00235 uint8_t LoRaMacJoinReq( uint8_t *devEui, uint8_t *appEui, uint8_t *appKey ); 00236 00237 /*! 00238 * Sends a LinkCheckReq MAC command on the next uplink frame 00239 * 00240 * \retval status Function status [0: OK, 1: Busy] 00241 */ 00242 uint8_t LoRaMacLinkCheckReq( void ); 00243 00244 /*! 00245 * LoRaMAC layer send frame 00246 * 00247 * \param [IN] fPort MAC payload port (must be > 0) 00248 * \param [IN] fBuffer MAC data buffer to be sent 00249 * \param [IN] fBufferSize MAC data buffer size 00250 * 00251 * \retval status [0: OK, 1: Busy, 2: No network joined, 00252 * 3: Length or port error, 4: Unknown MAC command 00253 * 5: Unable to find a free channel 00254 * 6: Device switched off] 00255 */ 00256 uint8_t LoRaMacSendFrame( uint8_t fPort, void *fBuffer, uint16_t fBufferSize ); 00257 00258 /*! 00259 * LoRaMAC layer send frame 00260 * 00261 * \param [IN] fPort MAC payload port (must be > 0) 00262 * \param [IN] fBuffer MAC data buffer to be sent 00263 * \param [IN] fBufferSize MAC data buffer size 00264 * \param [IN] fBufferSize MAC data buffer size 00265 * \param [IN] nbRetries Number of retries to receive the acknowledgement 00266 * 00267 * \retval status [0: OK, 1: Busy, 2: No network joined, 00268 * 3: Length or port error, 4: Unknown MAC command 00269 * 5: Unable to find a free channel 00270 * 6: Device switched off] 00271 */ 00272 uint8_t LoRaMacSendConfirmedFrame( uint8_t fPort, void *fBuffer, uint16_t fBufferSize, uint8_t nbRetries ); 00273 00274 /*! 00275 * ============================================================================ 00276 * = LoRaMac test functions = 00277 * ============================================================================ 00278 */ 00279 00280 /*! 00281 * LoRaMAC layer generic send frame 00282 * 00283 * \param [IN] macHdr MAC header field 00284 * \param [IN] fOpts MAC commands buffer 00285 * \param [IN] fPort MAC payload port 00286 * \param [IN] fBuffer MAC data buffer to be sent 00287 * \param [IN] fBufferSize MAC data buffer size 00288 * \retval status [0: OK, 1: Busy, 2: No network joined, 00289 * 3: Length or port error, 4: Unknown MAC command 00290 * 5: Unable to find a free channel 00291 * 6: Device switched off] 00292 */ 00293 uint8_t LoRaMacSend( LoRaMacHeader_t *macHdr, uint8_t *fOpts, uint8_t fPort, void *fBuffer, uint16_t fBufferSize ); 00294 00295 /*! 00296 * LoRaMAC layer frame buffer initialization. 00297 * 00298 * \param [IN] channel Channel parameters 00299 * \param [IN] macHdr MAC header field 00300 * \param [IN] fCtrl MAC frame control field 00301 * \param [IN] fOpts MAC commands buffer 00302 * \param [IN] fPort MAC payload port 00303 * \param [IN] fBuffer MAC data buffer to be sent 00304 * \param [IN] fBufferSize MAC data buffer size 00305 * \retval status [0: OK, 1: N/A, 2: No network joined, 00306 * 3: Length or port error, 4: Unknown MAC command] 00307 */ 00308 uint8_t LoRaMacPrepareFrame( ChannelParams_t channel,LoRaMacHeader_t *macHdr, LoRaMacFrameCtrl_t *fCtrl, uint8_t *fOpts, uint8_t fPort, void *fBuffer, uint16_t fBufferSize ); 00309 00310 /*! 00311 * LoRaMAC layer prepared frame buffer transmission with channel specification 00312 * 00313 * \remark LoRaMacPrepareFrame must be called at least once before calling this 00314 * function. 00315 * 00316 * \param [IN] channel Channel parameters 00317 * \retval status [0: OK, 1: Busy] 00318 */ 00319 uint8_t LoRaMacSendFrameOnChannel( ChannelParams_t channel ); 00320 00321 /*! 00322 * LoRaMAC layer generic send frame with channel specification 00323 * 00324 * \param [IN] channel Channel parameters 00325 * \param [IN] macHdr MAC header field 00326 * \param [IN] fCtrl MAC frame control field 00327 * \param [IN] fOpts MAC commands buffer 00328 * \param [IN] fPort MAC payload port 00329 * \param [IN] fBuffer MAC data buffer to be sent 00330 * \param [IN] fBufferSize MAC data buffer size 00331 * \retval status [0: OK, 1: Busy, 2: No network joined, 00332 * 3: Length or port error, 4: Unknown MAC command] 00333 */ 00334 uint8_t LoRaMacSendOnChannel( ChannelParams_t channel, LoRaMacHeader_t *macHdr, LoRaMacFrameCtrl_t *fCtrl, uint8_t *fOpts, uint8_t fPort, void *fBuffer, uint16_t fBufferSize ); 00335 00336 /*! 00337 * ============================================================================ 00338 * = LoRaMac setup functions = 00339 * ============================================================================ 00340 */ 00341 00342 /* 00343 * Wrapper function which calls \ref LoRaMacMibSetRequestConfirm to 00344 * set the LoRaWan device class. 00345 */ 00346 void LoRaMacSetDeviceClass( DeviceClass_t deviceClass ); 00347 00348 /* 00349 * Wrapper function which calls \ref LoRaMacMibSetRequestConfirm to 00350 * set the network type to public or private. 00351 */ 00352 void LoRaMacSetPublicNetwork( bool enable ); 00353 00354 /* 00355 * Wrapper function which calls \ref LoRaMacChannelAdd. 00356 */ 00357 void LoRaMacSetChannel( uint8_t id, ChannelParams_t params ); 00358 00359 /* 00360 * Wrapper function which calls \ref LoRaMacMibSetRequestConfirm to 00361 * set the receive window 2 channel. 00362 */ 00363 void LoRaMacSetRx2Channel( Rx2ChannelParams_t param ); 00364 00365 /*! 00366 * Sets channels tx output power 00367 * 00368 * \param [IN] txPower [TX_POWER_20_DBM, TX_POWER_14_DBM, 00369 TX_POWER_11_DBM, TX_POWER_08_DBM, 00370 TX_POWER_05_DBM, TX_POWER_02_DBM] 00371 */ 00372 void LoRaMacSetChannelsTxPower( int8_t txPower ); 00373 00374 /*! 00375 * Sets channels datarate 00376 * 00377 * \param [IN] datarate eu868 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_5, DR_6, DR_7] 00378 * us915 - [DR_0, DR_1, DR_2, DR_3, DR_4] 00379 */ 00380 void LoRaMacSetChannelsDatarate( int8_t datarate ); 00381 00382 /* 00383 * Wrapper function which calls \ref LoRaMacMibSetRequestConfirm to 00384 * set the channels mask. 00385 */ 00386 void LoRaMacSetChannelsMask( uint16_t *mask ); 00387 00388 /* 00389 * Wrapper function which calls \ref LoRaMacMibSetRequestConfirm to 00390 * set the number of repetitions on a channel. 00391 */ 00392 void LoRaMacSetChannelsNbRep( uint8_t nbRep ); 00393 00394 /* 00395 * Wrapper function which calls \ref LoRaMacMibSetRequestConfirm to 00396 * set the maximum receive window duration in [us]. 00397 */ 00398 void LoRaMacSetMaxRxWindow( uint32_t delay ); 00399 00400 /* 00401 * Wrapper function which calls \ref LoRaMacMibSetRequestConfirm to 00402 * set the receive delay 1 in [us]. 00403 */ 00404 void LoRaMacSetReceiveDelay1( uint32_t delay ); 00405 00406 /* 00407 * Wrapper function which calls \ref LoRaMacMibSetRequestConfirm to 00408 * set the receive delay 2 in [us]. 00409 */ 00410 void LoRaMacSetReceiveDelay2( uint32_t delay ); 00411 00412 /* 00413 * Wrapper function which calls \ref LoRaMacMibSetRequestConfirm to 00414 * set the join accept delay 1 in [us]. 00415 */ 00416 void LoRaMacSetJoinAcceptDelay1( uint32_t delay ); 00417 00418 /* 00419 * Wrapper function which calls \ref LoRaMacMibSetRequestConfirm to 00420 * set the join accept delay 2 in [us]. 00421 */ 00422 void LoRaMacSetJoinAcceptDelay2( uint32_t delay ); 00423 00424 /* 00425 * Wrapper function which calls \ref LoRaMacMibGetRequestConfirm to 00426 * get the up-link counter. 00427 */ 00428 uint32_t LoRaMacGetUpLinkCounter( void ); 00429 00430 /* 00431 * Wrapper function which calls \ref LoRaMacMibGetRequestConfirm to 00432 * get the down-link counter. 00433 */ 00434 uint32_t LoRaMacGetDownLinkCounter( void ); 00435 00436 /* 00437 * ============================================================================ 00438 * = LoRaMac test functions = 00439 * ============================================================================ 00440 */ 00441 00442 /*! 00443 * Disables/Enables the duty cycle enforcement (EU868) 00444 * 00445 * \param [IN] enable - Enabled or disables the duty cycle 00446 */ 00447 void LoRaMacTestSetDutyCycleOn ( bool enable ); 00448 00449 /*! 00450 * Disables/Enables the reception windows opening 00451 * 00452 * \param [IN] enable [true: enable, false: disable] 00453 */ 00454 void LoRaMacTestRxWindowsOn ( bool enable ); 00455 00456 /*! 00457 * Enables the MIC field test 00458 * 00459 * \param [IN] upLinkCounter Fixed Tx packet counter value 00460 */ 00461 void LoRaMacTestSetMic ( uint16_t upLinkCounter ); 00462 00463 #endif /* __LORAMAC_API_V3_H__ */
Generated on Tue Jul 12 2022 21:21:12 by
1.7.2