lmic.h

Go to the documentation of this file.

/*
 * Copyright (c) 2014-2016 IBM Corporation.
 * Copyright (c) 2016 Matthijs Kooijman.
 * Copyright (c) 2016-2026 MCCI Corporation.
 * All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are met:
 *  * Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *  * Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *  * Neither the name of the <organization> nor the
 *    names of its contributors may be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

 
#ifndef _lmic_h_
#define _lmic_h_
 
#include "oslmic.h"
#include "lorabase.h"
#ifndef _lmic_version_h_
# include "lmic_version.h"
#endif
 
#if LMIC_DEBUG_LEVEL > 0 || LMIC_X_DEBUG_LEVEL > 0
# if defined(LMIC_DEBUG_INCLUDE)
#   define LMIC_STRINGIFY_(x) #x
#   define LMIC_STRINGIFY(x) LMIC_STRINGIFY_(x)
#   include LMIC_STRINGIFY(LMIC_DEBUG_INCLUDE)
# endif
#  ifdef LMIC_DEBUG_PRINTF_FN
     extern void LMIC_DEBUG_PRINTF_FN(const char *f, ...);
#  endif // ndef LMIC_DEBUG_PRINTF_FN
#endif
 
// if LMIC_DEBUG_PRINTF is now defined, just use it. This lets you do anything
// you like with a sufficiently crazy header file.
#if LMIC_DEBUG_LEVEL > 0
# ifndef LMIC_DEBUG_PRINTF
//  otherwise, check whether someone configured a print-function to be used,
//  and use it if so.
#   ifdef LMIC_DEBUG_PRINTF_FN
#     define LMIC_DEBUG_PRINTF(f, ...) LMIC_DEBUG_PRINTF_FN(f, ## __VA_ARGS__)
#     ifndef LMIC_DEBUG_INCLUDE // If you use LMIC_DEBUG_INCLUDE, put the declaration in there
        void LMIC_DEBUG_PRINTF_FN(const char *f, ...);
#     endif // ndef LMIC_DEBUG_INCLUDE
#   else // ndef LMIC_DEBUG_PRINTF_FN
//    if there's no other info, just use printf. In a pure Arduino environment,
//    that's what will happen.
#     include <stdio.h>
#     define LMIC_DEBUG_PRINTF(f, ...) printf(f, ## __VA_ARGS__)
#   endif // ndef LMIC_DEBUG_PRINTF_FN
# endif // ndef LMIC_DEBUG_PRINTF
# ifndef LMIC_DEBUG_FLUSH
#   ifdef LMIC_DEBUG_FLUSH_FN
#     define LMIC_DEBUG_FLUSH() LMIC_DEBUG_FLUSH_FN()
#   else // ndef LMIC_DEBUG_FLUSH_FN
//    if there's no other info, assume that flush is not needed.
#     define LMIC_DEBUG_FLUSH() do { ; } while (0)
#   endif // ndef LMIC_DEBUG_FLUSH_FN
# endif // ndef LMIC_DEBUG_FLUSH
#else // LMIC_DEBUG_LEVEL == 0
// If debug level is zero, printf and flush expand to nothing.
# define LMIC_DEBUG_PRINTF(f, ...)      do { ; } while (0)
# define LMIC_DEBUG_FLUSH()             do { ; } while (0)
#endif // LMIC_DEBUG_LEVEL == 0
 
//
// LMIC_X_DEBUG_LEVEL enables additional, special print functions for debugging
// RSSI features. This is used sparingly.
#if LMIC_X_DEBUG_LEVEL > 0
#  ifdef LMIC_DEBUG_PRINTF_FN
#    define LMIC_X_DEBUG_PRINTF(f, ...) LMIC_DEBUG_PRINTF_FN(f, ## __VA_ARGS__)
#  else
#    error "LMIC_DEBUG_PRINTF_FN must be defined for LMIC_X_DEBUG_LEVEL > 0."
#  endif
#else
#  define LMIC_X_DEBUG_PRINTF(f, ...)  do {;} while(0)
#endif
 
#ifdef __cplusplus
extern "C"{
#endif

//#define CFG_TxContinuousMode 1
 
// since this was announced as the API variable, we keep it. But it's not used,
// MAX_LEN_FRAME is what the code uses.
enum { MAX_FRAME_LEN      =  MAX_LEN_FRAME };   
 
enum { TXCONF_ATTEMPTS    =   8 };   
enum { MAX_MISSED_BCNS    =  (2 * 60 * 60 + 127) / 128 };   
                                     // note that we need 100 ppm timing accuracy for
                                     // this, to keep the timing error to +/- 700ms.
enum { MAX_RXSYMS         = 350 };   // Stop tracking beacon if sync error grows beyond this. A 0.4% clock error
                                     // at SF9.125k means 512 ms; one symbol is 4.096 ms,
                                     // so this needs to be at least 125 for an STM32L0.
                                     // And for 100ppm clocks and 2 hours of beacon misses,
                                     // this needs to accommodate 1.4 seconds of error at
                                     // 4.096 ms/sym or at least 342 symbols.
 
enum { LINK_CHECK_CONT    =  0  ,    // continue with this after reported dead link
       LINK_CHECK_DEAD    =  32 ,    // after this UP frames and no response to ack from NWK assume link is dead (ADR_ACK_DELAY)
       LINK_CHECK_UNJOIN_MIN = LINK_CHECK_DEAD + 4,         // this is the minimum value of LINK_CHECK_UNJOIN if we parameterize
       LINK_CHECK_UNJOIN  =  LINK_CHECK_DEAD + (3 * 240),   // after this many UP frames and no response, switch to join (by default)
       LINK_CHECK_INIT    = -64 ,    // UP frame count until we ask for ack (ADR_ACK_LIMIT)
       LINK_CHECK_OFF     =-128 };   // link check disabled
 
enum { TIME_RESYNC        = 6*128 }; // secs
enum { TXRX_GUARD_ms      =  6000 };  // msecs - don't start TX-RX transaction before beacon
enum { JOIN_GUARD_ms      =  9000 };  // msecs - don't start Join Req/Acc transaction before beacon
enum { TXRX_BCNEXT_secs   =     2 };  // secs - earliest start after beacon time
enum { RETRY_PERIOD_secs  =     3 };  // secs - random period for retrying a confirmed send
 
#if CFG_LMIC_EU_like // EU868 spectrum ====================================================
 
enum { MAX_CHANNELS = 16 };      
enum { MAX_BANDS    =  4 };
 
enum { LIMIT_CHANNELS = (1<<4) };   // EU868 will never have more channels
struct band_t {
    u2_t     txcap;     // duty cycle limitation: 1/txcap
    s1_t     txpow;     // maximum TX power
    u1_t     lastchnl;  // last used channel
    ostime_t avail;     // band is blocked until this time
};
TYPEDEF_xref2band_t; 
 
struct lmic_saved_adr_state_s {
    u4_t        channelFreq[MAX_CHANNELS];
    u2_t        channelMap;
};
 
#elif CFG_LMIC_US_like  // US915 spectrum =================================================
 
struct lmic_saved_adr_state_s {
    u2_t        channelMap[(72+15)/16];  // enabled bits
    u2_t        activeChannels125khz;
    u2_t        activeChannels500khz;
};
 
#endif // ==========================================================================
 
typedef struct lmic_saved_adr_state_s   lmic_saved_adr_state_t;
 
// Keep in sync with evdefs.hpp::drChange
enum { DRCHG_SET, DRCHG_NOJACC, DRCHG_NOACK, DRCHG_NOADRACK, DRCHG_NWKCMD, DRCHG_FRAMESIZE };
enum { KEEP_TXPOW = -128 };
 
 
#if !defined(DISABLE_PING)
struct rxsched_t {
    dr_t     dr;
    u1_t     intvExp;   // 0..7
    u1_t     slot;      // runs from 0 to 128
    rxsyms_t rxsyms;
    ostime_t rxbase;
    ostime_t rxtime;    // start of next spot
    u4_t     freq;
};
TYPEDEF_xref2rxsched_t;  
#endif // !DISABLE_PING
 
 
#if !defined(DISABLE_BEACONS)
enum { BCN_NONE    = 0x00,   
       BCN_PARTIAL = 0x01,   
       BCN_FULL    = 0x02,   
       BCN_NODRIFT = 0x04,   
       BCN_NODDIFF = 0x08 }; 
struct bcninfo_t {
    ostime_t txtime;  
    u4_t     time;    
    s4_t     lat;     
    s4_t     lon;     
    s1_t     rssi;    
    s1_t     snr;     
    u1_t     flags;   
    //
    u1_t     info;    
};
#endif // !DISABLE_BEACONS

enum { RADIO_RST=0,     
       RADIO_TX=1,      
       RADIO_RX=2,      
       RADIO_RXON=3,    
       RADIO_TX_AT=4,   
       RADIO_RXON_C=5,  
       };
 
// Netid values /  lmic_t.netid
enum { NETID_NONE=(int)~0U, NETID_MASK=(int)0xFFFFFF };
// MAC operation modes (lmic_t.opmode).
enum { OP_NONE     = 0x0000,
       OP_SCAN     = 0x0001, 
       OP_TRACK    = 0x0002, 
       OP_JOINING  = 0x0004, 
       OP_TXDATA   = 0x0008, 
       OP_POLL     = 0x0010, 
       OP_REJOIN   = 0x0020, 
       OP_SHUTDOWN = 0x0040, 
       OP_TXRXPEND = 0x0080, 
       OP_RNDTX    = 0x0100, 
       OP_PINGINI  = 0x0200, 
       OP_PINGABLE = 0x0400, 
       OP_NEXTCHNL = 0x0800, 
       OP_LINKDEAD = 0x1000, 
       OP_TESTMODE = 0x2000, 
       OP_UNJOIN   = 0x4000, 
};
// TX-RX transaction flags - report back to user
enum { TXRX_ACK    = 0x80,   
       TXRX_NACK   = 0x40,   
       TXRX_NOPORT = 0x20,   
       TXRX_PORT   = 0x10,   
       TXRX_LENERR = 0x08,   
       TXRX_PING   = 0x04,   
       TXRX_DNW2   = 0x02,   
       TXRX_DNW1   = 0x01,   
};

static inline bit_t LMIC_txrxFlags_isClassC(u1_t flags) {
    return (flags & (TXRX_PING | TXRX_DNW2 | TXRX_DNW1)) == (TXRX_PING | TXRX_DNW2);
}

static inline bit_t LMIC_txrxFlags_isRx1(u1_t flags) {
    return (flags & (TXRX_PING | TXRX_DNW2 | TXRX_DNW1)) == (TXRX_DNW1);
}

static inline bit_t LMIC_txrxFlags_isRx2(u1_t flags) {
    return (flags & (TXRX_PING | TXRX_DNW2 | TXRX_DNW1)) == (TXRX_DNW2);
}

static inline bit_t LMIC_txrxFlags_isClassA(u1_t flags) {
    return LMIC_txrxFlags_isRx1(flags) || LMIC_txrxFlags_isRx2(flags);
}

static inline u1_t LMIC_txrxFlags_setClassC(u1_t flags) {
    return (flags & ~TXRX_DNW1) | (TXRX_PING | TXRX_DNW2);
}

static inline u1_t LMIC_txrxFlags_setRx1(u1_t flags) {
    return (flags & ~(TXRX_PING | TXRX_DNW2)) | (TXRX_DNW1);
}

static inline u1_t LMIC_txrxFlags_setRx2(u1_t flags) {
    return (flags & ~(TXRX_PING | TXRX_DNW1)) | (TXRX_DNW2);
}

static inline u1_t LMIC_txrxFlags_setRxPing(u1_t flags) {
    return (flags & ~(TXRX_DNW2 | TXRX_DNW1)) | (TXRX_PING);
}

enum _ev_t { EV_SCAN_TIMEOUT=1, EV_BEACON_FOUND,
             EV_BEACON_MISSED, EV_BEACON_TRACKED, EV_JOINING,
             EV_JOINED, EV_RFU1, EV_JOIN_FAILED, EV_REJOIN_FAILED,
             EV_TXCOMPLETE, EV_LOST_TSYNC, EV_RESET,
             EV_RXCOMPLETE, EV_LINK_DEAD, EV_LINK_ALIVE, EV_SCAN_FOUND,
             EV_TXSTART, EV_TXCANCELED, EV_RXSTART, EV_JOIN_TXCOMPLETE };
typedef enum _ev_t ev_t;

#define LMIC_EVENT_NAME_TABLE__INIT                                         \
    "<<zero>>",                                                             \
    "EV_SCAN_TIMEOUT", "EV_BEACON_FOUND",                                   \
    "EV_BEACON_MISSED", "EV_BEACON_TRACKED", "EV_JOINING",                  \
    "EV_JOINED", "EV_RFU1", "EV_JOIN_FAILED", "EV_REJOIN_FAILED",           \
    "EV_TXCOMPLETE", "EV_LOST_TSYNC", "EV_RESET",                           \
    "EV_RXCOMPLETE", "EV_LINK_DEAD", "EV_LINK_ALIVE", "EV_SCAN_FOUND",      \
    "EV_TXSTART", "EV_TXCANCELED", "EV_RXSTART", "EV_JOIN_TXCOMPLETE"

// /entry that begins with a \0.
#define LMIC_EVENT_NAME_MULTISZ__INIT                                       \
    "<<zero>>\0"                                                            \
    "EV_SCAN_TIMEOUT\0" "EV_BEACON_FOUND\0"                                 \
    "EV_BEACON_MISSED\0" "EV_BEACON_TRACKED\0" "EV_JOINING\0"               \
    "EV_JOINED\0" "EV_RFU1\0" "EV_JOIN_FAILED\0" "EV_REJOIN_FAILED\0"       \
    "EV_TXCOMPLETE\0" "EV_LOST_TSYNC\0" "EV_RESET\0"                        \
    "EV_RXCOMPLETE\0" "EV_LINK_DEAD\0" "EV_LINK_ALIVE\0" "EV_SCAN_FOUND\0"  \
    "EV_TXSTART\0" "EV_TXCANCELED\0" "EV_RXSTART\0" "EV_JOIN_TXCOMPLETE\0"

enum lmic_tx_error_e {
    LMIC_ERROR_SUCCESS = 0,             
    LMIC_ERROR_TX_BUSY = -1,            
    LMIC_ERROR_TX_TOO_LARGE = -2,       
    LMIC_ERROR_TX_NOT_FEASIBLE = -3,    
    LMIC_ERROR_TX_FAILED = -4,          
};

typedef int lmic_tx_error_t;

#define LMIC_ERROR_NAME__INIT                                               \
    "LMIC_ERROR_SUCCESS",                                                   \
    "LMIC_ERROR_TX_BUSY",                                                   \
    "LMIC_ERROR_TX_TOO_LARGE",                                              \
    "LMIC_ERROR_TX_NOT_FEASIBLE",                                           \
    "LMIC_ERROR_TX_FAILED"

#define LMIC_ERROR_NAME_MULTISZ__INIT                                       \
    "LMIC_ERROR_SUCCESS\0"                                                  \
    "LMIC_ERROR_TX_BUSY\0"                                                  \
    "LMIC_ERROR_TX_TOO_LARGE\0"                                             \
    "LMIC_ERROR_TX_NOT_FEASIBLE\0"                                          \
    "LMIC_ERROR_TX_FAILED"

enum lmic_beacon_error_e {
    LMIC_BEACON_ERROR_INVALID   = -2,       
    LMIC_BEACON_ERROR_WRONG_NETWORK = -1,   
    LMIC_BEACON_ERROR_SUCCESS_PARTIAL = 0,  
    LMIC_BEACON_ERROR_SUCCESS_FULL = 1,     
};

typedef s1_t lmic_beacon_error_t;

static inline bit_t LMIC_BEACON_SUCCESSFUL(lmic_beacon_error_t e) {
    return e < 0;
}
 
enum {
        MAX_CLOCK_ERROR = 65536,
        LMIC_kMaxClockError_ppm = 4000,
};
 
// callbacks for client alerts.
// types and functions are always defined, to reduce #ifs in example code and libraries.
typedef void LMIC_ABI_STD lmic_rxmessage_cb_t(void *pUserData, uint8_t port, const uint8_t *pMessage, size_t nMessage);
typedef void LMIC_ABI_STD lmic_txmessage_cb_t(void *pUserData, int fSuccess);
typedef void LMIC_ABI_STD lmic_event_cb_t(void *pUserData, ev_t e);

typedef void LMIC_ABI_STD lmic_request_network_time_cb_t(void *pUserData, int flagSuccess);

typedef u4_t lmic_gpstime_t;
 
// rather than deal with 1/256 second tick, we adjust ostime back
// (as it's high res) to match tNetwork.
typedef struct lmic_time_reference_s lmic_time_reference_t;
 
struct lmic_time_reference_s {
    ostime_t tLocal;
    lmic_gpstime_t tNetwork;
};
 
enum lmic_request_time_state_e {
    lmic_RequestTimeState_idle = 0,     
    lmic_RequestTimeState_tx,           
    lmic_RequestTimeState_rx,           
    lmic_RequestTimeState_success       
};
 
typedef u1_t lmic_request_time_state_t;
 
enum lmic_engine_update_state_e {
    lmic_EngineUpdateState_idle = 0,    
    lmic_EngineUpdateState_busy = 1,    
    lmic_EngineUpdateState_again = 2,   
};
 
typedef u1_t lmic_engine_update_state_t;

typedef struct lmic_client_data_s lmic_client_data_t;

struct lmic_client_data_s {
 
    /* pointer-width things come first */
