LoRaWAN-compatible node (class A device). More...

#include <LoRaWAN.h>

Public Member Functions
	LoRaWANNode (PhysicalLayer phy, const LoRaWANBand_t band, uint8_t subBand=0)
	Default constructor. More...

void	clearSession ()
	Clear an active session, so that the device will have to rejoin the network.

uint8_t *	getBufferNonces ()
	Returns the pointer to the internal buffer that holds the LW base parameters. More...

int16_t	setBufferNonces (uint8_t *persistentBuffer)
	Fill the internal buffer that holds the LW base parameters with a supplied buffer. More...

uint8_t *	getBufferSession ()
	Returns the pointer to the internal buffer that holds the LW session parameters. More...

int16_t	setBufferSession (uint8_t *persistentBuffer)
	Fill the internal buffer that holds the LW session parameters with a supplied buffer. More...

void	beginOTAA (uint64_t joinEUI, uint64_t devEUI, uint8_t nwkKey, uint8_t appKey)
	Set the device credentials and activation configuration. More...

int16_t	activateOTAA (uint8_t initialDr=RADIOLIB_LORAWAN_DATA_RATE_UNUSED, LoRaWANJoinEvent_t *joinEvent=NULL)
	Join network by restoring OTAA session or performing over-the-air activation. By this procedure, the device will perform an exchange with the network server and set all necessary configuration. More...

void	beginABP (uint32_t addr, uint8_t fNwkSIntKey, uint8_t sNwkSIntKey, uint8_t nwkSEncKey, uint8_t appSKey)
	Set the device credentials and activation configuration. More...

int16_t	activateABP (uint8_t initialDr=RADIOLIB_LORAWAN_DATA_RATE_UNUSED)
	Join network by restoring ABP session or performing over-the-air activation. In this procedure, all necessary configuration must be provided by the user. More...

bool	isActivated ()
	Whether there is an ongoing session active.

int16_t	setRx2Dr (uint8_t dr)
	Configure the Rx2 datarate for ABP mode. This should not be needed for LoRaWAN 1.1 as it is configured through the first downlink. More...

int16_t	sendMacCommandReq (uint8_t cid)
	Add a MAC command to the uplink queue. Only LinkCheck and DeviceTime are available to the user. Other commands are ignored; duplicate MAC commands are discarded. More...

int16_t	uplink (const char str, uint8_t fPort, bool isConfirmed=false, LoRaWANEvent_t event=NULL)
	Send a message to the server. More...

int16_t	uplink (uint8_t data, size_t len, uint8_t fPort, bool isConfirmed=false, LoRaWANEvent_t event=NULL)
	Send a message to the server. More...

int16_t	downlink (uint8_t data, size_t len, LoRaWANEvent_t *event=NULL)
	Wait for downlink from the server in either RX1 or RX2 window. More...

int16_t	downlink (LoRaWANEvent_t *event=NULL)
	Wait for downlink, simplified to allow for simpler sendReceive. More...

int16_t	sendReceive (const char strUp, uint8_t fPort, uint8_t dataDown, size_t lenDown, bool isConfirmed=false, LoRaWANEvent_t eventUp=NULL, LoRaWANEvent_t *eventDown=NULL)
	Send a message to the server and wait for a downlink during Rx1 and/or Rx2 window. More...

int16_t	sendReceive (uint8_t dataUp, size_t lenUp, uint8_t fPort, uint8_t dataDown, size_t lenDown, bool isConfirmed=false, LoRaWANEvent_t eventUp=NULL, LoRaWANEvent_t *eventDown=NULL)
	Send a message to the server and wait for a downlink during Rx1 and/or Rx2 window. More...

int16_t	sendReceive (uint8_t dataUp, size_t lenUp, uint8_t fPort=1, bool isConfirmed=false, LoRaWANEvent_t eventUp=NULL, LoRaWANEvent_t *eventDown=NULL)
	Send a message to the server and wait for a downlink but don't bother the user with downlink contents. More...

void	setDeviceStatus (uint8_t battLevel)
	Set device status. More...

uint32_t	getFCntUp ()
	Returns the last uplink's frame counter; also 0 if no uplink occured yet.

uint32_t	getNFCntDown ()
	Returns the last network downlink's frame counter; also 0 if no network downlink occured yet.

uint32_t	getAFCntDown ()
	Returns the last application downlink's frame counter; also 0 if no application downlink occured yet.

