Back to top

Cometa API

This document describes the Cometa HTTP REST and Websockets API to use in a Web or mobile application to interact with remote IoT devices using the Cometa platform.

Mode of Operation

Cometa is an edge server mediating communication between applications and remote devices. Typical communication needs of a IoT device include responding to a message request from an application and sending event data to a server. Both paradigms are covered in the Cometa API.

Devices connect to Cometa using the attach HTTP method to establish a permanent connection to the Cometa server. Once a device is attached, Cometa provides the underlying transport for both message exchange according to a RPC (Remote Procedure Call) pattern, and to establish a data pipe used by the devices to send asynchronous events data upstream.

Cometa follows the HTTP chunked transfer encoding format of the HTTP 1.1 specifications.

Messages to Device

After attaching to Cometa, a device starts a listening loop to receive RPC requests from Cometa. A message sent to a device is assumed to include a command and some parameters, and is also expected to receive a message response from the device.

Applications use the send method to invoke a RPC to a remote device, with the message body containing the request and the parameters. Once Cometa receives an RPC message for the device from the application, it relays the request to the device and expects a synchronous reply to the message, following a typical RPC (Remote Procedure Call) pattern. The reply received from the device is then relayed back to the requesting application as response to the RPC invocation.

Developers can take advantage of the higher level C/C++ library in the Cometa Devices SDK to accelerate firmware development and integration of devices in the Cometa platform.

Data Events

A device can use the connection to Cometa to send asynchronous upstream data, that is not in response to a RPC invocation. For instance, to send an event notification upstream. Sensor data that are acquired periodically can also be sent to the data pipe upstream by a device at any time and not as a RPC reply.

Cometa can be configured with webhooks to forward event upstream messages to an external application server or to a document database such as MongoDB.

Websockets

Cometa exposes a unique Websocket URL endpoint for each device attached to the server. Details on how to obtain the URL endpoint are decribed below.

Once a Websocket to a device is opened, an application has a real-time, bi-directional connection with the device. The payload sent by an application must follow the RPC pattern. in a similar way to the HTTP send method. However, since the communication has been already established, the exchange happens in real-time, without any overhead. Also, the application receives all the real-time events sent upstream by the device. The events are received by a Websocket application, regardless of the presence or not of a forwarding events webhook configured in Cometa.

Wire Protocol

A device attached to Cometa has a bi-directional transport for RPC and an upstream data pipe for events, but Cometa does not enforce any wire protocol, that is left to the application.

Using Cometa is straightforward to implement the JSON-RPC protocol for remote interactions with devices, and to send asynchronous data upstream as JSON objects. See the device code examples in the Cometa Device SDK documentation.

Cometa Applications

Both devices and applications use the concept of application both for partitioning devices into reserved areas, and for authentication purposes. A Cometa application provides credentials in the form of an ‘application-id’ and application-secret. The application-id is unique for the server. Cometa applications and their credentials are stored in the /etc/cometa.conf server configuration file.

Each device belongs to a Cometa application and has a unique device ID.

Base URL

http://{HOST}:{PORT}/v1/

Authentication

All HTTP requests, with exception of device attach, need to be authenticated using the following HTTP Header:

HEADER Description Value
Authorization authorization token OAuth {APPLICATION-SECRET}

Example:

Authorization: OAuth 8ad3773142a6692b25b7

Devices

Interactions with devices using HTTP methods.

Important Info

Devices need to be attached before they can receive RPC invocations or send events data.

For a device to attach to a Cometa server only the Application ID for the application and a unique Device ID are required. In the HTTP POST to attach a Device to Cometa the HTTP authorization header is not required. This is to avoid storing the Authorization token in a device.

If a Device is successfully subscribed, the response object contains the preferred heartbeat frequency in seconds, and the Epoch time of the server in the timestamp. The heartbeat frequency is only a hint and devices can decide whether to use it or to ignore it, however a heartbeat must be sent by a device to keep the connection. See details in the Cometa Device SDK documentation about the format of a heartbeat message.

Device

Device methods.

Attach a Device
POST/applications/{app_id}/devices/{device_id}

Attach the device invoking the method.

Once a sevice has attached to the Cometa server, the HTTP connection is reverted and persisted. Further interactions from an application follow the request/response typical of a synchronous RPC pattern. The method body contains a string used as generic platform information.

Attempts to attach a device that is already attached, is rejected by the Cometa server with a 409 Conflict HTTP status code.

Parameters
HideShow
app_id
string (required) Example: 946604ed1d971eca2879

The Application ID

device_id
string (required) Example: ca375b970d037fb7fb2e

The Device ID

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "BCMUSI14"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "msg": "200 OK",
  "heartbeat": 60,
  "timestamp": 1426274354
}
Response  409
HideShow
Headers
Content-Type: application/json
Body
{
  "msg": "409 Conflict"
}

Device presence info
GET/applications/{app_id}/devices/{device_id}

Obtain information about presence and statistics of the specified device.

The Device’s persistent connection to the Cometa server is maintained by the Device sending a heartbeat message to the server regularly, as specified in the Cometa server configuration. The heartbeat insures also that the port assigned in a NAT device the Device might be connected to, is not reused as result of inactivity.

The heartbeat message is not propagated to the application but used only by the Cometa server to determine the Device presence.

