Skip to content

Message Object

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

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


Request Data Model

The request message is an object with keys { __intf, subsys, seq, id, cmd, args }.

The following table gives the details of each command API for its subsys, cmd, and args.

Subsystem Command Name Arguments (args) Description
net getAllDevIds { [ncName] } Get identifiers of all devices on freebird Server. ncName is a string and is optional. If ncName is given, only identifiers of devices managed by that netcore will be returned from freebird.
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 } }.


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

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

Messaging Interface

REQ/RSP Message Model

IND Message Model

Appendix

Clone this wiki locally