The LMIC Struct

Instead of passing numerous parameters back and forth between API and callback functions, information about the protocol state can be accessed via a global LMIC structure as shown below. All fields besides the ones explicitly mentioned below are read-only and should not be modified.

struct lmic_t {
  u1_t      frame[MAX_LEN_FRAME];
  u1_t      dataLen;    // 0 no data or zero length data, >0 byte count of data
  u1_t      dataBeg;    // 0 or start of data (dataBeg-1 is port)

  u1_t      txCnt;
  u1_t      txrxFlags;  // transaction flags (TX-RX combo)

  u1_t      pendTxPort;
  u1_t      pendTxConf; // confirmed data
  u1_t      pendTxLen;
  u1_t      pendTxData[MAX_LEN_PAYLOAD];

  u1_t      bcnChnl;
  u1_t      bcnRxsyms;
  ostime_t  bcnRxtime;
  bcninfo_t bcninfo;    // Last received beacon info

  …
  …
};

This document does not describe the full struct in detail since most of the fields of the LMIC struct are used internally only. The most important fields to examine on reception (event EV_RXCOMPLETE or EV_TXCOMPLETE) are the txrxFlags for status information and frame[] and dataLen / dataBeg for the received application payload data. For data transmission the most important fields are pendTxData[], pendTxLen, pendTxPort and pendTxConf, which are used as input to the LMIC_setTxData() API function (see 2.5.13).

For the EV_RXCOMPLETE and EV_TXCOMPLETE events, the txrxFlags field should be evaluated. The following flags are defined:

• TXRX_ACK: confirmed UP frame was acked (mutually exclusive with TXRX_NACK)

• TXRX_NACK: confirmed UP frame was not acked (mutually exclusive with TXRX_ACK)

• TXRX_PORT: a port byte is contained in the received frame at offset LMIC.dataBeg – 1.

• TXRX_NOPORT: no port byte is available.

• TXRX_DNW1: received in first DOWN slot (mutually exclusive with TXRX_DNW2)

• TXRX_DNW2: received in second DOWN slot (mutually exclusive with TXRX_DNW1)

• TXRX_PING: received in a scheduled RX slot

• TXRX_LENERR: the transmitted message was abandoned because it was longer than the established data rate.

For the EV_TXCOMPLETE event the fields have the following values:

Received frame	LMIC.txrxFlags								LMIC.dataLen	LMIC.dataBeg
	ACK	NACK	PORT	NOPORT	DNW1	DNW2	PING	LENERR
nothing	0	0	0	1	0	0	0	0	0	0
empty frame	x	x	0	1	x	x	0	0	0	x
port only	x	x	1	0	x	x	0	0	0	x
port+payload	x	x	1	0	x	x	0	0	x	X
No message received, transmit message too long	0	0	0	1	x	x	x	1	0	0

For the EV_RXCOMPLETE event the fields have the following values:

Received frame	LMIC.txrxFlags							LMIC.dataLen	LMIC.dataBeg
	ACK	NACK	PORT	NOPORT	DNW1	DNW2	PING
empty frame	0	0	0	1	0	0	1	0	x
port only	0	0	1	0	0	0	1	0	x
port+payload	0	0	1	0	0	0	1	x	x