#if LMIC_ENABLE_DeviceTimeReq
    lmic_request_network_time_cb_t *pNetworkTimeCb; 
    void        *pNetworkTimeUserData;              
#endif
 
#if LMIC_ENABLE_user_events
    lmic_event_cb_t     *eventCb;           
    void                *eventUserData;     
    lmic_rxmessage_cb_t *rxMessageCb;       
    void                *rxMessageUserData; 
    lmic_txmessage_cb_t *txMessageCb;       
    void                *txMessageUserData; 
#endif // LMIC_ENABLE_user_events
 
    /* next we have things that are (u)int32_t */
    /* none at the moment */
 
    /* next we have things that are (u)int16_t */
 
    u2_t        clockError;                 
 
    /* finally, things that are (u)int8_t */
    u1_t        devStatusAns_battery;       
};
 
/****************************************************************************\
|
|   Radio driver interface
|
\****************************************************************************/

typedef u1_t lmic_radio_state_t;

enum lmic_radio_state_e {
    LMIC_RADIO_EV_NONE      = 0u,           
    LMIC_RADIO_EV_TXSTART   = (1u << 0),    
    LMIC_RADIO_EV_TXDONE    = (1u << 1),    
    LMIC_RADIO_EV_TXDEFER   = (1u << 2),    
    LMIC_RADIO_EV_TXUNKNOWN = (1u << 3),    
    LMIC_RADIO_EV_RXSTART   = (1u << 4),    
    LMIC_RADIO_EV_RXDONE    = (1u << 5),    
    LMIC_RADIO_EV_RXTIMEOUT = (1u << 6),    
    LMIC_RADIO_EV_RXUNKNOWN = (1u << 7),    
};

