Installation HomeAssistant - OpenCCU/OpenCCU GitHub Wiki

You can install OpenCCU as a Home Assistant App. In this mode, OpenCCU runs as a lightweight virtual appliance (Docker‑based) inside Home Assistant OS or within a Home Assistant Supervised setup. As with hardware installations, Home Assistant OS can itself run on various systems—from a Raspberry Pi to an Generic x86_64 or as a virtual appliance under Proxmox VE or other similar virtualization environments.

Running OpenCCU as HA-App embeds the full CCU functionality directly into Home Assistant and let it run alongside other HA integrations (e.g., Philips Hue, Sonos). It also benefits from HAOS features such as snapshots.

---

Depending on your platform, perform the following preparations before installing the HA add‑on.

1. Install / verify HAOS ≥ 7.3
   Make sure you run Home Assistant OS 7.3 or newer. Downloads: https://github.com/home-assistant/operating-system/releases

2. Enable GPIO support (only for GPIO‑attached RF modules)
   Required only if you plan to use an RPI‑RF‑MOD or HM‑MOD‑RPI‑PCB on GPIO. Not required when using HB‑RF‑USB, HB‑RF‑USB‑2, HB‑RF‑ETH, HmIP‑RFUSB, or HmIP‑RFUSB‑TK.

   • Access the boot partition (/mnt/boot) to edit the configuration:
     Mount the card/SSD in a PC, or use SSH to the host, or attach monitor+keyboard for a console login.
   • Raspberry Pi — edit /mnt/boot/config.txt and uncomment the following lines:

     # Enable GPIO support for RPI-RF-MOD/HM-MOD-RPI-PCB
     enable_uart=1
     dtparam=i2c_arm=on
     dtoverlay=miniuart-bt
     dtoverlay=rpi-rf-mod

   • Tinker Board / ODROID — edit /mnt/boot/haos-config.txt and uncomment:

     # Enable GPIO support for RPI-RF-MOD/HM-MOD-RPI-PCB
     overlays=rpi-rf-mod

   • Reboot the HAOS host to apply changes.

If you run Home Assistant Supervised on a Linux host, prepare the system to support RPI‑RF‑MOD, HM‑MOD‑RPI‑PCB, HmIP‑RFUSB/HmIP‑RFUSB‑TK as well as the HB‑RF‑USB, HB‑RF‑USB‑2, or HB‑RF‑ETH adapters.

1. Install piVCCU kernel modules

   sudo apt install wget ca-certificates build-essential bison flex libssl-dev gpg
   wget -qO - https://apt.pivccu.de/piVCCU/public.key | sudo gpg --dearmor -o /usr/share/keyrings/pivccu-archive-keyring.gpg
   echo "deb [signed-by=/usr/share/keyrings/pivccu-archive-keyring.gpg] https://apt.pivccu.de/piVCCU stable main" | sudo tee /etc/apt/sources.list.d/pivccu.list
   sudo apt update
   sudo apt install raspberrypi-kernel-headers pivccu-modules-dkms

2. Raspberry Pi with GPIO‑attached RF module (skip if you use HB‑RF‑USB / ‑2, HB‑RF‑ETH, or HmIP‑RFUSB/‑TK):

   • Install device‑tree patches:

     sudo apt install pivccu-modules-raspberrypi

   • Disable Bluetooth:

     sudo bash -c 'cat <<EOT >>/boot/config.txt
     dtoverlay=pi3-disable-bt
     EOT'
     systemctl is-active --quiet hciuart.service && sudo systemctl disable hciuart.service

   • Disable serial console:

     sudo sed -i /boot/cmdline.txt -e "s/console=\(serial0\|ttyAMA0\),[0-9]\+ //"

3. Load eq3_char_loop at boot

   echo eq3_char_loop | sudo tee /etc/modules-load.d/eq3_char_loop.conf
   sudo service pivccu-dkms start
   sudo modprobe eq3_char_loop

