Software

The Waspmote device communicates with the LoRaWAN module via UART. So different commands are sent from the microcontroller unit to the module so as to perform different tasks.

Waspmote libraries

Waspmote LoRaWAN files

The files related to the LoRaWAN libraries for these modules are:

WaspLoRaWAN.h
WaspLoRaWAN.cpp

It is mandatory to include the LoRaWAN library when using these modules. So the following line must be added at the beginning of the code:

#include <WaspLoRaWAN.h> or #include <WaspLoRaWAN_Global.h>

The include above will depend on the LoRaWAN module in use.

Class constructor

To start using the Waspmote LoRaWAN library, an object from the WaspLoRaWAN class must be created. This object, called LoRaWAN, is already created by default inside Waspmote LoRaWAN library. It will be usedthrough this guide to show how Waspmote works.

When using the class constructor, all variables are initialized to a default value.

API constants (common)

The API constants used in functions are:

API constants LoRaWAN

Constant

Description

API constants LoRaWAN Global

Constant

Description

API variables

The variables used inside functions and Waspmote codes are:

API functions

Through this guide there are lots of examples of using functions. In these examples, API functions are called to execute the commands, storing in their related variables the parameter value in each case. The functions are called using the predefined object LoRaWAN.

All public functions return one of these possible values:

LORAWAN_ANSWER_OK = 0
LORAWAN_ANSWER_ERROR = 1
LORAWAN_NO_ANSWER = 2
LORAWAN_INIT_ERROR = 3
LORAWAN_LENGTH_ERROR = 4
LORAWAN_SENDING_ERROR = 5
LORAWAN_NOT_JOINED = 6
LORAWAN_INPUT_ERROR = 7
LORAWAN_VERSION_ERROR = 8

Module system management features

Switch on

The ON() function allows to switch on the LoRaWAN module, it opens the MCU UART for communicating with the module and it automatically enters into command mode.

In addition, when the module has been powered and communication is opened, this function checks whethera module is plugged to the socket and which type of module has been plugged. This check is done within every function that reboots the module such as “ON”, “reset” or “factoryReset”.

After this step the module will be able to receive commands to configure it or send packets. It is necessary toindicate the socket that it is being used: SOCKET0 or SOCKET1.

Example of use for SOCKET0:

{
    LoRaWAN.ON(SOCKET0);
}

Related variable:

LoRaWAN._version → Stores the module's version

Switch off

The OFF() function allows the user to switch off the LoRaWAN module and close the UART. This function must be called in order to keep battery level when the module is not going to be managed. It is necessary to indicate the socket that it is being used: SOCKET0 or SOCKET1.

Example of use for SOCKET0:

{
    LoRaWAN.OFF(SOCKET0);
}

Module software reset

The reset() function allows the user to reset and restart the LoRaWAN module. The stored internal configurations will be loaded automatically upon reboot.

Example of use:

{
    LoRaWAN.reset();
}

Related variable:

LoRaWAN._version → Stores the module's version

Module factory reset

The factoryReset() function allows the user to reset the module's configuration data and user EEPROM to factory default values and restart the module.

Example of use:

{
    LoRaWAN.factoryReset();
}

Related variable:

LoRaWAN._version → Stores the module's version

Examples of LoRaWAN configuration: https://development.libelium.com/lorawan-01a-configure-module-eu-in-asia-pac-latam/ https://development.libelium.com/lorawan-01b-configure-module-us-or-au/ https://development.libelium.com/lorawan-global-01-region-configuration/

Preprogrammed unique identifier (EUI)

The getEUI() function allows the user to query the preprogrammed EUI node address from the module. The preprogrammed EUI node address is a read-only value and cannot be changed or erased. It is a global unique 64-bit identifier.

Example of use:

{
    LoRaWAN.getEUI();
}

Related variable:

LoRaWAN._eui → Stores the module's EUI

LoRaWAN parameters

Device EUI

The setDeviceEUI() function allows the user to set the 64-bit hexadecimal number representing the device EUI. There are two function prototypes which are explained below:

No input device EUI is specified, then the preprogrammed EUI is used as the device EUI.
A user-provided device EUI is specified as input.

The getDeviceEUI() function allows the user to query the device EUI which was previously set by the user. The attribute _devEUI permits to access to the settings of the module. The default value is 0000000000000000.

Depending on the network to join, it is needed to configure a random device EUI or a fixed device EUI provided by the back-end. This matter relies on the registering process for new devices in each back-end. For further information please go to “LoRaWAN back-ends” chapter.

Example for preprogrammed EUI:

{
    LoRaWAN.setDeviceEUI();
    LoRaWAN.getDeviceEUI();
}

Example for user-provided device EUI:

{
    LoRaWAN.setDeviceEUI(“0102030405060708”);
    LoRaWAN.getDeviceEUI();
}

Related variable:

LoRaWAN._devEUI → Stores the previously set device EUI

Device address

The setDeviceAddr() function allows the user to set the 32-bit hexadecimal number representing the device address. This address must be unique to the current network. There are two function prototypes which are explained below:

No input device address is specified, then the last 4 bytes of the preprogrammed EUI are set as device address.
A user-provided device address is specified as input.

The getDeviceAddr() function allows the user to query the device address which was previously set by the user. The attribute _devAddr permits to access to the settings of the module. The range goes from 00000000 to FFFFFFFF. The default value is 00000000.

