Waspmote Lorawan Networking Guide
Waspmote Lorawan Networking Guide
Networking Guide
Index
INDEX
1. Introduction.......................................................................................................................................... 4
1.1. Technology overview...................................................................................................................................................................7
2. Hardware............................................................................................................................................... 8
2.1. Specifications.................................................................................................................................................................................8
2.2. Power consumption.....................................................................................................................................................................9
2.3. Time consumption........................................................................................................................................................................9
2.4. Expansion Radio Board............................................................................................................................................................ 10
3. Software.............................................................................................................................................. 11
3.1. Waspmote libraries.................................................................................................................................................................... 11
3.1.1. Waspmote LoRaWAN files........................................................................................................................................11
3.1.2. Class constructor.........................................................................................................................................................11
3.1.3. API constants................................................................................................................................................................11
3.1.4. API variables..................................................................................................................................................................12
3.1.5. API functions.................................................................................................................................................................13
3.2. Module system management features.............................................................................................................................. 13
3.2.1. Switch on........................................................................................................................................................................13
3.2.2. Switch off........................................................................................................................................................................14
3.2.3. Module software reset...............................................................................................................................................14
3.2.4. Module factory reset..................................................................................................................................................14
3.2.5. Preprogrammed unique identifier (EUI).............................................................................................................14
3.3. LoRaWAN mode features........................................................................................................................................................ 15
3.3.1. Operational ISM bands..............................................................................................................................................15
3.3.2. Send data to a LoRaWAN gateway........................................................................................................................15
3.3.3. Receiving data from a LoRaWAN gateway.........................................................................................................17
3.3.4. Join a network..............................................................................................................................................................17
3.3.5. Save configuration......................................................................................................................................................18
3.3.6. Enable LoRaWAN mode............................................................................................................................................18
3.3.7. Device EUI......................................................................................................................................................................19
3.3.8. Device address.............................................................................................................................................................19
3.3.9. Application session key.............................................................................................................................................20
3.3.10. Network session key................................................................................................................................................21
3.3.11. Application key..........................................................................................................................................................22
3.3.12. Power level..................................................................................................................................................................22
3.3.13. Adaptive data rate (ADR).......................................................................................................................................23
3.3.14. Data rate.......................................................................................................................................................................23
3.3.15. Transmission retries.................................................................................................................................................24
-2- v4.2
Index
4. LoRaWAN back-ends.......................................................................................................................... 34
4.1. Actility............................................................................................................................................................................................ 34
4.1.1. Device registration......................................................................................................................................................34
4.1.2. Waspmote programming.........................................................................................................................................35
4.2. OrbiWise........................................................................................................................................................................................ 35
4.2.1. Device registration......................................................................................................................................................35
4.2.2. Data downlink..............................................................................................................................................................37
4.2.3. Waspmote programming.........................................................................................................................................37
4.3. LORIOT........................................................................................................................................................................................... 38
4.3.1. Device registration......................................................................................................................................................38
4.3.2. Data downlink..............................................................................................................................................................40
4.3.3. Waspmote programming.........................................................................................................................................40
6. Certifications....................................................................................................................................... 42
8. API changelog..................................................................................................................................... 49
9. Documentation change..................................................................................................................... 50
-3- v4.2
Introduction
1. Introduction
The Libelium LoRaWAN module has been integrated into the main sensor lines Waspmote OEM and Plug & Sense!, so now you
can create your own Low Power Wide Area Network (LPWAN).
LoRaWAN is a new, private and spread-spectrum modulation technique which allows sending data at extremely low data-rates
to extremely long ranges. The low data-rate (down to few bytes per second) and LoRaWAN modulation lead to very low receiver
sensitivity (down to -136 dBm), which combined to an output power of +14 dBm means extremely large link budgets: up to
150 dB, what means more than 22 km (13.6 miles) in LOS links and up to 2 km (1.2 miles) in NLOS links in urban environment
(going through buildings).
Libelium’s LoRaWAN current module works in both 868 and 433 MHz ISM bands (900 MHz version for US is coming in 2016),
which makes it suitable for virtually any country. Those frequency bands are lower than the popular 2.4 GHz band, so path
loss attenuation is better in LoRaWAN. In addition, 868 and 433 MHz are bands with much fewer interference than the highly
populated 2.4 GHz band. Besides, these low frequencies provide great penetration in possible materials (brick walls, trees,
concrete), so these bands get less loss in the presence of obstacles than higher band.
With the LoRaWAN modules we can send the data directly to any Base Station (BS) that is LoRaWAN compatible. Some
companies already offering solutions are: Kerlink, Link-Labs, Multitech, Cisco, Augtek, Manthink, Gupsy, Gemteck, ExpEmb,
Embedded Planet, Calao, RFI, etc. In order to visualize the information we will need also a Cloud platform where the data has
to be sent. Normally when you acquire a BS you can install your preferred SW packet in order to make it work against the
Cloud platform. We tested the LoRaWAN radios with three Cloud platforms: Actility, Orbiwise and Loriot, you can find more
information about the configuration in this tutorial.
-4- v4.2
Introduction
Libelium currently offers two options of this type of radio technology: LoRa and LoRaWAN
•• LoRa contains only the link layer protocol and is perfect to be used in P2P communications between nodes. LoRa modules
are a little cheaper that the LoRaWAN ones.
•• LoRaWAN includes the network layer too so it is possible to send the information to any Base Station already connected to
a Cloud platform. LoRaWAN modules may work in different frequencies by just connecting the right antenna to its socket.
As well as the LoRaWAN to Base Station mode, the modules may be used in two different more configurations.
•• P2P Mode - Direct Communication between nodes (LAN Interface)
•• Hybrid Mode - LoRaWAN / P2P (P2P + GW to LoRaWAN Network)
•• In the P2P Mode nodes may connect directly among them and send messages directly at no cost (as they are not using the
LoRaWAN Network but just direct radio communication). This is useful as we can create secondary networks at any time as
we don’t need to change the firmware but just use specific AT Commands in the current library. This mode works without
the need of a Base Station or a Cloud account so in case you don’t want to purchase any license (or renew the license
after the initial period) you will be able to keep on using the modules this way. For more info go to the section P2P Mode.
In the Hybrid Mode we use a combination of the LoRaWAN and P2P modes allowing to send just certain messages using the
LoRaWAN Network. In this case we use one node as GW of the network (P2P + LoRaWAN mode) and the rest of the nodes in P2P
mode. This mode may work using just one LoRaWAN License. For more info go to the section Hybrid Mode.
-5- v4.2
Introduction
Libelium offers two types of sensor platforms: Waspmote OEM and Plug & Sense!.
•• Waspmote OEM is intended to be used for research purposes or as part of a major product so it needs final certification on
the client side. More info at: http://www.libelium.com/products/waspmote/
•• Plug & Sense! is the line ready to be used out of the box. It includes market certifications. See below the specific list of
regulations passed. http://www.libelium.com/products/plug-sense/
In accordance with the 1999/5/EC (R&TTE) and the EU Directive 2011/65/EU (RoHS2), Libelium Comunicaciones Distribuidas S.L.
declares that the “Plug & Sense! LoRaWAN 868” device conforms to the following regulations:
Plug & Sense! Sigfox 900 / 915 is certified for the US (FCC) and Canada (IC). Specifically under the Part 15 Spread Spectrum
Transmitter (FCC Rule Part 15 C) and the Industry Canada Regulation (IC) - (RSS-210) respectively.
-6- v4.2
Introduction
LoRaWAN network architecture is typically laid out in a star-of-stars topology in which gateways is a transparent bridge relaying
messages between end-devices and a central network server in the back-end. Gateways are connected to the network server
via standard IP connections while end-devices use single-hop wireless communication to one or many gateways.
Communication between end-devices and gateways is spread out on different frequency channels and data rates. The
selection of the data rate is a trade-off between communication range and message duration. Due to the spread spectrum
technology, communications with different data rates do not interfere with each other and create a set of “virtual” channels
increasing the capacity of the gateway. To maximize both battery life of the end-devices and overall network capacity, the
LoRaWAN network server is managing the data rate and RF output for each end-device individually by means of an adaptive
data rate (ADR) scheme.
National wide networks targeting internet of things such as critical infrastructure, confidential personal data or critical functions
for the society has a special need for secure communication. This has been solved by several layer of encryption:
-7- v4.2
Hardware
2. Hardware
2.1. Specifications
The LoRaWAN module is managed by UART and it can be connected to SOCKET0 or SOCKET1. The main features of the modules
are listed below:
Figure: LoRaWAN module with normal antenna Figure: LoRaWAN module with 0 dBi antenna
Note: This module only works in the 868 and 433 MHz bands. The 900-915 MHz band version will be released by the beginning of
2016. The 900 MHz version does not support operation on the 433 MHz band. The user must check the allowed bands, channels
and transmission power, in order to respect the regulations in the operation country.
Libelium commercializes different items depending on the band the user wants to use: 868 or 433. The module is the same,
but the antenna is different for each band. The module for 868 and 433 MHz includes 2 RP-SMA connectors for the antenna.
One is for the 868 band and the other for the 433 band. A sticker on the bottom of the modules specifies clearly where to
screw the antenna.
-8- v4.2
Hardware
Note: The LoRaWAN module is provided with a special antenna (for 433 or for 868 MHz), which enables maximum range. The
only exception is Smart Parking; in this case the antenna is smaller, to fit inside the enclosure.
Note: Due to the propagation characteristics of the sub-GHz bands, the near field effect could make that 2 modules cannot
communicate if they are placed very close (< 1 m). We suggest to keep a minimum distance of 3 or 4 meters between modules.
These periods of time depend on the data rate set which is defined by the spreading factor and signal bandwidth configured.
Note: When transmitting in ISM frequency bands, the user must ensure that the communication is not exceeding the permitted
time using the chosen frequency channel (for example, 1% of time). This depends on the local regulations (CE, FCC, etc). It is the
responsibility of the user to know the allowed time of use in the occupied frequency band and respect it. Ignoring this, could lead
to considerable penalties. Also, a LoRaWAN back-end operator could cut off the service or apply extra fees, it they detect that the
user is exceeding the maximum number of frames or data in a period of time.
-9- v4.2
Hardware
Remark: GPRS Pro, GPRS+GPS and 3G/GPRS modules do not need the Expansion Board to be connected to Waspmote. They can be
plugged directly in the SOCKET1.
In the next photo you can see the sockets available along with the UART assigned. On one hand, SOCKET0 allows to plug any
kind of radio module through the UART0. On the other hand, SOCKET1 permits to connect a radio module through the UART1.
The API provides a function called ON() in order to switch the module on. This function supports a parameter which permits to
select the SOCKET. It is possible to choose between SOCKET0 and SOCKET1.
The rest of functions are used the same way as they are used with older API versions. In order to understand them we recommend
to read this guide.
-10- v4.2
Software
WARNING:
•• Avoid to use DIGITAL7 pin when working with Expansion Board. This pin is used for setting the XBee into sleep.
•• Avoid to use DIGITAL6 pin when working with Expansion Board. This pin is used as power supply for the Expansion Board.
•• Incompatibility with Sensor Boards:
-- Gases Board: Incompatible with SOCKET4 and NO2/O3 sensor.
-- Agriculture Board: Incompatible with Sensirion and the atmospheric pressure sensor.
-- Smart Metering Board: Incompatible with SOCKET11 and SOCKET13.
-- Smart Cities Board: Incompatible with microphone and the CLK of the interruption shift register.
-- Events Board: Incompatible with interruption shift register.
3. 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.
WaspLoRaWAN.h
WaspLoRaWAN.cpp
It is mandatory to include the LoRaWAN library when using this module. So the following line must be added at the beginning
of the code:
#include <WaspLoRaWAN.h>
When using the class constructor, all variables are initialized to a default value.
Constant Description
LORAWAN_ANSWER_OK Successful response to a function
LORAWAN_ANSWER_ERROR Erratic response to a function
LORAWAN_NO_ANSWER No response to a function
LORAWAN_INIT_ERROR Required keys to join to a network were not initialized
LORAWAN_LENGTH_ERROR Data to be sent length limit exceeded
LORAWAN_SENDING_ERROR Server did not response
LORAWAN_NOT_JOINED Module has not joined a network
-11- v4.2
Software
Constant Description
_buffer The buffer of memory used for storing the responses from the module
_length The useful length of the buffer
_def_delay The time to wait after sending every command until listen for a response
_baudrate The baudrate to be used when the module is switched on
_uart The selected UART (regarding the socket used: SOCKET0 or SOCKET1)
_adr The adaptive data rate state (on or off )
The buffer used for storing the preprogrammed globally unique identifier
_eui
from the module's hardware
The buffer used for storing the globally unique identifier for the module
_devEUI
(software programmable)
_appEUI The buffer used for storing the application identifier for the module
_nwkSKey The buffer used for storing the network session key for the module
_appSKey The buffer used for storing the application session key for the module
_appKey The buffer used for storing the application key for the module
_devAddr The buffer used for storing network device address for module
_band The buffer used for storing the frequency band
_margin The demodulation margin received in the last Link Check Answer frame
The number of gateways successfully received the last Link Check Answer
_gwNumber
frame
_freq The buffer used for storing the operating frequency for every channel
_radioFreq The transceiver operating frequency
_radioFreqDev The transceiver frequency deviation
_preambleLength The preamble length for transceiver
_dCycle The buffer used for storing the operating duty cycle for every channel
_drrMin The minimum operating data rate range for every channel
_drrMax The maximum operating data rate range for every channel
_dCyclePS The duty cycle prescaler (which can only be configured by the server)
_crcStatus The CRC status to determine if it is to be included during operation
_powerIndex The output power to be used on LoRaWAN transmissions
_dataRate The data rate to be used on LoRaWAN transmissions
_retries The number of retransmissions for an uplink
_upCounter The value of the uplink frame counter
_downCounter The value of the downlink frame counter
_radioPower The output power level used by the transceiver
_radioSF The spreading factor to be used by the transceiver
_radioRxBW The receiving bandwidth used by the transceiver
_radioCR The coding rate used by the transceiver
_radioWDT The time to be used by the transceiver watchdog timer
_radioBW The value used for the transceiver bandwidth
-12- v4.2
Software
_radioSNR The SNR value for the last received packet by the transceiver
_status The status of every LoRaWAN channel
_data The buffer of memory used for storing data received from the back-end
_port The port where data was received
_dataReceived The flag used to inform if any data was received
•• LORAWAN_ANSWER_OK = 0
•• LORAWAN_ANSWER_ERROR = 1
•• LORAWAN_NO_ANSWER = 2
•• LORAWAN_INIT_ERROR = 3
•• LORAWAN_DATA_LENGTH_ERROR = 4
•• LORAWAN_SENDING_ERROR = 5
•• LORAWAN_NOT_JOINED = 6
{
LoRaWAN.ON(SOCKET0);
}
-13- v4.2
Software
{
LoRaWAN.OFF(SOCKET0);
}
Example of use:
{
LoRaWAN.reset();
}
Example of use:
{
LoRaWAN.factoryReset();
}
Example of use:
{
LoRaWAN.getEUI();
}
Related variable:
-14- v4.2
Software
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 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:
-15- v4.2
Software
Example of use:
{
uint8_t port = 1;
char data[] = “010203040506070809”;
Example of use:
{
uint8_t port = 1;
char data[] = “010203040506070809”;
-16- v4.2
Software
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:
•• 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();
}
-17- v4.2
Software
•• 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
•• All Channel Parameter
-- Frequency
-- Duty Cycle
-- Data Rate Range
-- Status
Example of use:
{
LoRaWAN.saveConfig();
}
Example of use:
{
LoRaWAN.macResume();
}
-18- v4.2
Software
No input device EUI is specified, then the preprogrammed EUI is used as the device EUI.
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.
{
LoRaWAN.setDeviceEUI();
LoRaWAN.getDeviceEUI();
}
{
LoRaWAN.setDeviceEUI(“0102030405060708”);
LoRaWAN.getDeviceEUI();
}
Related variable:
No input device address is specified, then the last 4 bytes of the preprogrammed EUI are set as device address.
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.
-19- v4.2
Software
{
LoRaWAN.setDeviceAddr();
LoRaWAN.getDeviceAddr();
}
{
LoRaWAN.setDeviceAddr(“01020304”);
LoRaWAN.getDeviceAddr();
}
Related variable:
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 _appSKey stores the application session key previously set by the user. The range goes from 0000000000000000
0000000000000000 to FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF.
Example of use:
LoRaWAN.setAppSessionKey(“00102030405060708090A0B0C0D0E0F”);
-20- v4.2
Software
Related variable:
www.libelium.com/development/waspmote/examples/lorawan-01-configure
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 0000000000000000000
0000000000000 to FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF.
Example of use:
{
LoRaWAN.setNwkSessionKey(“00102030405060708090A0B0C0D0E0F”);
}
Related variable:
-21- v4.2
Software
The attribute _appKey stores the application session key previously set by the user. The range goes from 00000000000000000
000000000000000 to FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF.
Example of use:
{
LoRaWAN.setAppKey(“00102030405060708090A0B0C0D0E0F”);
}
Related variable:
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.
Power Index Power Level (868 MHz) Power Level (433 MHz)
0 N/A 10 dBm
1 14 dBm 7 dBm
2 11 dBm 4 dBm
3 8 dBm 1 dBm
4 5 dBm -2 dBm
5 2 dBm -5 dBm
Example of use:
{
LoRaWAN.setPower(1);
LoRaWAN.getPower();
}
Related variable:
-22- v4.2
Software
The getADR() function allows the user to query the device adaptive data rate status. The attribute _adr permits to access to
the settings of the module. This attribute is set to ‘true’ if ADR is enabled or ‘false’ if ADR is disabled.
Example of use:
{
LoRaWAN.setADR(“on”);
LoRaWAN.setADR(“off”);
LoRaWAN.getADR();
}
Related variable:
The getDataRate() function allows the user to query the device data rate. The attribute _dataRate permits to access to the
settings of the module.
Example of use:
{
LoRaWAN.setDatarate(0);
LoRaWAN.getDataRate();
}
Related variable:
-23- v4.2
Software
The getRetries() function allows the user to query the number of retransmissions which was previously set by the user. The
attribute _retries permits 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:
The getUpCounter() function allows the user to query the uplink frame counter that will be used for the next 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:
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.
-24- v4.2
Software
Example of use:
LoRaWAN.setDownCounter(10);
LoRaWAN.getDownCounter();
Related variable:
•• Frequency
•• Duty cycle
•• Data rate range
•• Status
Frequency band
Channel Number Parameters
868 433
Frequency (Hz) 868100000 433175000
Duty cycle 302 302
Channel 0
Data rate range 0-5 0-5
Status On On
Frequency (Hz) 868300000 433375000
Duty cycle 302 302
Channel 1
Data rate range 0-5 0-5
Status On On
Frequency (Hz) 868500000 433575000
Duty cycle 302 302
Channel 2
Data rate range 0-5 0-5
Status On On
Frequency (Hz) 0 0
Duty cycle 65535 65535
Channel 3 - 15
Data rate range 15 -15 15- 15
Status Off Off
-25- v4.2
Software
•• Channel frequency
The first three channels have a fixed frequency value. 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.
The setChannelFreq() function allows the user to set the operational frequency on the given channel number (from 0 to 15).
The default channels (0-2) cannot be modified in terms of frequency.
The getChannelFreq() function allows the user to query the channel frequency which was previously set by the user. The
attribute _freq permits to access to the settings of the module.
Example of use:
{
LoRaWAN.setChannelFreq(3,868000000);
LoRaWAN.getChannelFreq(3);
}
Related variable:
The getChannelDutyCycle() function allows the user to query the channel duty cycle which was previously set by the user.
The attribute _dCycle permits 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).
Example of use:
{
LoRaWAN.setChannelDutyCycle(3,9);
LoRaWAN.getChannelDutyCycle(3);
}
Related variable:
LoRaWAN._dCycle[n] → Stores the previously set duty cycle for channel ‘n’
-26- v4.2
Software
The getChannelDRRange() function allows the user to query the data rate range which was previously set by the user. The
attributes to store the maximum and minimum data rates are _drrMax and _drrMin respectively. For both values the range
goes from 0 to 7.
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”.
The getChannelStatus() function allows the user to query the operation channel status. The attribute _status permits to access
to the settings of the module.
Example of use:
{
LoRaWAN.setChannelStatus(3,”on”);
LoRaWAN.setChannelStatus(3,”off”);
LoRaWAN.getChannelStatus(3);
}
Related variable:
-27- v4.2
Software
Example of use:
{
LoRaWAN.getDutyCyclePrescaler();
}
Related variable:
LoRaWAN._dCyclePS → Stores the duty cycle prescaler established by the server
3.3.20. 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
Example of use:
{
LoRaWAN.getGatewayNumber();
}
Related variable:
LoRaWAN._gwNumber → Stores the number of gateways that received the last Link Check Request frame
-28- v4.2
Software
Example of use:
{
LoRaWAN.macPause();
}
Example of use:
{
char data[] = “010203040506070809”;
LoRaWAN.macPause();
LoRaWAN.sendRadio(data);
}
Example of use:
{
uint32_t time = 10000;
LoRaWAN.macPause();
LoRaWAN.receiveRadio(time);
}
Related variable:
-29- v4.2
Software
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 _radioPower permits to access to the settings of the module. The range of this attribute goes
from -3 to 14 dBm.
Example of use:
{
LoRaWAN.setRadioPower(3);
LoRaWAN.getRadioPower();
}
Related variable:
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 _radioSF permits 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:
The getRadioFreqDeviation() function allows the user to query the operating frequency deviation which was previously
set by the user. The attribute _radioFreqDev permits to access to the settings of the module. The frequency deviation range
goes from 0 to 65535.
Example of use:
{
LoRaWAN.setRadioFreqDeviation(5000);
LoRaWAN.getRadioFreqDeviation();
}
Related variable:
-30- v4.2
Software
The getRadioPreamble() function allows the user to query the preamble length which was previously set by the user. The
attribute _preambleLength permits 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:
The getRadioCRC() function allows the user to query the CRC status which was previously set by the user. The attribute _
crcStatus permits to access to the settings of the module. This attribute is set to ”on” if CRC is enabled or ”off” if CRC is disabled.
Example of use:
{
LoRaWAN.setRadioCRC(“on”);
LoRaWAN.setRadioCRC(“off”);
LoRaWAN.getRadioCRC();
}
Related variable:
The getRadioCR() function allows the user to query the CR which was previously set by the user. The attribute _radioCR
permits 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:
-31- v4.2
Software
3.4.10. 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 by the user. The attribute
_radioBW permits 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:
3.4.11. 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 _radioFreq permits to access to the settings of the module. The radio bandwidth can take values from 433250000 to
434550000 or from 863250000 to 869750000.
Example of use:
{
LoRaWAN.setRadioFrequency(868100000);
LoRaWAN.getRadioFrequency();
}
Related variable:
Example of use:
{
LoRaWAN.getRadioSNR();
}
Related variable:
-32- v4.2
Software
The user must keep in mind that there is a mismatch between the maximum payload in P2P networks (255 bytes) and LoRaWAN
networks (292 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:
www.libelium.com/development/waspmote/examples/lorawan-p2p-04-hybrid-p2p-to-lorawan
-33- v4.2
LoRaWAN back-ends
4. LoRaWAN back-ends
LoRaWAN network architecture is typically laid out in a star-of-stars topology in which a gateway is a transparent bridge relaying
messages between end-devices and a central network server in the back-end.
4.1. Actility
The ThingPark Wireless Device Manager is the back-end User Interface (UI) which allows you to manage all of your LoRaWAN
devices.
This Guide will provide the guidelines on the entire GUI, the device provisioning, device configuration and management, alarm
and routing profile management and connectivity plan association.
The Device Manager can be fully integrated into a third party customer UI, through all the ThingPark Wireless OSS REST API.
These parameters match with the ones which must be configured in the ThingPark Actility Portal (back-end).
-34- v4.2
LoRaWAN back-ends
Both NwkSKey and AppSKey will be configured by the user in the Actility Portal and set into the end-device. These keys are not
shown in the ThingPark Wireless Device Manager once they have been configured so it is strongly recommended to set them
into the end-device before configuring the end-device creation in the Actility Portal.
About DevEUI and DevAddr, there are two ways to configure it into the module with Waspmote.
•• On one hand they may be set by user manually. When using thivs method always keep in mind they must be unique for
every module.
•• On the other and they can be configured automatically by Waspmote. This method uses the preprogrammed by
manufacturer module’s identifier, that matches DevEUI length, ensuring it will be unique. DevAddr will be extracted
from this manufacturer module’s identifier taking its last 32 bit. E.g., Microchip Module: EUI: 0004A30B001A836D, DevEUI:
0004A30B001A836D, DevAddr: 001A836D.
Examples of setting configuration necessary to connect into a network and send packets:
www.libelium.com/development/waspmote/examples/lorawan-02-send-unconfirmed
www.libelium.com/development/waspmote/examples/lorawan-03-send-confirmed
4.2. OrbiWise
OrbiWise introduces its comprehensive UbiQ core network solution for Low-Power Wide-Area (LPWA) networks taking full
advantage of LoRaTM bidirectional communication technology.
LPWA networks are of special interest to wireless operators, utilities and industrial companies that want to serve many
applications in the Internet-of-Things domain with a single low-cost infrastructure.
OrbiWise’s UbiQ solution enables the deployment of such infrastructure from city-scale to nation-wide coverage with seamless
expansion and support for millions of connected objects. Furthermore, UbiQ’s O&M tool suite allows operations and maintenance
of the entire network from a single web-based graphical user interface.
Optional information:
•• Application EUI (AppEUI)
•• Comment (Cloud API device’s identifier)
•• Application Session Key (AppSKey)
-35- v4.2
LoRaWAN back-ends
•• Always have in mind to select the Personalized Registration Type. Despite AppSKey is an optional parameter to create the
device in the server, it is mandatory to be configured in the module. In any case, it is always better to set an AppSKey both
in server and module (same for both) so data can be decrypted by server.
-36- v4.2
LoRaWAN back-ends
Examples of setting configuration necessary to connect into a network and send packets:
www.libelium.com/development/waspmote/examples/lorawan-02-send-unconfirmed
www.libelium.com/development/waspmote/examples/lorawan-03-send-confirmed
-37- v4.2
LoRaWAN back-ends
4.3. LORIOT
LORIOT.io is a provider of a LoRaWAN Network Server and Application Server software, which is commercially offered through
a set of business models.
They provide:
As a gateway owner, users can use LORIOT.io software on gateways to connect them to their cloud. From then on, all data
received by the gateways will be relayed to the user through the LORIOT.io APIs or 3rd party services.
The network server components fulfills to role of protocol processor. It is a TLS connection end-point for the gateways and the
customer applications. It is responsible for processing the incoming end node data according to the LoRaWAN protocol.
-38- v4.2
LoRaWAN back-ends
When a new device is generated in the LORIOT.io portal these parameters are provided. The user will have to configure the
module according to these parameters.
Once the device is created you can access to its configuration and data clicking over the Device EUI field with the mouse. Data
messages can be seen there.
-39- v4.2
LoRaWAN back-ends
To perform data downlinks click on the “Send data” button and the “Send to device” section will be displayed. In this section,
Device EUI, port number and data payload to send must be filled. Finally, the “Send to device” button will enqueue the data to
be downloaded. Data will be received by the module after the next data uplink. It does not matter if the next uplink process is
confirmed or unconfirmed, the downlink will be performed.
The mandatory field to field are the ones which where mentioned in the previous section. They can be copied as is to the code
so module is configured the same way it was created in the portal.
Inside the device description in the LORIOT.io portal they warn to copy EUI and Address in little endian format, but it won’t be
necessary for the Waspmote code, it can be copied big endian format.
Examples of setting configuration necessary to connect into a network and send packets:
www.libelium.com/development/waspmote/examples/lorawan-02-send-unconfirmed
www.libelium.com/development/waspmote/examples/lorawan-03-send-confirmed
-40- v4.2
When is LoRaWAN recommended?
•• LoRaWAN is not advised for projects with a duty-cycle which require sending one frame every few minutes.
•• The downlink data rate is very low too, so OTA programming is not possible.
•• LoRaWAN is NOT recommended for real time streaming. Transmission is not done in real time as there is a minimum delay
for packet arrival.
•• LoRaWAN is recommended for long-range device communications in cities, where base stations by some LoRaWAN
operator are deployed, so the user can take advantage of this infrastructure.
•• Otherwise, the user can purchase his own LoRaWAN-compliant gateways and deploy a private LoRaWAN network for a
specific project.
-41- v4.2
Certifications
6. Certifications
Libelium offers two types of sensor platforms: Waspmote OEM and Plug & Sense!.
•• Waspmote OEM is intended to be used for research purposes or as part of a major product so it needs final certification on
the client side. More info at: http://www.libelium.com/products/waspmote/
•• Plug & Sense! is the line ready to be used out of the box. It includes market certifications. See below the specific list of
regulations passed. http://www.libelium.com/products/plug-sense/
CE
In accordance with the 1999/5/EC (R&TTE) and the EU Directive 2011/65/EU (RoHS2), Libelium Comunicaciones Distribuidas S.L.
declares that the “Plug & Sense! LoRaWAN 868” device conforms to the following regulations:
If desired, the Declaration of Conformity document can be requested using the Contact section at:
http://www.libelium.com/contact
-42- v4.2
Certifications
FCC
Plug & Sense! LoRaWAN 900 / 915 is ready for US. It has been certified under the Part 15 Spread Spectrum Transmitter (FCC Rule
Part 15 C). If you want to know more contact the Libelium Sales Department.
IC
Plug & Sense! LoRaWAN 900 / 915 is ready for Canada. It has been certified under the Industry Canada Regulation (IC) - (RSS-
210). If you want to know more contact the Libelium Sales Department.
-43- v4.2
Code examples and extended information
www.libelium.com/development/waspmote/examples
Example:
/*
* ------ LoRaWAN Code Example --------
*
* Explanation: This example shows how to configure the module
* and all general settings related to back-end registration
* process.
*
* Copyright (C) 2015 Libelium Comunicaciones Distribuidas S.L.
* http://www.libelium.com
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* Version: 0.1
* Design: David Gascon
* Implementation: Luismi Marti
*/
#include <WaspLoRaWAN.h>
//////////////////////////////////////////////
uint8_t socket = SOCKET0;
//////////////////////////////////////////////
// variable
uint8_t error;
void setup()
{
USB.ON();
USB.println(F(“LoRaWAN example - Module configuration”));
//////////////////////////////////////////////
// 1. switch on
//////////////////////////////////////////////
-44- v4.2
Code examples and extended information
error = LoRaWAN.ON(socket);
// Check status
if( error == 0 )
{
USB.println(F(“1. Switch ON OK”));
}
else
{
USB.print(F(“1. Switch ON error = “));
USB.println(error, DEC);
}
//////////////////////////////////////////////
// 2. Reset to factory default values
//////////////////////////////////////////////
error = LoRaWAN.factoryReset();
// Check status
if( error == 0 )
{
USB.println(F(“2. Reset to factory default values OK”));
}
else
{
USB.print(F(“2. Reset to factory error = “));
USB.println(error, DEC);
}
//////////////////////////////////////////////
// 3. Set/Get Device EUI
//////////////////////////////////////////////
// Check status
if( error == 0 )
{
USB.println(F(“3.1. Set Device EUI OK”));
}
else
{
USB.print(F(“3.1. Set Device EUI error = “));
USB.println(error, DEC);
}
// Check status
if( error == 0 )
{
USB.print(F(“3.2. Get Device EUI OK. “));
USB.print(F(“Device EUI: “));
USB.println(LoRaWAN._devEUI);
}
else
{
USB.print(F(“3.2. Get Device EUI error = “));
USB.println(error, DEC);
}
-45- v4.2
Code examples and extended information
//////////////////////////////////////////////
// 4. Set/Get Device Address
//////////////////////////////////////////////
// Check status
if( error == 0 )
{
USB.println(F(“4.1. Set Device address OK”));
}
else
{
USB.print(F(“4.1. Set Device address error = “));
USB.println(error, DEC);
}
// Check status
if( error == 0 )
{
USB.print(F(“4.2. Get Device address OK. “));
USB.print(F(“Device address: “));
USB.println(LoRaWAN._devAddr);
}
else
{
USB.print(F(“4.2. Get Device address error = “));
USB.println(error, DEC);
}
//////////////////////////////////////////////
// 5. Set Network Session Key
//////////////////////////////////////////////
error = LoRaWAN.setNwkSessionKey(NWK_SESSION_KEY);
// Check status
if( error == 0 )
{
USB.println(F(“5. Set Network Session Key OK”));
}
else
{
USB.print(F(“5. Set Network Session Key error = “));
USB.println(error, DEC);
}
//////////////////////////////////////////////
// 6. Set Application Session Key
//////////////////////////////////////////////
error = LoRaWAN.setAppSessionKey(APP_SESSION_KEY);
// Check status
if( error == 0 )
{
USB.println(F(“6. Set Application Session Key OK”));
-46- v4.2
Code examples and extended information
}
else
{
USB.print(F(“6. Set Application Session Key error = “));
USB.println(error, DEC);
}
//////////////////////////////////////////////
// 7. Set retransmissions for uplink confirmed packet
//////////////////////////////////////////////
// set retries
error = LoRaWAN.setRetries(7);
// Check status
if( error == 0 )
{
USB.println(F(“7.1. Set Retransmissions for uplink confirmed packet OK”));
}
else
{
USB.print(F(“7.1. Set Retransmissions for uplink confirmed packet error = “));
USB.println(error, DEC);
}
// Get retries
error = LoRaWAN.getRetries();
// Check status
if( error == 0 )
{
USB.print(F(“7.2. Get Retransmissions for uplink confirmed packet OK. “));
USB.print(F(“TX retries: “));
USB.println(LoRaWAN._retries, DEC);
}
else
{
USB.print(F(“7.2. Get Retransmissions for uplink confirmed packet error = “));
USB.println(error, DEC);
}
//////////////////////////////////////////////
// 8. Set application key
//////////////////////////////////////////////
error = LoRaWAN.setAppKey(APP_KEY);
// Check status
if( error == 0 )
{
USB.println(F(“8. Application key set OK”));
}
else
{
USB.print(F(“8. Application key set error = “));
USB.println(error, DEC);
}
//////////////////////////////////////////////
// 9. Save configuration
//////////////////////////////////////////////
error = LoRaWAN.saveConfig();
-47- v4.2
Code examples and extended information
// Check status
if( error == 0 )
{
USB.println(F(“9. Save configuration OK”));
}
else
{
USB.print(F(“9. Save configuration error = “));
USB.println(error, DEC);
}
USB.println(F(“------------------------------------”));
USB.println(F(“Now the LoRaWAN module is ready for”));
USB.println(F(“joining networks and send messages.”));
USB.println(F(“Please check the next examples...”));
USB.println(F(“------------------------------------\n”));
void loop()
{
// do nothing
}
-48- v4.2
API changelog
8. API changelog
Keep track of the software changes on this link:
-49- v4.2
Documentation change
9. Documentation change
From v4.1 to v4.2:
•• New API constants, API variables and function responses were added
•• Added section for the operational ISM bands
•• The data downlink process is explained, from the module point of view and from some back-ends point of view
•• More details about the ABP and OTAA processes
•• More details about the Application Session Key, the Network Session Key and the Application Key
•• Added sections for the downlink counter and the uplink counter
-50- v4.2