TP Wireless 6.1 OSS API User Guide

Actility ThingPark Wireless
OSS API User Guide
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.
© 2019 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
Under Non-Disclosure Agreement

Actility S.A. au capital de 744 810 € - 4 rue Ampère, 22300 Lannion, France
RCS St Brieuc 522 305 473, Siret 522 305 473 00012, TVA FR62522305473
TP_Wireless_6.1_ OSS_API_User_Guide.docx- 2
VERSIONS
Version Date Author Details
01 17/11/2015 S. Solomon Initial Version
02.3 06/01/2015 S. Solomon Updated architecture overview
02.3 13/01/2015 S. Solomon Updated introduction, layout and formatting
A.-F. Pierre
03 10/04/2015 OSS API User Guide as a tutorial
A. Yverneau
04 31/05/2016 L. Guillemot Initial revision for ThingPark Wireless 3.1.1
05 21/10/2016 L. Guillemot Initial revision for ThingPark Wireless 3.2.3
4.0.1-rev1 27/01/2017 L. Guillemot Initial revision for ThingPark Wireless 4.0.1
4.2-rev1 31/08/2017 L. Guillemot Initial revision for ThingPark Wireless 4.1, 4.1.2 and 4.2
There is no enhancement for 4.3 (LoRaWAN™

4.3 15/12/2017 ML Ancelle
connectivity)
There is no enhancement for 5.0 (LoRaWAN™
5.0 06/03/2018 ML Ancelle
connectivity)
Includes cellular connectivity features from 4.3 to 5.0
5.0-rev1 04/05/2018 L. Guillemot releases, and a LoRaWAN™ feature rectification. Does not
include LoRaWAN™ 5.0 new features.
5.1 27/08/2018 ML Ancelle There is no enhancement for 5.1
5.2 27/08/2018 ML Ancelle There is no enhancement for 5.2
5.2.2 12/00/2019 ML Ancelle There is no enhancement for 5.2.2
6.0 25/07/2019 L. Guillemot There is no enhancement for 6.0
6.1 23/12/2019 L.Guillemot There is no enhancement for 6.1

REFERENCE DOCUMENTS
Documents Author
Actility ThingPark Wireless OSS API Description – Connectivity Manager
Actility ThingPark Wireless OSS API Description – Network Manager
R1 Actility
Actility ThingPark Wireless OSS API Description – Device Manager
See https://oss-api.thingpark.com
Actility ThingPark System Management Platform User Sessions Guide Actility

R2
R3 Actility ThingPark Wireless Supplier User Guide Actility
R4 Actility ThingPark Functional Description Actility
R5 Actility ThingPark Wireless LRC-AS Tunnel Interface Developer Guide Actility
R6 ThingPark Wireless HSM Solution Description Actility
Actility ThingPark EPC Connector Solution Description Actility
Actility ThingPark Wireless Multi-Technology IoT Platform Actility
Actility ThingPark Wireless Vendor User Guide Actility
Actility ThingPark Wireless Network Partner User Guide Actility
Actility ThingPark Wireless Device Manager User Guide Actility
Actility ThingPark Wireless Logger User Guide Actility
Actility ThingPark Wireless Address Manager User Guide Actility
Actility ThingPark Wireless LRC-AS Tunnel Interface Developer Guide (LoRaWAN) Actility
Actility ThingPark Wireless LRC-AS Tunnel Interface Developer Guide (Cellular) Actility
Actility ThingPark Wireless LRC-OSS Interface Developer Guide (LoRaWAN) Actility
Actility ThingPark Wireless LRC-OSS Interface Developer Guide (Cellular) Actility
Actility ThingPark Wireless Usage Details Records Actility
Actility ThingPark Join Server Solution Description Actility

WHAT’S NEW
New/Enhanced Functionalities For More Information, See… Release
A base station must be in active
6.6 Updating a Base Station 4.3
state to be updated (RDTP4231)
All sections of this document apply to cellular
connectivity unless stated to the contrary.
The OSS API supports cellular Sections of special interest are:
connectivity in Message mode, SPR
1 Scope 4.3
provisioning and HSS/SPR
provisioning. (NFR 691) 5 Using the Connectivity Manager OSS API
7 Using the Device Manager OSS API
7.2.1.4.4.2.1 Creating an HTTP or a Kafka Local
Full integration of cellular Application Server
connectivity in Message mode. 7.2.1.4.4.2.3 Adding a Route to an HTTP Local
Introduction of cellular Direct IP and Application Server 5.0
Mixed modes (NFR 1012-1013-
1016-1017-1020-1021) 7.2.1.4 Associating an AS Routing Profile
7.2.1.4.5 Provisioning an AS Routing Profile

TABLE OF CONTENTS
Notice ................................................................................................................ 2
Versions ............................................................................................................. 3
Reference Documents ........................................................................................ 4
What’s New........................................................................................................ 5
Table of Contents ............................................................................................... 6
Definitions and Acronyms .................................................................................. 9
1 Scope ......................................................................................................... 12
2 Conventions .............................................................................................. 12
3 ThingPark Solution Overview ..................................................................... 13
4 Single-Sign-On Authentication General Process ........................................ 14
5 Using the Connectivity Manager OSS API .................................................. 15
5.1 Logging In with Administrator Credentials ............................................................................ 15
5.1.1 Authenticating the Administrator ................................................................................. 15
5.1.2 Generating a Connectivity Supplier Access Code as an Administrator ......................... 16
5.1.3 Logging Out from the SMP API Session ......................................................................... 17
5.1.4 Bootstrapping the Connectivity Manager OSS API Session ........................................... 17
5.2 Creating a Connectivity Plan ................................................................................................. 18
5.3 Listing the Connectivity Plans ................................................................................................ 19
5.4 Retrieving the Connectivity Plan Configuration .................................................................... 20
5.5 Editing a Connectivity Plan .................................................................................................... 20
5.6 Deleting a Connectivity Plan.................................................................................................. 21
6 Using the Network Manager OSS API ........................................................ 22
6.1 Logging In with Administrator Credentials ............................................................................ 22
6.1.1 Authenticating the Administrator ................................................................................. 22
6.1.2 Generating a Network Partner Access Code as an Administrator ................................ 23
6.1.3 Logging Out from the SMP API Session ......................................................................... 24
6.1.4 Bootstrapping the Network Manager OSS API Session ................................................. 24
6.2 Creating a Base Station ......................................................................................................... 25
6.2.1 Retrieving a Base Station Profile ................................................................................... 25
6.2.2 Declaring a Base Station ................................................................................................ 26
6.3 Retrieving Base Station Information ..................................................................................... 26
6.3.1 Retrieving Base Station Basic Information .................................................................... 26
6.3.2 Retrieving the Base Station System............................................................................... 29
6.3.3 Retrieving RF Cell Reports Information ......................................................................... 32
6.3.4 Retrieving WAN Reports Information ........................................................................... 37
6.4 Administering a Base Station ................................................................................................ 41
6.4.1 Asynchronous and Synchronous Commands ................................................................ 41
6.4.2 Executing an Asynchronous Command ......................................................................... 42
6.4.3 Retrieving the Result of an Asynchronous Command ................................................... 43
6.4.4 Executing a Synchronous Command ............................................................................. 43
6.5 Managing the Base Station Alarms ....................................................................................... 44
6.5.1 Listing the Base Station Alarms ..................................................................................... 44
6.5.2 Acknowledging an Alarm ............................................................................................... 45
6.5.3 Acknowledging the Alarms ............................................................................................ 45
6.6 Updating a Base Station ........................................................................................................ 45
6.7 Deleting a Base Station.......................................................................................................... 47
6.8 Logging Out from the Network Manager Session ................................................................. 47
7 Using the Device Manager OSS API............................................................ 48
7.1 Logging In with Administrator or Application Credentials .................................................... 48
7.1.1 Logging In with Administrator Credentials .................................................................... 48
7.1.2 Logging In with Application Credentials ........................................................................ 51
7.2 Creating Devices .................................................................................................................... 55
7.2.1 Preparing the Device Prerequisite Information ............................................................ 55
7.2.2 Declaring a LoRaWAN™ Device ..................................................................................... 68
7.2.3 Declaring a Cellular Device ............................................................................................ 70
7.2.4 Declaring a Set of Devices with Mass-Import................................................................ 72
7.3 Retrieving Device Information .............................................................................................. 74
7.3.1 Listing the Devices ......................................................................................................... 74
7.3.2 Retrieving the Device Configuration ............................................................................. 75
7.3.3 Retrieving the Device Uplink/Downlink History ............................................................ 76
7.3.4 Retrieving the Device Location (LoRaWAN™ Only) ....................................................... 76
7.3.5 Retrieving the Device Battery Level (LoRaWAN™ Only)................................................ 77
7.4 Managing Device Alarms ....................................................................................................... 78
7.4.1 Listing the Device Alarms .............................................................................................. 78
7.4.2 Acknowledging an Alarm ............................................................................................... 78
7.4.3 Acknowledging the Alarms ............................................................................................ 79
7.5 Handling AS Routing Profiles ................................................................................................. 79
7.5.1 Listing AS Routing Profiles ............................................................................................. 79
7.5.2 Creating an Empty AS Routing Profile ........................................................................... 79
7.5.3 Updating an AS Routing Profile ..................................................................................... 80

7.5.4 Deleting an AS Routing Profile ...................................................................................... 80
7.6 Handling Local Application Servers ....................................................................................... 80
7.6.1 Listing Local Application Servers ................................................................................... 81
7.6.2 Creating an Empty Local Application Server ................................................................. 81
7.6.3 Updating a Local Application Server ............................................................................. 81
7.6.4 Deleting a Local Application Server ............................................................................... 82
7.6.5 Local Application Server URLs Routing Strategies ......................................................... 82
7.7 Updating a Device ................................................................................................................. 83
7.8 Deleting a Device ................................................................................................................... 83
7.9 Logging Out from the Device Manager Session .................................................................... 83
What’s New History ......................................................................................... 85
About Actility ................................................................................................... 86

DEFINITIONS AND ACRONYMS
Acronyms Definitions
ABP Activation By Personalization
ADR Adaptive Data Rate
AES Advanced Encryption Standard
BPM Business Process Management
BSS Billing Support Systems
CSP Communication Service Provider
DC Duty Cycle
DDR Device Data Record
Device A sensor or actuator. Also called end-device.
EPCC Evolved Packet Call Connector
ESP Estimated Signal Power
ETSI European Telecommunications Standards Institute
GSCL Gateway Service Capability Layer
GTM Go To Market
GUI Graphical User Interface
HAN Home Area Network
HAN Home Area Network
HSM Hardware Security Module
HSS Home Subscriber Server
IaaS Infrastructure as a Service
IEC International Electrotechnical Commission
IMEI International Mobile Equipment Identity
IMSI International Mobile Subscriber identity
IoT Internet of Things
ISM Industrial Scientific Medical
JS Join Server
KPI Key Performance Indicator
LAN Local Area Network

LC Logical Channel
LoRaWAN™ Long Range Wide Area Network
LPWAN Low Power Wide Area Network
LRC Long Range Controller. Also called Network Server
LRR Long Range Relay
LTE Long-Term Evolution
M2M Machine-to-Machine
MAC Media Access Control
MSISDN Mobile Station International Subscriber Directory Number
MTBF Mean Time Before Failure
NAT Network Address Translation
NS Network Server
NSCL Network Service Capability Layer
NW Network
OBIX Open Building Information Exchange
ONG Object Network Gateway Browser
OSS Operations Support Systems
PER Packet Error Rate
P-GW Packet Data Network Gateway. Also called PDN-GW.
PKI Public Key Infrastructure
POC Proof Of Concept
REST REpresentational State Transfer
RF Radio Frequency
RIT Receiver Initiated Transmit
RSSI Received Signal Strength Indicator
SaaS Software as a Service
SF Spreading Factor
SLRC Secured LRC (VPN Concentrator)
SMP System Management Platform
SMTP Simple Mail Transfer Protocol

SNMP Simple Network Management Protocol
SNR Signal to Noise Ratio
SPR Subscriber Profile Repository
SSH Secure SHell
SSO Single Sign On
TLS Transport Layer Security
TWA ThingPark Wireless Application
UE User Equipment
UI User Interface
UNB Ultra Narrow Band
VLAN Virtual LAN
VM Virtual Machine
VPN Virtual Private Network
WS Web Service

1 SCOPE
The OSS API User Guide explains how to use the ThingPark Wireless OSS API’s web services that
allows you to control the ThingPark Wireless Applications (TWA): Connectivity Manager, Network
Manager, Device Manager. The OSS API supports LoRaWAN™ and Cellular connectivity.
This guide is based on a scenario that shows with extended examples how to manage:
▪ LoRaWAN™ and Cellular connectivity plans in the Connectivity Manager

▪ LoRaWAN™ base stations in the Network Manager
▪ LoRaWAN™ and Cellular devices in the Device Manager.
Handling the OSS API consists in calling web services by the means of REST requests. You are invited
to refer to the [R1] documents for the optional parameters that can be used when applying a
request.
All sections of this document apply to both LoRaWAN™ and Cellular connectivity unless stated to the
contrary.
2 CONVENTIONS
This user guide uses the following conventions:
Convention Description
API Domain Name For readability, the domain name to use for REST requests is never shown.
The domain name to use depends of the platform.
This may be api.thingpark.com when using the ThingPark SaaS platform,
or the domain name may be provided by the Operator when a dedicated
platform is used (e.g. api.the-operator-domain.com).
XML Versus In this guide, REST requests and responses use the default supported
JSON Documents document:
▪ JSON for the Connectivity Manager (only supported in JSON),

▪ XML for the Network Manager and the Device Manager.
Usage of JSON documents can be activated by adding an Accept HTTP
header in REST requests:
▪ Accept: application/json
Response Extract For all REST request shown in this guide, only a response extract with the
relevant content is given.

3 THINGPARK SOLUTION OVERVIEW
The ThingPark set consists of three main key components:
▪ ThingPark Wireless – OSS and core network

