# RadioLib: LoRaWANNode Class Reference

LoRaWANNode Class Reference

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...
uint64_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. 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).

## 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()

uint64_t LoRaWANNode::getDevAddr | ( |  | ) |

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

Returns
  8-byte DevAddr

## getLastToA()

RadioLibTime_t LoRaWANNode::getLastToA | ( |  | ) |

Get the Time-on-air of the last uplink message.

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

## 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

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

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