void	resetFCntDown ()
	Reset the downlink frame counters (application and network) This is unsafe and can possibly allow replay attacks using downlinks. It mainly exists as part of the TS009 Specification Verification protocol.

int16_t	setDatarate (uint8_t drUp)
	Set uplink datarate. This should not be used when ADR is enabled. More...

void	setADR (bool enable=true)
	Toggle ADR to on or off. More...

void	setDutyCycle (bool enable=true, RadioLibTime_t msPerHour=0)
	Toggle adherence to dutyCycle limits to on or off. More...

RadioLibTime_t	dutyCycleInterval (RadioLibTime_t msPerHour, RadioLibTime_t airtime)
	Calculate the minimum interval to adhere to a certain dutyCycle. This interval is based on the ToA of one uplink and does not actually keep track of total airtime. More...

RadioLibTime_t	timeUntilUplink ()
	Returns time in milliseconds until next uplink is available under dutyCycle limits.

void	setDwellTime (bool enable, RadioLibTime_t msPerUplink=0)
	Toggle adherence to dwellTime limits to on or off. More...

uint8_t	maxPayloadDwellTime ()
	Returns the maximum payload given the currently present dwell time limits. WARNING: the addition of MAC commands may cause uplink errors; if you want to be sure that your payload fits within dwell time limits, subtract 16 from the result!

int16_t	setTxPower (int8_t txPower)
	Configure TX power of the radio module. More...

int16_t	getMacLinkCheckAns (uint8_t margin, uint8_t gwCnt)
	Returns the quality of connectivity after requesting a LinkCheck MAC command. Returns 'true' if a network response was successfully parsed. Returns 'false' if there was no network response / parsing failed. More...

int16_t	getMacDeviceTimeAns (uint32_t gpsEpoch, uint8_t fraction, bool returnUnix=true)
	Returns the network time after requesting a DeviceTime MAC command. Returns 'true' if a network response was successfully parsed. Returns 'false' if there was no network response / parsing failed. More...

uint32_t	getDevAddr ()
	Returns the DevAddr of the device, regardless of OTAA or ABP mode. More...

RadioLibTime_t	getLastToA ()
	Get the Time-on-air of the last uplink message (in milliseconds). More...

Public Attributes
bool	TS009 = false
	TS009 Protocol Specification Verification switch (allows FPort 224 and cuts off uplink payload instead of rejecting if maximum length exceeded).

RadioLibTime_t	scanGuard = 10
	Rx window padding in milliseconds according to the spec, the Rx window must be at least enough time to effectively detect a preamble but we pad it a bit on both sides (start and end) to make sure it is wide enough The larger this number the more power will be consumed! So be careful about changing it. For debugging purposes 50 is a reasonable start, but for production devices it should be as low as possible. 0 is a valid time. More...

Detailed Description

LoRaWAN-compatible node (class A device).

Constructor & Destructor Documentation

◆ LoRaWANNode()

LoRaWANNode::LoRaWANNode	(	PhysicalLayer *	phy,
		const LoRaWANBand_t *	band,
		uint8_t	subBand = `0`
	)

Default constructor.

Parameters

phy	Pointer to the PhysicalLayer radio module.
band	Pointer to the LoRaWAN band to use.
subBand	The sub-band to be used (starting from 1!)

Member Function Documentation

◆ activateABP()

int16_t LoRaWANNode::activateABP ( uint8_t initialDr = RADIOLIB_LORAWAN_DATA_RATE_UNUSED )

Join network by restoring ABP session or performing over-the-air activation. In this procedure, all necessary configuration must be provided by the user.

Parameters

initialDr The datarate at which to send the first uplink and any subsequent uplinks (unless ADR is enabled).

Returns: Status Codes

◆ activateOTAA()

int16_t LoRaWANNode::activateOTAA	(	uint8_t	initialDr = `RADIOLIB_LORAWAN_DATA_RATE_UNUSED`,
		LoRaWANJoinEvent_t *	joinEvent = `NULL`
	)

Join network by restoring OTAA session or performing over-the-air activation. By this procedure, the device will perform an exchange with the network server and set all necessary configuration.

Parameters

joinDr The datarate at which to send the join-request and any subsequent uplinks (unless ADR is enabled)

Returns: Status Codes

◆ beginABP()

void LoRaWANNode::beginABP	(	uint32_t	addr,
		uint8_t *	fNwkSIntKey,
		uint8_t *	sNwkSIntKey,
		uint8_t *	nwkSEncKey,
		uint8_t *	appSKey
	)

Set the device credentials and activation configuration.

