The RaspberryMatic project is a collaborate effort to provide a lightweight, Linux/buildroot-based HomeMatic compatible operating system for embedded single board computers (SBC) like the RaspberryPi or Tinkerboard. It is meant to provide a an alternative operating system for CCU3 or ELV Charly systems. It is based on the Open-Central-Control-Unit-SDK (OCCU) provided by eQ-3 as part of the HomeMatic home automation platform. The RaspberryMatic distribution is provided as a full operating system image that can be flashed and then used in a RaspberryPi/Tinkerboard as the main operating system for controlling all HomeMatic compatible devices with full compatibility to a CCU device directly sold by eQ-3.

🍪 Features

• 100% HomeMatic CCU2/CCU3 system compliant using latest OCCU software environment
• Fully HomeMatic (BidCos-RF), HomeMatic-Wired (BidCos-Wired), homematicIP (HmIP-RF) and homematicIP-Wired (HmIP-Wired) compatible.
• Integrated WebUI-based firmware update mechanism and Recovery System to perform maintenance operations such as system restore.
• Enabled Preemptive kernel support (PREEMPT) to minimize latencies and improve CCU operation properties
• Read-only root file system to minimize write operations on SD card
• Includes embedded JAVA8 runtime environment (1.8.0_222-8.40.0.178)
• Full IPv6 support and default HTTPS enabled WebUI support
• Auto-resizing /usr/local partition to utilize the full capacity of the SD card or USB stick
• Hardware WatchDog support automatically rebooting the system upon severe hardware/lockup problems
• Direct CloudMatic (meine-homematic.de) support

🍰 Exclusive Features (not available in CCU2/CCU3 firmware)

• Runs on all available RaspberryPi and ASUS Tinkerboard hardware models on the market.
• Integration of latest community version of ReGaHss comming with latest features and bugfixes in logic engine.
• Integration of over 40 third-party patches for an improved WebUI experience providing the following additional functionalities:
  • Possibility to disable service messages for manually deactivating homematic devices
  • Direct display of important status messages (config pending, unreach, etc.) and RSSI values for each device
  • Added display of battery level and valve state for all heating control devices (e.g. HM-CC-RT-DN or HMIP-eTRV)
  • Completly reworked scripting editor (using CodeMirror engine) with the following features:
    • display of line numbers
    • syntax highlighting
    • internal (regex) search & replace functionality as well as match display on the scrollbar
    • internal command completion based on already existing words in the currently edited script
    • brackets-based code folding capabilities
    • brackets matching display to highlight all opening/closing brackets while editing
    • auto adding of closing brackets while editing
    • switchable fullscreen mode
    • Advanced editor keyboard shortcuts (e.g. Ctrl-Q: auto folding/un-folding of brackets)
  • Possibility to use "equal" and "not equal" comparisons in WebUI programs
  • Possibility to force a boot into the recovery system on next boot
  • Optimized WebUI-based file upload/download with improved large file support
  • Possibility to perform a CCU addon installation without a forced reboot
  • Display of the number of previously performed security key changes
  • Possibility to alphabetically sort all system variables added as user favorites
  • Improved browser cache handling for reduced conflicts when updating to newer firmware versions
  • Added Apple-Touch icons to be displayed if the WebUI is displayed as an iOS App on the Desktop of a iPad/iPhone
  • Integrated certain bug fixes in case system variables with white spaces and newlines are used
  • System variables can now be added as user favorites even though they were previously connected to a device channel
  • Cosmetical enhancements in the various table displays in the WebUI
  • More table filter possibilities for a faster search for devices/channels
  • Minor fixes to DevConfig tweak to also display RSSI values for HmIP devices
• Integration of certain general security enhancements:
  • Improved WebUI security via enabled cross-site-scripting preventions (X-Frame-Options, X-XSS-Protection, X-Robots-Tag, etc.)
  • Encryption certificates for HTTPS are exclusively generated on the system itself (and not via third-party servers)
  • Delivered robots.txt to prevent web crawlers from indexing a CCU in case it is accidently available from the internet
  • General use of SHA512 strong password hashes when entering a new SSH connection password
  • In case of low-memory conditions critical homematic services will be killed as one of the last services
