OpenMUC User Guide

To install OpenMUC just download the latest version and unpack it to your favorite destination.

OpenMUC requires Java 8 or higher, therefore make sure it is installed on your machine.

The OpenMUC demo contains a simple application which demonstrates how you can access channels and their records from an application. The application reads data from channels of the CSV driver, calculates new values from them and writes them to other channels. The application can be used as starting point to create your own OpenMUC application.

Open a terminal and navigate to the framework folder (<your-path>/openmuc/framework)

To start OpenMUC on Linux run:

To start OpenMUC on Windows run:

This will start the Apache Felix OSGi framework which in turn starts all the bundles located in the "bundle" folder. After initialization of the OSGi framework you should be able to see the output of the demo application.

Among the bundles that are started is the Apache Gogo shell. This shell is entered once you run OpenMUC. Now type lb to list all installed bundles.

You can stop and exit the OSGi framework any time by typing ctrl+d or stop 0. For more information about the start script see chapter OpenMUC Start Script.

This section leads you through the framework’s WebUI.

Open a browser (works currently best with Google Chrome) and enter the URL "http://localhost:8888". This leads you to the login page. The default user is admin and the default password is admin as well.

After successful login the OpenMUC Dashboard opens, which provides various plugins for configuration and visualization. A full description of the plugins can be found in the chapter Web UI.

Let us first look at the Channel Access Tool which provides the current value of each channel and also enables you to write values. Click on Channel Access Tool to open this plugin. The next page lists all available devices which are currently configured in OpenMUC. Select the home1 and proceed with Access selected.

On the next page you will see the latest records of all channels of home1. Each record consists of a data value, a timestamp when it was sampled and a quality flag.

Let’s have look at the Data Plotter. To get to the Data Plotter click on Applications next to the OpenMUC logo and select Data Plotter.

Select the Live Data Plotter. To view the live data select the channels of your choice and click Plot Data.

The last WebUI plugin we want to look at is a customised visualisation for our demo application. Click on Applications and select Simple Demo Visualisation. The purpose of this plugin is to show how OpenMUC channels can be accessed and used for individual visualisations. Detailed informations about the development of such a plugin can be found in the Tutorial Develop a Customised WebUI Plugin.

Objective: You will learn how to create a simple data logger which reads out a M-Bus meter via serial communication. It uses OpenMUC on-board tools so no programming is required.

Preparation: If not already done, your system needs to be prepared once for serial communication.

Now logout from your system and login again to apply system changes.

Step-by-step

Tips

Objective: You will learn how to develop your own OpenMUC application. This tutorial focuses on the Eclipse integration, build process and how to start your application in the felix OSGi framework.

Preparation: This tutorial is based on Eclipse IDE and Gradle build tool, therefore you need Eclipse IDE and Gradle installed on your pc.

Step-by-step

Objective: In this tutorial you will learn how to add a plugin to the WebUI as well as how to display data from your configured channels. Examples for such plugins are the simpledemovisualisation bundle or the HeiPhoss WebUI

Preparation: You should be familiar with OpenMUC’s architecture.

Step-by-step

Tips

The distribution contains the following important files and folders:

The folder "framework" contains a configured OpenMUC framework that can be used as a basis to create your own customized OpenMUC framework for your task. The framework folder contains the following important files and folders:

OpenMUC works on the basis of channels. A channel basically represents a single data point. Some examples for a channel are the metered active power of a smart meter, the temperature of a temperature sensor, any value of digital or analog I/O module or the some manufacture data of the device. Thus a channel can represent any kind of data point. The following picture illustrates the channel concept.

The conf/channels.xml file is the main configuration file for OpenMUC. It tells the OpenMUC framework which channels it should log and sample. It contains a hierarchical structure of drivers, devices and channels. A driver can have one or more devices and devices can have one or more channels. Following listing shows a sample configuration to illustrate the hierarchical structure. The driver, device and channel options are explained afterwards.

*time: integer with suffix (ms, s, m, h) like: 300ms, 2s.

