Home

1. Overview

This module is a transportation with WebSocket protocol, which is used by the RPC interface of freebird framework. It provides methods to create RPC client and RPC server for real-time remote communications. The RPC server should be registered to freebird framework to be able to transmit freebird messages to RPC client (e.g., the web browser). And the RPC client is provided for webapp to be able to communicate with freebird.

Subsystems

The freebird framework has net, dev, and gad subsystems responsible for network, device, and gadget management, respectively. In brief, a network is formed with many devices, and each device may have some gadgets on it. A gadget is the real application in a manchine network.

Example

Let's take a wifi weather station in a machine network for example. The weather station is made up of temperature, humidity, and pm2.5 sensors, where each sensor is a gadget living on the WiFi-connected device. A device, such as Arduino(wifi-connected), ESP8266, MT7688, RaspberryPi or Beaglebone, is the carrier of applications(gadgets). Now we know, this weather station has 3 gadgets on it, but only has a single device in it.

Here is another example, we have a bluetooth low-energy (BLE) light switch in the network. This is a simple one-device-with-one-gadget machine, here we can say "There is only one gadget - a light switch - implemented on a TI CC2540 BLE SoC device."

Why subsystems?

The concept of net, dev, and gad subsystems in freebird framework well separates the machine management and application management from each other. This brings developers a more clear, convenient and flexible way in building up a IoT machine network.

2. Installation

$ npm install freebird-rpc --save

3. Usage

freebird-rpc exports its functionalities as an object that has two methods createServer() and createClient() on it.

Create a RPC server (to be used at freebird side as a transportation)

var fbRpc = require('freebird-rpc'),
    http = require('http');

var httpServer = http.createServer();
httpServer.listen(3000);

var rpcServer = fbRpc.createServer(httpServer);

Create a RPC client (e.g., webapps or mobile apps)

var fbRpc = require('freebird-rpc');

var rpcClient = fbRpc.createClient('ws://192.168.1.108:3000');

4. APIs and Events

.createServer(httpServer)

Create the websocket RPC server on top of a http server.

Arguments:

httpServer (Object): A Node.js HTTP server.

Returns:

(Object): rpcServer

Example:

var http = require('http'),
    fbRpc = require('freebird-rpc'),
    httpServer,
    rpcServer;

httpServer = http.createServer().listen(3000);
rpcServer = fbRpc.createServer(httpServer);

.createClient(addr[, options])

Create the websocket RPC client.

Arguments:

addr (String): host address and port.
options (Object): An optional object to set up the websocket client. Please refer to websocket official ws.md for more details about this options.

Returns:

(Object): rpcClient

Example:

var rpcClient = fbRpc.createClient('ws://192.168.1.108:3000');

Server Class

fbRpc.createServer() returns an instance of the Server class. The instance, which is denoted as rpcServer in this document, is essentially a WebSocket server for real-time bidirectional communications with WebSocket clients.

.send(msg, callback)

Send response message to the client with results of the client asking for.

Arguments:

msg (Object): msg must at least have clientId and data fields, where clientId is used to identify the client you want to send the message to, and data is the message to transmit out. data must be an object shaped with Response Message format, and it must be serialized to a JSON string when transmitting.
callback (Function): function (err, bytes) { ... }. Get called after message send off. The argument bytes tells how many bytes were sent.

Returns:

(None)

Example:

var sendData = {
    __intf: 'RSP',
    subsys: 'net',
    seq: 5,
    id: null,
    cmd: 'getAllDevIds',
    status: 205,
    data: {
        ids: [ 1, 2, 3, 8, 12 ]
    }
};

sendData = JSON.stringify(sendData);

rpcServer.send({ clientId: 'client01', data: sendData }, function (err, bytes) {
    if (err)
        console.log(err);
    else
        console.log(bytes + ' bytes were sent');
});

.broadcast(msg, callback)

Broadcast the indication message to all clients.

Arguments:

msg (Object): msg must has the data field. data is the message to transmit out which must be shaped with Indication Message format, and it must be serialized to a JSON string when transmitting.
callback (Function): function (err, bytes) { ... }. Get called after message send off. The argument bytes tells how many bytes were sent.

Returns:

(None)

Example:

var broadcastData = {
    __intf: 'IND',
    subsys: 'net',
    type: 'started',
    id: null,
    data: { netcore: 'freebird-netcore-ble' }
};

broadcastData = JSON.stringify(broadcastData);

rpcServer.broadcast({ data: broadcastData }, function (err, bytes) {
    if (err)
        console.log(err);
    else
        console.log(bytes + ' bytes were sent');
});

.on('message', function (msg) {})

The 'message' event is triggered when the server receives a request from the client.

Arguments of the listener

msg (Object): msg contains clientId and data properties. clientId is to help the freebird determine which client sends the message, and data is the received message which is the serialized JSON string of Request Data Object.

Example:

rpcServer.on('message', function (msg) {
    console.log(msg.data);  // a JSON string

    msg.data = JSON.parse(msg.data);    // parse to an object
});

Client Class

fbRpc.createClient() returns an instance of the Client class. The instance, which is denoted as rpcClient in this document, is essentially a WebSocket client for real-time bidirectional communications with WebSocket servers.

