Protocol specification (v1.0.0)

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": "knot: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 'knot:gateway'.

Data

Object in the following format:

• type String Device type. One of: 'knot:thing', 'knot:gateway' or 'knot:app'.
• id String (Optional, mandatory when type is 'knot:thing') KNoT ID. Will be used as device ID.
• name String (Optional) Device name.
• active Boolean (Optional) Defines whether the 'knot: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": "knot: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 'knot: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. Depending on the type of the authenticated device, different devices will be returned:

• 'knot:user' can see all registered devices.
• 'knot:gateway' can see the 'knot:thing's associated to it.
• 'knot:app' can see all the 'knot:thing's associated to a 'knot:user'.
• 'knot:thing' won't see any device.

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": "knot: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 'knot: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. Value 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 'knot: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": "activate",
  "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 'knot:thing'.

Data

Object in the following format:

• sensorId Number Sensor ID. Value 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 'knot: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": "78159106-41ca-4022-95e8-2511695ce64c",
    "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 'knot: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": "78159106-41ca-4022-95e8-2511695ce64c",
    "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": "knot: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": "knot: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)

Data format

Events have a common format for the data field, as follows:

• from String ID of the device generating the event.
• payload Any (Optional) Event-defined payload.

registered

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

Recipients

Device of type 'knot:app'.

Sender

The from field contains the ID of the device that is registering the new device.

Payload

An Object containing the registered device.

Example

{
  "type": "registered",
  "data": {
    "from": "1b235edc-dfbe-46ea-ac01-98ad52b2f0e4",
    "payload": {
      "id": "35da7919-c9d1-4d39-ab4c-c3f2956771d7",
      "token": "c2473601230d87662118916e9a8882f13f27f078",
      "type": "knot:gateway",
      "metadata": {
        "name": "My gateway"
      },
      "knot": {
        "active": false
      }
    }
  }
}

unregistered

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

Recipients

Device of type 'knot:app'.

Sender

The from field contains the ID of the device that was unregistered.

Example

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

data

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

Recipients

Device of type 'knot:app'.

Sender

The from field contains the ID of the device that published data.

Payload

An Object in the following format:

• sensorId Number Sensor ID. Value 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": {
    "from": "35da7919-c9d1-4d39-ab4c-c3f2956771d7",
    "payload": {
      "sensorId": 1,
      "value": 10.57
    }
  }
}

command

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

Recipients

Device of type 'knot:thing'.

Sender

The from field contains the ID of the device that issued the command.

Payload

An object in the following format:

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

Example

{
  "type": "command",
  "data": {
    "from": "35da7919-c9d1-4d39-ab4c-c3f2956771d7",
    "payload": {
      "name": "setData",
      "args": [
        {
          "sensorId": 1,
          "value": 100
        }
      ]
    }
  }
}