ThingPark Wireless ™

Advanced Developer Guide

V4 - June 2017

Under NDA
NOTICE

This document contains proprietary and confidential material of ACTILITY SA. This document is
provided under and governed by either a license or confidentiality agreement. Any unauthorized
reproduction, use, or disclosure of this material, or any part thereof, is strictly prohibited.
The material provided in this document is believed to be accurate and reliable. However, no
responsibility is assumed by Actility SA for the use of this material. Actility SA reserves the right to
make changes to the material at any time and without notice. This document is intended for
information and operational purposes only. No part of this document shall constitute any contractual
commitment by Actility SA.
© 2016 ACTILITY SA. All rights reserved.
Portions of this documentation and of the software herein described are used by permission of their
copyright owners.
Actility, ThingPark, are registered trademarks of Actility SA or its subsidiaries may also be registered
in other countries.
Other denoted product names of Actility SA or other companies may be trademarks or registered
trademarks of Actility SA or its subsidiaries, or their respective owners.

Headquarters
Actility Lannion,
Actility S.A 4 rue Ampère BP 30225
22300 Lannion France
www.actility.com

2
AdvancedThingParkDeveloperGuide_V4.docx
TABLE OF CONTENTS

Notice .............................................................................. 2
Table of Contents ................................................................ 3
Definitions and Acronyms ....................................................... 5
1 Scope .......................................................................... 6
2 LoRaWAN specification ..................................................... 6
2.1 Globally unique EUI-64: DevEUI ...................................................................... 7
2.2 Over-The-Air Activation (OTAA) ...................................................................... 8
2.2.1 128 bit application key: AppKey ................................................................ 8
2.2.2 64 bit application server identifier: AppEUI (joinEUI) ...................................... 8
2.3 Activation By Personalization (ABP) ................................................................. 9
2.3.1 Device address: DevAddr ........................................................................ 9
2.3.2 128 bit network secret: NwkSkey .............................................................. 9
2.4 Channel plans........................................................................................... 10
2.4.1 ETSI EU 868 ....................................................................................... 10
3 NetworkManager ........................................................... 11
3.1 Base stations list ....................................................................................... 11
3.2 Base station details .................................................................................... 12
3.3 Base station provisioning ............................................................................. 16
3.3.1 Manual Base station creation .................................................................. 16
3.3.2 Modify a Base station ............................................................................ 17
4 DeviceManager.............................................................. 18
4.1 Devices Creation and Management .................................................................. 19
4.1.1 Device list ......................................................................................... 19
4.1.2 Device details .................................................................................... 20
4.1.3 Device provisioning .............................................................................. 23
4.2 Connectivity plan ...................................................................................... 27
4.2.1 Connectivity Plan details ....................................................................... 28
4.2.2 Assign/Change a Connectivity Plan ........................................................... 29
4.2.3 Remove a Connectivity Plan ................................................................... 30
4.3 Application servers .................................................................................... 30
4.3.1 Create a new application server .............................................................. 31
4.3.2 Edit an Application server ...................................................................... 31
4.3.3 Delete an Application server ................................................................... 32
4.4 AS routing profiles ..................................................................................... 33
4.4.1 Create an AS Routing Profile ................................................................... 33
4.4.2 Modify or Delete an AS Routing Profile ....................................................... 35
4.4.3 Define or Remove an AS Routing Profile ..................................................... 35
5 WirelessLogger .............................................................. 37
5.1 Metadata ................................................................................................ 37
5.2 Payload .................................................................................................. 38
5.3 Payload decoder ....................................................................................... 39
6 Application Server ......................................................... 40

3
AdvancedThingParkDeveloperGuide_V4.docx
6.1 Uplink interface: ....................................................................................... 40
6.1.1 Query parameters: ............................................................................... 40
6.1.2 XML payload ...................................................................................... 40
6.1.3 JSON payload ..................................................................................... 41
6.2 Downlink interface .................................................................................... 42

4
AdvancedThingParkDeveloperGuide_V4.docx
DEFINITIONS AND ACRONYMS
ABP Activation By Personalization
ADR Adaptive Data Rate
AES Advanced Encryption Standard
AS Application Server
ESP Estimated Signal Power
LC Logical Channel
LRC Long-Range Controller: Network Server
LRR Long-Range Relay: software inside the gateway
OTAA Over The Air Activation
RF Radio Frequency
RSSI Received Signal Strength Indicator
SF Spreading Factor
SNR Signal to Noise Ratio

5
AdvancedThingParkDeveloperGuide_V4.docx
1 SCOPE
The Scope of this Device Developer Guide is to provide the guidelines to a developer during the
Thingpark Wireless connectivity integration.

2 LORAWAN SPECIFICATION
The LoRaWAN specification is publicly available from the LoRa™ alliance web site: lora-alliance.org

The LoRaWAN specification enables bidirectional communications, and currently offers three variants
of the MAC layer: class A, optimized for battery usage and sensors; class B, optimized for battery
powered actuators with low command latency requirements, and class C for mains powered devices
including actuators.
Class name Intended usage

A Battery powered sensors, or actuators with no latency constraint

(« all ») Most energy efficient communication class.

Must be supported by all devices

B Battery powered actuators

(« beacon ») Energy efficient communication class for latency controlled downlink.

Based on slotted communication synchronized with a network beacon.

C Mains powered actuators

(« continuous ») Devices which can afford to listen continuously.

No latency for downlink communication.
LoRaWAN class A employs the well-known receiver initiated transmit strategy to enable
communication bidirectionality.

6
AdvancedThingParkDeveloperGuide_V4.docx
 x symbols

Packet End device sleeps Rx slot 1 Rx slot 2