typedef u1_t lmic_radio_state_t;

enum lmic_radio_flags_e {
    LMIC_RADIO_FLAGS_NO_RX_IQ_INVERSION     = 1u << 0,  
};

typedef u1_t lmic_radio_flags_t;
 

typedef struct lmic_radio_data_s lmic_radio_data_t;

struct lmic_radio_data_s {
    u4_t        freq;
    u1_t        *pFrame;
    ostime_t    rxtime;

    rps_t       rps;
    rxsyms_t    rxsyms;

    u1_t        dataLen;

    lmic_radio_flags_t flags;

    s1_t        txpow;

    lmic_radio_state_t state;

    osjob_t     *pRadioDoneJob;

    ostime_t    rxlate_ticks;
    ostime_t    txlate_ticks;
    u2_t        rxlate_count;
    u2_t        txlate_count;
};
 
 
/****************************************************************************\
|
|   Class C definitions
|
\****************************************************************************/


typedef union lmic_class_c_flags_u lmic_class_c_flags_t;

union lmic_class_c_flags_u {
    unsigned    mask;   

    struct lmic_class_c_flags_s {
        unsigned    fEnabled: 1;    
        unsigned    fRx2Active: 1;  
    } f;                
};

typedef union lmic_class_c_requests_u lmic_class_c_requests_t;