Depending on the network to join, it is possible configure a random device address or a fixed device address.This matter depends on the back-end and the registering process for new devices. For further information please go to “LoRaWAN back-ends” chapter.

Example for using the preprogrammed EUI:

{
    LoRaWAN.setDeviceAddr();
    LoRaWAN.getDeviceAddr();
}

Example for user-provided device address:

{
    LoRaWAN.setDeviceAddr(“01020304”);
    LoRaWAN.getDeviceAddr();
}

Related variable:

LoRaWAN._devAddr → Stores the previously set device address

Application Session Key

The setAppSessionKey() function allows the user to set the 128-bit hexadecimal number representing the application session key.

All payloads are encrypted using an AES algorithm with a 128-bit secret key, the Application Session Key. Each end-device has its own unique Application Session Key only known by the end-device and the application server.

The attribute _appSKeystores the application session key previously set by the user. The range goes from 00000000000000000000000000000000 to FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF.

Example of use:

{
    LoRaWAN.setAppSessionKey(“00102030405060708090A0B0C0D0E0F”);
}

Related variable:

LoRaWAN._appSKey → Stores the previously set application session key

Network session key

The setNwkSessionKey() function allows the user to set the 128-bit hexadecimal number representing the network session key.

All frames contain a 32-bit cryptographic Message Integrity Check (MIC) signature computed using the AES algorithm with a 128-bit secret key, the Network Session Key. Each end-device has its own Network Session Key only known by the end-device and the network server.

The attribute _nwkSKey stores the network session key previously set by the user. The range goes from 00000000000000000000000000000000 to FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF.

Example of use:

{
    LoRaWAN.setNwkSessionKey(“00102030405060708090A0B0C0D0E0F”);
}

Related variable:

LoRaWAN._nwkSKey → Stores the previously set network session key

Application EUI

The setAppEUI() function allows the user to set the 64-bit hexadecimal number representing the application identifier. This parameters is a global application identifier that uniquely identifies the application provider (i.e., owner) of the module.

Example of use:

{
    LoRaWAN.setAppEUI(“1112131415161718”);
}

Related variable:

LoRaWAN._appEUI → Stores the previously set application EUI

Application key

The setAppKey() function allows the user to set the 128-bit hexadecimal number representing the application key. Whenever an end-device joins a network via OTAA, the Application Key is used to derive thesession keys, Network Session Key and Application Session Key, which are specific for that end-device to encrypt and verify network communication and application data.

The attribute _appKeystores the application session key previously set by the user. The range goes from 00000000000000000000000000000000 to FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF.

Example of use:

{
    LoRaWAN.setAppKey(“00102030405060708090A0B0C0D0E0F”);
}

Related variable:

LoRaWAN._appKey → Stores the previously set application key

LoRaWAN module activation

To participate in a LoRaWAN network, each module has to be personalized and activated.

Activation of a module can be achieved in two ways, either via Over-The-Air Activation (OTAA) when an end-device is deployed or reset, or via Activation By Personalization (ABP) in which the two steps of end-device personalization and activation are done as one step.

Over-The-Air Activation (OTAA)

For OTAA, modules must follow a join procedure prior to participating in data exchanges with the network server. A module has to go through a new join procedure every time it has lost the session context information.

The OTAA join procedure requires the module to be personalized with the following information before its starts the join procedure:

Device EUI (64-bit)
Application EUI (64-bit)
Application Key (128-bit)

After joining through OTAA, the module and the network exchanged the Network Session Key and the Application Session Key which are needed to perform communications.

Activation By Personalization (ABP)

Activating a module by ABP means that the device address and the two session keys are directly stored into the module instead of the Device EUI, Application EUI and the Application Key. The module is equipped with the required information for participating in a specific LoRa network when started.

Each module should have a unique set of Network Session Key and Application Session Key. Compromising the keys of one module shouldn‘t compromise the security of the communications of other devices. The process to build those keys should be such that the keys cannot be derived in any way from publicly available information.

The ABP join procedure requires the module to be personalized with the following information before its starts the join procedure:

Device address (32-bit)
Network Session Key (128-bit key) ensures security on network level
Application Session Key (128-bit key) ensures end-to-end security on application level

Join a network

Before sending packets to a gateway, the node must join a network first. The joinABP() function allows theuser to attempt joining the network using thNon-Globalon By Personalization mode (ABP). The joinOTAA()function allows the user to attempt joining the network using the Over the Air Activation mode (OTAA). Beforejoining the network, the specific parameters for activation should be configured depending on the joining procedure.

Join ABP

Before joining the network, the specific parameters for activation should be configured: device EUI, device address, network session key and application session key.

Example of use:

{
    LoRaWAN.joinABP();
}

Join OTAA

Before joining the network, the specific parameters for activation should be configured: device EUI, application EUI and application key.

Example of use:

{
    LoRaWAN.joinOTAA();
}

After joining via OTAA successfully, the module will be able to join the network in ABP mode in future joining procedures. The session keys are stored in module's memory, so it is possible to power down the module and restart it using ABP for joining the network with the previously stored keys.

LoRaWAN mode features

Operational ISM bands

Non Global modules

The resetMacConfig() function allows the user to reset the software LoRaWAN stack and initialize it with the parameters for the selected band: 433 MHz, 868 MHz or 900 MHz.