End Device
14dBm Up to 27dBm
same freq and SF 869.525MHz

1 second ± 20µS 1 second ± 20µS

Base station

Received by all
base stations in
range

The End-device, e.g. a temperature sensor, wakes-up to transmit its measurement. The LoRaWAN
radio frame will be received by all nearby base stations of the RF network. The device then
immediately goes to sleep for a specified amount of time, by default 1 second, in order to preserve
the battery.
After the exact sleep time, the End-device must wake up to receive potential downlink
communication from the network. The downlink communication may be an ACK from the network if
the End-device had sent a confirmed LoRaWAN frame, or it may be a command from the MAC layer
network controller or from an application server.
The Core network will use, at its choice, this first receive window (RX1), or the second receive window
(RX2) do send downlink frames. So if no frame has been received during the RX1 slot, the device must
go to sleep again and wake up another time for the RX2 slot.

2.1 Globally unique EUI-64: DevEUI

Each LoRaWAN end device has a globally unique IEEE EUI-64 address, the DevEUI. These addresses
are allocated by manufacturers within address blocks that must be purchased from IEEE, three blocks
are available:
• Organizational Unique Identifier (OUI) / MAC Address Block Large (MA-L)
• MAC Address Block Medium (MA-M)
• MAC Address Block Small (MA-S)
These 3 different blocks of addresses can be purchased from IEEE here:
• http://standards.ieee.org/develop/regauth/oui/
• http://standards.ieee.org/develop/regauth/oui28/index.html
• http://standards.ieee.org/develop/regauth/oui36/index.html

7
AdvancedThingParkDeveloperGuide_V4.docx
2.2 Over-The-Air Activation (OTAA)
OTAA device derive its NwkSkey and AppSkey using the Join key negotiation procedure as they first
attach to a network. This procedure uses a master AppKey secret that must be personalized at
production in the device.
A single application server, identified by its AppEUI (JoinEUI), is supported per device.

OTAA Who? What is it?

DevEUI IEEE The DevEUI identifies the device on the LoRaWAN network
during the JOIN request
AppEUI (joinEUI) Operator The AppEUI identifies the join server during the JOIN
request
AppKey Device manufacturer The AppKey encrypts the data during the JOIN request

2.2.1 128 bit application key: AppKey

The 128 bit AppKey must be personalized in each device during production. It may be distinct per
device or unique per application depending on the use-case.
Typically the AppKey must be part of the Excel file delivered with each production batch to the
customer, so that the customer may be able to provision the AppKey to the application server
associated with the Device.

2.2.2 64 bit application server identifier: AppEUI (joinEUI)

The AppEUI is a globally unique identifier of the target application server that will process all
exchanges with the device.
The network forwards the join message to the application server identified by the AppEUI. This
application server is supposed to have been provisioned with the Device AppKey. Based on the AppKey
and the content of the Join message sent by the device, the Application server:
1. Generates a NwkSkey and AppSkey and sends the NwkSkey information to the Core Network
2. Forms a cryptographic Join response payload that will allow the device to compute a NwkSkey
and AppSkey

As part of the Join procedure, the network also allocates a DevAddr address to the LoRaWAN device.

An available joinEUI is available from Actility as a join server: F0:3D:29:AC:71:00:00:00.

8
AdvancedThingParkDeveloperGuide_V4.docx
2.3 Activation By Personalization (ABP)

ABP Who? What is it?

DevEUI IEEE DevEUI is not used in LoRa communication in ABP but is
used to identify the device at the Network Server side
DevAddr Operator The DevAddr is the Device Address on the LoRa Network
NwkSKey Device manufacturer The NwkSKey encrypts the data during the transmission.
Gateways from other networks cannot see the content of
messages. The NwkSKey authenticates the device on a LoRa
network
AppSKeys Device manufacturer The AppSKey encrypts the payload data

2.3.1 Device address: DevAddr

The DevAddr identifies the device on the network, together with the Network secret for the sensor.
The group (DevAddr, NwkSkey) must be globally unique.
If the end device is not using the JOIN LoRaWAN procedure, it must also be personalized with the
DevAddr.
On the Core network, the DevAddr must be formed as in
NwkID [31..25] NwkAddr (24..00]
These identifiers are preallocated awaiting Ask your operator for a block of NwkAddr for
NwkID management by LoRa alliance. the devices that you will produce for the target
network.
The NwkID identifies the operator.
Device manufacturers must ensure that each
DevAddr=NwkID+NwkAddr corresponds to very
few, ideally a single DevEUI.
Collisions may be resolved as each device has a
unique NwkSkey, however such collisions
should be avoided.

The DevAddr will be provided by your LoRaWAN network operator.

2.3.2 128 bit network secret: NwkSkey

The 128 bit NwkSkey is used by the Core network to verify the authenticity and integrity of each
message. Use a random NwkSkey for each device.

Allocating a random network secret per device is very important for security, but also to
ensure that the short address collision resolution algorithm will work appropriately. The pair
(DevAddr, NwkSkey) must be globally unique.

2.3.2.1 128 bit application secret: AppSkey

The 128 bit AppSkey is used to encrypt the payload of messages. You may decide to use a unique
AppSkey for all LoRaWAN ports used by your device, or to allocate one AppSkey for each port.

9
AdvancedThingParkDeveloperGuide_V4.docx
AppSkeys must be known to the Application Server. Typically AppSkeys are part of a production Excel
file providing the associations between DevEUI, DevAddr, NwkSkey, AppSkey(s) of the devices part of
the production batch.