The available driver settings, device settings and channel settings can also be found in the Javadoc of DriverConfig.java, DeviceConfig.java and ChannelConfig.java respectively.

Default Data Logger

You can define a default data logger by adding a logger element with the id of a data logger to the configuration. If available, that data logger is used to read logged values. The ids of data loggers shipped with the OpenMUC Framework are defined in the "Data Loggers" chapter. If no logger with the defined id is available, or the logger element is missing from the configuration, an arbitrary available logger is used to read logged values. Only one default logger may be defined. If multiple logger elements exists, only the first one is evaluated.

This configuration only affects reading of already logged values. Channels are still logged by all available loggers.

The following examples will give you a better understanding of these three settings.

In example 1 the channel is sampled every 4 seconds which means the data manager requests every 4 seconds the current value from the driver.

Example 2 extends example 1 by an additional logging. The logging interval is set to 8 seconds which means that every 8 seconds the last sampled value is stored in the database. In this case every second sampled value is stored because the sampling interval is 4 seconds. To log every sampled value the sampling interval and logging interval need to be the same.

In example 3 listening instead of sampling is used. This means that the driver reports a new channel value to the data manager when the value has changed for example.

Example 4 extends example 3 by an additional logging.

Example 5 extends example 3 by an additional event logging. It loggs only if only a new value was received. (the logger needs to support event logging)

To start OpenMUC on Linux run:

This runs OpenMUC in the foreground on your console. If you like to start OpenMUC as background process then skip the parameter -fg. On Windows you can run the bin\openmuc.bat to start OpenMUC. For now we will focus on the Linux script, since Linux is the more common environment for OpenMUC. The start command will basically run the Felix OSGi Framework via java -jar felix/felix.jar and Felix starts all bundles located in framework/bundle.

To stop OpenMUC run:

If you started OpenMUC in the foreground you can press ctrl+d or enter "stop 0" to stop OpenMUC.

With the restart command OpenMUC stops and starts again.

To reload the configuration without restarting OpenMUC use:

If you have modified the bundles.conf.gradle file then run the following command to update the /framework/bundle folder.

If you have changed the source code and want to rebuild the bundles and apply them to the /framework/bundle folder use:

If you are using a local maven repository you can use the -i option to update the repository with the latest changes.

Tip: development the following command is quite handy to start OpenMUC with your latest code changes:

The remote shell allows you to connect via telnet to a running OpenMUC which was started as background process.

OpenMUC uses the Apache Felix Gogo JLine Shell by default, since JLine provides more advanced features than the standard GoGo Shell. Unfortunately, JLine does not work in combination with the remote shell. Therefore, we must switch back to the standard GoGo Shell to use remote access. This can be achieved by modifying the bundles.conf.gradle. Add the following bundles org.apache.felix.shell.remote and org.apache.felix.gogo.shell and comment or remove the bundles org.apache.felix.gogo.jline and jline

To access OpenMUC you can either use

or

To exit the remote shell without stopping OpenMUC press ctrl+d.

On Debian based Linux distributions it is easy to configure automatic start of OpenMUC at boot time. As root execute the following commands:

The above solution will not work if the openmuc start script is located on a partion that is not yet mounted at the time the boot process attempts to open it. In this case you need copy the start script to /etc/init.d/ and edit it to set the OPENMUC_HOME variable.

For installing a new driver you have two possible ways.

Modbus Homepage: http://www.modbus.org
Modbus Protocol Specifications: http://www.modbus.org/specs.php
Modbus Master Simulator modpoll: http://www.modbusdriver.com/modpoll.html

The Modbus driver supports RTU, TCP and RTU over TCP.

DeviceAddress

For TCP and RTUTCP
The DeviceAddress is specified by an IP address and an optional port. If no port is specified, the driver uses the modbus default port 502.

For RTU:
The DeviceAddress is specified by a serial port like /dev/ttyS0.

Settings

ChannelAddress

The ChannelAddress consists of four parts: UnitId, PrimaryTable, Address and Datatyp which are explained in detail in the following table.

Valid Address Parameter Combinations