▪ ThingPark Market
▪ ThingPark X
ThingPark is a modular solution enabling NW Operators to deploy ThingPark Wireless only; with
ThingPark Market; with ThingPark X, or all components together.
The System Management Platform (SMP) is a software layer, which serves all ThingPark platform
modules such as the billing and the BPM engine.
Operator & Enterprise Application Servers

On-Line Shops
OSS & BSS Management
API Layer
ThingPark OS ThingPark Wireless Core NW & OSS ThingPark X

ThingPark Enterprise
User Portal Store (E-Shop) Operator Connectivity Address Usage Record Supervision, System OCP Edition SaaS Edition RMC
Manager Manager Manager Manager (UDR) Monitoring, Management
Alarms Platform (SMP)
BPM Engine Market
Drivers Connectors
Wireless Device Network

Logger Manager Manager LTE Security Geo-Location
Vendor Supplier Billing & EPC Server Server
Manager Charging ETSI M2M ETSI M2M
Manager Connectors
Net GSCL NSCL
Spectrum Network LoRaWANTM LoRaWANTM

Analysis Tool Survey Network Join Server ²
Local GW (GSCL)
Server
LoRaWANTM LRR (Gateway)

Any Device
Radio Network TPW Air Interface Message Broker Cluster Computing
Planning Tool Dimensioning Tool (Kafka) (Spark) LoRaWANTM /LTE Devices
Figure 1 – ThingPark Solution Architecture Description High Level Product Illustration

Please note that the modules above may be representing a physical server, a function, a service or a business support layer
as part of the overall ThingPark solution and not necessarily a physical HW server.

4 SINGLE-SIGN-ON AUTHENTICATION GENERAL PROCESS
Authentication and authorization on ThingPark Wireless OSS API rely on ThingPark Single-Sign-On
(SSO) framework which is part of ThingPark SMP API:
3. Access Code verification
ThingPark ThingPark
Wireless OSS SMP
2. Bootstrap using
Access Code 1. Authentication &
Access Code generation
4. Access granted to
OSS API
Third-party
Application
Figure 2 – ThingPark Single-Sign-On (SSO) framework
Consequently:
(1) Authentication & Access Code generation
The Application must use the SMP API to authenticate and generate an access code before accessing
the OSS API.
(2) Bootstrap using Access code
The access code is required to access the Connectivity Manager, a Network Manager subscription or
a Device Manager subscription in the OSS API.
(3) Access Code verification
The OSS API validates the access code with SSO.
(4) Access granted to OSS API
The Application is given access to the OSS API.
The SSO Authentication Process can be used by an Administrator, and additionally by an Application
for the Device Manager only. For more information about how to log in with examples, see:
▪ 5 Using the Connectivity Manager OSS API

▪ 6 Using the Network Manager OSS API
▪ 7 Using the Device Manager OSS API.
5 USING THE CONNECTIVITY MANAGER OSS API
This section explains and illustrates how to reproduce the features available in the Connectivity
Manager GUI using the OSS API to manage connectivity plans. It is composed of a sequence of tasks
that can reuse results from one task to another.
ThingPark SMP API is by default in xml format and can be set in json. The Connectivity Manager API is
in json format only. For more information about the APIs used in this section, see [R1].
5.1 Logging In with Administrator Credentials

This task shows how to apply the authentication process described in 4 Single-Sign-On Authentication
General Process with Administrator credentials.
The examples in this section use the following values:
Required Information Example
Administrator ThingPark login john.doe@acme.com
Administrator ThingPark password johndoepassword
Connectivity Supplier ID acme-cs
5.1.1 Authenticating the Administrator

This task shows how to authenticate the Administrator using the SMP API which includes the
ThingPark Single-Sign-On (SSO) framework.
The command is an HTTP POST request where you provide:
▪ The Administrator credentials (login and password) into the HTTP request content within an
XML document.
1. In your application, execute a REST request using the following example:

>> POST /thingpark/smp/rest/admins/login
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>

<ns2:login xmlns:ns2="http://www.actility.com/smp/ws/admin">
<login>john.doe@acme.com</login>
<password>johndoepassword</password>
</ns2:login>
2. Check your output with the response extract:

<< 200 OK
Set-Cookie: JSESSIONID=OtRcElEINlVRYrJekt-aD8JE.smp; path=/thingpark/smp; secure; HttpOnly

<thingparkID>tpk-100000999</thingparkID>
<sessionToken>ea9a77577f67d882</sessionToken>
</ns2:login>

3. To keep going with the scenario, take note of:
▪ The Administrator ThingPark ID
▪ The Session Cookie and the Session Token to use all along the SMP API session.
5.1.2 Generating a Connectivity Supplier Access Code as an Administrator

This task shows how to generate a Connectivity Supplier Access Code as an Administrator using the
SMP API which includes the ThingPark Single-Sign-On (SSO) framework.
The command is an HTTP POST request where you:
▪ Provide:
o The Administrator ThingPark ID into the requested URL
o The targeted Connectivity Supplier ID into the HTTP request content within an XML
document
o The Session Cookie into the HTTP request content within the Cookie header.
▪ Append:
o The Session Token to the requested URL.
1. In your application, execute a REST request using the following example.

Note: TPW_CS is the Connectivity Manager module ID in the OSS API.
>> POST /thingpark/smp/rest/admins/tpk-100000999/accessCode?sessionToken=ea9a77577f67d882
Cookie: JSESSIONID=OtRcElEINlVRYrJekt-aD8JE.smp

<ns:accessCode xmlns:ns="http://www.actility.com/smp/ws/admin">
<supplierID>acme-cs</supplierID>
<moduleID>TPW_CS</moduleID>
</ns:accessCode>

<< 200 OK

<ns2:accessCode xmlns:ns2="http://www.actility.com/smp/ws/admin">
<accessCode>YT10cGstMTAwMDcyODUzO2g9NTM3YjdjMTM1OTNkNzIwYjZiMWU4MzVlNGI2OTAwMWU4NWQ1MDhh
NzczYjg4NTRlZWQ3YzZjZjE4MzY0YzdiMjttPVRQV19DUztzPWFjdGlsaXR5LWNzO3Q9MjAxNi0xMi0xNlQxMDo1NT
o0MS4wMzgrMDE6MDA=
</accessCode>
</ns2:accessCode>

▪ The access code required to bootstrap the Connectivity Manager OSS API session.

5.1.3 Logging Out from the SMP API Session
Once you have got the Connectivity Manager access code, you do not need anymore the SMP API
session, and you have to log out.
▪ Provide the Session Cookie into the HTTP request content within the Cookie header
▪ Append the Session Token to the requested URL.

>> POST /thingpark/smp/rest/admins/logout;sessionToken=ea9a77577f67d882
Content-Type: application/json

<< 200 OK
5.1.4 Bootstrapping the Connectivity Manager OSS API Session

The access code you have generated in 5.1.2 Generating a Connectivity Supplier Access Code as an
Administrator allows you to get:
▪ The targeted Connectivity Manager HREF, which is the base URL you work with
▪ The Session Cookie to set in the Cookie header for any API request based on the Connectivity
Manager HREF
▪ The Session Token to append to the base URL for any API request based on the Connectivity
Manager HREF.
1. In your application, execute a REST request using the following example with your access code:
>> GET /thingpark/wirelessAdmin/rest/admins/suppliers?adminAccessCode=YT10cGstMTAwMDcyODUz
O2g9NTM3YjdjMTM1OTNkNzIwYjZiMWU4MzVlNGI2OTAwMWU4NWQ1MDhhNzczYjg4NTRlZWQ3YzZjZjE4MzY0YzdiMj
ttPVRQV19DUztzPWFjdGlsaXR5LWNzO3Q9MjAxNi0xMi0xNlQxMDo1NTo0MS4wMzgrMDE6MDA=

<< 200 OK
Set-Cookie: PHPSESSID=rqsrg73538u2344tplfd6imdb1; path=/; secure; HttpOnly
{
"success": true,
"data": {
"supplier": {
"ID": "acme-cs
"href": "\/admins\/suppliers\/3",
},
"sessionToken": "ebe0eae2b878725184cb6f69f5393574"
}
}

▪ The HREF value to use for the Connectivity Manager
▪ The Session Cookie and the Session Token to use all along the OSS API session.
5.2 Creating a Connectivity Plan

You can create a new connectivity plan on the connectivity supplier account using the HTTP POST
request.
There are LoRaWAN™ connectivity plans and cellular connectivity plans. If the connectivity
information is not specified, the connectivity plan is by default LoRaWAN™.
Connectivity Supplier HREF \/admins\/suppliers\/3
Session Cookie PHPSESSID=rqsrg73538u2344tplfd6imdb1
Session Token ebe0eae2b878725184cb6f69f5393574

>> POST /thingpark/wirelessAdmin/rest/admins/suppliers/3/connectivityPlans?sessionToken=eb
e0eae2b878725184cb6f69f5393574
Cookie: PHPSESSID=rqsrg73538u2344tplfd6imdb1
{
"data": {
"ID": "acme-cs\/cp001",
"uplinkRate": "10.0",
...
}
}

<< 201 Created
{
"success": true,
"data": ""
}

5.3 Listing the Connectivity Plans
You can retrieve all the existing connectivity plans created on the connectivity supplier account using
the HTTP GET request. This task is useful to retrieve a connectivity plan HREF. This information is
required for many operations you want to perform on a connectivity plan.
There are LoRaWAN™ connectivity plans and cellular connectivity plans. If the connectivity
information is not specified, the connectivity plan is by default LoRaWAN™.
Connectivity Supplier HREF \/admins\/suppliers\/3

>> GET /thingpark/wirelessAdmin/rest/admins/suppliers/3/connectivityPlans?sessionToken=ebe
0eae2b878725184cb6f69f5393574

<< 200 OK
{
"success": true,
"data": [{
"ID": "acme-cs\/acme-cp001",
"localization_value": "{\"b2cName\":\"acme-cp001\",\"b2cDescription\":\"Acme Connect
ivity Plan Level One\"}",
"commercialName": "acme-cp001",
"commercialDescription": " Acme Connectivity Plan Level One ",
"href": "\/admins\/suppliers\/3\/connectivityPlans\/43",
"provID": "TSP_ACME-CS.43"
}, {
...
}],
"more": false
}

▪ The HREF value of a connectivity plan.

5.4 Retrieving the Connectivity Plan Configuration
You can retrieve all the details of the connectivity plan you want using the HTTP GET request.
If you want to use the connectivity plan to create a device, the connectivity plan must have the same
type of connectivity than the device you want to create.
Connectivity Plan HREF \/admins\/suppliers\/3\/connectivityPlans\/43

GET /thingpark/wirelessAdmin/rest/admins/suppliers/3/connectivityPlans/43?sessionToken=ebe
0eae2b878725184cb6f69f5393574

<< 200 OK
{
"success": true,
"data": {
"provID": "TSP_ACME-CS.43",
"ackedUplinkFrame": "1",
"downlinkTransmission": "1",
...
}
}
5.5 Editing a Connectivity Plan

You can update a connectivity plan using the PUT REST request to modify one of its parameters.
In this example, the uplink rate parameter of the connectivity plan is modified.
Connectivity Plan HREF \/admins\/suppliers\/3\/connectivityPlans\/43

>> PUT /thingpark/wirelessAdmin/rest/admins/suppliers/3/connectivityPlans/43?sessionToken=
ebe0eae2b878725184cb6f69f5393574
{
"data": {
"ID": "acme-cs\/ acme-cp001",
"uplinkRate": "20.0",
…
}
}

<< 200 OK
5.6 Deleting a Connectivity Plan

You can delete a connectivity plan using the HTTP DELETE request.
The example uses the following values:
Connectivity Supplier HREF \/admins\/suppliers\/3\/connectivityPlans\/43

>> DELETE /thingpark/wirelessAdmin/rest/admins/suppliers/3/connectivityPlans/43?sessionTok
en=ebe0eae2b878725184cb6f69f5393574

<< 204 No Content

6 USING THE NETWORK MANAGER OSS API
The Network Manager only applies to LoRaWAN™ connectivity.
It explains and illustrates how to reproduce the features available in the Network Manager GUI using
the OSS API to manage LoRaWAN™ base stations. It is composed of a sequence of tasks that can
reuse results from one task to another.
ThingPark SMP and Network Manager APIs are by default in xml format and can be set in json. For
more information about the APIs used in this section, see [R1].
6.1 Logging In with Administrator Credentials

Network Supplier ID acme-np
6.1.1 Authenticating the Administrator

XML document.

</ns2:login>

<< 200 OK

</ns2:login>

6.1.2 Generating a Network Partner Access Code as an Administrator

This task shows how to generate a Network Partner Access Code as an Administrator using the SMP
API which includes the ThingPark Single-Sign-On (SSO) framework.
▪ Provide:
o The targeted Network Partner ID into the HTTP request content within an XML
document
▪ Append:

Note TWP_NP is the Network Partner module ID in the OSS API.

<supplierID>acme-np</supplierID>
<moduleID>TPW_NP</moduleID>
</ns:accessCode>

<< 200 OK

<accessCode>YT10cGstMTAwMDAwMjQxO2g9YzA0MjY1MGRhMmI5YzQ2OWVmNWIyMTYyOWQxZWZiOWM7bT1UUFdf
TlA7cz1hY3RpbGl0eS1wcy1zdXBwbGllcjt0PTIwMTUtMTEtMjVUMTA6Mzc6NTMuMDYxKzAxOjAw
</accessCode>
</ns2:accessCode>

▪ The access code required to bootstrap the Network Manager OSS API session.

6.1.3 Logging Out from the SMP API Session
Once you have got the Network Partner access code, you do not need anymore the SMP API session,
and you have to log out.

>> POST /thingpark/smp/rest/admins/logout;sessionToken=ea9a77577f67d882
<< 200 OK
6.1.4 Bootstrapping the Network Manager OSS API Session

