Skip to content

Protocol specification (v1.0.0)

Jump to bottom
Thiago Figueredo Cardoso edited this page Feb 18, 2019 · 14 revisions

This document specifies the KNoT Cloud WebSocket protocol.

Message format

All messages (requests or responses) are stringified JSON objects in the following format:

  • type String Message type name
  • data Any (Optional) Message-defined data

Example

{
  "type": "register",
  "data": {
    "type": "gateway",
    "name": "Home gateway",
    "active": false
  }
}

Message types (Device-Cloud)

identity

Identifies with the server. It establishes a session that is needed to send any other message.

Data

Object in the following format:

  • id String Device ID.
  • token String Device token.

Response

Replies with ready when successful or error otherwise.

Example

{
  "type": "identity"
  "data": {
    "id": "78159106-41ca-4022-95e8-2511695ce64c",
    "token": "d5265dbc4576a88f8654a8fc2c4d46a6d7b85574"
  }
}

register

Registers a device on the cloud. This operation can only be performed by users or devices of type 'gateway'.

Data

Object in the following format:

  • type String Device type. One of: 'thing', 'gateway' or 'app'.
  • id String (Optional, mandatory when type is 'thing') KNoT ID. Will be used as device ID.
  • name String (Optional) Device name.
  • active Boolean (Optional) Defines whether the 'gateway' being created is active or not.

Response

Replies with registered when successful or error otherwise.

Events

Triggers registered event.

Example

{
  "type": "register",
  "data": {
    "type": "gateway",
    "name": "Home gateway",
    "active": false
  }
}

unregister

Unregisters a device from the cloud. This operation can only be performed by users or devices of type 'gateway'.

Data

Object in the following format:

  • id String Device ID.

Response

Replies with unregistered when successful or error otherwise.

Events

Triggers unregistered event.

Example

{
  "type": "unregister",
  "data": {
    "id": "78159106-41ca-4022-95e8-2511695ce64c"
  }
}

devices

Search registered devices.

Data

Object in the following format:

  • query Object (Optional) Object specifying filters for device's properties.

Response

Replies with devices when successful or error otherwise.

Example

{
  "type": "devices",
  "data": {
    "query": {
      "type": "gateway"
    }
  }
}

token

Creates a new session token for a device. The authenticated device must have permission to create a token for the target device.

Data

Object in the following format:

  • id String Target device ID.

Response

Replies with created when successful or error otherwise.

Example

{
  "type": "token",
  "data": {
    "id": "78159106-41ca-4022-95e8-2511695ce64c"
  }
}

revoke

Revokes a token for a device. The authenticated device must have permission to revoke a token for the target device.

Data

Object in the following format:

  • id String Target device ID.
  • token String Token to be revoked.

Response

Replies with revoked when successful or error otherwise.

Example

{
  "type": "revoke",
  "data": {
    "id": "78159106-41ca-4022-95e8-2511695ce64c",
    "token": "d5265dbc4576a88f8654a8fc2c4d46a6d7b85574"
  }
}

schema

Updates the device schema. This operation can only be performed by devices of type 'thing'.

Data

Object in the following format:

  • schema Array Set of properties (associated to KNoT semantic) with details about sensors/actuators.
    • sensorId Number Sensor id between 0 and the maximum number of sensors defined for that thing.
    • typeId Number Sensor type, e.g. whether it is a presence sensor or distance sensor.
    • valueType Number Value type, e.g. whether it is an integer, a floating-point number, etc.
    • unit Number Sensor unit.
    • name String Sensor name.

Response

Replies with updated when successful or error otherwise.

Example

{
  "type": "schema",
  "data": {
    "schema": [
      {
        "sensorId": 251,
        "valueType": 2,
        "unit": 1,
        "typeId": 13,
        "name": "Tank Volume"
      },
      {
        "sensorId": 252,
        "valueType": 1,
        "unit": 1 ,
        "typeId": 5,
        "name": "Outdoor Temperature"
      },
      {
        "sensorId": 253,
        "valueType": 3,
        "unit": 0,
        "typeId": 65521,
        "name": "Lamp Status"
      }
    ]
  }
}

activate

Activates a gateway. This operation can only be performed on devices of type 'gateway'. The authenticated device must have permission to edit the target device.

Data

Object in the following format:

  • id String Target device ID.

Response

Replies with activated when successful or error otherwise.

Example

{
  "type": "schema",
  "data": {
    "id": "78159106-41ca-4022-95e8-2511695ce64c"
  }
}

metadata

Updates a device's metadata. Only the specified properties will be updated. The authenticated device must have permission to edit the target device.

Data

Object in the following format:

  • id String Target device ID.
  • metadata Object An object containing the properties to be updated.

Response

Replies with updated when successful or error otherwise.

Example

{
  "type": "metadata",
  "data": {
    "id": "78159106-41ca-4022-95e8-2511695ce64c",
    "metadata": {
      "name": "New gateway"
    }
  }
}

data

Publishes data. This operation can only be performed by device of type 'thing'.

Data

