jens-maus / Raspberrymatic

– The alternative/free operating system for your HomeMatic CCU

_{Hier drücken für 🇩🇪🇦🇹🇨🇭 deutschsprachiges ReadMe}

🚀 Quick-Start       📚 Documentation       📦 Download       🚑 Support       👮 Licenses

RaspberryMatic is a free and non-commercial OpenSource operating system alternative for the CCU3 or ELV Charly smart home central systems to configure and use HomeMatic/BidCos-RF or homematicIP IoT hardware distributed by eQ-3/ELV. RaspberryMatic has the aim to be 100% compatible to a standard HomeMatic CCU control central for a cloud-free use of HomeMatic IoT hardware on freely available single-board-computers (SBC) like a RaspberryPi, ASUS Tinkerboard or even as a virtual appliance on modern virtual environments (e.g. vmWare ESXi, Proxmox, VirtualBox, Docker/OCI, Kubernetes/K8s, etc.). On top of that, it provides additional exclusive features on different levels (WebUI, Linux-OS, etc.) to provide users with an enhanced user experience compared to the standard vendor-provided CCU firmware from eQ3/ELV.

more...

🍪 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.

more...

💻 Requirements

RaspberryMatic can be directly installed on the following, commercially distributed CCU hardware:

• CCU3, ELV-Charly

...or on the following self-made hardware systems:

• Hardware:
  • RaspberryPi
  • ASUS Tinkerboard
  • Intel NUC

...or even as a virtual appliance on the following virtualization environments:

• Virtualization Environment:
  • vmWare ESXi
  • Proxmox Virtual Environment
  • Oracle VirtualBox
  • Synology Virtual Machine Manager
  • QNAP VirtualizationStation
  • vmWare Workstation Player
  • QEmu/KVM
  • HyperV
  • Docker/OCI
  • Kubernetes/K8s
  • Home Assistant

more...

☁️ 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.

more...

📝 Documentation

1. Introduction
   • Requirements
   • Features
   • Limitations
   • License and Warranty
   • Commercial Distribution
2. Installation
   • Quick-Start
   • Basic Installation (Hardware)
     • CCU3
     • ELV-Charly
     • RaspberryPi
     • ASUS Tinkerboard
     • Intel NUC
   • Basic Installation (Virtual)
     • vmWare ESXi
     • Proxmox Virtual Environment
     • Oracle VirtualBox
     • Synology Virtual Machine Manager
     • QNAP VirtualizationStation
     • vmWare Workstation Player
     • QEmu/KVM
     • HyperV
     • Docker/OCI
     • Kubernetes/K8s
     • Home Assistant Add-on
   • Configuration Upgrade
     • Upgrade from CCU3
     • Upgrade from CCU2
     • Upgrade from CCU1
     • Upgrade to virtual RaspberryMatic
   • Deinstallation
3. Administration
   • Firmware Update/Upgrade
   • Backup/Restore
   • Security Advices
   • CCU-Addon Software
4. Usage
   • WebUI Usage
     • Log-Level setup
   • Tips&Tricks
   • Expert-Features
     • WLAN/WiFi Setup
     • Bluetooth Setup
     • LAN-Gateway Mode
     • USV Client/Server Setup
     • USB-Boot Setup
5. Support, Contributions
   • Known Issues
   • Request Help
   • FAQ - Frequently Asked Questions
   • Report Issues
   • Request Features
   • Contributions / Development

😋 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.

more...

📜 Licenses

The RaspberryMatic build enviroment itself – the files in this git repository – as well as the downloadable images in the Releases section are distributed under the open source Apache License 2.0 license. 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 RaspberryMatic itself is distributed, some components (e.g. the underlying Buildroot/Linux System) can be distributed under different licenses. E.g. Buildroot/Linux itself is distributed under the GPLv2 which could have other implications when changing source parts of these components. Furthermore, the eQ-3 OCCU components RaspberryMatic uses to provide the HomeMatic/homematicIP interconnectivity are distributed under the HMSL license terms.

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.

more...

📖 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

👏 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.

👪 Authors

Due to the large number of existing people having contributed to the success of RaspberryMatic, please refer to the Contributors accordingly.

🚧 ChangeLog

A detailed list of Changes between individual released versions can be reviewed through the Releases section of this GitHub project.