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.

net: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: { [ncName: <String>] }
- 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: <Object> }
data: { 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 ]
    }
}

net:getAllGadIds

Get identifiers of all gadgets on freebird Server.

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'getAllGadIds', args: <Object> }
args: { [ncName: <String>] }
- ncName is the name of which netcore you like to get gadgets under it management. If ncName is not given, all gadgets on the freebird will be returned.

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'getAllGadIds', status: <Status Code>, data: <Object> }
data: { ids: <Number[]> }
- ids is an array of gadget identifiers.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'getAllGadIds',
    args: {
        ncName: 'freebird-netcore-zigbee'
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'getAllGadIds',
    status: 205,
    data: {
        ids: [ 2, 3, 5, 11, 12, 13, 14, 15 ]
    }
}

net:getDevs

Get information of devices by their ids.

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'getDevs', args: <Object> }
args: { ids: <Number[]> }
- ids is an array of numbers and each number is a device id, i.e., given { ids: [ 56, 77 ] }.

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'getDevs', status: <Status Code>, data: <Object> }
data: { devs: <devInfo[]> }
- devs is an array of device information objects (devInfo).

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'getDevs',
    args: {
        ids: [ 56, 77 ]
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'getDevs',
    status: 205,
    data: {
        devs: [
            {
                id: 56,
                netcore: 'freebird-netcore-mqtt',
                gads: [ 116, 117 ],
                net: {
                    enabled: true,
                    joinTime: 1458008208,
                    timestamp: 1458008617,
                    role: 'client',
                    parent: '0',
                    status: 'online'
                    address: {
                        permanent: '00:0c:29:ff:ed:7c',
                        dynamic: '192.168.1.73'
                    },
                    traffic: {
                        in: { hits: 6, bytes: 72 },
                        out: { hits: 12, bytes: 96 }
                    }
                },
                props: {
                    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'
                    }
                }
            },
            {
                id: 77,
                netcore: 'freebird-netcore-ble',
                gads: [ 168, 169, 170 ],
                // ... ignore
            }
        ]
    }
}

net:getGads

Get gadget information by gadget ids.

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'getGads', args: <Object> }
args: { ids: <Number[]> }
- ids is an array of numbers and each number is a gadget id, i.e., given { ids: [ 23, 14, 132 ] }.

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'getGads', status: <Status Code>, data: <Object> }
data: { gads: <gadInfo[]> }
- gads is an array of gadget information objects (gadInfo).

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'getGads',
    args: {
        ids: [ 23, 14 ]
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'getGads',
    status: 205,
    data: {
        gads: [
            {
                id: 23,
                netcore: 'freebird-netcore-zigbee',
                dev: {
                    id: 26,
                    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
                }
            },
            {
                id: 14,
                netcore: 'freebird-netcore-ble',
                dev: {
                    id: 6,
                    permAddr: '0xecbb14ffcd1cc117a'
                },
                panel: {
                    enabled: true,
                    profile: 'home_automation',
                    classId: 'temperature'
                },
                props: {
                    name: 'temp_sensor_01',
                    description: 'This is a temperature sensor'
                },
                attrs: {
                    sensorValue: 26.2,
                    unit: 'cel'
                }
            }
        ]
    }
}

net:getNetcores

Get netcore information by netcore names. ncNames . Given with an empty object {} to get all netcore infos at once.

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'getNetcores', args: <Object> }
args: { [ncNames: <String[]>] }
- ncNames is an array of strings and each string is a netcore name, e.g., ncNames: [ 'freebird-netcore-ble', 'freebird-netcore-zigbee' ].

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'getNetcores', status: <Status Code>, data: <Object> }
data: { netcores: <ncInfo[]> }
- netcores is an array of the netcore information objects (ncInfo).

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'getNetcores',
    args: {
        ncName: [ 'freebird-netcore-zigbee' ]
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'getNetcores',
    status: 205,
    data: {
        netcores: [
            {
                name: 'freebird-netcore-zigbee',
                enabled: true,
                protocol: { phy: 'ieee802.15.4', dll: '', nwk: 'zigbee', tl: '', sl: '', pl: '', apl: 'zcl' },
                startTime: 1458008208,
                defaultJoinTime: 180,
                traffic: {
                    in: { hits: 6, bytes: 24 },
                    out: { hits: 3, bytes: 30 }
                },
                numDevs: 32,
                numGads: 46
            }
        ]
    }
}