.send(subsys, cmd, args, callback)

Send the request message to the server for requesting something or asking the server to perform an operation.

Arguments:

subSys (String): Only 3 types are accepted. They are 'net', 'dev', and 'gad' to denote which subsystem is this message referring to.
cmd (String): Command identifier, which is simply the API name that can be found in the _Command Name_ column of the Request Data Model, i.e. 'getAllDevIds', 'getDevs', 'permitJoin'.
args (Object): A value-object as the argument for a command. The corresponding argument for each command is listed in the **Arguments** column of Request Data Model.
callback (Function): function (err, result) {}. Get called when the server respond to this client.
- 'err' (Error): Error object.
- 'result' (Object): result is an object of { status, data }, where status is a code defined by RSP Status Code and data is a response object shaped with the Response Data Model format.

Returns:

(None)

Example:

rpcClient.send('net', 'getAllDevIds', { ncName: 'freebird-netcore-ble' }, function (err, result) {
    if (err) {
        console.log(err);
    } else {
        console.log(result);

        // result is 
        // {
        //     status: 205,
        //     data: {
        //         ids: [ 1, 5, 8, 15, 27 ]
        //     }
        // }
    }    
});

.on('open', function () {})

Fires when the connection is open and ready for communication.

Arguments of the listener

(None)

Example:

rpcClient.on('open', function () {
    // You can now communicate with the RPC server
});

.on('close', function (code, reason) {})

Fires when the connection is closed.

Arguments of the listener

code (Number): code is a numeric value to indicate the status code explaining why the connection has been closed.
reason (String): reason is a human-readable string explaining why the connection has been closed.

Example:

rpcClient.on('close', function (code, reason) {
    console.log('Connection is closed because the reason: ' + reason);
});

.on('ind', function (msg) {})

Fires when an indication received from the server.

Arguments of the listener

msg (Object): A message object with fields 'subsys', 'type', 'id' and 'data'
- subsys (String): Can be 'net', 'dev', or 'gad' to denote which subsystem is this indication coming from.
- type (String): Indication types. Please see section Indication types for details.
- id (Number): Id of the sender.
  - id is meaningless if subsys === 'net'.
  - id refers to device id if subsys === 'dev'.
  - id refers to gadget id if subsys === 'gad'
- data (Object): Data along with the indication. Please see section Indication Data Model to learn more about the indication data format.

Example:

rpcClient.on('ind', function (msg) {
    console.log(msg);
});

Messaging Interfaces

In freebird, the web-Client and Server are communicating with each other through websocket along with a JSON message. The __intf field in the message can be 'REQ', 'RSP' or 'IND' to denote the interface.

Request Message

Direction: Client sends to Server to request something or to ask the server to perform an operation.
Interface: __intf = 'REQ'

Message keys: { __intf, subsys, seq, id, cmd, args }

Property	Type	Description
__intf	String	'REQ'
subsys	String	Only 3 types accepted. They are 'net', 'dev', and 'gad' to denote which subsystem is this message going to
seq	Number	Sequence number of this REQ/RSP transaction
id	Number	Id of the sender. id is meaningless if `subsys === 'net'`. id is device id if `subsys === 'dev'`. id is gadget id if `subsys === 'gad'`. It is noticed that id = 0 is reserved for the freebird web-Client and Server
cmd	String	Command Identifier corresponding to the API name
args	Object	A value-object that contains command arguments. Please see section Request Data Model to learn more about the `args` data object

Message Example:

{ 
    __intf: 'REQ',
    subsys: 'net',
    seq: 3,
    id: 0,
    cmd: 'getDevs',
    args: {
        ids: [ 2, 4, 18, 61 ]
    }
}

Response Message

Direction: Server responds to Client with the results of the client asking for.
Interface: __intf = 'RSP'

Message keys: { __intf, subsys, seq, id, cmd, status, data }

Property	Type	Description
__intf	String	'RSP'
subsys	String	Only 3 types accepted. They are 'net', 'dev', and 'gad' to denote which subsystem is this message coming from
seq	Number	Sequence number of this REQ/RSP transaction
id	Number	Id of the sender. id is meaningless if `subsys === 'net'`. id is device id if `subsys === 'dev'`. id is gadget id if `subsys === 'gad'`. It is noticed that id = 0 is reserved for the freebird web-Client and Server
cmd	String	Command Identifier corresponding to the API name
status	Number	Status code of the response
data	Depends	Data along with the response. To learn more about the data format corresponding to each command, please see section Response Data Model.

Message Example:

{ 
    __intf: 'RSP',
    subsys: 'net',
    seq: 17,
    id: 0,
    cmd: 'getAllDevIds',
    status: 0,
    data: {
        ids: [ 2, 4, 18, 61 ]
    }
}

Indication Message

Direction: Server indicates Client
Interface: __intf = 'IND'

Message keys: { __intf, subsys, type, id, data }

Property	Type	Description
__intf	String	'IND'
subsys	String	Only 3 types accepted. They are 'net', 'dev', and 'gad' to denote which subsystem is this indication coming from
type	String	There are few types of indication accepted, such as 'attrsChanged'. Please see section Indication types for details
id	Number	Id of the sender. id is meaningless if `subsys === 'net'`. id is device id if `subsys === 'dev'`. id is gadget id if `subsys === 'gad'`
data	Depends	Data along with the indication. Please see section Indication Data Model to learn more about the indication data format