union lmic_class_c_requests_u {
    unsigned    mask;   

    struct lmic_class_c_requests_s {
        unsigned    fPending:       1;  
        unsigned    fStateChangeRq: 1;  
        unsigned    fTargetState: 1;    
    } f;    
};

typedef struct lmic_class_c_s lmic_class_c_t;

struct lmic_class_c_s {
    osjob_t                 job;        
    lmic_class_c_flags_t    flags;      
    lmic_class_c_requests_t requests;   
    u1_t                    frame[MAX_LEN_FRAME];
};

 
/****************************************************************************\
|
|   The LMIC instance object
|
\****************************************************************************/

struct lmic_t {
    lmic_client_data_t  client;

    osjob_t     osjob;

    osjob_t     osjob_defer;
 
#if !defined(DISABLE_BEACONS)
    bcninfo_t   bcninfo;      
#endif
 
#if !defined(DISABLE_PING)
    rxsched_t   ping;         
#endif

    lmic_radio_data_t   radio;
 
    /* (u)int32_t things */
 
    // Radio settings TX/RX (also accessed by HAL)
    ostime_t    txend;      
    ostime_t    rxtime;     
    ostime_t    nextRxTime; 
 
    // LBT info
    ostime_t    lbt_ticks;      
 
    u4_t        freq;           
 
