APIs and Events

freebird-rpc exports its functionalities with two methods createServer() and createClient() to create a RPC server and a client, respectively. The Server class is used by the freebird framework, and the Client class is for app developers.

Client and Server Creation

API	Description
createClient()	Create the websocket RPC client.
createServer()	Create the websocket RPC server on top of a http server.

Client Class

API and Event	Description
send()	Send request to the freefird server.
'open'	Fires when the connection is open and ready for communication.
'close'	Fires when the connection is closed.
'ind'	Fires when an indication received from the freefird server.

Server Class

API and Event	Description
send()	Send response to the client with results of the client asking for.
broadcast()	Broadcast the indication message to all clients.
'message'	Triggered when the server receives a request from the client.

---

.createClient(addr[, options])

Create the websocket RPC client.

Arguments:

1. addr (String): host address and port.
2. options (Object): An optional object to set up the websocket client. Please refer to websocket official ws.md for more details about this options.

Returns:

• (Object): rpcClient

Example:

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

---

.createServer(httpServer)

Create the websocket RPC server on top of a http server.

Arguments:

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

Returns:

• (Object): rpcServer

Example:

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

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

---

Client Class

fbRpc.createClient() returns an instance of the Client class. The instance, which is denoted as rpcClient in this document, is essentially a WebSocket client for real-time bidirectional communications with WebSocket servers.

---

.send(subsys, cmd, args, callback)

Send the request message to the server for requesting something or asking the server to perform an operation.

Arguments:

1. subSys (String): Only 3 types are accepted. They are 'net', 'dev', and 'gad' to denote which subsystem is this message referring to.
2. cmd (String): Command identifier, which is simply the API name that can be found in the _Command Name_ column of the Request Data Model, i.e. 'getAllDevIds', 'getDevs', 'permitJoin'.
3. args (Object): A value-object as the argument for a command. The corresponding argument for each command is listed in the **Arguments** column of Request Data Model.
4. callback (Function): function (err, result) {}. Get called when the server respond to this client.
   • 'err' (Error): Error object.
   • 'result' (Object): result is an object of { status, data }, where status is a code defined by RSP Status Code and data is a response object shaped with the Response Data Model format.

Returns:

• (None)

Example:

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

        // result is 
        // {
        //     status: 205,
        //     data: {
        //         ids: [ 1, 5, 8, 15, 27 ]
        //     }
        // }
    }    
});

---

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

Fires when the connection is open and ready for communication.

Arguments of the listener

• (None)

Example:

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

---

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

Fires when the connection is closed.

Arguments of the listener

1. code (Number): code is a numeric value to indicate 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) {})

Fires when an indication received from the server.

Arguments of the listener

1. msg (Object): A message object with fields 'subsys', 'type', 'id' and 'data'
   • subsys (String): Can be 'net', 'dev', or '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 refers to device id if subsys === 'dev'.
     • id refers to 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);
});

---

Server Class

fbRpc.createServer() returns an instance of the Server class. The instance, which is denoted as rpcServer in this document, is essentially a WebSocket server for real-time bidirectional communications with WebSocket clients.

---

.send(msg, callback)

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

Arguments:

1. msg (Object): msg must at least have clientId and data fields, where clientId is used to identify the client you want to send the message to, and data is the message to transmit out. data must be an object shaped with Response Message format, and it must be serialized to a JSON string when transmitting.
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: 205,
    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 clients.

Arguments:

1. msg (Object): msg must has the data field. data is the message to transmit out which must be shaped with Indication Message format, and it must be serialized to a JSON string when transmitting.
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 'message' event is triggered when the server receives a request from the client.

Arguments of the listener

1. msg (Object): msg contains clientId and data properties. clientId is to help the freebird determine which client sends the message, and data is the received message which is the serialized JSON string of Request Data Object.

Example:

rpcServer.on('message', function (msg) {
    console.log(msg.data);  // a JSON string

    msg.data = JSON.parse(msg.data);    // parse to an object
});