ibmiotf

Node.js Client Library

The node.js client is used for simplifying the interacting with the Internet of Things Foundation. The following libraries contain instructions and guidance on using the nodejs ibmiotf node to interact with devices and applications within your organizations.

This client library is divided into two parts, Device and Application. The Devices section contains information on how devices publish events and handle commands using the nodejs ibmiotf module, and the Applications section contains information on how applications can use the nodejs ibmiotf module to interact with devices.

Devices

IotfDevice is device client for the Internet of Things Foundation service. You can use this client to connect to the service, publish events from the device and subscribe to commands.

Constructor

The constructor builds the device client instance. It accepts an configuration json containing the following :

• org - Your organization ID
• type - The type of your device
• id - The ID of your device
• auth-method - Method of authentication (the only value currently supported is “token”)
• auth-token - API key token (required if auth-method is “token”)

If you want to use quickstart, then send only the first three properties.

var Client = require("ibmiotf").IotfDevice;
var config = {
    "org" : "organization",
    "id" : "deviceId",
    "type" : "deviceType",
    "auth-method" : "token",
    "auth-token" : "authToken"
};

var deviceClient = new Client(config);

....

Using a configuration file

Instead of passing the configuration json directly, you can also use a configuration file. Use the following code snippet

var Client = require("ibmiotf").IotfDevice;

var config = Client.parseConfigFile(configFilePath);    
var deviceClient = new Client(config);

....

The configuration file must be in the format of

org=$orgId
type=$myDeviceType
id=$myDeviceId
auth-method=token
auth-token=$token

Connect

Connect to the Internet of Things Foundation by calling the connect function

var Client = require("ibmiotf").IotfDevice;

var config = Client.parseConfigFile(configFilePath);    
var deviceClient = new Client(config);

deviceClient.connect();

deviceClient.on("connect", function () {

//Add your code here
});

....

After the successful connection to the IoTF service, the device client emits connect event. So all the device logic can be implemented inside this callback function.

Publishing events

Events are the mechanism by which devices publish data to the Internet of Things Foundation. The device controls the content of the event and assigns a name for each event it sends.

When an event is received by the IOT Foundation the credentials of the connection on which the event was received are used to determine from which device the event was sent. With this architecture it is impossible for a device to impersonate another device.

Events can be published at any of the three quality of service levels defined by the MQTT protocol. By default events will be published as qos level 0.

Events can be published by using

• eventType - Type of event to be published e.g status, gps
• eventFormat - Format of the event e.g json
• data - Payload of the event
• QoS - qos for the publish event. Supported values : 0,1,2

var config = IotfDevice.ParseConfigFile(configFilePath);    
var client = new IotfDevice(config);

client.connect();

client.on("connect", function () {
    //publishing event using the default quality of service
    client.publish("status","json",'{"d" : { "cpu" : 60, "mem" : 50 }}');

    //publishing event using the user-defined quality of service
    var myQosLevel=2
    client.publish("status","json",'{"d" : { "cpu" : 60, "mem" : 50 }}', myQosLevel); 
});

....

Handling commands

When the device client connects, it automatically subscribes to any command for this device. To process specific commands you need to register a command callback function. The device client emits command when a command is received. The callback function has the following properties

• commandName - name of the command invoked
• format - e.g json, xml
• payload - payload for the command
• topic - actual topic where the command was received

var config = IotfDevice.ParseConfigFile(configFilePath);    
var client = new IotfDevice(config);

client.connect();

client.on("connect", function () {
    //publishing event using the default quality of service
    client.publish("status","json",'{"d" : { "cpu" : 60, "mem" : 50 }}');

});

client.on("command", function (commandName,format,payload,topic) {
    if(commandName === "blink") {
        console.log(blink);
        //function to be performed for this command
        blink(payload);
    } else {
        console.log("Command not supported.. " + commandName);
    }
});
.... 

Disconnect Client

Disconnects the client and releases the connections

var config = IotfDevice.ParseConfigFile(configFilePath);    
var client = new IotfDevice(config);

client.connect();

client.on("connect", function () {
    //publishing event using the default quality of service
    client.publish("status","json",'{"d" : { "cpu" : 60, "mem" : 50 }}');

    //publishing event using the user-defined quality of service
    var myQosLevel=2
    client.publish("status","json",'{"d" : { "cpu" : 60, "mem" : 50 }}', myQosLevel); 

    //disconnect the client
    client.disconnect();
});

....

Check Connection Status

isConnected gives the current status of the client connection

//publishing event using the default quality of service
if(client.isConnected) {
    client.publish("status","json",'{"d" : { "cpu" : 60, "mem" : 50 }}');
}


....

Application

IotfApplication is application client for the Internet of Things Foundation service. This section contains information on how applications interact with devices.

Constructor

The constructor builds the application client instance. It accepts an configuration json containing the following :

• org - Your organization ID
• id - The unique ID of your application within your organization.
• auth-key - API key
• auth-token - API key token

If you want to use quickstart, then send only the first two properties.

var Client = require("ibmiotf").IotfApplication;
var config = {
    "org" : orgId,
    "id" : appId,
    "auth-key" : apiKey,
    "auth-token" : apiToken
}

var appClient = new Client(config);

....

Using a configuration file

