Skip to content

Workflow

Jump to bottom
simen edited this page May 3, 2017 · 9 revisions

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


1. What is netcore?

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


3. Netcore Implementors Responsibilties

  1. Every time when netcore start and ready, the developer should call nc.commitReady() to notify freebird that it is ready (When the low-level boot, reboot, soft/hard reset, the low-level must use this API to notify freebird).
  2. Need to implement nc._cookRawDev() and nc._cookRawGad() two methods to tell freebird how the low-level device or gadget raw data objects into Device Class and Gadget Class objects. In the implementation of the content, the developer must use dev.set('net', netInfoObj), dev.set('attrs', devAttrsObj), gad.set('panel ', panelInfoObj) and gad.set('attrs', gadAttrsObj) to complete the setup of the device and the gadget.
  3. Need to implement network management, device control and gadget control drivers. These three types of drivers must use the netcore methods nc.registerNetDrivers(), nc.registerDevDrivers() and nc.registerGadDrivers() to register the driver to netcore. When netcore starts (start ()), it will checks drivers to see if they are complete. If not, netcore will throw an error to remind the developer to implement the driver.
  4. When a new device is incoming to the low-level network, the developer must call nc.commitDevIncoming() to notify the netcore that the network has a device incoming.
  5. When a device is incoming to the network. The developer has the responsibility to find what the application is on the device and generate the corresponding gadget raw data based on certain rules, and then call nc.commitGadIncoming() to notify the netcore.
  6. When a device leaves the network. The developer has the responsibility to call nc.commitDevLeaving() to notify the netcore which device is leaving.
  7. When the low-level receives a attribute change or notification about the device. It must using nc.commitDevReporting() to report to the netcore.
  8. When the low-level receives a attribute change or notification about the gadget. It must using nc.commitGadReporting() to report to the netcore.
  9. When the low-level receives a network change about the device. It must using nc.commitDevNetChanging() to report to the netcore. The network change include any attributes of {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:

Driver


6. Apis

Constructor

Implementer provides

Implementer calls


********************************************
## 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.

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:

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'
});


### Device

### Gadget

## Implementer calls ### Netcore

.registerNetDrivers(netDrvs)

Register network drivers to the netcore.

Arguments:

  1. 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)

Register device drivers to the netcore.

Arguments:

  1. 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)

Register gadget drivers to the netcore.

Arguments:

  1. 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()

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)

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)

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)

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)

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)

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)

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)

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

Clone this wiki locally