When adding the device to your account using the Device Manager application:
v You do not need to provision the AppSkey. ThingPark Wireless will then forward the payload
in encrypted form to the application servers and has no access to the payload clear-form
content. Network tools like Wireless Logger will be unable to decode the payload and will
present it in encrypted form.
v If you provision the AppSkey(s), then the Core Network will decode the payload before
forwarding it to the application server(s), and the Wireless Logger tool will also present the
packet payload in decoded form (and parse this payload if the payload syntax is supported).

2.4 Channel plans

2.4.1 ETSI EU 868

The implementation in Europe is the following default and mandatory channel plan:
• LC1: 868.1 MHz
• LC2: 868.3 MHz
• LC3: 868.5 MHz
• RX2: 869.525 MHz / SF12
Then the network will configure the device with the operator settings (add new channels, change RX2
configuration).

10
AdvancedThingParkDeveloperGuide_V4.docx
3 NETWORKMANAGER

v Launch the NetworkManager from your Dashboard menu.

3.1 Base stations list

The Base stations list displays all the filtered base stations into a list.

In the Search section, a new check-box “Restrict search to visible map area” is available, in order to
filter only base stations on the previous map view.
The displayed field are:
v Name (LRR ID) / model: name with ID and model of the LRR
v Version: version of the LRR software installed on the base station
v Software restart: last date of software restart
v Power source: type of power source when available
v Min. rem. Cap. up/down: min. remaining capacity up/down depending on potential Duty
Cycle limitations
v Average packets up/down: average number of packets per hour
v Alarm: number of alarms not acknowledged
v Locate: open a pop-up and display the base station on a map

The filtering/sorting can be done on all the above mentioned properties. This way, one can easily
display all base stations for which e.g. the average packet level is high, that have raised critical
alarms, etc.

In order to View or Edit the device:

v View
o double click on a base station
o select a base station and click on View at the bottom of the list
v Edit
o Select a base station and click on Edit at the bottom of the list

11
AdvancedThingParkDeveloperGuide_V4.docx
3.2 Base station details
v Base station frame

This frame displays the basic information of the base station such as the model, name, LRR ID, SMN
(Serial Number).
Based on the LRR Base station Model and the available information at system level, the ThingPark
Wireless OSS will also present the Installation information such as Power source, GPS receiver,
Antennas, WAN backhaul, Software version.
The location of the base station on the map could be provided in 2 different ways:
o Location provided by the GPS receiver inside the base station
o Manual location set by the administrator in the Network Manager GUI (Edit the LRR,
Click on “Update Location” button, Select Manual, enter GPS location then Save).

Location provided by the GPS receiver are used by Actility tools such as Wlogger or
Network without further action.
Please contact Actility to use the tools when location is set manually.

NOTE
You can reload all indicators by clicking on the reload button in the right corner

12
AdvancedThingParkDeveloperGuide_V4.docx
 v Indicators frame
A summary view of indicators for System, RF Cell indicators and WAN backhaul indicators is
available for the LRR as shown below:

v System indicators frame

The availability of System indicators depends on the model name of LRR (Example: not all LRR
gateways support embedded GPS). Available system indicators include the following:
o Power type
o Battery option
o Temperature
o CPU
o RAM
o Mass Storage Usage
o GPS receiver
o Time sync
o Software restart date

13
AdvancedThingParkDeveloperGuide_V4.docx
 v RF Cell Indicators frame
RF Cell indicators include Uplink and Downlink traffic indicators on the RF interface. Available
indicators include the following:
o Uplink: message from the device to the network
o Downlink: message from the network to the device
o Average packets: number of packets in the last 1h window
o Last packets: date time of the last packet
o Most busy channel
o Duty cycle: utilization of the duty cycle on the most busy channel
o Rem. capacity: remaining capacity of the duty cycle

A provisioned LRR comes with pre-provisioned logical channels (LCs). The summary section provides
Network Managers with information on the most busy uplink and downlink logical channels based in
Duty Cycle data.

v WAN indicators frame

The supported LRRs may have multiple backhauling options, it could be Ethernet or Cellular or
others. Each interfaces can be monitored and managed from the interface.
Also the connection status to the LRC including the date of the last messages transferred to the
LRC.
o LRC1 / LRC2:
o Network interface (eth, ppp, wlan, …)
§ Activity
§ Avg. round trip latency
§ Dev. round trip latency
§ Total traffic
§ Avg. bitrate

14
AdvancedThingParkDeveloperGuide_V4.docx
 v Uplink/Downlink packets frame
The uplink/downlink packets and payload frame presents the number of packets or payload size
transmitted uplink and downlink by an LRR with multiple sub-total options (Daily, Hourly, Last 7
days, Last 15 days)

NOTE
All charts can be exported or printed by clicking on the top right menu icon in the chart as shown
below:

15
AdvancedThingParkDeveloperGuide_V4.docx
3.3 Base station provisioning
The base station provisioning allows the Network Partner to add a new base station to its network.
Information required to create a new base station:
v ID
v Serial Number (SMN)
v Model

3.3.1 Manual Base station creation

To create a new base station:
v Right click on Base stations

v Click on Create base station

v A new pop-up appears with 4 fields: ID, SMN, Model, Name

v Fill out the fields. Please note that all fields are mandatory
o ID: Identification of the base station(8 hexadecimal digits)
o SMN: Serial Number (format: 0000-XX-0000-0000)
The fields ID and SMN are written on the label sticked on the base station, if you do not have it,
enter 0000-XX-0000-0000
o Select the right model
o Enter a name

v Click on to add the base station.

v To view the base station in the list, click on Search in the search section.

NOTE

Once a new base station has been created, it stays in status VALIDATING until your Operator
Manager has validated the base station on its network.

