How to build a netcore

This document introduces things that you should know about how to create your own netcore for freebird framework.

Content

What is a netcore
Unified Data Model
Implementers Responsibilties
Device instance data settings
Device instance data settings

******************************************** ## 4. Unified Device Data Model: device instance data settings

1. What is a netcore?

Netcore is a network controller which equips with implementation of freebird-defined methods to accomplish operations of network transportation and management.

netcore drivers that implementer should provide:

API	Mandatory	Description
_cookRawDev()	Required	To see if this gadget is enabled.
_cookRawGad()	Required	To see if this gadget is registered to freebird framework.
start()	Required	Start the physical controller.
stop()	Required	Stop the physical controller.
reset()	Required	Reset the physical controller.
permitJoin()	Required	Allow devices to join the established network.
remove()	Required	Remove a remote device from the network.
ban()	Optional	Ban a device from the network.
unban()	Optional	Unban a device.
ping()	Required	Ping a remote device.

device drivers that implementer should provide:

API	Mandatory	Description
read()	Required	Read device attribute from the remote device.
write()	Required	Remotely write a value to an attribute on the device.
identify()	Optional	Identify a device in the network.

gadget drivers that implementer should provide:

API	Mandatory	Description
read()	Required	Read an attribute from a gadget on the remote device.
write()	Required	Remotely write the value to an attribute on the gadget.
exec()	Optional	Remotely invoke the procedure on this gadget.
readReportCfg()	Optional	Get the report settings from the gadget.
writeReportCfg()	Optional	Write the report configuration to a gadget on the remote device.

2. Unified Device and Gadget Data Model

Freebird uses two unified data models to represent the real device and gadget. The definition of a device is a communication device, such as a zigbee module. The definition of a gadget is a single and small application implemented on the device, for example, a zigbee module has two bulbs, so we will say that this package, it uses a device (zigbee module), in its There are 2 gadgets(bulb).

Device Class
- About the information in a device, the most important is the network information. You can use the device's method dev.set('net', netInfoObj) to set its network information.
- Device has another additional information, such as manufacturer, hardware version, etc. You can use device's method dev.set('attrs', devAttrsObj) to set it.
- The format of netInfoObj and devAttrsObj is listed in section 4.

Gadget Class
- About the information in a gadget, the most important is the application information. You can use the gadget's method gad.set('panel', panelInfoObj) to set its basic information.
- The gadget must have attributes associated with its application. As for what attributes should a gadget have, it is determined by the classId that defined by panelInfoObj.
- classId should follow the 51 kinds of Objects provided by IPSO to define its name. This document of smartobject lists the supported Object Ids, which also indicates the attributes that a gadget must have.
- After the developer decides the classId, the developer also has the responsibility to fill the gadget attribute. You can use gadget's method gad.set('attrs', gadAttrsObj) to fill the attributes.
- The format of panelInfoObj and gadAttrsObj is listed in section 5.

3. Netcore Implementors Responsibilties

1. Must inform freebird that the netcore is ready each time when it is started and ready.

Developer should call nc.commitReady() to notify freebird that the netcore is now ready.
When boot, reboot, soft/hard reset, the implementer must use this API to inform freebird.

2. Must implement the data transformers: `nc._cookRawDev()` and `nc._cookRawGad()`

Implement nc._cookRawDev(dev, rawDev, done) to tell freebird how to tranform device raw data into device instance (Device Class).
- According to rawDev content, ues dev.set('net') and dev.set('attrs') fill in the device attributes. Then call done(err, dev) and fill the of the dev to netcore.
- Use dev.set('net', netInfoObj) and dev.set('attrs', devAttrsObj) to set data to the device.
Implement nc._cookRawGad(gad, rawGad, done) to tell freebird how to tranform gadget raw data into gadget instance (Gadget Class).
- According to rawGad content, ues gad.set('panel') and gad.set('attrs') fill in the gadget attributes. Then call done(err, dev) and fill the of the gad to netcore.
- Use gad.set('panel ', panelInfoObj) and gad.set('attrs', gadAttrsObj) to set data to the device.