Indication types:

subsys	Indication Type	Description
net	'error'	Netcore error occurs
net	'started'	A netcore is started
net	'stopped'	A netcore is stopped
net	'enabled'	A netcore is enabled
net	'disabled'	A netcore is disabled
net	'permitJoining'	A netcore is now allowing devices to join the network
net	'bannedDevIncoming'	A banned device is trying to join the network
net	'bannedGadIncoming'	A banned gadget is trying to join the network
net	'bannedDevReporting'	A banned device is trying to report its attributes
net	'bannedGadReporting'	A banned gadget is trying to report its attributes
dev	'error'	Device error occurs
dev	'devIncoming'	A new device is incoming
dev	'devLeaving'	A device is leaving
dev	'netChanged'	Network information of a device has changed
dev	'statusChanged'	Status of a device has changed. The status can be 'online', 'sleep', 'offline', and 'unknown'
dev	'propsChanged'	Meta-property(ies) of a device has changed
dev	'attrsChanged'	Attribue(s) on a device has changed
gad	'error'	Gadget error occurs
gad	'gadIncoming'	A new gadget is incoming
gad	'gadLeaving'	A gadget is leaving
gad	'panelChanged'	Panel information of a gadget has changed
gad	'propsChanged'	Meta-property(ies) of a gadget has changed
gad	'attrsChanged'	Attribue(s) on a gadget has changed
gad	'attrsReport'	A report message of certain attribute(s) on a gadget

Message Example:

{ 
    __intf: 'IND',
    subsys: 'gad',
    type: 'attrsChanged',
    id: 147,            // sender of this indication is a gadget with id = 147
    data: {
        sensorValue: 24
    }
}

Message Data Model

The message data model presents the args and data formats in the REQ/RSP/IND messages.

Request Data Model

The request message is an object with keys { __intf, subsys, seq, id, cmd, args }. The following table gives the details of each API.