The access code you have generated in 6.1.2 Generating a Network Partner Access Code allows you
to get:
▪ The targeted Network Partner HREF, which is the base URL you work with
▪ The Session Cookie to set in the Cookie header for any API request based on the Network
Partner HREF
▪ The Session Token to append to the base URL for any API request based on the Network
Partner HREF.
>> GET /thingpark/wireless/rest/partners?adminAccessCode=YT10cGstMTAwMDAwMjQxO2g9YzA0MjY1M
GRhMmI5YzQ2OWVmNWIyMTYyOWQxZWZiOWM7bT1UUFdfTlA7cz1hY3RpbGl0eS1wcy1zdXBwbGllcjt0PTIwMTUtMTE
tMjVUMTA6Mzc6NTMuMDYxKzAxOjAw&type=SUPPLIER

<< 200 OK
Set-Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; path=/thingpark/wireless; secure; Htt
pOnly

<partners>
<partner>
<href>/partners/139</href>
</partner>
<user>
<firstName>John</firstName>
<lastName>Doe</lastName>
</user>
<sessionToken>bb32bade5c813448</sessionToken>
...
</partners>

▪ The HREF value to use for the Network Partner
6.2 Creating a Base Station

Creating a base station requires first to retrieve a base station profile, then to declare the base
station in the system.
Required Information Example Note
BS name ACME BS 1
LRR UUID 7076FF-024B0B030008 Recommended

LRR ID 08060999 Still supported for version
compatibility, and automatically
generated when LRR UUID is
provided.
Serial Marketing Number 9999-KE-9999-9999
6.2.1 Retrieving a Base Station Profile

You can retrieve a base station profile by listing the existing base station profiles.
A base station profile is required to add a base station in the system.
1. In your application, execute the following REST request using the following example with your
Network Partner HREF, Session Token and Session Cookie:
>> GET /thingpark/wireless/rest/partners/139/bsProfiles?sessionToken=bb32bade5c813448
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa

<< 200 OK

<ns2:bsProfiles xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<briefs>
<brief>
<commercialName>ACME Outdoor BS (Kerlink 868MHz)</commercialName>
<ID>KERL/KE868.1</ID>
</brief>
...
<more>false</more>
</ns2:bsProfiles>
3. To keep going with the scenario, take note of the ID value of one of the base station profiles that
are retrieved.
6.2.2 Declaring a Base Station

The base station profiles must have been listed first to retrieve a base station profile ID.
It is recommended to provide the LRRUUID of the base station to declare it.
1. In your application, execute the following REST request using the following example with the ID
value of the base station profile you retrieved in the previous task:
>> POST /thingpark/wireless/rest/partners/139/bss?sessionToken=bb32bade5c813448

<ns2:bs xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<name>ACME BS 1</name>
<lrrUUID>7076FF-024B0B030008</lrrUUID>
<smn>9999-KE-9999-9999</smn>
<model>
<ID>KERL/KE868.1</ID>
</model>
<state>VALIDATING</state>
</ns2:bs>
2. Check your output with the response extract showing that the new base station has been created
and added to the system:
<< 201 Created
Location: /thingpark/wireless/rest/partners/139/bss/1222
3. Take note of the Base Station HREF information displayed in the Location HTTP response header.
It is required for any REST request you want to perform on this base station.
6.3 Retrieving Base Station Information

This section shows with examples how to retrieve different kinds of information from a base station
after being created. All tasks are standalone.
If the base station has been created using a LRR ID, the LRR UUID is retrieved with a “null” value.
6.3.1 Retrieving Base Station Basic Information

If you want to retrieve information from a specific base station, the base station HREF information
with the base station id is required.

6.3.1.1 LISTING THE BASE STATIONS
You can list all the base stations owned by a Network Partner, for example to retrieve a base station
HREF. Base station HREF is a required information for many operations on base stations.

>> GET /thingpark/wireless/rest/partners/139/bss?sessionToken=bb32bade5c813448

<< 200 OK

<ns2:bss xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<now>2015-11-25T10:39:35.240+01:00</now>
<briefs>
<brief>
<model>
<commercialName>ACME Outdoor BS (Kerlink 868MHz)</commercialName>
<logo>/thingpark/wireless/rest/resources/files/logo/baseStationProfile/5</logo>
</model>
<lrrID>08060999</lrrID>
<state>ACTIVE</state>
...
<href>/thingpark/wireless/rest/partners/139/bss/1222</href>
</brief>
...
</briefs>
<more>false</more>
</ns2:bss>
6.3.1.2 RETRIEVING THE BASE STATION CONFIGURATION

This task shows how to retrieve the configuration of a base station.
>> GET /thingpark/wireless/rest/partners/139/bss/1222?sessionToken=bb32bade5c813448

<< 200 OK

<now>2015-11-25T10:43:06.227+01:00</now>
<occContext>
<version>5</version>
<lastUpdate>2015-11-22T21:45:15+01:00</lastUpdate>
<who>unknown</who>
</occContext>
<smn>9999-KE-9999-9999</smn>

<staticAddress>Hight Street, 999-999 Town</staticAddress>
<customerAdminData/>
<stateSince>2015-11-21T12:19:58.530+01:00</stateSince>
<cnxState>CNX</cnxState>
...
</ns2:bs>
6.3.1.3 RETRIEVING THE BASE STATION STATUS

A base station can have three statuses: INIT, VALIDATING, ACTIVE, SUSPENDED. If the base station is
ACTIVE, you cannot update it.
If you want to change the base station status, see 6.6 Updating a Base Station.

>> GET /thingpark/wireless/rest/partners/139/bss/1222/check?sessionToken=bb32bade5c813448

<< 200 OK

<ns2:check xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
...
</ns2:check>
6.3.1.4 RETRIEVING THE BASE STATION UPLINK/DOWNLINK HISTORY

You can retrieve the last 20,000 uplink/downlink frames of a base station. This number can be
changed by the Operator of the platform.
>> GET /thingpark/wireless/rest/partners/139/bss/1222/frames?sessionToken=bb32bade5c813448

<< 200 OK

<ns2:frames xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<now>2016-05-24T11:34:23.333+02:00</now>
<briefs>
<brief>
<timestamp>2016-05-23T12:00:00+02:00</timestamp>
<up><count>135</count><size>7024</size></up>
<dw><count>51</count><size>111</size></up>
<date>Mon May 23 12:00:00 CET 2016</date>
</brief>
...
<briefs/>
</ns2:frames>

6.3.2 Retrieving the Base Station System
If you want to retrieve information from a specific base station, the base station HREF information
with the base station id is required.
6.3.2.1 RETRIEVING CPU INFORMATION

You can retrieve various information about the CPU of the base station system.
6.3.2.1.1 Retrieving the CPU Status

You can retrieve the status of the CPU of the base station system.
>> GET /thingpark/wireless/rest/partners/139/bss/1222/sys/cpu?sessionToken=bb32bade5c81344
8

<< 200 OK

<ns2:cpu xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<minCPU>
<value>18</value>
<recordedDate>2016-05-11T06:23:21.103+01:00</recordedDate>
</minCPU>
<maxCPU>
<value>100</value>
</maxCPU>
<recordedSince>2016-03-10T15:06:45.303+01:00</recordedSince>
</ns2:cpu>
6.3.2.1.2 Retrieving the CPU Statistics History

You can retrieve an history of the CPU statistics of the base station system.
>> GET /thingpark/wireless/rest/partners/139/bss/1222/sys/cpu/histories?sessionToken=bb32b
ade5c813448

<< 200 OK

<ns2:cpuHistories xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<now>2016-03-10T15:03:19.291+01:00</now>
<briefs>
<brief>
<avgCPU>22</avgCPU>
<devCPU>9</devCPU>

<maxCPU>75</maxCPU>
</brief>
...
</briefs>
</ns2:cpuHistories>
6.3.2.1.3 Retrieving Last Values of Used RAM

You can retrieve the minimum and maximum last values of used RAM of the base station system.
>> GET /thingpark/wireless/rest/partners/139/bss/1222/sys/ram?sessionToken=bb32bade5c81344
8

<< 200 OK

<ns2:ram xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<minRAM>
<value>7</value>
</minRAM>
<maxRAM>
<value>7</value>
</maxRAM>
</ns2:ram>
6.3.2.1.4 Retrieving the RAM History

You can retrieve an history of the RAM of the base station system.
>> GET /thingpark/wireless/rest/partners/139/bss/1222/sys/ram/histories?sessionToken=bb32b
ade5c813448

<< 200 OK

<ns2:ramHistories xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<now>2016-03-10T15:10:08.403+01:00</now>
<briefs>
<brief>
<avgRAM>7</avgRAM>
<maxRAM>7</maxRAM>
</brief>
...
</briefs>
</ns2:ramHistories>

6.3.2.2 RETRIEVING DISK PARTITION INFORMATION
In addition to the contents of the diskConfig element returned by the REST request described in
6.3.1.2 Retrieving the Base Station, you can retrieve the disk partitions status of the base station
system.
In our examples, the disk partition is indexed as zero. If the base station contains several partitions,
each one will be associated with an index (0, 1, 2...). If you want to retrieve the list of the disk
partitions, perform the request described in 6.3.1.2 Retrieving the Base Station.
6.3.2.2.1 Retrieving the Disk Usage

You can retrieve the disk usage of the base station system with a minimum and a maximum
percentage.
>> GET /thingpark/wireless/rest/partners/139/bss/1222/sys/disks/0?sessionToken=bb32bade5c8
13448

<< 200 OK

<ns2:disk xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<minDisk>
<value>58</value>
</minDisk>
<maxDisk>
<value>58</value>
</maxDisk>
</ns2:disk>
6.3.2.2.2 Retrieving the Disk Usage History

You can retrieve the history of the disk usage of the base station system.
>> GET /thingpark/wireless/rest/partners/139/bss/1222/sys/disks/0/histories?sessionToken=b
b32bade5c813448

<< 200 OK

<ns2:diskHistories xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<now>2016-03-10T15:13:28.433+01:00</now>
<briefs>
<brief>

<avgDisk>58</avgDisk>
<maxDisk>58</maxDisk>
</brief>
...
</briefs>
</ns2:diskHistories>
6.3.3 Retrieving RF Cell Reports Information

You can retrieve data from the RF Cell reports of a base station. RF Cell reports are generated by the
base station and sent to Thingpark Wireless Application (TWA).
In our example, the antenna is indexed as zero. If the base station contains several antennas, each
one will be associated with an index (0, 1, 2...). If you want to retrieve the list of the antennas,
perform the request described in 6.3.1.2 Retrieving the Base Station.
6.3.3.1 RETRIEVING THE SCATTERING OF DEVICES

You can retrieve the coordinates of the devices that are in the range of a base station.
>> GET /thingpark/wireless/rest/partners/139/bss/1222/rfcell/ants/0/devicesScattering?sess
ionToken=bb32bade5c813448

<< 200 OK

<ns2:devicesScattering xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<briefs>
<brief>
<eui>2011240000000008</eui>
<loc>
<type>0</type>
<lat>47.51720069783942</lat>
<lon>1.7578125</lon>
</loc>
<rssi>-106.0</rssi>
<snr>1.25</snr>
</brief>
...
</briefs>
<lrrs>
<lrr>
<lat>41.387035</lat>
<lon>2.113095</lon>
</lrr>
...
</lrrs>
</ns2:devicesScattering>

6.3.3.2 RETRIEVING LOGICAL CHANNELS INFORMATION
The following tasks show you how to retrieve data from the logical channels using as an example the
value of the first logical channel, named LC1.
Logical channels are indexed from LC1 to LC16 for UL and DL/RX1, plus LC255 for DL/RX2 logical
channel.
6.3.3.2.1 Retrieving the Duty Cycle

You can retrieve the minimum and maximum values of a duty cycle of the base station.
>> GET /thingpark/wireless/rest/partners/139/bss/1222/rfcell/ants/0/lcs/LC1/dutyCycles?ses
sionToken=bb32bade5c813448

<< 200 OK

<ns2:dutyCycles xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<maxUplinkDC>
<value>7.908010666666666</value>
</maxUplinkDC>
<maxDownlinkDC>
<value>0.048128000000000004</value>
</maxDownlinkDC>
</ns2:dutyCycles>
6.3.3.2.2 Retrieving the Duty Cycle History

>> GET /thingpark/wireless/rest/partners/139/bss/1222/rfcell/ants/0/lcs/LC1/dutyCycles/his
tories?sessionToken=bb32bade5c813448

<< 200 OK

<ns2:histories xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<now>2016-03-10T15:24:35.532+01:00</now>
<briefs>
<brief>
<up><DC>0.0561362962962962</DC></up>
<dw><DC>0.01942725925925928</DC></dw>
</brief>
...
</briefs>
</ns2:histories>

6.3.3.2.3 Retrieving the Spreading Factors Distribution
The Spreading Factors (SF) define the data rate used during devices ‘transmission. SF7 is the fastest,
and SF12 the slowest.

>> GET /thingpark/wireless/rest/partners/139/bss/1222/rfcell/ants/0/lcs/LC1/spreadingFacto
rs/sfDistributions?sessionToken=bb32bade5c813448

<< 200 OK

<ns2:sfDistributions xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<briefs>
<brief>
<sf>7</sf>
<up>
<count>4</count>
<airtime></airtime>
</up>
<dw>
<count>3</count>
<airtime></airtime>
</dw>
</brief>
</briefs>
<up>
<totalCount>4</totalCount>
<totalAirtime></totalAirtime>
</up>
<dw>
<totalAirtime></totalAirtime>
</dw>
</ns2:sfDistributions>
6.3.3.2.4 Retrieving Signal Strength and Noise

You can retrieve the minimum signal strength and noise of the devices located in the range of an
antenna attached to a base station.
For more information about minRSSI and minSNR elements, see [R1].

>> GET /thingpark/wireless/rest/partners/139/bss/1222/rfcell/ants/0/lcs/LC1/signalsAndNois
es?sessionToken=bb32bade5c813448
<< 200 OK

<ns2:signalsAndNoises xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<minRSSI>
<value>-120.0</value>
<deviceEUI>2011240000000008</deviceEUI>
</minRSSI>
<minSNR>
<value>-18.75</value>
<deviceEUI>ACDE48234567ABCD</deviceEUI>
</minSNR>
</ns2:signalsAndNoises>
6.3.3.2.5 Retrieving Signal Strength and Noise Distribution