Parameters

addr	Device address.
fNwkSIntKey	Pointer to the Forwarding network session (LoRaWAN 1.1), NULL for LoRaWAN 1.0.
sNwkSIntKey	Pointer to the Serving network session (LoRaWAN 1.1), NULL for LoRaWAN 1.0.
nwkSEncKey	Pointer to the MAC command network session key NwkSEncKey or network session AES-128 key NwkSKey.
appSKey	Pointer to the application session AES-128 key.

◆ beginOTAA()

void LoRaWANNode::beginOTAA	(	uint64_t	joinEUI,
		uint64_t	devEUI,
		uint8_t *	nwkKey,
		uint8_t *	appKey
	)

Set the device credentials and activation configuration.

Parameters

joinEUI	8-byte application identifier.
devEUI	8-byte device identifier.
nwkKey	Pointer to the network AES-128 key.
appKey	Pointer to the application AES-128 key.

◆ downlink() [1/2]

int16_t LoRaWANNode::downlink ( LoRaWANEvent_t * event = NULL )

Wait for downlink, simplified to allow for simpler sendReceive.

Parameters

event Pointer to a structure to store extra information about the event (fPort, frame counter, etc.). If set to NULL, no extra information will be passed to the user.

Returns: Status Codes

◆ downlink() [2/2]

int16_t LoRaWANNode::downlink	(	uint8_t *	data,
		size_t *	len,
		LoRaWANEvent_t *	event = `NULL`
	)

Wait for downlink from the server in either RX1 or RX2 window.

Parameters

data	Buffer to save received data into.
len	Pointer to variable that will be used to save the number of received bytes.
event	Pointer to a structure to store extra information about the event (fPort, frame counter, etc.). If set to NULL, no extra information will be passed to the user.

Returns: Status Codes

◆ dutyCycleInterval()

RadioLibTime_t LoRaWANNode::dutyCycleInterval	(	RadioLibTime_t	msPerHour,
		RadioLibTime_t	airtime
	)

Calculate the minimum interval to adhere to a certain dutyCycle. This interval is based on the ToA of one uplink and does not actually keep track of total airtime.

Parameters

msPerHour	The maximum allowed duty cycle (in milliseconds per hour).
airtime	The airtime of the uplink.

Returns: Required interval (delay) in milliseconds between consecutive uplinks.

◆ getBufferNonces()

uint8_t * LoRaWANNode::getBufferNonces ( )

Returns the pointer to the internal buffer that holds the LW base parameters.

Returns: Pointer to uint8_t array of size RADIOLIB_LORAWAN_NONCES_BUF_SIZE

◆ getBufferSession()

uint8_t * LoRaWANNode::getBufferSession ( )

Returns the pointer to the internal buffer that holds the LW session parameters.

Returns: Pointer to uint8_t array of size RADIOLIB_LORAWAN_SESSION_BUF_SIZE

◆ getDevAddr()

uint32_t LoRaWANNode::getDevAddr ( )

Returns the DevAddr of the device, regardless of OTAA or ABP mode.

Returns: 4-byte DevAddr

◆ getLastToA()

RadioLibTime_t LoRaWANNode::getLastToA ( )

Get the Time-on-air of the last uplink message (in milliseconds).

Returns: (RadioLibTime_t) time-on-air (ToA) of last uplink message (in milliseconds).

◆ getMacDeviceTimeAns()

int16_t LoRaWANNode::getMacDeviceTimeAns	(	uint32_t *	gpsEpoch,
		uint8_t *	fraction,
		bool	returnUnix = `true`
	)

Returns the network time after requesting a DeviceTime MAC command. Returns 'true' if a network response was successfully parsed. Returns 'false' if there was no network response / parsing failed.

Parameters

gpsEpoch	Number of seconds since GPS epoch (Jan. 6th 1980)
fraction	Fractional-second, in 1/256-second steps
returnUnix	If true, returns Unix timestamp instead of GPS (default true)

Returns: Status Codes

◆ getMacLinkCheckAns()

int16_t LoRaWANNode::getMacLinkCheckAns	(	uint8_t *	margin,
		uint8_t *	gwCnt
	)

Returns the quality of connectivity after requesting a LinkCheck MAC command. Returns 'true' if a network response was successfully parsed. Returns 'false' if there was no network response / parsing failed.

Parameters

margin	Link margin in dB of LinkCheckReq demodulation at gateway side.
gwCnt	Number of gateways that received the LinkCheckReq.