Since COILS and DISCRETE_INPUTS are used for bit access, only the data type BOOLEAN makes sense in combinations with of one of these. INPUT_REGISTERS and HOLDING_REGISTERS are used for register access. There is also a difference between reading and writing. Only COILS and HOLDING_REGISTERS are readable and writable. DISCRETE_INPUTS and INPUT_REGISTERS are read only. The following table gives an overview of valid parameter combinations of PrimaryTable and Datatyp.

Function Codes (more detailed information about how the driver works)

The driver is based on the Java Modbus Library (j2mod) which provides read and write access via modbus. Following table shows which modbus function code is used to access the data of the channel.

Example

M-Bus is communication protocol to read out meters.

Device Address

<serial_port> - The serial port should be given that connects to the M-Bus converter. (e.g. /dev/ttyS0, /dev/ttyUSB0 on Linux).

<mbus_address> - The mbus adrdess can either be the the primary address or secondary address of the meter. The primary address is specified as integer (e.g. 1 for primary address 1) whereas the secondary address consits of 8 bytes that should be specified in hexadecimal form. (e.g. e30456a6b72e3e4e)

tcp - with this option M-Bus over TCP is used.

<host_address> - The host address for M-Bus over TCP e.g. 192.168.8.89.

<port> - The TCP port for M-Bus over TCP e.g. 5369

Settings

<baudrate> - If left empty the default is used: "2400"

<timeout> - Defines the read timeout in ms. Default is 2500 ms. Example: t5000 for timeout of 5 seconds

<lr> - Link reset before readout.

<ar> - Application reset before readout.

d<delay> - Inserts a delay between every message, including link reset and application reset. Delay in ms. A delay with 100 ms and activated link reset and application reset results in a total delay of 300 ms.

tc<tcp_connection_timeout> - The TCP connection timeout is need for a defined timeout when no TCP connection could established.

Channel Address

Shall be of the format <dib>:<vib> in a hexadecimal string format (e.g. 04:03 or 02:fd48) The X option is used for selecting a specific data record.

Wireless M-Bus is communication protocol to read out meters and sensors.

Device Address

<serial_port> - The serial port used for communication. Examples are /dev/ttyS0 (Linux) or COM1 (Windows)

<secondary_address> - The secondary address consists of 8 bytes that should be specified in hexadecimal form. (e.g. e30456a6b72e3e4e)

Settings

<transceiver> - The transceiver being used. It can be 'amber' or 'rc' for modules from RadioCrafts.

<mode> - The wM-Bus mode can be S or T.

<key> - The key in hexadecimal form.

Channel Address

Shall be of the format <dib>:<vib> in a hexadecimal string format (e.g. 04:03 or 02:fd48)

IEC 60870-5-104 is an international communication standard for telecontrol. The IEC 60870-5-104 driver uses the library from the j60870 project.
The driver is able to send general interrogation commands for sampling. For writing almost all commands are possible.

All options are separated by a semicolon.

Channel Address

Mandatory options are Common Address, Type ID and Information Object Address.

It is possible to get a single value of a Sequence Information Element, for this you can define Index of the needed element. The first element is 0, the second 1, …​

For reading values which are divided in multiple elements it can be defined how many elements should be read as one. e.g. i=0;m=4 says it reads from the first element up to the fourth element, of a sequence. This is only allowed for Binary State Information.

With the option Data Type it is possible to get a single quality flag.

IEC 61850 is an international communication standard used mostly for substation automation and controlling distributed energy resources (DER). The IEC 61850 driver uses the client library from the OpenIEC61850 project.

Channel Address

The channel address should be the IEC 61850 Object Reference and the Functional Constraint of the Basic Data Attribute that is to be addressed separated by a colon. Note that an IEC 61850 timestamp received will be converted to a LongValue that represents the milliseconds since 1970. Some information is lost during this conversion because the IEC 61850 timestamp is more exact.

Settings

The defaults for TSelLocal and TSelRemote are "00" and "01" respectively. You can also set either TSelector to the empty string (e.g. "-lt -rt"). This way they will be omitted in the connection request.