3. Must implement the drivers for network, device, and gadget management

Use netcore method nc.registerNetDrivers() to register the network drivers.
Use netcore method nc.registerDevDrivers() to register the device drivers.
Use netcore method nc.registerGadDrivers() to register the gadget drivers.

4. Must inform freebird that a device is incoming

Call nc.commitDevIncoming() to notify the freebird that there is a device incoming.

5. When a device is incoming, generate raw data of gadgets depending on certain rules

Call nc.commitGadIncoming() to notify the freebird that there is a gadget incoming.

6. Must inform freebird that a device is leaving from the network

Call nc.commitDevLeaving() to notify the freebird that a device is leaving.

7. Must inform freebird the device attribute(s) changes

Call nc.commitDevReporting() to report to the change(s).

8. Must inform freebird the gadget attribute(s) changes

Call nc.commitGadReporting() to report to the change(s).

9. Must inform freebird the device network status changes

Call nc.commitDevNetChanging() to report to the change(s).
The network status change(s) could be any attribute in object { role, parent, maySleep, sleepPeriod, address: { dynamic } }.

When the developer meets the above requirements. Netcore will be able to work in the freebird framework. In summary, a netcore developer must provide the following implementation:

Drivers

Network Drivers, package the driver with Object {start, stop, reset, permitJoin, remove, ban, unban, ping}, then use nc.registerNetDrivers(netDrvs) to register with netcore.
Device Drivers, package the driver with Object { read, write, identify }, then use nc.registerDevDrivers(devDrvs) to register with netcore.
Gadget Drivers, package the driver with Object { read, write, exec, writeReportCfg, readReportCfg }, then use nc.registerGadDrivers(gadDrvs) to register with netcore.

Arguments and Description for each Method of the Network Drivers

start: function(done) {}
- Start low-level controller. Called done(err) after done.
stop: function(done) {}
- Stop low-level controller. Called done(err) after done.
reset: function(mode, done) {}
- Reset low-level controller. Given mode with 0 for a soft reset and 1 for a hard reset. Called done(err) after done.
permitJoin: function(duration, done) {}
- Let low-level controller allow devices to join its network. Where duration is duration in seconds for the netcore to allow devices to join the network. Set it to 0 will immediately close the admission. Called done(err, timeLeft) after done. Where timeLeft is time left for joining in seconds.
remove: function(permAddr, done) {}
- Remove device from the network. Where permAddr is the device permanent address. Called done(err, permAddr) after done.
ban: function(permAddr, done) {}
- Ban the device from the network. Where permAddr is the device permanent address. Called done(err, permAddr) after done. This method is optional.
unban: function(permAddr, done) {}
- Unban the device. Where permAddr is the device permanent address. Called done(err, permAddr) after done. This method is optional.
ping: function(permAddr, done) {}
- Ping the remote device. Where permAddr is the device permanent address. Called done(err, time) after done. Where time is the round-trip time in milliseconds.

Arguments and Description for each Method of the Device Drivers

read: function(permAddr, attrName, done) {}
- Read device attribute from the remote device. Where permAddr is the device permanent address and attrName is attribute name. Called done(err, val) after done.
write: function(permAddr, attrName, val, done) {}, ),
- Remotely write a value to an attribute on the device. Where permAddr is the device permanent address, attrName is attribute name and val is attribute value to write to the device. Called done(err, val) after done.
identify: function(permAddr, done) {}
- Identify a device in the network. Where permAddr is the device permanent address. Called done(err) after done. This method is optional.

Arguments and Description for each Method of the Gadget Drivers

