en.Installation

Once the necessary hardware and software requirements for installing OpenCCU have been checked and met, you can proceed with the actual installation. The procedure differs depending on the hardware platform used; therefore, the installation is explained for each platform separately as a step-by-step guide in the following sections. Users of a CCU3 or ELV-Charly can alternatively install the more conservatively updated OpenCCU-LTS.

For the impatient or advanced CCU/Homematic/Linux users, the following quick start guide explains the basic steps, which can be found in a similar form in every platform-specific guide:

When using CCU3 hardware:

1. Download the latest version as an OpenCCU-X.XX.XX.YYYYMMDD-ccu3.tgz archive from Releases (or, for OpenCCU-LTS, the OpenCCU-LTS-X.XX.XX.YYYYMMDD-ccu3.tgz archive from OpenCCU-LTS Releases).
2. Log in to the WebUI of the running CCU3.
3. Under Settings → Control panel → CCU maintenance, select the downloaded *.tgz file like a regular firmware update via Choose File… and then start the installation via Upload.
4. OpenCCU is then installed on the CCU3 hardware and ready for use.

When using a single-board computer (Raspberry Pi, ELV-Charly, ODROID, ASUS Tinker Board 2/2S) or a generic x86_64/aarch64 system:

1. Write the appropriate image to a suitable microSD card, USB stick or SSD (at least 8 GB):

   • Raspberry Pi: The easiest way is to use the Raspberry Pi Imager: select the Raspberry Pi model used and then OpenCCU as the operating system.

   • All platforms: Download the latest version as an OpenCCU-X.XX.XX.YYYYMMDD-ZZZ.zip archive from Releases, extract it and write the included *.img file using an imaging tool (e.g. Raspberry Pi Imager via "Use custom"). ZZZ corresponds to the target platform:

     Platform	ZZZ
     Raspberry Pi 5	rpi5
     Raspberry Pi 4/400/CM4	rpi4
     Raspberry Pi 3/3+/3 A+/CM3, Raspberry Pi Zero 2 W, ELV-Charly	rpi3
     ODROID-N2/N2+, ODROID-C4, ODROID-C2	odroid-n2, odroid-c4, odroid-c2
     ASUS Tinker Board 2/2S	tinkerboard2
     Generic x86_64 (UEFI)	generic-x86_64
     Generic aarch64 (UEFI)	generic-aarch64

2. Insert the storage medium into the device.
3. Connect a suitable Homematic / Homematic IP radio module via GPIO or USB.
4. Power up the device – OpenCCU starts and boots up.

When using a virtualization environment (Proxmox VE, VMware ESXi, VirtualBox, etc.):

1. Download the latest version as OpenCCU-X.XX.XX.YYYYMMDD.ova from Releases (not the *-ova.zip file, which is only required for later updates via the WebUI). For Proxmox VE, an installation script is available as an alternative; for ARM-based hypervisors, use the *-generic-aarch64.zip image.
2. Import the *.ova file in the administration interface of the virtualization environment and adjust the basic settings of the virtual OpenCCU VM.
3. Connect a suitable Homematic / Homematic IP radio module via USB to the host and pass it through to the VM (or connect an HB-RF-ETH via the network).
4. Start the VM – OpenCCU boots up and is then accessible via the WebUI.

When using a container or the Home Assistant app:

• Docker/OCI: Installation and updates via the install-docker.sh script, see Docker Container (OCI).
• LXC: Installation and updates via the install-lxc.sh script, see Linux Container (LXC).
• Kubernetes: Installation via the openccu Helm chart, see Kubernetes/K8s.
• Home Assistant: Installation of the "OpenCCU" app from the "OpenCCU Apps" app repository, see Home Assistant App.

In the container variants, updates are performed via the respective platform and not via the update function of the WebUI.

More detailed installation guides for all supported platforms can be found in the following sections. After the installation, the first steps after installation help with the basic setup.