The IEC 62056 part 21 driver can be used to read out meter via optical interface

Device Address

<serial_port> - The serial port should be given that connects to the M-Bus converter. (e.g. /dev/ttyS0, /dev/ttyUSB0 on Linux).

Settings

Baud rate change delay -d sets the waiting time in milliseconds between a baud rate change default is 0.
Timeout -t sets the response timeout in milliseconds, default is 2000.
Number of read retries -r defines the maximum of read retries, default is 0.
Baud rate -bd sets a initial baud rate e.g. for devices with modem configuration, default is 300.
Device address -a is mostly needed for devices with RS485, default is no device address.
Fixed baud rate -fbd activates fixed baud rate, default is deactivated.
Request message start character -rsc is used for manufacture specific request messages. With this option you can change the default start character.
Read standard -rs reads the standard message and the manufacture specific message. This options has only an affect if the Request message start character is changed.

Channel Address

<data_set_id> - Id of the data set. It is usually an OBIS code of the format A-B:C.D.E*F or on older EDIS code of the format C.D.E.that specifies exactly what the value of this data set represents.

DLMS/COSEM is a international standardized protocol used mostly to communicate with smart meter devices. The DLMS/COSEM driver uses the client library developed by the jDLMS project. Currently, the DLMS/COSEM driver supports communication via HDLC and TCP/IP using Logical Name Referencing to retrieve values from the device.

Dependencies: rxtxcomm_api-2.1.7.jar (optional)

Device Address

The interface address consists of all elements the driver needs to uniquely identify and address a physical smart meter and format depends on the used protocol. Refer to the following table for the format of the interface address.

Serial with HDLC on serial port ttyUSB0 an 9600 baud:
t=serial;sp=/dev/ttyUSB0;bd=9600;hdlc=true

TCP with HDLC to host 192.168.85.99 on port 5081:
t=tcp;h=192.168.85.99;p=5081;hdlc=true

Settings

Settings are separated by a semi-colon. The available settings are determined by the used protocol, defined as first parameter of the device address. All possible settings with a short description and default values are listed in the following table.

KNX is a standardised protocol for intelligent buildings. The KNX driver uses KNXnet/IP to connect to the wired KNX BUS. The driver supports group read and writes and is also able to listen to the BUS. The driver uses the calimero library.

Device Address

The device address consists of the host IP and the IP of the KNX tunnel or router.

Channel Address

The channel address consist of the group address you want to monitor and the corresponding data point ID. A data point consists of a main number and a subtype. For example a boolean would be represented by the main number 1 and a switch by the subtype 001, the DPT_ID of a switch is 1.001.

OpenMUC driver for SML and IEC 62056-21

Dependencies: rxtxcomm_api-2.1.7.jar

scanForDevices() and scanForChannels will return the specific configuration.

Simple Network Management Protocol (SNMP) is an Internet-standard protocol for monitoring and management of devices on IP networks.

Dependencies: snmp4j-2.2.5.jar

Device Address

IP address and available SNMP port of the target device should be provided as Device Address.

Example for Device Address:

Settings

All settings are stored in "SnmpDriverSettingVariableNames" enum.

SNMPVersion

SNMPVersion is an enum variable containing valid SNMP versions. (V1, V2c, V3)

Example for valid settings string:

In order to read specific channel, corresponding SNMP OID shall be passed.

Example for SNMP OID:

For scanning SNMP enabled devices in the network, range of IP addresses shall be provided. This functionality is implemented only for SNMP V2c.

The csv driver supports sampling from a csv file. This feature can be very helpful during application development or show cases, when no real hardware is available. For example, our SimpleDemoApp uses data provided by the csv driver.

Settings

The columns unixtimestamp and hhmmss are part of the log files created by the AsciiLogger, therefore the csv driver supports these files.

The Aggregator which performs aggregation of logged values from a channel. It uses the DriverService and the DataAccessService. It is therefore a kind of OpenMUC driver/application mix. The aggregator is fully configurable through the channels.xml config file.