read: function(permAddr, auxId, attrName, done) {}
- Read an attribute from a gadget on the remote device. Where permAddr is the device permanent address, auxId is auxiliary id to identify a gadget on the device and attrName is attribute name. Called done(err, val) after done.
write: function(permAddr, auxId, attrName, val, done) {}
- Remotely write the value to an attribute on the gadget. Where permAddr is the device permanent address, auxId is auxiliary id to identify a gadget on the device, attrName is attribute name and val is attribute value to write to the gadget.. Called done(err, val) after done.
exec: function(permAddr, auxId, attrName, args, done) {}
- Remotely invoke the procedure on this gadget. Where permAddr is the device permanent address, auxId is auxiliary id to identify a gadget on the device, attrName is attribute name and args is arguments to invoke with. Called done(err, result) after done. This method is optional.
writeReportCfg: function(permAddr, auxId, attrName, cfg, done) {}
- Remotely get the report settings from the gadget. Where permAddr is the device permanent address, auxId is auxiliary id to identify a gadget on the device, attrName is attribute name and cfg is report configuration. Called done(err, result) after done. This method is optional.
readReportCfg: function(permAddr, auxId, attrName, done) {}
- Write the report configuration to a gadget on the remote device. Where permAddr is the device permanent address, auxId is auxiliary id to identify a gadget on the device and attrName is attribute name. Called done(err, cfg) after done. This method is optional.

4. Unified Device Data Model: device instance data settings

To set network information for a device, use its method dev.set('net', netInfoObj) to do this; To set attributes for a device, use its method dev.set('attrs', devAttrsObj) to do this.

dev.set('net', netInfoObj)

The object netInfoObj accepts the fields as follows. Where only address is required. address is an object with permanent address (permanent) and dynamic address (dynamic).

Property	Type	Mandatory	Description
address	Object	required	Device address record object `{ permanent, dynamic }`. `permanent` is permanent address and `dynamic` is dynamic address, these are required. `permanent` address can only be a string, and `dynamic` address can be a string or a number.
role	String	optional	The network role of the device. Depending on the protocol may have a different string to represent its role. e.g., zigbee may use 'router', 'end-device', and BLE may use 'central', 'peripheral'
parent	String	optional	The permanent address of the parent node of the device. If not a mesh network, all devices may be centralized to the netcore. Which means that the netcore is the parent node of all nodes. Then this field should be filled with '0', The default is '0'.
maySleep	Boolean	optional	If you are sure your device might sleep. Please set this field `true`. It will be related to Freebird how to confirm whether the device online algorithm. The default is `false`.
sleepPeriod	Number	optional	This field is valid when `maySleep` is `true`. If you know the device sleep cycle. Please set the number of seconds for the cycle. Freebird will use this to adjust its current status checking algorithm.

dev.set('attrs', devAttrsObj)

All of the propertys in devAttrsObj are optional. But should be filled in as much as possible. In order to meet these fields, you may need to remotely read the device attribute a few times.

Property	Type	Mandatory	Description
manufacturer	String	optional	Manufacturer name or identifier
model	String	optional	Hardware module model
serial	String	optional	Hardware serial or serial number
version	Object	optional	The attributes of this object `{ hw, sw, fw }` are used to record the version number of the hardware (`hw`), software (`sw`), and firmware (`fw`). The version number must be a string.
power	Object	optional	This object `{ type, voltage }` is used to record the power supply type of the hardware. Where the `type` attribute accepts the `'line'`, `'battery'`, or `'harvester'` three strings to represent the power supply type, and the voltage is filled with the string containing the unit. e.g., `'5 V'`

5. Unified Gadget Data Model: gadget instance data settings

To set panel information for a gadget, use its method gad.set('panel', panelInfoObj) to do this.

gad.set('panel', panelInfoObj)

Panel information means that an object seems to have a brand to show what it is. The object panelInfoObj currently has only two fields. One is classId and the other is profile. classId is optional. Because it will show what the gadget is. e.g., a lamp, a temperature sensor, or a power switch.

Property	Type	Mandatory	Description
classId	String	required	The class identifier of this object. Currently accept only 51 kinds of smart objects defined by IPSO. Please use the string value of Object Id to fill in `classId`. e.g., `'dIn'`, `'aIn'`, `'generic'`, `'temperature'`, `'humidity'`, etc.
profile	String	optional	The profile of this object. e.g., `'HA'`

