lmic.c File Reference

#include "lmic_bandplan.h"
#include "lmic_implementation.h"
#include "../se/i/lmic_secure_element_api.h"

Include dependency graph for lmic.c:

Functions
u1_t	LMIC_getBatteryLevel (void)
	get battery level that is to be returned by DevStatusAns.
bit_t	LMIC_queryTxReady (void)
	check whether the LMIC is ready for a transmit packet
u1_t	LMIC_setBatteryLevel (u1_t uBattLevel)
	set battery level to be returned by DevStatusAns.
void	LMIC_setSession (u4_t netid, devaddr_t devaddr, xref2u1_t nwkKey, xref2u1_t artKey)
	Set up keys for ABP.
ostime_t	LMICcore_adjustForDrift (ostime_t delay, ostime_t hsym, rxsyms_t rxsyms_in)
	Adjust the delay (in ticks) of the target window-open time from nominal.
u2_t	os_rlsbf2 (xref2cu1_t buf)
	Read 16-bit quantity from given pointer in little endian byte order.
u4_t	os_rlsbf4 (xref2cu1_t buf)
	Read 32-bit quantity from given pointer in little endian byte order.
u4_t	os_rmsbf4 (xref2cu1_t buf)
	Read 32-bit quantity from given pointer in big endian byte order.
void	os_wlsbf2 (xref2u1_t buf, u2_t v)
	Write 16-bit quantity into buffer in little endian byte order.
void	os_wlsbf4 (xref2u1_t buf, u4_t v)
	Write 32-bit quantity into buffer in little endian byte order.
void	os_wmsbf4 (xref2u1_t buf, u4_t v)
	Write 32-bit quantity into buffer in big endian byte order.

Function Documentation

LMIC_getBatteryLevel()

u1_t LMIC_getBatteryLevel

(

void

)

get battery level that is to be returned by DevStatusAns.

Returns

This function returns the saved value of the battery level (as used for the DevStatusAns message).

See also

LMIC_setBatteryLevel()

LMIC_setBatteryLevel()

u1_t LMIC_setBatteryLevel

(

u1_t

uBattLevel

)

set battery level to be returned by DevStatusAns.

Parameters

uBattLevel

is the 8-bit value to be returned. Per LoRaWAN 1.0.3 line 769, this is MCMD_DEVS_EXT_POWER (0) if on external power, MCMD_DEVS_NOINFO (255) if not able to measure battery level, or a value in [ MCMD_DEVS_BATT_MIN, MCMD_DEVS_BATT_MAX ], numerically [1, 254], to represent the charge state of the battery. Note that this is not millivolts.

Returns

This function returns the previous value of the battery level.

The LMIC maintains an idea of the current battery state, initially set to MCMD_DEVS_NOINFO after the call to LMIC_init(). The appplication then calls this function from time to time to update the battery level.

It is possible (in non-Arduino environments) to supply a local implementation of os_getBatteryLevel(). In that case, it's up to the implementation to decide whether to use the value supplied by this API.

This implementation was chosen to minimize the risk of a battery measurement introducting breaking delays into the LMIC.

LMIC_setSession()

void LMIC_setSession	(	u4_t	netid,
		devaddr_t	devaddr,
		xref2u1_t	nwkKey,
		xref2u1_t	artKey )

Set up keys for ABP.

The LMIC stores the given session keys and put thes MAC in a state as if a join request/accept had just negotiated these keys.

Parameters

netid	a 24-bit number describing the network id this device is using
devaddr	the 32-bit session address of the device. It is strongly recommended to ensure that different devices use different numbers with high probability.
nwkKey	the 16-byte network session key used for message integrity. If NULL the caller has copied the key into LMIC.nwkKey before.
artKey	the 16-byte application router session key used for message confidentiality. If NULL the caller has copied the key into LMIC.artKey before.

Note

On Harvard architectures, if session keys are in flash and not accessible via normal C pointers, caller must fill in LMIC.{nwk,art}Key separately and pass {nwk,art}Key as NULL.

It is crucial that the combinations devaddr/nwkkey and devaddr/artkey are unique within the network identified by netid.

References OP_JOINING, OP_NEXTCHNL, OP_PINGINI, OP_REJOIN, OP_TRACK, OP_TXRXPEND, OP_UNJOIN, and os_copyMem.

LMICcore_adjustForDrift()

ostime_t LMICcore_adjustForDrift	(	ostime_t	delay,
		ostime_t	hsym,
		rxsyms_t	rxsyms_in )

Adjust the delay (in ticks) of the target window-open time from nominal.

Parameters

hsym	the duration of one-half symbol in osticks.
rxsyms_in	the nominal window length – minimum length of time to delay.

Returns

Effective delay to use (positive for later, negative for earlier).

Postcondition

LMIC.rxsyms is set to the number of rxsymbols to be used for preamble timeout.

Bug

For FSK, the radio driver ignores LMIC.rxsysms, and uses a fixed value of 4080 bits (81 ms)

The calculation of the RX Window opening time has to balance several things. The system clock might be inaccurate. Generally, the LMIC assumes that the timebase is accurage to 100 ppm, or 0.01%. 0.01% of a 6 second window is 600 microseconds. For LoRa, the fastest data rates of interest is SF7 (1024 us/symbol); with an 8-byte preamble, the shortest preamble is 8.092ms long. If using FSK, the symbol rate is 20 microseconds, but the preamble is 8*5 bits long, so the preamble is 800 microseconds. Unless LMIC_ENABLE_arbitrary_clock_error is true, we fold clock errors of > 0.4% back to 0.4%.

References LMIC_kMaxClockError_ppm, and MAX_CLOCK_ERROR.