This project implements a communication protocol as part of emonmuc (energy monitoring multi utility communication), based on the open-source project OpenMUC, a software framework based on Java and OSGi, that simplifies the development of customized monitoring, logging and control systems.

HomeMatic by eQ-3 is a Smart Home System, operating on 868-MHz. At this relatively low frequency, highly stable transmissions over several 100m are possible with the signal being immune to disturbances from Wifi or similar radio signals.

This project is based on the OGEMA project and allows to read and control HomeMatic devices inside the emonmuc framework, allowing them to be controlled by other applications or energy management systems. To enable communication over 868-MHz, the installation of a radio transceiver is necessary.
Recommended and tested hardware are e.g. CC1101 RF transceivers:

• CC1101 USB Lite (CUL) module
• Stackable CC1101 (SCC) module for Raspberry Pi

To flash and prepare the SCC module, a comprehensive firmware installation guide may be followed.

To setup this protocol driver, emonmuc needs to be installed. To do so, a comprehensive guide is provided on the projects GitHub page.

With emonmuc being installed, the driver may be enabled

emonmuc install homematic-cc1101

To disable the driver, use

emonmuc remove homematic-cc1101

This shell command will automatically set up the driver. If there is the need to manually install the driver, a separate installation guide may be followed.

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

For the Stackable CC1101 (SCC) module for the Raspberry Pi, the GPIOs 0 and 1 needs to be set. This is done with the Pi4J library, that links to the Wiring Pi debian package. To prepare it, the Wiring Pi preparation guide needs to be followed.

Depending on the RF transceiver used, some additional configurations may be necessary.
This can be done in the OSGi frameworks system properties, located by default in /opt/emonmuc/conf/system.properties. Add any of the optional properties like this:

# Define the hardware interface used: <SCC/CUL>. Default is SCC
org.openmuc.framework.driver.homematic.interface = CUL

# If the CUL interface is used, the serial port of the stick needs to be defined. Default for CUL is /dev/ttyUSB0
;org.ogema.driver.homematic.serial.port = /dev/ttyACM0

Both hardware interface communication options SCC and CUL are serial connections.
The property org.ogema.driver.homematic.serial.port defines the port to be used. For CUL the default value of the port is /dev/ttyUSB0. For SCC, the default value of the port is /dev/ttyAMA0.

Additionally, the transceivers ID, used to pair and identify itself with HomeMatic devices, may be chosen.
The property org.openmuc.framework.driver.homematic.id allows to set this ID, which can be an arbitrary string of 6 characters. The default value is F11034.

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

With the protocol driver being enabled, some first steps can be taken to learn about the features of this project.
For this purpose, a First Steps guide was documented to be followed.

To provide an entrypoint for further developments, a generated javadoc can be visited. A description of system resources and a rough architecture overview got documented in the Development site and is encouraged to be read.
For other questions or initiatives please don't hesitate to file an issue or get into contact directly.

Currently, only a set of HomeMatic devices are supported and provided with templates to be created with the emoncms device module. While others should work as well, the only tested devices are:

• Switch Actuator (with power metering):
  • HM-ES-PMSw1-Pl
• Thermostat:
  • HM-CC-RT-DN
• Temperature/Humidity Sensor:
  • HM-WDS30-T-O
  • HM-WDS40-TH-I-2

This project is maintained by:

• ISC Konstanz (International Solar Energy Research Center)
• Adrian Minde: [email protected]