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    

Building Device Systems with Gateway Profile

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 any 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.

Building Device Systems with Gateway Profile

Suggested Edits are limited on API Reference Pages

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