16
AdvancedThingParkDeveloperGuide_V4.docx
3.3.2 Modify a Base station
Modifying a base station allows you to update base station-related data such as the name, the
address, the manually entered location or the administrative info.
Start by opening a base station in Edit view:
v Select the base station to edit in the list
v Click on Edit to enter in the Edit view

Modification allowed:
v Base station name
v Address
v Administrative info
v Update location / altitude
v Alarm settings
Finally, to confirm the changes, go back to the device details by selecting the device in the column
in the left sidebar, then click Save in the top-right corner of the screen.

17
AdvancedThingParkDeveloperGuide_V4.docx
4 DEVICEMANAGER

v Launch the DeviceManager from your Dashboard menu.

When you login to the Device Management portal, you get an overview of all the devices of the account
is listed. You can easily shift between the Map and List view of devices, by clicking the corresponding
tabs.

The interface is based on 2 frames, a left sidebar menu and a main application frame showing device
data.
The left sidebar menu gives access to Devices, Connectivity plans, AS routing profiles and Settings.
The first main frame contains a Search bar, allowing users to search devices by Location, device
Identifier or another filtering criteria.

18
AdvancedThingParkDeveloperGuide_V4.docx
4.1 Devices Creation and Management

4.1.1 Device list

Device List displays all the filtered devices in a list.

The displayed field are:

v Name / Type: name and device profile
v MAC address / Network address: DevEUI and DevAddr of the device
v Connectivity plan
v Average packets
v Average SNR: based on the last 5 packets received
v Battery
v Alarm: number of alarms not acknowledged
v Locate: open a pop-up and display the device on a map

The filtering/sorting can be done on all the above mentioned properties. Users can therefore easily
display all devices for which e.g. the battery level is low, that have raised critical alarms, etc.
In order to View or Edit the device:
v View
o double click on a device
o select a device and click on View at the bottom of the list
v Edit
o Select a device and click on Edit at the bottom of the list

19
AdvancedThingParkDeveloperGuide_V4.docx
4.1.2 Device details

v Device frame

This frame displays the basic information of the device such as the model (device profile), name,
DevEUI, devAddr.
The interface also provides information on the LoRaWAN traffic such as the average number of
packets, average RSSI and SNR, last instantaneous/mean PERs, last RSSI/SNR/SF, date/time of the
last message received/sent.
For devices supporting the feature, the battery status information can also be displayed.
The location of the device on the map could be provided in 3 different ways:
v Last GPS position reported by the device
v Manual location
v gateway position which has received the last message

The View location history button displays a map with markers showing where the devices are located.

v Uplink/Downlink frame

The graphic above displays the number of uplink/downlink packets and payloads (bytes) over the
selected period (Daily totals, last 7 days, last 15 days).
v PER/RSSI/SNR/SF graph

20
AdvancedThingParkDeveloperGuide_V4.docx
The graphic above displays the PER, RSSI, SNR or SF distribution over the selected period.

4.1.2.1 Device Network

The Devices/Network section provides information on the Network subscription, associated

connectivity plan, routing plans associated to the device and the Network Coverage.
v Network subscription

21
AdvancedThingParkDeveloperGuide_V4.docx
The Subscription section displays the current associated connectivity plan and the first date on which
the device has communicated.
The graphic displays the usage of the device in the connectivity plan, showing the number of packets
on the selected period.

HOW-TO change the Connectivity plan

v Go to the device Edit view

v Click on Change in the subscription section
v Select the desired Connectivity Plan from the drop-down menu
v Click Save

v Network/cloud routing

The Network routing section displays the current associated AS routing profile. It is possible to view
the details of this routing profile, or also change and remove it.

HOW-TO change or assign an AS Routing Profile

v Go to the device Edit view

v Click on Change in the Network routing section
v Select the preferred AS routing profile from the drop-down menu in the pop-up
v Click Save

22
AdvancedThingParkDeveloperGuide_V4.docx
4.1.3 Device provisioning
The device provisioning allows users to create devices and register them on the network through
Activation By Personalization.
There are two ways to create a device
v Manual creation: create devices one by one
v Batch creation: mass import from a csv file to create several devices in one go

Information required to create a new device:

v DevEUI
v DevAddr
v NwkSKey

Optional information may be required:

v AppSKey

4.1.3.1 ABP Manual Device creation

The manual creation is mainly for support or development purpose. Once the device is in production,
refer to the Batch provisioning mode.
To create a new device manually:
v Right click on Devices

v Click on Create device

v A new pop-up appears with 4 sections: Administrative data, Device identification, Network
parameters, Application layer handling

23
AdvancedThingParkDeveloperGuide_V4.docx
v Fill out the Administrative data section

o Enter a name for the device

o Change the marker if you wish to customize the device marker
o Enter any relevant administrative information (Such information will be displayed in
the e-mail generated by an alarm)
o Set a location
§ Network location
§ Manual location

v Fill out the Device identification section. Please note that all fields are mandatory

o Device EUI (hexa): devEUI, device EUI, globally unique IEEE EUI-64 address
o Network address (hexa): devAddr, device Address
o Device profile: please refer to Device Profile
o Network key (hexa): NwkSKey, Network Session Key, 128-bit key

v Fill the Network section

o Choose a Connectivity plan in the drop-down menu, the displayed count indicates
the remaining connectivity plans available
o Choose an AS routing profile in the drop-down menu

24
AdvancedThingParkDeveloperGuide_V4.docx
 v Fill out the Application layer section

o To add a new Application Key

§ Click on Add
§ Fill the Key, 128-bit key
§ Enter a port number
§ Click on Update

NOTE

