-
Notifications
You must be signed in to change notification settings - Fork 2
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.
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'));
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). |
Checks if this device is enabled.
Arguments:
- none
Returns:
- (Boolean): Returns
true
if enabled, elsefalse
.
Examples:
myDevice.isEnabled(); // true
Checks if this device has been registered to freebird.
Arguments:
- none
Returns:
- (Boolean): Returns
true
if registered, elsefalse
.
Examples:
myDevice.isRegistered(); // false
Enable this device. Transportation is active when device is enabled.
Arguments:
- none
Returns:
- (Object): device
Examples:
myDevice.enable();
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();
Reset traffic record of the device.
Arguments:
-
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 ifdir
is not specified.
Returns:
- (Object): device
Examples:
myDevice.resetTraffic('in');
myDevice.resetTraffic('out');
myDevice.resetTraffic();
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'
}
}
*/
Getter to get the required information.
Arguments:
-
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 returnsundefined
.
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
}
*/
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:
-
name
(String): Possible names are'net'
,'attrs'
, and'props'
-
data
(Depends): See descriptions below
-
set('net', data)
- Locally set network information on the device. Setting of
'enabled'
property will be ignored, one should useenable()
anddisable()
instead to enable or disable the device. -
data
(netInfoObj): An object contains (partial) key-value pairs of the network information.
- Locally set network information on the device. Setting of
-
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.
- 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)
- 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.
- Locally set properties on the device. This is for customization, you are free to add any property you like to
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 device attribute from the remote device.
Arguments:
-
attrName
(String): Attribute name -
callback
(Function):function (err, data) {}
Returns:
- none
Examples:
myDevice.read('model', function (err, data) {
if (!err)
console.log(data); // 'lwmqn-7688-duo'
});
Remotely write a value to an attribute on this device.
Arguments:
-
attrName
(String): Attribute name -
val
(Depends): Attribute value to write to the device -
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 this device. If remote device does not implement this feature, it would be inapplicable.
Arguments:
-
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 this remote device.
Arguments:
-
callback
(Function):function (err, time) {}
Returns:
- none
Examples:
myDevice.ping(function (err, time) {
if (!err)
console.log(time); // 26, this value is in milliseconds
});
Refresh the status and attributes from the remote device. All gadgets owned by this device will be refreshed as well.
Arguments:
-
callback
(Function):function (err) {}
Returns:
- none
Examples:
myDevice.maintain(function (err) {
if (!err)
console.log('device refreshed.');
});
freebird team
Overview
Main Classes
Design Your Own Netcore
- Workflow
- APIs for Implementer
- Unified data model
- What should be implemented
Appendix
- Device data object format
- Gadget data object format