Skip to content

Homematic Controller

Thomas Letsch edited this page Apr 15, 2014 · 1 revision



The controller "speaks" with the HomeMatic devices through the properiatry wireless protocol of HomeMatic.


The best supported hardware so far for HomeMatic is the CCU 1.


The second version (beginning with mid 2013) should work in most circumstances, but is not as widely used as the first version. We need testers here: If you own a CCU2, please try out the latest 1.4.0 nightly releases!

LAN Adapter

One of the cheaper alternatives is to use the HomeMatic LAN Adapter. The LAN Adapter requires the BidCos-Service running and listening on a specific port in your LAN. As of this writing the BidCos-Service is only available for Microsoft Windows. If you want to run the BidCos-Service 'natively' (through Qemu) on Linux without messing around with Wine follow these step by step instructions.

  1. Install QEMU (If you are running OpenHAB on i386/amd64)

    In order to run the BidCos-Service daemon 'rfd' under linux you need to install the QEMU arm emulation. If you are using Debian you have to install at least the package qemu-system-arm.

    apt-get install qemu
  2. Download the latest CCU 2 firmware from eQ-3 homepage

  3. Extract the downloaded firmware e.g. HM-CCU2-2.7.8.tar.gz

    mkdir /tmp/firmware
    tar xvzf HM-CCU2-2.7.8.tar.gz -C /tmp/firmware

    You should now have three files under the directory /tmp/firmware

    rootfs.ubi    (<-- this is the firmware inside a UBIFS iamge)
  4. Create an 256 MiB emulated NAND flash with 2KiB NAND page size

    modprobe nandsim first_id_byte=0x20 second_id_byte=0xaa third_id_byte=0x00 fourth_id_byte=0x15

    You should see a newly created MTD device /dev/mtd0 (assume that you do not have other MTD devices)

  5. Copy the contents of the UBIFS image rootfs.ubi to the emulated MTD device

    dd if=rootfs.ubi of=/dev/mtd0 bs=2048
  6. Load UBI kernel module and attach the MTD device mtd0

    modprobe ubi mtd=0,2048
  7. Mount the UBIFS image

    mkdir /mnt/ubifs
    mount -t ubifs /dev/ubi0_0 /mnt/ubifs
  8. Copy the required files to run the BidCos-Service from the UBIFS image

    mkdir -p /etc/eq3-rfd /opt/eq3-rfd/bin /opt/eq3-rfd/firmware
    cd /mnt/ubifs
    cp /mnt/ubifs/bin/rfd /opt/eq3-rfd/bin
    cp /mnt/ubifs/etc/config_templates/rfd.conf /etc/eq3-rfd/bidcos.conf
    cp -r /mnt/ubifs/firmware/* /opt/eq3-rfd/firmware/

    List the dependencies for rfd binary

    qemu-arm -L /mnt/ubifs /mnt/ubifs/lib/ --list /mnt/ubifs/bin/rfd

    You should see an output like this => /lib/ (0xf67a7000) => /lib/ (0xf6786000) => /lib/ (0xf6733000) => /lib/ (0xf6725000) => /lib/ (0xf66fc000) => /lib/ (0xf66d2000) => /lib/ (0xf66bf000) => /usr/lib/ (0xf65e8000) => /lib/ (0xf6542000) => /lib/ (0xf63f7000) => /lib/ (0xf63ce000)
    /lib/ => /mnt/ubifs/lib/ (0xf6fd7000)

    Copy all the listed libs from /mnt/ubifs to there respective folder at /opt/eq3-rfd

  9. Create a system user and adjust permissions

    adduser --system --home /opt/eq3-rfd --shell /bin/false --no-create-home --group bidcos
    chown -R bidcos:bidcos /opt/eq3-rfd
  10. Edit and adjust the BidCos-Service configuration bidcos.conf

    # TCP Port for XmlRpc connections
    Listen Port = 2001
    # Log Level: 1=DEBUG, 2=WARNING, 3=INFO, 4=NOTICE, 5=WARNING, 6=ERROR
    Log Level = 3
    # If set to 1 the AES keys are stored in a file. Highly recommended.
    Persist Keys = 1
    Address File = /etc/eq3-rfd/ids
    Key File = /etc/eq3-rfd/keys
    Device Files Dir = /etc/eq3-rfd/devices
    # These path are relative to QEMU_LD_PREFIX
    Device Description Dir = /firmware/rftypes
    Firmware Dir = /firmware
    Replacemap File = /firmware/rftypes/replaceMap/rfReplaceMap.xml
    # Logging
    Log Destination = File
    Log Filename = /var/log/eq3-rfd/bidcos.log
    [Interface 0]
    Type = Lan Interface
    Serial Number = <HomeMatic ID e.g. JEQ0707164>
    Encryption Key = <your encryption key>
  11. Start the BidCos-Service daemon 'rfd'

    The BidCos-Service daemon 'rfd' can now be started with the following command

    qemu-arm -L /opt/eq3-rfd /opt/eq3-rfd/bin/rfd -f /etc/eq3-rfd/bidcos.conf


The other cheaper alternative is the CUL stick. The CUL is an USB stick that can be used as a wireless transceiver. It ca be programmed to be used with a hughe amount of wireless protocols, under which you can find the homemtic protocol as well. Since the CUL is not natively supported by the binding, you need a program to translate the CUL data to the CCU XML RPC interface: Homegear

We have reports from users that succesfully use both for their homemtic devices. Apparently security is still not supported.

feature overview


Setup intro

Linux and OS X





User Interfaces



(link to openHAB forum)



Application Integration



A good source of inspiration and tips from users gathered over the years. Be aware that things may have changed since they were written and some examples might not work correctly.

Please update the wiki if you do come across any out of date information.

Binding configurations

Use case examples

Item definition examples

Sitemap definition examples

Collections of Rules on a single page

Single Rules


Syntax highlighting for external editors

Release Notes

Clone this wiki locally
You can’t perform that action at this time.