Device Class

The Device Class defines a device which can have many gadgets(applications) on it. A device is a real machine-node in the network, such as a CC2530 ZigBee SoC, a CC2540 BLE SoC, a MT7688 WiFi module, .etc. This document will show you what methods does a device have.

Finding a device managed by the freebird

One can use freebird.findById() or freebird.findByNet() to find a device that has been registered to the freebird.

var dev1 = freebird.findById('device', 26);
var dev2 = freebird.findByNet('device', 'my-netcore-mqtt', '00:0c:29:ff:ed:7c');

if (dev1)
    console.log(dev1.get('id'));

if (dev2)
    console.log(dev2.get('id'));

---

Device APIs

The following table lists the description for each method on a device instance.

API	Description
isEnabled()	Checks if this device is enabled.
isRegistered()	Checks if this device has been registered to freebird.
enable()	Enable this device. Transportation is active when device is enabled.
disable()	Disable this device. Any transportation will be inactivated if device is disabled.
resetTraffic()	Reset traffic record of the device.
dump()	Dump the information of this device.
get()	Getter to get the required information.
set()	Setter to set a value to the device. This method is mostly called by the netcore implementers.
read()	Read device attribute from the remote device.
write()	Remotely write a value to an attribute on this device.
identify()	Identify this device. (Remote device may not implement this feature)
ping()	Ping this remote device.
maintain()	Refresh the status and attributes from the remote device (include gagdtes).

---

.isEnabled()

Checks if this device is enabled.

Arguments:

• none

Returns:

• (Boolean): Returns true if enabled, else false.

Examples:

myDevice.isEnabled();   // true

---

.isRegistered()

Checks if this device has been registered to freebird.

Arguments:

• none

Returns:

• (Boolean): Returns true if registered, else false.

Examples:

myDevice.isRegistered();   // false

---

.enable()

Enable this device. Transportation is active when device is enabled.

Arguments:

• none

Returns:

• (Object): device

Examples:

myDevice.enable();

---

.disable()

Disable this device. Any transportation will be inactivated if device is disabled, and any remote operation upon this device is inapplicable.

Arguments:

• none

Returns:

• (Object): device

Examples:

myDevice.disable();

---

.resetTraffic([dir])

Reset traffic record of the device.

Arguments:

1. dir (String): If given with 'in', the incoming traffic will be reset, else if given with 'out', the outgoing traffic will be reset. Both incoming and outgoing traffic records will be reset if dir is not specified.

Returns:

• (Object): device

Examples:

myDevice.resetTraffic('in');
myDevice.resetTraffic('out');
myDevice.resetTraffic();

---

.dump()

Dump the information of this device.

Arguments:

• none

Returns:

• (Object): Information about this device.

Property	Type	Description
netcore	String	Netcore name
id	Number	Device id assigned by freebird
gads	Array	Gadget records, each record has a shape of { gadId, auxId }
net	Object	Network information object (netInfoObj)
attrs	Object	Device attributes (devAttrsObj)
props	Object	User-defined properties (devPropsObj)

Examples:

myDevice.dump();
/*
{
    netcore: 'freebird-netcore-mqtt',
    id: 268,
    gads: [
        { gadId: 721, auxId: 'temperature/0' },
        { gadId: 722, auxId: 'temperature/1' },
        { gadId: 723, auxId: 'humidity/0' }
    ],
    net: {
        enabled: true,
        joinTime: 1458008311,
        timestamp: 1458008617,
        traffic: {
            in: { hits: 882, bytes: 77826 }
            out: { hits: 67, bytes: 1368  }
        },
        role: 'end-device',
        parent: '0x24576052cdef',
        maySleep: true,
        sleepPeriod: 60,
        status: 'online',
        address: {
            permanent: '0x12345678abcd',
            dynamic: 10163 
        }
    },
    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'
        }
    },
    props: {
        name: 'home sensor 1',
        description: 'It measures temp and humidity in kitchen.',
        location: 'kitchen'
    }
}
*/

---

.get(name)

Getter to get the required information.

Arguments:

1. name (String): Possible names are listed in the following table.

Name	Description	Example	Returned Data Type
'id'	Get device id assigned by freebird. It will be null if it is not registered to freebird.	dev.get('id')	Number | String | null
'raw'	Get raw device data which may be undefined if it was not given at instance creation.	dev.get('raw')	Object | undefined
'netcore'	Get the netcore that manages this device.	dev.get('netcore')	Object (netcore instance)
'address'	Get device permanent and dynamic addresses. Returned object has a shape of { permanent, dynamic }.	dev.get('address')	Object
'permAddr'	Get device permanent address. For example, '00:0c:29:ff:ed:7c'.	dev.get('permAddr')	String
'dynAddr'	Get device dynamic address. For example, '192.168.1.96'.	dev.get('dynAddr')	String | Number
'status'	Get device status. Could be 'online', 'offline', 'sleep', and 'unknown'.	dev.get('status')	String
'gadTable'	Get the table of gadget records on this device. Returns an array in a shape of [ { gadId, auxId }, ... ].	dev.get('gadTable')	Array
'traffic'	Get the current traffic record of this device. Returns an object in a shape of { in: { hits, bytes }, out: { hits, bytes } }.	dev.get('traffic')	Object
'net'	Get network information of this device.	dev.get('net')	Object (netInfoObj)
'attrs'	Get attributes of this device.	dev.get('attrs')	Object (devAttrsObj)
'props'	Get user-defined properties of this device.	dev.get('props')	Object (devPropsObj)

