Skip to content

Message Object

Jump to bottom
simen edited this page May 12, 2017 · 10 revisions

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

Subsystem Command Name Arguments (args) Description
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.


Response Data Model

Subsystem Command Name Data Key:Type Data Description Response data Example
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

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



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


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

Messaging Interface

REQ/RSP Message Model

IND Message Model

Appendix

Clone this wiki locally