You can retrieve the signal strength and noise distribution of the devices in the range of an antenna
attached to a base station.
For more information about snDistributions elements, see [R1].

>> GET /thingpark/wireless/rest/partners/139/bss/1222/rfcell/ants/0/lcs/LC1/signalsAndNois
es/snDistributions?sessionToken=bb32bade5c813448

<< 200 OK

<ns2:snDistributions xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<briefs>
<brief>
<level>-69.0</level>
<count>1</count>
</brief>
...
</briefs>
</ns2:snDistributions>
6.3.3.3 RETRIEVING RF CELL INDICATORS

You can retrieve RF Cell indicators elements from the RF Cell Reports such as number of frames
received from the radio (urcv), number of frames received with a CRC error (ucrc), etc.
For more information about RF Cell indicators elements, see [R1].

>> GET /thingpark/wireless/rest/partners/139/bss/1222/rfcell/indicators?sessionToken=bb32b
ade5c813448

<< 200 OK

<ns2:indicators xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<inds>
<ind>
<ID>urcv</ID>
<current>74340</current>
</ind>
...
</inds>
</ns2:indicators>
6.3.3.4 RETRIEVING THE DOWNLINK FRAMES DELIVERY STATUS DISTRIBUTION

The following REST request analyzes the downlink frame delivery status of a base station and
retrieves its distribution.

>> GET /thingpark/wireless/rest/partners/139/bss/1222/rfcell/ants/0/downlinks/statusDistri
butions?sessionToken=bb32bade5c813448

<< 200 OK

<ns2:statusDistributions xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<rx1Failures>
<class>
<value>A</value>
<count>8</count>
</class>
...
</rx1Failures>
<rx2Failures>
<class>
<value>A</value>
<count>17</count>
</class>
...
</rx2Failures>
<totalSent>4287</totalSent>
<totalFailed>70</totalFailed>
</ns2:statusDistributions>
6.3.3.5 RETRIEVING BEACON TRANSMISSIONS STATISTICS

On a base station with LoRaWAN™ class B profile activated, you can retrieve the following statistics:
▪ Total number of beacon transmissions requested by the LRC since LRR startup
▪ Total number of beacon effectively transmitted since LRR startup
▪ The delivery cause of the last beacon transmission.

>> GET /thingpark/wireless/rest/partners/139/bss/1222/rfcell/beacons?sessionToken=bb32bade
5c813448

<< 200 OK

<ns2:beacons xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<totalRequested>16</totalRequested>
<totalSent>16</totalSent>
<lastDeliveryCause>00</lastDeliveryCause>
<lastDeliveryFailedCause>A2</lastDeliveryFailedCause>
<lastDeliveryFailedCauseDate>2017-08-21T10:25:15.859+02:00</lastDeliveryFailedCauseDate>
</ns2:beacons>
6.3.4 Retrieving WAN Reports Information

You can retrieve data from the WAN reports. WAN reports are generated by the base stations and
later sent to ThingPark Wireless OSS.
In our examples, the LRC is indexed by 0. If the base station is associated with two LRCs, each one will
be associated with an index (0, 1). If you want to retrieve the list of the LRCs, perform the request
described in 6.3.1.2 Retrieving the Base Station.
6.3.4.1 RETRIEVING LRC INFORMATION

In addition to the contents of the lrcConfig element returned by the REST request described in
6.3.1.2 Retrieving the Base Station, you can retrieve the following information about an LRC indexed
as zero.

>> GET /thingpark/wireless/rest/partners/139/bss/1222/wans/lrcs/0?sessionToken=bb32bade5c8
13448

<< 200 OK

<ns2:lrc xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<lastUplinkFrame>2016-03-02T15:30:50.729+01:00</lastUplinkFrame>
<lastDownlinkFrame>2016-03-02T14:37:52.779+01:00</lastDownlinkFrame>
<sentIecPacket>209675</sentIecPacket>
<sentIecByte>9305.236000000026</sentIecByte>
<receivedIecPacket>178018</receivedIecPacket>
<receivedIecByte>755.1339999999913</receivedIecByte>
<nbrDisconnection>41</nbrDisconnection>
<maxLatency>
<value>13389</value>

<recordedDate>2016-02-19T17:26:18+01:00</recordedDate>
</maxLatency>
</ns2:lrc>
6.3.4.2 RETRIEVING THE IEC PACKET HISTORY OF AN LRC

An IEC packet contains the uplinks and downlinks data’s packets sent and received between a base
station and an LRC.
For more information about iecPacket elements, see [R1].

>> GET /thingpark/wireless/rest/partners/139/bss/210/wans/lrcs/0/iecPackets
content-type: application/xml
Cookie: JSESSIONID=NuWw3fvusEFqU_LR-HJQ5JiS.twa-01

<< 200 OK

<ns2:iecPackets xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<now>2016-03-10T15:34:11.613+01:00</now>
<briefs>
<brief>
<sent>
<count>117</count>
<byte>5</byte>
</sent>
<received>
<count>103</count>
<byte>0</byte>
</received>
</brief>
…
</briefs>
</ns2:iecPackets>
6.3.4.3 RETRIEVING NETWORK INTERFACE INFORMATION

In addition to the contents of the wanConfig element returned by the REST request described in
6.3.1.2 Retrieving the Base Station, you can retrieve information about the network interfaces of a
base station, such as eth0 (Ethernet connection), wlan0 (WIFI connection), ppp0 (modem
connection), etc.
If the base station is associated to several network interfaces, each one will be associated with an
index (0, 1…). If you want to retrieve the list of the network interfaces, perform the request
described in 6.3.1.2 Retrieving the Base Station.

6.3.4.3.1 Retrieving the Network Interface Status

>> GET /thingpark/wireless/rest/partners/139/bss/1222/wans/ints/0?sessionToken=bb32bade5c8
13448

<< 200 OK

<ns2:int xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<address>172.19.76.114</address>
<totalTxTraffic>163779.53299999953</totalTxTraffic>
<averageTxTraffic>276</averageTxTraffic>
<maxTxTraffic>
<value>50042232</value>
</maxTxTraffic>
...
<activity>2658768</activity>
<averageLatency>199</averageLatency>
<deviationLatency>53</deviationLatency>
<maxLatency>
<value>3365</value>
</maxLatency>
<minCellSignal/>
</ns2:int>
6.3.4.3.2 Retrieving the Network Interface Bitrates History

You can retrieve the bitrates history of a network interface.
>> GET /thingpark/wireless/rest/partners/139/bss/1222/wans/ints/0/bitrates?sessionToken=bb
32bade5c813448

<< 200 OK

<ns2:bitrates xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<now>2016-03-10T15:41:01.743+01:00</now>
<briefs>
<brief>
<tx>
<avgBitRate>264</avgBitRate>
<maxBitRate>4384</maxBitRate>
</tx>
<rx>
<avgBitRate>280</avgBitRate>
<maxBitRate>4256</maxBitRate>
</rx>
</brief>

...
</briefs>
</ns2:bitrates>
6.3.4.3.3 Retrieving the Network Interface Roundtrips History

You can retrieve the roundtrips history of a network interface.
>> GET /thingpark/wireless/rest/partners/139/bss/1222/wans/ints/0/roundTrips?sessionToken=
bb32bade5c813448

<< 200 OK

<ns2:roundTrips xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<now>2016-03-10T15:41:03.742+01:00</now>
<briefs>
<brief>
<avgRT>212</avgRT>
<maxRT>358</maxRT>
<devRT>49</devRT>
</brief>
...
</briefs>
</ns2:roundTrips>
6.3.4.4 RETRIEVING WAN INDICATORS

For more information about WAN indicators elements, see [R1].
>> GET /thingpark/wireless/rest/partners/139/bss/1222/wans/indicators?sessionToken=bb32bad
e5c813448

<< 200 OK

<ns2:indicators xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<inds>
<ind>
<ID>ldrp</ID>
<current>0</current>
</ind>
</inds>
</ns2:indicators>

6.4 Administering a Base Station
This section explains and illustrates how to remotely execute administration commands on a base
station.
Important: Only one command can be processed by the base station at a given time. When a
command is being processed, the command must be completed before a new command can be
initiated.

Base Station HREF partners/139/bss/1222
Session Cookie JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa
Session Token bb32bade5c813448
6.4.1 Asynchronous and Synchronous Commands

Asynchronous and synchronous commands, both triggered by a REST request, are two types of
commands that work differently.
6.4.1.1 ASYNCHRONOUS COMMANDS

The command execution takes some time and the result is not returned in the REST response.
Another REST request is required to get the result.
Available asynchronous commands are:
▪ Upgrade LRR software

▪ Start/stop RF cell
▪ Reboot
▪ Restart LRR software
▪ Open/Close reverse SSH tunnel
▪ Open SSH terminal
▪ Backup/restore LRR software configuration
▪ Start/Cancel radio spectrum analysis
▪ Update location
▪ Update RF Region
▪ Update log configuration
▪ Set gain and cable loss for all antennas
▪ Set fine-timestamps decryption keys.
For more information about each command, see [R1].

6.4.1.2 SYNCHRONOUS COMMANDS
The command execution is immediate and the result is returned in the REST response.
Available synchronous commands are:
▪ Get LRR software version

▪ Get RF cell status
▪ Get system uptime
▪ Get LRR software uptime
▪ Get reverse SSH tunnel status
▪ Get the backup version
▪ Get the RF scan status
▪ Get location status
▪ Get RF Region status
▪ Get log configuration
▪ Get gain and cable loss for all antennas
▪ Get fine-timestamps decryption keys.
For more information about each command, see [R1].
6.4.2 Executing an Asynchronous Command

This task shows how to reboot a base station by executing an asynchronous command. For more
information about how to use other asynchronous commands, see [R1].
Before you begin: Any command execution requires as mandatory parameter the occContext
information from which the resource will be updated. If you have not the occContext information of
the base station you want to update, perform a GET request on the targeted base station HREF.

>> POST /thingpark/wireless/rest/partners/139/bss/1222/admins/reboot?sessionToken=bb32bade
5c813448

<ns2:reboot xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<occContext>
</occContext>
</ns2:reboot>

<< 200 OK

<ns2:reboot xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<occContext>

<who>John Doe</who>
</occContext>
</ns2:reboot>
3. You have now to retrieve the result of the asynchronous command by performing the following
task.
6.4.3 Retrieving the Result of an Asynchronous Command

This task shows how to retrieve the result of an asynchronous command previously executed.
>> GET /thingpark/wireless/rest/partners/139/bss/1222/admins/lastCmdStatus?sessionToken=bb
32bade5c813448

<< 200 OK

<ns2:lastCmdStatus xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<now>2015-11-25T11:02:25+01:00</now>
<lastCmdRequestDate>2015-11-25T10:59:09+01:00</lastCmdRequestDate>
<lastCmdType>REBOOT</lastCmdType>
<lastCmdCompletionStatus>COMPLETED</lastCmdCompletionStatus>
<lastCmdCompletionDate>2015-11-25T10:59:19+01:00</lastCmdCompletionDate>
...
</ns2:lastCmdStatus>
6.4.4 Executing a Synchronous Command

This task shows how to retrieve the system uptime of a base station by executing a synchronous
command.
For more information about how to use other asynchronous commands, see [R1].

>> GET /thingpark/wireless/rest/partners/139/bss/1222/admins/systemUptime?sessionToken=bb3
2bade5c813448

<< 200 OK

<ns2:systemUptime xmlns:ns2="http://www.actility.com/tpkwrls/ws/partner">
<completionStatus>COMPLETED</completionStatus>
<lastsystemReboot>2015-11-25T10:59:19+01:00</lastsystemReboot>
</ns2:systemUptime>

6.5 Managing the Base Station Alarms
Base Station HREF partners/139/bss/1222
6.5.1 Listing the Base Station Alarms

You can list all the alarms of a base station.
>> GET /thingpark/wireless/rest/partners/139/bss/1222/alarms?sessionToken=bb32bade5c813448

<< 200 OK

<ns2:alarms xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<more>false</more>
<briefs>
<brief>
<creationTimestamp>2015-11-21T12:14:55.760+01:00</creationTimestamp>
<updateTimestamp>2015-11-22T21:44:54.773+01:00</updateTimestamp>
<ID>102</ID>
<state>1</state>
<occurrence>2</occurrence>
<addInfo>2009</addInfo>
<acked>true</acked>
<ackedTimestamp>2015-11-24T20:00:24.711+01:00</ackedTimestamp>
<ackedInfo>John Doe</ackedInfo>
<href>
/thingpark/wireless/rest/partners/139/bss/1222/alarms/5650522fe4b04c7aee5da59e
</href>
</brief>
...
</briefs>
</ns2:alarms>
3. If you want to perform the next task to acknowledge an alarm, take note of its HREF value.

6.5.2 Acknowledging an Alarm
You can acknowledge the alarm of your choice using its HREF value.
>> POST /thingpark/wireless/rest/partners/139/bss/1222/alarms/5650522fe4b04c7aee5da59e/ack
?sessionToken=bb32bade5c813448

<< 201 Created
6.5.3 Acknowledging the Alarms

You can acknowledge simultaneously all the alarms of a base station.
If you want to associate the REST request with filter criteria to limit the scope of the
acknowledgment, for instance to only acknowledge an alarm level, see [R1].

>> POST /thingpark/wireless/rest/partners/139/bss/1222/alarms/ack?sessionToken=bb32bade5c8
13448

<< 201 Created
6.6 Updating a Base Station

If you want to modify any base station information, you have to update the base station. The base
station must be in active state. As the OCC context is required, this task makes you first retrieve it.
Notes
▪ If the base station has been created using a LRR UUID, the LRR UUID cannot be modified.
▪ If the base station has been created using a LRR ID, the LRR UUID is returned with a “null”
value.
1. In your application, execute a GET REST request using the following example to retrieve the base
station version number and the base station state:
>> GET /thingpark/wireless/rest/partners/139/bss/1222?sessionToken=bb32bade5c813448

<< 200 OK

<now>2015-11-25T10:43:06.227+01:00</now>
<occContext>
<who>unknown</who>
</occContext>
...
<state>INIT</state>
...
</ns2:bs>
3. Take note of the version information in the occContext element.
4. Execute a PUT REST request to update the base station using the following example:
>> PUT /thingpark/wireless/rest/partners/139/bss/1222?sessionToken=bb32bade5c813448