The following sections describe how to install and run OpenCCU on dedicated hardware:

• CCU3
• ELV-Charly
• Raspberry Pi – Raspberry Pi 5, Raspberry Pi 4/400/CM4, Raspberry Pi 3/3+/3 A+/CM3 as well as Raspberry Pi Zero 2 W
• Hardkernel ODROID – ODROID-N2/N2+, ODROID-C4, ODROID-C2
• ASUS Tinker Board 2/2S
• Generic x86_64 – standard x86_64 systems (e.g. Intel NUC) with UEFI boot
• Generic aarch64 – standard ARM64 systems with UEFI boot

In addition to installing on real hardware, OpenCCU can be run in modern virtualization environments and used together with a suitable USB or network-based Homematic radio module:

• as a virtual machine on x86_64 hypervisors (e.g. Proxmox VE, VMware ESXi, VirtualBox, Synology VMM) using the *.ova archive, which can be imported into common virtualization solutions with just a few clicks, or on ARM-based hypervisors using the *-generic-aarch64.zip image,
• as a container (Docker/OCI, LXC, Kubernetes) on amd64 or arm64 host systems,
• as an app within Home Assistant.

This is described separately for each supported platform below:

• Proxmox Virtual Environment
• Home Assistant App
• Docker Container (OCI)
• Linux Container (LXC)
• QEMU/KVM
• Kubernetes/K8s
• Synology Virtual Machine Manager
• QNAP Virtualization Station
• Unraid
• XCP-ng/XenServer
• Oracle VirtualBox
• VMware ESXi
• VMware Workstation Player
• Hyper-V

Once the basic installation on your own hardware or in a virtualization environment has been completed successfully – and if you already have another or older CCU central unit from eQ-3/ELV – the following sections show how to transfer the existing configuration.

Due to the extensive compatibility between the operating system/firmware used on the CCU3 and OpenCCU, manual adjustments are usually only necessary when switching from a CCU3 firmware to OpenCCU if you switch directly to a virtual OpenCCU system. More information on switching to a virtual OpenCCU can be found here.

If OpenCCU has been installed directly on the existing CCU3 hardware according to the installation guide, the configuration including installed CCU add-ons should have been transferred automatically – no further steps are required. If, on the other hand, you switch from the CCU3 hardware to another hardware platform (e.g. Raspberry Pi, ODROID), the system backup (*.sbk) previously exported via the CCU3 WebUI can be imported via the OpenCCU WebUI after the fresh basic installation. No further steps are necessary.

When upgrading from an older CCU2 with firmware version 2.x to OpenCCU, a few points need to be considered. Since a direct switch from a CCU2 firmware to a current OpenCCU version can cause problems, the transfer takes place in two stages via an intermediate version whose version level is closest to the latest CCU2 firmware. This also applies to LXCCU, YAHM and piVCCU2:

1. Before transferring the configuration, make sure that the latest CCU2 firmware (2.59.7) is installed on the old CCU2.
2. Log in to the WebUI of the old CCU2 and create a backup (*.sbk) of the configuration under Settings → Control panel → Security → Create backup and keep it in a safe place.
3. Write down all additional software packages (CCU add-ons) listed under Settings → Control panel → Additional software, since these must be reinstalled manually in an OpenCCU-compatible version later (after transferring the configuration to OpenCCU).
4. Now go through the list of additional software packages/CCU add-ons under Settings → Control panel → Additional software and uninstall all of them. Exceptions (do not uninstall, otherwise configuration will be lost; these can be reinstalled later in step 13):
   • CUxD
   • JP-HB-Devices-addon
   • HB-TM-Devices-AddOn