Channel Address

<sourceChannelId> - id of channel to be aggregated

<aggregationType> -

<quality> - Range 0.0 - 1.0. Percentage of the expected valid/available logged records for aggregation. Default value is 1.0. Example: Aggregation of 5s values to 15min. The 15min interval consists of 180 5s values. If quality is 0.9 then at least 162 of 180 values must be valid/available for aggregation. NOTE: The missing/invalid values could appear as block at the beginning or end of the interval, which might be problematic for some aggregation types

Example:

Channel A (channelA) is sampled and logged every 10 seconds.

Now you want a channel B (channelB) which contains the same values as channel A but in a 1 minute resolution by using the 'average' as aggregation type. You can achieve this by simply adding the aggregator driver to your channel config file and define a the channel B as follows:

The new (aggregated) channel has the id channelB. The channel address consists of the channel id of the original channel and the aggregation type which is channelA:avg in this example. OpenMUC calls the read method of the aggregator every minute. The aggregator then gets all logged records from channelA of the last minute, calculates the average and sets this value for the record of channelB. NOTE: It’s recommended to specify the samplingTimeOffset for channelB. It should be between samplingIntervalB - samplingIntervalA and samplingIntervalB. In this example: 50 < offset < 60. This constraint ensures that values are AGGREGATED CORRECTLY. At hh:mm:55 the aggregator gets the logged values of channelA and at hh:mm:60 respectively hh:mm:00 the aggregated value is logged.

Driver to connect an OpenMUC instance with an remote OpenMUC instance with REST.

Supported features:

Not supported features:

Example:

Connecting to an remote OpenMUC instance (192.168.8.18:8888) and reading the channel "power_grid" every 5s if the timestamp has changed.

Connects OpenMUC with an AMQP-Broker and writes the records from the queues to channels. Therefore this driver makes usage of our AMQP-Library, which is described in section [amqp-lib]. For configuration of the AMQP-Connection, the values from the following table have to be set in the channels.xml.

Parameter description:

Supported features:

Not supported features:

After starting this bundle, it connects to the configured amqp host. The example below is listening for the queue "SmartMeter_power_grid".

The MQTT-Driver connects OpenMUC to a MQTT-Broker. It enables OpenMUC to listen on topics and write records and messages to topics. The driver is based on our MQTT-Library, which is described in section [mqtt-lib]. For configuration of the MQTT-Connection, the values from the following table have to be set in the channels.xml.

Parameter description:

Parameters marked with [ ] are optional parameters.
NOTE: If optional parameters are used, then all parameters included in the brackets need to be specified (see grouping above).

To get a more clean looking channels.xml it is also possible to use line breaks instead of semicolons or a mix of both.

Supported features:

Not supported features:

After starting this bundle, it connects to the configured mqtt host. The example below is listening for the topic "SmartMeter/power_grid". It also uses firstWill and lastWill for sending connection status messages.

The AMQP library uses the RabbitMQ Java Client to connect to the broker.

The library consists of four classes:

It implements automatic connection recovery with message buffering. If only publishing (or consuming) is needed only the AmqpConnection and the AmqpReader (or AmqpWriter) needs to be instantiated.

The MQTT library uses the HiveMQ MQTT Client to connect to the broker.

The library consists of several classes with the most important listed below:

It implements automatic connection recovery with message buffering. Also LWT is supported with additional "first will" feature (see below). If only publishing (or subscribing) is needed only the MqttConnection and the MqttReader (or MqttWriter) needs to be instantiated.

Bundle: openmuc-lib-osgi

This library provides an API to make the usage of OSGi concepts more comfortable. Main goals are dynamic providing and subscription of OSGi services and their configuration.

The Parser-Service is part of the OpenMUC core SPI bundle and provides methods to serialize and deserialize OpenMUC records. It is used by the MQTT and AMQP logger but can be also used inside OpenMUC drivers and applications.

Key/Trust Store

To get the certificates of a server one can easily use a browser and click on the lock sign next to the URL to download it. Alternatively on *nix one can use the tool openssl:

Copy the needed certificates into a file i.e. cert.crt (beginning with -----BEGIN CERTIFICATE----- ending with -----END CERTIFICATE-----. Add them to the store:

The default password is changeme. We want to change that:

You can also import certificates from another store. Prefer importing over just using the other store directly as the store type needs to be PKCS#12.

Editing conf/keystore.jks is done analog to the Trust Store.

Edit /conf/system.properties to reflect the changes:

The servlet context root of the OpenMUC WebUI can be configured, by setting the org.apache.felix.http.context_path system property.

This must be a valid path starting with a slash and not ending with a slash (unless it is the root context).

You can access the WebUI over https as well: https://localhost:8889. To make the framework more secure you could disable http by setting org.apache.felix.http.enable in the conf/system.properties file to false.

You can include your own Plugins in the OpenMUC WebUI by creating a java class that extends the WebUiPluginService. This class also has to be annotated as a component. The two functions getAlias and getName have to be overridden. The alias is used to identify the plugin while the name will be displayed in the WebUI.

In order to display an icon above the plugins name, the file needs to be called icon and saved under samplePlugin/src/main/resources/images.

First you need a svg and assign all the svg Elements a unique id. You can include an external svg as an Object Element or you can create the svg directly in html. Either way the Element containing the svg needs an id which you can then use to access the svg in javascript.

Now you can manipulate the Elements of the svg, the easiest way to do this is through getElementById for a single Element or getElementsByClass for multiple Elements.

Aside from changing what is displayed you can also manipulate the css in this way. The following example would change the displayed texts color to blue.

In order to start the RESTful web service, the following bundle must be provided:

This bundles is already provided by the demo framework. The RESTful web service will start automatically with the framework without additional settings.

The latest record of a single channel can be accessed, by sending a GET request at the address: 'http://server-address/rest/channels/{id}' where {id} is replaced with the actual channel ID. The result will be latest record object of the channel encoded in JSON with the following structure:

You can access logged values of a channel by adding '/history?from=fromTimestamp&until=untilTimestamp' to the channel address, fromTimestamp and untilTimestamp are both milliseconds since Unix epoch (1970-01-01 00:00:00). The result is a collection of records encoded as JSON.

Additionally, the records off all available channels can be read in one go, by omitting the ID from the address. The result is a collection of channel objects encoded in JSON using this structure:

New records can be written to channels by sending a PUT request at the address that represents a channel. The data in the put request is a record encoded as specified in Record JSON above.

If HTTPS is used to access the REST server then HTTP basic authentication is required. The login credentials are the same as the one used to log into the web interface of the OpenMUC Framework.

The rest Server has the ability to handle CORS(Cross-Origin Resource Sharing). CORS is explained in detail here. Typically this functionality is needed when your browser sends an OPTIONS request instead of the request (f.e. GET, POST etc.) that you intended to send. Per default CORS is is deactivated for the rest Server. The functionality can be activated via the system.properties file located in the openmuc/framework/conf/ directory. If the following lines are not there add them.

The variable enable_cors activates or deactivates the support for CORS. The variables for url_cors, methods_cors, header_cors defines the allowed origins and the methods these origins are allowed to send to the server. Multiple origins are semicolon separated with the methods and headers separated by the same order as the origins. The methods and headers for each origin are then separated by comma. This means that in the above example the origin:

http://localhost:4200 is a trusted origin which is allowed to send GET and PUT requests and uses the headers Authorization and Content-Type.
http://localhost:8456 is a trusted origin which is allowed to send POST requests and uses the header Authorization.

The Apache Felix Web Console is a Web Based Management Console for OSGi Frameworks. You can use it e.g. for managing your OpenMUC framework bundle during runtime. For more information about the Web Console read the Felix Apache documentation. With this console you can also configure the configuration of all bundles which are using the openmuc-lib-osgi bundle or reconfigure the .

The default local link to the console is http://127.0.0.1:8888/system/console, the credentials are the same like in OpenMUC WebUI.