<occContext>
</occContext>
<name>New ACME BS name</name>
<smn>8888-KE-8888-8888</smn>
</ns2:bs>
5. Check your output with the response extract.

The version number is increased by an increment of one.
<< 200 OK

<now>2015-11-25T10:59:09.211+01:00</now>
<occContext>
<who>John Doe</who>
</occContext>
<name>New ACME BS name</name>
<smn>8888-KE-8888-8888</smn>
...
</ns2:bs>

6.7 Deleting a Base Station
Before you begin: If you have not the HREF information of the base station you want to delete,
execute a GET REST request to retrieve it. For more information, see 6.5.1 Listing the Base Stations.
1. Execute a REST request using the following example with your base station HREF:
>> DELETE /thingpark/wireless/rest/partners/139/bss/1222?sessionToken=bb32bade5c813448

<< 204 No Content
6.8 Logging Out from the Network Manager Session

You can log out the Network Manager using your session cookie and session token.

>> GET /thingpark/wireless/rest/partners/logout?sessionToken=bb32bade5c813448

<< 204 No Content

7 USING THE DEVICE MANAGER OSS API
This section explains and illustrates how to reproduce the features available in the Device Manager
GUI using the OSS API to manage LoRaWAN™ devices. It is composed of a sequence of tasks that can
reuse results from one task to another.
ThingPark SMP and Device Manager APIs are by default in xml format, and can be set in json. For
more information about the APIs used in this section, see [R1].
7.1 Logging In with Administrator or Application Credentials

The Device Manager API enables the login either as an Administrator or as an Application.
7.1.1 Logging In with Administrator Credentials

Subscriber ID 199999999
7.1.1.1 AUTHENTICATING THE ADMINISTRATOR

XML document.


</ns2:login>

<< 201 Created

</ns2:login>

7.1.1.2 GENERATING A SUBSCRIBER ACCESS CODE AS AN ADMINISTRATOR

This task shows how to generate a Subscriber Access Code as an Administrator using the SMP API
which includes the ThingPark Single-Sign-On (SSO) framework.
▪ Provide:
o The targeted Subscriber ID into the HTTP request content within an XML document
▪ Append:

Note TWP_SUBS is the Subscriber module ID in the TWA configuration.

<subscriberID>199999999</subscriberID>
<moduleID>TPW_SUBS</moduleID>
</ns:accessCode>

<< 201 Created

<accessCode>YT10cGstMTAwMDAwMjQxO2g9ZDYxNGFlMzYwYzljYjlkYWQwMzM3MzNlMGQ5NzdjYTk7bT1UUFdf
U1VCUzt0PTIwMTUtMTEtMjhUMDc6NDY6NTMuNjI5KzAxOjAwO3c9MTAwMDAwNjY2</accessCode>
</ns2:accessCode>

▪ The access code required to bootstrap the Device Manager OSS API session.
7.1.1.3 LOGGING OUT FROM THE SMP API SESSION
Once you have got the Subscriber access code, you do not need anymore the SMP API session, and
you have to log out.

>> POST /thingpark/smp/rest/admins/logout?sessionToken=ea9a77577f67d882

<< 201 Created
7.1.1.4 BOOTSTRAPPING THE DEVICE MANAGER OSS API SESSION

The access code you have generated in 7.1.1.2 Generating a Subscriber Access Code allows you to
retrieve:
▪ The targeted Device Manager HREF, which is the base URL you work with
▪ The Session Cookie to set in the Cookie header for any API request based on the Device
Manager HREF
▪ The Session Token to append to the base URL for any API request based on the Device
Manager HREF.
GET /thingpark/wireless/rest/customers/?adminAccessCode=YT10cGstMTAwMDAwMjQxO2g9ZDYxNGFlMz
YwYzljYjlkYWQwMzM3MzNlMGQ5NzdjYTk7bT1UUFdfU1VCUzt0PTIwMTUtMTEtMjhUMDc6NDY6NTMuNjI5KzAxOjAw
O3c9MTAwMDAwNjY2

<< 200 OK
pOnly

<customers>
<subscription>
<href>/subscriptions/47</href>
</subscription>
<user>
<firstName>Alice</firstName>
<lastName>Smith</lastName>
</user>
...
</customers>

▪ The HREF value to use for the Device Manager
7.1.2 Logging In with Application Credentials

General Process with Application credentials.

Application ThingPark login application@acme.com
Application ThingPark password Applicationpassword
Application Subscription HREF /applications/123/subscriptions/997
7.1.2.1 GRANTING PERMISSIONS TO THE APPLICATION

To allow an Application to access the Device Manager subscription, you have to, as a Supplier, to
configure the ThingPark Wireless Device Manager permissions in the Application manifest frame.
1. Enter the Actility ThingPark Wireless Supplier GUI.
For more information, see [R3].
2. In the navigation panel of the Supplier tab, click Application.
3. In the Search frame of the Applications panel, click Search without specifying any criteria.
4. From the application list frame, click Device Manager, then click Edit.
5. In the Application manifest frame, click Add.
6. In the Add a permission dialog box that opens, the following permissions are available in the
Type list:

▪ Read AS routing profile:
allows the application to browse AS routing profiles.
▪ Read network subscription:
allows the application to browse network subscriptions.
▪ Read node:
allows the application to browse devices.
▪ Write AS routing profile:
allows the application to create or update AS routing profiles.
▪ Write node:
allows the application to configure the devices (without the permission to
activate/deactivate the devices).
▪ Write node activation:
allows the application to activate devices.
7. Select Read AS routing profile in the Type list to add the permission.
8. Click Add.
9. Repeat for all items in the list.
10. Click Close.
All the permissions you have allowed to the Application will be available for the Subscriber when
purchasing the offer.
7.1.2.2 AUTHENTICATING THE APPLICATION

This task shows how to authenticate the Application using the SMP API.
▪ Provide the Application credentials (login and password) into the HTTP request content
within an XML document.

>> POST /thingpark/smp/rest/applications/login

<ns2:login xmlns:ns2="http://www.actility.com/smp/ws/application">
<login>application@acme.com</login>
<password>applicationpassword</password>
</ns2:login>

<< 201 Created

<ns2:login xmlns:ns2="http://www.actility.com/smp/ws/application">
<href>/applications/123</href>
</ns2:login>

7.1.2.3 GENERATING A SUBSCRIBER ACCESS CODE AS AN APPLICATION

This task shows how to generate a Subscriber Access Code as an Administrator using the SMP API.
▪ Provide:
o The Application Subscription HREF into the requested URL
▪ Append:

>> POST /thingpark/smp/rest/applications/123/subscriptions/997/places/DEFAULT/applications/acc
essCode?sessionToken=ea9a77577f67d882

<< 200 OK

<ns2:accessCode xmlns:ns2="http://www.actility.com/smp/ws/application">
<accessCode>YT10cGstMTAwMDAwMjQxO2g9ZDYxNGFlMzYwYzljYjlkYWQwMzM3MzNlMGQ5NzdjYTk7bT1UUFdf
U1VCUzt0PTIwMTUtMTEtMjhUMDc6NDY6NTMuNjI5KzAxOjAwO3c9MTAwMDAwNjY2</accessCode>
</ns2:accessCode>

▪ The access code required to bootstrap the Device Manager OSS API session.
7.1.2.4 LOGGING OUT FROM THE SMP API SESSION

Once you have got the Subscriber access code, you do not need anymore the SMP API session, and
you have to log out.

>> POST /thingpark/smp/rest/applications/logout?sessionToken=ea9a77577f67d882


<< 201 Created
7.1.2.5 BOOTSTRAPPING THE DEVICE MANAGER OSS API SESSION

The access code you have generated in 7.1.2.3 Generating a Subscriber Access Code as an Application
allows you to retrieve:
▪ The targeted Device Manager HREF, which is the base URL you work with
▪ The Session Cookie to set in the Cookie header for any API request based on the Network
Partner HREF
▪ The Session Token to append to the base URL for any API request based on the Network
Partner HREF.
GET /thingpark/wireless/rest/customers/?appAccessCode=YT10cGstMTAwMDAwMjQxO2g9ZDYxNGFlMzYw
YzljYjlkYWQwMzM3MzNlMGQ5NzdjYTk7bT1UUFdfU1VCUzt0PTIwMTUtMTEtMjhUMDc6NDY6NTMuNjI5KzAxOjAwO3
c9MTAwMDAwNjY2

<< 200 OK
pOnly

<customers>
<subscription>
<href>/subscriptions/47</href>
</subscription>
<user>
<firstName>Alice</firstName>
<lastName>Smith</lastName>
</user>
...
</customers>

▪ The HREF value to use for the Device Manager

7.2 Creating Devices
You can create LoRaWAN™ and cellular devices, one by one or by mass import. It requires first to
prepare the prerequisite information, then to declare the device or devices.
7.2.1 Preparing the Device Prerequisite Information

Preparing the prerequisite information to create a device is a long process that requires to perform
tasks in a recommended order. It involves network subscriptions, device profiles, AS routing profiles,
and Application Servers that you will retrieve or create.
Device Manager HREF /subscriptions/47
7.2.1.1 LISTING THE NETWORK SUBSCRIPTIONS

This task allows you to list all the network subscriptions of the Subscriber. A network subscription is
mandatory to activate a device.
The network subscriptions are allocated from SMP and cannot be created from the ThingPark
Wireless OSS API. In the Device Manager GUI, network subscriptions are labeled as connectivity
plans.
There are LoRaWAN™ network subscriptions and cellular network subscriptions. The network
subscriptions must have the same connectivity than the device you want to create.

>> GET /thingpark/wireless/rest/subscriptions/47/networkSubscriptions?sessionToken=bb32bad
e5c813448

<< 200 OK

<ns2:networkSubscriptions xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<briefs>
<brief>
<commercialName>Connectivity Plan</commercialName>
<ID>acme-cs/cp1</ID>
<used>23</used>
<granted>100</granted>
<href>
/thingpark/wireless/rest/subscriptions/47/networkSubscriptions/98
</href>

<connectivity>LORAWAN</connectivity>
</brief>
</briefs>
</ns2:networkSubscriptions>
3. To keep going with the scenario and according to the connectivity (LoRaWAN™ or cellular) you
want to use, take note of the:
▪ ID value
▪ HREF value
of the network subscription you want to be associated with the device.
7.2.1.2 RETRIEVING A NETWORK SUBSCRIPTION

You can retrieve all the details of the network subscription you want using its HREF in an HTTP GET
request. The connectivity plan must have the same connectivity than the device you want to create.
If an HSM group ID is returned, it indicates that the network subscription has the Hardware Security
Module (HSM) option activated. This option, only applicable to LoRaWAN™ OTAA devices, allows to
store the device’s AppKey with an enforced security, using master secrets only known by the HSM.

>> GET /thingpark/wireless/rest/subscriptions/47/networkSubscriptions/98?sessionToken=bb32
bade5c813448

<< 200 OK
<ns2:networkSubscription xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<ID>actility-cs/testing</ID>
<commercialName>Actility Testing CP</commercialName>
<supplier>
<commercialName>Actility Connectivity Supplier</commercialName>
<ID>actility-cs</ID>
</supplier>
<connectivity>LORAWAN</connectivity>
<hsmGroupID>HSM-group1<hsmGroupID>
...
</ns2:networkSubscription>
3. If you want to create a LoRaWAN™ OTAA device and if an HSM group ID is returned, take note of
its value to keep going with the scenario. You will need it when declaring the OTAA device.
7.2.1.3 LISTING THE DEVICE PROFILES

This task allows you to retrieve the existing device profiles registered in the system and is mandatory
to create a device.
The device profiles are allocated by the Operator and cannot be created from the ThingPark Wireless
OSS API.

>> GET /thingpark/wireless/rest/subscriptions/47/deviceProfiles?sessionToken=bb32bade5c813
448

<< 200 OK

<ns2:deviceProfiles xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<briefs>
<brief>
<commercialName>LoRaMote v1</commercialName>
<ID>LoRaMote.1</ID>
<typeMAC>LoRaMAC</typeMAC>
</brief>
...
</briefs>
<more>false</more>
</ns2:deviceProfiles>

▪ The ID of the device profile.
7.2.1.4 ASSOCIATING AN AS ROUTING PROFILE

You can retrieve or create an AS routing profile to associate with the device you want to create.
When creating a device, an AS routing profile is required to:
▪ Give LoRaWAN™ or cellular connectivity to the device on the ThingPark platform according
to the type of the AS routing profile
▪ Route the device’s uplink and downlink packets to an Application Server.
For more information about other operations you can perform on AS routing profiles, see 7.5
Handling AS Routing Profiles.
7.2.1.4.1 Retrieving an AS Routing Profile

You can list the AS routing profiles already created in the Device Manager subscription, and retrieve
the one you want.
If you want to use the AS Routing Profile to create a device, the AS Routing Profile must have the
same type of connectivity than the device you want to create.

>> GET /thingpark/wireless/rest/subscriptions/47/appServersRoutingProfiles?sessionToken=bb
32bade5c813448

<< 200 OK

<ns2:appServersRoutingProfiles xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription"
>
<briefs>
<brief>
<name>My AS Routing Profile</name>
<ID>TWA_199999999.833</ID>
<isDefault>true</isDefault>
<href>/thingpark/wireless/rest/subscriptions/47/appServersRoutingProfiles/256</href>
<type>LORAWAN</type>
</brief>
...
</briefs>
<more>false</more>
</ns2:appServersRoutingProfiles>
3. Take note of the ID and HREF information of the AS routing profile you want according to the
connectivity of the device you want to create.
If no information is returned in the response, you have to declare a new AS routing profile.
7.2.1.4.2 Declaring an AS Routing Profile

Declaring an AS routing profile results in creating a named empty AS routing profile of LoRaWAN™ or
cellular type that you will provision later with an Application Server destination.
The AS Routing Profile must have the same type of connectivity than the device you want to create.
If you have retrieved an AS routing profile that meets your device specifications, you can skip this
task.