Returns: Status Codes

◆ sendMacCommandReq()

int16_t LoRaWANNode::sendMacCommandReq ( uint8_t cid )

Add a MAC command to the uplink queue. Only LinkCheck and DeviceTime are available to the user. Other commands are ignored; duplicate MAC commands are discarded.

Parameters

cid	ID of the MAC command

Returns: Status Codes

◆ sendReceive() [1/3]

int16_t LoRaWANNode::sendReceive	(	const char *	strUp,
		uint8_t	fPort,
		uint8_t *	dataDown,
		size_t *	lenDown,
		bool	isConfirmed = `false`,
		LoRaWANEvent_t *	eventUp = `NULL`,
		LoRaWANEvent_t *	eventDown = `NULL`
	)

Send a message to the server and wait for a downlink during Rx1 and/or Rx2 window.

Parameters

strUp	C-string that will be transmitted.
fPort	Port number to send the message to.
dataDown	Buffer to save received data into.
lenDown	Pointer to variable that will be used to save the number of received bytes.
isConfirmed	Whether to send a confirmed uplink or not.
eventUp	Pointer to a structure to store extra information about the uplink event (fPort, frame counter, etc.). If set to NULL, no extra information will be passed to the user.
eventDown	Pointer to a structure to store extra information about the downlink event (fPort, frame counter, etc.). If set to NULL, no extra information will be passed to the user.

Returns: Status Codes

◆ sendReceive() [2/3]

int16_t LoRaWANNode::sendReceive	(	uint8_t *	dataUp,
		size_t	lenUp,
		uint8_t	fPort,
		uint8_t *	dataDown,
		size_t *	lenDown,
		bool	isConfirmed = `false`,
		LoRaWANEvent_t *	eventUp = `NULL`,
		LoRaWANEvent_t *	eventDown = `NULL`
	)

Send a message to the server and wait for a downlink during Rx1 and/or Rx2 window.

Parameters

dataUp	Data to send.
lenUp	Length of the data.
fPort	Port number to send the message to.
dataDown	Buffer to save received data into.
lenDown	Pointer to variable that will be used to save the number of received bytes.
isConfirmed	Whether to send a confirmed uplink or not.
eventUp	Pointer to a structure to store extra information about the uplink event (fPort, frame counter, etc.). If set to NULL, no extra information will be passed to the user.
eventDown	Pointer to a structure to store extra information about the downlink event (fPort, frame counter, etc.). If set to NULL, no extra information will be passed to the user.

Returns: Status Codes

◆ sendReceive() [3/3]

int16_t LoRaWANNode::sendReceive	(	uint8_t *	dataUp,
		size_t	lenUp,
		uint8_t	fPort = `1`,
		bool	isConfirmed = `false`,
		LoRaWANEvent_t *	eventUp = `NULL`,
		LoRaWANEvent_t *	eventDown = `NULL`
	)

Send a message to the server and wait for a downlink but don't bother the user with downlink contents.

Parameters

dataUp	Data to send.
lenUp	Length of the data.
fPort	Port number to send the message to.
isConfirmed	Whether to send a confirmed uplink or not.
eventUp	Pointer to a structure to store extra information about the uplink event (fPort, frame counter, etc.). If set to NULL, no extra information will be passed to the user.
eventDown	Pointer to a structure to store extra information about the downlink event (fPort, frame counter, etc.). If set to NULL, no extra information will be passed to the user.

Returns: Status Codes

◆ setADR()

void LoRaWANNode::setADR ( bool enable = true )

Toggle ADR to on or off.

Parameters

enable Whether to disable ADR or not.

◆ setBufferNonces()

int16_t LoRaWANNode::setBufferNonces ( uint8_t * persistentBuffer )

Fill the internal buffer that holds the LW base parameters with a supplied buffer.

Parameters

persistentBuffer Buffer that should match the internal format (previously extracted using getBufferNonces)

Returns: Status Codes

◆ setBufferSession()

int16_t LoRaWANNode::setBufferSession ( uint8_t * persistentBuffer )

Fill the internal buffer that holds the LW session parameters with a supplied buffer.

Parameters

persistentBuffer Buffer that should match the internal format (previously extracted using getBufferSession)

Returns: Status Codes

◆ setDatarate()

int16_t LoRaWANNode::setDatarate ( uint8_t drUp )

Set uplink datarate. This should not be used when ADR is enabled.

Parameters

drUp	Datarate to use for uplinks.

Returns: Status Codes

◆ setDeviceStatus()

