@cesarbr/knot-cloud-websocket
v1.1.3
Published
KNoT Cloud WebSocket library for NodeJS and browser
Downloads
35
Keywords
Readme
KNoT Cloud WebSocket library for NodeJS and browser
A client side library that provides a WebSocket abstraction to the KNoT Cloud for Node.js and browser applications.
Quickstart
Install
npm install --save @cesarbr/knot-cloud-websocket
Run
KNoTCloudWebSocket
connects to <protocol>://<hostname>:<port>/<pathname> using ID and token as credentials. Replace this address with your protocol adapter instance and the credentials with valid ones.
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '78159106-41ca-4022-95e8-2511695ce64c',
token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574',
});
client.on('ready', () => {
client.register({
id: '6e5a681b2ae7be40',
type: 'knot:thing',
name: 'Door Lock',
});
});
client.on('registered', (thing) => {
console.log('Registered', thing);
client.close();
});
client.connect();
Methods
constructor(options)
Create a client object that will connect to a KNoT Cloud protocol adapter instance.
Arguments
options
Object JSON object with connection details.protocol
String (Optional) Either'ws'
or'wss'
. Default:'wss'
.hostname
String KNoT Cloud protocol adapter instance host name.port
Number (Optional) KNoT Cloud protocol adapter instance port. Default: 443.pathname
String (Optional) Path name on the server.id
String Device ID.token
String Device token.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '78159106-41ca-4022-95e8-2511695ce64c',
token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574',
});
connect(): <Void>
Connects to the protocol adapter instance. Receives the 'ready'
message when succeeds and 'error'
otherwise.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '78159106-41ca-4022-95e8-2511695ce64c',
token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574',
});
client.on('ready', () => {
console.log('Connection established');
});
client.on('error', (err) => {
console.error(err);
console.log('Connection refused');
});
client.connect();
close(): <Void>
Closes the current connection.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '78159106-41ca-4022-95e8-2511695ce64c',
token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574',
});
client.on('ready', () => {
console.log('Connection established');
client.close();
});
client.on('error', (err) => {
console.error(err);
console.log('Connection refused');
client.close();
});
client.connect();
register(properties): <Void>
Registers a new device. Receives the 'registered'
message when succeeds and 'error'
otherwise.
Users can create 'knot:gateway'
, 'knot:app'
and 'knot:thing'
. Gateways ('knot:gateway'
) can create 'knot:thing'
.
Arguments
properties
Object JSON object with device detailstype
String Device type. One of:'knot:gateway'
,'knot:app'
or'knot:thing'
.name
String (Optional) Human readable name for your device.id
String Device ID. Required whentype
is'knot:thing'
, for other types it is automatically generated.active
Boolean (Optional) Whether the gateway being created is active. Only used whentype
is'knot:gateway'
. Default:false
.
Result
device
Object JSON object containing device details after creation on cloud.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '78159106-41ca-4022-95e8-2511695ce64c',
token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574',
});
client.on('ready', () => {
client.register({
id: '6e5a681b2ae7be40',
type: 'knot:thing',
name: 'Door Lock',
});
});
client.on('registered', (thing) => {
console.log(thing);
client.close();
});
client.on('error', (err) => {
console.error(err);
console.log('Connection refused');
client.close();
});
client.connect();
// { type: 'knot:thing',
// metadata: { name: 'Door Lock' },
// knot:
// { gateways: [ '78159106-41ca-4022-95e8-2511695ce64c' ],
// id: '6e5a681b2ae7be40' },
// token: '40ad864d503488eda9b629825876d46cb1356bdf' }
unregister(id): <Void>
Removes a device from the cloud. Receives the 'unregistered'
message when succeeds and 'error'
otherwise.
Arguments
id
String Device ID.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '78159106-41ca-4022-95e8-2511695ce64c',
token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574',
});
client.on('ready', () => {
client.unregister('6e5a681b2ae7be40');
});
client.on('unregistered', () => {
client.close();
});
client.on('error', (err) => {
console.error(err);
console.log('Connection refused');
client.close();
});
client.connect();
getDevices(query): <Void>
Lists the devices registered on cloud. If a query
is specified, only the devices that match such query will be returned. Receives the 'devices'
message when succeeds and 'error'
otherwise.
Arguments
query
Object (Optional) Search query, written using MongoDB query format.
Result
devices
Array Set of devices that match the constraint specified onquery
.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '78159106-41ca-4022-95e8-2511695ce64c',
token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574',
});
client.on('ready', () => {
client.getDevices({
type: 'knot:thing',
});
});
client.on('devices', (devices) => {
console.log(devices);
client.close();
});
client.on('error', (err) => {
console.error(err);
console.log('Connection refused');
client.close();
});
client.connect();
// [ { type: 'knot:thing',
// metadata: { name: 'Door Lock' },
// knot:
// { gateways: [ '78159106-41ca-4022-95e8-2511695ce64c' ],
// id: '6e5a681b2ae7be40' } } ]
createSessionToken(id): <Void>
Creates a session token for a device. Receives the 'created'
message when succeeds and 'error'
otherwise.
Arguments
id
String Device ID.
Result
token
String New token for the specified device.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '78159106-41ca-4022-95e8-2511695ce64c',
token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574',
});
client.on('ready', () => {
client.createSessionToken('6e5a681b2ae7be40');
});
client.on('created', (token) => {
console.log(token);
client.close();
});
client.on('error', (err) => {
console.error(err);
console.log('Connection refused');
client.close();
});
client.connect();
// 'a0ab6f486633ddc87dceecc98e88d7ffee60a402'
revokeSessionToken(id, token): <Void>
Revokes a device session token. Receives the 'revoked'
message when succeeds and 'error'
otherwise.
Arguments
id
String Device ID.token
String Existing session token for the specified device.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '78159106-41ca-4022-95e8-2511695ce64c',
token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574',
});
client.on('ready', () => {
client.revokeSessionToken('6e5a681b2ae7be40', 'a0ab6f486633ddc87dceecc98e88d7ffee60a402');
});
client.on('revoked', () => {
client.close();
});
client.on('error', (err) => {
console.error(err);
console.log('Connection refused');
client.close();
});
client.connect();
updateSchema(schema): <Void>
Updates the thing schema. Receives the 'updated'
message when succeeds and 'error'
otherwise.
Arguments
schema
Array An array of objects in the following format: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.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '6e5a681b2ae7be40',
token: 'a0ab6f486633ddc87dceecc98e88d7ffee60a402',
});
client.on('ready', () => {
client.updateSchema([
{
sensorId: 253,
typeId: 0xFFF1,
valueType: 3,
unit: 0,
name: 'Lock'
}
]);
});
client.on('updated', () => {
client.close();
});
client.on('error', (err) => {
console.error(err);
console.log('Connection refused');
client.close();
});
client.connect();
activate(id): <Void>
Activates a gateway. Receives the 'activated'
message when succeeds and 'error'
otherwise.
Arguments
id
String Device ID.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '78159106-41ca-4022-95e8-2511695ce64c',
token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574',
});
client.on('ready', () => {
client.activate('871a6907-45c0-4557-b783-6224f3de92e7');
});
client.on('activated', () => {
client.close();
});
client.on('error', (err) => {
console.error(err);
console.log('Connection refused');
client.close();
});
client.connect();
updateMetadata(id, metadata): <Void>
Updates the device metadata. Receives the 'updated'
message when succeeds and 'error'
otherwise.
Arguments
id
String Device ID.metadata
Any Device metadata.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '78159106-41ca-4022-95e8-2511695ce64c',
token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574',
});
client.on('ready', () => {
client.updateMetadata('6e5a681b2ae7be40', {
room: {
name: 'Lula Cardoso Ayres',
location: 'Tiradentes'
}
});
});
client.on('updated', () => {
client.close();
});
client.on('error', (err) => {
console.error(err);
console.log('Connection refused');
client.close();
});
client.connect();
publishData(sensorId, value): <Void>
Publishes data. Receives the 'published'
message when succeeds and 'error'
otherwise.
Arguments
sensorId
Number Sensor ID.value
Number Sensor value.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '6e5a681b2ae7be40',
token: 'a0ab6f486633ddc87dceecc98e88d7ffee60a402',
});
client.on('ready', () => {
client.publishData(253, true);
});
client.on('published', () => {
client.close();
});
client.on('error', (err) => {
console.error(err);
console.log('Connection refused');
client.close();
});
client.connect();
getData(id, sensorIds): <Void>
Requests a thing to send its current data items values. Receives the 'sent'
message when succeeds and 'error'
otherwise.
Arguments
id
String Device ID.sensorIds
Array Array of sensor IDs.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '78159106-41ca-4022-95e8-2511695ce64c',
token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574',
});
client.on('ready', () => {
client.getData('6e5a681b2ae7be40', [253]);
});
client.on('data', (data) => {
console.log(JSON.stringify(data, null, 2));
});
client.on('error', (err) => {
console.error(err);
console.log('Connection refused');
client.close();
});
client.connect();
setData(id, data): <Void>
Requests a thing to update its data items with the values passed as arguments. Receives the 'sent'
message when succeeds and 'error'
otherwise.
Arguments
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.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '78159106-41ca-4022-95e8-2511695ce64c',
token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574',
});
client.on('ready', () => {
client.setData('6e5a681b2ae7be40', [{ sensorId: 253, value: false }]);
});
client.on('sent', () => {
client.close();
});
client.on('error', (err) => {
console.error(err);
console.log('Connection refused');
client.close();
});
client.connect();
on(name, handler): <Void>
Registers an event handler. See next section for details on events.
Arguments
name
String Event namehandler
Function Event handler.
Example
const KNoTCloudWebSocket = require('@cesarbr/knot-cloud-websocket');
const client = new KNoTCloudWebSocket({
protocol: 'wss',
hostname: 'ws.knot.cloud',
port: 443,
pathname: '/',
id: '78159106-41ca-4022-95e8-2511695ce64c',
token: 'd5265dbc4576a88f8654a8fc2c4d46a6d7b85574',
});
client.on('registered', (message) => {
console.log('Who?', message.from);
console.log('What?', message.payload);
client.close();
});
client.on('error', (err) => {
console.error(err);
console.log('Connection refused');
client.close();
});
client.connect();
Events
Events can be listened to by registering a handler with on()
. The handler will receive an object in the following format:
from
String ID of the device generating the event.payload
Any (Optional) Event-defined payload.
Event: "registered"
Triggered when a device is registered on the cloud. Only apps ('knot:app'
) and users receive this event.
Payload
An object containing the registered device.
Example
{
from: '78159106-41ca-4022-95e8-2511695ce64c',
payload: {
type: 'knot:thing',
metadata: { name: 'Door Lock' },
knot: {
gateways: [ '78159106-41ca-4022-95e8-2511695ce64c' ],
id: '6e5a681b2ae7be40',
},
},
}
Event: "unregistered"
Triggered when a device is unregistered from the cloud. Only apps ('knot:app'
) and users receive this event.
Payload
No payload. The ID of the unregistered device will come in the from
field.
Example
{
from: '6e5a681b2ae7be40'
}
Event: "data"
Triggered when a device publishes data items. Only apps 'knot:app'
and users receive this event.
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
{
from: '6e5a681b2ae7be40',
payload: {
sensorId: 253,
value: true,
},
}
Event: "command"
Triggered when a device of type 'knot:app'
sends a command. Currently supported commands are getData
and setData
. Only things ('knot:thing'
) receive this event.
Payload
An object in the following format:
name
String Command name.args
Any (Optional) Command-defined arguments.
Example
{
from: '78159106-41ca-4022-95e8-2511695ce64c',
payload: {
name: 'getData',
args: [253],
},
}