The getBand() function allows the user to query the current frequency band of operation. This function is not available for the LoRaWAN US and AU modules since they can only work in the 902-928 MHz ISM band for the US version and 915-928 MHz ISM band for the AU version. The attribute _band permits to access to the settings of the module. The default value is 868. This value can be saved into the module's memory with the saveConfig() function due to keep the band configuration after a reboot. Value can be either 433 or 868.

Example of use:

{
    LoRaWAN.resetMacConfig(433);
    LoRaWAN.getBand();
}

Related variable:

LoRaWAN._band → Stores the current frequency band of operation

LoRaWAN Global module

The setBand() function allows the user to configure the module for the selected band: AS923, AU915, EU868, KR920, IN865 or US915.

The getBand() function allows the user to query the current frequency band of operation. The attribute _band permits to access to the settings of the module. The default value is EU868.

Example of use:

{
    LoRaWAN.setBand(AU915);
    LoRaWAN.getBand();
}

Related variable:

LoRaWAN._band → Stores the current frequency band of operation

The setChannelMask() function allows the user to configure the sub-band in certain regions, such as AU915 and US915.

Example of use:

{
    LoRaWAN.setChannelMask(SUB_BAND_0); // Configures channels from 0 to 7 and 64
}

The showChannelConfig() function allows the user to query the current channel frequency configuration. The channel configuration is printed through the serial port and it is available for all the band configurations.

Example of use:

{
    LoRaWAN.showChannelConfig();
    
    //Output
    // Channel number 0	Frequency: 915200000	DRR Min: 0	DRR Max: 5
    // Channel number 1	Frequency: 915400000	DRR Min: 0	DRR Max: l
    // Channel number 2	Frequency: 915600000	DRR Min: 0	DRR Max: 5
    // Channel number 3	Frequency: 915800000	DRR Min: 0	DRR Max: 5
    // Channel number 4	Frequency: 916000000	DRR Min: 0	DRR Max: 5
    // Channel number 5	Frequency: 916200000	DRR Min: 0	DRR Max: 5
    // Channel number 6	Frequency: 916400000	DRR Min: 0	DRR Max: 5
    // Channel number 7	Frequency: 916600000	DRR Min: 0	DRR Max: 5
    // Channel number64 Frequency: 915900000	DRR Min: 6	DRR Max: 6
}

Example of region configuration: https://development.libelium.com/lorawan-global-01-region-configuration/

Send data to a LoRaWAN gateway

Sending unconfirmed packets

The sendUnconfirmed() function allows the user to transmit data on a specified port number. This function will not expect any acknowledgement back from the server. It is necessary to indicate the port to use. The range is from 1 to 223. The second input of the sending function is the payload of the packet to send. The payload must be specified in hexadecimal format as a string.

Example of use:

{
    uint8_t port = 1; 
    char data[] = “010203040506070809”; 
    LoRaWAN.sendUnconfirmed( port, data); 
}

Example of sending a packet without ACK: https://development.libelium.com/lorawan-06-join-abp-send-unconfirmed/ https://development.libelium.com/lorawan-09-join-otaa-send-unconfirmed/ https://development.libelium.com/lorawan-global-04-join-abp-send-unconfirmed/ https://development.libelium.com/lorawan-global-07-join-otaa-send-unconfirmed/

There is a second sendUnconfirmed() function prototype which permits to send a packet defined as an array of bytes. So the function expects three inputs: port, pointer to the data and length of the data.

Example of use:

{
    uint8_t port = 1; 
    uint8_t data[] = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06}; 
    LoRaWAN.sendUnconfirmed( port, data, 6); 
}

Examples of sending a packet using the alternative prototype: https://development.libelium.com/lorawan-08-join-abp-send-frame/ https://development.libelium.com/lorawan-11-join-otaa-send-frame/ https://development.libelium.com/lorawan-global-09-join-otaa-send-frame/ https://development.libelium.com/lorawan-global-11-join-otaa-send-tiny-frame/

The length of the payload capable of being transmitted is dependent upon the set data rate. Please refer to the “Data rate” section for the payload length values.

The sendConfirmed() function allows the user to transmit data on a specified port number. This function will expect an acknowledgement from the server. If no ACK is received, the message will be retransmitted automatically up to a maximum of times specified by the setRetries() function. It is necessary to indicate the port to use. The range is from 1 to 223. The second input of the sending function is the payload of the packet to send. The payload must be specified in hexadecimal format as a string.

Example of use:

{
    uint8_t port = 1;
    char data[] = “010203040506070809”;
    LoRaWAN.sendConfirmed( port, data);
}

Example of sending a packet with ACK: https://development.libelium.com/lorawan-08-join-abp-send-frame/ https://development.libelium.com/lorawan-11-join-otaa-send-frame/ https://development.libelium.com/lorawan-global-05-join-abp-send-confirmed/ https://development.libelium.com/lorawan-global-08-join-otaa-send-confirmed/

The length of the payload capable of being transmitted is dependent upon the set data rate. Please refer to the “Data rate” section for the payload length values.

Receiving data from a LoRaWAN gateway

Note that not every back-end is able to send data to end devices. The back-ends which are able to perform data downlink use the ACK process to send a special ACK frame containing data. So once the user programs a downlink process, this downlink data will be received by the target module the next time it performs a transmission.

