Difference between revisions of "How to implement a new plugin"

Latest revision as of 10:11, 14 June 2018

• Create a thing type XXXThing (See Thing types)
• Create the observations type the thing XXXThing produces or consumes, example XXXThingObserv1 (See Observations and observation types)
• Associate the observation XXXThingObserv1 type to the XXXThing
• Implement a nodejs module with the following interface

    function XXXThing() {
    }

    XXXThing.prototype.start = function ( complete) {
        try {
            complete(null);
        } catch (e) {
            complete(e);
        }
    };

    XXXThing.prototype.stop = function (complete) {
        try {
            complete(null);
        } catch (e) {
            complete(e);
        }
    };

    XXXThing.prototype.command = function (observation, complete) {
        try {
            complete(null);
        } catch (e) {
            complete(e);
        }
    };

    module.exports.XXXThing = XXXThing;

Smoothing observations

In order to allow the plugin to reduce the number of unnecessary observations, we propose a SmoothingHandler class. This class implements the smoothing process described here according to some given configurations.

The main advantages of using this class would be:

• New smoothing criteria could be included in the future according to the users needs.
• Smoothing process can be done in a device-wise manner allowing to handle several devices with the same plugin instance (e.g. with beacon scanners)
• It is possible to use several independent smoothing processes at the same time according to different models (for instance one model for ibeacons and one for eddystone ones)
• Possibility to know which fields satisfied their configured smoothing criteria

Using smoothing in the plugins

In order to include the smoothing tool we propose, the nodejs code should :

• Import the code of the smoothing handler
• Initialize the smoothing handler with the given configuration
• Free the memory used by the smoothing handler
• Verify each observation by the smoothing handler before send it

Import smoothing handler

To import the smoothing handler class include the code belo at the beginning of the nodejs file

const SmoothingHandler = require("../../common/smoothingHandler.js");

Initialize smoothing handler

The smoothing handlers should be initialized on the start function of the plugin with the smoothing configuration to use (see below).

this.smoothingHandler = new SmoothingHandler(smoothingConfig, this.logger, smoothingId);

where smoothingId is used only for logging purpose and smoothingConfig contains the smoothing configuration.

Free memory

To avoid issues upon restart of plugins and bridges, the smoothing memory should be freed on plugin stop function

this.smoothingHandler.destroy();
this.smoothingHandler=undefined;

Verify smoothing criteria

To verify if an observation satisfies or not the smoothing criteria use the smooth function of the smoothing handler, for instance:

if (this.smoothingHandler.smooth(deviceId, observationInfo)){
   this.sendObservation(...);
}

It is possible also to know which fields have satisfied the smoothing criteria by including a third parameter holding an array:

  var changedFields = [];
  var smoothingSatisfied=this.smoothingHandler.smooth(deviceId, observationInfo, changedFields));

Smoothing configuration

Managing observation delivery

There exist another tool called ObservationDeliveryMgr. This tool manage when the observations are sent. For instance, it can send the observations at a given frequency reducing the number of observations sent.

Using this class will allow, by instance configuration, to

• say if all the observations should be sent or if the observations should be stored so they are only sent with some time interval.

Other features could be added to this class making them available for each plugin

How to use it

The plugin code should :

• Import the code of the ObservationDeliveryMgr class
• Initialize the observation delivery manager with the given configuration
• Stop the observation delivery manager
• Post the observations to the delivery manager

Import ObservationDeliveryMgr class

 const ObservationDeliveryMgr = require("../../common/observationDeliveryMgr.js");

Initialize observation delivery manager

 var observationDeliveryMgr = new ObservationDeliveryMgr(config);
 observationDeliveryMgr.start(done)

where done is the callback to call when the start process is finished and config is an object with

 timeInterval: time interval to send observations. Set to 0 or undefined to send all observations
 sendFunction: function to call each time an observation should be sent
 logger: logger object

Stop observation delivery manager

 observationDeliveryMgr.stop(done)

when done is the callback to call when the manager has been stopped

Post observations delivery manager

Each time the plugin has an observation ready it should call the postObservation function

 observationDeliveryMgr.postObservation(id, observation, ph)

where observation is the observation object to be sent and ph is the list of placeholders

In this case, according to the given timeInterval, the manager will

timeInterval= undefined or 0

The sendFunction callback is called inmediately with the given observation and ph

timeInterval>0

The observation and ph are cached associated to the given id. If there was another observation, only the last will be kept for each id. Then the sendFunction will be called with the observation and ph cached for each id