>> POST /thingpark/wireless/rest/subscriptions/47/appServersRoutingProfiles?sessionToken=b
b32bade5c813448

<ns2:appServersRoutingProfile xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
</ns2:appServersRoutingProfile>

<< 201 Created
Location: /thingpark/wireless/rest/subscriptions/47/appServersRoutingProfiles/256

<occContext>
<lastUpdate>2015-11-28T07:46:54.862+01:00</lastUpdate>
<who>John Doe</who>
</occContext>
<ID>TWA_199999999.833</ID>
<isDefault>true</isDefault>
Notes
▪ The first version of the AS routing profile is created. It is empty.

▪ You cannot specify the AS routing profile properties when declaring it. You will set its
properties (route destinations, isDefault, etc.) with an update REST request when
provisioning it later. For more information, see 7.2.1.4.5 Provisioning an AS Routing Profile.
7.2.1.4.3 Activating the HSM Option on an AS Routing Profile (LoRaWAN™ Only)

This task only applies to LoRaWAN™ OTAA devices.
If the network subscription you want to use to create an OTAA device has the HSM option activated,
you also have to activate this option on the AS routing profile.
For more information about how to check if a network subscription has the HSM option activated,
see 7.2.1.2 Retrieving a Network Subscription.

>> PUT /thingpark/wireless/rest/subscriptions/47/appServersRoutingProfiles/256/security?se
ssionToken=bb32bade5c813448

<ns2:security xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<occContext>
</occContext>
<hsmSecurity>
<status>HSM_AS_KEY</status>
<hsmGroupID>HSM-group1</hsmGroupID>
<rsaPublicKey>
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA61BjmfXGEvWmegnBGSuS
+rU9soUg2FnODva32D1AqhwdziwHINFaD1MVlcrYG6XRKfkcxnaXGfFDWHLEvNBS
EVCgJjtHAGZIm5GL/KA86KDp/CwDFMSwluowcXwDwoyinmeOY9eKyh6aY72xJh7n
oLBBq1N0bWi1e2i+83txOCg4yV2oVXhBo8pYEJ8LT3el6Smxol3C1oFMVdwPgc0v
Tl25XucMcG/ALE/KNY6pqC2AQ6R2ERlVgPiUWOPatVkt7+Bs3h5Ramxh7XjBOXeu
lmCpGSynXNcpZ/06+vofGi/2MlpQZNhHAo8eayMp6FcvNucIpUndo1X8dKMv3Y26
ZQIDAQAB
-----END PUBLIC KEY-----
</rsaPublicKey>
</hsmSecurity>
</ns2:security>

<< 200 OK
Location: /thingpark/wireless/rest/subscriptions/47/appServersRoutingProfiles/256

<occContext>
<who>John Doe</who>
</occContext>
<hsmSecurity>
<status>HSM_AS_KEY</status>
<rsaEncryptedASKey>45361b7dd64e7b65e88f8adbdc4d464cb9aa833dafd3344508035d362891356cfe5
9c26a1c1e57188be1a851af56545744ec7cf5181727f76272045b4242fbdcf00f46e715211ffda18f0340147bb
aa9b62551c398340a4f5ab6d2d1be6f22d6fd648b652173d9e1699662adbcd64e616d46ede67b4660f608dc30d
9c3b6d23af3d5b8afbd4dd5766bbf3d1f642463a3c6e0aa1c3c911de939afa926bbdf53f0415d2befae5f20a3c
5f81de06c531ecd0f5b874df13a344fcb31006b92eae1842055e128d2f611dd37aedc32aff0d0fdca9cb8f57ef
089b698f1a12aaeb6eb1f889e8531a38fc8d8384689201b4e632607eabcc029ada92777d75fd237ae5d3d</rsa
EncryptedASKey>
</hsmSecurity>
3. To keep going with the scenario, take note of the value of:
▪ The rsaEncryptedASKey, which is the AS key generated by the HSM.
This key has been encrypted with the rsa public key you have provided in the PUT request. It
is used in the LRC-AS tunnel interface to decrypt the appSKey. For more information, see
[R5].
7.2.1.4.4 Retrieving a Server Destination

Any AS routing profile needs a destination to be routed. You can use:
▪ A ThingPark X destination that you have to retrieve

▪ A third-party Local Application Server destination that you have to create locally
▪ A third-party Supplier Application Server destination which has been previously created by a
Supplier and that you have to retrieve. Supplier Application Servers only apply to LoRaWAN™
connectivity.
For more information about other operations you can perform on Local Application Servers, see 7.6
Handling Local Application Servers.
7.2.1.4.4.1 Retrieving a ThingPark X Destination

If you want to associate your AS routing profile with a ThingPark X destination, you have to retrieve it
first. ThingPark X destinations apply to LoRaWAN™ and cellular connectivity.

>> GET /thingpark/wireless/rest/subscriptions/47/appServersRoutingProfiles/tpkClouds?sessi
onToken=bb32bade5c813448

<< 200 OK

<ns2:tpkClouds xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<cloudConfig><clouds><cloud name="netONG" address="http://netong
.acme.com:8081/payload"/></clouds></cloudConfig>
</ns2:tpkClouds>

▪ The URL of the ThingPark X destination.
7.2.1.4.4.2 Creating a Local Application Server Destination

If you want to associate your AS routing profile with a third-party Local Application Server using LRC
tunneling interface, you have to perform the following tasks in this order:
▪ Create the Local Application Server you want according to the connectivity and server used
by the device:
o LoRaWAN™ HTTP Application Server
o Cellular HTTP Application Server
o Kafka Application Server, that applies to LoRaWAN™ and cellular connectivity.
▪ Activate the uplink/downlink security of the Local Application Server:

o The uplink/downlink security of a Local application Server is optional or mandatory
according to the Operator policy.
o For Kafka Application Server, this security only applies to downlink packets.
▪ Update the Local Application Server to add it a destination.
For more information about other operations you can perform on Local Application Servers, see 7.6
Handling Local Application Servers.
7.2.1.4.4.2.1 Creating an HTTP or a Kafka Local Application Server

It consists in creating an empty Local Application Server, giving it a name and a type according to the
connectivity and server used by the device.
The type can have the following values:
▪ HTTP: applies to LoRaWAN™ HTTP Application Server

▪ HTTP_CELLULAR: applies to Cellular HTTP Application Server
▪ KAFKA: applies to Kafka Application Server for LoRaWAN™ and cellular connectivity.
The Device Manager HREF is required. To retrieved it, see 7.2.1.1 Listing the Network Subscriptions,
then 7.2.1.2 Retrieving a Network Subscription.

Type HTTP

>> POST /thingpark/wireless/rest/subscriptions/47/appServers?sessionToken=bb32bade5c813448

<ns2:appServers xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<name>My Application Server</name>
<type>HTTP</type>
</ns2:appServers>

<< 201 Created
Location: /thingpark/wireless/rest/subscriptions/47/appServers/184

<occContext>
<who>John Doe</who>
</occContext>
<ID>TWA_199999999.70.AS</ID>
<name>My Application Server</name>
<downlinkSecurity>
<status>NONE</status>
</downlinkSecurity>
</ns2:appServers>

▪ The ID of the newly created Application Server.
7.2.1.4.4.2.2 Activating the Uplink/Downlink Security of the Local Application Server

Activating the uplink/downlink security of a Local Application Server is optional. If you want to
activate it, you must configure this security after creating the Local Application Server, and before
adding it a route.
If the Operator made it mandatory on its platform, you must activate this security. If not, the Local
Application Server cannot be saved.
The uplink/downlink security of the Local Application Server uses the LRC-AS Key that needs, by
default, a high entropy.
For Kafka Application Server, this security only applies to downlink packets.

7.2.1.4.4.2.2.1 LRC-AS Key Entropy
The LRC-AS Key is a 128-bit hexadecimal key which is used to activate the uplink/downlink security of
the Local Application Server. It is given by the owner of the Local Application Server. The LRC-AS Key
is shared by the LRC and the Local Application Server to secure uplink and downlink packets passing
through the tunnel interface. For more information about the LRC-AS tunnel interface, see [R5].
When you provide a LRC-AS Key, its entropy is computed by the system using Shannon's algorithm. If
the entropy is greater than or equal to the entropy threshold accepted by the configuration of the
ThingPark Wireless platform, the LRC-AS Key is accepted. If not, the LRC-AS Key is rejected. For more
information, contact the administrator of the Operator platform.
7.2.1.4.4.2.2.2 Activating the Uplink/Downlink Security

To activate the uplink/downlink security of a Local Application Server, you need the following
information from its owner:
Required Information
▪ AS ID AS-ID and LRC-AS Key are used by the LRC and the Local Application
▪ LRC-AS Key Server for the tunneling interface. For more information, see [R5].
▪ Max timestamp Optionally defines the tolerance of downlink timestamp deviation in

seconds.
deviation

>> PUT /thingpark/wireless/rest/subscriptions/47/appServers/184/security?sessionToken=bb32
bade5c813448

<occContext>
</occContext>
<downlinkSecurity>
<asID>My Application Server</asID>
<downlinkAsKey>a2b3c4d5e6f7a8b9c1d2e3f4a5b6c7d</downlinkAsKey>
<maxTimestampDeviation>10</maxTimestampDeviation>
<status>DOWNLINK_AS_KEY</status>
</downlinkSecurity>
</ns2:appServers>

<< 200 OK
7.2.1.4.4.2.3 Adding a Route to an HTTP Local Application Server

It consists in updating the newly created HTTP Local Application Server to add it a route with a
destination by specifying source ports, route strategy, and URL addresses.

For cellular connectivity in Message Mode, all device packets come from the same source port that is
used by the Cellular HTTP Application Server. Thus, there is no need to define source ports and only
one route can be created. For more information about Message mode, see 7.2.1.4.5 Provisioning an
AS Routing Profile.
For more information about Local Application Server URLs routing strategies, see 7.6.5 Local
Application Server URLs Routing Strategies.
You need the following information from the owner of the Application Server. The example uses the
following values:
Application Server URL http://as.acme.com:8080

>> PUT /thingpark/wireless/rest/subscriptions/47/appServers/184?sessionToken=bb32bade5c813
448

<occContext>
</occContext>
<destinations>
<destination>
<addresses>
<address>http://as.acme.com:8080</address>
</addresses>
<ports>*</ports>
<strategy>SEQUENTIAL</strategy>
</destination>
</destinations>
</ns2:appServers>

<< 200 OK
7.2.1.4.4.2.4 Adding a Route to a Kafka Local Application Server

It consists in updating the newly created Kafka Local Application Server to add it a broker ID and a
topic name. Kafka Local Application Servers apply to LoRaWAN™ and cellular connectivity.
You need the following information from the owner of the Application Server. The example uses the
following values:
Broker ID KAFKA_DEFAULT
Topic name AS.application1.v1

448

<occContext>
</occContext>
<destinations>
<destination>
<brokerID>KAFKA_DEFAULT</brokerID>
<topicName>AS.application1.v1</topicName>
</destination>
</destinations></ns2:appServers>

<< 200 OK
7.2.1.4.4.3 Retrieving a Supplier Application Server Destination

Supplier Application Servers only apply to LoRaWAN™ connectivity.
A third-party Supplier Application Server is an Application Server created by a Supplier.
If you want to associate your AS routing profile with a Supplier Application Server, you have to:
▪ Retrieve the list of the Operator’s Suppliers who provide Application Servers in order to
choose the supplier you want
▪ Use the Supplier ID to list its Supplier Application Server.
7.2.1.4.4.3.1 Listing the Suppliers with Supplier Application Servers

You can retrieve the Operator’s Suppliers who provide Supplier Application Servers in order to get a
supplier ID.
>> GET /thingpark/wireless/rest/subscriptions/47/appServersRoutingProfiles/suppliers?sessi

<< 200 OK

<ns2:suppliers xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<briefs>
<brief>
<name>Supplier 001</name>
<commercialName>Supplier 001</commercialName>
<ID>supplier-001</ID>
</brief>
...
</briefs>
<more>false</more>
</ns2:suppliers>

▪ The ID of the Supplier you want.
7.2.1.4.4.3.2 Listing the Supplier Application Servers of a Supplier

You can retrieve the Supplier Application Servers attached to a Supplier.
The ID of the Supplier must have been retrieved first. For more information, see 7.2.1.4.4.3.1 Listing
the Suppliers with Supplier Application Servers.

>> GET /thingpark/wireless/rest/subscriptions/47/appServersRoutingProfiles/suppliers?sessi

<< 200 OK

<ns2:AppServers xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<briefs>
<supplier>
<name>Supplier 001</name>
<commercialName>Supplier 001</commercialName>
<ID>supplier-001</ID>
</supplier>
<appServer>
<name>Supplier 001 Application Server A</name>
<commercialName>Supplier 001 Application Server A</commercialName>
<commercialDescription><p>AppServer A by Supplier 001</p></commercialDescription>
<ID>TWA_supplier-001.10.AS</ID>
</appServer>
...
</briefs>
<more>false</more>
</ns2:AppServers>

According to the connectivity type of the AS routing profile, you can provision it with the following
Application Server destinations:
▪ For a LoRaWAN™ AS routing profile

o A ThingPark X Application Server

o A third-party Local Application Server: LoRaWAN™ HTTP Application Server or Kafka
Application Server
o A third-party Supplier Application Server.
▪ For a Cellular AS routing profile

o In Message mode
▪ Define the IPv4 settings (subnet, DHCP pool, DNS server1, ...) in the request
payload. See GTP tunnel settings in SUPPLIERAPPSERVERS:
AppServersRoutingProfileCellular in [R1].
▪ Use the following Application Server destinations:
• A ThingPark X Application Server
• A third-party Local Application Server: Cellular HTTP Application
Server or Kafka Application Server.
o In Direct IP mode
▪ Define the IPv4 settings (subnet, DHCP pool, DNS server1, ...) in the request
payload. See GTP tunnel settings in SUPPLIERAPPSERVERS:
▪ Define an ASR address as Application Server destination in the request
payload. See GRE tunnel settings in SUPPLIERAPPSERVERS:
o In Mixed mode
Apply the Message and Direct IP modes instructions.
In the following example, a LoRaWAN™ AS routing profile is provisioned with the following
Application Server destinations at the same time.
>> PUT /thingpark/wireless/rest/subscriptions/47/appServersRoutingProfiles/833?sessionToke
n=bb32bade5c813448