net:getBlacklist

Get blacklist of the banned devices. . i.e., given { ncName: 'ble-core' }

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'getBlacklist', args: <Object> }
args: { ncName: <String> }
- ncName is the netcore name of which you like to get the blacklist from.

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'getBlacklist', status: <Status Code>, data: <Object> }
data: { list: <String[]> }
- list is an array of banned device permanent address.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'getBlacklist',
    args: {
        ncName: 'freebird-netcore-zigbee'
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'getBlacklist',
    status: 205,
    data: {
        list: [ '0x00124b0001ce4b89', '0x00124b0001277a4d' ]
    }
}

net:permitJoin

Allow or disallow devices to join the network.

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'permitJoin', args: <Object> }
args: { [ncName: <String>,] duration: <Number> }
- ncName is the name of which netcore you like to allow for device joining. 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.

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'permitJoin', status: <Status Code>, data: <Object> }
data: {}
- Response contains no data.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'permitJoin',
    args: {
        ncName: 'freebird-netcore-zigbee',
        duration: 60
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'permitJoin',
    status: 200,
    data: {}
}

net:maintain

Maintain the network. When a netcore starts to maintain its own network, all devices managed by it will be refreshed.

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'maintain', args: <Object> }
args: { [ncName: <String>] }
- ncName is the name of which netcore you like to maintain. All netcores will enter maintaining mode if ncName is not given.

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'maintain', status: <Status Code>, data: <Object> }
data: {}
- Response contains no data.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'maintain',
    args: {
        ncName: 'freebird-netcore-zigbee'
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'maintain',
    status: 200,
    data: {}
}

net:reset

Reset the network. Reset a network will remove all devices managed by that netcore. Once reset, the banned devices in the netcore blacklist will also be removed.

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'reset', args: <Object> }
args: { [ncName: <String>,] mode: < Number> }
- ncName is the name of which netcore you like to reset. It will reset all netcores if ncName is not given.
- mode is given with 1 for a HARD reset while with 0 for a SOFT reset.

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'reset', status: <Status Code>, data: <Object> }
data: {}
- Response contains no data.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'reset',
    args: {
        ncName: 'freebird-netcore-zigbee',
        mode: 0
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'reset',
    status: 200,
    data: {}
}

net:enable

Enable the network.

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'enable', args: <Object> }
args: { [ncName: <String>] }
- 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.)

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'enable', status: <Status Code>, data: <Object> }
data: {}
- Response contains no data.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'enable',
    args: {
        ncName: 'freebird-netcore-zigbee'
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'enable',
    status: 200,
    data: {}
}

net:disable

Disable the network. 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.

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'disable', args: <Object> }
args: { [ncName: <String>] }
- ncName is the name of which netcore you like to disable. It will disable all netcores if ncName is not given.

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'disable', status: <Status Code>, data: <Object> }
data: {}
- Response contains no data.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'disable',
    args: {
        ncName: 'freebird-netcore-zigbee'
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'disable',
    status: 200,
    data: {}
}

net:ban

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.

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'ban', args: <Object> }
args: { ncName: <String>, permAddr: <String> }
- ncName is the netcore that manages the device.
- permAddr is the permanent address of the device to be banned. 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.

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'ban', status: <Status Code>, data: <Object> }
data: { permAddr: <String> }
- permAddr is the device permanent address.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'ban',
    args: {
        ncName: 'freebird-netcore-zigbee'
        id: '0x00124b0001ce4b89'
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'ban',
    status: 200,
    data: {
        permAddr: '0x00124b0001ce4b89'
    }
}

net:unban

Unban a device.

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'unban', args: <Object> }
args: { ncName: <String>, permAddr: <String> }
- ncName is the netcore that manages the device.
- permAddr is the permanent address of the banned device.

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'unban', status: <Status Code>, data: <Object> }
data: { permAddr: <String> }
- permAddr is the device permanent address.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'unban',
    args: {
        ncName: 'freebird-netcore-zigbee'
        id: '0x00124b0001ce4b89'
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'unban',
    status: 200,
    data: {
        permAddr: '0x00124b0001ce4b89'
    }
}

net:remove

