Connio

The Connio API Developer Hub

Welcome to the Connio API developer hub. You'll find comprehensive guides and documentation to help you start working with Connio API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Understanding Builtin Profiles

This tutorial explains how to use predefined device profiles

Predefined device profiles come with built-in logic to automate common IoT scenarios you might need when you manage your devices. Like class inheritance in OOP, inherited device profiles carries their capabilities including their alerts with them into their child.

Since predefined profiles consist of properties and not attributes, each property can be used in different alarm scenarios. For example, if you inherit your profile from Device, and create an alert connected to Active property at Device level, your profile does also benefit from this alert automatically. See alerts for details.

Beware of IS-A relationship

Similar to OOP, Connio's device profile inheritance mechanism allows profiles to be arranged in a hierarchy that represents "is-a-type-of" relationships. For example, profile CellularDevice might inherit from profile ConnectedDevice. All the data and methods available to the parent class also appear in the child class with the same names.

Device

A generic profile to represent any type of bidirectional data source. It helps device developer to monitor data-source/device activity based on communication frequency, and track inbound and outbound traffic.

It consists of the following properties:

Name
Description
Type
Values

Active

This property is set to inactive automatically if the device is not communicating with the system within the timeframe defined by its period attribute. It is always unknown if period is not set to any positive integer duration (i.e 0).

enum

active, inactive, unknown.

LastIn

Stores the details of the last write operation completed by the device. The details consist of the name of the last written property and timestamp.

string

property name

LastOut

Stores the details of the last data successfully sent to the device by the platform. The details consist of the name of the property and timestamp.

string

property name

ConnectedDevice

A generic profile to represent any type of connected device. It helps device developer to monitor connectivity of the device. It inherits Device device profile.

It consists of the following properties:

Name
Description
Type
Values

ConnectionInfo

Provides additional information about the connectivity of the device such as its remote IP and connected endpoint. It consists of ip and endpoint fields. endpoint can be mqtt or rest.

object

ConnectionStatus

If the device is connected to the platform through MQTT, it set automatically to online by the system. Otherwise it is set to offline.

enum

online, offline.

Gateway

Some IoT scenarios require a gateway that facilitates the communication between the edge devices and your solution backend, such as smart home systems. Gateway profile helps developers to model their IoT solutions without losing semantics about the configuration of their devices.

The problem

If you have constant number of sensor types and constant number of sensors per installation, the low hangin fruit approach would be to create a single device profile with multiple properties where each property corresponds to a sensor. As long as your gateway's firmware manages the mapping between the sensors and your profile properties, it can communicates with the platform securely through a single device key. The only issue with this approach is it cannot keep the device inventory knowledge for your deployment. This causes extra effort to keep track of the sensors. Many IoT systems are modelled like that.

This approach falls short when you have multiple types of sensors that can be installed in different quantities per deployment (e.g. some customers have 2 door sensors, some have 5, some have none). In the Connio platform such tightly coupled, loosely deployed device configurations are called as device systems. One ugly hack could be to to create a separate device profile per each device combination. Although it might seem attractive at first, this approach is not recommended due to (1) you lose track of the devices in the field by replacing them with properties in your model, (2) you can create only so many device profiles per account in the Connio platform - there is a hard limit for security reasons, (3) this makes your solution unmanageable in the long run. This is not how device profile meant to be used in The Connio platform.

The right approach would be to create a device profile for each sensor type and a device for each sensor. Each customer/deployment can be modelled after a sub account or app in the platform, and can be assigned to their unique system - actual device combination deployed in the field. This way Connio's device inventory capabilities can be leveraged, and devices will be managed as close as possible to the real situation. Although sounds good, this approach comes with a slight issue. Connio assigns a unique device key to each device to authenticate and authorize the data exchange. When we create a unique device for each sensor, the platform accepts data only when the proper keys are used. Without the help from the solution backend, this device key management should be managed by the gateway's firmware (i.e. mapping each edge device to a device key locally), and makes the firmware code slightly more complex and hard to manage.

The Solution

Enter the Gateway device profile. The Gateway profile solves this key management issue by moving the burden form the firmware to the device backend. The Connio platform allows gateways to exchange data on behalf of the devices within their device system. The security is managed on the platform side. The gateway firmware only needs to know a single key.

A device generated from the Gateway profile can be associated with the edge devices residing in the same system by adding edge device ids into the device key id list of the gateway. That's it. The rest will be managed by the platform.

PUT .../v3/devices/_dev_785862679194761789/apikey

{
  "context": {
    "type": "device",
    "ids": [
      "_dev_785862679194761789, _dev_200062579194761790, _dev_085862679194761791"
    ]
  }
}

where _dev_785862679194761789 is your gateway device id, other ids are belong to the edge devices working behind this gateway.

Once done, gateway can read/write data to/from the platform on behalf of these devices using its own device key by simply replacing its device's id with the edge device's id. For example:

POST .../v3/data/devices/_dev_200062579194761790/properties/temperature

Note that device key for this request is belong to the gateway.

{
  "dps" : [
        { "t": "2017-10-12T00:34:34Z", 
          "v": 0.23
        }
      ]
}

Same goes for the MQTT connections. The gateway can publish and subscribe to topics involving their edge devices.

Another goody about gateway behaviour related to MQTT is, gateway shares its connection status info with its edge devices automatically. Meaning that, if a gateway disconnects, all edge devices within the system of this gateway gets a disconnected notification to their connection status property.

You can create your own gateways by inhering from the default Gateway device profile.

Understanding Builtin Profiles


This tutorial explains how to use predefined device profiles

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.