The port 0 is encrypted by the NwkSKey

The optional 128-bit AppSkey is used to encrypt the payload of the messages, and has to be shared
with the application server. You may decide to use a unique AppSkey for all LoRaWAN ports used by
your device (* keyword), or to allocate one AppSkey for each port.
v If you do not provision the AppSkey, ThingPark Wireless will forward the payload in encrypted
form to the application servers and has no access to the payload clear-form content. Network
tools like Wireless Logger will be unable to decode the payload and will present it in encrypted
form.
v If you provision the AppSkey(s), the LRC will decode the payload before forwarding it to the
application server(s) and the Wireless Logger tool will also present the packet payload in
decoded form (and parse this payload if the payload syntax is supported).

25
AdvancedThingParkDeveloperGuide_V4.docx
4.1.3.2 OTAA Manual Device creation

The Join device activation procedure is similar as the ABP provisioning, except about the keys to
inquire.
Fill out the Device identification section. Please note that all fields are mandatory
o Device EUI (hexa): devEUI, globally unique IEEE EUI-64 address
o Device profile: please refer to Device Profile
o Application EUI (hexa): AppEUI is a global application ID in IEEE EUI64 address space
that uniquely identifies application provider of the end-device
o Application key (hexa): is an AES-128 application key specific for the end-device that
is assigned by the application owner to the end-device and is responsible to encrypt
JOIN communication.

4.1.3.3 Modify a device

Modifying a device allows you to update device-related data such as the name, the manually entered
location, define another connectivity plan or define a routing plan.
Start by opening a device in Edit view:
v Select the device to delete in the list
v Click on Edit to enter the Edit view

Modification allowed:
v Device name
v Administrative info
v Device location
v Device marker
v Change/remove a connectivity plan
v Change/remove a AS routing plan

Finally, to confirm the changes, go back to the device details by selecting the device in the column
in the left sidebar, then click Save in the top-right corner of the screen.

4.1.3.4 Delete a device

Deleting a device is an action which cannot be undone and should be handled with care. All device
details and device status information will be lost.
Below are the steps to delete a device:
v Select the device to delete in the list
v Click on Edit to enter the Edit view

26
AdvancedThingParkDeveloperGuide_V4.docx
 v Click on Delete

v Confirm in the pop-up to delete the device

v Go back to the device list, click on Refresh to refresh the list

4.2 Connectivity plan

The Connectivity plan defines the network connectivity features (e.g. confirmed messages, downlink
traffic), and traffic policing parameters (token bucket regulators for uplink and downlink traffic) and
is associated to a given activation and recurring fee.
To access Connectivity plans, click on Connectivity plans in the left sidebar menu:

v Connectivity plan section

First Connectivity plan section displays the available plans in your account:

o Connectivity plans: name of the connectivity plan

o ID of the connectivity plan (required for batch provisioning)
o Purchased credit for end devices: number of maximum devices allowed in the plan
o Used up credit by end devices: number of devices registered on the selected plan

So the remaining devices that could be provisioned are “Purchased credit” – “Used up credit”.
Ask Actility to purchase additional Connectivity Plans.

27
AdvancedThingParkDeveloperGuide_V4.docx
4.2.1 Connectivity Plan details

In the Connectivity Plan details tab, the name, ID and description of the plan are displayed.
Furthermore, this tab provides a view on the following characteristics of the plan:
v Uplink frame parameters
o Ack: Feature flag to allow the network to send an ACK when requested by a device
operating in confirmed frame up mode.
o Rate regulator: nb of frames allowed per hour, nb of frames allowed in burst
o Regulator policy: uplink and downlink regulator policy
§ Mark: the system will keep track of devices exceeding the limits set
§ Drop: the system will drop packets that are beyond the limits set
o LRR buffering policy: RFU
o Forced adaptive data rate: Force a specific DataRate
v Downlink frame parameters
o Downlink transmission: activation state of the downlink transmission
o Acked downlink frame: Allow to send downlink confirmed
o Rate regulator: number of frames allowed per hour, number of frames allowed in
burst
o Regulator policy: uplink and downlink regulator policy (see Uplink frame Regulatory
policy above)
o Device status request frequency: Number of DevStatusReq sent by the server in 24h
o Report device battery level: Report Device battery usage level to the Device Manager
application and to Third Party Application Servers
o Report device margin: Report Device signal margin to the Device Manager application
and to Third Party Application Servers
v Network parameters

28
AdvancedThingParkDeveloperGuide_V4.docx
 o Mobility: RFU
o Network geolocation: RFU
o Base station metadata: feature flag to provide LRR meta information (RSSI, SR, SNR,
LRR, …) to third party application
v Routing parameters
o ThingPark cloud routing: Feature flag to allow routing to the ThingPark cloud service
o Third party application routing: Feature flag to allow routing to the ThingPark cloud
service
o Max. destinations per route: maximum number of destinations per route
o Add PER information: Forward PER to the Application Server
o Downlink sent indication: Forward sent downlink indication to the Application Server
v All RF regions parameters
o Minimal/Maximal SF: Lowest/highest spreading factor allowed for a device
o Force channel mask: Force a specific channel mask
o Minimum macro diversity: Minimum number of gateways which received the uplink
o Margin offset: The offset to apply on top of the global SNR margin set at RFregion
level to tune the global margin differently for different class of services to control
uplink PER
o Number of transmissions offset: Tune the number of transmissions for each uplink
packet (aka redundancy) differently for different class of service to optimize uplink
performance
o Target packet error rate: "Packet Error Rate value targeted by the ADR algorithm
o Macro diversity reliability: Minimum probability target of having N Base Stations
receiving Device uplink packets
o Minimum/Maximum number of transmissions: Minimum/Maximum number of Device
uplink transmissions to ensure quality of service will not be degraded

