Libelium Waspmote LoRaWAN Networking Manual

Waspmote LoRaWAN

Networking Guide

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

-2-

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

-3- v7.6

Index

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

-4-

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.

-5- 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)

-6-

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

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

-8-

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

-9- v7.6

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

Hardware

Figure: LoRaWAN EU module with antenna

-10-

v7.6

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

Hardware

Figure: LoRaWAN US module

Figure: LoRaWAN US module with antenna

-11- v7.6

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

Hardware

Figure: LoRaWAN AU module

Figure: LoRaWAN AU module with antenna

-12-

v7.6

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

Hardware

Figure: LoRaWAN IN module

Figure: LoRaWAN IN module with antenna

-13- v7.6

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

Hardware

Figure: LoRaWAN AU module

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.

-14-

v7.6

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: LoRaWAN JP / KR module

Hardware

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.

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

-15- v7.6

Hardware

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)

KR 920-923 MHz ISM Band (South Korea) LoRaWAN JP / KR

INDIA 865-867 ISM Band (India) LoRaWAN IN

Figure: Regional compatibility table

LoRaWAN ASIA-PAC / LATAM

LoRaWAN JP / KR (special for Japan)

-16-

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

-17- 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.

Figure: Power consumption table

State Power Consumption

On 1.1 mA

Transmitting data 96.1 mA

Receiving data 27 mA

-18-

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.

-19- 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);

-20-

v7.6

Hardware

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.

Warnings:

• Avoid to use DIGITAL7 pin when working with the Expansion Board. This pin is used for setting the XBee into sleep mode.

• Avoid to use DIGITAL6 pin when working with the Expansion Board. This pin is used as power supply for the Expansion Board.

• Incompatibility with Sensor Boards:

- Agriculture v30 and Agriculture PRO v30: Incompatible with Watermark and solar radiation sensors

- Events v30: Incompatible with interruption shift register

- Gases v30: DIGITAL6 is incompatible with CO2 (SOCKET_2) and DIGITAL7 is incompatible with NO2

(SOCKET_3)

- Smart Water v30: DIGITAL7 incompatible with conductivity sensor

- Smart Water Ions v30: Incompatible with ADC conversion (sensors cannot be read if the Expansion Board

is in use)

- Gases PRO v30: Incompatible with SOCKET_2 and SOCKET_3

- Cities PRO v30: Incompatible with SOCKET_3. I2C bus can be used. No gas sensor can be used.

-21- v7.6

Software

3. Software

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

3.1. Waspmote libraries

3.1.1. Waspmote LoRaWAN les

The les related to the LoRaWAN libraries for these modules are:

WaspLoRaWAN.h WaspLoRaWAN.cpp

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

#include <WaspLoRaWAN.h>

3.1.2. Class constructor

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

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

3.1.3. API constants

The API constants used in functions are:

Constant Description

LORAWAN_ANSWER_OK

LORAWAN_ANSWER_ERROR

LORAWAN_NO_ANSWER

LORAWAN_INIT_ERROR

LORAWAN_LENGTH_ERROR

LORAWAN_SENDING_ERROR

LORAWAN_NOT_JOINED

LORAWAN_INPUT_ERROR

LORAWAN_VERSION_ERROR

RN2483_MODULE

RN2903_MODULE

RN2903_IN_MODULE

RN2903_AS_MODULE

ABZ_MODULE

BAND_JP923

BAND_KR920

Successful response to a function

Erratic response to a function

No response to a function

Required keys to join to a network were not initialized

Data to be sent length limit exceeded

Server did not response

Module has not joined a network

Invalid input parameter

The module does not support this function

LoRaWAN module plugged is LoRaWAN EU

LoRaWAN module plugged is LoRaWAN US

LoRaWAN module plugged is LoRaWAN IN

LoRaWAN module plugged is LoRaWAN ASIA-PAC / LATAM

LoRaWAN module plugged is LoRaWAN JP / KR

LoRaWAN module is using the AS923 band

LoRaWAN module is using the KR920-923 band

-22-

v7.6

3.1.4. API variables

The variables used inside functions and Waspmote codes are:

Constant Description

_buffer

_length

_def_delay

_baudrate

_uart

_adr

_ar

_eui

