Skip to main content

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.

info

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:

The example in this section uses the following values:

Required InformationExample
Connection nameMy MQTT connection
Connector identifieractility-mqtt-iot
MQTT broker hostnamemyhostname.com:8883
Uplink topic patternmqtt/things/\{DevEUI\}/uplink
Downlink topic patternmqtt/things/\{DevEUI\}/downlink
ProtocolSSL
Usernamemycompany
Passwordbar
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 InformationExample
Connection nameMy Basic HTTPS connection
URLhttps://www.example.com/myApp
Content typeJSON
Tunnel interface authentication keyC72C6F867B150B1210ACDA5F3CDFB449
Maximum timestamp deviation10 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 InformationExample
Device nameMy device
ActivationOTAA
DevEUI70B3D5E756000999
AppKey7374757A3FDD092947CE2DE9321C6040

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 InformationExample
Device nameMy device
IMEI123456789012347
SIM identifier89208013535718672291

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 InformationExample
Multicast group nameMy multicast group
DevEUI70B3D5E756000999
DevAddr785D25E2
NwkSKey7374757A3FDD092947CE2DE9321C6040
AppSKey8D67B0D6359D11ACFC45AD4BB9CE2D4F
ClassC
Downlink data rate15
Downlink frequency869.525 MHz
Base station tagstag1 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",
...
}
Ask AI