Home

1. Overview

This module is a transportation with WebSocket protocol, which is used by the RPC interface of freebird framework. It provides methods to create RPC client and RPC server for real-time remote communications. The RPC server should be registered to freebird framework to be able to transmit freebird messages to RPC client (e.g., the web browser). And the RPC client is provided for webapp to be able to communicate with freebird.

Subsystems

The freebird framework has net, dev, and gad subsystems responsible for network, device, and gadget management, respectively. In brief, a network is formed with many devices, and each device may have some gadgets on it. A gadget is the real application in a manchine network.

Example

Let's take a wifi weather station in a machine network for example. The weather station is made up of temperature, humidity, and pm2.5 sensors, where each sensor is a gadget living on the WiFi-connected device. A device, such as Arduino(wifi-connected), ESP8266, MT7688, RaspberryPi or Beaglebone, is the carrier of applications(gadgets). Now we know, this weather station has 3 gadgets on it, but only has a single device in it.

Here is another example, we have a bluetooth low-energy (BLE) light switch in the network. This is a simple one-device-with-one-gadget machine, here we can say "There is only one gadget - a light switch - implemented on a TI CC2540 BLE SoC device."

Why subsystems?

The concept of net, dev, and gad subsystems in freebird framework well separates the machine management and application management from each other. This brings developers a more clear, convenient and flexible way in building up a IoT machine network.

2. Installation

$ npm install freebird-rpc --save

3. Usage

freebird-rpc exports its functionalities as a object, which contains two methods, createServer() and createClient().

• Create a RPC server

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

var httpServer = http.createServer();
httpServer.listen(3000);

var rpcServer = fbRpc.createServer(httpServer);

• Create a RPC client

var fbRpc = require('freebird-rpc');

var rpcClient = fbRpc.createClient('ws://192.168.1.108:3000');

4. APIs and Events

.createServer(httpServer)

Create the RPC server with a WebSocket server.

Arguments:

1. httpServer (Object): A Node.js HTTP server.

Returns:

• (Object): rpcServer

Example:

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

var httpServer,
    rpcServer;

httpServer = http.createServer().listen(3000);
rpcServer = fbRpc.createServer(httpServer);

---

.createClient(addr[, options])

Create the RPC client with a WebSocket client.

Arguments:

1. addr (String): host address
2. options (Object): An object to set up the websocket client. Please refer to ws.md to see more detail about options.

Returns:

• (Objects): rpcClient

Example:

var rpcClient = fbRpc.createClient('ws://192.168.1.108:3000');

---

Server Class

fbRpc.createServer() returns an instance of this class. The instance, which is denoted as rpcServer in this document, and cotains a WebSocket server to do real-time bidirectional with WebSocket client.

---

.send(msg, callback)

Send the response message to Websocket client with the results of the client asking for.

Arguments:

1. msg (Object): msg must contains clientId and data properties. clientId is used to identify the client you want to send message to, and data is the message to transmit out which must follow Response Data Object and should be converts to a JSON string.
2. callback (Function): function (err, bytes) { ... }. Get called after message send off. The argument bytes tells how many bytes were sent.

Returns:

• (None)

Example:

var sendData = {
    __intf: 'RSP',
    subsys: 'net',
    seq: 5,
    id: null,
    cmd: 'getAllDevIds',
    status: 0,
    data: { ids: [ 1, 2, 3, 8, 12 ] }
};

sendData = JSON.stringify(sendData);

rpcServer.send({ clientId: 'client01', data: sendData }, function (err, bytes) {
    if (err)
        console.log(err);
    else
        console.log(bytes + ' bytes were sent');
});

---

.broadcast(msg, callback)

Broadcast the indication message to all WebSocket clients.

Arguments:

1. msg (Object): msg must contains data property. data is the message to transmit out which must follow Indication Data Object and should be converts to a JSON string.
2. callback (Function): function (err, bytes) { ... }. Get called after message send off. The argument bytes tells how many bytes were sent.

Returns:

• (None)

Example:

var broadcastData = {
    __intf: 'IND',
    subsys: 'net',
    type: 'started',
    id: null,
    data: { netcore: 'freebird-netcore-ble' }
};

broadcastData = JSON.stringify(broadcastData);

rpcServer.broadcast({ data: broadcastData }, function (err, bytes) {
    if (err)
        console.log(err);
    else
        console.log(bytes + ' bytes were sent');
});

---

.on('message', function (msg) {})

The user can listen to the 'message' event to receive the request message from WebSocket client.

Arguments of the listener

1. msg (Object): msg contains clientId and data properties. clientId is to help the user determine which client sends the message, and data is the received message which will follow Request Data Object and be converted to a JSON string.

Example:

rpcServer.on('message', function (msg) {
    console.log(msg.data.toString());
});

---

Client Class

fbRpc.createClient() returns an instance of this class. The instance, which is denoted as rpcClient in this document, and cotains a WebSocket client to do real-time bidirectional with WebSocket server.

---

.send(subsys, cmd, args, callback)

Send the request message to Websocket server to request something or to ask the server to perform an operation.

Arguments:

1. subSys (String): Only 3 types accepted. They are 'net', 'dev', and 'gad' to denote which subsystem is this message going to.
2. cmd (String): Command Identifier corresponding to the API name. It can be found in the Command Name field of the Request Data Model.
3. args (Object): A value-object that contains command arguments. Please see section Request Data Model to learn more about the args data object.
4. callback (Function): function (err, result) {}. Get called when server respond to client with the results of the client asking for.
   • 'err' (Error): Error object.
   • 'result' (Object): result is an object of { status, data }. status is corresponding to RSP Status Code. data is a response data object, you can refer to Response Data Model to see more detail.

Returns:

• (None)

Example:

rpcClient.send('net', 'getAllDevIds', { ncName: 'freebird-netcore-ble' }, function (err, result) {
    if (err) {
        console.log(err);
    } else {
        console.log(result);

        // result equal to 
        // {
        //     status: 0,
        //     data: {
        //         ids: [1, 5, 8, 15, 27]
        //     }
        // }
    }    
});

---

.on('open', function () {})

Emitted when the connection is open and ready to communicate.

Arguments of the listener

• (None)

Example:

rpcClient.on('open', function () {
    // You can communicate to RPC server
});

---

.on('close', function (code, reason) {})

Emitted when the connection is closed.

Arguments of the listener

1. code (Number): code is a numeric value indicating the status code explaining why the connection has been closed.
2. reason (String): reason is a human-readable string explaining why the connection has been closed.

Example:

rpcClient.on('close', function (code, reason) {
    console.log('Connection is closed because the reason: ' + reason);
});

---

.on('ind', function (msg) {})

Emitted when receiving an indication from websocket server side.

Arguments of the listener

1. msg (Object): It is a message object with properties 'subsys', 'type', 'id' and 'data'
   • subsys (String): They are 'net', 'dev', and 'gad' to denote which subsystem is this indication coming from.
   • type (String): Indication types. Please see section Indication types for details.
   • id (Number): Id of the sender. id is meaningless if subsys === 'net'. id is device id if subsys === 'dev'. id is gadget id if subsys === 'gad'
   • data (Object): Data along with the indication. Please see section Indication Data Model to learn more about the indication data format.

Example:

rpcClient.on('ind', function (msg) {
    console.log(msg);
});