Overview

The Channel Plugin API enables developers to create plugins that acts as a server/endpoint for outbound data and also for receiving commands for target devices or groups. Software applications can subscribe to a Channel plugin to receive real-time data from devices and also communicate with their devices to issue commands. This article aims to provide detailed information on the APIs available for Channel Plugins and how to build one.

Starting a Node.js Channel Plugin Project

To easily create a plugin project scaffolding for Channel plugins, Reekoh has provided a generator tool which can be used like:

cd path/to/your/project-folder

yo reekoh-node:channel

Building the Plugin

The file named app.js is where everything starts. To use the Channel Plugin API, one starts by creating a Channel instance as seen on the scaffolding's app.js file.

app.js

'use strict'

const reekoh = require('reekoh')
const plugin = new reekoh.plugins.Channel()

plugin is now an instance of a Channel with the necessary properties, methods, and events for creating a Channel plugin. Details of the Channel instance' properties, methods and events are specified in the following sections.

Properties

Specified below are the properties of a Channel which are injected for use in your plugin.

• port {number} - The port where the Channel plugin must listen to for incoming connections and data
• config {object} - The custom plugin configuration values as requested from and specified by the end user. For more about plugin configurations, please see the Packaging & Submission section.
• rootCrl {string} - The Root Certificate Revocation List (CRL) in PEM format which can be used by the Channel plugin for security. Can be null or undefined if certificate security has not been set by the user.
• ca {string} - The Root Certificate Authority (CA) in PEM format which can be used by the Channel plugin for security. Can be null or undefined if certificate security has not been set by the user.
• crl {string} - The Certificate Revocation List (CRL) in PEM format which can be used by the Channel plugin for security. Can be null or undefined if certificate security has not been set by the user.
• key {string} - The Private Key in PEM format which can be used by the Channel plugin for security. Can be null or undefined if certificate security has not been set by the user.
• cert {string} - The Certificate in PEM format which can be used by the Channel plugin for security. Can be null or undefined if certificate security has not been set by the user.

Events

Specified below are the events that a Channel instance is able to emit based upon operations that are happening on the platform pipelines.

'ready'

This event is emitted when the Channel instance has fully initialised. This is usually the event where one listens to and puts the code to create a server to accept connections and send data outbound.

Sample Code

let server

plugin.on('ready', () => {
  server = createServer()

  server.listen(plugin.port, () => {
    plugin.log(`Server is now listening on port ${plugin.port}`)
  })
})

 'data'

This event is emitted when device/sensor data is received from the platform. This is the event to listen to in order to get real-time data feed from the connected devices and publish the data to connected clients.

Arguments

• data {object} - the data received from the pipeline. Can be raw device/sensor data but can be processed data too depending on how the user has designed the pipeline.

Sample Code

plugin.on('data', data => {
  client.publish('data', JSON.stringify(data))
})

Methods

Specified below are Channel API methods that you can use for your plugin to relay information and initiate operations on the platform.

relayCommand(command, targetDevices, targetDeviceGroups, [source])

Invoke this method to send a command or message to target device/s or device group/s. The platform will process the command/message and relay it to the appropriate device/s via the Command Relay where the Channel is attached.

Arguments

• command {string} - The command/message to send.
• targetDevices {string | [string]} - A device id or an array of device ids to where the command must be sent to. Can be blank only if targetDeviceGroups has value.
• targetDeviceGroups - {string | [string]} - A device group id or an array of device group ids to where the command must be sent to. Can be blank only if targetDevices has value.
• source {string} - Optional The source of the command. Can be the device id where the command originated from.

Returns

• Promise - which is fulfilled when the command/message has been relayed to the target device/s or device group/s.

Sample Code

server.on('commandTopic', commandDetails => {
  plugin
    .relayCommand(commandDetails.command, commandDetails.targetDevices, commandDetails.targetDeviceGroups)
    .then(() => {
      plugin.log('Command Sent')
    })
    .catch(err => {
      plugin.logException(err)
    })
})

setState(state)

Invoke this method to set the plugin's state. State can be used to store additional information or metadata for the plugin. It can also be used as cache for any information that needs to be stored temporarily.

Arguments

• state {any} - state to be stored. Can be anything - object, array, string, number etc.

Returns

• Promise - which is fulfilled when the state has been submitted for storage.

Sample Code

let server

plugin.on('ready', () => {
  server = createServer()

  server.listen(plugin.port, () => {
    plugin.log(`Server is now listening on port ${plugin.port}`)
  })

    plugin.setState({
    config: plugin.config,
    otherMetadata: {
      initialised: true
    }
  })
})

getState()

Invoke this method to retrieve the contents of the plugin state. 

Returns

• Promise (state {any}) - resolves or returns the contents of the plugin's state.

Sample Code

let client

plugin.on('data', data => {
  plugin.getState().then(state => {
    console.log(state)
  })
})

log(logData)

Invoke this function to log any information. Can be useful for debugging. Logs are found under the Logs module or in each plugin instance in the Pipeline Studio.

Arguments

• logData {string | object} - The information to be logged.

Returns

• Promise - fulfilled when the log data has been submitted to the platform for recording.

Sample Code

plugin.on('data', data => {
  server.publish('data', data)
    .then(() => {
      plugin.log('Data published')
      plugin.log(data)
    })
    .catch(err => {
      plugin.logException(err)
    })
})

logException(err)

Invoke this function to log errors/exceptions. Can be useful for debugging. Error/exception logs are found under the Logs module or in each plugin instance in the Pipeline Studio. 

Arguments

• err {error} - The error to be logged.

Returns

• Promise - fulfilled when the error data has been submitted to the platform for recording.

Sample Code

plugin.on('data', data => {
  server.publish('data', data)
    .then(() => {
      plugin.log('Data published')
      plugin.log(data)
    })
    .catch(err => {
      plugin.logException(err)
    })
})

Reference Implementations

Listed below are some reference implementations of the Channel Plugin API.

• Websocket Channel

These are just some of the Channel Plugins developed and open-sourced by Reekoh. You may visit our Gitlab Page for more information. Contributions are most welcome.