Message Object

This document presents the args and data formats within the REQ/RSP/IND messages.

Command Table

Subsystem	Command Name	Description
net	getAllDevIds	Get identifiers of all devices on freebird Server.
net	getAllGadIds	Get identifiers of all gadgets on freebird Server.
net	getDevs	Get device information by device ids.
net	getGads	Get gadget information by gadget ids.
net	getNetcores	Get netcore information by netcore names.
net	getBlacklist	Get blacklist of the banned devices.
net	permitJoin	Allow or disallow devices to join the network.
net	maintain	Maintain the network.
net	reset	Reset the network.
net	enable	Enable the network.
net	disable	Disable the network.
net	ban	Ban a device from the network.
net	unban	Unban a device.
net	remove	Remove a device from the network.
net	ping	Ping a device in the network.
dev	enable	Enable the device to activate its function and messages transportation.
dev	disable	Disable the device.
dev	read	Read an attribute on a device.
dev	write	Write a value to an attribute on a device.
dev	identify	Identify a device in the network.
dev	remove	Remove a device from the network.
dev	ping	Ping a device in the network.
dev	getProps	Get device meta-properties.
dev	setProps	Set device meta-properties.
gad	enable	Enable the gadget to activate its function and messages transportation.
gad	disable	Disable the gadget.
gad	read	Read an attribute on a gadget.
gad	write	Write a value to an attribute on a gadget.
gad	exec	Invoke a remote procedure on a gadget.
gad	writeReportCfg	Set the condition for an attribute reporting from a gadget.
gad	readReportCfg	Get the report settings of an attribute on a gadget.
gad	getProps	Get gadget meta-properties.
gad	setProps	Set gadget meta-properties.

Indication Table

subsys	Indication Type	Data 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 or disallowing 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.

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 command API for its subsys, cmd, and args.

Subsystem	Command Name	Arguments (args)	Description
net	getAllDevIds	{ [ncName] }
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 freebird.
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.
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 } }`.

getAllDevIds

Get identifiers of all devices managed by the freebird server.

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'getAllDevIds', args: <Object> }
args (Object): { [ncName] }
- ncName is a string and is optional. If ncName is given, return identifiers of devices managed by that netcore; otherwise, return all.

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'getAllDevIds', status: <Status Code>, data: <Number> }
data (Object): { ids: <Number[]> } or {}
- Array of device identifiers

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 82,
    id: 0,
    cmd: 'getAllDevIds',
    args: {
        ncName: 'mqtt-core'
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 82,
    id: 0,
    cmd: 'getAllDevIds',
    status: 205 ,
    data: {
        ids: [ 1, 2, 3, 8, 12 ]
    }
}

Response Data Model

The response message is an object with keys { __intf, subsys, seq, id, cmd, status, data }, where status field shows if the request is successful, 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.

The following table gives the details of each response for its subsys, cmd, and data.

subsys: net

Subsystem	Command Name	Data Key:Type	Data Description	Response `data` Example
net	getAllDevIds	ids:Number[]		{ 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 indication type, and data field is an object that contains indication data in it.

subsys	Indication Type	Data Key:Type	Data 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
    }
}

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