Libelium Waspmote LoRaWAN User manual

Waspmote LoRaWAN
Networking Guide

-2- v7.6
Index
Document Version: v7.6 - 10/2019
© Libelium Comunicaciones Distribuidas S.L.
INDEX
1. Introduction .......................................................................................................................... 5
1.1. Technology overview ........................................................................................................................ 9
2. Hardware .............................................................................................................................10
2.1. Specications................................................................................................................................... 10
2.1.1. LoRaWAN EU........................................................................................................................10
2.1.2. LoRaWAN US........................................................................................................................11
2.1.3. LoRaWAN AU .......................................................................................................................12
2.1.4. LoRaWAN IN ........................................................................................................................13
2.1.5. LoRaWAN ASIA-PAC / LATAM ............................................................................................14
2.1.6. LoRaWAN JP / KR ................................................................................................................15
2.2. Region standards ............................................................................................................................ 16
2.3. Power consumption........................................................................................................................ 17
2.3.1. LoRaWAN EU........................................................................................................................17
2.3.2. LoRaWAN US........................................................................................................................17
2.3.3. LoRaWAN AU........................................................................................................................17
2.3.4. LoRaWAN IN.........................................................................................................................17
2.3.5. LoRaWAN ASIA-PAC / LATAM .............................................................................................18
2.3.6. LoRaWAN JP / KR .................................................................................................................18
2.4. Time consumption.......................................................................................................................... 19
2.5. How to connect the module .......................................................................................................... 19
2.6. Expansion Radio Board .................................................................................................................. 20
3. Software............................................................................................................................... 22
3.1. Waspmote libraries......................................................................................................................... 22
3.1.1. Waspmote LoRaWAN les..................................................................................................22
3.1.2. Class constructor.................................................................................................................22
3.1.3. API constants .......................................................................................................................22
3.1.4. API variables.........................................................................................................................23
3.1.5. API functions........................................................................................................................24
3.2. Module system management features ........................................................................................ 25
3.2.1. Switch on ..............................................................................................................................25
3.2.2. Switch o..............................................................................................................................26
3.2.3. Module software reset........................................................................................................26
3.2.4. Module factory reset...........................................................................................................26
3.2.5. Preprogrammed unique identier (EUI)...........................................................................26
3.3. LoRaWAN parameters .................................................................................................................... 27

-3- v7.6
Index
3.3.1. Device EUI.............................................................................................................................27
3.3.2. Device address.....................................................................................................................27
3.3.3. Application Session Key......................................................................................................28
3.3.4. Network session key ...........................................................................................................29
3.3.5. Application EUI.....................................................................................................................30
3.3.6. Application key ....................................................................................................................30
3.4. LoRaWAN module activation......................................................................................................... 31
3.4.1. Over-The-Air Activation (OTAA)..........................................................................................31
3.4.2. Activation By Personalization (ABP) ..................................................................................31
3.4.3. Join a network......................................................................................................................31
3.5. LoRaWAN mode features............................................................................................................... 33
3.5.1. Operational ISM bands.......................................................................................................33
3.5.2. Send data to a LoRaWAN gateway....................................................................................33
3.5.3. Receiving data from a LoRaWAN gateway .......................................................................35
3.5.4. Save conguration ..............................................................................................................36
3.5.5. Power level...........................................................................................................................37
3.5.6. Adaptive data rate (ADR) ....................................................................................................39
3.5.7. Data rate...............................................................................................................................40
3.5.8. Transmission retries ...........................................................................................................41
3.5.9. Receiving windows ..............................................................................................................41
3.5.10. Automatic reply (AR) .........................................................................................................42
3.5.11. Uplink counter...................................................................................................................43
3.5.12. Downlink counter..............................................................................................................43
3.5.13. Channel parameters .........................................................................................................44
3.5.14. Duty cycle prescaler..........................................................................................................50
3.5.15. Margin.................................................................................................................................50
3.5.16. Gateway number...............................................................................................................50
3.6. P2P mode – Direct communication between nodes .................................................................. 50
3.6.1. Enable P2P mode ................................................................................................................50
3.6.2. Send data .............................................................................................................................51
3.6.3. Receive data.........................................................................................................................51
3.6.4. Power level...........................................................................................................................51
3.6.5. Spreading Factor .................................................................................................................52
3.6.6. Frequency deviation............................................................................................................52
3.6.7. Preamble length ..................................................................................................................52
3.6.8. CRC header ..........................................................................................................................53
3.6.9. Coding Rate..........................................................................................................................53
3.6.10. Bandwidth..........................................................................................................................53
3.6.11. Frequency...........................................................................................................................54
3.6.12. Signal to noise ratio (SNR)................................................................................................54
3.7. Hybrid LoRaWAN / P2P mode ....................................................................................................... 55
4. LoRaWAN back-ends........................................................................................................... 56
4.1. Waspmote recommended conguration..................................................................................... 56