There is no specific function to receive data from back-ends in this library. The sendUnconfirmed() and the sendConfirmed() functions check if any special ACK is received and store data if any has been received. In case data has been received, _dataReceived flag will be set to true.

Related variables:

LoRaWAN._port → Stores the port used by the back-ends to send data LoRaWAN._data → Stores the received data LoRaWAN._dataReceived → Data received flag

Save configuration

The saveConfig() function allows the user to save LoRaWAN Class A protocol configuration parameters to the module’s non-volatile memory. This function must be issued after the configuration parameters have been appropriately set.

The LoRaWAN Class A protocol configuration savable parameters are:

Band
Uplink Frame Counter
Downlink Frame Counter
Data Rate
Adaptive Data Rate state
Device EUI
Application EUI
Application Key
Network Session Key
Application Session Key
Device Address
Second receiving window parameters
All Channel Parameter
- Frequency
- Duty Cycle
- Data Rate Range
- Status

There are some exceptions for the LoRaWAN US module, it does not save:

Band, since it does not use this parameter
Data rate
Channel frequency, preset according to specification
Duty cycle, since it does not use this parameter

Example of use:

{
    LoRaWAN.saveConfig();
}

Examples of LoRaWAN configuration: https://development.libelium.com/lorawan-01a-configure-module-eu-in-asia-pac-latam/ https://development.libelium.com/lorawan-01b-configure-module-us-or-au/

The macResume() function allows the user to enable LoRaWAN mode. After switching on the module it is not mandatory to call this function because the default mode upon reboot is LoRaWAN mode. However, if P2P mode was previously set and the user needs to switch back to LoRaWAN mode, then this function must be called. This function is not available for the LoRaWAN JP / KR module.

Example of use:

{
    LoRaWAN.macResume();
}

Power level

The setPower() function allows the user to set the output power to be used on the next transmissions.

The getPower() function allows the user to query the device power index which was previously set by the user. The attribute _powerIndex permits to access to the settings of the module. The range goes from 0 to 5 for the 433 MHz frequency band and from 1 to 5 for the 868 MHz frequency band. LoRaWAN US and LoRaWAN AU power index values can be: 5, 7, 8, 9 or 10. LoRaWAN IN power index values go from 0 to 5. LoRaWAN ASIA-PAC / LATAM power index values go from 0 to 5. LoRaWAN JP / KR power index values go from 0 to 7.

Table: Power levels table (LoRaWAN EU /433 module)

Table: Power levels table (LoRaWAN US and LoRaWAN AU modules)

Table: Power levels table (LoRaWAN IN module MaxEIRP is 18.5 dBm)

Table: Power levels table (LoRaWAN ASIA-PAC / LATAM module MaxEIRP is 18.5 dBm)

Table: Power levels table (LoRaWAN JP / KR (band AS923MHZ Japan) module MaxEIRP is 16 dBm)

Table: Power levels table (LoRaWAN JP / KR (band KR920-923MHz) module MaxEIRP is 14 dBm)

Example of use:

{
    LoRaWAN.setPower(1);
    LoRaWAN.getPower();
}

Related variable:

LoRaWAN._powerIndex → Stores the previously set power

Example of setting power level: https://development.libelium.com/lorawan-03-power-level/ https://development.libelium.com/lorawan-global-02-power-lever/

Adaptive data rate (ADR)

The setADR() function allows the user to enable or disable the adaptive data rate (ADR). The server is informed about the status of the module's ADR. In every uplink frame it receives from ADR field in uplink datapacket. If ADR is enabled, the server will optimize the data rate and the transmission power based on the information collected from the network: the RSSI / SNR of the last received packets.

The getADR() function allows the user to query the device adaptive data rate status. The attribute _adrpermits to access to the settings of the module. This attribute is set to 'true' if ADR is enabled or 'false' if ADRis disabled.

Example of use:

{
    LoRaWAN.setADR(“on”);
    LoRaWAN.setADR(“off”);
    LoRaWAN.getADR();
}

Related variable:

LoRaWAN._adr → Stores the previously set ADR status

Example of setting adaptive data rate: https://development.libelium.com/lorawan-05-adaptive-data-rate/ https://development.libelium.com/lorawan-global-03-data-rate/

Data rate

The setDataRate() function allows the user to set the data rate to be used for the next transmission. The following encoding is used for Data Rate (DR):

Table: Data rates table for the LoRaWAN EU, IN, ASIA-PAC / LATAM and JP / KR modules

Table: Data rates table for the LoRaWAN US and LoRaWAN AU modules

The getDataRate() function allows the user to query the device data rate. The attribute _dataRatepermits to access to the settings of the module.

Example of use:

{
    LoRaWAN.setDatarate(0);
    LoRaWAN.getDataRate();
}

Related variable:

LoRaWAN._dataRate → Stores the previously set data rate

Example of setting data rate: https://development.libelium.com/lorawan-04-data-rate/ https://development.libelium.com/lorawan-global-03-data-rate/

Transmission retries

The setRetries() function allows the user to set the number of retransmissions to be used for an uplink confirmed packet, if no downlink acknowledgment is received from the server.

The getRetries() function allows the user to query the number of retransmissions which was previously set by the user. The attribute _retriespermits to access to the settings of the module. The attribute range is from 0 to 255.

