APIs for Implementer

This document gives the Netcore APIs for implementers to call, not for Netcore users!

Netcore APIs for Implementers

API	Description
Create a netcore	Use require('freebird-base').createNetcore() to create a new instance of Netcore.
registerNetDrivers()	Register network drivers to the netcore.
registerDevDrivers()	Register device drivers to the netcore.
registerGadDrivers()	Register gadget drivers to the netcore.
commitReady()	Tell the netcore that the network controller is ready.
commitDevNetChanging()	When a device changes any of its network information, tell the netcore.
commitDevIncoming()	When a device is coming into the network, tell the netcore.
commitDevLeaving()	When a device is leaving from the network, tell the netcore.
commitGadIncoming()	When a gadget is coming into the network, tell the netcore.
commitDevReporting()	When a device reports its attribtue(s), tell the netcore.
commitGadReporting()	When a gadget reports its attribtue(s), tell the netcore.
dangerouslyCommitGadReporting()	When a gadget reports its attribtue(s), tell the netcore. If attribute does not exist, netcore will append it to the gadget.

---

Create a netcore: require('freebird-base').createNetcore(name, controller, protocol[, opt])

Create a new instance of Netcore.

Arguments:

1. name (String): Netcore name.

2. controller (Object): Low-level controller. e.g., ble-shepherd.

3. 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

4. opt (Object): Reserved.

Returns:

• (Object): netcore

Examples:

// Network raw controller
var BShepherd = require('ble-shepherd'),
    controller = new BShepherd('noble');

// Freebird netcore
var fbBase = require('freebird-base'),
    nc;

var nc = fbBase.createNetcore('freebird-netcore-ble', controller, {
    phy: 'bluetooth smart',
    nwk: 'ble'
});

---

.registerNetDrivers(netDrvs)

Register network drivers to the netcore.

Arguments:

1. netDrvs (Object): An object contains all network management drivers required by the netcore. Please see Network Driver Section for more details on signature and behavior of each driver.

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 (done) {
        // your implementation
    },
    stop: function (done) {
        // your implementation
    },
    reset: function (mode, done) {
        // your implementation
    },
    permitJoin: function (duration, done) {
        // your implementation
    },
    remove: function (permAddr, done) {
        // your implementation
    },
    ping: function (permAddr, done) {
        // your implementation
    }
};

nc.registerNetDrivers(netDrvs);

---

.registerDevDrivers(devDrvs)

Register device drivers to the netcore.

Arguments:

1. drvs (Object): An object contains all device operation drivers required by the netcore. Please see Device Driver Section for more details on signature and behavior of each driver.

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 the device supoorts 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, done) {
        // your implementation
    },
    write: function (permAddr, attrName, val, done) {
        // your implementation
    },
    identify: function (permAddr, done) {
        // your implementation
    }
};

nc.registerDevDrivers(devDrvs);

---

.registerGadDrivers(gadDrvs)

Register gadget drivers to the netcore.

Arguments:

1. drvs (Object): An object contains all gadget operation drivers required by the netcore. Please see Gadget Driver Section for more details on signature and behavior of each driver.

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 a procedure on a remote gadget
readReportCfg	Function	optional	Driver to read the report configuration of 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, done) {
        // your implementation
    },
    write: function (permAddr, auxId, attrName, val, done) {
        // your implementation
    },
    exec: function (permAddr, auxId, attrName, args, done) {
        // your implementation
    },
    readReportCfg: function (permAddr, auxId, attrName, done) {
        // your implementation
    },
    writeReportCfg: function (permAddr, auxId, attrName, cfg, done) {
        // your implementation
    }
};

nc.registerDevDrivers(gadDrvs);

---

.commitReady()

Call commitReady to tell netcore that the network controller is ready. Everytime when netcore starts, reboots, or resets, it must call nc.commitReady() to let the netcore know if it is ready.

Arguments:

• none

Returns:

• none

Examples:

nc.commitReady();

---

.commitDevNetChanging(permAddr, changes)

Commit the device network information changes.

Arguments:

1. permAddr (String): Permanent address of the device.
2. changes (Object): Network information changes, which is an object in the shape of { role, parent, maySleep, sleepPeriod, status, address: { dynamic } } and partial changes is acceptable.

Returns:

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

Examples:

// commit a status change
nc.commitDevNetChanging('0x0123456789', { status: 'online' });

// commit some changes at once
nc.commitDevNetChanging('0x0123456789', {
    status: 'online',
    parent: '0xabcd12345',
    role: 'end-device'
});

---

.commitDevIncoming(permAddr, rawDev)

Commit a device incoming message to netcore when a device is coming in.

Arguments:

1. permAddr (String): Permanent address of the device.
2. rawDev (Object): Raw device data given by the low-layer controller.

Returns:

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

Examples:

nc.commitDevIncoming('0x0123456789', rawDev);   // rawDev is an object from the controller

---

.commitDevLeaving(permAddr)

Commit a device leaving message to netcore when a device is leaving from the network.

Arguments:

1. permAddr (String): Permanent address of the device.

Returns:

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

Examples:

nc.commitDevLeaving('0x0123456789');

---

.commitGadIncoming(permAddr, auxId, rawGad)

Commit a gadget incoming message to netcore when a gadget is coming in.

Arguments:

1. permAddr (String): Permanent address of which device is the gadget hosted on.
2. auxId (String | Number): Auxiliary id of the gadget. This id is to uniquely identify a gadget on the device.
3. rawGad (Object): Raw gadget data given by the low-layer controller.

Returns:

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

Examples:

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

---

.commitDevReporting(permAddr, devAttrs)

Commit a device reporting message to netcore when a device attribtue(s) report is received.

Arguments:

1. permAddr (String): Permanent address of the device.
2. devAttrs (Object): Attribtue(s) report from the remote device.

Returns:

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

Examples:

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

---

.commitGadReporting(permAddr, auxId, gadAttrs)

Commit a gadget reporting message to netcore when a gadget attribtue(s) report is received.

Arguments:

1. permAddr (String): Permanent address of which device is the gadget hosted on.
2. auxId (String | Number): Auxiliary id of the gadget. This id is to uniquely identify a gadget on the device.
3. gadAttrs (Object): Attribtue(s) report from the remote gadget.

Returns:

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

Examples:

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

---

.dangerouslyCommitGadReporting(permAddr, auxId, gadAttrs)

Dangerously commit a gadget reporting message to netcore when a gadget attribtue(s) report is received. This will append new attribute(s) to the gadget if the reported attribute(s) does not exist. Use this API as you do know what you are doing.

Arguments:

1. permAddr (String): Permanent address of which device is the gadget hosted on.
2. auxId (String | Number): Auxiliary id of the gadget. This id is to uniquely identify a gadget on the device.
3. gadAttrs (Object): Attribtue(s) report from the remote gadget.

Returns:

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

Examples:

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