-4- v7.6
4.1.1. LoRaWAN EU........................................................................................................................56
4.1.2. LoRaWAN US........................................................................................................................56
4.1.3. LoRaWAN AU........................................................................................................................57
4.1.4. LoRaWAN IN.........................................................................................................................57
4.1.5. LoRaWAN ASIA-PAC / LATAM .............................................................................................57
4.1.6. LoRaWAN JP / KR .................................................................................................................58
4.2. Actility ............................................................................................................................................... 59
4.2.1. Device registration ..............................................................................................................59
4.2.2. Waspmote programming ...................................................................................................61
4.3. LORIOT ............................................................................................................................................. 62
4.3.1. Device registration ..............................................................................................................62
4.3.2. Data downlink......................................................................................................................64
4.3.3. Waspmote programming ...................................................................................................64
4.4. The Things Network........................................................................................................................ 65
5. When is LoRaWAN recommended?...................................................................................66
6. Certications ....................................................................................................................... 67
7. Code examples and extended information .....................................................................68
8. API changelog ...................................................................................................................... 76
9. Documentation changelog ................................................................................................ 77
Index

-5- v7.6
Introduction
1. Introduction
This guide explains the LoRaWAN modules features and functions. These products were designed for Waspmote
v12 and Plug & Sense! v12 and continue with no changes for Waspmote v15 and Plug & Sense! v15. There are
no great variations in this library for our new product lines Waspmote v15 and Plug & Sense! v15, released on
October 2016.
Anyway, if you are using previous versions of our products, please use the corresponding guides, available on our
Development website.
You can get more information about the generation change on the document “New generation of Libelium product
lines”.
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).
Figure: Waspmote LoRaWAN
Libelium’s LoRaWAN EU/433 module works in both 868 and 433 MHz ISM bands and the LoRaWAN US module
works in 900 MHz ISM band, which makes them 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, 433, 868 and
900 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 bands.

-6- v7.6
Introduction
With the LoRaWAN modules we can send the data directly to any Base Station (BS) that is LoRaWAN compatible.
Some companies already oering 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 nd more information about the conguration in this tutorial.
Figure: LoRaWAN network
Libelium currently oers two options of this type of radio technology: LoRa (“raw”) and LoRaWAN:
•LoRa contains only the link layer protocol and is perfect to be used in P2P communications between nodes.
You can set a topology of a maximum of 10 nodes to the same Gateway as LoRa does not make packet
management.
•LoRaWAN can handle hundreds of connections at the same time.
•LoRaWAN includes the network layer too so it is possible to send the information to any LoRaWAN Base
Station already connected to a Cloud platform. LoRaWAN modules may work in the 868/900/433 MHz bands.
•LoRa is available for the Waspmote OEM v15 platform but not for Plug & Sense! v15.
•LoRaWAN is available for both Waspmote OEM v15 and Plug & Sense! v15.
•Plug & Sense! with LoRaWAN radio is certied for Europe (CE), USA (FCC) and Canada (IC), while LoRa is not
certied.
As well as the LoRaWAN to Base Station mode, the modules may be used in two dierent more congurations.
•P2P Mode - Direct Communication between nodes (LAN Interface)
•Hybrid Mode - LoRaWAN / P2P (P2P + GW to LoRaWAN Network)

-7- v7.6
Introduction
•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 rmware but just use specic 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.
Figure: 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.
Figure: P2P mode