_devEUI

_appEUI

_nwkSKey

_appSKey

_appKey

_devAddr

_band

_margin

_gwNumber

_freq

_radioFreq

_radioFreqDev

_preambleLength

_dCycle

_drrMin

_drrMax

_dCyclePS

_crcStatus

_powerIndex

_dataRate

_retries

_upCounter

The buer of memory used for storing the responses from the

module

The useful length of the buer

The time to wait after sending every command until listen for a response

The baudrate to be used when the module is switched on

The selected UART (regarding the socket used: SOCKET0 or SOCKET1)

The adaptive data rate state (on or o)

The automatic reply state (on or o)

The buer used for storing the preprogrammed globally unique identier from the module's hardware

The buer used for storing the globally unique identier for the module (software programmable)

The buer used for storing the application identier for the

module

The buer used for storing the network session key for the module

The buer used for storing the application session key for the

module

The buer used for storing the application key for the module

The buer used for storing network device address for module

The buer used for storing the frequency band

The demodulation margin received in the last Link Check Answer frame

The number of gateways successfully received the last Link Check Answer frame

The buer used for storing the operating frequency for every

channel

The transceiver operating frequency

The transceiver frequency deviation

The preamble length for transceiver

The buer used for storing the operating duty cycle for every

channel

The minimum operating data rate range for every channel

The maximum operating data rate range for every channel

The duty cycle prescaler (which can only be congured by the server)

The CRC status to determine if it is to be included during operation

The output power to be used on LoRaWAN transmissions

The data rate to be used on LoRaWAN transmissions

The number of retransmissions for an uplink

The value of the uplink frame counter

Software

-23- v7.6

Software

_downCounter

_radioPower

_radioSF

_radioRxBW

_radioCR

_radioWDT

_radioBW

_radioSNR

_radioMode

_radioBitRate

_supplyPower

_rx2DataRate

_rx2Frequency

_rx1Delay

_macStatus

_status

_data

_port

_dataReceived

_version

_bandABZ

The value of the downlink frame counter

The output power level used by the transceiver

The spreading factor to be used by the transceiver

The receiving bandwidth used by the transceiver

The coding rate used by the transceiver

The time to be used by the transceiver watchdog timer

The value used for the transceiver bandwidth

The SNR value for the last received packet by the transceiver

The buer to save the operative radio mode

The operative radio bit rate

The voltage level read by the module

The second receiving window data rate

The second receiving window frequency

The rst receiving window delay

The MAC status register from the module

The status of every LoRaWAN channel

The buer of memory used for storing data received from the

back-end

The port where data was received

The ag used to inform if any data was received

The version of the module plugged into Waspmote

Band used for the LoRaWAN JP / KR type module

3.1.5. API functions

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

All public functions return one of these possible values:

• LORAWAN_ANSWER_OK = 0

• LORAWAN_ANSWER_ERROR = 1

• LORAWAN_NO_ANSWER = 2

• LORAWAN_INIT_ERROR = 3

• LORAWAN_LENGTH_ERROR = 4

• LORAWAN_SENDING_ERROR = 5

• LORAWAN_NOT_JOINED = 6

• LORAWAN_INPUT_ERROR = 7

• LORAWAN_VERSION_ERROR = 8

-24-

v7.6

+ 53 hidden pages

Libelium Waspmote LoRaWAN Networking Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

1. Introduction

1.1. Technology overview

2. Hardware

2.1.1. LoRaWAN EU

2.1.2. LoRaWAN US

2.1.3. LoRaWAN AU

2.1.4. LoRaWAN IN

2.1.5. LoRaWAN ASIA-PAC / LATAM

2.1.6. LoRaWAN JP / KR

2.2. Region standards

2.3. Power consumption

2.3.1. LoRaWAN EU

2.3.2. LoRaWAN US

2.3.3. LoRaWAN AU

2.3.4. LoRaWAN IN

2.3.5. LoRaWAN ASIA-PAC / LATAM

2.3.6. LoRaWAN JP / KR

2.4. Time consumption

2.5. How to connect the module

2.6. Expansion Radio Board

3. Software

3.1. Waspmote libraries

3.1.2. Class constructor

3.1.3. API constants

3.1.4. API variables

3.1.5. API functions