Currently accepted classId a total of 51 (IPSO definition), they are strings
- 'dIn', 'dOut'
- 'aIn', 'aOut'
- 'generic', 'illuminance', 'presence', 'temperature', 'humidity'
- 'pwrMea'
- 'actuation', 'setPoint', 'loadCtrl', 'lightCtrl', 'pwrCtrl'
- 'accelerometer', 'magnetometer', 'barometer'
- 'voltage', 'current', 'frequency', 'depth', 'percentage', 'altitude', 'load', 'pressure'
- 'loudness', 'concentration', 'acidity', 'conductivity', 'power', 'powerFactor', 'distance'
- 'energy', 'direction', 'time', 'gyrometer', 'colour', 'gpsLocation', 'positioner', 'buzzer'
- 'audioClip', 'timer', 'addressableTextDisplay', 'onOffSwitch', 'levelControl'
- 'upDownControl', 'multipleAxisJoystick', 'rate', 'pushButton', 'multistateSelector'

6. Apis

********************************************
## Constructor ### Netcore

new Netcore(name, controller, protocol[, opt])

Netcore constructor. It is suggested to use freebird-base .createNetcore() method to create a new instance of Netcore.

Implementer calls

Arguments:

name (String): Netcore name.
controller (Object): Low-level controller. e.g., ble-shepherd.

protocol (Object): Information of the used protocol

Property	Type	Mandatory	Description
phy	String	Required	Physic layer
dll	String	Optional	Data link layer
nwk	String	Required	Network layer
tl	String	Optional	Transportation layer
sl	String	Optional	Session layer
pl	String	Optional	Presentation layer
apl	String	Optional	Application layer

opt (Object): Reserved.

Returns:

(Object): netcore

Examples:

var BShepherd = require('ble-shepherd'),
    fbBase = require('freebird-base'),
    Netcore = fbBase.Netcore,
    controller = new BShepherd('noble');

var nc = new Netcore('freebird-netcore-ble', controller, {
    phy: 'ieee802.15.1',
    nwk: 'ble',
});

// recommended to use .createNetcore()
var nc = fbBase.createNetcore('freebird-netcore-ble', controller, {
    phy: 'ieee802.15.1',
    nwk: 'ble'
});

********************************************
## Implementer provides ### Netcore

_cookRawDev(dev, rawDev, done)

<< Implementer provides for the freebird to >>
According to the low-level device data object rawDev, use dev.set('net') and dev.set('attrs') to fill the Device Instance Data. At the end, call done(err, dev) return to netcore。

Arguments:

dev (Object): Deivce instance.
rawDev (Object): Raw device data object.
done (Function): function (err, dev) {}. Return dev to netcore.

Returns:

none

Examples:

nc._cookRawDev = function (dev, rawDev, done) {
    dev.set('net', {
        role: 'router',
        maySleep: false,
        address: {  // Required
            permanent: rawDev.ieeeAddr,
            dynamic: rawDev.nwkAddr,
        }
    });

    dev.set('attrs', {
        manufacturer: rawDev.manufacturerName,
        model: rawDev.modelNum
    });

    done(null, dev);
};

_cookRawGad(gad, rawGad, done)

<< Implementer provides for the freebird to >>
According to the low-level gadget data object rawGad, Use gad.set('panel') and gad.set('attrs') to fill the Gadget Instance Data. At the end, call done(err, gad) return to netcore。

Arguments:

gad (Object): gadget instance.
rawGad (Object): Raw gadget data object.
done (Function): function (err, gad) {}. Return gad to netcore.

Returns:

none

Examples:

nc._cookRawGad = function (gad, rawGad, done) {
    gad.set('panel', {
        profile: 'home',
        classId: 'presence'
    });

    gad.set('attrs', {
        dInState: 5500,
        counter: 5501,
        counterReset: 5505
    });

    done(null, gad);
};

start(done)

<< Implementer provides for the users to >>
Start low-level controller.