    ostime_t    globalDutyAvail; 
 
    u4_t        netid;        
    devaddr_t   devaddr;      
    u4_t        seqnoDn;      
    u4_t        seqnoUp;      
    u4_t        dn2Freq;      
 
#if !defined(DISABLE_BEACONS)
    ostime_t    bcnRxtime;
#endif
 
#if LMIC_ENABLE_DeviceTimeReq
    // put here for alignment, to reduce RAM use.
    ostime_t    localDeviceTime;    // the LMIC.txend value for last DeviceTimeAns
    lmic_gpstime_t netDeviceTime;   // the netDeviceTime for lastDeviceTimeAns
                                    // zero ==> not valid.
#endif // LMIC_ENABLE_DeviceTimeReq
 
    // Channel scheduling -- very much private
#if CFG_LMIC_EU_like
    band_t      bands[MAX_BANDS];
    u4_t        channelFreq[MAX_CHANNELS];
#if !defined(DISABLE_MCMD_DlChannelReq)
    u4_t        channelDlFreq[MAX_CHANNELS];
#endif
    // bit map of enabled datarates for each channel
    u2_t        channelDrMap[MAX_CHANNELS];
    u2_t        channelMap;
    u2_t        channelShuffleMap;
#elif CFG_LMIC_US_like
    u2_t        channelMap[(72+15)/16];  // enabled bits
    u2_t        channelShuffleMap[(72+15)/16];  // enabled bits
    u2_t        activeChannels125khz;
    u2_t        activeChannels500khz;
#endif
 