4. Supervisor / kernel caveats

   • cgroup v2: If Supervisor logs show
     Can't set cgroup permission on the host for addon_XXXX_openccu, switch to cgroup v1 by adding to /etc/default/grub:

     GRUB_CMDLINE_LINUX_DEFAULT="quiet systemd.unified_cgroup_hierarchy=false"
     

     Then run sudo update-grub. On Raspberry Pi, add systemd.unified_cgroup_hierarchy=false to /boot/cmdline.txt. Other boards require the equivalent bootloader setting.
   • RT scheduler limit (CONFIG_RT_GROUP_SCHED=y): If addons receive no real‑time runtime (breaking multimacd), disable the limit:

     sudo sysctl -w kernel.sched_rt_runtime_us=-1
     echo "kernel.sched_rt_runtime_us = -1" | sudo tee /etc/sysctl.d/10-disable-rt-group-limit.conf

---

Prerequisite: a working Home Assistant OS or Supervised installation.

1. Open the Add‑on Store
   In the HA UI (http://homeassistant.local:8123/), go to
   Configuration → Addons, Backups & Supervisor → Add‑on Store
   and click the ⋮ menu (top‑right) → Repositories.
   

2. Add the OpenCCU repository
   Add this URL as an extra add‑on repository:
   https://github.com/OpenCCU/OpenCCU
   

3. Open the OpenCCU add‑on
   Close the “Manage add‑on repositories” dialog, scroll to the section “Home Assistant OpenCCU Add‑on”, and select “OpenCCU CCU”.
   

4. Install the add‑on
   Click INSTALL to install the OpenCCU add‑on.
   

5. Pin to sidebar & start
   After installation, enable Show in sidebar for quick access to the CCU WebUI, then click START. You can follow the startup progress in the Log tab (hostname, CPU/RAM usage).
   

6. Expose additional API ports (optional)
   To make CCU XML‑RPC / scripting APIs reachable from other hosts, open the Configuration tab of the add‑on and configure the desired ports.
   

7. Open the CCU WebUI
   Click the new OpenCCU entry in the HA sidebar to launch the standard CCU WebUI.
   

Once the add‑on is running, you can import an existing configuration, teach‑in devices (depending on your RF/wired hardware), and use OpenCCU as you would on dedicated hardware.

---

To make your Homematic / Homematic IP devices available as HA entities, add the integration in HA after the add‑on is working. Follow the step‑by‑step instructions in Home Assistant Integration.

---

Because of Docker-related networking limitations in Home Assistant Apps, the OpenCCU HA-App cannot communicate with a HmIP‑HAP as a range extender or with a HmIPW‑DRAP as a HomematicIP Wired gateway. However, if you still require support for these devices, there is a dedicated OpenCCU HAP/DRAP-Helper HA-App that you can install alongside the normal OpenCCU HA-App. When kept running in parallel to the normal OpenCCU HA-App, this HAP/DRAP-Helper App will ensure that the running OpenCCU App Docker container gets a dedicated LAN IPv4 address assigned and routing tables setup so that the OpenCCU HA-App will be able to communicat with a HmIP-HAP or HmIPW-DRAP device.

To setup this special OpenCCU HAP/DRAP-Helper App, please perform the following steps:

1. Install and start the regular "OpenCCU" HA-App (see OpenCCU HA-App installation
2. Additionally install the OpenCCU HAP/DRAP-Helper HA-App from the same repository.
3. Set the "OpenCCU IP" config option in the HAP/DRAP-Helper App to a free, dedicated and static IPv4 address of your LAN.
4. Ensure to disable the "Protection Mode" for this helper app.
5. Enable "Start on boot" in the helper app configuration and also enable the WatchDog functionality to ensure that the Helper-App will be automatically restarted.
6. Start the OpenCCU HAP/DRAP-Helper HA-App to keep it running.
7. Start the normal OpenCCU HA-App and check the Log of the Helper-App to see if it can correctly assign the IPv4 address.
8. Try to access the OpenCCU HA-App WebUI via the specified IPv4 address (e.g. http://<IP-ADDRESS>/) and adjust the OpenCCU firewall in the WebUI as needed. Note, that OpenCCU App port settings no longer apply; the App now connects directly to your LAN via the setup IPv4 address.

After these steps, the OpenCCU HA-App should be able to correctly communicate with your teached-in HmIP-HAP or HmIPW-DRAP devices.

---

If you need more guidance on installing the add‑on:

• YouTube (🇩🇪) — “OpenCCU AddOn auf Home Assistant installieren und einrichten 2022”