Arguments:

done (Function): function (err) {}.

Returns:

none

Examples:

var netDrvs = {
    start: function (done) {
        // your implementation

        done(null);  // call at the end
    },
    ...
};

stop(done)

<< Implementer provides for the users to >>
Stop low-level controller.

Arguments:

done (Function): function (err) {}.

Returns:

none

Examples:

var netDrvs = {
    stop: function (done) {
        // your implementation

        done(null);  // call at the end
    },
    ...
};

reset(mode, done)

<< Implementer provides for the users to >>
Reset low-level controller.

Arguments:

mode (Number): 0 for a soft reset and 1 for a hard reset. It will perform the soft reset if mode is not given.
done (Function): function (err) {}.

Returns:

none

Examples:

var netDrvs = {
    reset: function (mode, done) {
        // your implementation

        done(null);  // call at the end
    },
    ...
};

permitJoin(duration, done)

<< Implementer provides for the users to >>
Let low-level controller allow devices to join its network.

Arguments:

duration (Number): Duration in seconds for the netcore to allow devices to join the network. Set it to 0 can immediately close the admission.
done (Function): function (err, timeLeft) {}. timeLeft (Number) is a number that indicates time left for device joining in seconds.

Returns:

none

Examples:

var netDrvs = {
    permitJoin: function (duration, done) {
        // your implementation

        done(null, timeLeft);  // call at the end
    },
    ...
};

remove(permAddr, done)

<< Implementer provides for the users to >>
Remove a remote device from the network.

Arguments:

permAddr (String): Device permanent address.
done (Function): function (err, permAddr) {}. permAddr (String) is the permananet address of that device.

Returns:

none

Examples:

var netDrvs = {
    remove: function (permAddr, done) {
        // your implementation

        done(null, permAddr);  // call at the end
    },
    ...
};

ban(permAddr, done)

<< Implementer provides for the users to >>
Ban a device from the network. This driver is optional.

Arguments:

permAddr (String): Device permanent address.
done (Function): function (err, permAddr) {}. permAddr (String) is the permananet address of that device.

Returns:

none

Examples:

var netDrvs = {
    ban: function (permAddr, done) {
        // your implementation

        done(null, permAddr);  // call at the end
    },
    ...
};

unban(permAddr, done)

<< Implementer provides for the users to >>
Unban a device. This driver is optional.

Arguments:

permAddr (String): Device permanent address.
done (Function): function (err, permAddr) {}. permAddr (String) is the permananet address of that device.

Returns:

none

Examples:

var netDrvs = {
    unban: function (permAddr, done) {
        // your implementation

        done(null, permAddr);  // call at the end
    },
    ...
};

ping(permAddr, done)

<< Implementer provides for the users to >>
Ping a remote device.

Arguments:

permAddr (String): Device permanent address.
done (Function): function (err, time) {}. time (Number) is the round-trip time in milliseconds, e.g., 16.

Returns:

none

Examples:

var netDrvs = {
    ping: function (permAddr, done) {
        // your implementation

        done(null, time);  // call at the end
    },
    ...
};

********************************************
### Device

read(permAddr, attrName, done)

<< Implementer provides for the users to >>
Read device attribute from the remote device.

Arguments:

permAddr (String): Device permanent address.
attrName (String): Attribute name.
done (Function): function (err, val) {}. val (Depends) is the attribute value.

Returns:

none

Examples:

var devDrvs = {
    read: function (permAddr, attrName, done) {
        // your implementation

        done(null, data);  // call at the end
    },
    ...
};

write(permAddr, attrName, val, done)

<< Implementer provides for the users to >>
Remotely write a value to an attribute on the device.

Arguments:

permAddr (String): Device permanent address.
attrName (String): Attribute name.
val (Depends): Attribute value to write to the device.
done (Function): function (err[, val]) {}. val (Depends) is the written value. Returns:

none

Examples:

var devDrvs = {
    write: function (permAddr, attrName, val, done) {
        // your implementation

        done(null[, data]);  // call at the end
    },
    ...
};

