– The alternative/free operating system for your homematicIP CCU
Deutschsprachiges 🇩🇪🇦🇹🇨🇭 ReadMe
RaspberryMatic is a free and non-commercial open-source operating system alternative for running a cloud-free smart-home IoT central to provide connectivity to the homematicIP / HomeMatic hardware line of IoT devices developed by eQ-3 and distributed by ELV. RaspberryMatic has the aim to be 100% compatible to the vendor-developed HomeMatic CCU3 control central (CCU3) system. It can be directly installed on a CCU3 or ELV Charly hardware device. Alternatively, it can also be installed on a wide range of freely available single-board-computers (SBC) like a RaspberryPi, ASUS Tinkerboard, Hardkernel ODROID or even on full-fledged hardware platforms like an Intel NUC system. Furthermore, it can be run as a virtual appliance in modern virtualization environments (e.g. Proxmox VE, VirtualBox, Synology VMM, Docker/OCI, Kubernetes/K8s, vmWare ESXi, etc.) or even as a pure Home Assistant Add-On. On top of that wider range of supported operating environments, it also comes with exclusive features on different levels (WebUI, Linux OS, connectivity, etc.) to support end users with a more modern and advanced user experience compared to the vendor-provided CCU3 operating system.
:cookie: Features
Due to the used base components, RaspberryMatic is 100% compatibile to the standard CCU control center distributed by eQ3/ELV (CCU2/CCU3). This means, that not only it can use the same HomeMatic/homematicIP IoT hardware like a CCU3 central with the same base version. It also provides the same level of functionality in areas like the WebUI or Add-on compatibility. Furthermore, even system backups are compatible between the two CCU variants, which allows to easily switch between the vendor-provided CCU firmware and this free open-source based CCU system software.
On top of that, RaspberryMatic provides a whole bunch of enhancements or even bugfixes in the WebUI or underlying Linux operating system which are either not yet integrated in the official eQ3 CCU firmware or will never be integrated due to the functionality not being commercially interesting enough for eQ3/ELV.
:computer: Requirements
RaspberryMatic can be directly installed on the following, commercially distributed CCU hardware:
...or as a virtual appliance on the following virtualization environments:
- Virtualization Environment:
:cloud: Quick-Start
Under Releases you will find dedicated images/files for each supported target hardware. Such an image is e.g. available as an RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.zip download file. After having unarchived this file you should identify a *.img file which can be "flashed" to an adequate target media (sd card, usb-stick, ssd or virtual disk, etc.) using e.g. an imaging tool like Etcher. After having flashed this image on the target media you can then put it into your SBC or CCU3 hardware and boot the system. Depending on the used hardware, RaspberryMatic should then boot-up and try to identify the used HomeMatic/homematicIP RF-Module hardware potentially installed on the GPIO bus of your SBC. If this boot-up is finished, you should be able to access the standard WebUI in your local network by using the address http://homematic-raspi/ in your web browser. Afterwards you should then find yourself in then normal CCU WebUI where you can start configuring/using your HomeMatic/homematicIP IoT hardware.
:memo: Documentation (🇩🇪/🇺🇸)
- Introduction
- Installation
- Administration
- Usage
- Support, Contributions
:yum: Support, Contributions
To provide general feedback or start discussions, please use either the Discussion fora in this GitHub project or (if you are german speaking) please contribute to the RaspberryMatic fora of the HomeMatic-Forum. If during discussions in these fora a definite and unique feature request or bug has been acknowledged by other RaspberryMatic users, please feel free to open a dedicated feature or bug fixing request in the issue tracker.
Any contribution in any way is highly welcome. Please feel free to contribute not only by using the official releases. If you have some time and free resources, we welcome any contributing to help to reproduce and perhaps even fixing any open issues in our issue tracker. Also participating in enhancing or fixing the official wiki-based documentation is appreciated. That's why any logged-in GitHub user can directly add and modify any documentation pages in this wiki.
On top of that, direct contributions by sending in PullRequests and source code contributions (Bugs, Features, etc.) are welcome. So if someone would like to see a certain feature implemented or bug fixed and has enough free resources and knowhow, please feel free to directly send in PullRequests using Git/GitHub. Please note, however, that any contribution to this open source project have to be in accordance to the Apache-2.0 open source license under which RaspberryMatic itself is developed and distributed. So by sending in PullRequests you will have to acknowledge that you are fine with the license implications of your contributions. Therefore, please refer to CONTRIBUTING as well as reading our CODE OF CONDUCT before you consider contributing to this project in any form.
:scroll: Licenses
The RaspberryMatic project itself – the files in this repository – as well as the downloadable binary images in the Releases section are distributed under conditions of the open source Apache License 2.0 license, if not otherwise stated. RaspberryMatic itself is distributed completly free of charge and without any commercial intension whatsoever. Please note, that on top of the Apache-2.0 license, under which RaspberryMatic itself is distributed, other components (e.g. the underlying Buildroot/Linux Operating System) are distributed under different licenses. E.g. Buildroot/Linux itself is distributed under the GPLv2 which could have other implications when changing source parts or distributing own RaspberryMatic images. Furthermore, the eQ-3 OCCU components RaspberryMatic uses to provide the HomeMatic/homematicIP interconnectivity are re-distributed under the HMSL license terms. Furthermore, the RaspberryMatic logo and all other graphical image files in this repository and the downloadable binary images which are closely linked to this project are copyrighted by its sole authors. Any commercial and non-commercial (re-)use of these graphical image files or use of the RaspberryMatic logo are strictly prohibited when distributing own binary distributions or forked versions of RaspberryMatic.
Disclaimer of Warranty
All project contributors provide RaspberryMatic (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing RaspberryMatic and assume any risks associated with Your exercise of permissions under this License.
:book: Literature
If after reading through this documentatin anyone is still unsure regarding the pros and cons of using RaspberryMatic rather than the standard vendor-provided CCU firmware or if someone would like to read / see more on which additional features RaspberryMatic provides, please see the following list of (mostly german speaking) literature:
- Vortragsfolien HomeMatic-Usertreffen 2019
- Vortragsfolien HomeMatic-Usertreffen 2018
- Vortragsfolien HomeMatic-Usertreffen 2017
- Vortragsfolien HomeMatic-Usertreffen 2016
:clap: Acknowledgements
In addition to the whole list of Contributors which have contributed to the success of RaspberryMatic, we would like to explicitly thank the following list of people for their third-party contributions:
- Alexander Reinert (@alexreinert) – for his low-latency generic_raw_uart kernel module which allows to use the eQ3 distributed RF modules (RPI-RF-MOD, HM-MOD-RPI-PCB) as well as for his HB-RF-USB, HB-RF-USB-2 and HB-RF-ETH open hardware projects providing USB and Ethernet based adapter PCBs to use the eQ3 RF modules with other base interfaces.
:family: Authors
Due to the large number of existing people having contributed to the success of RaspberryMatic, please refer to the Contributors accordingly.
:construction: ChangeLog
A detailed list of Changes between individual released versions can be reviewed through the Releases section of this GitHub project.