Gadget Class

The Gadget Class defines a gadget (an application), such as a temperature sensor, a light switch, and a barometer. This document will show you what methods does a gadget have.

Finding a gadget managed by the freebird

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

var gad1 = freebird.findById('gadget', 120);
var gad2 = freebird.findByNet('gadget', 'my-netcore-mqtt', '00:0c:29:ff:ed:7c', 'humidity/2');

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

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

---

Gadget APIs

The following table list the description for each method on a gadget instance.

API	Description
isEnabled()	To see if this gadget is enabled.
isRegistered()	To see if this gadget is registered to freebird framework.
enable()	Enable this gadget. Transportation to this gadget is active when enabled.
disable()	Disable this gadget. Any transportation to this gadget will be inactivated.
dump()	Dump the information of this gadget.
get()	Getter to get the information by the property name.
set()	Setter to set data to the gadget.
read()	Read an attribute from a gadget on the remote device.
write()	Remotely write the value to an attribute on this gadget.
exec()	Remotely invoke the procedure on this gadget.
readReportCfg()	Get the report settings from the gadget.
writeReportCfg()	Write the report config to a gadget on the remote device.

.isEnabled()

To see if this gadget is enabled.

Arguments:

• none

Returns:

• (Boolean): true if enabled, otherwise false.

Examples:

myGadget.isEnabled();  // false

---

.isRegistered()

To see if this gadget is registered to freebird framework.

Arguments:

• none

Returns:

• (Boolean): true if registered, otherwise false.

Examples:

myGadget.isRegistered();  // false

---

.enable()

Enable this gadget. Transportation to this gadget is active when enabled.

Arguments:

• none

Returns:

• (Object): gadget

Examples:

myGadget.enable();

---

.disable()

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

Arguments:

• none

Returns:

• (Object): gadget

Examples:

myGadget.disable();

---

.dump()

Dump the information of this gadget.

Arguments:

• none

Returns:

• (Object): Information about this gadget.

Property	Type	Description
netcore	String	Netcore name
id	Number	Gadget id in freebird
auxId	String | Number	Auxiliary id to identify the gadget on a device
dev	Object	Owner device information, { id: 3, permAddr: '0x12345678' }
panel	panelInfoObj	Panel information, { enabled: true, profile: 'Home', classId: 'temperature' }
attrs	gadAttrsObj	Gadget attributes
props	gadPropsObj	User-defined properties

Examples:

myGadget.dump();
/*
{
    netcore: 'freebird-netcore-mqtt',
    id: 648,
    auxId: 'temperature/0',
    dev: {
        id: 573,
        permAddr: '0x123456789abcdef'
    },
    panel: {
        enabled: true,
        profile: 'Home',
        classId: 'temperature'
    },
    attrs: {
        sensorValue: 26.4 ,
        unit: 'Cels'
    },
    props: {
        name: 'sivann temperature sensor',
        description: 'Do not remove this sensor'
    }
}
*/

---

Getter and Setter

---

.get(name)

Getter to get the information by the property name.

Arguments:

1. name (String):

Name	Description	Example	Returned Data Type
'id'	Get gadget id assigned by freebird. It will be null if it is not registered to freebird.	myGadget.get('id')	Number | null
'auxId'	Get gadget auxiliary id.	myGadget.get('auxId')	Number | String
'raw'	Get raw data which may be undefined if it was not given at instance creation.	myGadget.get('raw')	Object | undefined
'device'	Get the device that owns this gadget.	myGadget.get('device')	Object (device instance)
'netcore'	Get the netcore that manages this gadget.	myGadget.get('netcore')	Object (netcore instance)
'permAddr'	Get the permanent address from which device owns this gadget.	myGadget.get('permAddr')	String
'dynAddr'	Get the dynamic address from which device owns this gadget.	myGadget.get('dynAddr')	Number | String
'location'	Get the location of which device owns this gadget.	myGadget.get('location')	String
'panel'	Get panel information of this gadget.	myGadget.get('panel')	Object (panelInfoObj)
'attrs'	Get attributes of this gadget.	myGadget.get('attrs')	Object (gadAttrsObj)
'props'	Get user-defined properties of this gadget.	myGadget.get('props')	Object (gadPropsObj)

Returns:

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

Examples:

myGadget.get('id');        // 122
myGadget.get('auxId');     // 'temperature/3'