Example of use:

{
    LoRaWAN.setRetries (3);
    LoRaWAN.getRetries ();
}

Related variable:

LoRaWAN._retries → Stores the previously set number of retransmissions

Examples of LoRaWAN configuration: https://development.libelium.com/lorawan-01a-configure-module-eu-in-asia-pac-latam/ https://development.libelium.com/lorawan-01b-configure-module-us-or-au/

Receiving windows

As it has been described in the section “Receiving data from a LoRaWAN gateway”, there is no specific function to receive data. The module is only capable of receiving gateway messages after a transmission hasbeen done from the module during shorts periods of time named receiving windows.

The first receiving window has a fixed data rate and frequency that matches with those used in the last transmission. The setRX1Delay() function allows the user to set the delay between the transmission and the first reception window.

The getRX1Delay() function allows the user to query the delay between the transmission and the first reception window. The attribute _rx1Delaypermits to access to the settings of the module. The attribute range is from 0 to 65535.

The second receiving delay is set internally by the module calculated with the first window delay plus 1000 ms. The setRX2Parameters() function allows the user to set the data rate and frequency that will be usedby the second reception window. The getRX2Delay() function allows the user to query the delay between the transmission and the second reception window.

The attribute _rx2Delaypermits to access to the settings of the module. The attribute range is from 0 to 65535. The getRX2Parameters() function allows the user to query the data rate and frequency used in the second reception window. This function expects a parameter that indicates the band ofthe parameters that are queried: 868 and 433 for the LoRaWAN EU module and 900 fo the LoRaWAN US and LoRaWAN AU modules. The attribute _rx2DataRatepermits to access to the settings of the module. The attribute range is from 0 to 7 for the LoRaWAN EU, LoRaWAN IN and LoRaWAN ASIA-PAC / LATAM modules and 8 to 13 for the LoRaWAN US and LoRaWAN AU modules. The attribute _rx2Frequencypermits to access to the settings of the module. The attribute range is from 863000000 to 870000000 for the 868 band and from 433050000 to 434790000 for the 433 band, in Hz for the LoRaWAN EU and IN modules and from 923300000 to 927500000, for the 900 band, in Hz for the LoRaWAN US, AU and ASIA-PAC / LATAM modules. The attribute range is from 920600000 to 928000000 for the AS923MHz Japan band and from 920900000 to 923300000 for the KR920-923MHz band, in Hz for the LoRaWAN JP / KR module.

Example of use:

{
    LoRaWAN.setRX1Delay(1000); // set a 1000 ms delay
    LoRaWAN.getRX1Delay();
    LoRaWAN.getRX2Delay();
    LoRaWAN.setRX2Parameters(0,864500000); // set DR0 and 864.5 MHz
    LoRaWAN.getRX2Delay(868);
}

Related variable:

LoRaWAN. rx1Delay → Stores the RX1 delay LoRaWAN. rx2Delay → Stores the RX2 delay LoRaWAN. rx2DataRate → Stores the RX2 data rate LoRaWAN. rx2Frequency → Stores the RX2 frequency

Automatic reply (AR)

The setAR() function allows the user to enable or disable the module's automatic reply. By enabling the automatic reply, the module will transmit a packet without a payload immediately after a confirmed downlink is received, or when the Frame Pending bit has been set by the server. If set to OFF, no automatic reply will be transmitted.

The getAR() function allows the user to query the automatic reply status to the module. The attribute _arpermits to access to the settings of the module. This attribute is set to 'true' if AR is enabled or 'false' if AR is disabled.

This parameter cannot be stored in the module's EEPROM using the saveConfig() function. To get to know the previous state of this parameter user can use the attribute _ar.

Example of use:

{
    LoRaWAN.setAR(“on”);
    LoRaWAN.setAR(“off”);
    LoRaWAN.getAR();
}

Related variable:

LoRaWAN._ar → Stores the previously set ADR status

Examples of LoRaWAN configuration: https://development.libelium.com/lorawan-01a-configure-module-eu-in-asia-pac-latam/ https://development.libelium.com/lorawan-01b-configure-module-us-or-au/

Uplink counter

The setUpCounter() function allows the user to set the uplink frame counter that will be used for the next uplink transmission.

The getUpCounter() function allows the user to query the uplink frame counter that will be used for thenext uplink transmission. The attribute _upCounter permits to access the settings of the module. The attribute range is from 0 to 4294967295.

If the back-end's sequence number check is set to strict, this uplink counter must be synchronized with the back-end uplink counter. The _upCounter is saved into the module's memory after every transmission.

Example of use:

{
    LoRaWAN.setUpCounter(10);
    LoRaWAN.getUpCounter();
}

Related variable:

LoRaWAN._upCounter → Stores the previously set uplink frame sequence number

Downlink counter

The setDownCounter() function allows the user to set the downlink frame counter that will be used for the next downlink reception.

The getDownCounter() function allows the user to query the downlink frame counter that will be used for the next downlink reception. The attribute _downCounter permits to access the settings of the module. The attribute range is from 0 to 4294967295.

If the back-end check sequence number function is set to strict, this downlink counter must be synchronized with the back-end downlink counter. The _downCounter is saved into the module's memory after every reception.

Example of use:

{
    LoRaWAN.setDownCounter(10);
    LoRaWAN.getDownCounter();
}

