Freebird APIs

Constructor

• new Freebird()    Create a server instance of the Freebird class.

Basic Methods

• findById()            Find a netcore by name, or find a device/gadget by id.
• findByNet()          Find a netcore, a device, or a gadget by network parameters.
• filter()                  Returns an array of netcores, devices, or gadgets you finding for.
• addTransport()    Add a transportation of RPC messaging to freebird.

Network Management

• start()                  Start the freebird server.
• stop()                  Stop the freebird server.
• reset()                  Reset the freebird server.
• permitJoin()         Let the freebird allow devices to join the network.
• remove()             Remove a remote device from the network.
• ban()                   Ban a device from the network.
• unban()               Unban a device.
• ping()                  Ping a remote device.
• maintain()           Maintain the machine network.

Remote Device Operation

• Device Class

Remote Gadget Operation

• Gadget Class

---

new Freebird(netcores[, options])

Create a server instance of the Freebird class. This document will use freebird to denote the server.

Arguments:

1. netcores (Array): An array of netcores to register to the freebird server, where each element in the array must be an instance of the Netcore class. Currently, there are ready-made netcores of BLE, ZigBee, CoAP, MQTT offered by this project. You can create your own netcore to work with freebird as well.
2. options (Object): An optional configuration. This is reserved for future use.

Returns:

• (Object): freebird

Examples:

var Freebird = require('freebird'),
    bleCore = require('freebird-netcore-ble')(),
    mqttCore = require('freebird-netcore-mqtt')(),
    coapCore = require('freebird-netcore-coap')(),
    zigbeeCore = require('freebird-netcore-zigbee')();

var freebird = new Freebird([ bleCore, mqttCore, coapCore, zigbeeCore ]);

---

.findById(type, id)

Find a netcore by name, or find a device/gadget by id. If you like to find a device/gadget by address, please use .findByNet().

Arguments:

1. type (String): Only accepts 'netcore', 'device', or 'gadget' to find a netcore, a device, or a gadget, respectively.
2. id (String | Number): id is the netcore name when finding for a netcore. id is a number when finding for a device or a gadget.

Returns:

• (Object): Found component, otherwise undefined

Examples:

// find netcore by name
freebird.findById('netcore', 'foo_netcore');        // netcore instance
freebird.findById('netcore', 'no_such_netcore');    // undefined (netcore not found)

// find device by id
freebird.findById('device', 88);    // device instance
freebird.findById('device', 999);   // undefined (device not found)

// find gadget by id
freebird.findById('gadget', 120);   // gadget instance
freebird.findById('gadget', 777);   // undefined (gadget not found)

---

.findByNet(type, ncName[, permAddr[, auxId]])

Find a netcore, a device, or a gadget by network parameters.

• To find a netcore: findByNet('netcore', ncName)
• To find a device: findByNet('device', ncName, permAddr)
• To find a gadget: findByNet('gadget', ncName, permAddr, auxId)

Arguments:

1. type (String): Only accepts 'netcore', 'device', or 'gadget' to find a netcore, a device, or a gadget, respectively.
2. ncName (String): Netcore name.
3. permAddr (String): Device permanent address which is required when finding for a device or a gadget.
4. auxId (String | Number): Gadget auxiliary id which is required when finding for a gadget.

Returns:

• (Object): Found component, otherwise undefined

Examples:

// find netcore by name
freebird.findByNet('netcore', 'foo_netcore');       // netcore instance
freebird.findByNet('netcore', 'no_such_netcore');   // undefined (netcore not found)

// find device by its network info
freebird.findByNet('device', 'foo_netcore', '00:0c:29:3e:1b:d2');       // device instance
freebird.findByNet('device', 'no_such_netcore', '00:0c:29:3e:1b:d2');   // undefined (not found)
freebird.findByNet('device', 'foo_netcore', '00:00:00:00:00:00');       // undefined (not found)

// find gadget by its network info
freebird.findByNet('gadget', 'foo_netcore', '00:0c:29:3e:1b:d2', 'humidity/2');     // gadget instance
freebird.findByNet('gadget', 'no_such_netcore', '00:0c:29:3e:1b:d2', 'humidity/2'); // undefined (not found)
freebird.findByNet('gadget', 'foo_netcore', '00:00:00:00:00:00', 'humidity/2');     // undefined (not found)
freebird.findByNet('gadget', 'foo_netcore', '00:0c:29:3e:1b:d2', 'no_such_auxId');  // undefined (not found)

---

.filter(type, pred)

This method returns an array of netcores, devices, or gadgets which contains all elements of pred returns truthy for.

Arguments:

1. type (String): Only accepts 'netcore', 'device', or 'gadget' to find netcores, devices, or gadgets that meet the prediction, respectively.
2. pred (Function): function (obj) {}, the function invoked per iteration in a netcores, devices, or gadget collection.

Returns:

• (Array): Returns the new filtered array of components

Examples:

// filter for enabled netcores
freebird.filter('netcore', function (nc) {
    return nc.isEnabled();
});

// filter for enabled devices
freebird.filter('device', function (dev) {
    return dev.isEnabled();
});