Subsystem	Command Name	Arguments (args)	Description
net	'getAllDevIds'	{ [ncName] }	Get identifiers of all devices on freebird Server. ncName is a string and is optional. If ncName is given, only identifiers of devices managed by that netcore will be returned from Server.
net	'getAllGadIds'	{ [ncName] }	Get identifiers of all gadgets on freebird Server. ncName is a string and is optional. If ncName is given, only identifiers of gadgets managed by that netcore will be returned from Server.
net	'getDevs'	{ ids }	Get information of devices by their ids. ids is an array of numbers and each number is a device id, i.e., given `{ ids: [ 5, 6, 77 ] }`.
net	'getGads'	{ ids }	Get gadget information by gadget id. ids is an array of numbers and each number is a gadget id, i.e., given `{ ids: [ 23, 14, 132 ] }`.
net	'getNetcores'	{ [ncNames] }	Get netcore information by netcore names. ncNames is an array of strings and each string is a netcore name, i.e., given `{ ncNames: [ 'ble-core', 'zigbee-core' ] }`. Given with an empty object `{}` to get all netcore infos at once.
net	'getBlacklist'	{ ncName }	Get blacklist of the banned devices. ncName is the netcore name of which you like to get the blacklist from. ncName should be a string. i.e., given `{ ncName: 'ble-core' }`
net	'permitJoin'	{ [ncName,] duration }	Allow or disallow devices to join the network. ncName is the name of which netcore you like to allow for device joining and ncName should be a string if given. All netcores will allow for device joining if ncName is not given. duration is the time in seconds which should be a number. Set duration to 0 will immediately close the admission. For example, given `{ ncName: 'zigbee-core', duration: 60 }` will allow zigbee devices to join the zigbee network for 60 seconds.
net	'maintain'	{ [ncName] }	Maintain the network. ncName is the name of which netcore you like to maintain. ncName should be a string if given. All netcores will enter maintaining mode if ncName is not given. When a netcore starts to maintain its own network, all devices managed by it will be refreshed. For example, given `{ ncName: 'ble-core' }` to let the BLE netcore do its maintenance.
net	'reset'	{ [ncName,] mode }	Reset the network. ncName is the name of which netcore you like to reset. ncName should be a string if given. It will reset all netcores if ncName is not given. Reset a network will remove all devices managed by that netcore. Given mode with 1 for a HARD reset while with 0 for a SOFT reset. Once reset, the banned devices in the netcore blacklist will also be removed.
net	'enable'	{ [ncName] }	Enable the network. ncName is the name of which netcore you like to enable. It will enable all netcores if ncName is not given. (All netcores are enabled by default.)
net	'disable'	{ [ncName] }	Disable the network. ncName is the name of which netcore you like to disable.It will disable all netcores if ncName is not given. If netcore is disabled, no messages can be send out and received from remote devices. That is, messages will be ignored and you will not get any message from the netcore on freebird Server.
net	'ban'	{ ncName, permAddr }	Ban a device from the network. Once a device has been banned, freebird will always reject its joining request. If a device is already in the network, freebird will first remove it from the network. ncName is the netcore that manages the device you'd like to ban. permAddr is the permanent address of the banned device. For example, given `{ ncName: 'zigbee-core', permAddr: '0x00124b0001ce4b89' }` to ban a zigbee device with an IEEE address of 0x00124b0001ce4b89. The permanent address depends on protocol, such as IEEE address for zigbee devices, BD address for BLE devices, and MAC address for IP-based devices.
net	'unban'	{ ncName, permAddr }	Unban a device. ncName is the netcore that manages the banned device. permAddr is the permanent address of the banned device. For example, given `{ ncName: 'zigbee-core', permAddr: '0x00124b0001ce4b89' }` to unban a zigbee device with an IEEE address of 0x00124b0001ce4b89.
net	'remove'	{ ncName, permAddr }	Remove a device from the network. ncName is the netcore that manages the device. permAddr is the permanent address of the device to be removed.
net	'ping'	{ ncName, permAddr }	Ping a device in the network. ncName is the netcore that manages the device. permAddr is the permanent address of the device you like to ping.
dev	'enable'	{ id }	Enable the device to activate its function and messages transportation.
dev	'disable'	{ id }	Disable the device.
dev	'read'	{ id, attrName }	Read an attribute on a device. id is the id of which device you like to read from. attrName is the attribute you like to read. For example, given `{ id: 20, attrName: 'location' }` to read the location attribute from the device with id = 20.
dev	'write'	{ id, attrName, value }	Write a value to an attribute on a device. id is the id of which device you like to write a value to. attrName is the attribute to be written. For example, given `{ id: 20, attrName: 'location', value: 'kitchen' }` to set the device location attribute to 'kitchen'.
dev	'identify'	{ id }	Identify a device in the network. id is the id of which device to be identified.
dev	'remove'	{ id }	Remove a device from the network. id is the id of which device to remove.
dev	'ping'	{ id }	Ping a device in the network. id is the id of which device you like to ping.
dev	'getProps'	{ id[, propNames] }	Get device meta-properties. propNames is an array of strings and each string is a meta-property name, i.e., given `{ id: 3, propNames: [ 'location', 'description' ] }`. All props will be returned if propNames is not given.
dev	'setProps'	{ id, props }	Set device meta-properties. props is an object contains meta-properties to set, i.e., given `{ id: 60, props: { location: 'bedroom', description: 'for my baby' } }`.
gad	'enable'	{ id }	Enable the gadget to activate its function and messages transportation.
gad	'disable'	{ id }	Disable the gadget.
gad	'read'	{ id, attrName }	Read an attribute on a gadget. id is the id of which gadget you like to read from. attrName is the attribute you like to read. For example, given `{ id: 2316, attrName: 'sensorValue' }` to read the sensed value attribute from a temperature sensor (the sensor is a gadget with id = 2316).
gad	'write'	{ id, attrName, value }	Write a value to an attribute on a gadget. id is the id of which gadget you like to write a value to. attrName is the attribute to be written. For example, given `{ id: 1314, attrName: 'onOff', value: 1 }` to turn on a light bulb (the light bulb is a gadget with id = 1314).
gad	'exec'	{ id, attrName[, params] }	Invoke a remote procedure on a gadget. id is the id of which gadget you like to perform its particular procedure. attrName is the attribute name of an executable procedure. params is an array of parameters given in order to meet the procedure signature. The signature depends on how a developer declare his(/her) own procedure. For example, given `{ id: 9, attrName: 'blink', params: [ 10, 500 ] }` to blink a LED on a gadget 10 times with 500ms interval.
gad	'writeReportCfg'	{ id, attrName, rptCfg }	Set the condition for an attribute reporting from a gadget.
gad	'readReportCfg'	{ id, attrName }	Get the report settings of an attribute on a gadget.
gad	'getProps'	{ id[, propNames] }	Get gadget meta-properties. propNames is an array of strings and each string is a meta-property name, i.e., given `{ id: 8, propNames: [ 'description' ] }`. All props will be returned if propNames is not given.
gad	'setProps'	{ id, props }	Set gadget meta-properties. props is an object contains meta-properties to set, i.e., given `{ id: 12, props: { description: 'temperature sensor 3', installed: true } }`.

Response Data Model

The response message is an object with keys { __intf, subsys, seq, id, cmd, status, data }, where status shows if the request is successful, the data field contains the respond data according to the request, and data will always be an object which will be empty if the request is unsuccessful.