-8- v7.6
Introduction
Important:
•All documents and any examples they contain are provided as-is and are subject to change without notice.
Except to the extent prohibited by law, Libelium makes no express or implied representation or warranty of
any kind with regard to the documents, and specically disclaims the implied warranties and conditions of
merchantability and tness for a particular purpose.
•The information on Libelium’s websites has been included in good faith for general informational purposes
only. It should not be relied upon for any specic purpose and no representation or warranty is given as to its
accuracy or completeness.

-9- v7.6
Introduction
1.1. Technology overview
LoRaWAN is a Low Power Wide Area Network (LPWAN) specication intended for wireless battery operated
devices in regional, national or global network. LoRaWAN target key requirements of Internet of things such
as secure bi-directional communication, mobility and localization services. This standard will provide seamless
interoperability among smart Things without the need of complex local installations and gives back the freedom
to the user, developer, businesses enabling the role out of Internet of Things.
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 dierent frequency channels and data
rates. The selection of the data rate is a trade-o between communication range and message duration. Due to
the spread spectrum technology, communications with dierent 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, condential personal data or
critical functions for the society has a special need for secure communication. This has been solved by several
layer of encryption:
•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
•Application Key (128-bit key) ensures end-to-end security on application level (only OTAA procedure)
Figure: LoRaWAN security overview

-10- v7.6
Hardware
2. Hardware
2.1. Specications
The LoRaWAN module is managed via UART and it can be connected to SOCKET0 or SOCKET1.
2.1.1. LoRaWAN EU
The main features of the module are listed below:
•Manufacturer: Microchip
•Model: RN2483
•Protocol: LoRaWAN 1.0, Class A
•LoRaWAN-ready
•Frequency: EU 863-870 MHz and EU 433 MHz ISM frequency bands.
•TX power: up to +14 dBm
•Sensitivity: down to -136 dBm
•Range: >15 km at suburban and >5 km at urban area. Typically, each base
station covers some km. Check the LoRaWAN Network in your area.
•Chipset consumption: 38.9 mA
•Radio bit rate: from 250 to 5470 bps
•Receiver: purchase your own base station or use networks from LoRaWAN operators
Figure: LoRaWAN EU module with antenna
Figure: LoRaWAN EU module

-11- v7.6
Hardware
2.1.2. LoRaWAN US
The main features of the module are listed below:
•Manufacturer: Microchip
•Model: RN2903
•Protocol: LoRaWAN 1.0, Class A
•LoRaWAN-ready
•Frequency: US 902-928 MHz ISM band
•TX power: up to +18.5 dBm
•Sensitivity: down to -136 dBm
•Range: >15 km at suburban and >5 km at urban area. Typically, each base
station covers some km. Check the LoRaWAN Network in your area.
•Chipset consumption: 124.4 mA
•Radio bit rate: from 250 to 12500 bps
•Receiver: purchase your own base station or use networks from LoRaWAN operators
Figure: LoRaWAN US module with antenna
Figure: LoRaWAN US module

-12- v7.6
Hardware
2.1.3. LoRaWAN AU
The main features of the module are listed below:
•Manufacturer: Microchip
•Model: RN2903
•Protocol: LoRaWAN 1.0.1, Class A
•LoRaWAN-ready
•Frequency: AU 915-928 MHz ISM band
•TX power: up to +18.5 dBm
•Sensitivity: down to -136 dBm
•Range: >15 km at suburban and >5 km at urban area. Typically, each base
station covers some km. Check the LoRaWAN Network in your area.
•Chipset consumption: 124.4 mA
•Radio bit rate: from 250 to 12500 bps
•Receiver: purchase your own base station or use networks from LoRaWAN operators
Figure: LoRaWAN AU module with antenna
Figure: LoRaWAN AU module