    /* (u)int16_t things */
    rps_t       rps;            // radio parameter selections: SF, BW, CodingRate, NoCrc, implicit hdr
    u2_t        opmode;         // engineUpdate() operating mode flags
    u2_t        devNonce;       // last generated nonce
 
    s2_t        adrAckReq;      // counter for link integrity tracking (LINK_CHECK_OFF=off)
 
#if !defined(DISABLE_BEACONS)
    s2_t        drift;          // last measured drift
    s2_t        lastDriftDiff;
    s2_t        maxDriftDiff;
    rxsyms_t    bcnRxsyms;      //
#endif
 
    /* (u)int8_t things */
    lmic_engine_update_state_t engineUpdateState;   // state of the engineUpdate() evaluator.
    s1_t        rssi;
    s1_t        snr;            // LMIC.snr is SNR times 4
    rxsyms_t    rxsyms;         // symbols for receive timeout.
    u1_t        dndr;
    s1_t        txpow;          // transmit dBm (administrative)
    s1_t        lbt_dbmax;      // max permissible dB on our channel (eg -80)
 
    u1_t        txChnl;          // channel for next TX
    u1_t        globalDutyRate;  // max rate: 1/2^k
#if CFG_LMIC_US_like
    u1_t        txChnl_125kHz;  
#endif
    u1_t        upRepeat;     // configured up repeat
    s1_t        adrTxPow;     // ADR adjusted TX power
    u1_t        datarate;     // current data rate
    u1_t        errcr;        // error coding rate (used for TX only)
    u1_t        rejoinCnt;    // adjustment for rejoin datarate
 
    u1_t        upRepeatCount;  // current up-repeat
    bit_t       initBandplanAfterReset; // cleared by LMIC_reset(), set by first join. See issue #244
 
    u1_t        pendTxPort;
    u1_t        pendTxConf;   // confirmed data
    u1_t        pendTxLen;    // count of bytes in pendTxData.
    u1_t        pendTxData[MAX_LEN_PAYLOAD];
 
    u1_t        pendMacLen;         // number of bytes of pending Mac response data
    bit_t       pendMacPiggyback;   // received on port 0 or piggyback?
    // response data if piggybacked
    u1_t        pendMacData[LWAN_FCtrl_FOptsLen_MAX];
 
    u1_t        nwkKey[16];   // network session key
    u1_t        artKey[16];   // application router session key
 
    u1_t        dnConf;       // dn frame confirm pending: LORA::FCT_ACK or 0
    u1_t        lastDnConf;   // downlink with seqnoDn-1 requested confirmation
    u1_t        adrChanged;
 
    u1_t        rxDelay;      // Rx delay after TX
 