Subsystem	Command Name	Data Key:Type	Data Description	Example
net	'getAllDevIds'	ids:Number[]	Array of device identifiers	{ ids: [ 1, 2, 3, 8, 12 ] }
net	'getAllGadIds'	ids:Number[]	Array of gadget identifiers	{ ids: [ 2, 3, 5, 11, 12, 13, 14, 15 ] }
net	'getDevs'	devs:devInfo[]	Array of device information objects	{ devs: [ devInfo, ... ] }
net	'getGads'	gads:gadInfo[]	Array of gadget information objects	{ gads: [ gadInfo , ... ] }
net	'getNetcores'	netcores:ncInfo[]	Array of netcore information objects	{ netcores: [ ncInfo, ... ] }
net	'getBlacklist'	list:String[]	Array of banned device permanent address	{ list: [ '0x00124b0001ce4b89', ... ] }
net	'permitJoin'	-	Response contains no data	{}
net	'maintain'	-	Response contains no data	{}
net	'reset'	-	Response contains no data	{}
net	'enable'	-	Response contains no data	{}
net	'disable'	-	Response contains no data	{}
net	'ban'	permAddr:String	Device permanent address	{ permAddr: '0x00124b0001ce4b89' }
net	'unban'	permAddr:String	Device permanent address	{ permAddr: '0x00124b0001ce4b89' }
net	'remove'	permAddr:String	Device permanent address	{ permAddr: '0x00124b0001ce4b89' }
net	'ping'	time:Number	Round-trip time in ms	{ time: 12 }
dev	'enable'	enabled:Boolean	To show if the device is enabled	{ enabled: true }
dev	'disable'	enabled:Boolean	To show if the device is enabled	{ enabled: false }
dev	'read'	value:Depends	The read value. Can be anything	{ value: 3 }
dev	'write'	value:Depends	The written value. Can be anything	{ value: 'kitchen' }
dev	'identify'	-	Response contains no data	{}
dev	'remove'	permAddr:String	Device permanent address	{ permAddr: '0x00124b0001ce4b89' }
dev	'ping'	time:Number	Round-trip time in ms	{ time: 12 }
dev	'getProps'	props:Depends	Meta-properties got. The props got is an object.	{ props: { name: 'mywifi-dev', location: 'kitchen' } }
dev	'setProps'	-	Response contains no data	{}
gad	'enable'	enabled:Boolean	To show if the gadget is enabled	{ enabled: true }
gad	'disable'	enabled:Boolean	To show if the gadget is enabled	{ enabled: false }
gad	'read'	value:Depends	The read value. Can be anything	{ value: 371.42 }
gad	'write'	value:Depends	The written value. Can be anything	{ value: false }
gad	'exec'	result:Depends	The data returned by the procedure. Can be anything	{ result: 'completed' }
gad	'writeReportCfg'	result: Boolean	To show if the reporting configuration is written	{ result: true }
gad	'readReportCfg'	cfg:Object	Report settings object	{ cfg: rptCfg }
gad	'getProps'	props:Depends	Meta-properties got. The props got is an object.	{ props: { name: 'mysensor1' } }
gad	'setProps'	-	Response contains no data	{}

Indication Data Model

The indication message is an object with keys { __intf, subsys, type, id, data }, where type shows the type of indication, and the data field contains indication data which is an object.

subsys	Indication Type	Data Object Key:Type	Description
net	'error'	`{ netcore:String, message: String }`	Netcore error occurs
net	'started'	`{ netcore:String }`	A netcore is started
net	'stopped'	`{ netcore:String }`	A netcore is stopped
net	'enabled'	`{ netcore:String }`	A netcore is enabled
net	'disabled'	`{ netcore:String }`	A netcore is disabled
net	'permitJoining'	`{ netcore:String, timeLeft:Number }`	A netcore is now allowing or disallowing devices to join the network
net	'bannedDevIncoming'	`{ netcore:String, permAddr:String }`	A banned device is trying to join the network
net	'bannedGadIncoming'	`{ netcore:String, permAddr:String, auxId:String	Number }`
net	'bannedDevReporting'	`{ netcore:String, permAddr:String }`	A banned device is trying to report its attributes
net	'bannedGadReporting'	`{ netcore:String, permAddr:String, auxId:String	Number }`
dev	'error'	`{ netcore:String, message: String }`	Device error occurs
dev	'devIncoming'	devInfo	A new device is incoming
dev	'devLeaving'	`{ netcore:String, permAddr:String }`	A device is leaving
dev	'netChanged'	netInfo	Network information of a device has changed
dev	'statusChanged'	`{ status:String }`	Status of a device has changed. The status can be 'online', 'sleep', 'offline', and 'unknown'
dev	'propsChanged'	devInfo.props	Meta-property(ies) of a device has changed
dev	'attrsChanged'	devInfo.attrs	Attribue(s) on a device has changed
gad	'error'	`{ netcore:String, message: String }`	Gadget error occurs
gad	'gadIncoming'	gadInfo	A new gadget is incoming
gad	'gadLeaving'	`{ netcore:String, permAddr:String, auxId:String	Number }`
gad	'panelChanged'	gadInfo.pannel	Panel information of a gadget has changed
gad	'propsChanged'	gadInfo.props	Meta-property(ies) of a gadget has changed
gad	'attrsChanged'	gadInfo.attrs	Attribue(s) on a gadget has changed
gad	'attrsReport'	gadInfo.attrs	A report message of certain attribute(s) on a gadget

Indication Example: indMsg of 'permitJoining'

{
    __intf: 'IND',
    subsys: 'net',
    type: 'permitJoining',
    id: 0,
    data: {
        netcore: 'zigbee-core',
        timeLeft: 60            // netcore does not allow for devices to join the network if timeLeft is 0
    }
}

Indication Example: indMsg of 'devIncoming'