identify(permAddr, done)

<< Implementer provides for the users to >>
Identify a device in the network. If remote device does not implement this feature, it would be inapplicable.

Arguments:

permAddr (String): Device permanent address.
done (Function): function (err, permAddr) {}. permAddr (String) is the permanent address which device to be identified.

Returns:

none

Examples:

var devDrvs = {
    identify: function (permAddr, done) {
        // your implementation

        done(null, permAddr);  // call at the end
    },
    ...
};

********************************************
### Gadget

read(permAddr, auxId, attrName, done)

<< Implementer provides for the users to >>
Read an attribute from a gadget on the remote device.

Arguments:

permAddr (String): Device permanent address.
auxId (String | Number): Auxiliary id to identify a gadget on the device.
attrName (String): Attribute name.
done (Function): function (err, val) {}. val (Depends) is the attribute value.

Returns:

none

Examples:

var gadDrvs = {
    read: function (permAddr, auxId, attrName, done) {
        // your implementation

        done(null, data);  // call at the end
    },
    ...
};

write(permAddr, auxId, attrName, val, done)

<< Implementer provides for the users to >>
Remotely write the value to an attribute on the gadget.

Arguments:

permAddr (String): Device permanent address.
auxId (String | Number): Auxiliary id to identify a gadget on the device.
attrName (String): Attribute name.
val (Depends): Attribute value to write to the gadget.
done (Function): function (err[, val]) {}. val (Depends) is the written value.

Returns:

none

Examples:

var gadDrvs = {
    write: function (permAddr, auxId, attrName, val, done) {
        // your implementation

        done(null[, data]);  // call at the end
    },
    ...
};

exec(permAddr, auxId, attrName, args, done)

<< Implementer provides for the users to >>
Remotely invoke the procedure on this gadget. This driver is optional.

Arguments:

permAddr (String): Device permanent address.
auxId (String | Number): Auxiliary id to identify a gadget on the device.
attrName (String): Attribute name.
args (Array): Arguments to invoke with.
done (Function): function (err, result) {}. result (Depends) is the data returned by the procedure.

Returns:

none

Examples:

var gadDrvs = {
    exec: function (permAddr, auxId, attrName, args, done) {
        // your implementation

        done(null, result);  // call at the end
    },
    ...
};

readReportCfg(permAddr, auxId, attrName, done)

<< Implementer provides for the users to >>
Remotely get the report settings from the gadget. This driver is optional.

Arguments:

permAddr (String): Device permanent address.
auxId (String | Number): Auxiliary id to identify a gadget on the device.
attrName (String): Name of which attribute you'd like to read its reporting configuration.
done (Function): function (err, cfg) {}. cfg (Object) is the attribute settings object。

Returns:

none

Examples:

var gadDrvs = {
    readReportCfg: function (permAddr, auxId, attrName, done) {
        // your implementation

        done(null, cfg);  // call at the end
    },
    ...
};

writeReportCfg(permAddr, auxId, attrName, cfg, done) - Implementer provides

<< Implementer provides for the users to >>
Write the report configuration to a gadget on the remote device. This driver is optional.

Arguments:

permAddr (String): Device permanent address.
auxId (String | Number): Auxiliary id to identify a gadget on the device.
attrName (String): Name of which attribute you'd like to set its reporting behavior.
cfg (Object): Report configuration.
done (Function): function (err, result) {}. result (Boolean) show if the reporting configuration is written.

Returns:

none

Examples:

var gadDrvs = {
    writeReportCfg: function (permAddr, auxId, attrName, cfg, done) {
        // your implementation

        done(null, result);  // call at the end
    },
    ...
};

.registerNetDrivers(netDrvs)

<< Implementer calls to >>
Register network drivers to the netcore.

Arguments:

netDrvs (Object): An object contains all network management drivers required by the netcore.

