# SETTING UP A CONNECTION INSTANCE

# Creating a Connection instance

Follow the example below to create your connection:

POST /connections
 
{
  "connectorId": "actility-aws-iot",
  "name": "Test AWS Connection",
  "active": true,
  "alarms": [
    {
      "startTime": "2019-01-31T09:00:00+01:00",
      "endTime": "2019-01-31T18:00:00+01:00",
      "timezone": "Europe/Paris",
      "recurrence": [
        {
        "frequency": "weekly",
        "byDays": ["monday", "tuesday", "wednesday", "thursday", "friday"]
        }
      ],
      "uplinkRateMinPerHour": 10,
      "message": "Low rate during business day..."
    }
  ],
  "configuration": {
    "description": "AWS Europe Datacenter",
    "createDevices": true,
    "sendMetadata": false,
    "sendRawDecodedFormat": true,
    "uplinkTimeValidity": "5m",
    "downlinkEnabled": false,
    "downlinkAsId": "TWA_199983788.1972.AS",
    "downlinkAsKey": "9311e33d7d44fc52215b0dc789aa1d22",
    "downlinkPort": 5,
    "uplinkTopicPattern": "tpx/things/{DevEUI}/uplink",
    "downlinkTopicPattern": "tpx/things/{DevEUI}/downlink",
    "deviceType": "actilitytestsensor",
    "region": "eu-central-1",
    "accountPrefix": "a2sheeefctigr-ats",
    "secretAccessKey": "lymHcfefddzerrZHnV5Q5YN/GTMFNiTREAj/7dz3358",
    "accessKeyId": "AKIAJUJWTO76B3XZGHYA",
    "certificateId": "arn:aws:iot:eu-central-1:101513775872:cert/8be79f58542e4f8983t45fgjb0842465efa41fea4554fa974",
    "certificate": "-----BEGIN CERTIFICATE-----xxx-----END CERTIFICATE-----",
    "privateKey": "-----BEGIN RSA PRIVATE KEY-----xxx-----END RSA PRIVATE KEY-----"
  }
}

None of the fields is mandatory.

# Common Parameters

The following table lists the properties that are applicable to all connections.

Property Configuration value
 
"active"
 (optional, default = true)
  • Defines if you enable or not your connection.
  • When set to false and if previously active, the connection is stopped under 1mn.
"connectorId"
 (mandatory)		 Defines the type of connector that you choose.E.g.:actility-aws-iot or actility-azure-iot
"name"
 (mandatory)		 Name of the connection. Used for information only.
"alarms"
 (optional)		 Defines alarms on low rate flow. For more information, see the section below.
"configuration"
 (mandatory)
  • Defines all specific parameters of a connection.
  • All properties available are defined for each connector. For more information, see the related chapters in this document.
"configuration/description"
 (optional)		 Description text for the configuration (optional)
"configuration/createDevices"
 (optional, default = true)
  • When set to true, the connection should try to register on-the-fly devices on the cloud on the first uplink sent (if not yet created).
  • Default value is true.

  • If this is not wanted/allowed (devices are already created on the cloud), set the value to false.

    If it is found on the Cloud side, it is used. If it is not found on the Cloud side and createDevices is set to false, and error event is logged, and the uplink is skipped.

"configuration/sendMetadata"
 (optional, default = false)		 For backward compatibility with tpdx-dataflow you can set sendMetadata to true to remove ‘DevEUI_uplink’ root node from uplinks.Default value in tpx-flow is false. 
"configuration/sendRawDecodedFormat"
 (optional, default = false)		 If sendMetadata is set to false (default value) and sendRawDecodedFormat is set to true, the uplink sent to the cloud contains only ‘payload’ field content. In case ‘payload’ is not present, full uplink msg body is sent. Default values is false, so that full uplink msg body is sent. 
"configuration/uplinkTimeValidity"
 (optional)

If set with a value (for instance, 1m), uplinks older than the set validity, will not be sent to the cloud service, and an alarm event is saved in the events’ log.

No default value.

When connections have not started or have downtimes, uplinks are accumulating. Most of these uplinks expire before connections get up again.

"configuration/downlinkEnabled"
 (optional, default = true)
  • When set to true, the connection should use downstream.
  • Default value is true.
  • If set to false, it will disable downstream.
"configuration/downlinkAsId"
 (optional)		 In cases where downlinks need authentication, set the AS_ID value to downlinkAsId. 
"configuration/downlinkAsKey"
 (optional)		 In cases where downlinks need authentication, set the AS_KEY value to downlinkAsKey.
