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:

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#/Connection where <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",
    ...
}

Listing the devices

You can list all the devices.

GET /thingpark/wireless/rest/subscriptions/mine/devices 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",
            "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": false,
    "now": 1556209037421
}

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 ...
Content-Type: application/json
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": []
            }
        },
        ...
    ]
}

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",
    ...
}

Managing connections​

Adding a ThingPark X IoT Flow connection​

Adding a Basic HTTPS connection​

Managing devices​

Adding a LoRaWAN® device​

Retrieving a device model​

Retrieving a connection​

Adding the device​

Listing the devices​

Retrieving a device​

Retrieving the traffic history of a device​

Managing multicast groups​

Adding a multicast group​

Retrieving a connection​

Adding the multicast group​

Managing connections

Adding a ThingPark X IoT Flow connection

Adding a Basic HTTPS connection

Managing devices

Adding a LoRaWAN® device

Retrieving a device model

Retrieving a connection

Adding the device

Listing the devices

Retrieving a device

Retrieving the traffic history of a device

Managing multicast groups

Adding a multicast group

Retrieving a connection

Adding the multicast group