4.2.2 Assign/Change a Connectivity Plan

First of all, go to the Device Edit view in order to modify a device:

v Select the device to delete in the list
v Click on Edit to enter the Edit view

v Go to the Network section

v In the Network subscription > Subscription section

v Click on Change

v Select your new Connectivity plan in the drop-down menu

29
AdvancedThingParkDeveloperGuide_V4.docx
 v Click on Save

4.2.3 Remove a Connectivity Plan

To remove a Connectivity Plan, use the same process as above to assign/change a Connectivity Plan,
then click Remove.

4.3 Application servers

The Application Server (AS) needs to be defined prior to adding a routing profile to it.
TO access the Application Server settings, click on Application servers on the left sidebar menu:

The right-hand side will then be populated with the following dialog:

30
AdvancedThingParkDeveloperGuide_V4.docx
4.3.1 Create a new application server

v In the ‘New application server’ section, click on

v In the name section of the new dialog, enter the name of your new Application server:

v A new dialog appears.

v Select the type of content your Application Server can handle (xml or json) for the metadata,
including a field for the payload
v If you want the security feature to be enabled, click on ‘Activate’ in the ‘Uplink/downlink
security’ section

o Enter the Application Server unique ID, signature key and allowed timestamp
deviation between the LRC and your Application Server. This can seriously affect
communication if both sides are not properly synchronized.
o Click on ‘Save’ to validate the information
v Click on ‘Save’ to save the new Application server, then close.

4.3.2 Edit an Application server

v In the list of application server, select the server you want to delete and click on ‘Edit’, you
might have to confirm that you want to edit if not already done.
v In the ‘Add a route’ section, click on ‘Add’
o A new layer “Route” appears

31
AdvancedThingParkDeveloperGuide_V4.docx
 o Enter the Source ports to route
The Source ports are the LoRaWAN ports, it could be only one port (1), a range of ports (1-4), or all
ports (‘*’).
o Choose the Routing strategy
In case multiple destinations are given, the routing strategy defines how the data will be sent to these
destinations.
If “Sequential” is selected, the data will be sent to the first destination and only be sent to the
subsequent destination if the previous one is not available. If “Blast” is selected, the data will be
sent to all destinations at the same time.
o Click on Add to create a new one

o Select the Destination of the new route

o Click on Add to add this new destination

v Sort between different destinations, for order selection if using Sequential strategy
o You can change the order in which messages will be sent using the arrow buttons

v To edit a destination, select it and click on Edit

v To delete a destination, select it and click on Delete

4.3.3 Delete an Application server

v In the list of application server, select the server you want to delete and click on ‘Edit’, you
might have to confirm that you want to edit if not already done.

32
AdvancedThingParkDeveloperGuide_V4.docx
 v In the new dialog, click on ‘Delete’ on the top part of the dialog and confirm

4.4 AS routing profiles

The AS (Application Server) routing profile defines how the sensor data is routed to a back-end
application.
To access an AS routing profile, click on AS routing profiles on the left sidebar menu:

You will see the existing AS routing profiles in the list where you can View details or Edit an AS routing
profile.

The second section New AS routing profile gives the capability to add a new AS routing profile.

4.4.1 Create an AS Routing Profile

In order to create a new AS Routing Profile, go through the following steps:
v Click on Add in the New AS routing profile section

33
AdvancedThingParkDeveloperGuide_V4.docx
v Enter a name to the desired new AS routing profile

v Click on Create
v This new AS routing profile is opened and you can now edit it

v Set or unset the profile as default: check Is default checkbox

v Add a route
o Click on Add in the “Destinations” section

o A new pop up ‘Add destination’ appears

o Select the type of destination (ThinkPark Cloud or Application server) and the
destination
o Click on ‘Add’

34
AdvancedThingParkDeveloperGuide_V4.docx
 v The Application server is now in the list

4.4.2 Modify or Delete an AS Routing Profile

In order to modify or remove an AS Routing Profile

v Select the applicable Profile in the list
v Click on Edit

v On the AS routing profile details in Edit view if edition is desired

v Click on Delete if deletion is desired

NOTE

Remember to click on Save after any modification made in case of edition.

4.4.3 Define or Remove an AS Routing Profile

First, go to the Device Edit view in order to modify a device:
v Select the device to delete in the list
v Click on Edit to enter the Edit view

35
AdvancedThingParkDeveloperGuide_V4.docx
v Go to the Network section

v In the Network/cloud routing section

v Click on Change

v Select your new AS routing profile in the drop-down menu

v To remove the current associated AS routing profile, click on Remove

36
AdvancedThingParkDeveloperGuide_V4.docx
5 WIRELESSLOGGER

v Launch the WirelessLogger from your Dashboard menu.

When you login to the Wireless Logger interface, the interface automatically displays the 50 last
messages received from the devices provisioned into your Device Manager.

The interface contains a search bar and a result window displaying the messages.

5.1 Metadata
The metadata available for each message are:
v Direction of the data: up or down represented by an arrow
v Type of transmission: data, mac or simply an acknowledge
v UTC Timestamp
v Local Timestamp: UTC Timestamp translated to browser timezone
v Device Address
v Device EUI
v Port: Application port of the message
v Counter UP and Counter DOWN
v LRR RSSI: RSSI of the received message on LRR side
v LRR SNR: SNR of the received message on LRR side
v LRR ESP: ESP of the received message on LRR side
v SF: Spreading Factor

37
AdvancedThingParkDeveloperGuide_V4.docx
 v Sub Band: LoRa sub band used for the message