Returns:

• (Depends): If name is none of the listed property, always returns undefined.

Examples:

myDevice.get('foo_name');   // undefined

myDevice.get('id');         // 18
myDevice.get('raw');        // { ieeeAddr: '0x123456789abcdef', nwkAddr: 0x27B3, ... }
myDevice.get('netcore');    // netcore instance
myDevice.get('address');    // { permanent: '0x123456789abcdef', dynamic: 10163 };
myDevice.get('permAddr');   // '0x123456789abcdef'
myDevice.get('dynAddr');    // 10163
myDevice.get('status');     // 'online'. Can be `'online'`, `'offline'`, `'sleep'`, and `'unknown'`.  

myDevice.get('gadTable');
/*
[
    { gadId: 28, auxId: 'temperature/0' },
    { gadId: 29, auxId: 'temperature/1' },
    { gadId: 30, auxId: 'humidity/0' }
]
*/

myDevice.get('traffic');
/*
{
    in: { hits: 6, bytes: 220 },
    out: { hits: 8, bytes: 72 }
}
*/

myDevice.get('net');  // true
/*
{
    enabled: true,
    joinTime: 1458008311,
    timestamp: 1458008617,
    traffic: {
        in: { hits: 882, bytes: 77826 }
        out: { hits: 67, bytes: 1368  }
    },
    role: 'end-device',
    parent: '0x24576052cdef',
    maySleep: true,
    sleepPeriod: 60,
    status: 'online',
    address: {
        permanent: '0x123456789abcdef',
        dynamic: 10163 
    }
}
*/

myDevice.get('attrs');
/*
{
    manufacturer: 'sivann',
    model: 'zb-temperature-sensor',
    serial: 'zb-2016-03-28-002',
    version: {
        hw: '0.8.0',
        sw: '0.4.2',
        fw: '0.4.2'
    },
    power: {
        type: 'battery',
        voltage: '3.3V'
    }
}
*/

myDevice.get('props');
/*
{
    name: 'home sensor 1',          // client user set at will
    description: 'detect heat',     // client user set at will
    location: 'kitchen',            // client user set at will
    ...                             // There may be other properties
}
*/

---

.set(name, data)

Setter to set a value to the device. This method is mostly called by the netcore implementers. The possible usage for netcore users is to call .set('props', devPropsObj).

Arguments:

1. name (String): Possible names are 'net', 'attrs', and 'props'
2. data (Depends): See descriptions below

• set('net', data)
  • Locally set network information on the device. Setting of 'enabled' property will be ignored, one should use enable() and disable() instead to enable or disable the device.
  • data (netInfoObj): An object contains (partial) key-value pairs of the network information.
• set('attrs', data)
  • Locally set (partial) attributes on the device. Only attributes listed in devAttrsObj are accepted. If you like to have some additional attributes, please use set('props', data).
  • data (devAttrsObj): An object contains key-value pairs of the attributes.
• set('props', data)
  • Locally set properties on the device. This is for customization, you are free to add any property you like to props.
  • data (devPropsObj): An object contains (partial) key-value pairs of the properties.

Returns:

• (Object): device

Examples:

myDevice.set('net', {
    enabled: true,      // this will be ignore, use enable() or disable() instead
    status: 'online'
});

myDevice.set('attrs', {
    manufacturer: 'foo_brand'
});

myDevice.set('props', {
    greeting: 'hello world!'
});

---

.read(attrName, callback)

Read device attribute from the remote device.

Arguments:

1. attrName (String): Attribute name
2. callback (Function): function (err, data) {}

Returns:

• none

Examples:

myDevice.read('model', function (err, data) {
    if (!err)
        console.log(data);  // 'lwmqn-7688-duo'
});

---

.write(attrName, val, callback)

Remotely write a value to an attribute on this device.

Arguments:

1. attrName (String): Attribute name
2. val (Depends): Attribute value to write to the device
3. callback (Function): function (err, data) {}

Returns:

• none

Examples:

myDevice.write('model', 'lwmqn-7688-happy-duo', function (err, data) {
    if (!err)
        console.log(data);  // 'lwmqn-7688-happy-duo'

    // Most devices don't accept write operation upon the attribute!
    // Thus you probably will get an error.
});

---

.identify(callback)

Identify this device. If remote device does not implement this feature, it would be inapplicable.

Arguments:

1. callback (Function): function (err) {}

Returns:

• none

Examples:

myDevice.identify(function (err) {
    if (err)
        console.log(err);

    // If no identify driver implemented, an error will occur.
});

---

.ping(callback)

Ping this remote device.

Arguments:

1. callback (Function): function (err, time) {}

Returns:

• none

Examples:

myDevice.ping(function (err, time) {
    if (!err)
        console.log(time);  // 26, this value is in milliseconds
});

---

.maintain(callback)

Refresh the status and attributes from the remote device. All gadgets owned by this device will be refreshed as well.

Arguments:

1. callback (Function): function (err) {}

Returns:

• none

Examples:

myDevice.maintain(function (err) {
    if (!err)
        console.log('device refreshed.');
});