Homematic Driver Summary

Last modified by David Nestle on 2019/05/14 12:37

This page mainly concentrales on the Homematic XML-RPC driver - for a detailed documentation see the HomeMaticXmlRpc page. The source code is available on Github in homematic-xmlrpc-hl (high level driver) and homematic-xmlrpc-ll (low level driver). The first homematic driver in projects hm-hl-driver and homematic-driver requires a USB hardware that is not available on the market anymore.

Removing Homematic devices from a gateway

1. Via app "Device configuration" select the device and delete via Button "Delete Resource"

2. For full removal you need to access the console of the Semabox (ask your administrator). Delete from directory opt/hm/etc/config/rfd the file that corresponds to the device

3. Afterwards the device should not be re-created after a re-start of the box. If the file is not deleted the device is most likely recreated on restart.

Data Models provided

see High Level Driver documentation.

The following homematic channels are already provided as part of the homematic driver (check source code for a most recent list):


Access more than one Homematic system or systems not built into gateway

For each homematic system to access a separate (usually toplevel) resource of type org.ogema.drivers.homematic.xmlrpc.hl.types.HmLogicInterface has to be set up. This is mainly relevant if Homematic and Homematic IP shall be used in parallel - see Section on Homematic IP below.

An example XML file to create such a resource is provided below. In your development rundir you can save the file in the replay-on-clean directory to let the system create the resources on a clean start. Usually only the address of the Homematic-base-process or the CCU has to be adapted in the clientUrl value (here: port value specified should be the HTTP port on which the OGEMA system is listening to receive callback messages from the Homematic system. This should usually not need to be changed on a development system. The networkInterface subresource can either be 'lo' (for loopback, Homematic process on same IP as OGEMA), 'wlan' or can be deactivated in order to let the driver find the right network itself (recommended for Microsoft Windows). If automated interface detection does not work, the respective IP and port can be given explicitly in the resource baseUrl, e.g. add the following to the homematic XML file used to create the homematic resource via replay-on-clean after the networkInterface entry. The following is an example for this:

   <resource xsi:type="og:StringResource">

The console commands can be called in the name space which is defined by the name of the configuration resource (here HomeMatic, see documentation of OSGi console commands below).

If you want to access more than one HomeMatic system from a single OGEMA instance the names of the toplevel resources have to be different, of course, and thus also the name spaces for console commands. Also the 'alias' entries should be different. Use only lower case letters here, the alias is used as URL path. Port 2001 is the standard for BidCos-RF, for HomeMatic-IP on a new CCU2 you should use port 2010 (the sema-box soes not yet support HomeMatic-IP).

Download XML resource file: homematic-config.ogx

Configure CCU3 for usage with OGEMA

The CCU3 does not open the port for the XML-RPC interface by default. You have to log into the CCU web interface and go to Einstellungen > Systemsteuerung -> Firewall konfigurieren and allow for full access to XML-RPC. You may also go to "Sicherheit" and disbable "Authentifizierung" (for XML-RPC).

Driver extensions

Note: An example extension bundle as source code is provided in https://github.com/ogema/tutorial/tree/master/src/homematic-sample-channel. For the development of a homematic driver extension it is recommended to configure a rundir on the development PC to connect to relevant homematic devices via a CCU2 or a semabox as described above. To access channels provided by the Homematic Lowlevel Driver directly there is also a special app available now in the ogema core repository at src/drivers/homematic-xmlrpc-cfg (expected for release 2.2.1). Note that the web interface of the app may only be accessible if a homematic connection could be started.

A HomeMatic device consists of a main or top level device which contains a hierarchy of sub devices called 'channels'. Sensor and actor control data is usually transmitted on channels, so most driver implementations actually do not identify top level devices directly and only work on channels which are identified by their device type. To implement a new device driver you have to provide an implementation of org.ogema.drivers.homematic.xmlrpc.hl.api.DeviceHandler, usually by extending AbstractDeviceHandler. See e.g. org.ogema.drivers.homematic.xmlrpc.hl.channels.IpShutterContact as example.
A new DeviceHandler implementation must then be registered in the OSGi framework with a DeviceHandlerFactory (this can be integrated into the class extending AbstractDeviceHandler as it is done in IpShutterContact. The OGEMA HomeMatic driver will build a list of all registered DeviceHandlerFactories, ordered by their OSGi service ranking (starting with the highest rank, see the @Component annotation in IpShutterContact source) and offer each available device or channel to all installed handlers until the first handler accepts the device. This way, there will be only one handler controlling a channel and generic handlers can be overridden by more specific ones.
One handler that the standard driver will activate for every device is the MAINTENANCE channel handler which reports basic information like reachability, signal quality or battery charge. What channels are available on which device can be learned from manufacturer documentation or directly from the driver. For EQ-3 devices, complete channel and parameter specifications are available as PDF (HomeMatic-Script Dokumentation, Teil 4 (german)).

Adding supported Homematic devices

  • Use an existing channel as template, e.g. IpShutterContact as explained above.
    The channels are not specific to Homematic or Homematic IP, but each device type is either a classic or IP device type. You can interchange templates, though. If you choose a template that contains the data points of your target device you may be able just to adapt the accept method and maybe make small adaptations to the channel names.
  • You have to identify parentType and type evaluated in the accept method.
    To do this, find the device in the entries returned by the <homematicType>:list command on the console (see information on the homematic console commands below if you fo not understand this). The first line should look like:
    <PARENT_TYPE> (v<X>) @ <DEVICE_ID>
    So you have the PARENT_TYPE for now. The TYPE can be derived from one of the (sub-)device names returned by list command. Usually it is the first sub-device that provides meausurement values and actor controls. If you know a similar device already you may be able to guess the right TYPE by checking if the same type is used in a similar device. Otherwise you have to check the sub devices with params <DEVICE_ID>:<N> for the values you want to provide in the OGEMA model.
  • You have to identify the read and write channels. For standard channels like temperature and humidity sensors usually most homematic devices use the same names. You can et the actual names with the params <device-name> command (see below). The main place of adapting/implementing this is the setup method.
  • Instead of the standard templates you can also use the adapted template in https://github.com/ogema/tutorial/tree/master/src/homematic-sample-channel. You just extend HmAbstractReadHandler for sensor devides and HmAbstractReadHandler for actor devices that also may include sensors. The required specifications for each supported channel type are methods to be overriden in HmReadChannel or HmWriteChannel. This is especially helpful for standard actor devices.
  • See ThermostatChannel.ParameterListener for an example how to set parameters that are not defined as VALUES, usually defined as MASTER. These cannot be set like VALUES as single values, but all parameters have to be read, a single value changed and all values rewritten.

Model Extensions

Typcially you either want to add suppoort for a new device type, which is done in the IpMotionDetector example. In the example case the same OGEMA resource model can be used that was already used for the standard Homematic motion detector, but if you want to add support for a new device type you have to find the appropriate device model in the OGEMA data models or develop a draft for a model extension. More information on this process can be fpund on the OGEMA Alliance Extensions page.

Another typical case is that you want to extend the data points supported for a homematic device that is already supported. The example ThermostatChannelExtended provides an example for this. If you only want to add a very small number of additional data points that are very specific for the respective driver and might not be relevant to be included into a general OGEMA data model you can just add decorators for this and document them in the Appstore or wiki documentation of your driver extension. You should still feed the extension into the modeling process to make sure that not other developers provide access to the same data points in an inconsistent way in the future.

OSGI console commands and examples

Additional information can be found in the Confluence OGEMA Open Source Wiki: https://www.ogema-source.net/wiki/display/OGEMA/Homematic+XML-RPC+debugging . This contains a documentation how to check and set the Auto/Manu mode of thermostats.

When the OGEMA HomeMatic XMLRPC driver is configured and connected it is also possible to explore all available devices with driver-specific commands on the OSGi console. For each HmLogicInterface resource in the system, the driver will install a set of commands using the HmLogicInterface resource name as command namespace (HomeMatic and hmiphelp for the default installation). For a documentation of the command line commands see the LowLever-Driver Documentation.

Connected HomeMatic devices along with all channels can be displayed with list (prefix with the namespace for the configuration):
G! hmip:list HMIP-eTRV (v1) @ 000393C991886D MAINTENANCE (v1) @ 000393C991886D:0 HEATING_CLIMATECONTROL_TRANSCEIVER (v1) @ 000393C991886D:1 HEATING_CLIMATECONTROL_RECEIVER (v1) @ 000393C991886D:2 HEATING_CLIMATECONTROL_CL_RECEIVER (v1) @ 000393C991886D:3 HEATING_SHUTTER_CONTACT_RECEIVER (v1) @ 000393C991886D:4 HEATING_ROOM_TH_TRANSCEIVER (v1) @ 000393C991886D:5 HEATING_ROOM_TH_RECEIVER (v1) @ 000393C991886D:6 HEATING_KEY_RECEIVER (v1) @ 000393C991886D:7 HmIP-SMI (v2) @ 0009156999C396 MAINTENANCE (v2) @ 0009156999C396:0 MOTIONDETECTOR_TRANSCEIVER (v2) @ 0009156999C396:1 HMIP-SWDO (v1) @ 0000D3C996014C MAINTENANCE (v1) @ 0000D3C996014C:0 SHUTTER_CONTACT (v1) @ 0000D3C996014C:1

Use params <address> to list all parameter sets for a single device/channel:

(help lists all available console commands)

Read / Write Specification

This is determined by the OPERATIONS flag: This is an Integer with an OR connection of possible operations: 1=Read, 2=Write, 4=Event

A value that can be read and will send its value as event (when changed / other events possible?) has OPERATIONS = 5, a value that can only be written has OPERATIONS = 2.
Values that have the OPERATIONS flag 0x04 set (i.e. have value 4,5,6 or 7) will be reported regularly or on change to all registered HmEventListeners, so listeners will need to filter events for unknown channels.

Examples for read / write via console

You can start boost mode for standard homematic like this:

HomeMatic:set NEQ1006648:4 BOOST_MODE true

Reading can be done for all values of a device like this:

HomeMatic:read NEQ1006648:4

The global MASTER parameters of the device can be obtained when not specifying a channel:

HomeMatic:params NEQ1006648

There is (probably) no possibility available yet to set such a parameter via the console. It can be done as Homematic driver extension as given in the example project, though.

The channels that have no data points are used for linking to other homematic devices. There is also an example in the sample project code for linking the thermostat to a temperature sensor.

Homematic IP

To use Homematic IP you have to create a separate top-level resource, e.g. named HomematicIP. The port in the the resource clientUrl must be set to 2010 instead of 2001 and if the "normal" Homematic driver is still configured a different alias has to be set. Note that currently starting the learn mode from OGEMA does not work for Homematic IP. This only works in the CCU - for using this on a Raspberry Pi together with OGEMA we recommend to install piVCCU. Devices that are connected via the CCU-webUI are automatically detected in OGEMA when the configuration of the resource is correct.

Update interval

Many classical Homematic sensors send data on each measuerment (e.g. every 2 to 3 minutes for room weather sensor). The motion detection sensor usually sends a value once per hour if not change in status is detected. The window sensor does not send data when no change of status is detected.

The Homematic IP room weather sensor has a default setting to skip 20 unchanged values before re-sending, so this may take up to one hour or maybe more. This can be changed in the CCU sensor configuration (or also via XML-RPC setting most likely). There is currently no information on the measurement frequency, so the minimum distance between new values shall be evaluated when suitable data is available.

Note that some value resources, especially in MAINTENANCE, are only created when the first value is received. Only after this time logging can be configured for such a resource in the activate-log-modus app.


This is already enough information to write a basic handler for HomeMatic-IP motion detectors: Accept devices of type MOTIONDETECTOR_TRANSCEIVER and register an HmEventListener that listens for events with ValueKey (HmEvent.getValueKey()) MOTION.

Created by David Nestle on 2017/05/11 14:35