v Channel: LoRa logical channel used for the message
v LRC Id: Id of the LRC server
v LRR Id: LRR with better SNR
v LRR Lat: LRR latitude
v LRR Long: LRR longitude
v LRR Count: number of LRR receiving this message. The system performs a 250ms buffering
upon receiving a message to check if the same message arrives though other LRR, in which
case LRR Count is incremented. If latency is uneven in the network, a message (with the same
Counter Up and payload) may appear more than once in the Wlogger.
v Device Lat: Device latitude
v Device Lon: Device longitude
v LoS Distance (m): distance between the device and the LRR
v Map: displays the device and LRR on a map
v Trip: displays the location path of the device (if device location available)
v MIC: Checksum

NOTE

The GPS data (Device lat/lon, LoS, map and trip) are filled only if the device gives its location:
v Manual location
v Decoder selected if the location is in the payload

5.2 Payload

Click on the icon on the left of a message in order to expand and display the message payload.
By default the message is displayed in raw data:

NOTE

If the AppSKey has been entered during the Device provisioning, then the payload has been decrypted
by the LRC, if not then the payload is displayed encrypted.

38
AdvancedThingParkDeveloperGuide_V4.docx
5.3 Payload decoder
The payload can be displayed with the application data format if the decoded is known by the Wireless
Logger.
v Select your decoder in the Decoder list:

v Click on to refresh the messages

v Click on the icon left of a message to expand the message payload

NOTE
Payload can only be decoded if the AppSKey is known by the ThingPark Wireless

39
AdvancedThingParkDeveloperGuide_V4.docx
6 APPLICATION SERVER

6.1 Uplink interface:

Uplink destination URIs are defined for each device in service profiles (basically one per device).
The main criteria is the LoRa port numbers expressed as intervals, lists or single values. A default
LoRa port destination can be declared.
There are two modes of distribution which are not exclusive:
v Blast/blind mode: packets are delivered to a set of destinations without acknowledgment
control.
v Order mode: packets are delivered to a list of destinations until one of them confirms
receipt (200OK).

Duplicate packets (same counter up and same payload) are not sent to application servers, as long
as the multiple copies are received by the network infrastructure within a maximum delay of 250ms
(configurable by the LPWA operator). The XML payload sent to the application servers still include
the RF metadata corresponding to all receiving base stations.
The uplink message is transmitted in a HTTP/POST request with query parameters and an XML
payload.

6.1.1 Query parameters:

LrnDevEui: 00000000007E074F // the device DevEUI
LrnFPort: 2 // the LoRaWAN port number
LrnInfos: UPHTTP_LAB_LORA // the service profile name used to route the packet

6.1.2 XML payload

<?xml version="1.0" encoding="UTF-8"?>
<DevEUI_uplink xmlns="http://uri.actility.com/lora">
<Time>2015-07-09T16:06:38.49+02:00</Time> // timestamp for the packet
<DevEUI>00000000007E074F</DevEUI>
<FPort>2</FPort> //LoRaWAN port number
<FCntUp>11</FCntUp> // the uplink counter for this packet
<FCntDn>10</FCntDn> // the downlink counter for the previous packet
<ADRbit>1</ADRbit>
<FCntDn>0</FCntDn> // the last downlink counter to the device
<payload_hex>0027…bd00</payload_hex> //LoRaWAN payload in hexa ascii format
<mic_hex>38e7a3b9</mic_hex> // MIC in hexa ascii format
<Lrcid>00000065</Lrcid>
<LrrRSSI>-60.000000</LrrRSSI>
<LrrSNR>9.750000</LrrSNR>
<SpFact>7</SpFact>
<SubBand>G1</SubBand>
<Channel>LC2</Channel>
<DevLrrCnt>3</DevLrrCnt> // number of LRRs which received this packet
<Lrrid>08040059</Lrrid>
<LrrLAT>48.874931</LrrLAT>
<LrrLON>2.333673</LrrLON>
<Lrrs>
<Lrr>
<Lrrid>08040059</Lrrid>
<Chain>0</Chain>
<LrrRSSI>-60.000000</LrrRSSI>

40
AdvancedThingParkDeveloperGuide_V4.docx
 <LrrSNR>9.750000</LrrSNR>
<LrrESP>-51.568496</LrrESP>
</Lrr>
<Lrr>
<Lrrid>33d13a41</Lrrid>
<Chain>0</Chain>
<LrrRSSI>-73.000000</LrrRSSI>
<LrrSNR>9.750000</LrrSNR>
<LrrESP>-41.754934</LrrESP>
</Lrr>
<Lrr>
<Lrrid>a74e48b4</Lrrid>
<Chain>0</Chain>
<LrrRSSI>-38.000000</LrrRSSI>
<LrrSNR>9.250000</LrrSNR>
<LrrESP>-46.497314</LrrESP>
</Lrr>
</Lrrs>
<CustomerID>100000507</CustomerID>
<CustomerData>…</CustomerData> // ascii customer data set by provisioning
<ModelCfg>0</ModelCfg>
<DevAddr>007E074F</DevAddr>
</DevEUI_uplink>

6.1.3 JSON payload

