README
1. Install
The client library for Node.js is distributed as an npm package and can be installed from here.
2. Public functions:
All library functionallity is accessed by means of its 4 public functions:
connect()
: used by the thing to connect with Vizibles. It can receive an only paramater, which is anoptions
object used to configure the client behaviour. The meaning of all properties ofoptions
and their valid values are the following:protocol
: valid protocols arews
(unsecure websocket),wss
(secure websocket) andhttp
.hostname
: it is the domain name part of the URL where the Vizibles server is located. By default it is set toapi.vizibles.com
.port
: the port used to connect to Vizibles. The valid ports are the default ones:80
for unsecure connections and443
for secure connections.path
: it is the path part of the URL where the Vizibles server is located. By default it is set to/thing
.credentials
: they must have the form of an API Key with 2 propertieskeyId
andsecret
. For a complete description of API Keys and to know how to obtain an API Key for your device, see the API reference for this point.server
: an HTTP server can run on the thing, so that it can receive orders and requests directly from the Vizibles server, from other things or from the user using a mobile app for example. It is configured using and object with 2 properties:enabled
: a boolean to enable/disable server.port
: the port used to listen for connections.
id
: the not scoped thingId. It is the configurable part of the unique identifier string of the thing. Vizibles will add a prefix (scope) to build the complete thingId. In order to get unique identifiers for your things, you can generate thisid
using some data like the MAC address, the serial number etc.onConnected
: a function callback to be called when the thing connect with Vizibles.onDisconnected
: a function callback to be called when the thing disconnects from Vizibles.ack
: when a thing is using websockets (eitherws
orwss
) all messages sent to Vizibles are confirmed with an ack message that the server sends back to the thing. The parametertimeout
defines the maximum time (in seconds) to wait for these ack messages. If ack is not received in that time the thing assumes that connection has failed and it will retry to connect with Vizibles after the time specified inmonitor
.monitor
: when a thing is trying to connect or send data to Vizibles and this connection fails, it will retry to connect with server after the time specified inretryAfter
(in seconds).platform
: for future use. The only valid value by now ispc
.
These are the defaults options values:
config.options = {
protocol: 'wss',
hostname: 'api.vizibles.com', // for development: 'localhost'
port: 443, // for development: 8443
path: '/thing',
credentials: null,
server: {enabled: true, port: 5000},
id: null,
onConnected: null,
onDisconnected: null,
ack: {timeout: 10},
monitor: {wifi: {sta: {retryAfter: 300}}},
platform: 'pc'
};
update()
: used to update the values of one or more attributes. It receives a JSON object as a parameter, with a pair key-value for each attribute that must be updated. The attribute is created in the server the first time that it is updated, so there is no need for a function to create it explicitly.expose()
: used to publish a function, so that it can be remotely called by users with suitable roles. Exposed functions can also be used to define controls and to form part of ITTT rules.unexpose()
: it removes a function from the list of published functions.
3. Example
The following is a full example that simulates a connected air-conditioner device with these characteristics:
- It exposes 3 functions:
setTargetTemperature
,upTargetTemperature
anddownTargetTemperature
. - It updates 3 attributes:
temperature
,humidity
andtarget
.
var Cloud = require('../../cloud.js');
var config = require('../config.js');
var cloudConnectionOpened = false;
var targetTemp = 21;
function randomInt (low, high) {
return Math.floor(Math.random() * (high - low + 1) + low);
}
function setTargetTemperature (n) {
var number = parseInt(n);
if (number > 0 && number < 50) {
targetTemp = number;
Cloud.update({ 'target': targetTemp });
return (number);
}
return ('Invalid temperature');
}
function upTargetTemperature (n) {
if (targetTemp < 34) {
targetTemp++;
Cloud.update({ 'target': targetTemp });
return targetTemp;
}
return 'Max temp: 34';
}
function downTargetTemperature (n) {
if (targetTemp > 12) {
targetTemp--;
Cloud.update({ 'target': targetTemp });
return targetTemp;
}
return 'Min temp: 12';
}
function onConnected() {
console.log('[air-conditioner-apikey] onConnected()');
if (!cloudConnectionOpened) {
cloudConnectionOpened = true;
Cloud.expose('setTarget', setTargetTemperature);
Cloud.expose('upTargetTemperature', upTargetTemperature);
Cloud.expose('downTargetTemperature', downTargetTemperature);
setInterval(function() {
var temp = targetTemp + randomInt(0, 2) -1;
var hum = randomInt(61, 64);
Cloud.update({ 'temperature': temp, 'humidity': hum , 'target': targetTemp });
}, 5000);
}
}
function onDisconnected(err) {
console.log('[air-conditioner-apikey] onDisconnected(' + err + ')');
cloudConnectionOpened = false;
}
Cloud.connect({
id:'air-conditioner',
credentials: config.defaults.apiKey,
onConnected: onConnected,
onDisconnected: onDisconnected});