5. Create another backup (*.sbk) under Settings → Control panel → Security → Create backup and keep it temporarily.
6. Shut down the old CCU2 and disconnect it from power (must not run in parallel to OpenCCU!).
7. Install the intermediate version 3.59.6.20211009 (released at that time under the name "RaspberryMatic") – e.g. as a temporary virtual machine using the *.ova file provided there or on a separate SD card – and import the backup created in step 5 (without add-ons) under Settings → Control panel → Security → Import backup.
8. After the restart triggered by the backup, check whether the configuration (devices, programs, system variables) has been transferred completely, and then create a new backup (*.sbk) in the intermediate version under Settings → Control panel → Security → Create backup.
9. Shut down the intermediate version.
10. Completely clear the browser cache of the browser used and restart the browser.
11. Log in to the WebUI of the freshly installed, current OpenCCU and import the backup created in step 8 under Settings → Control panel → Security → Import backup.
12. After the restart triggered by the backup, reconnect to the WebUI and check under Settings → Control panel → Time-/position settings → NTP server that valid NTP servers are configured, e.g.:

    0.de.pool.ntp.org 1.de.pool.ntp.org 2.de.pool.ntp.org 3.de.pool.ntp.org
    

13. Go through the add-on list noted in step 3 via the WebUI and install all add-ons in their respective OpenCCU-compatible version to restore the previous functionality.
14. Finally, restart OpenCCU again. Afterwards, login and WebUI with the previous credentials as well as all Homematic devices, programs, etc. should be available again. If this unexpectedly does not work, the first backup (before uninstalling the add-ons) can be restored on the old CCU2. Please note: depending on the existing programming, an increased duty cycle (i.e. radio utilization) may occur after startup. It may take > 1 h until communication errors with certain Homematic devices disappear.

Due to the very large version jump from a CCU1 to a current OpenCCU, a complete new setup is recommended (remove all Homematic devices, perform a factory reset, pair them with OpenCCU again and reconfigure them).

If you want to switch directly from an older CCU2/CCU3 or from a hardware-based OpenCCU to a virtual OpenCCU – or generally move OpenCCU to another platform (e.g. from a Raspberry Pi to Proxmox VE or from an SD card to an SSD) – proceed as follows:

1. First, make sure according to the respective basic installation guide that the new OpenCCU boots up properly and the WebUI is accessible.
2. In the old installation/central unit, create and download a system backup (*.sbk) under Settings → Control panel → Security → Create backup.
3. Go through the list of additional software packages/CCU add-ons under Settings → Control panel → Additional software and uninstall all of them. Exceptions (do not uninstall, otherwise configuration will be lost; these can be reinstalled later in step 8):
   • CUxD
   • JP-HB-Devices-addon
   • HB-TM-Devices-AddOn
4. Create another backup (*.sbk) and keep it temporarily.
5. Deactivate the old CCU central unit or disconnect it from power – never run two CCU central units with an identical configuration in parallel!
6. If no USB or network-based radio module (e.g. HB-RF-USB-2, HmIP-RFUSB, HB-RF-ETH) is connected to the new OpenCCU yet, do this according to the installation guide of the respective platform.
7. Log in to the WebUI of the new OpenCCU and import the backup (without add-ons).
8. Afterwards, reinstall all previously manually uninstalled CCU add-ons. Important: check beforehand whether the add-ons are available for the target architecture (x86_64 or aarch64). Add-ons compiled for 32-bit ARM usually continue to run on 64-bit ARM systems thanks to the integrated 32-bit support, but not on x86_64 systems.
9. Finally, restart the new OpenCCU. Note: depending on the existing programming, an increased duty cycle (i.e. radio utilization) may occur after startup. It may take > 1 h until communication errors with certain Homematic devices disappear.

If you want to switch the control of your Homematic / Homematic IP devices from the now heavily outdated FHEM home automation platform directly to OpenCCU, you can use the separate Migration from FHEM quick guide in this documentation wiki.

Due to the renaming of "RaspberryMatic" to "OpenCCU" in October 2025 with version 3.83.6.20251025 – including internal changes in the firmware – the switch is not possible via the automatic update. This means: anyone who wants to "update" an existing RaspberryMatic installation to OpenCCU must do this once manually.