// filter for enabled gadgets
freebird.filter('gadget', function (gad) {
    return gad.isEnabled();
});

---

.addTransport(transp[, callback])

Add a transportation of RPC messaging to freebird. This project also provides a ready-made websocket transportation freebird-rpc for remote client/server communication. The following example shows how to use it with freebird.

Arguments:

1. transp (Object): The instance of transportation.
2. callback (Function): function (err) {}.

Returns:

• none

Examples:

var fbRpc = require('freebird-rpc'),
    http = require('http'),
    httpServer,
    rpcServer;

// create the websocket server
httpServer = http.createServer();
httpServer.listen(3000);

rpcServer = fbRpc.createServer(httpServer);

// register it to freebird
freebird.addTransport(rpcServer, function (err) {
    if (err)
        console.log(err);
});

---

.start([callback])

Start the freebird server.

Arguments:

1. callback (Function): function (err) {}. Get called after started.

Returns:

• none

Examples:

freebird.start(function (err) {
    if (!err)
        console.log('freebird is up');
    else
        console.log(err);
});

---

.stop([callback])

Stop the freebird server.

Arguments:

1. callback (Function): function (err) {}. Get called after stopped.

Returns:

• none

Examples:

nc.stop(function (err) {
    if (!err)
        console.log('freebird is down');
    else
        console.log(err);
});

---

.reset(mode[, callback])

Reset the freebird server.

Arguments:

1. mode (Number): 0 for a soft reset and 1 for a hard reset.
2. callback (Function): function (err) {}. Get called after reset is applied. When freebird has restarted again, a 'ready' event will be fired.

Returns:

• none

Examples:

freebird.on('ready', function () {
    console.log('freebird is ready');
});

freebird.reset(0, function (err) {
    if (!err)
        console.log('freebird starts to run its reset procedure');
    else
        console.log(err);
});

---

.permitJoin(duration[, callback])

Let the freebird allow devices to join the network.

Arguments:

1. duration (Number): Duration in seconds for allowing devices to join the network. Set it to 0 can immediately close the admission.
2. callback (Function): function (err, timeLeft) {}. Get called when freebird starts/stops to permit joining, where timeLeft is a number that indicates time left for device joining in seconds, e.g., 180.

Returns:

• none

Examples:

freebird.permitJoin(180, function (err, timeLeft) {
    if (!err)
        console.log(timeLeft);  // 180
});

freebird.permitJoin(0, function (err, timeLeft) {
    if (!err)
        console.log(timeLeft);  // 0
});

---

.remove(ncName, permAddr, callback)

Remove a remote device from the network.

Arguments:

1. ncName (String): Netcore name.
2. permAddr (String): Permanent address of the device to remove.
3. callback (Function): function (err, permAddr) {}. Get called after device removed, where permAddr is permananet address of that device.

Returns:

• none

Examples:

freebird.remove('mqtt-core', '00:0c:29:ff:ed:7c', function (err, permAddr) {
    if (!err)
        console.log(permAddr);  // 00:0c:29:ff:ed:7c
});

---

.ban(ncName, permAddr, callback)

Ban a device from the network. Once a device is banned, it can never join the network unless you unban it.

Arguments:

1. ncName (String): Netcore name.
2. permAddr (String): Permanent address of the device to ban.
3. callback (Function): function (err, permAddr) {}. Get called after device banned, where permAddr is permananet address of that device.

Returns:

• none

Examples:

freebird.ban('mqtt-core', '00:0c:29:ff:ed:7c', function (err, permAddr) {
    if (!err)
        console.log(permAddr);  // 00:0c:29:ff:ed:7c
});

---

.unban(ncName, permAddr, callback)

Unban a device.

Arguments:

1. ncName (String): Netcore name.
2. permAddr (String): Permanent address of the device to ban.
3. callback (Function): function (err, permAddr) {}. Get called after device unbanned, where permAddr is permananet address of that device.

Returns:

• none

Examples:

freebird.unban('mqtt-core', '00:0c:29:ff:ed:7c', function (err, permAddr) {
    if (!err)
        console.log(permAddr);  // 00:0c:29:ff:ed:7c
});

---

.ping(ncName, permAddr, callback)

Ping a remote device.

Arguments:

1. ncName (String): Netcore name.
2. permAddr (String): Permanent address of the device to ping.
3. callback (Function): function (err, time) {}. Get called after ping response comes back, where time is the round-trip time in milliseconds, e.g., 16.

Returns:

• none

Examples:

freebird.ping('mqtt-core', '00:0c:29:ff:ed:7c', function (err, time) {
    if (!err)
        console.log(time);  // 42
});

---

.maintain([ncName,][callback])

Maintain the machine network. This will re-sync the remote devices and gadgets.

Arguments:

1. ncName (String): Optional. If ncName is given, only the corresponding sub-network controlled by the netcore will be maintained. If ncName is not given, all sub-networks will be maintained.
2. callback (Function): function (err) {}. Optional. Get called after maintenannce starts.

Returns:

• none

Examples:

freebird.maintain('mqtt-core', function (err) {
    if (!err)
        console.log('Starts to maintaining the MQTT machine network');
});

freebird.maintain();    // Maintain all ub-networks