Plugin Controller
The plugin controller is a controller that can be extended through plugins. Controller plugins can be programmed by the users themselves using the Java programming language. This enables users to program complex controllers. Redirections or forwarding to other programming environments such as Matlab are possible, for example to use existing controllers for Polysun. The interface to the plugin controllers is the Java interface IPluginController.
Introduction
Plugin controllers enable the user to create controllers for Polysun. This way, complex and powerful controllers can be developed. These controllers can either be developed from scratch or external controller plugins can be added to a Polysun installation.
A Polysun installation comes with several plugin controllers, see the following chapters.
In practice, plugin controllers behave similar to “traditional controllers”. The difference is that anyone able to program in Java, is able to develop and pass on a plugin controller.
Difference to the Programmable Controller and Advantages of the Plugin Controller
Plugin controllers are used for the programming of controllers just like the “Programmable controller”. However, the programming of plugin controllers is done through the programming languages Java, Python or Matlab. Thus, complex controllers can be programmed. Program loops or libraries can be used. The full scale of these programming languages is at your disposal.
Additionally, you have the possibility to program redirections or forwarding to existing controllers, for example like how it was done for Matlab or Python.
Uses of Plugin Controllers
Plugin controllers are added to your system diagram just like “traditional” controllers through the controller selection. In the plugin controller selection, all existing plugin controllers are on display.
Projects containing a plugin controller need the plugin containing the controller in order to run or to be edited. Plugins are stored as .jar-files and can be added to the plugins folder in the data path of Polysun. As a default for Windows this would be C:UsersPublicPolysunplugins, as a default for MacOS, it would be /Programs/Polysun/plugins. Plugins added are available after Polysun is started anew.
You can test it using the demo plugin controller contained in the plugin DemoPlugin.jar. This is found in the Polysun folder and can be copied from the folder plugins/examples to the folder plugins. This controller is available once Polysun is started anew.
If a plugin controller is missing, an error message is shown. Editing or running a simulation is not possible if the plugin is missing. You have to add the missing plugin controller.
Polysun has a number of plugin controllers included.
Project examples can be found in the folder plugins/examples.
Currently, plugin controllers are not automatically added to projects the way profiles are. Users have to pass on plugins manually.
Flow Rate Plugin Controller
The flow rate plugin controller behaves like the existing flow rate controller. It is a mere copy. This controller is offered as part of the source code and as open source software, check the folder plugins/PolysunPluginDevelopmentKit.zip.
„Fixed Time Step“ Plugin Controller
This controller prescribes the simulation a regular, fixed time step.
For every point in time that is a multiple of the fixed time step, the simulation will execute a time step. Polysun can execute more time steps if necessary for the simulation. For example, for the fixed time step of 180s, the simulation will execute the time steps 0s, 180s, 360s, 480s, 720s, …. 0 means no fixed time steps, the default time steps of Polysun (240s during the day and 720s at night) are used. In other words, 0 stands for “normal time steps”.
Matlab Plugin Controller
The Matlab controller is a plugin controller passing on the commands from Polysun to a Matlab function. The plugin will set the name of the function in Matlab. This function has to be in the path of Matlab or in the start folder. The Matlab function must have the following function arguments:
function [ controlSignals, logValues, timepoints ] = control( simulationTime, status, sensors, sensorsUsed, properties, propertiesStr, preRun, controlSignalsUsed, numLogValues, stage, fixedTimestep, verboseLevel, parameters)
The Matlab function given in the Matlab controller is retrieved in every time step from Polysun and has to calculate the controller outputs for Polysun based on the input parameters in every time step.
The configuration and examples of the Matlab controller are stored in the Polysun folder plugins/com.velasolaris.plugin.controller.matlab.matconsolectl.MatlabPluginController after the first command, for example
C:UsersPublicPolysunpluginscom.velasolaris.plugin.controller.matlab.matconsolectl.MatlabPluginController.
The file config.properties contains the basic configuration of the MatLab controller. If MatLab is not found, the path to the MatLab program file in matctl.matlabLocation must be set, for example
matctl.matlabLocation=C:\Program Files\MATLAB\R2017a\bin\matlab.exe
The correct usage of “” is technically necessary, i. e. double and a single one in front of “:”. The start directory can also be set the first time Matlab is started using the parameter matctl.matlabStartingDirectory. The names of most other parameters make them self-explanatory or generally do not have to be altered.
The function arguments of the control function are documented in control.m. The Matlab function controlFlowrate.m implements a flow rate controller. It behaves the same way as the “traditional” Polysun flow rate controller.
This controller is offered in source code and is open source software, check the folder plugins/PolysunPluginDevelopmentKit.zip.
If Matlab was not started already, it will be started. Breakpoints in Matlab are supported.
The Matlab controller uses the library MatConsoleCtl for its internal communication.
In the chapter Speed comparison, Matlab will be compared to the other command giving types.
RPC Plugin Controller (Python)
The RPC controller is a plugin controller that passes commands from Polysun through a Remote Procedure Call (RPC) on to a RPC server. In the controller, the name of the function and the URL of the server are set, for example “controlFlowrate” and http://localhost:2102/control. The function in the RPC server must contain the following function arguments:
control(simulationTime, status, sensors, sensorsUsed, properties, propertiesStr, preRun, controlSignalsUsed, numLogValues, stage, fixedTimestep, verboseLevel, parameters)
=> controlSignals, logValues, timepoints
The RPC function entered into the controller is retrieved in every time step from Polysun and has to calculate the output commands for Polysun based on the input parameters in every time step.
Three types of RPC are supported: JSON-RPC stream (optimized for speed), JSON-RPC and XML-RPC. Both JSON-RPC and XML-RPC are supported by many systems, for example by the programming language Python.
In Python (https://python.org), JSON-RPC is supported through additional modules and XML-RPC by default. In the RPC controller folder (plugins/com.velasolaris.plugin.controller.rpc.SimpleRpcPluginController) you will find both a XML and a JSON-RPC server and an optimized JSON-RPC stream server for Python. The controller functions are found in controlFunctions.py.
How to start the function server:
python controlJsonRpcStreamServer.py
python controlJsonRpcServer.py
python controlXmlRpcServer.py
python controlRpcServer.py
You can also use pypy (http://pypy.org), which uses a just-in-time (JIT) compiler making it faster:
pypy controlJsonRpcStreamServer.py
pypy controlJsonRpcServer.py
pypy controlXmlRpcServer.py
pypy controlRpcServer.py
Polysun offers the possibility to automatically start a RPC function server. For a successful start of a RPC server, the parameters have to be set right. Should the automatic start of the RPC server fail, please refer to the Polysun log file in the Polysun folder, for example C:UsersPublicPolysundata.log. Analyzing existing problems is only possible with a minimum degree of technical knowledge.
The different command giving types are compared with one another in the chapter Speed comparison.
Additional information is documented in the script files.
This controller is offered as a source code and is open source software, check the folder plugins/PolysunPluginDevelopmentKit.zip.
Programming of Plugin Controllers
You can program plugin controllers yourself using the programming language Java. Preconditions to programming are knowledge of the Java programming language and a Java programming environment.
As an introduction, the interface IPluginController defines a controller and ControllerPlugin a plugin.
Plugin controllers have to meet (implement) the Java interface IPluginController. The most important method is control(). This method is called on in every time step and calculates the controller output signals from the sensor signals. The signature is
control(int simulationTime, boolean status, float[] sensors, float[] controlSignals, float[] logValues, boolean preRun, Map<String, Object> parameters).
The values for the set controller inputs are provided in the sensors array in every time step. Based on these values, the plugin controller calculates the controlling commands (controlSignals array) for the controller inputs.
The files necessary for the development of plugin controllers are available as a zipped archive in the folder plugins/PolysunPluginDevelopmentKit.zip. Further information can be found in the README.txt files.
A plugin controller is defined by the interface ControllerPlugin. A plugin has to have a class that is implemented by this interface. In order for the plugin to be found, it has to be “registered”. In order for this to happen, the full name of the class of the plugin programmed (including packages) has to be set in the file
META-INF
servicescom.velasolaris.plugin.controller.spi.ControllerPlugin. For the plugin demo, this content is contained in this file
com.velasolaris.plugin.controller.DemoControllerPlugin. The compiled Java classes (.class) with the META-INF folder can then be packed into a Java archive (.jar-file) and subsequently added to the class path of Polysun. It is best if the plugins are added to the folder plugins of the directory. A plugin jar file is best created with an Ant script, please refer to build.xml of the demo plugin.
Normally plugin-jar-files will not be reloaded executing Polysun, but this can be helpful during the development. Setting the command
Plugin.ReloadAlways=1
in the file user.ini (eg. in C:UsersPublicPolysun) which contains the Polysun user settings, the plugins will be reloaded executing the plugin controller dialogue.
In order to program a new plugin controller it is best to make a copy of the demo plugin and to adapt the relevant files. We recommend to check new controllers with a JUnit test. The DemoFlowratePluginControllerTest is an example of a JUnit test.
Speed Comparison
Plugin commands are possible through numerous ways. Programming languages like Matlab, Python or Java can be especially suitable for some determined tasks.
The simulation time is dependent on the type of commands. In order to compare the speeds, the different types of command giving were compared. The template “16c: Space heating (heat pump, no buffer tank)” was used, always with the same flow rate control logics (see Polysun project “FlowratePluginControllerComparison.pse”).
Table: Simulation time and average execution time for different plugin controller types System used for testing: Intel Core i7-6820HQ 2.7GHz, Windows 10 1607, Java 8, Matlab 2016a, pypy 5.4.1, Polysun 9.2 dev (r24000), plugins/examples/FlowratePluginControllerComparison.pse
| Plugin controller type | Simulation time | Average execution time |
| FlowrateController | 4 s | 0 ms |
| Java FlowratePluginController | 4 s | 0 ms |
| MatlabPluginController | 86 s | 0.5 ms |
| JSON-RPC stream (Python) | 14 s | 0.06 ms |
| JSON-RPC (Python) | Abort (68s) | 0.4 ms |
| XML-RPC (Python) | 228 s | 1.5 ms |
Comparison of commands by different Remote Procedure Call (RPC) protocols with the different Python interpreters.
Table: Average execution time for different Python interpreters and RPC protocols System used for testing: Intel Core i7-4500U CPU 1.80GHz, openSuse 13.2 Linux, Java 8, Polysun 9.2 dev (r24000), plugins/examples/FlowratePluginControllerComparison.pse
| Python / RPC protocol | JSON-RPC stream | JSON-RPC | XML-RPC |
| RPC type | Own development | Standard | Standard |
| Communication protocol | TCP Socket | HTTP | HTTP |
| One TCP connection per | Simulation | Time step | Time step |
| PyPy 5.4.1 | 0.06 ms | 0.5 ms | 0.6 ms |
| Python 2.7 | 0.09 ms | 0.7 ms | 1.3 ms |
| Python 3.4 | 0.08 ms | 0.9 ms | 1.4 ms |
Using JSON-RPC locally on fast systems under Windows leads to the error message “java.net.BindException: Address already in use: connect” (PSA-4571). Use the “JSON-RPC stream” protocol instead.
Possible Further Developments
Controller plugins currently have to be passed on in parallel with the projects. In the future, it could be possible to store plugins in the Polysun project files .pse, as it is already the case with profiles.