<occContext>
</occContext>
<tpkCloudDestinations>
<destination>
<ports>*</ports>
<address>http://netong.acme.com:8081/payload</address>
</destination>
</tpkCloudDestinations>
<appServers>
<appServer><ID>TWA_199999999.70.AS</ID></appServer>
</appServers>
<supplierAppServers>
<supplierAppServer><ID>TWA_supplier-001.10.AS</ID></supplierAppServer>
</supplierAppServers>

<< 200 OK
7.2.2 Declaring a LoRaWAN™ Device

Once you have prepared all the prerequisite information, you can declare a new device on the end
user account.
7.2.2.1 PREREQUISITE AND EXAMPLE INFORMATION

The following information is mandatory to declare a LoRaWAN™ device in ABP mode. For OTAA
device, see [R1].
Data Type Description
Provisioning mode Over The Air Activation (OTAA)/Activation By Personalization (ABP)
Device profile ID For more information, see 7.2.1.3 Listing the Device Profiles.
DevEUI Globally unique identifier of a LoRaWAN™ device which is written
on it. Composed of 16 hexadecimal digits (0 to 9, and A to F).
Example: F0-3D-29-00-0B-B1-7A-AA.
DevAddr Device address on the network for a LoRaWAN™ device.
Composed of 8 hexadecimal digits (0 to 9, and A to F), it identifies
the device on the current network. The first 6 digits correspond to
the LoRa network operator ID. Example: 05-AB-C4-89.
Only required when Activation By Personalization (ABP) is used.
Network device keys Application EUI and Application Key (OTAA)/Network and
Application Session Keys (ABP)
Device Connectivity Plan ID For more information, see 7.2.1.1 Listing the Network
Subscriptions.
Device AS Routing Profile ID For more information, see 7.2.1.4.1 Retrieving an AS Routing
Profile.
The following information is optional for ABP and OTAA devices. Additional required information
applies if the HSM option is activated on an OTAA device.
Device name Any name you want.
Administrative information Administrative information associated to the device (e.g. floor
number, building, address, etc.).

HSM group ID Only applies to OTAA devices to associate with a Network
Subscription with the HSM option activated. For more information,
see 7.2.1.2 Retrieving a Network Subscription.
AppKey Encryption Mode Only applicable if the HSM option is activated on the network
subscription for OTAA devices.
In our example, we will use the following information to declare the device:
Data Type Example
Provisioning mode ABP /OTAA with HSM
Device name My device
Device profile ID LoRaMote.1
DevEUI 70B3D5E756000999
DevAddr 6E0000999
Network session Key 7374757A3FDD092947CE2DE9321C6040
Application session Key (on LoRaWAN™ port 1) 65FC7B3530A44FB95CF327AB19B1454E
Device Network Subscription ID acme-cs/cp1
AppKey Encryption Mode HSM_APP_KEY
HSM group ID HSM-group1
Device AS Routing Profile ID TWA_100000131.48
Administrative information High Street, 999-999 Town, John Office
7.2.2.2 PROCEDURE
Once you have the prerequisite information, you can perform the following request to declare the
LoRaWAN™ ABP device (with the required additional information for an OTAA device with HSM).
>> POST /thingpark/wireless/rest/subscriptions/47/devices?sessionToken=bb32bade5c813448

<ns2:device xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<activation>ABP</activation>
<name>My device</name>
<model><ID>SMTC/LoRaMote.1</ID></model>
<EUI>70B3D5E756000999</EUI>
<nwAddress>6E000999</nwAddress>
<nwKey>7374757A3FDD092947CE2DE9321C6040</nwKey>
<appKeys><AppSKeys><AppSKey Port="1">65FC7B3530A44FB95CF327AB19B14
54E</AppSKey></AppSKeys></appKeys>

<networkSubscription><ID>acme-cs/cp1</ID></networkSubscription>
<appKeyEncryptionMode>HSM_APP_KEY</appKeyEncryptionMode>
<appServersRoutingProfile><ID>TWA_100000131.48</ID></appServersRoutingProfile>
<customerAdminData>High Street, 999-999 Town, John Office</customerAdminData>
</ns2:device>

<< 201 Created
Location: /thingpark/wireless/rest/subscriptions/47/devices/2227

<now>2016-04-25T19:29:31.681+02:00</now>
<occContext>
<who>John Doe</who>
</occContext>
...
</ns2:device>
▪ Take note of:

o The HTTP Location header that is the main information to remember.
o The occContext information that contains the version number of the device.
Note It can be retrieved by performing a GET request on the device HREF.
7.2.3 Declaring a Cellular Device

The following information is mandatory:
Device profile ID For more information, see 7.2.1.3 Listing the Device Profiles.
IMEI International Mobile Equipment Identity that uniquely identifies a
(Uses the <EUI> tag) cellular device. Composed of 14 or 15 digits, the last digit is an
optional Luhn checksum. In ThingPark, if the device is created
entering 15 digits, only the first 14 digits are kept in base after the
Luhn algorithm validation and are necessary to retrieve the device.
IMSI International Mobile Subscriber Identity
Ki Public Key Infrastructure
Mandatory if HSS data provisioning is required by the Operator.
Device Connectivity Plan ID For more information, see 7.2.1.1 Listing the Network
Subscriptions.
Device AS Routing Profile ID For more information, see 7.2.1.4.1 Retrieving an AS Routing
Profile.

The following information is optional:
Device name Any name you want.

Administrative information Administrative information associated to the device (e.g. floor
number, building, address, etc.).
In our example, we will use the following information to declare the device:
Data Type Example
Device name My device
Device profile ID LTE device
IMEI (Uses the <EUI> tag) 123456789012347
IMSI 460004777770001
Ki 7374757A3FDD092947CE2DE9321C6040
Administrative information Old Street, 999-999 Town, Jim Office
7.2.3.2 PROCEDURE
Once you have the prerequisite information, you can perform the following request to declare the
cellular device:
>> POST /thingpark/wireless/rest/subscriptions/47/devices?sessionToken=bb32bade5c813448

<name>My device</name>
<model><ID>LTE device</ID></model>
<EUI>123456789012347</EUI>
<imsi>460004777770001</imsi>
<ki>7374757A3FDD092947CE2DE9321C6040</ki>
<networkSubscription><ID>acme-cs/cp1</ID></networkSubscription>
<appServersRoutingProfile><ID>TWA_100000131.48</ID></appServersRoutingProfile>
<customerAdminData>Old Street, 999-999 Town, Jim Office</customerAdminData>
</ns2:device>

<< 201 Created
Location: /thingpark/wireless/rest/subscriptions/47/devices/2227


<now>2016-04-25T19:29:31.681+02:00</now>
<occContext>
<who>John Doe</who>
</occContext>
...
</ns2:device>
▪ Take note of:

o The HTTP Location header that is the main information to remember.
o The occContext information that contains the version number of the device.
Note It can be retrieved by performing a GET request on the device HREF.
7.2.4 Declaring a Set of Devices with Mass-Import

This task shows an example of how to declare a set of a LoRaWAN™ and cellular devices using the
mass-import feature, which enables importing functions through a CSV file describing the required
operations.
In the CSV file:
▪ One CSV entry is an operation order with required parameters.

▪ Only two operations are allowed:
o CREATE operation
▪ CREATE_ABP (or CREATE)
▪ CREATE_OTAA
▪ CREATE_CELLULAR
o DELETE operation
For more information about CSV entry format and mass-import functionality, see [R1].

For each device, the same mandatory information as in 7.2.2 Declaring a LoRaWAN™ Device and
7.2.3 Declaring a Cellular Device is required.
In our example, we will use the following data to import a LoRaWAN™ ABP device and a cellular
device:
Device 1
Data Type Example
Processing directive CREATE_ABP

DevEUI 74B3D5E76E000174
DevAddr 6E000174
Device profile ID ABC/DEMO.1

Data Type Example
Network Session Key 7374757A3FDD092947CE2DE9321C6040
Application Session Key (on LoRaWAN™ port 1) 65FC7B3530A44FB95CF327AB19B1454E
ThingPark X Configuration <modelCfgs>
<modelCfg>1</modelCfg>
</modelCfgs>
Device AS Routing Profile ID TWA_100000131.48"
Device name Device #1 imported with API
Administrative information High Street, 999-999 Town, John Office
Device 2
Data Type Example
Processing directive CREATE_CELLULAR
IMEI (Uses the <EUI> tag) 123456789012347
IMSI 460004777770001
Device profile ID LTE/DEMO.1
Ki 7374757A3FDD092947CE2DE9321C6040
Device Network Subscription ID cellular-cs/testing
Device name Device #2 imported with API
Administrative information New Street, 111-111 Town, Jim Office
CSV Content
The CSV content reflecting the mass-import file used to declare the LoRaWAN™ ABP device and the
cellular device looks like this:
#== CSV content built for mass-import ==
"CREATE_ABP","74B3D5E76E000174","6E000174","ABC/DEMO.1","7374757A3FDD092947CE2DE9321C6040","<A
ppSKeys><AppSKey
Port=""1"">65FC7B3530A44FB95CF327AB19B1454E</AppSKey></AppSKeys>","<modelCfgs><modelCfg>1</mod
elCfg></modelCfgs>","acme-cs/cp1","TWA_100000131.48","","Device #1 imported with
API","","","High Street, 999-999 Town, John Office","","","","",""
"CREATE_CELLULAR","123456789012347","460004777770001","LTE/DEMO.1","7374757A3FDD092947CE2DE932
1C6040","","","cellular-cs/testing","TWA_100000131.67","","Device #2 imported with
API","","","New Street, 111-111 Town, Jim Office","","","","",""

7.2.4.2 PROCEDURE
Once the CSV file is ready with the prerequisite information, you can use a Multipart HTTP request
where:
▪ The HTTP request Accept header is: application/xml

▪ The HTTP request Content-Type header is: multipart/form-data.

>> POST /thingpark/wireless/rest/subscriptions/47/devices/import?sessionToken=bb32bade5c81
3448
Accept: application/xml
Content-Type: multipart/form-data; boundary=1ac07af2e4dc4cf985eabda7313e34b7
b'--1ac07af2e4dc4cf985eabda7313e34b7\r\nContent-Disposition: form-data; name="csv"; filena

me="import.csv"\r\n\r\n"CREATE_ABP","74B3D5E76E000174","6E000174","ABC/DEMO.1","7374757A3F
DD092947CE2DE9321C6040","<AppSKeys><AppSKey Port=""1"">65FC7B3530A44FB95CF327AB19B1454E</A
ppSKey></AppSKeys>","<modelCfgs><modelCfg>1</modelCfg></modelCfgs>","acme-cs/cp1","TWA_100
000131.48","","Device #1 imported with API","","","High Street, 999-999 Town, John Office"
,"","","","",""\r\n"CREATE_CELLULAR","123456789012347","460004777770001","LTE/DEMO.1","737
4757A3FDD092947CE2DE9321C6040","","","cellular-cs/testing","TWA_100000131.67","","Device #
2 imported with API","","","New Street, 111-111 Town, Jim Office","","","","",""\r\n--1ac0
7af2e4dc4cf985eabda7313e34b7--\r\n'
2. Check your output with the following returned code meaning that every CSV entry has been
handled successfully:
<< 200 OK
7.3 Retrieving Device Information

This section shows how to retrieve different types of information from a device. All tasks are
standalone.
7.3.1 Listing the Devices

You can list all the devices registered on the Subscriber account.
This task is useful to retrieve a device HREF. This information is required for many operations you
want to perform on a device.

>> GET /thingpark/wireless/rest/subscriptions/47/devices?sessionToken=bb32bade5c813448

<< 200 OK
<? xml version="1.0" encoding="UTF-8"?>

<ns2:devices xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<now>2016-04-25T19:29:20.779+02:00</now>
<briefs>
<brief>
<name>My device 1</name>
<EUI>70B3D5E756000999</EUI>
<href>/thingpark/wireless/rest/subscriptions/47/devices/692</href>
...
</brief>
<brief>
...
</brief>
</briefs>
<more>false</more>
</ns2:devices>
7.3.2 Retrieving the Device Configuration

You can retrieve all the details of a device using the device HREF value.
>> GET /thingpark/wireless/rest/subscriptions/47/devices/692?sessionToken=bb32bade5c813448

<< 200 OK

<now>2016-04-25T23:36:41.773+02:00</now>
<occContext>
<who>John Doe</who>
</occContext>
<name>My device 1</name>
<model>
<commercialName>LoRaMote v1</commercialName>
<logo>/thingpark/wireless/rest/resources/files/logo/deviceProfile/92</logo>
<typeMAC>LoRaMAC</typeMAC>
<ID>LoRaMote.1</ID>
</model>
<EUI>70B3D5E756000999</EUI>
<activation>ABP</activation>
...
</ns2:device>

7.3.3 Retrieving the Device Uplink/Downlink History
You can retrieve the last 2,000 uplink/downlink frames of a device. This number can be modified by
the Operator of the platform. The device HREF is required.
>> GET /thingpark/wireless/rest/subscriptions/47/devices/692/frames?sessionToken=bb32bade5
c813448

<< 200 OK

<ns2:frames xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<now>2016-04-25T23:43:46.762+02:00</now>
<briefs>
<brief>
<type>1</type>
<timestamp>2016-04-24T03:32:28.265+02:00</timestamp>
<bitrate>0.0</bitrate>
<size>0</size>
<sf>8</sf>
<overflow>false</overflow>
</brief>
<brief>
<type>0</type>
<bitrate>0.0015855014</bitrate>
<size>137</size>
<rssi>-108.0</rssi>
<snr>-7.25</snr>
<sf>8</sf>
<overflow>false</overflow>
</brief>
...
</briefs>
</ns2:frames>
7.3.4 Retrieving the Device Location (LoRaWAN™ Only)

