Tutorial
A valid OAuth v2 Bearer token is required. See Authentication for more details.
Managing connections
Adding a ThingPark X IoT Flow connection
A ThingPark X IoT Flow connection is an asynchronous dataflow with built-in message queuing services designed to meet high availability, scalability and resiliency requirements for industrial deployments. IoT Flow offers a wide range of professionally supported IoT connectors towards the leading IoT platforms and a rich built-in catalog of payload drivers, in addition to supporting custom payload drivers. Device and base station alarms may be reported over this type of connection.
ThingPark X IoT Flow connections are managed with the DX Core API.
To get the full description of the API operations available for ThingPark X IOT Flow connection, see the DX Core API documentation of your platform:
- ThingPark Community
- ThingPark Enterprise SaaS EU
- ThingPark Enterprise SaaS AU
- ThingPark Enterprise SaaS US
- Self-hosted ThingPark Enterprise:
https://<domain>/thingpark/dx/core/latest/swagger-ui.html#/Connectionwhere<domain>is the hostname/IP address of your self-hosted ThingPark Enterprise
The example in this section uses the following values:
| Required Information | Example |
|---|---|
| Connection name | My MQTT connection |
| Connector identifier | actility-mqtt-iot |
| MQTT broker hostname | myhostname.com:8883 |
| Uplink topic pattern | mqtt/things/\{DevEUI\}/uplink |
| Downlink topic pattern | mqtt/things/\{DevEUI\}/downlink |
| Protocol | SSL |
| Username | mycompany |
| Password | bar |
POST /thingpark/dx/core/latest/api/connections HTTP/1.1
Authorization: Bearer ...
Content-Type: application/json
Accept: application/json
{
"connectorId": "actility-mqtt-iot",
"name": "My MQTT connection",
"configuration": {
"uplinkTopicPattern": "mqtt/things/{DevEUI}/uplink",
"downlinkTopicPattern": "mqtt/things/{DevEUI}/downlink",
"hostName": "myhostname.com:8883",
"protocol": "SSL",
"username": "mycompany",
"password": "bar"
}
}
HTTP/1.1 201 Created
Content-Type: application/json
Location: /connections/1114
{
"id": "1114",
"connectorId": "actility-mqtt-iot",
"name": "My MQTT connection",
"state": "OPENED",
"configuration": {
...
}
}
Adding a Basic HTTPS connection
A Basic HTTPS connection supports HTTPS-based connections, also known as NS-AS Tunnel Interface. Device payloads are exchanged in encoded format without the support of payload drivers. This connection type does not support message queuing services. Device and base station alarms cannot be reported over this type of connection.
The example in this section uses the following values:
| Required Information | Example |
|---|---|
| Connection name | My Basic HTTPS connection |
| URL | https://www.example.com/myApp |
| Content type | JSON |
| Tunnel interface authentication key | C72C6F867B150B1210ACDA5F3CDFB449 |
| Maximum timestamp deviation | 10 seconds |
POST /thingpark/wireless/rest/subscriptions/mine/appServers HTTP/1.1
Authorization: Bearer ...
Content-Type: application/json
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
{
"contentType": "jsontyped",
"destinations": [
{
"addresses": [
"https://www.example.com/myApp"
],
"ports": "*",
"strategy": "SEQUENTIAL"
}
],
"downlinkSecurity": {
"downlinkAsKey": "C72C6F867B150B1210ACDA5F3CDFB449",
"maxTimestampDeviation": 10,
"status": "DOWNLINK_AS_KEY"
},
"name": "My Basic HTTPS connection"
}
HTTP/1.1 201 Created
Content-Type: application/json
Location: /thingpark/wireless/rest/subscriptions/32/appServers/2227
{
"occContext": {
"version": 0,
"lastUpdate": 1546598395000,
"who": "John Doe"
},
"name": "My Basic HTTPS connection",
"ID": "TWA_199983788.568.AS",
...
}
Managing devices
Adding a LoRaWAN® device
The example in this section uses the following values of a LoRaWAN® 1.0 device:
| Required Information | Example |
|---|---|
| Device name | My device |
| Activation | OTAA |
| DevEUI | 70B3D5E756000999 |
| AppKey | 7374757A3FDD092947CE2DE9321C6040 |
Retrieving a device model
The selection of a device model is mandatory to add a device. You can retrieve a device model ID by listing the existing LoRaWAN® device models.
GET /thingpark/wireless/rest/subscriptions/mine/deviceProfiles?connectivity=LORAWAN HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
HTTP/1.1 200 OK
Content-Type: application/json
{
"briefs": [
{
"commercialName": "LoRaMote EU fw4 - class A",
"typeMAC": "LoRaMAC",
"vendor": {
"name": "Semtech",
"commercialName": "Semtech",
"commercialDescription": "Supplier of analog and mixed-signal semiconductors.",
"ID": "semtech"
},
"connectivity": "LORAWAN",
"macMajorVersion": 0,
"macMinorVersion": 3,
"motionModelIndicator": "RANDOM",
"ID": "SMTC/LoRaMoteA.1_EU",
"defaultIsmBands": [
{
"name": "EU863-870 (EU868)",
"ID": "eu868"
},
{
"name": "RU864-870 (RU864)",
"ID": "ru864"
}
]
},
...
],
"more": false
}
Extract the ID of the selected device model from the response.
Retrieving a connection
The selection of a connection is mandatory to enable the communication with an application server. You can retrieve a connection ID by listing the existing connections.
GET /thingpark/wireless/rest/subscriptions/mine/appServers HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
HTTP/1.1 200 OK
Content-Type: application/json
{
"briefs": [
{
"ID": "TWA_199982747.1972.AS",
"baseStationCount": 5,
"deviceCount": 22,
"href": "/thingpark/wireless/rest/subscriptions/32/appServers/1972",
"multicastGroupCount": 0,
"name": "my MQTT application",
"state": "ACTIVE",
"healthState": "ACTIVE",
"notification": {
"baseStationAlarms": true,
"deviceAlarms": true
},
"type": "KAFKA",
"validationState": "VALIDATED"
},
...
],
"more": false
}
If the connection is a ThingPark X IoT Flow connection, it is managed with the DX Core API as
explained in Adding a ThingPark X IoT Flow connection.
This connection is identified by the id property in DX Core API. This identifier is stored in the
tpxIotFlow.connectionId property in OSS API.
Extract the ID of the selected connection from the response.
Adding the device
The following example uses the device model ID and connection ID retrieved in the previous steps.
POST /thingpark/wireless/rest/subscriptions/mine/devices?networkSubscriptionsHandlingMode=BASIC HTTP/1.1
Authorization: Bearer ...
Content-Type: application/json
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
{
"connectivity": "LORAWAN",
"activation": "OTAA",
"EUI": "70B3D5E756000999",
"model": {
"ID": "SMTC/LoRaMoteA.1_EU"
},
"networkSubscription": {
"nwGeolocalization": false,
"prAllowed": false
},
"appServers": [
{
"ID": "TWA_199982747.1972.AS"
}
],
"name": "My device",
"appKey": "7374757A3FDD092947CE2DE9321C6040"
}
HTTP/1.1 201 Created
Content-Type: application/json
Location: /thingpark/wireless/rest/subscriptions/32/devices/2227
{
"now": 1556274131027,
"occContext": {
"version": 0,
"lastUpdate": 1546598395000,
"who": "John Doe"
},
"name": "My device",
...
}
Adding a cellular device
The example in this section uses the following values of a cellular device:
| Required Information | Example |
|---|---|
| Device name | My device |
| IMEI | 123456789012347 |
| SIM identifier | 89208013535718672291 |
The SIM identifier is the one your cellular operator gave to you, for example by printing is on the SIM card. It could be either an ICCID or an eID depending on the type of your SIM.
Retrieving a device model
The selection of a device model is mandatory to add a device. You can retrieve a device model ID by listing the existing cellular device models.
GET /thingpark/wireless/rest/subscriptions/mine/deviceProfiles?connectivity=CELLULAR HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
HTTP/1.1 200 OK
Content-Type: application/json
{
"briefs": [
{
"commercialName": "LTE Dongle",
"vendor": {
"name": "Generic",
"commercialName": "Generic",
"commercialDescription": "Generic devices.",
"ID": "generic"
},
"connectivity": "CELLULAR",
"motionModelIndicator": "RANDOM",
"ID": "CUSTOM/LTE_Dongle"
},
...
],
"more": false
}
Extract the ID of the selected device model in the response.
Retrieving a connectivity plan
The selection of a connectivity plan is mandatory to activate a device. If no connectivity plan is associated with the device, the device is suspended. You can retrieve a connectivity plan ID by listing the existing cellular connectivity plans.
GET /thingpark/wireless/rest/subscriptions/mine/networkSubscriptions?connectivity=CELLULAR HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
HTTP/1.1 200 OK
Content-Type: application/json
{
"briefs": [
{
"commercialName": "Cellular CP",
"ID": "acme-cs/cellular-cp",
"supplier": {
"ID": "acme-cs",
"commercialName": "ACME Connectivity Supplier"
},
"used": 23,
"granted": 100,
"href": "/thingpark/wireless/rest/subscriptions/32/networkSubscriptions/98",
"connectivity": "CELLULAR",
"communicationType": "UNICAST",
"nwGeolocalization": false,
"prAllowed": false,
"maxDestinationPerRoute": 5,
"thingParkCloudRouting": true,
"thirdPartyAppServersRouting": true,
"thingParkKafkaRouting": false
},
...
],
"more": false
}
Extract the ID of the selected connectivity plan from the response.
Retrieving a connection
The selection of a connection is mandatory to enable the communication with an application server. You can retrieve a connection ID by listing the existing connections.
GET /thingpark/wireless/rest/subscriptions/mine/appServers HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
HTTP/1.1 200 OK
Content-Type: application/json
{
"briefs": [
{
"ID": "TWA_199982747.1972.AS",
"baseStationCount": 5,
"deviceCount": 22,
"href": "/thingpark/wireless/rest/subscriptions/32/appServers/1972",
"multicastGroupCount": 0,
"name": "my MQTT application",
"state": "ACTIVE",
"healthState": "ACTIVE",
"notification": {
"baseStationAlarms": true,
"deviceAlarms": true
},
"type": "KAFKA",
"validationState": "VALIDATED"
},
...
],
"more": false
}
Extract the ID of the selected connection from the response.
Retrieving a cellular network context
The selection of cellular network context is mandatory to enable the communication with application servers using message or direct IP mode. You can retrieve a cellular network context ID by listing the existing cellular network contexts.
GET /thingpark/wireless/rest/subscriptions/mine/cellularNetworkContexts HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
HTTP/1.1 200 OK
Content-Type: application/json
{
"briefs": [
{
"ID": "1AF3B",
"name": "My cellular network context",
"mode": "MIXED",
"gtpTunnel": {
"subnet": "10.20.0.0/16",
"dhcpPool": "10.20.0.1-10.20.255.254",
"dns1": "10.10.0.1",
"dns2": "10.10.0.2"
},
"greTunnels": [
{
"peerAddress": "192.0.2.1"
}
],
"messageRouting": {
"sourcePort": 45826
},
"appServersReporting": {
"microflowEvents": false
},
"occContext": {
"version": 0,
"lastUpdate": 1546598395000,
"who": "John Doe"
},
},
...
],
"more": false
}
Extract the ID of the selected cellular network context from the response.
Adding the device
The following example uses the device model ID, the connectivity plan ID, the connection ID and the network context ID retrieved in the previous steps.
The IMEI can be optionally enforced.
The device is automatically assigned a unique EUI.
POST /thingpark/wireless/rest/subscriptions/mine/devices HTTP/1.1
Authorization: Bearer ...
Content-Type: application/json
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
{
"connectivity": "CELLULAR",
"enforcedIMEI": "123456789012347",
"model": {
"ID": "CUSTOM/LTE_Dongle"
},
"networkSubscription": {
"ID": "acme-cs/cellular-cp"
},
"networkContext": {
"ID": "1AF3B"
},
"appServers": [
{
"ID": "TWA_199982747.1972.AS"
}
],
"name": "My device",
"sim": {
"ID": "89208013535718672291"
}
}
HTTP/1.1 201 Created
Content-Type: application/json
Location: /thingpark/wireless/rest/subscriptions/32/devices/2227
{
"now": 1556274131027,
"occContext": {
"version": 0,
"lastUpdate": 1546598395000,
"who": "John Doe"
},
"name": "My device",
"EUI": "F03D290000000001",
"enforcedIMEI": "123456789012347",
"sim": {
"ID": "89208013535718672291",
"type": "SINGLE_IMSI"
},
...
}
Listing the devices
You can list all the devices. The list of devices is paginated. The cursor-based pagination is recommended to ensure good performances and no limitation in the number of retrieved devices.
Retrieving the first page
In order to use the cursor-based pagination, the device list must be sorted by DevEUI.
GET /thingpark/wireless/rest/subscriptions/mine/devices?sort=EUI%2Casc HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
HTTP/1.1 200 OK
Content-Type: application/json
{
"briefs": [
{
"name": "My device 1",
"model": {
"commercialName": "LoRaMote EU fw4 - class A",
"logo": "/thingpark/wireless/rest/resources/files/logo/deviceProfile/42"
},
"connectivity": "LORAWAN",
"activation": "OTAA",
"EUI": "70B3D5E756000999",
...
"href": "/thingpark/wireless/rest/subscriptions/32/devices/2227"
},
...
],
"more": true,
"now": 1556209037421,
"count": 62804,
"cursors": {
"last": "eyJFVUkiOiI3MEIzRDVFNzU2MTAwOTk5In0="
}
}
The count indicates the total number of devices. It is only returned with the first page.
If a second page is available, more is set to true. The cursors.last value can be used to
retrieve the second page as described in the next section.
Retrieving the subsequent pages
The cursors.last value of the last retrieved page must be set in the pageAfter query parameter
to retrieve the next page.
GET /thingpark/wireless/rest/subscriptions/mine/devices?sort=EUI%2Casc&pageAfter=eyJFVUkiOiI3MEIzRDVFNzU2MTAwOTk5In0%3D HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
HTTP/1.1 200 OK
Content-Type: application/json
{
"briefs": [
{
"name": "My device 101",
"model": {
"commercialName": "LoRaMote EU fw4 - class A",
"logo": "/thingpark/wireless/rest/resources/files/logo/deviceProfile/42"
},
"connectivity": "LORAWAN",
"activation": "OTAA",
"EUI": "70B3D5E756111999",
...
"href": "/thingpark/wireless/rest/subscriptions/32/devices/3054"
},
...
],
"more": true,
"now": 1556209037421,
"count": null,
"cursors": {
"last": "eyJFVUkiOiI3MEIzRDVFNzU2MjAwOTk5In0="
}
}
If a next page is available, more is set to true. The cursors.last value can be used to
retrieve the next page as described in this section.
Retrieving a device
The device resource is retrieved using the device's DevEUI.
GET /thingpark/wireless/rest/subscriptions/mine/devices/e70B3D5E756000999 HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
HTTP/1.1 200 OK
Content-Type: application/json
{
"now": 1556274131027,
"occContext": {
"version": 0,
"lastUpdate": 1546598395000,
"who": "John Doe"
},
"name": "My device",
"connectivity": "LORAWAN",
"activation": "OTAA",
"appEUI": "65FC7B3530A44FB9",
"EUI": "70B3D5E756000999",
...
}
Retrieving the traffic history of a device
You can retrieve the traffic history of a device using the device's DevEUI. The following example retrieves a daily aggregation of the traffic for the last 7 days in the Europe/Paris timezone.
GET /thingpark/wireless/rest/subscriptions/mine/devices/e70B3D5E756000999/frames/aggregated?duration=P7D&step=P1D&timezone=Europe/Paris HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
HTTP/1.1 200 OK
Content-Type: application/json
{
"now": 1691574920713,
"briefs": [
{
"timestamp": 1691532000000,
"instantPerMean": 0.021186423,
"meanPerMean": 0.058798883,
"rssiMean": -60.898304,
"snrMean": 0.3411017,
"espMean": -62.225357,
"mf": {
"count": 0,
"size": 0,
"sizeUp": 0,
"sizeDown": 0,
"duration": 0
},
"up": {
"count": 58,
"size": 530,
"countOnTime": 58,
"sizeOnTime": 530,
"countLate": 0,
"sizeLate": 0,
"countLost": 8,
"subTypes": []
},
"dw": {
"count": 60,
"size": 0,
"countSent": 59,
"sizeSent": 0,
"countFailed": 1,
"sizeFailed": 0,
"subTypes": []
}
},
...
]
}
Listing the device alarms
You can list all the device alarms. The list of alarms is paginated. The cursor-based pagination is recommended to ensure good performances and no limitation in the number of retrieved alarms.
Cursor-based pagination is new in ThingPark Enterprise SaaS 8.1.3 / self-hosted ThingPark Enterprise 8.1.0
Retrieving the first page
In order to use the cursor-based pagination, the alarm list must be sorted by alarm Uid.
GET /thingpark/wireless/rest/subscriptions/mine/devices/alarms?sort=alarmUid%2Casc HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
HTTP/1.1 200 OK
Content-Type: application/json
{
"briefs": [
{
"ID": 4,
"alarmUid": "5b1f81e7a1ae4234a037be11",
"device": {
"name": "My device 1",
"EUI": "70B3D5E756000999"
},
...
"href": "/thingpark/wireless/rest/subscriptions/32/devices/2227/alarms/5b1f81e7a1ae4234a037be11"
},
...
],
"more": true,
"count": 2390,
"cursors": {
"last": "eyJhbGFybVVpZCI6IjViMWY4MWU3YTFhZTQyMzRhMDM3Y2QzNyJ9"
}
}
The count indicates the total number of alarms. It is only returned with the first page.
If a second page is available, more is set to true. The cursors.last value can be used to
retrieve the second page as described in the next section.
Retrieving the subsequent pages
The cursors.last value of the last retrieved page must be set in the pageAfter query parameter
to retrieve the next page.
GET /thingpark/wireless/rest/subscriptions/mine/devices/alarms?sort=alarmUid%2Casc&pageAfter=eyJhbGFybVVpZCI6IjViMWY4MWU3YTFhZTQyMzRhMDM3Y2QzNyJ9 HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
HTTP/1.1 200 OK
Content-Type: application/json
{
"briefs": [
{
"ID": 17,
"alarmUid": "5b1f81e7a1ae4234a037d092",
"device": {
"name": "My device 101",
"EUI": "70B3D5E756111999"
},
...
"href": "/thingpark/wireless/rest/subscriptions/32/devices/3054/alarms/5b1f81e7a1ae4234a037d092"
},
...
],
"more": true,
"count": null,
"cursors": {
"last": "eyJhbGFybVVpZCI6IjViMWY4MWU3YTFhZTQyMzRhMDM3ZTlhMiJ9"
}
}
If a next page is available, more is set to true. The cursors.last value can be used to
retrieve the next page as described in this section.
Managing multicast groups
Adding a multicast group
The example in this section uses the following values of a LoRaWAN® 1.0 multicast group:
| Required Information | Example |
|---|---|
| Multicast group name | My multicast group |
| DevEUI | 70B3D5E756000999 |
| DevAddr | 785D25E2 |
| NwkSKey | 7374757A3FDD092947CE2DE9321C6040 |
| AppSKey | 8D67B0D6359D11ACFC45AD4BB9CE2D4F |
| Class | C |
| Downlink data rate | 15 |
| Downlink frequency | 869.525 MHz |
| Base station tags | tag1 in SUBSCRIPTION namespace |
Retrieving a connection
The selection of a connection is mandatory to enable the communication with an application server. You can retrieve a connection ID by listing the existing connections. The procedure is the same than for a device, see Retrieving a connection for more details.
Adding the multicast group
The following example uses the connection ID retrieved in the previous steps.
POST /thingpark/wireless/rest/subscriptions/mine/devices?networkSubscriptionsHandlingMode=BASIC HTTP/1.1
Authorization: Bearer ...
Content-Type: application/json
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0
{
"name": "My multicast group",
"EUI": "70B3D5E756000999",
"nwAddress": "785D25E2",
"nwKey": "7374757A3FDD092947CE2DE9321C6040",
"appKeys": "<AppSKeys><AppSKey Port=\"*\">8D67B0D6359D11ACFC45AD4BB9CE2D4F</AppSKey></AppSKeys>",
"class": "C",
"downlinkDataRate": 15,
"downlinkFrequency": 869.525,
"bss": {
"tags": [
{
"name": "tag1",
"namespace": "OPERATOR"
}
]
},
"appServers": [
{
"ID": "TWA_199982747.1972.AS"
}
]
}
HTTP/1.1 201 Created
Content-Type: application/json
Location: /thingpark/wireless/rest/subscriptions/32/devices/2227
{
"now": 1556274131027,
"occContext": {
"version": 0,
"lastUpdate": 1546598395000,
"who": "John Doe"
},
"name": "My multicast group",
...
}