    u1_t        margin;
    s1_t        devAnsMargin; // SNR value between -32 and 31 (inclusive) for the last successfully received DevStatusReq command
    u1_t        adrEnabled;
    u1_t        moreData;     // NWK has more data pending
#if LMIC_ENABLE_TxParamSetupReq
    u1_t        txParam;        // the saved TX param byte.
#endif
#if LMIC_ENABLE_DeviceTimeReq
    lmic_request_time_state_t txDeviceTimeReqState;  // current state, initially idle.
    u1_t        netDeviceTimeFrac;     // updated on any DeviceTimeAns.
#endif
 
    // rx1DrOffset is the offset from uplink to downlink datarate
    u1_t        rx1DrOffset;  // captured from join. zero by default.
 
    // 2nd RX window (after up stream)
    u1_t        dn2Dr;
#if !defined(DISABLE_MCMD_RXParamSetupReq)
    u1_t        dn2Ans;       // 0=no answer pend, 0x80+ACKs
#endif
#if !defined(DISABLE_MCMD_DlChannelReq)
    u1_t        macDlChannelAns;        // 0 ==> no answer pending, 0x80+ACK bits
#endif
#if !defined(DISABLE_MCMD_RXTimingSetupReq)
    bit_t       macRxTimingSetupAns;    // 0 ==> no answer pend, non-zero inserts response.
#endif
 
    // Class B state
#if !defined(DISABLE_BEACONS)
    u1_t        missedBcns;   // unable to track last N beacons
    u1_t        bcninfoTries; // how often to try (scan mode only)
#endif
    // Public part of MAC state
    u1_t        txCnt;
    u2_t        txrxFlags;  
 
    u1_t        dataBeg;    // 0 or start of data (dataBeg-1 is port)
    u1_t        dataLen;    // 0 no data or zero length data, >0 byte count of data
    u1_t        frame[MAX_LEN_FRAME];
 
#if !defined(DISABLE_BEACONS)
    u1_t        bcnChnl;
#endif
 
    u1_t        noRXIQinversion;
    u1_t        saveIrqFlags;   // last LoRa IRQ flags
 
    // Class C state
#if LMIC_ENABLE_class_c
    lmic_class_c_t  classC;     
#endif
};

DECLARE_LMIC; 
 
/****************************************************************************\
|
|   API functions
|
\****************************************************************************/

#define DR_RANGE_MAP(drlo,drhi) (((u2_t)0xFFFF<<(drlo)) & ((u2_t)0xFFFF>>(15-(drhi))))
bit_t LMIC_setupChannelGroup (u1_t group, s1_t txpow, u2_t txcap);

static inline bit_t LMIC_setupBand (u1_t bandidx, s1_t txpow, u2_t txcap) LMIC_DEPRECATED("use LMIC_setupChannelGroup()");
static inline bit_t LMIC_setupBand (u1_t bandidx, s1_t txpow, u2_t txcap) {
        return LMIC_setupChannelGroup(bandidx, txpow, txcap);
}

bit_t LMIC_setupChannel (u1_t channel, u4_t freq, u2_t drmap, s1_t group);

bit_t LMIC_disableChannel (u1_t channel);

bit_t LMIC_enableChannel(u1_t channel);

bit_t LMIC_enableSubBand(u1_t band);

bit_t LMIC_disableSubBand(u1_t band);

bit_t LMIC_selectSubBand(u1_t band);

u1_t  LMIC_queryNumDefaultChannels(void);

typedef enum lmic_channel_bandwidth_e {
        LMIC_CHANNEL_BW_125kHz = 0,
        LMIC_CHANNEL_BW_250kHz,
        LMIC_CHANNEL_BW_500kHz,
        LMIC_CHANNEL_BW_BY_DATARATE,    
} lmic_channel_bandwidth_t;
 
enum { LMIC_CHANNEL_NO_GROUP = 0xFF };  

typedef struct lmic_channel_info_s {
        u4_t    uplinkFreq;     
        u4_t    downlinkFreq;   
        u2_t    drMap;          
        u1_t    group;          
        u1_t    bandwidth;      
        bit_t   enabled;        
        bit_t   isDefault;      
} lmic_channel_info_t;

u1_t  LMIC_queryChannelCount(void);

bit_t LMIC_queryChannel(u1_t channel, lmic_channel_info_t *pInfo);

bit_t LMIC_queryTxReady(void);
 
void  LMIC_setDrTxpow   (dr_t dr, s1_t txpow);  // set default/start DR/txpow
void  LMIC_setAdrMode   (bit_t enabled);        // set ADR mode (if mobile turn off)
 