Related variable:

LoRaWAN._downCounter → Stores the previously set downlink frame sequence number

Channel parameters

The LoRaWAN EU module has 16 channels available to be configured. The channel parameters are:

Frequency
Duty cycle
Data rate range
Status

Table: Channel parameters table for LoRaWAN EU

The LoRaWAN US module has 72 channels with a preset fixed frequency for every channel. Data rate rangeand channel status are the only settable parameters.

Table: Channel parameters table for LoRaWAN US

The LoRaWAN AU module has 72 channels with a preset fixed frequency for every channel (like the US model). Data rate range and channel status are the only settable parameters.

Table: Channel parameters table for LoRaWAN AU

The LoRaWAN IN module has 16 channels available to be configured. The channel parameters are:

Frequency
Duty cycle
Data rate range
Status

Table: Channel parameters table for LoRaWAN IN

The LoRaWAN ASIA-PAC / LATAM module has 16 channels available to be configured. The channel parameters are:

Frequency
Duty cycle
Data rate range
Status

Table: Channel parameters table for LoRaWAN ASIA-PAC / LATAM

The LoRaWAN JP / KR module configured in the AS923 MHz Japan band has 16 channels available to be configured. The channel parameters are:

Frequency
Data rate range
Status

Table: Channel parameters table for LoRaWAN JP / KR (band AS923MHz Japan)

The LoRaWAN JP / KR module configured in the KR920-923 MHz band 16 channels available to be configured. The channel parameters are:

Frequency
Data rate range
Status

Table: Channel parameters table for LoRaWAN JP / KR (band KR902-923MHz)

Below you can see how the parameters can be configured.

Channel frequency

The first 3 channels have a fixed frequency value fot the LoRaWAN EU module. The rest of them can be configured in the following ranges: from 863250000 to 869750000 Hz for the 868 MHz band, and from 433050000 to 434790000 Hz for the 433 MHz band. Though frequency is not a settable parameter in LoRaWAN US and LoRaWAN AU modules frequency can be queried with ranges from 902300000 to 914900000 Hz and from 915200000 to 927800000 for each module. Like in the LoRaWAN EU module, the first 3 channels are preconfigured by default for the LoRaWAN JP / KR configured in the KR920-923 MHz band. In the LoRaWAN IN, LoRaWAN ASIA-PAC / LATAM and LoRaWAN JP / KR configured in the AS923 MHz Japan band, only the first 2 channels are preconfigured by default.

The setChannelFreq() function allows the user to set the operational frequency on the given channel number (from 3 to 15). The default channels (0-2) cannot be modified in terms of frequency. This function is not available for LoRaWAN US or LoRaWAN AU modules because channels have a fixed frequency.

The getChannelFreq() function allows the user to query the channel frequency which was previously set by the user. This function can query channels from 0 to 15 when using LoRaWAN EU module and channels from 0 to 71 when using LoRaWAN US or LoRaWAN AU module. The attribute _freqpermits to access to the settings of the module.

Example of use:

{
    LoRaWAN.setChannelFreq(3,868000000);
    LoRaWAN.getChannelFreq(3);
}

Related variable:

LoRaWAN._freq[n] → Stores the previously set frequency for channel 'n'

Example of channel settings configuration: https://development.libelium.com/lorawan-02a-channels-eu-or-in-or-asia-pac-latam/ https://development.libelium.com/lorawan-02b-channels-us-or-au/ https://development.libelium.com/lorawan-global-01-region-configuration/

Channel duty cycle

The setChannelDutyCycle() function allows the user to set the operational duty cycle on the given channel number (from 0 to 15). The duty cycle value that needs to be used as input argument can be obtained from the wanted duty cycle X (in percentage) using the following formula: duty cycle = (100/X) – 1. The default settings consider only the three default channels (0-2), and their default duty cycle is 0.33%. If a new channel is created either by the server or by the user, all the channels (including the default ones) must be updated by the user in terms of duty cycle to comply with the applicable regulations in the country. This function is not available for LoRaWAN US, LoRaWAN AU and LoRaWAN JP / KR modules.

The getChannelDutyCycle() function allows the user to query the channel duty cycle which was previously set by the user. The attribute _dCyclepermits to access to the settings of the module. The attribute range goes from 0 to 65535. The _dCycle value that needs to be configured can be obtained from the actual duty cycle X (in percentage) using the following formula: X = 100/(_dCycle+ 1). This function is not available for LoRaWAN US and LoRaWAN AU modules.

Example of use:

{
    LoRaWAN.setChannelDutyCycle(3,9);
    LoRaWAN.getChannelDutyCycle(3);
}

Related variable:

LoRaWAN._dCycle[n] → Stores the previously set duty cycle for channel 'n'

Example of channel settings configuration: https://development.libelium.com/lorawan-02a-channels-eu-or-in-or-asia-pac-latam/ https://development.libelium.com/lorawan-02b-channels-us-or-au/

Channel data rate range (DRR)

The setChannelDRRange() function allows the user to set the operational data rate range, from minimum to maximum values, for the given channel number.

The LoRaWAN EU, LoRaWAN IN, LoRaWAN ASIA-PAC / LATAM and LoRaWAN JP / KR modules support data rate ranges from 0 to 5 on channels 0 to 15.

