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