Instead of passing the configuration json directly, you can also use a configuration file. Use the following code snippet

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

....

The configuration file must be in the format of

org=$orgId
id=$myUniqueIs
auth-key=$apiKey
auth-token=$token

Connect

Connect to the Internet of Things Foundation by calling the connect function

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

appClient.connect();

appClient.on("connect", function () {

//Add your code here
});

....

After the successful connection to the IoTF service, the application client emits connect event. So all the logic can be implemented inside this callback function.

Subscribing to device events

Events are the mechanism by which devices publish data to the Internet of Things Foundation. The device controls the content of the event and assigns a name for each event it sends.

When an event is received by the IOT Foundation the credentials of the connection on which the event was received are used to determine from which device the event was sent. With this architecture it is impossible for a device to impersonate another device.

By default, applications will subscribe to all events from all connected devices. Use the type, id, event and msgFormat parameters to control the scope of the subscription. A single client can support multiple subscriptions. The code samples below give examples of how to subscribe to devices dependent on device type, id, event and msgFormat parameters.

To subscribe to all events from all devices

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

appClient.connect();

appClient.on("connect", function () {

    appClient.subscribeToDeviceEvents();
});

....

To subscribe to all events from all devices of a specific type

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

appClient.connect();

appClient.on("connect", function () {

    appClient.subscribeToDeviceEvents("mydeviceType");
});

....

To subscribe to a specific event from all devices

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

appClient.connect();

appClient.on("connect", function () {

    appClient.subscribeToDeviceEvents("+","+","myevent");
});

....

To subscribe to a specific event from two or more different devices

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

appClient.connect();

appClient.on("connect", function () {

    appClient.subscribeToDeviceEvents("myDeviceType","device01","myevent");
    appClient.subscribeToDeviceEvents("myOtherDeviceType","device02","myevent");
});

....

To subscribe to all events published by a device in json format

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

appClient.connect();

appClient.on("connect", function () {

    appClient.subscribeToDeviceEvents("myDeviceType","device01","+","json");

});

....

Handling events from devices

To process the events received by your subscriptions you need to implement an device event callback method. The ibmiotf application client emits the event deviceEvent. This function has the following properties

• deviceType
• deviceId
• eventType
• format
• payload - Device event payload
• topic - Original topic

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

appClient.connect();

appClient.on("connect", function () {

    appClient.subscribeToDeviceEvents("myDeviceType","device01","+","json");

});
appClient.on("deviceEvent", function (deviceType, deviceId, eventType, format, payload) {

    console.log("Device Event from :: "+deviceType+" : "+deviceId+" of event "+eventType+" with payload : "+payload);

});

....

Subscribing to device status

By default, this will subscribe to status updates for all connected devices. Use the type and id parameters to control the scope of the subscription. A single client can support multiple subscriptions.

Subscribe to status updates for all devices

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

appClient.connect();

appClient.on("connect", function () {

    appClient.subscribeToDeviceStatus();

});

Subscribe to status updates for all devices of a specific type

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

appClient.connect();

appClient.on("connect", function () {

    appClient.subscribeToDeviceStatus("myDeviceType");

});

Subscribe to status updates for two different devices

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

appClient.connect();

appClient.on("connect", function () {

    appClient.subscribeToDeviceStatus("myDeviceType","device01");
    appClient.subscribeToDeviceStatus("myOtherDeviceType","device02");

});

Handling status updates from devices

To process the status updates received by your subscriptions you need to implement an device status callback method. The ibmiotf application client emits the event deviceStatus. This function has the following properties

• deviceType
• deviceId
• payload - Device status payload
• topic

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

appClient.connect();

appClient.on("connect", function () {

    appClient.subscribeToDeviceStatus("myDeviceType","device01");
    appClient.subscribeToDeviceStatus("myOtherDeviceType","device02");

});
appClient.on("deviceStatus", function (deviceType, deviceId, payload, topic) {

    console.log("Device status from :: "+deviceType+" : "+deviceId+" with payload : "+payload);

});

Publishing events from devices

Applications can publish events as if they originated from a Device. The function requires

• DeviceType
• Device ID
• Event Type
• Format
• Data

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

appClient.connect();

appClient.on("connect", function () {

    var myData={'name' : 'foo', 'cpu' : 60, 'mem' : 50}
    appClient.publishDeviceEvent("myDeviceType","device01", "myEvent", "json", myData);

});

Publishing commands to devices

Applications can publish commands to connected devices. The function requires

• DeviceType
• Device ID
• Command Type
• Format
• Data

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

appClient.connect();

appClient.on("connect", function () {

    var myData={'DelaySeconds' : 10}
    appClient.publishDeviceCommand("myDeviceType","device01", "reboot", "json", myData);

});

Disconnect Client

Disconnects the client and releases the connections

var Client = require("ibmiotf").IotfApplication;

var config = Client.parseConfigFile(configFilePath);    
var appClient = new Client(config);

appClient.connect();

appClient.on("connect", function () {

    var myData={'DelaySeconds' : 10}
    appClient.publishDeviceCommand("myDeviceType","device01", "reboot", "json", myData);

    appClient.disconnect();
});

Check Connection Status

isConnected gives the current status of the application client connection

if(client.isConnected) {
    ....
    ....
}