Property	Type	Mandatory	Description
start	Function	required	Driver to start the network controller
stop	Function	required	Driver to stop the network controller
reset	Function	required	Driver to reset the network controller
permitJoin	Function	required	Driver to allow devices to join the network
remove	Function	required	Driver to remove a device from the network
ping	Function	required	Driver to ping a device in the network
ban	Function	optional	Driver to ban a device from the network
unban	Function	optional	Driver to unban a device from the network

Returns:

(Object): netcore

Examples:

var netDrvs = {
    start: function (callback) {},
    stop: function (callback) {},
    reset: function (mode, callback) {},
    permitJoin: function (duration, callback) {},
    remove: function (permAddr, callback) {},
    ping: function (permAddr, callback) {}
};

nc.registerNetDrivers(netDrvs);

.registerDevDrivers(devDrvs)

<< Implementer calls to >>
Register device drivers to the netcore.

Arguments:

drvs (Object): An object contains all device operation drivers required by the netcore.

Property	Type	Mandatory	Description
read	Function	required	Driver to read an attribute from a remote device
write	Function	required	Driver to write an attribute value to a remote device
identify	Function	optional	Driver to identify a remote device. This method is optional. If a device supoorts the identifying mode, it may, for example, start to blink a led to get users attention.

Returns:

(Object): netcore

Examples:

var devDrvs = {
    read: function (permAddr, attrName, callback) {},
    write: function (permAddr, attrName, val, callback) {},
    identify: function (permAddr, callback) {}
};

nc.registerDevDrivers(devDrvs);

.registerGadDrivers(gadDrvs)

<< Implementer calls to >>
Register gadget drivers to the netcore.

Arguments:

drvs (Object): An object contains all device operation drivers required by the netcore.

Property	Type	Mandatory	Description
read	Function	required	Driver to read an attribute from a remote gadget
write	Function	required	Driver to write an attribute value to a remote gadget
exec	Function	optional	Driver to invoke the procedure on a remote gadget
readReportCfg	Function	optional	Driver to read the report configuration to a remote gadget
writeReportCfg	Function	optional	Driver to write the report configuration to a remote gadget

Returns:

(Object): netcore

Examples:

var gadDrvs = {
    read: function (permAddr, auxId, attrName, callback) {},
    write: function (permAddr, auxId, attrName, val, callback) {},
    exec: function (permAddr, auxId, attrName, args, callback) {},
    readReportCfg: function (permAddr, auxId, attrName, callback) {},
    writeReportCfg: function (permAddr, auxId, attrName, cfg, callback) {}
};

nc.registerDevDrivers(gadDrvs);

.commitReady()

<< Implementer calls to >>
Commit ready to tell the netcore that the network controller is ready. Everytime the netcore starts, reboots, or resset, it must call nc.commitReady() to let the netcore know.

Arguments:

none

Returns:

none

Examples:

nc.commitReady();

.commitDevNetChanging(permAddr, changes)

<< Implementer calls to >>
Commit the network status when a device changes its status.

Arguments:

none

Returns:

(Boolean): true for a success, otherwise false for failure.

Examples:

nc.commitDevNetChanging('0x0123456789', { status: 'online' });

.commitDevIncoming(permAddr, rawDev)

<< Implementer calls to >>
Commit a device incoming message to netcore when a device comes in.

Arguments:

none

Returns:

(Boolean): true for a success, otherwise false for failure.

Examples:

nc.commitDevIncoming('0x0123456789', rawDev);

.commitDevLeaving(permAddr)

<< Implementer calls to >>
Commit a device leaving message to netcore when a device leave from the network.

Arguments:

none

Returns:

(Boolean): true for a success, otherwise false for failure.

Examples:

nc.commitDevLeaving('0x0123456789');

.commitGadIncoming(permAddr, auxId, rawGad)

<< Implementer calls to >>
Commit a gadget incoming message to netcore when a gadget comes in.

Arguments:

none

Returns:

(Boolean): true for a success, otherwise false for failure.

Examples:

nc.commitGadIncoming('0x0123456789', 'temperature/0', rawGad);