Remove a device from the network.

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'remove', args: <Object> }
args: { ncName: <String>, permAddr: <String> }
- ncName is the netcore that manages the device.
- permAddr is the permanent address of the device to be removed.

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'remove', status: <Status Code>, data: <Object> }
data: { permAddr: <String> }
- permAddr is the device permanent address.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'remove',
    args: {
        ncName: 'freebird-netcore-zigbee'
        id: '0x00124b0001ce4b89'
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'remove',
    status: 200,
    data: {
        permAddr: '0x00124b0001ce4b89'
    }
}

net:ping

Ping a device in the network.

Request Message:

msg: { __intf: 'REQ', subsys: 'net', seq: <Number>, id: 0, cmd: 'ping', args: <Object> }
args: { ncName: <String>, permAddr: <String> }
- ncName is the netcore that manages the device.
- permAddr is the permanent address of the device you like to ping.

Response Message:

msg: { __intf: 'RSP', subsys: 'net', seq: <Number>, id: 0, cmd: 'ping', status: <Status Code>, data: <Object> }
data: { time: <Number> }
- time is the round-trip time in ms.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'ping',
    args: {
        ncName: 'freebird-netcore-zigbee'
        id: '0x00124b0001ce4b89'
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'net',
    seq: 22,
    id: 0,
    cmd: 'ping',
    status: 200,
    data: {
        time: 12
    }
}

dev:enable

Enable the device to activate its function and messages transportation.

Request Message:

msg: { __intf: 'REQ', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'enable', args: <Object> }
args: { id: <Number> }
- id is the devices id.

Response Message:

msg: { __intf: 'RSP', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'enable', status: <Status Code>, data: <Object> }
data: { enabled: <Boolean> }
- enabled is the value to show if the device is enabled.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'enable',
    args: {
        id: 18
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'enable',
    status: 200,
    data: {
        enabled: true
    }
}

dev:disable

Disable the device.

Request Message:

msg: { __intf: 'REQ', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'disable', args: <Object> }
args: { id: <Number> }
- id is the devices id.

Response Message:

msg: { __intf: 'RSP', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'disable', status: <Status Code>, data: <Object> }
data: { enabled: <Boolean> }
- enabled is the value to show if the device is enabled.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'disable',
    args: {
        id: 18
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'disable',
    status: 200,
    data: {
        enabled: false
    }
}

dev:read

Read an attribute on a device.

Request Message:

msg: { __intf: 'REQ', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'read', args: <Object> }
args: { id: <Number>, attrName: <String> }
- id is the devices id.
- attrName is the attribute to read from.

Response Message:

msg: { __intf: 'RSP', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'read', status: <Status Code>, data: <Object> }
data: { value: <Depends> }
- The written value.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'read',
    args: {
        id: 18,
        attrName: 'location'
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'read',
    status: 205,
    data: {
        value: 'bedroom'
    }
}

dev:write

Write a value to an attribute on a device.

Request Message:

msg: { __intf: 'REQ', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'write', args: <Object> }
args: { id: <Number>, attrName: <String>, value: <Depends> }
- id is the devices id.
- attrName is the attribute to write to.
- value is the value to be written.

Response Message:

msg: { __intf: 'RSP', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'write', status: <Status Code>, data: <Object> }
data: { value: <Depends> }
- The written value.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'write',
    args: {
        id: 18,
        attrName: 'location',
        value: 'kitchen'
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'write',
    status: 200,
    data: {
        value: 'kitchen'
    }
}

dev:identify

Identify a device in the network.

Request Message:

msg: { __intf: 'REQ', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'identify', args: <Object> }
args: { id: <Number> }
- id is the devices id.

Response Message:

msg: { __intf: 'RSP', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'identify', status: <Status Code>, data: <Object> }
data: {}
- Response contains no data.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'identify',
    args: {
        id: 18
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'identify',
    status: 200,
    data: {}
}

dev:remove

Remove a device from the network.

Request Message:

msg: { __intf: 'REQ', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'remove', args: <Object> }
args: { id: <Number> }
- id is the devices id.

Response Message:

msg: { __intf: 'RSP', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'remove', status: <Status Code>, data: <Object> }
data: { permAddr: <String> }
- permAddr is the deevice permanent address.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'remove',
    args: {
        id: 18
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'remove',
    status: 200,
    data: {
        permAddr: '0x00124b0001ce4b89'
    }
}