{
    __intf: 'IND',
    subsys: 'dev',
    type: 'devIncoming',
    id: 18,                 // device id is 18
    data: {                 // data is devInfo object
        netcore: 'mqtt-core',
        id: 18,
        gads: [ 116, 117, 120 ],
        net: {
            enabled: true,
            joinTime: 1458008311,
            timestamp: 1458008617,
            role: 'client',         // depends on protocol
            parent: '0',            // parent is the netcore
            status: 'online'
            address: {
                permanent: '00:0c:29:ff:ed:7c',
                dynamic: '192.168.1.24'
            },
            traffic: {              // accumulated data since device joined
                in: {
                    hits: 2,
                    bytes: 24
                },
                out: {
                    hits: 4,
                    bytes: 32
                }
            }
        },
        props: {    // props: name, description, and location are writable and can be modified by users
            name: 'sample_device',
            description: 'This is a device example',
            location: 'bedroom'
        },
        attrs: {
            manufacturer: 'freebird',
            model: 'lwmqn-7688-duo',
            serial: 'lwmqn-2016-04-29-03',
            version: {
                hw: 'v1.2.0',
                sw: 'v0.8.4',
                fw: 'v2.0.0'
            },
            power: {
                type: 'line',
                voltage: '5V'
            }
        }
    }
}

Indication Example: indMsg of 'devLeaving'

{
    __intf: 'IND',
    subsys: 'dev',
    type: 'devLeaving',
    id: 27,                   // device id is 27
    data: { 
        netcore: 'zigbee-core', 
        permAddr: '0x00124b0001ce4b89' 
    }
}

Indication Example: indMsg of device 'netChanged'

{
    __intf: 'IND',
    subsys: 'dev',
    type: 'netChanged',
    id: 18,                 // device id is 18
    data: {                 // partial changes of netInfo object
        address: {
            dynamic: '192.168.1.32'
        },
        status: 'online'    // status changed, an 'statusChanged' indication will also be fired  
    }
}

Indication Example: indMsg of device 'statusChanged'

{
    __intf: 'IND',
    subsys: 'dev',
    type: 'statusChanged',
    id: 18,                 // device id is 18
    data: {
        status: 'online'
    }
}

Indication Example: indMsg of device 'propsChanged'

{
    __intf: 'IND',
    subsys: 'dev',
    type: 'propsChanged',
    id: 37,                   // device id is 37
    data: {
        location: 'kitchen'
    }
}

Indication Example: indMsg of device 'attrsChanged'

{
    __intf: 'IND',
    subsys: 'dev',
    type: 'attrsChanged',
    id: 16,                   // device id is 16
    data: {
        version: {
            sw: 'v1.2.3'
        },
        serial: '2016-05-01-001'
    }
}

Indication Example: indMsg of 'gadIncoming'

{
    __intf: 'IND',
    subsys: 'gad',
    type: 'gadIncoming',
    id: 2763,                   // gadget id is 2763
    data: {
        id: 2763,       // gadget id
        dev: {
            id: 822,    // device id
            permAddr: '0x00124b0001ce4b89'
        },
        panel: {
            enabled: true,
            profile: 'home_automation',
            classId: 'lightCtrl'
        },
        props: {
            name: 'sampleLight',
            description: 'This is a simple light controller'
        },
        attrs: {
            onOff: 1,
            dimmer: 80
        }
    }
}

Indication Example: indMsg of 'gadLeaving'

{
    __intf: 'IND',
    subsys: 'gad',
    type: 'gadLeaving',
    id: 41,                   // gadget id is 41
    data: { 
        netcore: 'mqtt-core', 
        permAddr: '0x123456789abcdef',
        auxId: 'temperature/0' 
    }
}

Indication Example: indMsg of gadget 'panelChanged'

{
    __intf: 'IND',
    subsys: 'gad',
    type: 'panelChanged',
    id: 21,                   // gadget id is 21
    data: {
        enabled: true
    }
}

Indication Example: indMsg of gadget 'propsChanged'

{
    __intf: 'IND',
    subsys: 'gad',
    type: 'propsChanged',
    id: 52,                   // gadget id is 52
    data: {
        description: 'A good smart radio in my bedroom'
    }
}

Indication Example: indMsg of gadget 'attrsChanged'

{
    __intf: 'IND',
    subsys: 'gad',
    type: 'attrsChanged',
    id: 83,                   // gadget id is 83
    data: {
        onOff: 0
    }
}

Indication Example: indMsg of gadget 'attrsReport'

{
    __intf: 'IND',
    subsys: 'gad',
    type: 'attrsReport',
    id: 64,                   // gadget id is 64
    data: {
        sensorValue: 18
    }
}

7. Appendix

Netcore Information (ncInfo) Object

Properties

Property	Type	Description
name	String	Netcore name
enabled	Boolean	Is this netcore enabled?
protocol	Object	Network protocol of this netcore.
startTime	Number	Start time of this netcore. (UNIX time in secs)
traffic	Object	Accumulated inbound and outbound data since netcore started. { in: { hits: 6, bytes: 24 }, out: { hits: 3, bytes: 30 } } (unit: bytes)
numDevs	Number	Number of devices managed by this netcore
numGads	Number	Number of gadgets managed by this netcore

Example