The LoRaWAN US and the LoRAWAN AU modules support data rate ranges from 0 to 3 on channels 0 to 63.Channels from 64 to 71 have a fixed data rate range.

The getChannelDRRange() function allows the user to query the data rate range which was previously setby the user. The attributes to store the maximum and minimum data rates are _drrMax and _drrMinrespectively.

Example of use:

{
    LoRaWAN.setChannelDRRange(3,0,6);
    LoRaWAN.getChannelDRRange(3);
}

Related variable:

LoRaWAN._drrMax[n] → Stores the previously set maximum data rate for channel 'n'

LoRaWAN._drrMin[n] → Stores the previously set minimum data rate for channel 'n'

Channel status

The setChannelStatus() function allows the user to set the operation of the given channel, either ”on”or ”off”. This function is not available for the LoRaWAN JP / KR.

LoRaWAN EU, LoRaWAN IN and LoRaWAN ASIA-PAC / LATAM allows to configure the channel status on channels from 0 to 15.

LoRaWAN US and LoRaWAN AU allow to configure the channel status on channels from 0 to 71.

The getChannelStatus() function allows the user to query the operation channel status. The attribute _statuspermits to access to the settings of the module.

Example of use:

{
    LoRaWAN.setChannelStatus(3,”on”);
    LoRaWAN.setChannelStatus(3,”off”);
    LoRaWAN.getChannelStatus(3);
}

Related variable:

LoRaWAN._status[n] → Stores the previously set status for channel 'n'

Duty cycle prescaler

The getDutyCyclePrescaler() function allows the user to query the duty cycle prescaler. The value of the prescaler can be configured only by the server through use of the Duty Cycle Request frame. Upon reception of this command from the server, the duty cycle prescaler is changed for all enabled channels. Theattribute _dCyclePS permits to access to the settings of the module.

Example of use:

{
    LoRaWAN.getDutyCyclePrescaler();
}

Related variable:

LoRaWAN._dCyclePS → Stores the duty cycle prescaler established by the server

Margin

The getMargin() function allows the user to query the demodulation margin as received in the last Link Check Answer frame. The attribute _margin permits to access to the settings of the module.

Example of use:

{
    LoRaWAN.getMargin();
}

Related variable:

LoRaWAN._margin → Stores the margin received in the last Link Check Answer frame

Gateway number

The getGatewayNumber() function allows the user to query the number of gateways that successfully received the last Link Check Request frame command, as received in the last Link Check Answer. The attribute _gwNumber permits to access to the settings of the module.

Example of use:

{
    LoRaWAN.getGatewayNumber();
}

Related variable:

LoRaWAN._gwNumber → Stores the number of gateways that received the last Link Check Request frame

P2P mode – Direct communication between nodes

This feature is only available for the LoRaWAN module, the LoRaWAN Global module can only communicate with LoRaWAN gateways using the LoRaWAN communication protocol.

Enable P2P mode

The macPause() function allows the user to disable LoRaWAN mode and enable P2P mode. After power reboot, the module's default mode is LoRaWAN. So, it is mandatory to call this function in order to work with the P2P mode. After calling this function, all P2P functions explained in this section will be able to be run.

Example of use:

{
    LoRaWAN.macPause();
}

Send data

The sendRadio() function allows the user to transmit data using the radio transceiver. This function will notexpect any acknowledgement back from the receiver. The maximum length of the frame is 255 bytes (510 ASCII digits).

Example of use:

{
    char data[] = “010203040506070809”;
    
    LoRaWAN.macPause();
    LoRaWAN.sendRadio(data);
}

Receive data

The receiveRadio() function allows the user to receive data using the radio transceiver. This function needs a timeout parameter to keep the module listening for any data. The range for this timeout input parameter is from 0 ms to 4294967295 ms. If any data frame is received, it is stored in _buffer. The length of the buffer is specified in _length. The user must keep in mind that this buffer structure is used for all functions in the API. So, the packet contents should be stored in a program buffer for being used after reception.

Example of use:

{
    uint32_t time = 10000;
    
    LoRaWAN.macPause();
    LoRaWAN.receiveRadio(time);
}

Related variable:

LoRaWAN._buffer → Stores data received through radio transceiver LoRaWAN._length → Stores length of the data stored in _buffer

Power level

The setRadioPower() function allows the user to set the operating output power in P2P mode.

The getRadioPower() function allows the user to query the operating output power level in P2P mode which was previously set by the user. The attribute _radioPowerpermits to access to the settings of the module.

The range of this attribute goes from -3 to 15 for the LoRaWAN EU module.

The range of this attribute goes from 2 to 20 for the LoRaWAN US and LoRaWAN AU modules.

The output power level in dBm can be consulted in the radio transceiver module datasheet:

RN2483 to see about LoRaWAN EU
RN2903 to see about LoRaWAN US, LoRaWAN AU, LoRaWAN IN and LoRaWAN ASIA-PAC / LATAM
CMWX1ZZABZ to see about LoRaWAN JP / KR

Example of use:

{
    LoRaWAN.setRadioPower(3);
    LoRaWAN.getRadioPower();
}

Related variable:

LoRaWAN._radioPower → Stores the previously set output power level

Spreading Factor

The setRadioSF() function allows the user to set the operating spreading factor (SF) in P2P mode.