For installations on hardware (Raspberry Pi, CCU3, ELV-Charly, ODROID, etc.) or as a virtual machine (OVA), proceed as follows:

1. Download the appropriate update archive for the platform currently used from Releases (e.g. OpenCCU-X.XX.XX.YYYYMMDD-rpi3.zip for CCU3/ELV-Charly/Raspberry Pi 3 or OpenCCU-X.XX.XX.YYYYMMDD-ova.zip for virtual machines).
2. In the RaspberryMatic WebUI, open Settings → Control panel → CCU maintenance → Choose File…, upload the archive and start the firmware update.
3. After the successful update, OpenCCU is installed. Future updates can be installed again as usual via the automatic update function.

For the container variants, the following applies:

• Docker/OCI: Run the install-docker.sh script again according to the installation guide. It uses the same container (ccu) and volume name (ccu_data) as before, but replaces the previous RaspberryMatic image with the OpenCCU image ghcr.io/openccu/openccu. The configuration is preserved.
• LXC: Install a new OpenCCU container according to the installation guide and transfer the configuration via a backup (*.sbk) from the old RaspberryMatic container.
• Kubernetes: Switch to the openccu Helm chart according to the installation guide and transfer the configuration via a backup (*.sbk).

For the Home Assistant add-on, an automatic switch from "RaspberryMatic" to the new Home Assistant app "OpenCCU" is not possible either. Therefore, the switch has to be performed manually once as follows:

The switch is performed manually once as follows:

1. In the running RaspberryMatic add-on, create a manual backup in the CCU WebUI under Settings → Control panel → Security → Backup management and download it as *.sbk.

   NOTE If the RaspberryMatic add-on has already been uninstalled or deleted before the new OpenCCU app was set up, you can try to download the last automatic configuration backup (*.sbk) from /backup/raspberrymatic using the guide for downloading configuration backups from Home Assistant.

2. Stop the RaspberryMatic add-on, disable autostart and write down the port settings enabled in the add-on.
3. Additionally install the OpenCCU app in Home Assistant.
4. Enable autostart and show in sidebar for the OpenCCU app and set up the previously noted ports again in the app configuration. Important: without enabled ports, the Home Assistant integration cannot connect to OpenCCU later.
5. Start the OpenCCU app and log in to the WebUI (the settings to be made will be overwritten by the backup in the next step).
6. Import the previously created SBK backup under Settings → Control panel → Security → Backup management.
7. In Home Assistant, write down the hostname shown in the settings of the OpenCCU app (e.g. xxxxxx-openccu).
8. In Home Assistant, select Settings → Devices & services → Homematic(IP) Local for OpenCCU and click on the gear icon to configure it. There, change the hostname from xxxxxx-raspberrymatic to xxxxxx-openccu. The name of the hub then automatically changes to "OpenCCU".
9. Restart Home Assistant. If everything works, remove the old RaspberryMatic add-on (including "Delete data").
10. If not all devices are found with their names afterwards, execute the action homematicip_local.clear_cache in Home Assistant under Developer tools → Actions and reload the integration.

After the successful installation or configuration transfer, the following steps are recommended for the basic setup:

1. Open the WebUI: The WebUI can be accessed in a web browser at http://openccu/ (default hostname) or via the IP address of the system. The IP address can be determined, for example, in the device overview of your router. With the Home Assistant app, the WebUI is accessed via the Home Assistant sidebar.
2. Set a password: Under Settings → User management, set a secure password for the Admin user. Without a password, the WebUI is accessible to everyone in the local network without logging in.
3. Check time and location: Under Settings → Control panel → Time-/position settings, check the time zone, location (for astro functions) and NTP servers.
4. Set up backups: Create regular backups of the configuration or set up the automatic backup.
5. Stay up to date: Update OpenCCU regularly. Available updates are shown on the start page of the WebUI.