{
    name: 'zigbee-core',
    enabled: true,
    protocol: {              // required
        phy: 'ieee802.15.4', // required, physical layer
        dll: '',             // optional, data link layer
        nwk: 'zigbee',       // required, network layer
        tl: '',              // optional, transportation layer
        sl: '',              // optional, session layer
        pl: '',              // optional, presentation layer
        apl: 'zcl',          // optional, application layer
    },
    startTime: 1458008208,
    defaultJoinTime: 180,
    traffic: {
        in: {
            hits: 6,
            bytes: 24
        },
        out: {
            hits: 3,
            bytes: 30
        }
    },
    numDevs: 32,
    numGads: 46
}

Device Information (devInfo) Object

Properties

Property	Type	Description
id	Number	Device id
netcore	String	Name of the netcore that holds this device
gads	Number[]	A list of gadget ids that this device owns
net	Object	Network information of the device.
props	Object	Meta-properties of the device. This is for client users to set something to the device
attrs	Object	Attributes of the device. This is attributes of the remote device.

net object

Property	Type	Description
enabled	Boolean	Is this device enabled?
joinTime	Number	Device join time. UNIX time in secs
timestamp	Number	Device last activity. UNIX time in secs
role	String	Device role. Depends on protocol, i.e., 'peripheral' for BLE devices, 'router' for zigbee devices
parent	String	Parent device permanent address. It is string '0' if device parent is its netcore
status	String	Device status, can be 'online', 'sleep', 'offline', or 'unknown'
address	Object	Device permanent and dynamic addresses. { permanent: '00:0c:29:ff:ed:7c', dynamic: '192.168.1.101' }
traffic	Object	Accumulated inbound and outbound data since device joined. { in: { hits: 6, bytes: 24 }, out: { hits: 3, bytes: 30 } } (unit: bytes)

props object

Property	Type	Description
name	String	Device name. This is not on the remote device and can be set by end-users.
description	String	Device description. This is not on the remote device and can be set by end-users.
location	String	Device location. This is not on the remote device and can be set by end-users.
others	Any	Anything end-users like to set to device `props` by setProps API.

attrs object

Property	Type	Description
manufacturer	String	Manufacturer name
model	String	Model name
version	Object	Version tags. { hw: '', sw: 'v1.2.2', fw: 'v0.0.8' }
power	Object	Power source. { type: 'battery', voltage: '5V' }. The type can be 'line', 'battery' or 'harvester'

Example

{
    id: 6,
    netcore: 'mqtt-core',
    gads: [ 116, 117 ],
    net: {
        enabled: true,
        joinTime: 1458008208,
        timestamp: 1458008617,
        role: 'client',         // depends on protocol
        parent: '0',            // parent is the netcore
        status: 'online'
        address: {
            permanent: '00:0c:29:ff:ed:7c',
            dynamic: '192.168.1.73'
        },
        traffic: {              // accumulated data since device joined
            in: {
                hits: 6,
                bytes: 72
            },
            out: {
                hits: 12,
                bytes: 96
            }
        }
    },
    props: {    // props: name, description, and location are writable and can be modified by users
        name: 'sample_device',
        description: 'This is a device example',
        location: 'balcony'
    },
    attrs: {
        manufacturer: 'freebird',
        model: 'lwmqn-7688-duo',
        serial: 'lwmqn-2016-03-15-01',
        version: {
            hw: 'v1.2.0',
            sw: 'v0.8.4',
            fw: 'v2.0.0'
        },
        power: {
            type: 'line',
            voltage: '5V'
        }
    }
}

Gadget Information (gadInfo) Object

Properties

Property	Type	Description
id	Number	Gadget id
netcore	String	Name of the netcore that holds this gadget
dev	Object	Id and permanent address of which device owns this gadget. { id: 3, permAddr: '0x00124b0001ce4b89' }
auxId	String	The auxiliary id to identify the gadget on a device
panel	Object	Basic information about the gadget. { enabled: true, profile: 'home', classId: 'temperature' }
props	Object	Meta-properties of this gadget. This is for client users to set something to the gadget
attrs	Object	Attributes of this gadget

panel object

Property	Type	Description
enabled	Boolean	Is this gadget enabled?
profile	String	Optional. The profile defines the application environment, may mot be given.
classId	String	The classId defines what application the gadget is. The gadget class to denote its application, i.e. 'illuminance', 'temperature', 'lightCtrl'

props object

Property	Type	Description
name	String	Gadget name. This is not on the remote device and can be set by end-users.
description	String	Gadget description. This is not on the remote device and can be set by end-users.
others	Any	Anything end-users like to set to gadget `props` by setProps API.

attrs object

Property	Type	Description
Depends	Any	The gadget attributes that could be read, written, or excuted on the remote device.

Example

{
    id: 308,
    netcore: 'zb-core',
    dev: {
        id: 26,
        permAddr: '0x00124b0001ce4b89'
    },
    panel: {
        enabled: true,
        profile: 'home_automation', // it will be an empty string '' if no profile given
        classId: 'lightCtrl'
    },
    props: {    // props: name and description writable and can be modified by end-users
        name: 'sampleLight',
        description: 'This is a simple light controller'
    },
    attrs: {
        onOff: 1,
        dimmer: 80
    }
}

Attribute Report Configuration (rptCfg) Object

Properties