void LoRaWANNode::setDeviceStatus ( uint8_t battLevel )

Set device status.

Parameters

battLevel Battery level to set. 0 for external power source, 1 for lowest battery, 254 for highest battery, 255 for unable to measure.

◆ setDutyCycle()

void LoRaWANNode::setDutyCycle	(	bool	enable = `true`,
		RadioLibTime_t	msPerHour = `0`
	)

Toggle adherence to dutyCycle limits to on or off.

Parameters

enable	Whether to adhere to dutyCycle limits or not (default true).
msPerHour	The maximum allowed Time-on-Air per hour in milliseconds (default 0 = maximum allowed for configured band).

◆ setDwellTime()

void LoRaWANNode::setDwellTime	(	bool	enable,
		RadioLibTime_t	msPerUplink = `0`
	)

Toggle adherence to dwellTime limits to on or off.

Parameters

enable	Whether to adhere to dwellTime limits or not (default true).
msPerUplink	The maximum allowed Time-on-Air per uplink in milliseconds (default 0 = maximum allowed for configured band).

◆ setRx2Dr()

int16_t LoRaWANNode::setRx2Dr ( uint8_t dr )

Configure the Rx2 datarate for ABP mode. This should not be needed for LoRaWAN 1.1 as it is configured through the first downlink.

Parameters

dr	The datarate to be used for listening for downlinks in Rx2.

Returns: Status Codes

◆ setTxPower()

int16_t LoRaWANNode::setTxPower ( int8_t txPower )

Configure TX power of the radio module.

Parameters

txPower Output power during TX mode to be set in dBm.

Returns: Status Codes

◆ uplink() [1/2]

int16_t LoRaWANNode::uplink	(	const char *	str,
		uint8_t	fPort,
		bool	isConfirmed = `false`,
		LoRaWANEvent_t *	event = `NULL`
	)

Send a message to the server.

Parameters

str	C-string that will be transmitted.
fPort	Port number to send the message to.
isConfirmed	Whether to send a confirmed uplink or not.
event	Pointer to a structure to store extra information about the event (fPort, frame counter, etc.). If set to NULL, no extra information will be passed to the user.

Returns: Status Codes

◆ uplink() [2/2]

int16_t LoRaWANNode::uplink	(	uint8_t *	data,
		size_t	len,
		uint8_t	fPort,
		bool	isConfirmed = `false`,
		LoRaWANEvent_t *	event = `NULL`
	)

Send a message to the server.

Parameters

data	Data to send.
len	Length of the data.
fPort	Port number to send the message to.
isConfirmed	Whether to send a confirmed uplink or not.
event	Pointer to a structure to store extra information about the event (fPort, frame counter, etc.). If set to NULL, no extra information will be passed to the user.

Returns: Status Codes

Member Data Documentation

◆ scanGuard

RadioLibTime_t LoRaWANNode::scanGuard = 10

Rx window padding in milliseconds according to the spec, the Rx window must be at least enough time to effectively detect a preamble but we pad it a bit on both sides (start and end) to make sure it is wide enough The larger this number the more power will be consumed! So be careful about changing it. For debugging purposes 50 is a reasonable start, but for production devices it should be as low as possible. 0 is a valid time.

500 is the maximum value, but it is not a good idea to go anywhere near that. If you have to go above 50 you probably have a bug somewhere. Check your device timing.

The documentation for this class was generated from the following files:

src/protocols/LoRaWAN/LoRaWAN.h
src/protocols/LoRaWAN/LoRaWAN.cpp

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ LoRaWANNode()

Member Function Documentation

◆ activateABP()

◆ activateOTAA()

◆ beginABP()

◆ beginOTAA()

◆ downlink() [1/2]

◆ downlink() [2/2]

◆ dutyCycleInterval()

◆ getBufferNonces()

◆ getBufferSession()

◆ getDevAddr()

◆ getLastToA()

◆ getMacDeviceTimeAns()

◆ getMacLinkCheckAns()

◆ sendMacCommandReq()

◆ sendReceive() [1/3]

◆ sendReceive() [2/3]

◆ sendReceive() [3/3]

◆ setADR()

◆ setBufferNonces()

◆ setBufferSession()

◆ setDatarate()

◆ setDeviceStatus()

◆ setDutyCycle()

◆ setDwellTime()

◆ setRx2Dr()

◆ setTxPower()

◆ uplink() [1/2]

◆ uplink() [2/2]

Member Data Documentation

◆ scanGuard