• Improved backup/restore functionality for
  • manually running a backup/restore on the command-line (createBackup.sh, restoreBackup.sh)
  • automatic nightly backups on a connected USB memory stick
  • possibility to route nightly backups to external storage devices (e.g. NAS)
• Additional linux packages installed/available:
  • wiringPi - GPIO library and command-line tools to easily query/set GPIO states
  • chrony - as a drop-in replacement for the old ntpd NTP daemon used
  • jq - json parsing command-line tool
  • ethtool - command-line tool to query/set information on network links
  • f2fs - F2FS filesystem which is explicitly developed for flash devices and can be used for e.g. external USB devices
• Additional helper scripts useable on command-line:
  • triggerAlarm.tcl – can be used to trigger an own alarm in the WebUI
  • updateAddonContig.tcl – to add/remove CCU addon buttons to the WebUI
• Automatic generation and update of DutyCycle system variables which will contain the percentage of each rf module (GPIO module or connected LAN gateways) as well as automatic alarm triggering in case a duty cycle > 98% is reached
• Use of the RaspberryPi/Tinkerboard onboard LEDs to signal general system load using heartbeat-typed LED flashes
• A combination of multiple homematic RF-modules can be used to distribute DutyCycle and allow for a wider range of different homematic access scenarios (e.g. HmIP-RF-USB and HM-CFG-USB-2 at the same time)
• Support to be used as a pure HomeMatic LAN Gateway (HM-LGW-O-TW-W-EU) only
• Support to be used without any GPIO RF module HAT when just connecting to a HomeMatic LAN Gateway (HM-LGW-O-TW-W-EU)
• Self-contained disk image targeted for lightweight embedded devices (e.g. RaspberryPi, ASUS Tinkerboard)
• Based on latest Buildroot 2019.08.1 lightweight Linux operating system
• Latest Linux kernel (RaspberryPi: 4.19.79, Tinkerboard: 4.19.79) with hard-float (ARMv7) support
• Support to boot system using an external USB memory stick or hard disk (RaspberryPi3 only) or from internal eMMC storage (ASUS Tinkerboard S)
• Supports onboard WiFi of RaspberryPi3, RaspberryPi Zero W or ASUS Tinkerboard as well as various third-party USB WiFi sticks
• Supports USB Gadget Mode for RaspberryPi Zero and RaspberryPi Zero W to connect the USB port to another system (Linux/macOS/Windows) and use it for a routed ethernet connection (requires /etc/config/usbGadgetModeEnabled)
• Supports onboard Bluetooth of RaspberryPi3, RaspberryPi Zero W or ASUS Tinkerboard as well as various third-party USB Bluetooth sticks
• Supports Network UPS Tools (NUT) setups including USB connection to uninterruptible power supply (UPS) as well as remote NUT server use (e.g. via Synology NAS Network UPS functionality)
• Support for the following third-party Hardware Attached on Top (HAT) boards:
  • S.USV – UPS including alarm notification upon power loss and automatic system shutdown.
  • PiUSV+ – UPS including alarm notification upon power loss and automatic system shutdown.
  • PiModules UPS PIco – UPS including automatic system shutdown.
  • StromPi2 – UPS including alarm notification upon power loss (WARNING: StromPi3 is NOT supported!)
  • PiDesktop – Addon HAT with power button and dedicated RTC clock (PCF8563).
• Integrated support for various RTC clock modules:
  • PiFace Shim RTC
  • DS3231
  • DS1307
  • RX8130CE
  • PCF8563
  • onboard Tinkerboard RTC
• Dedicated Build Environment using a cross compiler (arm-linux-gcc) to compile third-party applications

🔥 Limitations