Property	Type	Mandatory	Description
pmin	Number	optional	Minimum Period. Minimum time in seconds the gadget should wait from the time when sending the last notification to the time when sending a new notification.
pmax	Number	optional	Maximum Period. Maximum time in seconds the gadget should wait from the time when sending the last notification to the time sending the next notification (regardless if the value has changed).
gt	Number	optional	Greater Than. The gadget should notify its attribute when the value is greater than this setting. Only valid for the attribute typed as a number.
lt	Number	optional	Less Than. The gadget should notify its attribute when the value is smaller than this setting. Only valid for the attribute typed as a number.
step	Number	optional	Step. The gadget should notify its value when the change of the attribute value, since the last report happened, is greater than this setting.
enable	Boolean	required	It is set to true for the gadget to start reporting an attribute. Set to false to stop reporting.

Example

// start reporting with the following settings
{
    pmin: 10,
    pmax: 60,
    lt: 120
    gt: 260
    enable: true
}

// the time chart of reporting: (O: report triggered, xxxxx: pmin, -----: pmax)
//       O             O     O             O     O             O     O             O
// |xxxxx|-------------|xxxxx|-------------|xxxxx|-------------|xxxxx|-------------|
// 0s   10s           70s   80s           140s 150s           210s  220s          280s
//  <10s> <    60s    >

// note:
//     1. only in |---------| duration, any change meets lt or gt condition will be reported
//     2. In this example, the attribute will be reported when its value is greater than 260 or is less than 120

// start periodical reporting
{
    pmin: 0,
    pmax: 30,
    enable: true
}

// the time chart of reporting: (O: report triggered, xxxxx: pmin, -----: pmax)
// O             O             O             O             O             0
// |-------------|-------------|-------------|-------------|-------------|
// 0s           30s           60s           90s          120s          150s

// note:
//     1. In this example, the attribute will be reported every 30 seconds

// set but not start reporting
{
    gt: 50
    enable: false
}

// start reporting with the current settings
{
    enable: true
}

// stop reporting
{
    enable: false
}

Gadget Classes

Freebird framework uses the classId property on a gadget to define its application. The classes are Smart Object Identfiers defined by IPSO SmartObject Guideline(Smart Objects Starter Pack1.0). Here is the table of Object ids from lwm2m-id library.

Class Id	Description
'dIn'	Digital Input
'dOut'	Digital Output
'aIn'	Analogue Input
'aOut'	Analogue Output
'generic'	Generic Sensor
'illuminance'	Illuminance Sensor
'presence'	Presence Sensor
'temperature'	Temperature Sensor
'humidity'	Humidity Sensor
'pwrMea'	Power Measurement
'actuation'	Actuation
'setPoint'	Set Point
'loadCtrl'	Load Control
'lightCtrl'	Light Control
'pwrCtrl'	Power Control
'accelerometer'	Accelerometer
'magnetometer'	Magnetometer
'barometer'	Barometer
'voltage'	Voltage
'current'	Current
'frequency'	Frequency
'depth'	Depth
'percentage'	Percentage
'altitude'	Altitude
'load'	Load
'pressure'	Pressure
'loudness'	Loudness
'concentration'	Concentration
'acidity'	Acidity
'conductivity'	Conductivity
'power'	Power
'powerFactor'	Power Factor
'distance'	Distance
'energy'	Energy
'direction'	Direction
'time'	Time
'gyrometer'	Gyrometer
'colour'	Colour
'gpsLocation'	GPS Location
'positioner'	Positioner
'buzzer'	Buzzer
'audioClip'	Audio Clip
'timer'	Timer
'addressableTextDisplay'	Addressable Text Display
'onOffSwitch'	On/Off Switch
'levelControl'	Level Controller
'upDownControl'	Up/Down Controller
'multipleAxisJoystick'	Multiple Axis Joystick
'rate'	Rate
'pushButton'	Push Button
'multistateSelector'	Multi-state Selector

Response Status Code

Code	Description
200	OK
201	Created
202	Deleted
204	Changed
205	Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
405	Method Not Allowed
408	Timeout
409	Conflict
500	Internal Server Error

Home

Overview

Usage

APIs & Events

createClient()
createServer()
Client Class
- send()
- 'open' event
- 'close' event
- 'ind' event
Server Class
- send()
- broadcast()
- 'message' event

Messaging Interface

REQ/RSP Message Model

IND Message Model

Appendix

Data Objects
- ncInfo
- devInfo
- gadInfo
- rptCfg
Gadget classId
Status Code

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Home

1. Overview

Subsystems

Example

Why subsystems?

2. Installation

3. Usage

4. APIs and Events

.createServer(httpServer)

.createClient(addr[, options])

Server Class

.send(msg, callback)

.broadcast(msg, callback)

.on('message', function (msg) {})

Client Class

.send(subsys, cmd, args, callback)

.on('open', function () {})

.on('close', function (code, reason) {})

.on('ind', function (msg) {})

Messaging Interfaces

Request Message

Response Message

Indication Message

Message Data Model

Request Data Model

Response Data Model

Indication Data Model

7. Appendix

Netcore Information (ncInfo) Object

Device Information (devInfo) Object

Gadget Information (gadInfo) Object

Attribute Report Configuration (rptCfg) Object

Gadget Classes

Response Status Code

Clone this wiki locally