myGadget.get('raw');       // { ... } or undefined
myGadget.get('device');    // device instance
myGadget.get('netcore');   // netcore instance
myGadget.get('permAddr');  // '0x123456789abcdef'
myGadget.get('dynAddr');   // 10163
myGadget.get('location');  // 'kitchen'

myGadget.get('panel');
/*
{
    enabled: true,
    profile: 'Home',
    classId: 'temperature'
}
*/

myGadget.get('attrs');
/*
{
    sensorValue: 26.4,
    unit: 'Cels',
    ...             // There may be other attributes
}
*/

myGadget.get('props');
/*
{
    name: 'sivann temperature sensor',
    description: 'Do not remove this sensor',
    ...             // There may be other properties
}
*/

---

.set(name, data)

Setter to set data to the gadget.

Arguments:

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

• set('panel', data)
  • Locally set panel information on the gadget. Setting of 'enabled' property will be ignored, one should use enable() and disable() instead to enable or disable the gadget.
  • data (panelInfoObj): An object contains partial key-value pairs of the panel information.
• set('attrs', data)
  • Locally set attributes on the gadget. If you like to have some additional attributes, please use set('props', data).
  • data (gadAttrsObj): An object contains partial key-value pairs of the attributes.
• set('props', data)
  • Locally set properties on the gadget. This is for customization, you are free to add any property you like.
  • data (gadPropsObj): An object contains partial key-value pairs of the properties.

Returns:

• (Object): gadget

Examples:

myGadget.set('panel', {
    enabled: true,  // this will be ignore, use enable() or disable() instead
    profile: 'Smart Energy'
});

myGadget.set('attrs', {
    sensorValue: 24
});

myGadget.set('props', {
    name: 'temp sensor',
    greeting: 'hello world!'
});

---

Remote Operations

---

.read(attrName, callback)

Read an attribute from a gadget on the remote device.

Arguments:

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

Returns:

• none

Examples:

myGadget.read('sensorValue', function (err, data) {
    if (!err)
        console.log(data);  // 21.2
});

---

.write(attrName, val, callback)

Remotely write the value to an attribute on this gadget.

Arguments:

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

Returns:

• none

Examples:

myGadget.write('sensorValue', 18, function (err, data) {
    if (err)
        console.log(err);
});

myGadget.write('onOff', 1, function (err, data) {
    if (!err)
        console.log(data);  // 1
});

---

.exec(attrName, args, callback)

Remotely invoke the procedure on this gadget.

Arguments:

1. attrName (String): Attribute name.
2. args (Array): Arguments to invoke with.
3. callback (Function): function (err, data) {}.

Returns:

• none

Examples:

myGadget.exec('blink', [ 10 ], function (err, data) {
    if (!err)
        console.log(data);  // Depends
});

---

.readReportCfg(attrName, callback)

Remotely get the report settings from the gadget.

Arguments:

1. attrName (String): Name of which attribute you'd like to read its reporting configuration.
2. callback (Function): function (err, cfg) {}. The cfg object is the reporting configuration.

Returns:

• none

Examples:

myGadget.readReportCfg('sensorValue', function (err, cfg) {
    if (!err)
        console.log(cfg);  // { pmin: 60, pmax: 180 }
});

---

.writeReportCfg(attrName, cfg, callback)

Write the report configuration to a gadget on the remote device. To start the reporting, one must set cfg.enable = true.

Arguments:

1. attrName (String): Name of which attribute you'd like to set its reporting behavior.

2. cfg (Object): Report configuration.

   Property	Type	Mandatory	Description
   pmin	Number	optional	Minimum Period. Minimum time in seconds the Client Device should wait from the time when sending the last notification to the time when sending a new notification.
   pmax	Number	optional	Maximum Period. Maximum time in seconds the Client Device should wait from the time when sending the last notification to the time sending the next notification (regardless if the value has changed).
   gt	Number	optional	Greater Than. The Client Device should notify its value when the value is greater than this setting. Only valid for the Resource typed as a number.
   lt	Number	optional	Less Than. The Client Device should notify its value when the value is smaller than this setting. Only valid for the Resource typed as a number.
   stp	Number	optional	Step. The Client Device should notify its value when the change of the Resource value, since the last report happened, is greater than this setting.
   enable	Boolean	optional	Set to true for a Client Device to enable observation on the allocated Resource or Object Instance.

3. callback (Function): function (err, data) {}.

Returns:

• none

Examples:

myGadget.writeReportCfg('sensorValue', { pmin: 60, pmax: 180 }, function (err, data) {
    if (!err)
        console.log(data);  // { sensorValue: true }, true for success and false for fail
});