Skip to content

Commit

Permalink
Deploying to gh-pages from @ 37cf55b 🚀
Browse files Browse the repository at this point in the history
  • Loading branch information
@pbosetti
pbosetti committed Jun 27, 2024
1 parent 897c496 commit 9ad46d2
Show file tree
Hide file tree
Showing 21 changed files with 158 additions and 85 deletions.
129 changes: 81 additions & 48 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>plugin: Plugins!</title>
<title>plugin: Availabe plugins</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
Expand Down Expand Up @@ -63,58 +63,91 @@

<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Plugins! </div> </div>
<div class="title">Availabe plugins </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="anchor" id="md_README"></a><img src="https://github.com/pbosetti/mads_plugin/actions/workflows/cmake-multi-platform.yml/badge.svg" alt="Build status" style="pointer-events: none;" class="inline"/></p>
<p>This example project explores how to develop a plugin system for a C++ application. It is based on the [pugg plugin system]().</p>
<div class="textblock"><p><a class="anchor" id="md_src_plugin_README"></a> </p>
<h1><a class="anchor" id="autotoc_md1"></a>
Building</h1>
<p>To build the project, you need to have CMake installed. Then, you can run the following commands:</p>
<div class="fragment"><div class="line">mkdir build</div>
<div class="line">ccmake -Bbuild -DCMAKE_BUILD_TYPE=Release</div>
<div class="line">cmake --build build -t install</div>
</div><!-- fragment --><p>This creates three plugins in the form of executable files <b>that also export symbols</b>, so that they can be externally loaded by the main application. The plugins are named <code>echo.plugin</code>, <code>twice.plugin</code>, and <code>echoj.plugin</code>.</p>
<p>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.</p>
<p>Plugins are named <b>Filters</b>, 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 <code><a class="el" href="classFilter.html">Filter</a></code> (see <code><a class="el" href="filter_8hpp_source.html">src/filter.hpp</a></code>).</p>
<p>If needed, this project will be extended by adding base classes for other types of plugins, such as <b>Sources</b> (output only) and <b>Sinks</b> (input only).</p>
Templates</h1>
<p>The available templates are:</p>
<ul>
<li><code>template_source.cpp</code> for implementing source plugins</li>
<li><code>template_sink.cpp</code> for implementing sink plugins</li>
<li><code>template_filter.cpp</code> for implementing filter plugins</li>
</ul>
<p>Use these files as a starting point for your own plugins.</p>
<h1><a class="anchor" id="autotoc_md2"></a>
Executing</h1>
<p>The install step creates and populates the <code>usr</code> directory in the project root folder. You can run the executable that loads the plugin with the following command:</p>
<div class="fragment"><div class="line">cd usr</div>
<div class="line">bin/loaderj bin/echoj.plugin</div>
</div><!-- fragment --><p>Note that <b>on MacOS only</b> the <code>echoj.plugin</code> 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 <code>main()</code>) as:</p>
<div class="fragment"><div class="line">bin/echoj.plugin</div>
</div><!-- fragment --><p>This is a very flexible way for implementing standalone apps that can also be used as plugins within the Miroscic framework of distributed agents.</p>
<p>On Windows and Linux, the plugin is a shared library that can only be loaded by the <code>loader</code> executable. Beside the plugin, an equivalent executable is also generated.</p>
Example plugins</h1>
<p>The followings are example plugins of little practucalu use, but they are good for learning the basics of plugin development.</p>
<ul>
<li><code>clock</code>: a source that provides clock values</li>
<li><code>echoj</code>: a filter that echoes the input message</li>
<li><code>random</code>: a source that provides random values</li>
<li><code>to_console</code>: a sink that prints the input message to the console</li>
<li><code>twice</code>: a filter that duplicates the input message</li>
</ul>
<h1><a class="anchor" id="autotoc_md3"></a>
Plugin Versioning</h1>
<p>The plugin system uses an internal version number <code><a class="el" href="classFilter.html#a7110a1aae1ae96563c00c8f0592d929e">Filter::version</a></code> 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.</p>
<h1><a class="anchor" id="autotoc_md4"></a>
Derived classes</h1>
<p>To create a new plugin, fork this repository and implement a derived class of <code><a class="el" href="classFilter.html">Filter</a></code> or <code><a class="el" href="classSource.html">Source</a></code> 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</p>
<div class="fragment"><div class="line"><a class="code" href="common_8hpp.html#ab7463bc9c9b40ff018d92b01c237c452">INSTALL_SOURCE_DRIVER</a>(MySourceClassName, json)</div>
<div class="ttc" id="acommon_8hpp_html_ab7463bc9c9b40ff018d92b01c237c452"><div class="ttname"><a href="common_8hpp.html#ab7463bc9c9b40ff018d92b01c237c452">INSTALL_SOURCE_DRIVER</a></div><div class="ttdeci">#define INSTALL_SOURCE_DRIVER(klass, type)</div><div class="ttdoc">Call this macro after defining a source class to install it into the kernel.</div><div class="ttdef"><b>Definition:</b> common.hpp:19</div></div>
</div><!-- fragment --><p>If it is a filter, add</p>
<div class="fragment"><div class="line"><a class="code" href="common_8hpp.html#ac2ca73400d23bb4f12e23a64071588db">INSTALL_FILTER_DRIVER</a>(MyFilterClassName, json, json)</div>
<div class="ttc" id="acommon_8hpp_html_ac2ca73400d23bb4f12e23a64071588db"><div class="ttname"><a href="common_8hpp.html#ac2ca73400d23bb4f12e23a64071588db">INSTALL_FILTER_DRIVER</a></div><div class="ttdeci">#define INSTALL_FILTER_DRIVER(klass, type_in, type_out)</div><div class="ttdoc">Call this macro after defining a filter class to install it into the kernel.</div><div class="ttdef"><b>Definition:</b> common.hpp:38</div></div>
</div><!-- fragment --><p>If it is a sink, add</p>
<div class="fragment"><div class="line"><a class="code" href="common_8hpp.html#a1bbc82f63035c765ea291fb1051afad4">INSTALL_SINK_DRIVER</a>(MySinkClassName, json)</div>
<div class="ttc" id="acommon_8hpp_html_a1bbc82f63035c765ea291fb1051afad4"><div class="ttname"><a href="common_8hpp.html#a1bbc82f63035c765ea291fb1051afad4">INSTALL_SINK_DRIVER</a></div><div class="ttdeci">#define INSTALL_SINK_DRIVER(klass, type)</div><div class="ttdoc">Call this macro after defining a source class to install it into the kernel.</div><div class="ttdef"><b>Definition:</b> common.hpp:57</div></div>
</div><!-- fragment --><p>Finally, create a new target in the <code>CMakeLists.txt</code> file that compiles the new plugin. Something like:</p>
<div class="fragment"><div class="line">add_plugin(webcam LIBS LibsNeeded)</div>
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md5"></a>
HTTPS Client Certificates</h1>
<p>To connect with the Siemens Edge device, we need a SSL client certificate. To configure it, follow the next steps:</p>
<ol type="1">
<li>on the Siemens Edge miniweb interface, create a new certificate in .p12 format (if it is not exsiting yet)</li>
<li>download the certificate in this project root folder: when exporting, check the "Export key" option and give a passphrase</li>
<li>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):</li>
</ol>
<div class="fragment"><div class="line">openssl pkcs12 -in amwcapture.p12 -clcerts -nokeys -out amwcapture.crt -legacy</div>
<div class="line">openssl pkcs12 -in amwcapture.p12 -nocerts -nodes -out amwcapture.key -legacy</div>
</div><!-- fragment --><p>The executable will look for these two files in the current working directory. </p>
</div></div><!-- PageDoc -->
Plugins of actual use</h1>
<h2><a class="anchor" id="autotoc_md4"></a>
MQTT</h2>
<p>This acts as a source plugin, which reads messages from an MQTT broker and sends them to the MADS broker.</p>
<p>Note that the plugin <b>only subscribes to the topic as specified in the configuration file</b> and does not publish any messages.</p>
<p>The <b>frequency</b> 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.</p>
<h3><a class="anchor" id="autotoc_md5"></a>
Parameters</h3>
<p>The accepted parameters are:</p>
<div class="fragment"><div class="line">[mqtt]</div>
<div class="line">broker_host = &quot;localhost&quot;</div>
<div class="line">broker_port = 1883</div>
<div class="line">topic = &quot;capture/#&quot;</div>
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md6"></a>
Notes</h3>
<p>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. <code>capture</code>) 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. <code>capture/mads</code>). So, you typically want to subscribe to <code>capture/#</code> to get all the messages.</p>
<h2><a class="anchor" id="autotoc_md7"></a>
Serial Reader</h2>
<p>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.</p>
<p>The <b>frequency</b> 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 (<code>cfg_cmd</code> parameter).</p>
<h3><a class="anchor" id="autotoc_md8"></a>
Parameters</h3>
<p>The accepted parameters are:</p>
<div class="fragment"><div class="line">[serial_reader]</div>
<div class="line">port=&quot;/dev/ttyACM0&quot;</div>
<div class="line">baudrate=115200</div>
<div class="line"># Arduino config serial command</div>
<div class="line">cfg_cmd = &quot;40p&quot;</div>
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md9"></a>
Notes</h3>
<p>The <code>cfg_cmd</code> parameter is used to configure the Arduino board. The default value is <code>40p</code>, which sets the Arduino board to send a message every 40 ms.</p>
<h2><a class="anchor" id="autotoc_md10"></a>
Running average</h2>
<p>This acts as a filter plugin, which calculates the running average of the input values.</p>
<h3><a class="anchor" id="autotoc_md11"></a>
Parameters</h3>
<p>The accepted parameters are:</p>
<div class="fragment"><div class="line">[running_avg]</div>
<div class="line">sub_topic = [&quot;serial_reader&quot;]</div>
<div class="line">capa = 10 # running window size</div>
<div class="line">field = &quot;data&quot; # agerage all values in the dictionary &quot;data&quot;</div>
<div class="line">out_field = &quot;avg&quot; # output field</div>
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md12"></a>
Notes</h3>
<p>It searches for a field in the message payload having the name specified in the <code>field</code> parameter. the data field must be a dictionary. of numerical values, e.g.:</p>
<div class="fragment"><div class="line">{</div>
<div class="line"> &quot;data&quot;: {</div>
<div class="line"> &quot;value1&quot;: 1,</div>
<div class="line"> &quot;value2&quot;: 2,</div>
<div class="line"> &quot;value3&quot;: 3</div>
<div class="line"> }</div>
<div class="line">}</div>
</div><!-- fragment --><p>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 <code>out_field</code> parameter:</p>
<div class="fragment"><div class="line">{</div>
<div class="line"> &quot;avg&quot;: {</div>
<div class="line"> &quot;value1&quot;: 1,</div>
<div class="line"> &quot;value2&quot;: 2,</div>
<div class="line"> &quot;value3&quot;: 3</div>
<div class="line"> }</div>
<div class="line">}</div>
</div><!-- fragment --> </div></div><!-- PageDoc -->
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Expand Down
2 changes: 1 addition & 1 deletion search/all_0.js
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
var searchData=
[
['blob_5fformat_0',['blob_format',['../classSource.html#a119129cc44d86a108285b52b7c496212',1,'Source']]]
['availabe_20plugins_0',['Availabe plugins',['../index.html',1,'']]]
];
2 changes: 1 addition & 1 deletion search/all_1.js
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
var searchData=
[
['common_2ehpp_1',['common.hpp',['../common_8hpp.html',1,'']]]
['blob_5fformat_1',['blob_format',['../classSource.html#a119129cc44d86a108285b52b7c496212',1,'Source']]]
];
37 changes: 37 additions & 0 deletions search/all_10.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><title></title>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<link rel="stylesheet" type="text/css" href="search.css"/>
<script type="text/javascript" src="all_10.js"></script>
<script type="text/javascript" src="search.js"></script>
</head>
<body class="SRPage">
<div id="SRIndex">
<div class="SRStatus" id="Loading">Loading...</div>
<div id="SRResults"></div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
createResults();
/* @license-end */
</script>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
document.getElementById("Loading").style.display="none";
document.getElementById("NoMatches").style.display="none";
var searchResults = new SearchResults("searchResults");
searchResults.Search();
window.addEventListener("message", function(event) {
if (event.data == "take_focus") {
var elem = searchResults.NavNext(0);
if (elem) elem.focus();
}
});
/* @license-end */
</script>
</div>
</body>
</html>
4 changes: 4 additions & 0 deletions search/all_10.js
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
var searchData=
[
['write_33',['write',['../classSerialPort.html#a1b4627dc37646df3be8b532372d0b399',1,'SerialPort::write(const char *buf, size_t nBytes)'],['../classSerialPort.html#ac9c4df34bd033c9fead180e235e1fe06',1,'SerialPort::write(const std::string &amp;string)']]]
];
2 changes: 1 addition & 1 deletion search/all_2.js
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
var searchData=
[
['dummy_2',['dummy',['../classFilter.html#a29bce8d312ef763d7beb39f13851d9d3',1,'Filter::dummy()'],['../classSink.html#a21eb67669b967111d8f92f3fd9524d48',1,'Sink::dummy()'],['../classSource.html#a504d988ace793cf47a4301151ebdf570',1,'Source::dummy()']]]
['common_2ehpp_2',['common.hpp',['../common_8hpp.html',1,'']]]
];
2 changes: 1 addition & 1 deletion search/all_3.js
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
var searchData=
[
['error_3',['error',['../classFilter.html#a4f5237964d639b9f3c43a4a1d540174d',1,'Filter::error()'],['../classSink.html#a5d3da423ff6979ec8150a43fadfbd5ab',1,'Sink::error()'],['../classSource.html#aeb408a2891887138206fd602bf2357cb',1,'Source::error()']]]
['dummy_3',['dummy',['../classFilter.html#a29bce8d312ef763d7beb39f13851d9d3',1,'Filter::dummy()'],['../classSink.html#a21eb67669b967111d8f92f3fd9524d48',1,'Sink::dummy()'],['../classSource.html#a504d988ace793cf47a4301151ebdf570',1,'Source::dummy()']]]
];
3 changes: 1 addition & 2 deletions search/all_4.js
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
var searchData=
[
['filter_4',['Filter',['../classFilter.html',1,'']]],
['filter_3c_20json_2c_20json_20_3e_5',['Filter&lt; json, json &gt;',['../classFilter.html',1,'']]]
['error_4',['error',['../classFilter.html#a4f5237964d639b9f3c43a4a1d540174d',1,'Filter::error()'],['../classSink.html#a5d3da423ff6979ec8150a43fadfbd5ab',1,'Sink::error()'],['../classSource.html#aeb408a2891887138206fd602bf2357cb',1,'Source::error()']]]
];
3 changes: 2 additions & 1 deletion search/all_5.js
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
var searchData=
[
['get_5foutput_6',['get_output',['../classMQTTBridge.html#a5a94e80b54015e4200d76eea11fdddf7',1,'MQTTBridge::get_output()'],['../classRandom.html#a0d0abc75765b1ad5504ef6a7ff5873bf',1,'Random::get_output()'],['../classSerialReader.html#a7c0a2f303b640862cb3f0feef2bd4430',1,'SerialReader::get_output()'],['../classPluginClassName.html#aa7145bf08e4b7a4a38ad079db66dd2cf',1,'PluginClassName::get_output()'],['../classSource.html#ae53b4ab2f47b84e811232e0301682bb8',1,'Source::get_output()']]]
['filter_5',['Filter',['../classFilter.html',1,'']]],
['filter_3c_20json_2c_20json_20_3e_6',['Filter&lt; json, json &gt;',['../classFilter.html',1,'']]]
];
5 changes: 1 addition & 4 deletions search/all_6.js
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,4 @@
var searchData=
[
['info_7',['info',['../classFilter.html#afdb37ae1a5382b33d14d2b6cd725ce96',1,'Filter::info()'],['../classMQTTBridge.html#a3b61cdabab81977c353c68f1e8b9a6f4',1,'MQTTBridge::info()'],['../classRandom.html#a16db0a2cbd601f40faaf81e51277885b',1,'Random::info()'],['../classRunningAverage.html#a246a9741870901734a7e3db5d5ffb797',1,'RunningAverage::info()'],['../classSerialReader.html#ae9e404b161358edd22852e653c23079d',1,'SerialReader::info()'],['../classPluginClassName.html#ac27d630e667fb497ef6b86c72feaa439',1,'PluginClassName::info() override'],['../classPluginClassName.html#ac27d630e667fb497ef6b86c72feaa439',1,'PluginClassName::info() override'],['../classPluginClassName.html#ac27d630e667fb497ef6b86c72feaa439',1,'PluginClassName::info() override'],['../classToConsole.html#a10c404eb15c5c7c6263b9c5a1ae0520d',1,'ToConsole::info()'],['../classSink.html#acde447f8670f585d14ab2c7d4eaa4369',1,'Sink::info()'],['../classSource.html#a7db86c9293679009397ebf1a1f848c5a',1,'Source::info()']]],
['install_5ffilter_5fdriver_8',['INSTALL_FILTER_DRIVER',['../common_8hpp.html#ac2ca73400d23bb4f12e23a64071588db',1,'common.hpp']]],
['install_5fsink_5fdriver_9',['INSTALL_SINK_DRIVER',['../common_8hpp.html#a1bbc82f63035c765ea291fb1051afad4',1,'common.hpp']]],
['install_5fsource_5fdriver_10',['INSTALL_SOURCE_DRIVER',['../common_8hpp.html#ab7463bc9c9b40ff018d92b01c237c452',1,'common.hpp']]]
['get_5foutput_7',['get_output',['../classMQTTBridge.html#a5a94e80b54015e4200d76eea11fdddf7',1,'MQTTBridge::get_output()'],['../classRandom.html#a0d0abc75765b1ad5504ef6a7ff5873bf',1,'Random::get_output()'],['../classSerialReader.html#a7c0a2f303b640862cb3f0feef2bd4430',1,'SerialReader::get_output()'],['../classPluginClassName.html#aa7145bf08e4b7a4a38ad079db66dd2cf',1,'PluginClassName::get_output()'],['../classSource.html#ae53b4ab2f47b84e811232e0301682bb8',1,'Source::get_output()']]]
];
Loading

0 comments on commit 9ad46d2

Please sign in to comment.