Devicehive-plugin-core NPM

DeviceHive plugin core functionality (Node JS implementation)

This module makes it possible to quickly and easily create DeviceHive plugins using NodeJS.

Module structure

PluginCore class (private)

PluginCore class implements basic interaction functionality with DeviceHive service. User is not able to use it.

ProxyClient class (private)

ProxyClient class implements basic transport functionality with DeviceHive WS Proxy service (in plugin mode). User is not able to use it.

DeviceHivePlugin class (public)

DeviceHivePlugin class implements interface for user's plugin service classes. User is able to extends their own plugin services from the DeviceHivePlugin class.

    const { DeviceHivePlugin } = require(`devicehive-plugin-core`);

    class PluginService extends DeviceHivePlugin {
        beforeStart() {}
        afterStart() {}
        handleMessage(message) {}
        beforeStop() {}
        onError(error) {}
    }

Plugin lifecycle hooks

beforeStart() {}
afterStart() {
handleMessage(message) {}
beforeStop() {}
onError(error) {}

1) beforeStart - This hook fires before plugin will do try to connect to DeviceHive WS plugin server 2) afterStart - This hook fires after plugin successfully connects to DeviceHive WS plugin server 3) handleMessage - This hook fires on every incoming Message from DeviceHive 4) beforeStop - This hook fires before plugin will stop it's own process because of some critical reason (For example, WS plugin serer closes the connection) 5) onError - This hook fires on every internal error (critical/non critical)

Plugin API

DeviceHivePlugin class has few methods that are defined internally by core functionality:

sendMessage(message) {}
subscribe(subscriptionGroup) {}
unsubscribe() {}

1) sendMessage - Sends Message object to WS plugin server. Returns Promise with response/error 2) subscribe - Subscribes to plugin topic with optionally mentioned subscription group 3) unsubscribe - Unsubscribes from plugin topic

Plugin entry point

To start plugin you should use next static method of DeviceHivePlugin class:

DeviceHivePlugin.start(<pluginService>, <config>, [<envPrefix>]);

where:

pluginService - instance of User's own DeviceHivePlugin implementation
config - configuration object or path to configuration json file. See Configuration section
envPrefix - prefix to add to environmental variables to override configuration fields

Example:

    const { DeviceHivePlugin } = require(`devicehive-plugin-core`);

    class PluginService extends DeviceHivePlugin {
        beforeStart() {}
        afterStart() {}
        handleMessage(message) {}
        beforeStop() {}
        onError(error) {}
    }
    
    DeviceHivePlugin.start(new PluginService(), {
         DEVICE_HIVE_PLUGIN_WS_ENDPOINT: "ws://localhost:3001",
         DEVICE_HIVE_AUTH_SERVICE_API_URL: "http://localhost:8090/dh/rest",
         PLUGIN_ACCESS_TOKEN: "plugin_access_token",
         AUTO_SUBSCRIPTION_ON_START: true
    }, "MY_PLUGIN_SERVICE");

Configuration

DEVICE_HIVE_PLUGIN_WS_ENDPOINT - Path to DeviceHive WS server with plugin support
DEVICE_HIVE_AUTH_SERVICE_API_URL - Path to DeviceHive Auth REST API service
PLUGIN_TOPIC - Plugin topic
PLUGIN_TOKEN_LIFE_TIME_MIN - Plugin topic lifetime in minutes. Optional parameter
USER_LOGIN - User login (plugin owner ar administrator). Optional parameter
USER_PASSWORD - User password (plugin owner ar administrator). Optional parameter
USER_ACCESS_TOKEN - User access token (plugin owner ar administrator). Optional parameter
USER_REFRESH_TOKEN - User refresh token (plugin owner ar administrator). Optional parameter
PLUGIN_ACCESS_TOKEN - Plugin access token. Optional parameter
PLUGIN_REFRESH_TOKEN - Plugin refresh token. Optional parameter
AUTO_SUBSCRIPTION_ON_START - Flag to on/off auto subscription to plugin topic on plugin start

Each configuration field can be overridden with corresponding environmental variable with "PLUGIN" prefix, for example:

PLUGIN.PLUGIN_TOKEN_LIFE_TIME_MIN=60

Prefix separator can be overridden by ENVSEPARATOR environmental variable. Example:

ENVSEPARATOR=_
PLUGIN_PLUGIN_TOKEN_LIFE_TIME_MIN=60

For plugin authentication next configuration combinations can bu used:

1) PLUGIN_ACCESS_TOKEN
2) PLUGIN_REFRESH_TOKEN 3) USER_ACCESS_TOKEN + PLUGIN_TOPIC + DEVICE_HIVE_AUTH_SERVICE_API_URL 4) USER_REFRESH_TOKEN + PLUGIN_TOPIC + DEVICE_HIVE_AUTH_SERVICE_API_URL 5) USER_LOGIN + USER_PASSWORD + PLUGIN_TOPIC + DEVICE_HIVE_AUTH_SERVICE_API_URL