"configuration/downlinkPort"
 (optional)		 In cases where downlinks messages don’t specify a downlink port, set the default port to downlinkPort.
"configuration/reconnectStrategy"
 (optional, default = NORMAL)

Reconnect strategy to use when a connection is unable to get to OPENED state in time.

Possible values are:

    CALM

  • Each 10mn for 12 hour
  • Each hour for 1 day
  • Set the connection to CLOSED

    NORMAL - default

  • Each 5mn for 1 hour
  • Each hour for 1 day
  • Each day without limitation of time

    AGGRESSIVE

  • Each 3mn for 3 hour
  • Each 30mn for 1 week
  • Each hour without limitation of time
  • Automatic restart, if no uplink has been detected during more than one hour.

# Configuring the Low Message Rate Alarm

ThingPark X IoT Flow has a built-in functionality to detect unusually low uplink message rates processed by the connector towards the IoT cloud platform. This rate is set by connection and not for a specific Device. You can set up one or several low message rate alarms by specifying the following parameters:

  • A recurring time window for which the minimum message rate will be checked.
  • The minimum uplink message rate expected during this time window for the connector instance.

For example, your Devices send on average 1 message per hour, and you have a pool of 20 Devices associated with this connector via ThingPark X IoT Flow. Therefore, you expect 20 messages per hour during open hours through the connector instance. You believe that the average rate of uplinks per hour should never get below 15 messages per hour during open hours, and you configure an alarm as in the example below:

  • If during off hours the rate is lower than 15 messages per minute, no alarm is raised.
  • If during open hours the rate gets lower than 15 messages per minute, a low-level uplink message rate alarm event is raised and added to the event log.
"alarms": [
    {
      "startTime": "2019-01-31T09:00:00+01:00",
      "endTime": "2019-01-31T18:00:00+01:00",
      "timezone": "Europe/Paris",
      "recurrence": [
        {
        "frequency": "weekly",
        "byDays": ["monday", "tuesday", "wednesday", "thursday", "friday"]
        }
      ],
      "uplinkRateMinPerHour": 15,
      "message": "Low rate during business day..."
    }
  ]

Note

ThingPark Wireless also has a message rate alarm functionality per Device, which is configured per Device profile. This functionality generates alarms in ThingPark Wireless Device Manager tool and APIs. The ThingPark X low message rate alarm functionality is completely independent and accessed via TPX IoT Flow API.

# Retrieving Connection Instance Details

Follow the example below to list your connections:

GET /connections
 
[
  {
    "configuration": {
      "protocol": "SSL",
      "region": "eu-central-1",
      "accountPrefix": "a2e8k469sk385s-ats",
      "accessKeyId": "*****",
      "secretAccessKey": "*****",
      "certificateId": "arn:aws:iot:eu-central-1:076081621542:cert/28e7cc38a99f78b3d0b2b1af5d4cd8ddc83264ad435ce4248f4146ccc34e3329",
      "privateKey": "*****",
      "deviceType": "actilityDeviceType",
      "uplinkTopicPattern": "tpx/things/{DevEUI}/uplink",
      "downlinkTopicPattern": "tpx/things/{DevEUI}/downlink",
      "description": "Test AWS Connection configuration",
      "createDevices": true,
      "sendMetadata": false,
      "sendRawDecodedFormat": false,
      "certificate": "*****"
    },
    "id": "8",
    "connectorId": "actility-aws-iot",
    "name": "Test AWS Connection",
    "active": true,
    "startupTime": "2019-09-27T10:08:08.309+02:00",
    "state": "OPENED"
  },
]

Beside connection details, you get also startupTime and connection state.

# Connection states

The state of a connection is provided by the connection object. An action does not change immediately the state of a connection due to the asynchronous architecture. When you start a connection, the connection can remain on CLOSED state during a short period before changing to OPENING. It is a normal behavior. Depending on the cloud connector, a connection can take time to be in a stable state.

Connection states are depicted in the following table.

Connection state Property
OPENING The connection is currently opening.
OPENED The connection is up and running.
CLOSED The connection is currently closing.
AUTHENTICATING The connection is currently authenticating.
AUTHENTICATION_FAILED The authentication has failed.
UNREACHABLE The bridge that hosts the connection is unreachable; none of the connection information can be retried.
DEACTIVATED The connection is currently authenticating.
AUTHENTICATING The connection is deactivated.

The corresponding workflow is illustrated In the following graphic:

img

Last Updated: 1/18/2021, 10:22:26 AM

← Setting up an IoT Flow instance →