• No web-based configuration for setting up WiFi or Bluetooth support (work in progress)
• No web-based configuration for enabling/disabling the LAN-Gateway mode (work in progress)
• No web-based configuration for configuring NUT (UPS) support (work in progress)

💻 Requirements

Existing product

You can use one of the following existing ready-to-go products:

1. CCU3
2. ELV Charly

Build-your-Own hardware

... or you can build your own embedded system using the following components:

1. One of the following hardware boards:
   • RaspberryPi4 Model B
   • RaspberryPi3 Model B+
   • RaspberryPi3 Model B
   • RaspberryPi3 Model A+
   • RaspberryPi2 Model B
   • RaspberryPi Compute Module 3
   • RaspberryPi Compute Module 3 lite
   • RaspberryPi Zero W
   • RaspberryPi Zero
   • RaspberryPi Compute Module 1
   • RaspberryPi1 Model B+
   • RaspberryPi1 Model B, 512MB
   • RaspberryPi1 Model A+
   • RaspberryPi1 Model A, 256MB
   • Tinker Board S
   • Tinker Board
2. A minimum 4 GB sized microSD card or USB device (memory stick, SSD, hard disk)
3. One or more of the following homematic capabale communication devices:

		HomeMatic	homematicIP	HomeMatic-Wired	homematicIP-Wired
RPI-RF-MOD	GPIO Radio Module HAT	✔️	✔️
HM-MOD-RPI-PCB (Installation)	GPIO Radio Module HAT	✔️	✔️
HB-RF-USB (Discussion)	USB Radio Module Adapter PCB	✔️	✔️
HmIP-RFUSB	USB Radio Module Stick		✔️
HM-CFG-USB-2	USB Radio Module Stick	✔️
HM-LGW-O-TW-W-EU	LAN RF-Gateway	✔️
HMW-LGW-O-DR-GS-EU	LAN Wired-Gateway			✔️
HmIPW-DRAP	HmIP-Wired Access Point				✔️ (requires RPI-RF-MOD)

🔭 Compatible Third-Party CCU Addons

The CCU platform allows to enhance the functionality of a CCU by installing so-called CCU Addon packages. For RaspberryMatic, standard CCU Addon packages won't work because included binaries have to be recompiled for the hard-float buildroot environment RaspberryMatic uses. Here is a list of well-known already compatible Addon packages (please note that this list might be incomplete):

• CUxD
• XML-API
• hm_pdetect
• Email-Addon
• CUxD-Highcharts
• HQ-WebUI
• DB-Access
• QuickAccess
• Script-Parser
• WebMatic
• Sonos Player
• hm2mqtt
• CCU-Historian
• Watchdog
• homeputer CL Studio
• Print / ProgrammeDrucken
• HomeMatic Check_MK
• hm-tools
• HB-UW-Sen-THPL Universalsensor
• RedMatic
• Mosquitto
• Redis
• HomeMatic Virtual Interface
• ioBroker CCU Addon
• Philips Hue Addon
• Velux Addon
• LGTV Addon

☁️ Installation

The installation of RaspberryMatic is quite straight forward as it is delivered as a full system image that can be directly flashed onto a microSD / eMMC and put into the corresponding SBC. As such the installation consists of the following basic steps:

1. Download latest release archive (RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.zip) for the hardware platform you are using:
   • wget https://github.com/jens-maus/RaspberryMatic/releases/download/X.XX.XX.YYYYMMDD/RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.zip
2. Unarchive zip file resulting in an SD card image (RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.img), e.g.:
   • unzip RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.zip
3. Check sha256 checksum to check integrity of SD card image, e.g.:
   • sha256sum -c RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.img.sha256
