This example project explores how to develop a plugin system for a C++ application. It is based on the [pugg plugin system]().
+-Building
-To build the project, you need to have CMake installed. Then, you can run the following commands:
-This creates three plugins in the form of executable files that also export symbols, so that they can be externally loaded by the main application. The plugins are named echo.plugin, twice.plugin, and echoj.plugin.
The latter plugin is a template for complete plugins, and it is pretty extensible. Indeed, it accepts a JSON object as settings, a JSON object as input, and produces a JSON object as output. The other two plugins are simple examples of how to implement a plugin.
-Plugins are named Filters, for they are expected to act as filters, taking an input and producing an output. The plugins must be implemented as derived classes of the templated class Filter (see src/filter.hpp).
If needed, this project will be extended by adding base classes for other types of plugins, such as Sources (output only) and Sinks (input only).
+Templates +The available templates are:
+-
+
template_source.cppfor implementing source plugins
+template_sink.cppfor implementing sink plugins
+template_filter.cppfor implementing filter plugins
+
Use these files as a starting point for your own plugins.
-Executing
-The install step creates and populates the usr directory in the project root folder. You can run the executable that loads the plugin with the following command:
Note that on MacOS only the echoj.plugin file is actually an executable file that exports symbols. It is not a shared library, but it is a plugin that can also be directly executed (using its internal main()) as:
This is a very flexible way for implementing standalone apps that can also be used as plugins within the Miroscic framework of distributed agents.
-On Windows and Linux, the plugin is a shared library that can only be loaded by the loader executable. Beside the plugin, an equivalent executable is also generated.
The followings are example plugins of little practucalu use, but they are good for learning the basics of plugin development.
+-
+
clock: a source that provides clock values
+echoj: a filter that echoes the input message
+random: a source that provides random values
+to_console: a sink that prints the input message to the console
+twice: a filter that duplicates the input message
+
-Plugin Versioning
-The plugin system uses an internal version number Filter::version to check compatibility between the main application and the plugins. To invalidate a previously released plugin, simply imcrease the version number in the base class.
-Derived classes
-To create a new plugin, fork this repository and implement a derived class of Filter or Source in a new file. At the end of the new derived class definition, add the macros that set up the plugin driver: if it is a source, add
If it is a filter, add
-If it is a sink, add
-Finally, create a new target in the CMakeLists.txt file that compiles the new plugin. Something like:
-HTTPS Client Certificates
-To connect with the Siemens Edge device, we need a SSL client certificate. To configure it, follow the next steps:
--
-
- on the Siemens Edge miniweb interface, create a new certificate in .p12 format (if it is not exsiting yet) -
- download the certificate in this project root folder: when exporting, check the "Export key" option and give a passphrase -
- now the encripted certificate must be extracted in two separate files: the certificate itself and the private key. To do so, run the following commands (which will ask you the same passphrase used in the previous step): -
The executable will look for these two files in the current working directory.
-+MQTT
+This acts as a source plugin, which reads messages from an MQTT broker and sends them to the MADS broker.
+Note that the plugin only subscribes to the topic as specified in the configuration file and does not publish any messages.
+The frequency of messages depends on when they are received from the MQTT broker. The plugin will send the messages to the MADS broker as soon as they are received.
++Parameters
+The accepted parameters are:
++Notes
+The MQTT broker must be running on the same address that has been set into the Siemens MindSphere settings. The root publishing topic (e.g. capture) is defined in the settings of the Siemens MindSphere application, while each acquisition procedure defined in the Edge internal webapp will append a unique identifier to the root topic (e.g. capture/mads). So, you typically want to subscribe to capture/# to get all the messages.
+Serial Reader
+This acts as a source plugin, which reads messages from a serial port (typically connected to an Arduino) and sends them to the MADS broker.
+The frequency of messages depends on the configuration of the Arduino board. The plugin will send the messages to the MADS broker as soon as they are received from the Arduino board. In turn, this frequency can be set in the configuration file (cfg_cmd parameter).
+Parameters
+The accepted parameters are:
++Notes
+The cfg_cmd parameter is used to configure the Arduino board. The default value is 40p, which sets the Arduino board to send a message every 40 ms.
+Running average
+This acts as a filter plugin, which calculates the running average of the input values.
++Parameters
+The accepted parameters are:
++Notes
+It searches for a field in the message payload having the name specified in the field parameter. the data field must be a dictionary. of numerical values, e.g.:
The plugin will calculate the average of all the values in the dictionary and store it in a new field, whose name is specified in the out_field parameter: