Getting Started With Plugins

OCPPJS 1.0.0 introduces a new feature : the plugins. This document is here for helping developers to write plugins for the simulator. It also contains the API documentation.

Writing plugins allow yourself to define the behavior of the simulator without modifying the source code of the program. A plugin consists of one JavaScript file which can be loaded by the simulator.

API Documentation

Input/Output API

log("Plugin Started !");

parse('show cache'); 
        => {command: 'show', arguments: ['cache']};

Simulator API

cp.call('BootNotification');

cs.call('ClearCache');

Callback API

onResult('BootNotification', function(values)   {
  log('Heartbeat interval: '+ values.heartbeatInterval);
});
        

onCall('ClearCache', function(values) {
  // clear the cache
});
        

onConnectionEvent(function(type, cpId) {
  if(type == 'connected')
    log('Connected to Central System.');
  else if (type == 'disconnected')
    log('Disconnected to Central System.');
});
        

onClientConnectionEvent(function(type, cpId) {
  if(type == 'connected')
    log('Connected to Central System.');
  else if (type == 'disconnected')
    log('Disconnected to Central System.');
});
        

onCommand(function(command) {
  var commandObj = parse(command);

  if(commandObj.command == 'cache')
    log('Cache content:'+ cache);
});
        

onIdle(function(command) {
  // ...
});
        

A Plugin Example

First of all, the plugins need to be in the plugins/ folder which already contains some examples.

A primitive plugin template file looks like:

var myPlugin = {
  name: '',
  description: '',
  author: '',

  ocpp_version: '',
  system: '',

  onLoad: function() {

  }
};

export.modules = myPlugin;

Every plugin must have a onLoad function, this is the entry point, the function triggered right after loading the plugin. All the other fields are optional.

Within the framework of this document, we are going to build a charge point plugin which:

• Sends a BootNotification at start.
• Sets a result function for the BootNotification procedure.
• Calls a StartTransaction procedure when a RemoteStartTransaction is received.
• Displays a message when the connection is lost.
• Create a new "hello" command for introducing the plugin.

Calling a procedure

Right after loading our plugin, this one sends a BootNotification to the Central System.

var myPlugin = {
  name: 'My Plugin',
  description: 'Plugin example with the tutorial',
  author: 'myself',

  ocpp_version: '1.5',
  system: 'cs',

  onLoad: function() {
    var self = this;

    self.cp.call('BootNotification');
  }
};

export.modules = myPlugin;

The API also provides a second parameter for the call function in order to customize the arguments of the message.

var myPlugin = {
  name: 'My Plugin',
  description: 'Charge point plugin example for the tutorial',
  author: 'myself',

  ocpp_version: '1.5',
  system: 'cs',

  onLoad: function() {
    var self = this;

    self.cp.call('BootNotification', {
      chargePointVendor: "Vendor",
      chargePointModel: "Model"
    });
  }
};

export.modules = myPlugin;

Setting a result function

We want our plugin to display the heartbeatInterval when it receives a response from the BootNotification call. So, we need to write an onResult callback function.

var myPlugin = {
  name: 'My Plugin',
  description: 'Charge point plugin example for the tutorial',
  author: 'myself',

  ocpp_version: '1.5',
  system: 'cs',

  onLoad: function() {
    var self = this;

    self.cp.call('BootNotification', {
      chargePointVendor: "Vendor",
      chargePointModel: "Model"
    });

    self.onResult('BootNotification', function(values) {
      self.log('Heartbeat interval value:' + values.heartbeatInterval);
    });
  }
};

export.modules = myPlugin;

Setting a call function

We want our charge point to start a new transaction when the central system calls a RemoteStartTransaction remote procedure.

var myPlugin = {
  name: 'My Plugin',
  description: 'Charge point plugin example for the tutorial',
  author: 'myself',

  ocpp_version: '1.5',
  system: 'cs',

  onLoad: function() {
    var self = this;

    self.cp.call('BootNotification', {
      chargePointVendor: "Vendor",
      chargePointModel: "Model"
    });

    self.onResult('BootNotification', function(values) {
      self.log('Heartbeat interval value:' + values.heartbeatInterval);
    });

    self.onCall('RemoteStartTransaction', function(values) {
      self.cp.call('StartTransaction');
    });

  }
};

export.modules = myPlugin;

Setting a function when a connection event occurs

When the connection between the charge point and the central system is lost, we want to display a message.

var myPlugin = {
  name: 'My Plugin',
  description: 'Charge point plugin example for the tutorial',
  author: 'myself',

  ocpp_version: '1.5',
  system: 'cs',

  onLoad: function() {
    var self = this;

    self.cp.call('BootNotification', {
      chargePointVendor: "Vendor",
      chargePointModel: "Model"
    });

    self.onResult('BootNotification', function(values) {
      self.log('Heartbeat interval value:' + values.heartbeatInterval);
    });

    self.onCall('RemoteStartTransaction', function(values) {
      self.cp.call('StartTransaction');
    });

    self.onConnectEvent(function(type, cbId) {
      if(type == 'disconnected')
        self.log('Connection to the Central System lost !');
    });

  }
};

export.modules = myPlugin;

Creating a custom command

The API provides functions for parsing what the user enters in the command line interface. This process also allows the developer to create new commands. In our case, we want to create a "hello" command for displaying informations about the plugin.

var myPlugin = {
  name: 'My Plugin',
  description: 'Charge point plugin example for the tutorial',
  author: 'myself',

  ocpp_version: '1.5',
  system: 'cs',

  onLoad: function() {
    var self = this;

    self.cp.call('BootNotification', {
      chargePointVendor: "Vendor",
      chargePointModel: "Model"
    });

    self.onResult('BootNotification', function(values) {
      self.log('Heartbeat interval value:' + values.heartbeatInterval);
    });

    self.onCall('RemoteStartTransaction', function(values) {
      self.cp.call('StartTransaction');
    });

    self.onConnectEvent(function(type, cbId) {
      if(type == 'disconnected')
        self.log('Connection to the Central System lost !');
    });

    self.onCommand(function(command) {
      var commandObj = self.parse(command);

      if(commandObj.command == 'hello') {
        self.log("Hi! I'm "+ myPlugin.name +", created by "+ myPlugin.author +"!");
        return true;
      }
    });


  }
};

export.modules = myPlugin;

Important: If you want the simulator not to parse the command afterwards, you must return true.

Running the plugin

For testing the plugin, at first, run a charge point simulator. Available plugins can be viewed using the 'plugins' command:

> plugins
List of plugins:
[ ] cbxs-automatic-mode.js
[ ] cs-example.js
[ ] helloworld.js
[ ] myplugin.js

For loading our plugin, just type:

> load myplugin

> plugins
List of plugins:
[ ] cbxs-automatic-mode.js
[ ] cs-example.js
[ ] helloworld.js
[X] myplugin.js

If you want to stop the plugin without stopping the program, just type:

> unload myplugin