Installation HomeAssistant - OpenCCU/OpenCCU GitHub Wiki

You can install OpenCCU as a Home Assistant add‑on. 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 Intel NUC or as a virtual appliance on Proxmox VE, VMware ESXi, etc.

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

Note
If you already have a working OpenCCU on dedicated hardware or in a VM and you only want Homematic / Homematic IP devices to appear in Home Assistant, follow the Home Assistant Integration guide instead.

---

---

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 networking limitations in Home Assistant, the OpenCCU add‑on usually cannot communicate with a HmIP‑HAP range extender or HmIPW‑DRAP (Homematic IP Wired gateway). If you must support these devices, apply the macvlan patch to connect the add‑on directly to your LAN:

1. Reserve a static IP for the add‑on, outside your DHCP range: <IP-ADDRESS>.

2. Install the Advanced SSH & Web Terminal add‑on (https://github.com/hassio-addons/addon-ssh) and disable Protection mode so docker can be used within the terminal.

3. Ensure the OpenCCU add‑on is running and disable its watchdog. Note the internal container hostname (e.g., 5422eb72-openccu) — not the HA host name.

4. Run the patch in the HA host shell (via the SSH add‑on’s Web UI):

   wget -qO - https://raw.githubusercontent.com/OpenCCU/OpenCCU/master/scripts/patch-ha-addon-macvlan.sh | bash -

   The script auto‑detects interface, subnet, and gateway, then asks for the OpenCCU container hostname and the static <IP-ADDRESS>.

   Limitation
   The patch is not persistent across HA host reboots or add‑on restarts. Re‑apply the script after each reboot/restart until a future HA version adds native macvlan support for add‑ons.

5. After the patch, the OpenCCU WebUI is reachable at http://<IP-ADDRESS>/. Adjust the OpenCCU firewall in the WebUI as needed. Note that add‑on port settings no longer apply; the add‑on now connects directly to your LAN via macvlan.

---

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

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