.commitDevReporting(permAddr, devAttrs)

<< Implementer calls to >>
Commit a device reporting message to netcore when a device reports its attribtue(s).

Arguments:

none

Returns:

(Boolean): true for a success, otherwise false for failure.

Examples:

nc.commitDevReporting('0x0123456789', { manufacturer: 'xxx' });

.commitGadReporting(permAddr, auxId, gadAttrs)

<< Implementer calls to >>
Commit a gadget reporting message to netcore when a gadget reports its attribtue(s).

Arguments:

none

Returns:

(Boolean): true for a success, otherwise false for failure.

Examples:

nc.commitGadReporting('0x0123456789', 'temperature/0', { sensorValue: 27.8 });

.dangerouslyCommitGadReporting(permAddr, auxId, gadAttrs)

<< Implementer calls to >>
Dangerously commit a gadget reporting message to netcore when a gadget reports its attribtue(s). This will restructure the attrs data in the gadget instance. Use this API when you do know what you are doing.

Arguments:

none

Returns:

(Boolean): true for a success, otherwise false for failure.

Examples:

nc.dangerouslyCommitGadReporting('0x12345678abcde', 'dIn/6', {
    xx: 1,
    yy: 2
});

freebird team

Home

Overview

Main Classes

Design Your Own Netcore

Appendix

Device data object format
Gadget data object format

How to build a netcore

Content

1. What is a netcore?

netcore drivers that implementer should provide:

device drivers that implementer should provide:

gadget drivers that implementer should provide:

2. Unified Device and Gadget Data Model

3. Netcore Implementors Responsibilties

1. Must inform freebird that the netcore is ready each time when it is started and ready.

2. Must implement the data transformers: nc._cookRawDev() and nc._cookRawGad()

3. Must implement the drivers for network, device, and gadget management

4. Must inform freebird that a device is incoming

5. When a device is incoming, generate raw data of gadgets depending on certain rules

6. Must inform freebird that a device is leaving from the network

7. Must inform freebird the device attribute(s) changes

8. Must inform freebird the gadget attribute(s) changes

9. Must inform freebird the device network status changes

Drivers

Arguments and Description for each Method of the Network Drivers

Arguments and Description for each Method of the Device Drivers

Arguments and Description for each Method of the Gadget Drivers

4. Unified Device Data Model: device instance data settings

dev.set('net', netInfoObj)

dev.set('attrs', devAttrsObj)

5. Unified Gadget Data Model: gadget instance data settings

gad.set('panel', panelInfoObj)

6. Apis

Constructor

Implementer provides

Implementer calls

new Netcore(name, controller, protocol[, opt])

_cookRawDev(dev, rawDev, done)

_cookRawGad(gad, rawGad, done)

start(done)

stop(done)

reset(mode, done)

permitJoin(duration, done)

remove(permAddr, done)

ban(permAddr, done)

unban(permAddr, done)

ping(permAddr, done)

read(permAddr, attrName, done)

write(permAddr, attrName, val, done)

identify(permAddr, done)

read(permAddr, auxId, attrName, done)

write(permAddr, auxId, attrName, val, done)

exec(permAddr, auxId, attrName, args, done)

readReportCfg(permAddr, auxId, attrName, done)

writeReportCfg(permAddr, auxId, attrName, cfg, done) - Implementer provides

.registerNetDrivers(netDrvs)

.registerDevDrivers(devDrvs)

.registerGadDrivers(gadDrvs)

.commitReady()

.commitDevNetChanging(permAddr, changes)

.commitDevIncoming(permAddr, rawDev)

.commitDevLeaving(permAddr)

.commitGadIncoming(permAddr, auxId, rawGad)

.commitDevReporting(permAddr, devAttrs)

.commitGadReporting(permAddr, auxId, gadAttrs)

.dangerouslyCommitGadReporting(permAddr, auxId, gadAttrs)

Clone this wiki locally

2. Must implement the data transformers: `nc._cookRawDev()` and `nc._cookRawGad()`