/emonmuc

Extension for the web application emoncms, based on the protocol driver framework OpenMUC

Primary LanguagePHPGNU Affero General Public License v3.0AGPL-3.0

emonmuc header

EmonMUC (energy monitoring multi utility communication) is based on the open-source project OpenMUC, a Java OSGi software framework, that simplifies the development of customized monitoring, logging and control systems. It can be used as a basis to flexibly implement anything from simple data loggers to complex SCADA systems. The OpenMUC framework is getting developed at Fraunhofer ISE and used as a basis in various smart grid projects. Among other tasks it is used in energy management gateways to readout smart meters, control CHP units, monitor PV systems and control electric vehicle charging. Therefore the OpenMUC framework includes mostly communication protocol drivers from the energy domain.

This project focuses on the easy setup and configuration of hardware such as household metering devices and the visualisation of collected data. All configurations of OpenMUC metering devices and further handling of monitored data is therefore managed by emoncms, an open-source web application for processing, logging and visualising energy, temperature and other environmental data. Utilizing emoncms possibility to add standalone extensions, a designated PHP module is part of this project, to configure the device communication within the emoncms web views and to incorporate as much helpful tooltips, descriptions and templates as possible, to allow an easy configuration of metering devices.

Features

This project is developed as an extension to emoncms and adds additional features to the versatile web application. In summary, those are the following highlights:

  • Easy application development: OpenMUC offers an abstract service for accessing data. Developers can focus on the applications logic rather than the details of the communication and data logging technology.

  • Modularity: Drivers, data loggers etc. are all individual components. By selecting only the components you need you can create a very light weight system.

  • Drivers: With a default installation, support for several popular communication protocols, e.g. Modbus TCP/IP and RTU.

  • Embedded systems: The framework is designed to run on low-power embedded devices. It is currently being used on embedded x86 and ARM systems. Because OpenMUC is based on Java and OSGi it is platform independent.

Installation

These setup instructions were documented for Debian Linux based platforms, specifically for a user pi on Raspbian buster, but may work for other Linux systems with slight adjustments to the setup script. Further guides may follow in the future.

The most comfortable installation solution provided by an installer, is currently developed by the OpenEnergyMonitor project.
To install the whole system, including a LAMP server and related packages, redis, mqtt and the home emoncms framework, a more detailed readme can be viewed here

To start the installation process, simply execute the initialization:

bash <(curl -s https://raw.githubusercontent.com/isc-konstanz/emonscripts/seal/install/init.sh)

With both components installed and running, the OpenMUC framework needs to be registered to the emoncms user. This can be done in the Controllers page, accessible from the Setup cogwheel menu item.

Select New controller and confirm the default settings, if the framework is running on the same machine.

Energy meters and other utility devices connected to the platform can now be configured in the Channels site, or automatically generated with an existing template through the Inputs site.

A more detailed installation guide, containing the separate steps that will be executed in the setup script, can be found here:

Configuration

For the framework to be able to post values to emoncms, a few parameters are necessary to be configured. All settings can be found in the emoncms.conf.
Defaults for all parameters can be found in emoncms.default.conf.

cp /opt/emonmuc/conf/emoncms.default.conf /opt/openmuc/conf/emoncms.conf
nano /opt/openmuc/conf/emoncms.conf

  • The web servers location may be changed. By default, it is commented and points to an emoncms sever at http://localhost/emoncms/, e.g. VPN addresses or the remote emoncms.org server can be a valid selection though.

    # URL of emoncms web server, used to post data
address = http://localhost/

  • A default authentication for emoncms may be configured. While each data channel can be configured to have its own credentials, it may be preferable to group them with the same authentication, as this improves bulk posting and hence reduced traffic. To do this, uncomment the lines related to authorization and authentication, and enter the users Write Api Key

    # API Key credentials to authorize communication with the emoncms webserver
authorization = WRITE
authentication = <apiKey>

  • The maximum allowed threads for the emoncms logger to post values simultaniously to the specified webserver may be configured, if the configured server and the platform supports or needs higher traffic

    # Set the maximum amount of HTTP requests running asynchronously. Default is 1  
;maxThreads = 1

After changing any of the configurations, a restart of the framework is currently still necessary for the changes to take effect

sudo systemctl restart openmuc

Drivers

With a default installation, no drivers are enabled and need to be installed separately. As a first step, a set of protocol drivers ought to be used should be selected.
This can be done with their unique ID, e.g. to install the CSV driver:

emonmuc install csv

To disable the driver, use

emonmuc remove csv

Several drivers can be enabled at once, while each needs to be selected individually. A list of possible integrated drivers are:

Details about drivers and specific information about their usage and configuration may be found by clicking corresponding links or for most of them in the OpenMUC User Guide.

As prompted after installing one or several drivers, a restart of the framework is currently still necessary for the changes to take effect

sudo systemctl restart openmuc

Serial Port

To use any serial port with the emonmuc framework, e.g. to communicate via Modbus RTU, the open-source project jRxTx is used. This, as well as some additional steps if the UART Pins of the Raspberry Pi Platform should be used, need to be prepared.
The Serial Port preparation guide may be followed to do so.

Guides

With the system being prepared, some first steps can be taken to learn about the features of emonmuc.
For this purpose, some guides were documented to be followed,

To get accustomed with some of the drivers or the general emonmuc framework, a set of specified guides were written:

Contact

To get in contact with the developers of the OpenMUC project, visit their homepage at openmuc.org.
This fork is maintained by:

ISC logo