Skip to content

Home

Jump to bottom
simen edited this page Mar 27, 2017 · 22 revisions

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
var fbRpc = require('freebird-rpc'),
    http = require('http');

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

var rpcServer = fbRpc.createServer(httpServer);
  • Create a RPC client
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:

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

Returns:

  • (Object): rpcServer

Example:

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

var httpServer,
    rpcServer;

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



.createClient(addr[, options])

Create the websocket RPC client.

Arguments:

  1. addr (String): host address and port.
  2. 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 this 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:

  1. 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 Data Object definition, and it must be serialized to a JSON string when transmitting.
  2. 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: 0,
    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:

  1. msg (Object): msg must has the data field. data is the message to transmit out which must be shaped with Indication Data Object definition, and it must be serialized to a JSON string when transmitting.
  2. 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

  1. msg (Object): msg contains clientId and data properties. clientId is to help the user determine which client sends the message, and data is the received message which will follow Request Data Object and be converted to a JSON string.

Example:

rpcServer.on('message', function (msg) {
    console.log(msg.data.toString());
});


Client Class

fbRpc.createClient() returns an instance of this 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:

  1. subSys (String): Only 3 types are accepted. They are 'net', 'dev', and 'gad' to denote which subsystem is this message referring to.
  2. cmd (String): Command identifier, which is simply the API name. It can be found in the Command Name field of the Request Data Model.
  3. args (Object): A value-object with command arguments. Please see section Request Data Model to learn more about the args.
  4. callback (Function): function (err, result) {}. Get called when the server respond to this client with results of the client asking for.
    • '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 definition.

Returns:

  • (None)

Example:

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

        // result equal to 
        // {
        //     status: 0,
        //     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

  1. code (Number): code is a numeric value to indicate the status code explaining why the connection has been closed.
  2. 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

  1. 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

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

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

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 } A banned gadget is trying to join the network
net 'bannedDevReporting' { netcore:String, permAddr:String } A banned device is trying to report its attributes
net 'bannedGadReporting' { netcore:String, permAddr:String, auxId:String | Number } A banned gadget is trying to report its attributes
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 } A gadget is leaving
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


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
    }
}


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
}


Gadget Classes

Freebird framework uses the class 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 Name 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


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
}

Home

Overview

Usage

APIs & Events

Messaging Interface

REQ/RSP Message Model

IND Message Model

Appendix

Clone this wiki locally