angelnu/ccu repository overview

⁠docker-ccu

Homematic CCU firmware running as docker container on arm and (emulated) x86.

This project downloads the Homematic CCU2 firmware and re-package it as docker image. You can then start it on your raspi. Other ARM-based boards might also work (see Dependencies section). You can deploy on x86 but it will be slow and some components fail. I am working on a true multi-arch docker container for this.

An automated build pushes new docker images to Docker Hub⁠. You can check there the available versions.

Support for CCU2 has been removed from the HEAD. Please checkout the ccu2 branch⁠ if you need to build the CCU2 images. There is also another Docker Hub repository with old CCU2⁠ images.

⁠Features

• deploy original CCU firmware to Docker and kubernetes
  • addons, ssh and any other feature from the original CCU not listed under Not Working section⁠
• Homematic and Homematic IP supported (wired not tested)
• automatically install support for Homematic HW - thanks to Alex´s piVCCU proyect⁠
• partial multiarch:
  • builds on x86
  • runs on x86 but HMServer does not start
• displays Duty Cycle for CCU Gateways - thanks to Andreas and Jens⁠
• keep configuration in a remote location specified with the env variable PERSISTENT_DIR - you can use any location supported by rsync

⁠Not working

• Settings -> Control Panel -> Network Settings
• Display when there is a new CCU version available
• true multiarch dynamic docker
  • current multiarch is based on qemu
  • will use OCCU as base as done by this other project⁠
  • looking at USB adapter⁠ for dual stack with a single device
• automatically build new docker containers when new CCU versions are published by e3q.

⁠Dependencies

• Docker⁠
  • Kubernetes and Docker Swarm can be used for High Availability set ups. See the cluster section⁠ for more details.
• ARM HW. Following combinations tested for both Homematic and Homematic IP:
  • Raspberry with HM-MOD-RPI-PCB
  • Orange Pi Plus 2 with HM-MOD-RPI-PCB
  • OdroidXU4 with HM-LGW-O-TW-W-EU and HmIP-RFUSB
• One or more adapters to connect to the Homematic and/or Homematic IP devices
  • Homematic LAN GW for Homematic devices:
    • HM-LGW-O-TW-W-EU⁠
    • RaspberryMatic in LAN GW mode⁠
    • Docker computer and LAN GW need to be in the same network. No additional SW is needed in the docker computer. Connection is configured using the CCU web UI (settings -> LAN Gateway configuration)
  • Homematic USB IP adapter
    • HmIP-RFUSB⁠
    • the required kernel module is cp210x which is available in most Linux systems. The deploy.sh will add a udev rule to enable it automatically when plugged.
  • HM-MOD-RPI-PCB, RPI-RF-MOD, HB-RF-USB and emulated adapters
    • additional packages need to be installed in the host to support Homematic and Homematic IP in parallel. The required packages come from the piVCCU project⁠ which supports multiple ARM devices⁠
    • the deploy.sh script will try to install the pivccu packages for you. If it does not work please follow these instructions⁠ to install pivccu-modules-dkms, pivccu-devicetree-armbian (if you are on Armbian) and pivccu-modules-raspberrypi (if you use a Raspberry with Raspbian). You do not need to install a network bridge since docker manages that.

⁠How to deploy

1. ssh into the target computer (better an ARM device)
2. git clone this repository
3. (Optional) cp -a settings.template settings and edit settings.template
4. sudo ./deploy.sh
   • you can also use env variables such as MAYOR_CCU_VERSION=2 to deploy a CCU2 firmware. See settings.template⁠ for all available options

After the above steps you can connect to the :<port 80>. The CCU docker image will be restarted automatically when the computer boots: the container is started in auto-restart mode. With docker ps ccu you can see its status.

⁠How to build

This is only needed if you do not use the already built docker container.

1. git clone this repository
2. (Optional) cp -a settings.template settings and edit settings.template
3. sudo ./build.sh

⁠How to update to a new CCU firmware

1. git pull
2. ./pull.sh
3. ./deploy.sh

Optionally you can use the CCU_VERSION variable to select a particular version.

Your CCU settings will be preserved.

⁠How to import settings from an existing CCU

You can move your settings from an existing CCU into the docker CCU, either via ssh or using the native backup/restore support in the CCU (recommended).

If you use a HM-MOD-RPI-PCB and the Homematic is not working after restoring the backup then likely your old system was running without compatibility with Homematic IP. You need to use the new dual-stack mode. The easiest way to achieve that is to execute the following command: docker exec ccu sh -c "rm /etc/config/rfd.conf && /etc/init.d/S61rfd restart && cat /etc/config/rfd.conf". After this please check that Improved Coprocessor Initialization = true.

⁠Using the CCU UI (recommend)

1. log into you HW CCU web ui
2. go to Settings -> Security -> create backup
3. go into the the docker CCU web UI
4. go to Settings -> Security -> import backup

⁠Manually copying files

Please notice that this method does not support switch HW versions: to update from HW CCU2 to docker CCU you need to use the UI

1. Enable ssh in your CCU2. Instructions (in German) here⁠
2. ssh into your target computer
3. sudo ./undeploy.sh
4. rsync -av \[your CCU IP\]/usr/local/* /var/lib/docker/volumes/ccu_data/_data/
5. ./deploy.sh

⁠Cluster

You can deploy this docker container into a docker cluster with Kubernetes or Docker Swarm. This allows a High Available configuration where the home automation can stay up in the event of HW dying. This is usefull considering that a Raspberry is cheap so you should not depend on a single one to ensure your house stays warm ;-) .

⁠Kubernetes

You can check this example⁠ of a high available deployment. There I keep the configuration into a cluster persistent volume (glusterfs) so if one of computers is down then the CCU is "just" redeployed automatically into another available computer.

⁠Docker swarm

You can also deploy this docker image to a docker swarm. For this you need to:

• set up a docker swarm in multiple Raspberries. They all need to have local antennas at least you use a LAN gateway
• have a shared folder mounted at the same location in all the members of the cluster. Examples:
  • Mount a NAS folder. This is simple but then the NAS is the single point of failure
  • Cluster FS such as glusterfs. TBD: upload instructions

1. Change settings parameters
   • Set DOCKER_CCU_DATA to the absolute path of your shared folder. Example: _/media/glusterfs/ccu_
   • Set DOCKER_MODE to swarm
   • Set DOCKER_OPTIONS to --constraint node.labels.architecture==arm
2. ./deploy.sh