The getRadioSF() function allows the user to query the operating Spreading Factor (SF) in P2P mode which was previously set by the user. The attribute _radioSFpermits to access to the settings of the module. The spreading factor can take the following values: “sf7”, “sf8”, “sf9”, “sf10”, “sf11” and “sf12”.

Example of use:

{
    LoRaWAN.setRadioSF(“sf7”);
    LoRaWAN.getRadioSF();
}

Related variable:

LoRaWAN._radioSF → Stores the previously set Spreading Factor

Frequency deviation

The setRadioFreqDeviation() function allows the user to set the frequency deviation during operation in P2P mode.

The getRadioFreqDeviation() function allows the user to query the operating frequency deviation which was previously set by the user. The attribute _radioFreqDevpermits to access to the settings of the module. The frequency deviation range goes from 0 to 200000.

Example of use:

{
    LoRaWAN.setRadioFreqDeviation(5000);
    LoRaWAN.getRadioFreqDeviation();
}

Related variable:

LoRaWAN._radioFreqDev → Stores the previously set frequency deviation

Preamble length

The setRadioPreamble() function allows the user to set the preamble length for transmit/receive in P2P mode.

The getRadioPreamble() function allows the user to query the preamble length which was previously set by the user. The attribute _preambleLengthpermits to access to the settings of the module. The preamble length range goes from 0 to 65535.

Example of use:

{
    LoRaWAN.setRadioPreamble(8);
    LoRaWAN.getRadioPreamble();
}

Related variable:

LoRaWAN._preambleLength → Stores the previously set preamble length

CRC header

The setRadioCRC() function allows the user to set the Cyclic Redundancy Check (CRC) header status for transmit/receive in P2P mode.

The getRadioCRC() function allows the user to query the CRC status which was previously set by the user. The attribute _crcStatuspermits to access to the settings of the module. This attribute is set to ”on” ifCRC is enabled or ”off” if CRC is disabled.

Example of use:

{
    LoRaWAN.setRadioCRC(“on”);
    LoRaWAN.setRadioCRC(“off”);
    LoRaWAN.getRadioCRC();
}

Related variable:

LoRaWAN._crcStatus → Stores the previously set CRC status

Coding Rate

The setRadioCR() function allows the user to set the Coding Rate (CR) for communications in P2P mode.

The getRadioCR() function allows the user to query the CR which was previously set by the user. The attribute _radioCRpermits to access to the settings of the module. The CR can take the following values: “4/5”, “4/6”, “4/7” and “4/8”.

Example of use:

{
    LoRaWAN.setRadioCR(“4/5”);
    LoRaWAN.getRadioCR();
}

Related variable:

LoRaWAN._radioCR → Stores the previously set coding rate

Bandwidth

The setRadioBandwidth() function allows the user to set the operating radio bandwidth (BW) for LoRa operation.

The getRadioBandwidth() function allows the user to query radio bandwidth which was previously set bythe user. The attribute _radioBWpermits to access to the settings of the module. The radio bandwidth can take the following values: 125 kHz, 250 kHz and 500 kHz.

Example of use:

{
    LoRaWAN.setRadioBandwidth(250);
    LoRaWAN.getRadioBandwidth();
}

Related variable:

LoRaWAN._radioBW → Stores the previously set radio bandwidth

Frequency

The setRadioFrequency() function allows the user to set the communication frequency of the radio transceiver.

The getRadioFrequency() function allows the user to query radio frequency which was previously set by the user. The attribute _radioFreqpermits to access to the settings of the module.

When using the LoRaWAN EU or the LoRaWAN IN module, the operation frequency can take values from 433250000 to 434550000 or from 863250000 to 869750000, for the 433 and 868 MHz bands.

When using the LoRaWAN US or the LoRaWAN AU module, the operation frequency can take values from 902000000 to 928000000.

When using the LoRaWAN ASIA-PAC / LATAM module, the operation frequency can take values from 919000000 to 928000000.

Example of use:

{
    LoRaWAN.setRadioFrequency(868100000);
    LoRaWAN.getRadioFrequency();
}

Related variable:

LoRaWAN._radioFreq → Stores the previously set communication frequency

Signal to noise ratio (SNR)

The getRadioSNR() function allows the user to query the Signal to Noise Ratio (SNR) for the last received packet. The attribute _radioSNRpermits to access to the settings of the module. The SNR can take values from -127 to 128.

Example of use:

{
    LoRaWAN.getRadioSNR();
}

Related variable:

LoRaWAN._radioSNR → Stores the previously set communication frequency

Hybrid LoRaWAN / P2P mode

It is possible to set up hybrid networks using both Radio and LoRaWAN protocols. Therefore, several nodes can use a P2P star topology to reach a central node which will access to the LoRaWAN network to route the information. The basis of this operation is that the central node listens to P2P packets and sends them to the LoRaWAN infrastructure. See the following diagram to understand this hybrid network:

The user must keep in mind that there is a mismatch between the maximum payload in P2P networks (255 bytes) and LoRaWAN networks (242 bytes). Therefore, the central node will be able to resend all received frames from the other P2P nodes. The following example shows how to operate as a central node sending data of the incoming P2P packets to the LoRaWAN network: https://development.libelium.com/lorawan-p2p-04-hybrid-p2p-lorawan/

PreviousHardware NextLoRaWAN back-ends

Last updated 1 year ago