Object in the following format:

  • sensorId Number Sensor id between 0 and the maximum number of sensors defined for that thing.
  • value String|Boolean|Number Sensor value. Strings must be Base64 encoded.

Response

Replies with published when successful or error otherwise.

Events

Triggers data event.

Example

{
  "type": "data",
  "data": {
    "sensorId": 1,
    "value": 10.57
  }
}

getData

Request the thing to send its current data items values. This operation can only be performed by device of type 'app'.

Data

Object in the following format:

  • id String Device ID.
  • sensorIds Array List of sensor IDs to be sent, each one is a Number.

Response

Replies with sent when successful or error otherwise.

Events

Triggers command event.

Example

{
  "type": "getData",
  "data": {
    "id": 1,
    "sensorIds": [2, 3]
  }
}

setData

Request the thing to update its data items with the values that are being sent. This operation can only be performed by device of type 'app'.

Data

Object in the following format:

  • id String Device ID.
  • data Array Data items to be sent, each one formed by:
    • sensorId Number Sensor ID.
    • value String|Boolean|Number Sensor value. Strings must be Base64 encoded.

Response

Replies with sent when successful or error otherwise.

Events

Triggers command event.

Example

{
  "type": "setData",
  "data": {
    "id": 1,
    "data": [
      { "sensorId": 2, "value": 7 },
      { "sensorId": 3, "value": true }
    ]
  }
}

Message types (Responses, Cloud-Device)

error

Possible response of multiple messages sent in case of error.

Data

Object in the following format:

  • code Number Error code (HTTP status is being used).
  • message String (Optional) Message describing the error.

Example

{
  "type": "error",
  "data": {
    "code": 403,
    "message": "Forbidden"
  }
}

ready

Response of identity when the authentication succeeds.

Example

{
  "type": "ready"
}

registered

Response of register when the registration succeeds.

Data

An Object containing the registered device.

Example

{
  "type": "registered",
  "data": {
    "id": "35da7919-c9d1-4d39-ab4c-c3f2956771d7"
    "token": "c2473601230d87662118916e9a8882f13f27f078"
    "type": "gateway",
    "metadata": {
      "name": "My gateway"
    },
    "knot": {
      "active": false
    }
  }
}

unregistered

Response of unregister when the unregistration succeeds.

Example

{
  "type": "unregistered"
}

devices

Response of devices when the query succeeds.

Data

An Array containing Objects representing devices.

Example

{
  "type": "devices",
  "data": [
    {
      "id": "35da7919-c9d1-4d39-ab4c-c3f2956771d7"
      "type": "gateway",
      "metadata": {
        "name": "My gateway"
      },
      "knot": {
        "active": false
      }
    }
  ]
}

created

Response of token when the creation succeeds.

Data

The new token as a String.

Example

{
  "type": "created",
  "data": "c2473601230d87662118916e9a8882f13f27f078"
}

revoked

Response of revoke when it succeeds.

Example

{
  "type": "revoked"
}

updated

Response of schema or 'metadata' when it succeeds.

Example

{
  "type": "updated"
}

activated

Response of activate when it succeeds.

Example

{
  "type": "activated"
}

published

Response of data when it succeeds.

Example

{
  "type": "published"
}

sent

Response of getData or setData when it succeeds.

Example

{
  "type": "sent"
}

Message types (Events, Cloud-Device)

registered

Similar to register's response, triggered when a new device is registered on the cloud.

Recipients

Device of type 'app'.

Data

An Object containing the registered device.

Example

{
  "type": "registered",
  "data": {
    "id": "35da7919-c9d1-4d39-ab4c-c3f2956771d7"
    "token": "c2473601230d87662118916e9a8882f13f27f078"
    "type": "gateway",
    "metadata": {
      "name": "My gateway"
    },
    "knot": {
      "active": false
    }
  }
}

registered

Similar to unregister's response, triggered when a new device is unregistered from the cloud.

Recipients

Device of type 'app'.

Data

An Object in following format:

  • id String Device ID.

Example

{
  "type": "unregistered",
  "data": {
    "id": "35da7919-c9d1-4d39-ab4c-c3f2956771d7"
  }
}

data

Similar to data command, triggered when a device published data to the cloud.

Recipients

Device of type 'app'.

Data

An Object in the following format:

  • id String Device ID.
  • sensorId Number Sensor id between 0 and the maximum number of sensors defined for that thing.
  • value String|Boolean|Number Sensor value. Strings must be Base64 encoded.

Example

{
  "type": "data",
  "data": {
    "id": "35da7919-c9d1-4d39-ab4c-c3f2956771d7",
    "sensorId": 1,
    "value": 10.57
  }
}

command

Triggered when a device of type 'app' sends a command. Currently supported commands are getData and setData.

Recipients

Device of type 'thing'.

Data

An object in the following format:

  • name String Command name.
  • args Any (Optional) Command-defined arguments.

Example

{
  "type": "command",
  "data": {
    "name": "getData",
    "args": {
      "id": 1,
      "sensorIds": [2, 3]
    }
  }
}
Clone this wiki locally