LMIC lib Lora OTA device for Everynet

Fork of LMiC-10secs by Alcatel-Lucent IoT Development

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers lmic.h Source File

lmic.h

Go to the documentation of this file.
00001 /*******************************************************************************
00002  * Copyright (c) 2014-2015 IBM Corporation.
00003  * All rights reserved. This program and the accompanying materials
00004  * are made available under the terms of the Eclipse Public License v1.0
00005  * which accompanies this distribution, and is available at
00006  * http://www.eclipse.org/legal/epl-v10.html
00007  *
00008  * Contributors:
00009  *    IBM Zurich Research Lab - initial API, implementation and documentation
00010  *******************************************************************************/
00011 
00012 //! @file
00013 //! @brief LMIC API
00014 
00015 #ifndef _lmic_h_
00016 #define _lmic_h_
00017 
00018 // MBED compiler options
00019 #define CFG_eu868                                   1
00020 //#define CFG_us915                                   0
00021 
00022 #define USE_SMTC_RADIO_DRIVER                       1
00023 
00024 //#define CFG_sx1272_radio                            0
00025 #define CFG_sx1276_radio                            1
00026 // End MBED compiler options
00027 
00028 #include "oslmic.h "
00029 #include "lorabase.h"
00030 
00031 // LMIC version
00032 #define LMIC_VERSION_MAJOR 1
00033 #define LMIC_VERSION_MINOR 4
00034 #define LMIC_VERSION_BUILD 1426605786
00035 
00036 enum { MAX_FRAME_LEN      =  64 };   //!< Library cap on max frame length
00037 //enum { MAX_FRAME_LEN      =  96 };   //!< Library cap on max frame length
00038 enum { TXCONF_ATTEMPTS    =   8 };   //!< Transmit attempts for confirmed frames
00039 enum { MAX_MISSED_BCNS    =  20 };   // threshold for triggering rejoin requests
00040 enum { MAX_RXSYMS         = 100 };   // stop tracking beacon beyond this
00041 
00042 enum { LINK_CHECK_CONT    =   6 ,    // continue with this after reported dead link
00043        LINK_CHECK_DEAD    =  12 ,    // after this UP frames and no response from NWK assume link is dead
00044        LINK_CHECK_INIT    = -12 ,    // UP frame count until we inc datarate
00045        LINK_CHECK_OFF     =-128 };   // link check disabled
00046 
00047 enum { TIME_RESYNC        =  6*128 }; // secs
00048 enum { TXRX_GUARD_ms      =  6000 };  // msecs - don't start TX-RX transaction before beacon
00049 enum { JOIN_GUARD_ms      =  9000 };  // msecs - don't start Join Req/Acc transaction before beacon
00050 enum { TXRX_BCNEXT_secs   =     2 };  // secs - earliest start after beacon time
00051 enum { RETRY_PERIOD_secs  =     3 };  // secs - random period for retrying a confirmed send
00052 
00053 //PANY
00054 /*
00055 enum { TIME_RESYNC        =  6*128 }; // secs
00056 enum { TXRX_GUARD_ms      =  1000 };  // msecs - don't start TX-RX transaction before beacon
00057 enum { JOIN_GUARD_ms      =  1000 };  // msecs - don't start Join Req/Acc transaction before beacon
00058 enum { TXRX_BCNEXT_secs   =     1 };  // secs - earliest start after beacon time
00059 enum { RETRY_PERIOD_secs  =     1 };  // secs - random period for retrying a confirmed send
00060 */
00061 //PANY
00062 #if defined(CFG_eu868) // EU868 spectrum ====================================================
00063 
00064 enum { MAX_CHANNELS = 16 };      //!< Max supported channels
00065 enum { MAX_BANDS    =  4 };
00066 
00067 enum { LIMIT_CHANNELS = (1<<4) };   // EU868 will never have more channels
00068 //! \internal
00069 struct band_t {
00070     u2_t     txcap;     // duty cycle limitation: 1/txcap
00071     s1_t     txpow;     // maximum TX power
00072     u1_t     lastchnl;  // last used channel
00073     ostime_t avail;     // channel is blocked until this time
00074 };
00075 TYPEDEF_xref2band_t; //!< \internal
00076 
00077 #elif defined(CFG_us915)  // US915 spectrum =================================================
00078 
00079 enum { MAX_XCHANNELS = 2 };      // extra channels in RAM, channels 0-71 are immutable 
00080 enum { MAX_TXPOW_125kHz = 30 };
00081 
00082 #endif // ==========================================================================
00083 
00084 // Keep in sync with evdefs.hpp::drChange
00085 enum { DRCHG_SET, DRCHG_NOJACC, DRCHG_NOACK, DRCHG_NOADRACK, DRCHG_NWKCMD };
00086 enum { KEEP_TXPOW = -128 };
00087 
00088 
00089 //! \internal
00090 struct rxsched_t {
00091     u1_t     dr;
00092     u1_t     intvExp;   // 0..7
00093     u1_t     slot;      // runs from 0 to 128
00094     u1_t     rxsyms;
00095     ostime_t rxbase;
00096     ostime_t rxtime;    // start of next spot
00097     u4_t     freq;
00098 };
00099 TYPEDEF_xref2rxsched_t;  //!< \internal
00100 
00101 
00102 //! Parsing and tracking states of beacons.
00103 enum { BCN_NONE    = 0x00,   //!< No beacon received
00104        BCN_PARTIAL = 0x01,   //!< Only first (common) part could be decoded (info,lat,lon invalid/previous)
00105        BCN_FULL    = 0x02,   //!< Full beacon decoded
00106        BCN_NODRIFT = 0x04,   //!< No drift value measured yet
00107        BCN_NODDIFF = 0x08 }; //!< No differential drift measured yet
00108 //! Information about the last and previous beacons.
00109 struct bcninfo_t {
00110     ostime_t txtime;  //!< Time when the beacon was sent
00111     s1_t     rssi;    //!< Adjusted RSSI value of last received beacon
00112     s1_t     snr;     //!< Scaled SNR value of last received beacon
00113     u1_t     flags;   //!< Last beacon reception and tracking states. See BCN_* values.
00114     u4_t     time;    //!< GPS time in seconds of last beacon (received or surrogate)
00115     //
00116     u1_t     info;    //!< Info field of last beacon (valid only if BCN_FULL set)
00117     s4_t     lat;     //!< Lat field of last beacon (valid only if BCN_FULL set)
00118     s4_t     lon;     //!< Lon field of last beacon (valid only if BCN_FULL set)
00119 };
00120 
00121 // purpose of receive window - lmic_t.rxState
00122 enum { RADIO_RST=0, RADIO_TX=1, RADIO_RX=2, RADIO_RXON=3 };
00123 // Netid values /  lmic_t.netid
00124 enum { NETID_NONE=(int)~0U, NETID_MASK=(int)0xFFFFFF };
00125 // MAC operation modes (lmic_t.opmode).
00126 enum { OP_NONE     = 0x0000,
00127        OP_SCAN     = 0x0001, // radio scan to find a beacon
00128        OP_TRACK    = 0x0002, // track my networks beacon (netid)
00129        OP_JOINING  = 0x0004, // device joining in progress (blocks other activities)
00130        OP_TXDATA   = 0x0008, // TX user data (buffered in pendTxData)
00131        OP_POLL     = 0x0010, // send empty UP frame to ACK confirmed DN/fetch more DN data
00132        OP_REJOIN   = 0x0020, // occasionally send JOIN REQUEST
00133        OP_SHUTDOWN = 0x0040, // prevent MAC from doing anything
00134        OP_TXRXPEND = 0x0080, // TX/RX transaction pending
00135        OP_RNDTX    = 0x0100, // prevent TX lining up after a beacon
00136        OP_PINGINI  = 0x0200, // pingable is initialized and scheduling active
00137        OP_PINGABLE = 0x0400, // we're pingable
00138        OP_NEXTCHNL = 0x0800, // find a new channel
00139        OP_LINKDEAD = 0x1000, // link was reported as dead
00140        OP_TESTMODE = 0x2000, // developer test mode
00141 };
00142 // TX-RX transaction flags - report back to user
00143 enum { TXRX_ACK    = 0x80,   // confirmed UP frame was acked
00144        TXRX_NACK   = 0x40,   // confirmed UP frame was not acked
00145        TXRX_NOPORT = 0x20,   // set if a frame with a port was RXed, clr if no frame/no port
00146        TXRX_PORT   = 0x10,   // set if a frame with a port was RXed, LMIC.frame[LMIC.dataBeg-1] => port
00147        TXRX_DNW1   = 0x01,   // received in 1st DN slot
00148        TXRX_DNW2   = 0x02,   // received in 2dn DN slot
00149        TXRX_PING   = 0x04 }; // received in a scheduled RX slot
00150 // Event types for event callback
00151 enum _ev_t { EV_SCAN_TIMEOUT=1, EV_BEACON_FOUND,
00152              EV_BEACON_MISSED, EV_BEACON_TRACKED, EV_JOINING,
00153              EV_JOINED, EV_RFU1, EV_JOIN_FAILED, EV_REJOIN_FAILED,
00154              EV_TXCOMPLETE, EV_LOST_TSYNC, EV_RESET,
00155              EV_RXCOMPLETE, EV_LINK_DEAD, EV_LINK_ALIVE };
00156 typedef enum _ev_t ev_t;
00157 
00158 
00159 struct lmic_t {
00160     // Radio settings TX/RX (also accessed by HAL)
00161     ostime_t    txend;
00162     ostime_t    rxtime;
00163     u4_t        freq;
00164     s1_t        rssi;
00165     s1_t        snr;
00166     rps_t       rps;
00167     u1_t        rxsyms;
00168     u1_t        dndr;
00169     s1_t        txpow;     // dBm
00170 
00171     osjob_t     osjob;
00172 
00173     // Channel scheduling
00174 #if defined(CFG_eu868)
00175     band_t      bands[MAX_BANDS];
00176     u4_t        channelFreq[MAX_CHANNELS];
00177     u2_t        channelDrMap[MAX_CHANNELS];
00178     u2_t        channelMap;
00179 #elif defined(CFG_us915)
00180     u4_t        xchFreq[MAX_XCHANNELS];    // extra channel frequencies (if device is behind a repeater)
00181     u2_t        xchDrMap[MAX_XCHANNELS];   // extra channel datarate ranges  ---XXX: ditto
00182     u2_t        channelMap[(72+MAX_XCHANNELS+15)/16];  // enabled bits
00183     u2_t        chRnd;        // channel randomizer
00184 #endif
00185     u1_t        txChnl;          // channel for next TX
00186     u1_t        globalDutyRate;  // max rate: 1/2^k
00187     ostime_t    globalDutyAvail; // time device can send again
00188     
00189     u4_t        netid;        // current network id (~0 - none)
00190     u2_t        opmode;
00191     u1_t        upRepeat;     // configured up repeat
00192     s1_t        adrTxPow;     // ADR adjusted TX power
00193     u1_t        datarate;     // current data rate
00194     u1_t        errcr;        // error coding rate (used for TX only)
00195     u1_t        rejoinCnt;    // adjustment for rejoin datarate
00196     s2_t        drift;        // last measured drift
00197     s2_t        lastDriftDiff;
00198     s2_t        maxDriftDiff;
00199 
00200     u1_t        pendTxPort;
00201     u1_t        pendTxConf;   // confirmed data
00202     u1_t        pendTxLen;    // +0x80 = confirmed
00203     u1_t        pendTxData[MAX_LEN_PAYLOAD];
00204 
00205     u2_t        devNonce;     // last generated nonce
00206     u1_t        nwkKey[16];   // network session key
00207     u1_t        artKey[16];   // application router session key
00208     devaddr_t   devaddr;
00209     u4_t        seqnoDn;      // device level down stream seqno
00210     u4_t        seqnoUp;
00211 
00212     u1_t        dnConf;       // dn frame confirm pending: LORA::FCT_ACK or 0
00213     s1_t        adrAckReq;    // counter until we reset data rate (0=off)
00214     u1_t        adrChanged;
00215 
00216     u1_t        margin;
00217     bit_t       ladrAns;      // link adr adapt answer pending
00218     bit_t       devsAns;      // device status answer pending
00219     u1_t        adrEnabled;
00220     u1_t        moreData;     // NWK has more data pending
00221     bit_t       dutyCapAns;   // have to ACK duty cycle settings
00222     u1_t        snchAns;      // answer set new channel
00223     // 2nd RX window (after up stream)
00224     u1_t        dn2Dr;
00225     u4_t        dn2Freq;
00226     u1_t        dn2Ans;       // 0=no answer pend, 0x80+ACKs
00227 
00228     // Class B state
00229     u1_t        missedBcns;   // unable to track last N beacons
00230     u1_t        bcninfoTries; // how often to try (scan mode only)
00231     u1_t        pingSetAns;   // answer set cmd and ACK bits
00232     rxsched_t   ping;         // pingable setup
00233 
00234     // Public part of MAC state
00235     u1_t        txCnt;
00236     u1_t        txrxFlags;  // transaction flags (TX-RX combo)
00237     u1_t        dataBeg;    // 0 or start of data (dataBeg-1 is port)
00238     u1_t        dataLen;    // 0 no data or zero length data, >0 byte count of data
00239     u1_t        frame[MAX_LEN_FRAME];
00240 
00241     u1_t        bcnChnl;
00242     u1_t        bcnRxsyms;    // 
00243     ostime_t    bcnRxtime;
00244     bcninfo_t   bcninfo;      // Last received beacon info
00245 };
00246 //! \var struct lmic_t LMIC
00247 //! The state of LMIC MAC layer is encapsulated in this variable.
00248 DECLARE_LMIC; //!< \internal
00249 
00250 //! Construct a bit map of allowed datarates from drlo to drhi (both included). 
00251 #define DR_RANGE_MAP(drlo,drhi) (((u2_t)0xFFFF<<(drlo)) & ((u2_t)0xFFFF>>(15-(drhi))))
00252 #if defined(CFG_eu868)
00253 enum { BAND_MILLI=0, BAND_CENTI=1, BAND_DECI=2, BAND_AUX=3 };
00254 bit_t LMIC_setupBand (u1_t bandidx, s1_t txpow, u2_t txcap);
00255 #endif
00256 bit_t LMIC_setupChannel (u1_t channel, u4_t freq, u2_t drmap, s1_t band);
00257 void  LMIC_disableChannel (u1_t channel);
00258 
00259 void  LMIC_setDrTxpow   (dr_t dr, s1_t txpow);  // set default/start DR/txpow
00260 void  LMIC_setAdrMode   (bit_t enabled);        // set ADR mode (if mobile turn off)
00261 bit_t LMIC_startJoining (void);
00262 
00263 void  LMIC_shutdown     (void);
00264 void  LMIC_init         (void);
00265 void  LMIC_reset        (void);
00266 void  LMIC_clrTxData    (void);
00267 void  LMIC_setTxData    (void);
00268 int   LMIC_setTxData2   (u1_t port, xref2u1_t data, u1_t dlen, u1_t confirmed, int encrypted);
00269 void  LMIC_sendAlive    (void);
00270 
00271 bit_t LMIC_enableTracking  (u1_t tryBcnInfo);
00272 void  LMIC_disableTracking (void);
00273 
00274 void  LMIC_stopPingable  (void);
00275 void  LMIC_setPingable   (u1_t intvExp);
00276 void  LMIC_tryRejoin     (void);
00277 
00278 void LMIC_setSession (u4_t netid, devaddr_t devaddr, xref2u1_t nwkKey, xref2u1_t artKey);
00279 void LMIC_setLinkCheckMode (bit_t enabled);
00280 
00281 // Special APIs - for development or testing
00282 // !!!See implementation for caveats!!!
00283 
00284 #endif // _lmic_h_