-13- v7.6
Hardware
2.1.4. LoRaWAN IN
The main features of the module are listed below:
•Manufacturer: Microchip
•Model: RN2903
•Protocol: LoRaWAN 1.0.1, Class A
•LoRaWAN-ready
•Frequency: IN 865-867 MHz ISM band
•TX power: up to +18.5 dBm
•Sensitivity: down to -136 dBm
•Range: >15 km at suburban and >5 km at urban area. Typically, each base
station covers some km. Check the LoRaWAN Network in your area.
•Chipset consumption: 124.4 mA
•Radio bit rate: from 250 to 12500 bps
•Receiver: purchase your own base station or use networks from LoRaWAN operators
Figure: LoRaWAN IN module with antenna
Figure: LoRaWAN IN module

-14- v7.6
Hardware
2.1.5. LoRaWAN ASIA-PAC / LATAM
The main features of the module are listed below:
•Manufacturer: Microchip
•Model: RN2903
•Protocol: LoRaWAN 1.0.1, Class A
•LoRaWAN-ready
•Frequency: AS 923 MHz ISM band
•TX power: up to +18.5 dBm
•Sensitivity: down to -136 dBm
•Range: >15 km at suburban and >5 km at urban area. Typically, each base
station covers some km. Check the LoRaWAN Network in your area.
•Chipset consumption: 124.4 mA
•Radio bit rate: from 250 to 12500 bps
•Receiver: purchase your own base station or use networks from LoRaWAN operators
Figure: LoRaWAN ASIA-PAC / LATAM module with antenna
Note: The user must check the allowed bands, channels and transmission power, in order to respect the regulations
in the operation country.
Libelium commercializes dierent items depending on the band the user wants to use. In the case of 868 and 433,
the module is the same, but the antenna is dierent for each band. The module for EU (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 species clearly where to screw the antenna.
Note: Any LoRaWAN module is provided with a special antenna (for 433 or for 868 or for 900 MHz), which enables
maximum range.
Note: Due to the propagation characteristics of the sub-GHz bands, the near eld eect 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.
Figure: LoRaWAN AU module

-15- v7.6
Hardware
2.1.6. LoRaWAN JP / KR
The main features of the module are listed below:
•Manufacturer: Murata
•Model: CMWX1ZZABZ
•Protocol: LoRaWAN 1.0.1, Class A
•LoRaWAN-ready
•Frequency: AS 923 MHz ISM band and KR 920-923 MHz ISM band
•TX power: up to +16 dBm
•Sensitivity: down to -135.5 dBm
•Range: >15 km at suburban and >5 km at urban area.
Typically, each base station covers some km.
Check the LoRaWAN Network in your area.
•Chipset consumption: 96.7 mA
•Radio bit rate: from 250 to 5470 bps
•Receiver: purchase your own base station or use networks from LoRaWAN operators
Figure: Bottom of the LoRaWAN JP / KR and module with antenna
Note: The user must check the allowed bands, channels and transmission power, in order to respect the regulations
in the operation country.
Libelium commercializes dierent items depending on the band the user wants to use. In the case of 868 and 433,
the module is the same, but the antenna is dierent for each band. The module for EU (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 species clearly where to screw the antenna.
Note: Any LoRaWAN module is provided with a special antenna (for 433 or for 868 or for 900 MHz or for 916 MHz
[JP / KR]), which enables maximum range
Figure: LoRaWAN JP / KR module

-16- v7.6
Hardware
Note: Due to the propagation characteristics of the sub-GHz bands, the near eld eect 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.
2.2. Region standards
The LoRaWAN Specication settled by the LoRa Alliance establishes the parameters that must be complied for
every region. Check the compatibility table below, showing the areas supported by our LoRaWAN versions for the
moment.
Region Supported by
EU 863-870 MHz ISM Band (Europe) LoRaWAN EU
US 902-928 MHz ISM Band (United States) LoRaWAN US
CN 779-787 MHz ISM Band (China) Not supported
AU 915-928 MHz ISM Band (Australia) LoRaWAN AU
CN 470-510 MHz ISM Band (China) Not supported
AS 923 MHz ISM Band (ASEAN) LoRaWAN ASIA-PAC / LATAM
AS 923 MHz ISM Band (ASEAN)
LoRaWAN ASIA-PAC / LATAM
LoRaWAN JP / KR (special for Japan)
KR 920-923 MHz ISM Band (South Korea) LoRaWAN JP / KR
INDIA 865-867 ISM Band (India) LoRaWAN IN
Figure: Regional compatibility table

-17- v7.6
Hardware
2.3. Power consumption
2.3.1. LoRaWAN EU
The LoRaWAN EU module is powered at 3.3 V. The next table shows the module’s average current consumption
in dierent states of the module.
State Power Consumption
On 2.8 mA
Transmitting data 38.9 mA
Receiving data 14.2 mA
Figure: Power consumption table
2.3.2. LoRaWAN US
The LoRaWAN US module is powered at 3.3 V. The next table shows the module’s average current consumption
in dierent states of the module.
State Power Consumption
On 2.7 mA
Transmitting data 124.4 mA
Receiving data 13.5 mA
Figure: Power consumption table
2.3.3. LoRaWAN AU
The LoRaWAN AU module is powered at 3.3 V. The next table shows the module’s average current consumption
in dierent states of the module.
State Power Consumption
On 2.7 mA
Transmitting data 124.4 mA
Receiving data 13.5 mA
Figure: Power consumption table
2.3.4. LoRaWAN IN
The LoRaWAN IN module is powered at 3.3 V. The next table shows the module’s average current consumption
in dierent states of the module.
State Power Consumption
On 2.7 mA
Transmitting data 124.4 mA
Receiving data 13.5 mA
Figure: Power consumption table

-18- v7.6
Hardware
2.3.5. LoRaWAN ASIA-PAC / LATAM
The LoRaWAN ASIA-PAC / LATAM module is powered at 3.3 V. The next table shows the module’s average current
consumption in dierent states of the module.
State Power Consumption
On 2.7 mA
Transmitting data 124.4 mA
Receiving data 13.5 mA
Figure: Power consumption table
2.3.6. LoRaWAN JP / KR
The LoRaWAN JP / KR module is powered at 3.3 V. The next table shows the module’s average current consumption
in dierent states of the module.
State Power Consumption
On 1.1 mA
Transmitting data 96.1 mA
Receiving data 27 mA
Figure: Power consumption table

-19- v7.6
Hardware
2.4. Time consumption
The elapsed periods dened in this chapter take into account the following steps depending on the case:
•Join to a network and send unconrmed data
•Join to a network and send conrmed data
These periods of time depend on the data rate set which is dened by the spreading factor and signal bandwidth
congured.
Transmit mode Time elapsed
Send unconrmed at 5470 bps ~ 2.8 seconds
Send unconrmed at 250 bps ~ 4.2 seconds
Send conrmed at 5470 bps ~ 1.7 seconds
Send conrmed at 250 bps ~ 4.2 seconds
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 o 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.
2.5. How to connect the module
This module can be connected to both SOCKET0 and SOCKET1 on the Waspmote board.
Figure: Module connected to Waspmote in SOCKET0
In order to connect the module to the SOCKET1, the user must use the Expansion Radio Board.

-20- v7.6
Hardware
2.6. Expansion Radio Board
The Expansion Board allows to connect two communication modules at the same time in the Waspmote sensor
platform. This means a lot of dierent combinations are possible using any of the wireless radios available for
Waspmote: 802.15.4, ZigBee, DigiMesh, 868 MHz, 900 MHz, LoRa, WiFi, GPRS, GPRS+GPS, 3G, 4G, Sigfox, LoRaWAN,
Bluetooth Pro, Bluetooth Low Energy and RFID/NFC. Besides, the following Industrial Protocols modules are
available: RS-485/Modbus, RS-232 Serial/Modbus and CAN Bus.
Some of the possible combinations are:
•LoRaWAN - GPRS
•802.15.4 - Sigfox
•868 MHz - RS-485
•RS-232 - WiFi
•DigiMesh - 4G
•RS-232 - RFID/NFC
•WiFi - 3G
•CAN Bus - Bluetooth
•etc.
Remark: GPRS, GPRS+GPS, 3G and 4G 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.
Figure: Use of the Expansion Board
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.
Selecting SOCKET0: LoRaWAN.ON(SOCKET0);
Selecting SOCKET1: LoRaWAN.ON(SOCKET1);