4. Use the image flasher tool "Etcher" (https://etcher.io) to flash the *.img file to your SD card or USB drive. As an alternative you can also use the following command-line calls to manually flash it on Unix-based operating systems:
   • Linux: sudo dd if=RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.img of=/dev/mmcblk0 bs=1M conv=fsync
   • macOS: sudo dd if=RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.img of=/dev/rdiskX bs=1m
5. For RPI-RF-MOD/HM-MOD-RPI-PCB use only: Make sure you have the RPI-RF-MOD/HM-MOD-RPI-PCB radio module correctly installed on the GPIO
6. Install microSD in your SBC and connect power
7. Wait until bootup process is finished and use a web browser to connect to http://homematic-raspi/

📝 Documentation

Documentation (e.g. how to port your HomeMatic configuration from a CCU2/CCU3 to RaspberryMatic) and installation support is currently limited to using a mostly german language speaking fora with the following links pointing to the relevant sections of the fora where you can find documentation and help about RaspberryMatic:

• RaspberryMatic - Installation Guide 🇩🇪
• RaspberryMatic - Forum 🇩🇪
• HM-MOD-RPI-PCB - Installation Video 🇩🇪

📺 Presentations (German 🇩🇪 – YouTube)

😋 How to contribute

As the RaspberryMatic project is an open source based project everyone is invited to contribute to this project. Please note, however, that functionality within the corresponding eQ-3 OCCU binaries can not be modified as the main HomeMatic services (rfd, ReGaHSS, HMServer, etc.) are provided in binary format by the OCCU project and not compiled from sources. Nevertheless, if you are a talented developer and want to contribute to the success of RaspberryMatic feel free to send over pull requests or report issues / enhancement requests. Please note, however, the licensing and contributing implications and accept that - in short - anything you contribute to this repository/project (especially source code) will be (re)licensed under the Apache 2.0 license (see CONTRIBUTING.md). In addition, please understand that we will only accept contributions (either source code or issues in the issue tracker) if these comply to our CODE OF CONDUCT.

💰 Donations

Even for those that don't have the technical knowhow to help developing on RaspberryMatic there are ways to support our development. Please consider sending us a donation to not only help us to compensate for expenses regarding RaspberryMatic, but also to keep our general development motivation on a high level. So if you want to donate some money please feel free to send us money via PayPal. And if you are running a business which might integrate RaspberryMatic in one of your products please contact us for a regular donation plan which could not only show that you do care about open source development, but also could secure your product by ensuring that development on RaspberryMatic continues in future.

🚧 Development

Building your own RaspberryMatic SD card image is a very straight forward process using this build environment – given that you have sufficient Linux/Unix knowledge and you know what you are actually doing. But if you know what you are doing and which host tools are required to actually be able to run a RaspberryMatic build, it should be as simple as:

$ git clone https://github.com/jens-maus/RaspberryMatic
$ cd RaspberryMatic
$ make dist
[wait up to 1h]
$ make install of=/dev/sdX

🔖 Using the generated cross compiler

After a successfull build of RaspberryMatic a dedicated cross compiler (arm-linux-gcc) should be available within the build-raspmatic_rpi3 path. You can use this GCC-based cross compiler to compile all kind of third party applications which can then be run within RaspberryMatic:

$ cd HelloWorld
$ <path-to-RaspberryMatic-build>/build-raspmatic_rpi3/host/usr/bin/arm-linux-gcc -o HelloWorld HelloWorld.c

A valid alternative for building RaspberryMatic ARM-hardfloat compatible binaries is to use the following Linux cross compiler suite supplied by the RaspberryPi foundation.

📜 License

The RaspberryMatic build environment itself – the files found in this git repository – as well as the RaspberryMatic sd card images are licensed under the conditions of the Apache License 2.0. Please note, however, that the buildroot distribution RaspberryMatic is using is licensed under the GPLv2 license instead. Furthermore, the eQ-3 OCCU software RaspberryMatic is using to provide HomeMatic-based services is licensed under the (HMSL).

👏 Acknowledgments

As this project is a collaborative effort also indirectly using several third-party solutions we would like to thank the following authors for their valueable contributions:

• Alexander Reinert – for his generic_raw_uart kernel module enabling homematicIP support with the ASUS Tinkerboard.

👪 Authors

See Contributors for a complete list of people that have directly contributed to this project.