{
"DevEUI_uplink": {
"Time": "2016-10-26T11:08:00.609+02:00",
"DevEUI": "A81758FFFE0301EA",
"FPort": "5",
"FCntUp": "43749",
"ADRbit": "1",
"MType": "2",
"FCntDn": "784",
"payload_hex": "0100fd02290404b505020603c2070e0c",
"mic_hex": "975457b1",
"Lrcid": "00000127",
"LrrRSSI": "-45.000000",
"LrrSNR": "7.750000",
"SpFact": "7",
"SubBand": "G0",
"Channel": "LC6",
"DevLrrCnt": "3",
"Lrrid": "29000119",
"Late": "0",
"LrrLAT": "48.875259",
"LrrLON": "2.332962",
"Lrrs": {
"Lrr": [{
"Lrrid": "29000119",
"Chain": "0",
"LrrRSSI": "-45.000000",
"LrrSNR": "7.750000",
"LrrESP": "-45.673985"
},
{
"Lrrid": "080E0E94",
"Chain": "0",

41
AdvancedThingParkDeveloperGuide_V4.docx
 "LrrRSSI": "-51.000000",
"LrrSNR": "6.750000",
"LrrESP": "-51.832691"
},
{
"Lrrid": "08060311",
"Chain": "0",
"LrrRSSI": "-59.000000",
"LrrSNR": "10.250000",
"LrrESP": "-59.391785"
}]
},
"CustomerID": "100000128",
"CustomerData": {
"alr": {
"pro": "LORA/Generic",
"ver": "1"
}
},
"ModelCfg": "0",
"DevAddr": "040874A4"
}

6.2 Downlink interface

Depending on the device provisioning (application secret keys) encryption/decryption can be
performed by the Network Server.
The following HTTP/POST message format is used to tunnel the radio frame payload and associated
metadata from the target application server to the Network Server. The downlink destination URI is
the primary LRC cluster (lrc-dev.thingpark.com). The application server acts as a HTTP client and
the Network Server acts as a HTTP server.
Such POST command may be generated easily by tools such as curl or POSTman.
curl -H "Content-type:application/x-www-form-urlencoded" -X POST
"https://api-
dev1.thingpark.com/thingpark/lrc/rest/downlink?DevEUI=000000000F1D8693&FPort=1&Payload=0102030
405060708090A0B0C0D0E0F&FCntDn=1234"

Query parameters:
v DevEUI (Mandatory): target device IEEE EUI64 in hexadecimal form (representing 8 octets)
v FPort (Mandatory): target port (in decimal format)
v Payload (Mandatory): hexadecimal payload. The hexadecimal payload will be encrypted by
the LRC cluster if FCntDn parameter is absent, and if the LRC has been configured with an
AppSKey for the specified LoRaWAN port, otherwise the Payload must be encrypted by the
Application Server according to the LoRaWAN specification. The Application Server
encryption uses the downlink counter, which is why the FCntDn query parameter is required
in this case.
v FCntDn (Optional); LoRaWAN Downlink Counter value used to encrypt the payload. This
query parameter is needed only if the Application server (not the Network Server) encrypts
the payload. If present, FCntDn will be copied in the LoRaWAN header field FCnt, and the
encrypted payload will be copied as-is to the LoRaWAN downlink frame by the Network
Server.
v Confirmed (Optional). A value of Confirmed=0 requests transmission of an UNCONFIRMED
downlink frame. A value of Confirmed=1 requests transmission of a CONFIRMED downlink
frame. Default value Confirmed=0 (UNCONFIRMED).
Support of Confirmed frame transmission is subject to Connectivity plan feature flag

42
AdvancedThingParkDeveloperGuide_V4.docx
 "ackedDownlinkFrame": if the Confirmed flag is set on the HTTP POST and the device is
associated with a Connectivity plan where the "ackedDownlinkFrame" feature flag is set, the
downlink packet is processed, otherwise the processing is aborted and a specific error code
is returned to the AS in the HTTP response.
v FlushDownlinkQueue : (Optional) Empties the device AS DL queue of the device
(Boolean). When this parameter is set to FlushDownlinkQueue=1, the AS requests the LRC
to purge the AS DL queue of the device prior to adding the DL payload transported by this
HTTP POST.
v ValidityTime : (Optional) Associates the AS DL payload with an expiration date (ISO date, or
Duration in second) in the device AS DL queue. If the AS DL payload has not yet been sent to
the device, the AS DL payload will be discarded by the LRC when the expiration date is
reached.

Example (sample)
v curl -H "Content-type:application/x-www-form-urlencoded" -X POST
"https://api.thingpark.com/thingpark/lrc/rest/downlink?DevEUI=xxx&FPort=1&Payload=010203
0405060708090A&FCntDn=1234&FlushDownlinkQueue=1&ValidityTime=2016-01-
11T14:28:00+02:00"
v When this HTTP POST is received by the LRC, the LRC purges the DL queue associated with
the 000000000F1D8693 device, and queues the 0102030405060708090A DL payload,
waiting for an UL from the device. The queued DL payload is associated with the 2016-01-
11T14:28:00+02:00 expiration date. If the DL payload cannot be sent to the device before the
expiration date, the DL payload will be discarded by the LRC.

LRC HTTP response codes:

v 200 “Request queued by LRC”: request accepted and queued until the class A device opens
Rx slots by sending an uplink. In the case of a class C device, the downlink command will be
sent as soon as the LRR base station radio is available and the maximum regulatory Tx duty
cycle allows transmission.
v 350 “Invalid DevEUI”
v 350 “Downlink counter value already used. Expected=1238”: the downlink counter value
was already used, for instance due to a race condition with another Application server.
v 350 “Downlink counter value increment too large. Expected=1001”: the AS supplied
downlink counter value is much larger than the expected downlink counter value and was
rejected by the LRC.
v 350 "Confirmed downlink is not authorized for this device": the request for transmission of a
confirmed downlink packet was rejected by the LRC due to absence of
“ackedDownlinkFrame” feature flag in the Connectivity plan associated to the device.

43
AdvancedThingParkDeveloperGuide_V4.docx