It is important to notice that when an attached device goes away abruptly without closing the connection, the Cometa server may still consider the device as attached, until an inactivity timeout occurs for lack of receiving an heartbeat from the device. The typical timeout with a heartbeat setting of 60 seconds is of 120 seconds.

Parameters
HideShow
app_id
string (required) Example: 946604ed1d971eca2879

The Application ID

device_id
string (required) Example: ca375b970d037fb7fb2e

The Device ID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "device_id": "45F026",
  "ip_address": "169.237.139.216:10371",
  "heartbeat": "1440100577",
  "info": "BCMUSI14",
  "stats": {
    "connected_at": "1440095840",
    "messages": "12",
    "errors": "0",
    "bytes_up": "108652",
    "bytes_down": "4560",
    "latency": "2",
    "websockets": "0"
  }
}
Response  423
HideShow
Headers
Content-Type: application/json
Body
{
  "msg": "Error 418 in the request: Device not attached"
}

Detach a Device
DELETE/applications/{app_id}/devices/{device_id}

Detach the specified device from the Cometa server.

Parameters
HideShow
app_id
string (required) Example: 946604ed1d971eca2879

The Application ID

device_id
string (required) Example: ca375b970d037fb7fb2e

The Device ID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "msg": "200 OK"
}
Response  418
HideShow
Headers
Content-Type: application/json
Body
{
  "msg": "418 Device not attached"
}

Send to Device

Send a message containing a request to an attached Device and receive the reply in the response.

Only one request at a time can be processed by a device. A 423 Locked HTTP status code is returned if the device is still processing a previous request.

Send a message to a device
POST/applications/{app_id}/devices/{device_id}/send

Parameters
HideShow
app_id
string (required) Example: 946604ed1d971eca2879

The Application ID

device_id
string (required) Example: ca375b970d037fb7fb2e

The Device ID

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "cmd": "get",
  "params": [
    "compressor_power",
    "cabin_temperature"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "ok",
  "reply": [
    {
      "value": "251.32",
      "properties": {
        "ReadingType": "double",
        "Timezone": "America/Los_Angeles",
        "UnitofMeasure": "Watt"
      },
      "path": "/cloudfridge/100007/compressor_power",
      "uuid": "2180322f-6999-4e89-8320-e2127ffc26d3"
    },
    {
      "value": "4.21",
      "properties": {
        "ReadingType": "double",
        "Timezone": "America/Los_Angeles",
        "UnitofMeasure": "Deg C"
      },
      "path": "/cloudfridge/100007/cabin_temperature",
      "uuid": "9ebb7573-d55a-4597-8793-ffe4db0773eb"
    }
  ]
}
Response  423
HideShow
Headers
Content-Type: application/json
Body
{
  "msg": "423 Locked"
}
Response  408
HideShow
Headers
Content-Type: application/json
Body
{
  "msg": "408 Request Time-out"
}
Response  418
HideShow
Headers
Content-Type: application/json
Body
{
  "msg": "418 Device not attached"
}

Websockets

Websockets communication with devices.

Obtain a Device Websocket key

A Websocket endpoint for a device includes an authorization key that is provided by the websocket method.

The key can only be used once, and the key has to be requested every time an application opens a device Websocket endpoint.

A device Websocket endpoint is created by Cometa as follows:

ws://{HOST}:{PORT}/websockets/{DEVICE_ID}/{DEVICE_KEY}

For example:

ws://api.cometa.io/websockets/700012/e8d8349a7afb3a7c70e93b85a348b21762b518de

Get a Websocket device key
GET/applications/{app_id}/devices/{device_id}/websocket

Parameters
HideShow
app_id
string (required) Example: 946604ed1d971eca2879

The Application ID

device_id
string (required) Example: ca375b970d037fb7fb2e

The Device ID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "device_id": "700012",
  "device_key": "e8d8349a7afb3a7c70e93b85a348b21762b518de"
}
Response  418
HideShow
Headers
Content-Type: application/json
Body
{
  "msg": "418 Device not attached"
}

Application

Also Markdown formatted. This also includes automatic “smartypants” formatting – hooray!

Info

Get application info.

Application info
GET/applications/{app_id}

Parameters
HideShow
app_id
string (required) Example: 946604ed1d971eca2879

The Application ID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "app_id": "946604ed1d971eca2879",
  "app_name": "cometatest",
  "stats": {
    "num_devices": "10000",
    "messages": "8896837",
    "errors": "0",
    "bytes_up": "302578104",
    "bytes_down": "286847744",
    "latency": "8",
    "latency_min": "0",
    "latency_max": "12",
    "std_deviation": "1.000",
    "websockets": "500"
  }
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "msg": "403 Forbidden"
}

Devices

List devices attached to an application methods.

List devices
GET/applications/{app_id}/devices

Parameters
HideShow
app_id
string (required) Example: 946604ed1d971eca2879

The Application ID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "num_devices": 10,
  "devices": [
    "70001F",
    "700012",
    "70001A",
    "45F01C",
    "45F011",
    "70001E",
    "45F003",
    "45F026",
    "45F162",
    "45F025"
  ]
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "msg": "403 Forbidden"
}

Generated by aglio on 22 Aug 2015