#if !defined(DISABLE_JOIN)
bit_t LMIC_startJoining (void);
void  LMIC_tryRejoin    (void);
void  LMIC_unjoin       (void);
void  LMIC_unjoinAndRejoin (void);
#endif
 
void  LMIC_shutdown     (void);
void  LMIC_init         (void);
void  LMIC_reset        (void);
void  LMIC_clrTxData    (void);
void  LMIC_setTxData    (void);
void  LMIC_setTxData_strict(void);
lmic_tx_error_t LMIC_setTxData2(u1_t port, xref2u1_t data, u1_t dlen, u1_t confirmed);
lmic_tx_error_t LMIC_setTxData2_strict(u1_t port, xref2u1_t data, u1_t dlen, u1_t confirmed);
lmic_tx_error_t LMIC_sendWithCallback(u1_t port, xref2u1_t data, u1_t dlen, u1_t confirmed, lmic_txmessage_cb_t *pCb, void *pUserData);
lmic_tx_error_t LMIC_sendWithCallback_strict(u1_t port, xref2u1_t data, u1_t dlen, u1_t confirmed, lmic_txmessage_cb_t *pCb, void *pUserData);
void  LMIC_sendAlive    (void);
 
#if !defined(DISABLE_BEACONS)
bit_t LMIC_enableTracking  (u1_t tryBcnInfo);
void  LMIC_disableTracking (void);
#endif
 
#if !defined(DISABLE_PING)
void  LMIC_stopPingable  (void);
void  LMIC_setPingable   (u1_t intvExp);
#endif
 
void LMIC_setSession (u4_t netid, devaddr_t devaddr, xref2u1_t nwkKey, xref2u1_t artKey);
void LMIC_setLinkCheckMode (bit_t enabled);
void LMIC_setClockError(u2_t error);
 
u4_t LMIC_getSeqnoUp    (void);
u4_t LMIC_setSeqnoUp    (u4_t);
void LMIC_getSessionKeys (u4_t *netid, devaddr_t *devaddr, xref2u1_t nwkKey, xref2u1_t artKey);
 
void LMIC_requestNetworkTime(lmic_request_network_time_cb_t *pCallbackfn, void *pUserData);
int LMIC_getNetworkTimeReference(lmic_time_reference_t *pReference);
 
int LMIC_registerRxMessageCb(lmic_rxmessage_cb_t *pRxMessageCb, void *pUserData);
int LMIC_registerEventCb(lmic_event_cb_t *pEventCb, void *pUserData);
 
int LMIC_findNextChannel(uint16_t *, const uint16_t *, uint16_t, int);
 
u1_t LMIC_getBatteryLevel(void);
u1_t LMIC_setBatteryLevel(u1_t /* uBattLevel */);
 
// APIs for client half of compliance.
typedef u1_t lmic_compliance_rx_action_t;
 
enum lmic_compliance_rx_action_e {
    LMIC_COMPLIANCE_RX_ACTION_PROCESS = 0,  // process this message normally
    LMIC_COMPLIANCE_RX_ACTION_START,        // enter compliance mode, discard this message
    LMIC_COMPLIANCE_RX_ACTION_IGNORE,       // continue in compliance mode, discard this message
    LMIC_COMPLIANCE_RX_ACTION_END           // exit compliance mode, discard this message
};
 
lmic_compliance_rx_action_t LMIC_complianceRxMessage(u1_t port, const u1_t *pMessage, size_t nMessage);
 
// APIs for class C support
// We provide stubs so that users don't need to litter their code with #if unless
// they want to.
 
static inline bit_t LMIC_isConfiguredClassC(void) {
    return LMIC_ENABLE_class_c;
}
 
#if LMIC_ENABLE_class_c
bit_t LMIC_enableClassC(bit_t fOnIfTrue);
#else
static inline bit_t LMIC_enableClassC(bit_t fOnIfTrue) {
    if (fOnIfTrue)
        // class C cannot be turned on in this build;
        return 0;
    else
        // class C cannot be turned on, but the request says "turn it off"
        return 1;
}
#endif // !LMIC_ENABLE_class_c
 
// Declare onEvent() function, to make sure any definition will have the
// C conventions, even when in a C++ file.
#if LMIC_ENABLE_onEvent
DECL_ON_LMIC_EVENT;
#endif /* LMIC_ENABLE_onEvent */
 
// Special APIs - for development or testing
// !!!See implementation for caveats!!!
 
#ifdef __cplusplus
} // extern "C"
#endif
 
// names for backward compatibility
#include "lmic_compat.h"
 
#endif // _lmic_h_