This task only applies to LoRaWAN™ connectivity.
You can retrieve the 2,000 last locations of a device. A device location is retrieved by the coordinates
provided by the location server. These coordinates are only available when the network geo-location
is activated in the service profile. The number of last locations to be retrieved can be modified by the
Operator of the platform. The device HREF is required.
This Web Service does not retrieve the location administratively configured in the device. If you want
to retrieve the device administrative location, perform the request described in 7.3.2 Retrieving the
Device Configuration.

>> GET /thingpark/wireless/rest/subscriptions/47/devices/692/locations?sessionToken=bb32ba
de5c813448

<< 200 OK

<ns2:locations xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<briefs>
<brief>
<lat>0.0</lat>
<lon>0.0</lon>
</brief> <brief>
<lat>49.157669</lat>
<lon>-0.311</lon>
<alt>100.0</alt>
<hRadius>0.0</hRadius>
<vRadius>0.0</vRadius>
</brief>
...
</briefs>
</ns2:locations>
7.3.5 Retrieving the Device Battery Level (LoRaWAN™ Only)

This task only applies to LoRaWAN™ connectivity.
If the device is able to produce information about its battery level, you can retrieve the information.
Battery levels are only available when the device status reporting is activated in the service profile.
The device HREF is required.
>> GET /thingpark/wireless/rest/subscriptions/47/devices/692/batLevels?sessionToken=bb32ba
de5c813448

<< 200 OK

<ns2:batLevels xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<briefs>
<brief>
<level>80</levels>
</brief>
...
</briefs>
</ns2:batLevels>

7.4 Managing Device Alarms
Device HREF /subscriptions/47/devices/692
7.4.1 Listing the Device Alarms

You can list all the alarms of the device of your choice, using the device HREF value.
>> GET /thingpark/wireless/rest/subscriptions/47/devices/692/alarms?sessionToken=bb32bade5
c813448

<< 200 OK

<ns2:alarms xmlns:ns2="http://www.actility.com/tpkwrls/ws/subscription">
<more>false</more>
<briefs>
<brief>
<creationTimestamp>2016-04-21T03:23:49.189+02:00</creationTimestamp>
<updateTimestamp>2016-04-24T03:24:23.047+02:00</updateTimestamp>
<ID>3</ID>
<state>1</state>
<occurrence>10</occurrence>
<addInfo>1</addInfo>
<acked>false</acked>
<href>/thingpark/wireless/rest/subscriptions/47/devices/1649/alarms/57182ba5e4b00acc
b6175260</href>
</brief>
...
</briefs>
</ns2:alarms>
7.4.2 Acknowledging an Alarm

You can acknowledge the alarm of your choice using the alarm HREF value.
>> POST /thingpark/wireless/rest/subscriptions/47/devices/1849/alarms/57182ba5e4b00accb617
5260/ack?sessionToken=bb32bade5c813448

<< 201 Created

7.4.3 Acknowledging the Alarms
You can acknowledge simultaneously all the alarms of a device.
If you want to limit the scope of the acknowledgment, for instance to only acknowledge an alarm
level, you can associate filter criteria with the REST request. For more information, see [R1].

>> POST /thingpark/wireless/rest/subscriptions/47/devices/1849/alarms/ack?sessionToken=bb3
2bade5c813448

<< 201 Created
7.5 Handling AS Routing Profiles

In addition to the AS routing profile tasks involved in the device creating process described in 7.2
Creating Devices, you can perform some more operations on AS routing profiles.
For general information about AS routing profiles, see 7.2.1.4 Associating an AS Routing Profile and
7.2.1.4.5 Provisioning an AS Routing Profile.
7.5.1 Listing AS Routing Profiles

If you want to list the AS routing profiles created in the Device Manager subscription, see 7.2.1.4.1
Retrieving an AS Routing Profile.
7.5.2 Creating an Empty AS Routing Profile

If you want to create an empty AS routing profile without creating a device, see 7.2.1.4.2 Declaring
an AS Routing Profile.

7.5.3 Updating an AS Routing Profile
You can modify an AS routing profile, for example by adding it another Local Application Server
destination. You can also change the mode of a cellular AS routing profile.
1. In your application, execute a REST request using the following example. Type the new full list of
destinations to override the previous list.
>> PUT /thingpark/wireless/rest/subscriptions/47/appServersRoutingProfiles/256?sessionToke
n=bb32bade5c813448

<occContext>
</occContext>
<appServers>
</appServers>

<< 200 OK
7.5.4 Deleting an AS Routing Profile

The HREF reference of the AS Routing profile you want to delete is required.
1. In your application, execute a REST request on the HREF reference using the following example:
>> DELETE /thingpark/wireless/rest/subscriptions/47/appServersRoutingProfiles/256?sessionT
oken=bb32bade5c813448

<< 204 No Content
7.6 Handling Local Application Servers

In addition to the Local Application Servers tasks involved in the device creating process described in
7.2 Creating Devices, you can perform some more operations on AS routing profiles.

For more information about other types of Application Server, see 7.2.1.4.4 Retrieving a Server
Destination.
7.6.1 Listing Local Application Servers

You can list the Local Application Servers associated to the Device Manager subscription and created
in the Device Manager in 7.2.1.4.4.2 Creating a Local Application Server Destination. It will retrieve
the Local Application Server HREF.
>> GET /thingpark/wireless/rest/subscriptions/47/appServers?sessionToken=bb32bade5c813448

<< 200 OK

<briefs>
<brief>
<ID>TWA_199999999.70.AS</ID>
<href>/thingpark/wireless/rest/subscriptions/47/appServers/184</href>
</brief>
...
</briefs>
<more>false</more>
</ns2:appServers>
7.6.2 Creating an Empty Local Application Server

Local Application Servers are created locally in the Device Manager subscription. This operation is
part of the device creating process described in 7.2 Creating Devices.
If you want to create an empty Local Application Server without creating a device, see 7.2.1.4.4.2.1
Creating an HTTP or a Kafka Local Application Server.
7.6.3 Updating a Local Application Server

You can modify a Local Application Server, for example by adding a second destination URL to a HTTP
Application Server. The Local Application Server HREF is required.
For more information about route strategies, see 7.6.5 Local Application Server URLs Routing
Strategies.

1. In your application, execute a REST request using the following example. Type the new full list of
destinations to override the former list.
448

<occContext>
</occContext>
<destinations>
<addresses>
<address>http://as.acme.com:8080</address>
<address>http://as2.acme.com:8080</address>
</addresses>
<ports>*</ports>
<strategy>SEQUENTIAL</strategy>
</destinations>
</ns2:appServers>

<< 200 OK
7.6.4 Deleting a Local Application Server

You can delete a Local Application Server using its HREF.
>> DELETE /thingpark/wireless/rest/subscriptions/47/appServers/184?sessionToken=bb32bade5c
813448

<< 204 No Content
7.6.5 Local Application Server URLs Routing Strategies

There are two routing strategies for sending the device packets to a Local Application Server.
Mode Description
SEQUENTIAL Uplink frames are sent to the first URL. The next URLs are sequentially tried
in case of error.
BLAST Uplink frames are sent to all ULRs in parallel.

7.7 Updating a Device
This task shows an example of how to update a device to change its name.
Before you begin: Any update requires as a mandatory parameter the occContext information from
which the resource will be updated. If you have not the occContext information of the device you
want to update, perform first a GET request on the targeted device HREF.
>> PUT /thingpark/wireless/rest/subscriptions/47/devices/2227?sessionToken=bb32bade5c81344
8

<occContext>
</occContext>
<name>My new device name</name>
</ns2:device>

<< 200 OK
7.8 Deleting a Device

You can delete the device you want using its HREF information.
>> DELETE /thingpark/wireless/rest/subscriptions/47/devices/2227?sessionToken=bb32bade5c81
3448

<< 204 No Content
7.9 Logging Out from the Device Manager Session

You can log out the Device Manager using your session cookie and session token.

>> GET /thingpark/wireless/rest/customers/logout?sessionToken=bb32bade5c813448

<< 204 No Content

WHAT’S NEW HISTORY
New/Enhanced Functionalities For More Information, See… Release
3 ThingPark Solution Overview
ThingPark Mashup is renamed 7.2.1.4.4 Retrieving a Server Destination

4.1
ThingPark X 7.2.1.4.4.1 Retrieving a ThingPark X Destination
LoRaWAN™ class B profile and
6.3.3.5 Retrieving Beacon Transmissions Statistics 4.1.2
beacons transmission
7.2.1.2 Retrieving a Network Subscription
Hardware Security Module (HSM)
7.2.1.4.3 Activating the HSM Option on an AS
activation when creating a device or 4.1.2
Routing Profile
an AS routing profile
7.2.2 Declaring a LoRaWAN™ Device
7.2.1.4.4.2.1 Creating an HTTP or a Kafka Local
Application Server
Kafka Application Server 4.1.2
7.2.1.4.4.2.4 Adding a Route to a Kafka Local
Application Server
6.2 Creating a Base Station
LRR UUIDD is recommended when
creating a base station. LRR ID is still 6.3 Retrieving Base Station Information 4.2
supported
6.6 Updating a Base Station
New commands:
▪ Update the log 6.4.1 Asynchronous and Synchronous Commands 4.2

configuration
▪ Get the log configuration

ABOUT ACTILITY
Actility is an industry leader in LPWAN (Low Power Wide Area) large scale infrastructure with
ThingPark™, the new generation standard-based M2M communication platform. Actility’s ThingPark
Wireless™ network provides long-range coverage for low-power sensors used in SmartCity,
SmartBuilding and SmartFactory applications. Actility also provides the ThingPark X which provides
big data storage for sensor data and exposes sensor function through an open API allowing
developers to provide vertical applications on top of rolled out sensors. To help vendors transform
their sensors, Actility provides the ThingPark IoT platform which include embedded software
solutions and cloud solutions to help devices connect to innovative applications. Via the ThingPark
Market, an online marketplace engine dedicated to the IoT sensors, applications and network
solutions, Actility enables the roll-out of new innovative IoT services for sensor vendors and network
solution vendors. Actility is a founding member of the LoRa Alliance™: the largest, most powerful
standards-based effort to enable the Internet of Things (IoT). Visit www.actility.com.
LoRaWAN™, the LoRa Alliance™, and LoRa Alliance Certified™ are trademarks of Semtech
Corporation, used with permission under a sublicense granted to the LoRa Alliance™ and its
members.


TP Wireless 6.1 OSS API User Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

TP Wireless 6.1 OSS API User Guide

Uploaded by

Copyright:

Available Formats

Actility ThingPark Wireless

OSS API User Guide

© 2019 ACTILITY SA. All rights reserved.

Under Non-Disclosure Agreement

02.3 06/01/2015 S. Solomon Updated architecture overview

02.3 13/01/2015 S. Solomon Updated introduction, layout and formatting

04 31/05/2016 L. Guillemot Initial revision for ThingPark Wireless 3.1.1

05 21/10/2016 L. Guillemot Initial revision for ThingPark Wireless 3.2.3

4.0.1-rev1 27/01/2017 L. Guillemot Initial revision for ThingPark Wireless 4.0.1

There is no enhancement for 4.3 (LoRaWAN™

5.1 27/08/2018 ML Ancelle There is no enhancement for 5.1

5.2 27/08/2018 ML Ancelle There is no enhancement for 5.2

5.2.2 12/00/2019 ML Ancelle There is no enhancement for 5.2.2

6.0 25/07/2019 L. Guillemot There is no enhancement for 6.0

6.1 23/12/2019 L.Guillemot There is no enhancement for 6.1

Under Non-Disclosure Agreement

Actility ThingPark System Management Platform User Sessions Guide Actility

R3 Actility ThingPark Wireless Supplier User Guide Actility

R4 Actility ThingPark Functional Description Actility

R5 Actility ThingPark Wireless LRC-AS Tunnel Interface Developer Guide Actility

R6 ThingPark Wireless HSM Solution Description Actility

Actility ThingPark EPC Connector Solution Description Actility

Actility ThingPark Wireless Multi-Technology IoT Platform Actility

Actility ThingPark Wireless Vendor User Guide Actility

Actility ThingPark Wireless Network Partner User Guide Actility

Actility ThingPark Wireless Device Manager User Guide Actility

Actility ThingPark Wireless Logger User Guide Actility

Actility ThingPark Wireless Address Manager User Guide Actility

Actility ThingPark Wireless LRC-OSS Interface Developer Guide (LoRaWAN) Actility

Actility ThingPark Wireless LRC-OSS Interface Developer Guide (Cellular) Actility

Actility ThingPark Wireless Usage Details Records Actility

Actility ThingPark Join Server Solution Description Actility

Under Non-Disclosure Agreement

Under Non-Disclosure Agreement

Under Non-Disclosure Agreement

Under Non-Disclosure Agreement

Under Non-Disclosure Agreement

Under Non-Disclosure Agreement

Under Non-Disclosure Agreement

▪ LoRaWAN™ and Cellular connectivity plans in the Connectivity Manager

▪ JSON for the Connectivity Manager (only supported in JSON),

Under Non-Disclosure Agreement

▪ ThingPark Wireless – OSS and core network

Operator & Enterprise Application Servers

ThingPark OS ThingPark Wireless Core NW & OSS ThingPark X

Wireless Device Network

Spectrum Network LoRaWANTM LoRaWANTM

LoRaWANTM LRR (Gateway)

Figure 1 – ThingPark Solution Architecture Description High Level Product Illustration

Under Non-Disclosure Agreement

3. Access Code verification

Figure 2 – ThingPark Single-Sign-On (SSO) framework

▪ 5 Using the Connectivity Manager OSS API

5.1 Logging In with Administrator Credentials

Administrator ThingPark password johndoepassword

Connectivity Supplier ID acme-cs

5.1.1 Authenticating the Administrator

1. In your application, execute a REST request using the following example:

<?xml version="1.0" encoding="UTF-8"?>

2. Check your output with the response extract:

<?xml version="1.0" encoding="UTF-8"?>

Under Non-Disclosure Agreement

5.1.2 Generating a Connectivity Supplier Access Code as an Administrator

1. In your application, execute a REST request using the following example.