LoRaMac.h

00001 /*
00002  / _____)             _              | |
00003 ( (____  _____ ____ _| |_ _____  ____| |__
00004  \____ \| ___ |    (_   _) ___ |/ ___)  _ \
00005  _____) ) ____| | | || |_| ____( (___| | | |
00006 (______/|_____)_|_|_| \__)_____)\____)_| |_|
00007     (C)2013 Semtech
00008 Description: LoRa MAC layer implementation
00009 License: Revised BSD License, see LICENSE.TXT file include in the project
00010 Maintainer: Miguel Luis and Gregory Cristian
00011 */
00012 #ifndef __LORAMAC_H__
00013 #define __LORAMAC_H__
00014 
00015 // Includes board dependent definitions such as channels frequencies
00016 #include "LoRaMac-board.h"
00017 #include "enums.h"
00018 #define USE_BAND_868
00019 /*!
00020  * Beacon interval in us
00021  */
00022 #define BEACON_INTERVAL                             128000000
00023 
00024 /*!
00025  * Class A&B receive delay in us
00026  */
00027 #define RECEIVE_DELAY1                              1000000
00028 #define RECEIVE_DELAY2                              2000000
00029 
00030 /*!
00031  * Join accept receive delay in us
00032  */
00033 #define JOIN_ACCEPT_DELAY1                          5000000
00034 #define JOIN_ACCEPT_DELAY2                          6000000
00035 
00036 /*!
00037  * Class A&B maximum receive window delay in us
00038  */
00039 #define MAX_RX_WINDOW                               3000000
00040 
00041 /*!
00042  * Maximum allowed gap for the FCNT field
00043  */
00044 #define MAX_FCNT_GAP                                16384
00045 
00046 /*!
00047  * ADR acknowledgement counter limit
00048  */
00049 #define ADR_ACK_LIMIT                               64
00050 
00051 /*!
00052  * Number of ADR acknowledgement requests before returning to default datarate
00053  */
00054 #define ADR_ACK_DELAY                               32
00055 
00056 /*!
00057  * Number of seconds after the start of the second reception window without
00058  * receiving an acknowledge.
00059  * AckTimeout = ACK_TIMEOUT + Random( -ACK_TIMEOUT_RND, ACK_TIMEOUT_RND )
00060  */
00061 #define ACK_TIMEOUT                                 2000000
00062 
00063 /*!
00064  * Random number of seconds after the start of the second reception window without
00065  * receiving an acknowledge
00066  * AckTimeout = ACK_TIMEOUT + Random( -ACK_TIMEOUT_RND, ACK_TIMEOUT_RND )
00067  */
00068 #define ACK_TIMEOUT_RND                             1000000
00069 
00070 /*!
00071  * Check the Mac layer state every MAC_STATE_CHECK_TIMEOUT
00072  */
00073 #define MAC_STATE_CHECK_TIMEOUT                     1000000
00074 
00075 /*!
00076  * Maximum number of times the MAC layer tries to get an acknowledge.
00077  */
00078 #define MAX_ACK_RETRIES                             8
00079 
00080 /*!
00081  * RSSI free threshold
00082  */
00083 #define RSSI_FREE_TH                                ( int8_t )( -90 ) // [dBm]
00084 
00085 /*! 
00086  * Frame direction definition
00087  */
00088 #define UP_LINK                                     0
00089 #define DOWN_LINK                                   1
00090 
00091 /*!
00092  * Sets the length of the LoRaMAC footer field.
00093  * Mainly indicates the MIC field length
00094  */
00095 #define LORAMAC_MFR_LEN                             4
00096 
00097 /*!
00098  * Syncword for Private LoRa networks
00099  */
00100 #define LORA_MAC_PRIVATE_SYNCWORD                   0x12
00101 
00102 /*!
00103  * Syncword for Public LoRa networks
00104  */
00105 #define LORA_MAC_PUBLIC_SYNCWORD                    0x34
00106 
00107 /*!
00108  * LoRaWAN devices classes definition
00109  */
00110 typedef enum
00111 {
00112     CLASS_A,
00113     CLASS_B,
00114     CLASS_C,
00115 }DeviceClass_t;
00116 
00117 /*!
00118  * LoRaMAC channels parameters definition
00119  */
00120 typedef union
00121 {
00122     int8_t Value;
00123     struct
00124     {
00125         int8_t Min : 4;
00126         int8_t Max : 4;
00127     }Fields;
00128 }DrRange_t ;
00129 
00130 typedef struct
00131 {
00132     uint16_t DCycle;
00133     int8_t TxMaxPower;
00134     uint64_t LastTxDoneTime;
00135     uint64_t TimeOff;
00136 }Band_t;
00137 
00138 typedef struct
00139 {
00140     uint32_t Frequency; // Hz
00141     DrRange_t  DrRange;  // Max datarate [0: SF12, 1: SF11, 2: SF10, 3: SF9, 4: SF8, 5: SF7, 6: SF7, 7: FSK]
00142                         // Min datarate [0: SF12, 1: SF11, 2: SF10, 3: SF9, 4: SF8, 5: SF7, 6: SF7, 7: FSK]
00143     uint8_t Band;       // Band index
00144 }ChannelParams_t;
00145 
00146 typedef struct
00147 {
00148     uint32_t Frequency; // Hz
00149     uint8_t  Datarate;  // [0: SF12, 1: SF11, 2: SF10, 3: SF9, 4: SF8, 5: SF7, 6: SF7, 7: FSK]
00150 }Rx2ChannelParams_t;
00151 
00152 typedef struct MulticastParams_s
00153 {
00154     uint32_t Address;
00155     uint8_t NwkSKey[16];
00156     uint8_t AppSKey[16];
00157     uint32_t DownLinkCounter;
00158     struct MulticastParams_s *Next;
00159 }MulticastParams_t;
00160 
00161 /*!
00162  * LoRaMAC frame types
00163  */
00164 typedef enum
00165 {
00166     FRAME_TYPE_JOIN_REQ              = 0x00,
00167     FRAME_TYPE_JOIN_ACCEPT           = 0x01,
00168     FRAME_TYPE_DATA_UNCONFIRMED_UP   = 0x02,
00169     FRAME_TYPE_DATA_UNCONFIRMED_DOWN = 0x03,
00170     FRAME_TYPE_DATA_CONFIRMED_UP     = 0x04,
00171     FRAME_TYPE_DATA_CONFIRMED_DOWN   = 0x05,
00172     FRAME_TYPE_RFU                   = 0x06,
00173     FRAME_TYPE_PROPRIETARY           = 0x07,
00174 }LoRaMacFrameType_t;
00175 
00176 /*!
00177  * LoRaMAC mote MAC commands
00178  */
00179 typedef enum
00180 {
00181     MOTE_MAC_LINK_CHECK_REQ          = 0x02,
00182     MOTE_MAC_LINK_ADR_ANS            = 0x03,
00183     MOTE_MAC_DUTY_CYCLE_ANS          = 0x04,
00184     MOTE_MAC_RX_PARAM_SETUP_ANS      = 0x05,
00185     MOTE_MAC_DEV_STATUS_ANS          = 0x06,
00186     MOTE_MAC_NEW_CHANNEL_ANS         = 0x07,
00187     MOTE_MAC_RX_TIMING_SETUP_ANS     = 0x08,
00188 }LoRaMacMoteCmd_t;
00189 
00190 /*!
00191  * LoRaMAC server MAC commands
00192  */
00193 typedef enum
00194 {
00195     SRV_MAC_LINK_CHECK_ANS           = 0x02,
00196     SRV_MAC_LINK_ADR_REQ             = 0x03,
00197     SRV_MAC_DUTY_CYCLE_REQ           = 0x04,
00198     SRV_MAC_RX_PARAM_SETUP_REQ       = 0x05,
00199     SRV_MAC_DEV_STATUS_REQ           = 0x06,
00200     SRV_MAC_NEW_CHANNEL_REQ          = 0x07,
00201     SRV_MAC_RX_TIMING_SETUP_REQ      = 0x08,
00202 }LoRaMacSrvCmd_t;
00203 
00204 /*!
00205  * LoRaMAC Battery level indicator
00206  */
00207 typedef enum
00208 {
00209     BAT_LEVEL_EXT_SRC                = 0x00,
00210     BAT_LEVEL_EMPTY                  = 0x01,
00211     BAT_LEVEL_FULL                   = 0xFE,
00212     BAT_LEVEL_NO_MEASURE             = 0xFF,
00213 }LoRaMacBatteryLevel_t;
00214 
00215 /*!
00216  * LoRaMAC header field definition
00217  */
00218 typedef union
00219 {
00220     uint8_t Value;
00221     struct
00222     {
00223         uint8_t Major           : 2;
00224         uint8_t RFU             : 3;
00225         uint8_t MType           : 3;
00226     }Bits;
00227 }LoRaMacHeader_t ;
00228 
00229 /*!
00230  * LoRaMAC frame header field definition
00231  */
00232 typedef union
00233 {
00234     uint8_t Value;
00235     struct
00236     {
00237         uint8_t FOptsLen        : 4;
00238         uint8_t FPending        : 1;
00239         uint8_t Ack             : 1;
00240         uint8_t AdrAckReq       : 1;
00241         uint8_t Adr             : 1;
00242     }Bits;
00243 }LoRaMacFrameCtrl_t ;
00244 
00245 /*!
00246  * LoRaMAC event flags
00247  */
00248 typedef union
00249 {
00250     uint8_t Value;
00251     struct
00252     {
00253         uint8_t Tx              : 1;
00254         uint8_t Rx              : 1;
00255         uint8_t RxData          : 1;
00256         uint8_t Multicast       : 1;
00257         uint8_t RxSlot          : 2;
00258         uint8_t LinkCheck       : 1;
00259         uint8_t JoinAccept      : 1;
00260     }Bits;
00261 }LoRaMacEventFlags_t ;
00262 
00263 typedef enum
00264 {
00265     LORAMAC_EVENT_INFO_STATUS_OK = 0,
00266     LORAMAC_EVENT_INFO_STATUS_ERROR,
00267     LORAMAC_EVENT_INFO_STATUS_TX_TIMEOUT,
00268     LORAMAC_EVENT_INFO_STATUS_RX2_TIMEOUT,
00269     LORAMAC_EVENT_INFO_STATUS_RX2_ERROR,
00270     LORAMAC_EVENT_INFO_STATUS_JOIN_FAIL,
00271     LORAMAC_EVENT_INFO_STATUS_DOWNLINK_FAIL,
00272     LORAMAC_EVENT_INFO_STATUS_ADDRESS_FAIL,
00273     LORAMAC_EVENT_INFO_STATUS_MIC_FAIL,
00274 }LoRaMacEventInfoStatus_t;
00275 
00276 /*!
00277  * LoRaMAC event information
00278  */
00279 typedef struct
00280 {
00281     LoRaMacEventInfoStatus_t Status;
00282     bool TxAckReceived;
00283     uint8_t TxNbRetries;
00284     uint8_t TxDatarate;
00285     uint8_t RxPort;
00286     uint8_t *RxBuffer;
00287     uint8_t RxBufferSize;
00288     int16_t RxRssi;
00289     uint8_t RxSnr;
00290     uint16_t Energy;
00291     uint8_t DemodMargin;
00292     uint8_t NbGateways;
00293 }LoRaMacEventInfo_t ;
00294 
00295 /*!
00296  * LoRaMAC events structure
00297  * Used to notify upper layers of MAC events
00298  */
00299 typedef struct sLoRaMacCallbacks 
00300 {
00301     /*!
00302      * MAC layer event callback prototype.
00303      *
00304      * \param [IN] flags Bit field indicating the MAC events occurred
00305      * \param [IN] info  Details about MAC events occurred
00306      */
00307     void ( *MacEvent  )( LoRaMacEventFlags_t  *flags, LoRaMacEventInfo_t  *info );
00308     /*!
00309      * Function callback to get the current battery level
00310      *
00311      * \retval batteryLevel Current battery level
00312      */
00313     uint8_t ( *GetBatteryLevel  )( void );
00314 }LoRaMacCallbacks_t ;
00315 
00316 /*!
00317  * LoRaMAC layer initialization
00318  *
00319  * \param [IN] callabcks       Pointer to a structure defining the LoRaMAC
00320  *                             callback functions.
00321  */
00322 void LoRaMacInit( LoRaMacCallbacks_t  *callabcks );
00323 
00324 /*!
00325  * Enables/Disables the ADR (Adaptive Data Rate)
00326  * 
00327  * \param [IN] enable [true: ADR ON, false: ADR OFF]
00328  */
00329 void LoRaMacSetAdrOn( bool enable );
00330 
00331 /*!
00332  * Initializes the network IDs. Device address, 
00333  * network session AES128 key and application session AES128 key.
00334  *
00335  * \remark To be only used when Over-the-Air activation isn't used.
00336  *
00337  * \param [IN] netID   24 bits network identifier 
00338  *                     ( provided by network operator )
00339  * \param [IN] devAddr 32 bits device address on the network 
00340  *                     (must be unique to the network)
00341  * \param [IN] nwkSKey Pointer to the network session AES128 key array
00342  *                     ( 16 bytes )
00343  * \param [IN] appSKey Pointer to the application session AES128 key array
00344  *                     ( 16 bytes )
00345  */
00346 void LoRaMacInitNwkIds( uint32_t netID, uint32_t devAddr, uint8_t *nwkSKey, uint8_t *appSKey );
00347 
00348 /*
00349  * TODO: Add documentation
00350  */
00351 void LoRaMacMulticastChannelAdd( MulticastParams_t *channelParam );
00352 
00353 /*
00354  * TODO: Add documentation
00355  */
00356 void LoRaMacMulticastChannelRemove( MulticastParams_t *channelParam );
00357 
00358 /*!
00359  * Initiates the Over-the-Air activation 
00360  * 
00361  * \param [IN] devEui Pointer to the device EUI array ( 8 bytes )
00362  * \param [IN] appEui Pointer to the application EUI array ( 8 bytes )
00363  * \param [IN] appKey Pointer to the application AES128 key array ( 16 bytes )
00364  *
00365  * \retval status [0: OK, 1: Tx error, 2: Already joined a network]
00366  */
00367 uint8_t LoRaMacJoinReq( uint8_t *devEui, uint8_t *appEui, uint8_t *appKey );
00368 
00369 /*!
00370  * Sends a LinkCheckReq MAC command on the next uplink frame
00371  *
00372  * \retval status Function status [0: OK, 1: Busy]
00373  */
00374 uint8_t LoRaMacLinkCheckReq( void );
00375 
00376 /*!
00377  * LoRaMAC layer send frame
00378  *
00379  * \param [IN] fPort       MAC payload port (must be > 0)
00380  * \param [IN] fBuffer     MAC data buffer to be sent
00381  * \param [IN] fBufferSize MAC data buffer size
00382  *
00383  * \retval status          [0: OK, 1: Busy, 2: No network joined,
00384  *                          3: Length or port error, 4: Unknown MAC command
00385  *                          5: Unable to find a free channel
00386  *                          6: Device switched off]
00387  */
00388 uint8_t LoRaMacSendFrame( uint8_t fPort, void *fBuffer, uint16_t fBufferSize );
00389 
00390 /*!
00391  * LoRaMAC layer send frame
00392  *
00393  * \param [IN] fPort       MAC payload port (must be > 0)
00394  * \param [IN] fBuffer     MAC data buffer to be sent
00395  * \param [IN] fBufferSize MAC data buffer size
00396  * \param [IN] fBufferSize MAC data buffer size
00397  * \param [IN] nbRetries   Number of retries to receive the acknowledgement
00398  *
00399  * \retval status          [0: OK, 1: Busy, 2: No network joined,
00400  *                          3: Length or port error, 4: Unknown MAC command
00401  *                          5: Unable to find a free channel
00402  *                          6: Device switched off]
00403  */
00404 uint8_t LoRaMacSendConfirmedFrame( uint8_t fPort, void *fBuffer, uint16_t fBufferSize, uint8_t nbRetries );
00405 
00406 /*!
00407  * ============================================================================
00408  * = LoRaMac test functions                                                   =
00409  * ============================================================================
00410  */
00411 
00412 /*!
00413  * LoRaMAC layer generic send frame
00414  *
00415  * \param [IN] macHdr      MAC header field
00416  * \param [IN] fOpts       MAC commands buffer
00417  * \param [IN] fPort       MAC payload port
00418  * \param [IN] fBuffer     MAC data buffer to be sent
00419  * \param [IN] fBufferSize MAC data buffer size
00420  * \retval status          [0: OK, 1: Busy, 2: No network joined,
00421  *                          3: Length or port error, 4: Unknown MAC command
00422  *                          5: Unable to find a free channel
00423  *                          6: Device switched off]
00424  */
00425 uint8_t LoRaMacSend( LoRaMacHeader_t  *macHdr, uint8_t *fOpts, uint8_t fPort, void *fBuffer, uint16_t fBufferSize );
00426 
00427 /*!
00428  * LoRaMAC layer frame buffer initialization.
00429  *
00430  * \param [IN] channel     Channel parameters
00431  * \param [IN] macHdr      MAC header field
00432  * \param [IN] fCtrl       MAC frame control field
00433  * \param [IN] fOpts       MAC commands buffer
00434  * \param [IN] fPort       MAC payload port
00435  * \param [IN] fBuffer     MAC data buffer to be sent
00436  * \param [IN] fBufferSize MAC data buffer size
00437  * \retval status          [0: OK, 1: N/A, 2: No network joined,
00438  *                          3: Length or port error, 4: Unknown MAC command]
00439  */
00440 uint8_t LoRaMacPrepareFrame( ChannelParams_t channel,LoRaMacHeader_t  *macHdr, LoRaMacFrameCtrl_t  *fCtrl, uint8_t *fOpts, uint8_t fPort, void *fBuffer, uint16_t fBufferSize );
00441 
00442 /*!
00443  * LoRaMAC layer prepared frame buffer transmission with channel specification
00444  *
00445  * \remark LoRaMacPrepareFrame must be called at least once before calling this
00446  *         function.
00447  *
00448  * \param [IN] channel     Channel parameters
00449  * \retval status          [0: OK, 1: Busy]
00450  */
00451 uint8_t LoRaMacSendFrameOnChannel( ChannelParams_t channel );
00452 
00453 /*!
00454  * LoRaMAC layer generic send frame with channel specification
00455  *
00456  * \param [IN] channel     Channel parameters
00457  * \param [IN] macHdr      MAC header field
00458  * \param [IN] fCtrl       MAC frame control field
00459  * \param [IN] fOpts       MAC commands buffer
00460  * \param [IN] fPort       MAC payload port
00461  * \param [IN] fBuffer     MAC data buffer to be sent
00462  * \param [IN] fBufferSize MAC data buffer size
00463  * \retval status          [0: OK, 1: Busy, 2: No network joined,
00464  *                          3: Length or port error, 4: Unknown MAC command]
00465  */
00466 uint8_t LoRaMacSendOnChannel( ChannelParams_t channel, LoRaMacHeader_t  *macHdr, LoRaMacFrameCtrl_t  *fCtrl, uint8_t *fOpts, uint8_t fPort, void *fBuffer, uint16_t fBufferSize );
00467 
00468 /*!
00469  * ============================================================================
00470  * = LoRaMac setup functions                                                  =
00471  * ============================================================================
00472  */
00473 
00474 /*
00475  * TODO: Add documentation
00476  */
00477 void LoRaMacSetDeviceClass( DeviceClass_t deviceClass );
00478 
00479 /*
00480  * TODO: Add documentation
00481  */
00482 void LoRaMacSetPublicNetwork( bool enable );
00483 
00484 /*
00485  * TODO: Add documentation
00486  */
00487 void LoRaMacSetChannel( uint8_t id, ChannelParams_t params );
00488 
00489 /*
00490  * TODO: Add documentation
00491  */
00492 void LoRaMacSetRx2Channel( Rx2ChannelParams_t param );
00493 
00494 /*!
00495  * Sets channels tx output power
00496  *
00497  * \param [IN] txPower [TX_POWER_20_DBM, TX_POWER_14_DBM,
00498                         TX_POWER_11_DBM, TX_POWER_08_DBM,
00499                         TX_POWER_05_DBM, TX_POWER_02_DBM]
00500  */
00501 void LoRaMacSetChannelsTxPower( int8_t txPower );
00502 
00503 /*!
00504  * Sets channels datarate
00505  *
00506  * \param [IN] datarate eu868 - [DR_0, DR_1, DR_2, DR_3, DR_4, DR_5, DR_6, DR_7]
00507  *                      us915 - [DR_0, DR_1, DR_2, DR_3, DR_4]
00508  */
00509 void LoRaMacSetChannelsDatarate( int8_t datarate );
00510 
00511 /*
00512  * TODO: Add documentation
00513  */
00514 void LoRaMacSetChannelsMask( uint16_t *mask );
00515 
00516 /*
00517  * TODO: Add documentation
00518  */
00519 void LoRaMacSetChannelsNbRep( uint8_t nbRep );
00520 
00521 /*
00522  * TODO: Add documentation
00523  */
00524 void LoRaMacSetMaxRxWindow( uint32_t delay );
00525 
00526 /*
00527  * TODO: Add documentation
00528  */
00529 void LoRaMacSetReceiveDelay1( uint32_t delay );
00530 
00531 /*
00532  * TODO: Add documentation
00533  */
00534 void LoRaMacSetReceiveDelay2( uint32_t delay );
00535 
00536 /*
00537  * TODO: Add documentation
00538  */
00539 void LoRaMacSetJoinAcceptDelay1( uint32_t delay );
00540 
00541 /*
00542  * TODO: Add documentation
00543  */
00544 void LoRaMacSetJoinAcceptDelay2( uint32_t delay );
00545 
00546 /*
00547  * TODO: Add documentation
00548  */
00549 uint32_t LoRaMacGetUpLinkCounter( void );
00550 
00551 /*
00552  * TODO: Add documentation
00553  */
00554 uint32_t LoRaMacGetDownLinkCounter( void );
00555 
00556 /*
00557  * ============================================================================
00558  * = LoRaMac test functions                                                   =
00559  * ============================================================================
00560  */
00561 
00562 /*!
00563  * Disables/Enables the duty cycle enforcement (EU868)
00564  *
00565  * \param   [IN] enable - Enabled or disables the duty cycle
00566  */
00567 void LoRaMacTestSetDutyCycleOn( bool enable );
00568 
00569 /*!
00570  * Disables/Enables the reception windows opening
00571  *
00572  * \param [IN] enable [true: enable, false: disable]
00573  */
00574 void LoRaMacTestRxWindowsOn( bool enable );
00575 
00576 /*!
00577  * Enables the MIC field test
00578  *
00579  * \param [IN] upLinkCounter Fixed Tx packet counter value
00580  */
00581 void LoRaMacTestSetMic( uint16_t upLinkCounter );
00582 
00583 #endif // __LORAMAC_H__