dev:ping

Ping a device in the network.

Request Message:

msg: { __intf: 'REQ', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'ping', args: <Object> }
args: { id: <Number> }
- id is the devices id.

Response Message:

msg: { __intf: 'RSP', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'ping', status: <Status Code>, data: <Object> }
data: { time: <Number> }
- time is the round-trip time in ms.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'ping',
    args: {
        id: 18
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'ping',
    status: 200,
    data: {
        time: 12
    }
}

dev:getProps

Get device meta-properties.

Request Message:

msg: { __intf: 'REQ', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'getProps', args: <Object> }
args: { id: <Number>[, propNames: <String[]> }
- id is the devices id.
- propNames is an array of strings and each string is a meta-property name. All props will be returned if propNames is not given.

Response Message:

msg: { __intf: 'RSP', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'getProps', status: <Status Code>, data: <Object> }
data: { props: <Depends> }
- Response contains no data

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'getProps',
    args: {
        id: 18,
        propNames: [ 'location', 'description' ]
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'getProps',
    status: 200,
    data: {
        props: {
            location: 'kitchen',
            description: 'humidity sensor in the cabinet'
        }
    }
}

dev:setProps

Set device meta-properties.

Request Message:

msg: { __intf: 'REQ', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'setProps', args: <Object> }
args: { id: <Number>, props: <Object> }
- id is the devices id.
- props is an object contains meta-properties to set.

Response Message:

msg: { __intf: 'RSP', subsys: 'dev', seq: <Number>, id: <Number>, cmd: 'setProps', status: <Status Code>, data: <Object> }
data: {}
- Response contains no data

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'setProps',
    args: {
        id: 18,
        props: {
            location: 'bedroom',
            description: 'for my baby'
        }
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'dev',
    seq: 22,
    id: 18,
    cmd: 'setProps',
    status: 200,
    data: {}
}

gad:enable

Enable the gadget to activate its function and messages transportation.

Request Message:

msg: { __intf: 'REQ', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'enable', args: <Object> }
args: { id: <Number> }
- id is the gadget id.

Response Message:

msg: { __intf: 'RSP', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'enable', status: <Status Code>, data: <Object> }
data: { enabled: <Boolean> }
- enabled: To show if the gadget is enabled.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'enable',
    args: {
        id: 161
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'enable',
    status: 200,
    data: {
        enabled: true
    }
}

gad:disable

Disable the gadget.

Request Message:

msg: { __intf: 'REQ', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'disable', args: <Object> }
args: { id: <Number> }
- id is the gadget id.

Response Message:

msg: { __intf: 'RSP', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'disable', status: <Status Code>, data: <Object> }
data: { enabled: <Boolean> }
- enabled: To show if the gadget is enabled.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'disable',
    args: {
        id: 161
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'disable',
    status: 200,
    data: {
        enabled: false
    }
}

gad:read

Read an attribute on a gadget.

Request Message:

msg: { __intf: 'REQ', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'read', args: <Object> }
args: { id: <Number>, attrName: <String> }
- id is the gadget id.
- attrName is the attribute name.

Response Message:

msg: { __intf: 'RSP', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'read', status: <Status Code>, data: <Object> }
data: { value: <Depends> }
- value: The value read.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'read',
    args: {
        id: 161,
        attrName: 'sensorValue'
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'read',
    status: 200,
    data: {
        value: 26.5
    }
}

gad:write

Write a value to an attribute on a gadget.

Request Message:

msg: { __intf: 'REQ', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'write', args: <Object> }
args: { id: <Number>, attrName: <String>, value: <Depends> }
- id is the gadget id.
- attrName is the attribute name.
- value is the value to write to.

Response Message:

msg: { __intf: 'RSP', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'write', status: <Status Code>, data: <Object> }
data: { value: <Depends> }
- value: The value written.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'write',
    args: {
        id: 161,
        attrName: 'onOff',
        value: 1
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'write',
    status: 200,
    data: {
        value: 1
    }
}

gad:exec

Invoke a remote procedure on a gadget.

Request Message:

msg: { __intf: 'REQ', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'exec', args: <Object> }
args: { id: <Number>, attrName: <String>[, params: <Array>] }
- id is the gadget id.
- attrName is the attribute name.
- params is an array of parameters given in order to invoke the executable procedure. The signature depends on developers declaration. For example, given { id: 9, attrName: 'blink', params: [ 10, 500 ] } to blink a LED on a gadget 10 times with a 500 ms interval.

Response Message:

msg: { __intf: 'RSP', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'exec', status: <Status Code>, data: <Object> }
data: { result: <Depends> }
- result: The data returned by the procedure. Can be anything.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'exec',
    args: {
        id: 161,
        attrName: 'blink',
        params: [ 10, 500 ]
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'exec',
    status: 200,
    data: {
        result: 'triggered'
    }
}

gad:readReportCfg

Get the report settings of an attribute on a gadget.

Request Message:

msg: { __intf: 'REQ', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'readReportCfg', args: <Object> }
args: { id: <Number>, attrName: <String> }
- id is the gadget id.
- attrName is the attribute name.

Response Message:

msg: { __intf: 'RSP', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'readReportCfg', status: <Status Code>, data: <Object> }
data: { cfg: <Object> }
- cfg: Report settings object rptCfg [TODO: ref]

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'readReportCfg',
    args: {
        id: 161,
        attrName: 'sensorValue'
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'readReportCfg',
    status: 205,
    data: {
        cfg: {
            // [TODO]
        }
    }
}

gad:writeReportCfg

Set the configuration for an attribute reporting of a gadget.

Request Message:

msg: { __intf: 'REQ', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'writeReportCfg', args: <Object> }
args: { id: <Number>, attrName: <String>[, rptCfg: <Object>] } [TODO: cfg? why use rptCfg?]
- id is the gadget id.
- attrName is the attribute name.
- rptCfg is the report settings. [TODO: ref]

Response Message:

msg: { __intf: 'RSP', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'writeReportCfg', status: <Status Code>, data: <Object> }
data: { result: <Boolean> }
- To show if the reporting configuration is written. true for success, otherwise false.

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'writeReportCfg',
    args: {
        id: 161,
        attrName: 'sensorValue',
        rptCfg: {
            // [TODO]
        }
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'writeReportCfg',
    status: 205,
    data: {
        result: true
    }
}

gad:getProps

Get gadget meta-properties.

Request Message:

msg: { __intf: 'REQ', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'getProps', args: <Object> }
args: { id: <Number> [, propNames: <String[]> ] }
- id is the gadget id.
- propNames is an array of strings and each string is a meta-property name. All props will be returned if propNames is not given.

Response Message:

msg: { __intf: 'RSP', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'getProps', status: <Status Code>, data: <Object> }
data: { props: <Object> }

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'getProps',
    args: {
        id: 161,
        propNames: [ 'name', 'description' ]
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'getProps',
    status: 205,
    data: {
        props: {
            name: 'mysensor1',
            description: 'temperature sensor 1'
        }
    }
}

gad:setProps

Set gadget meta-properties.

Request Message:

msg: { __intf: 'REQ', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'setProps', args: <Object> }
args: { id: <Number>, props: <Object> }
- id is the gadget id.
- props is an object contains meta-properties to set.

Response Message:

msg: { __intf: 'RSP', subsys: 'gad', seq: <Number>, id: <Number>, cmd: 'setProps', status: <Status Code>, data: <Object> }
data: {}
- Response contains no data

Example:

// Request:
{
    __intf: 'REQ',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'setProps',
    args: {
        id: 161,
        props: { description: 'temperature sensor 3', installed: true }
    }
}

// Response:
{
    __intf: 'RSP',
    subsys: 'gad',
    seq: 22,
    id: 161,
    cmd: 'setProps',
    status: 200,
    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

Message Object

Command Table

Indication Table

net:getAllDevIds

net:getAllGadIds

net:getDevs

net:getGads

net:getNetcores

net:getBlacklist

net:permitJoin

net:maintain

net:reset

net:enable

net:disable

net:ban

net:unban

net:remove

net:ping

dev:enable

dev:disable

dev:read

dev:write

dev:identify

dev:remove

dev:ping

dev:getProps

dev:setProps

gad:enable

gad:disable

gad:read

gad:write

gad:exec

gad:readReportCfg

gad:writeReportCfg

gad:getProps

gad:setProps

Indication Data Model

Clone this wiki locally