Einrichten der Bluetooth-Thermostate von eQ-3

Die Firma eQ-3 stellt verschiedene elektronische Heizkörperthermostate her. Das Eqiva BLUETOOTH® Smart Heizkörperthermostat (CC-RT-BLE-EQ) kann auch von FHEM gesteuert werden. Voraussetzung ist natürlich ein Bluetooth-Empfänger (RasPi 3+4 oder Bluetooth-Dongle).

Hinweis: Es gibt auch Versionen ohne Bluetooth, die genau gleich aussehen. Bei der Bestellung bitte aufpassen.

Bluetooth einrichten

Standardmäßig sollte Bluetooth auf dem Raspberry Pi schon eingerichtet sein. Nutzt man einen B+ mit Dongle (z.B. als Verlängerung), so müssen unter Umständen folgende Pakete installiert werden:

sudo apt-get install bluetooth, bluez

Danach ein sudo reboot. Ein sudo service bluetooth status sollte zeigen, dass der Daemon läuft. Damit der user fhem bzw. pi auf bluetooth zugreifen kann, muss in bluetooth.conf noch folgendes eingetragen werden:

sudo nano /etc/dbus-1/system.d/bluetooth.conf

<policy user="fhem">
    <allow own="org.bluez"/>
    <allow send_destination="org.bluez"/>
    <allow send_interface="org.bluez.GattCharacteristic1"/>
    <allow send_interface="org.bluez.GattDescriptor1"/>
    <allow send_interface="org.freedesktop.DBus.ObjectManager"/>
    <allow send_interface="org.freedesktop.DBus.Properties"/>
</policy>

sudo systemctl restart dbus

Für den User pi muss natürlich fhem durch pi ersetzt werden.

Thermostat in FHEM definieren

Pairing

Die Thermostate müssen mit dem RasPi gepaired werden. Drücke dazu das Rad am Thermostat bis „Pair“ im Display erscheint. Dann führe folgende Schritte aus:

$ sudo bluetoothctl
[bluetooth]# power on
[bluetooth]# agent on
[bluetooth]# default-agent
[bluetooth]# scan on
Discovery started
[CHG] Controller 00:1A:7D:XX:XX:XX Discovering: yes
[NEW] Device 41:86:FB:XX:XX:XX 41-86-FB-...
[NEW] Device 00:1A:22:XX:XX:XX CC-RT-BLE <== EQ3 Device, erkennbar an CC-RT-BLE
[CHG] Device 41:86:FB:XX:XX:XX RSSI: -56
[NEW] Device 00:1A:22:XX:XX:XX CC-RT-BLE <== EQ3 Device, erkennbar an CC-RT-BLE
[CHG] Device 41:86:FB:XX:XX:XX RSSI: -70
[NEW] Device 5A:64:25:XX:XX:XX 5A-64-25-...
[bluetooth]# scan off
[bluetooth]# pair 00:1A:22:06:A7:83
[agent] Enter passkey (number in 0-999999): <enter pin>
[bluetooth]# trust 00:1A:22:06:A7:83
[bluetooth]# disconnect 00:1A:22:06:A7:83
[bluetooth]# exit

Optional steps:
[bluetooth]# devices - to list all bluetooth devices
[bluetooth]# info 00:1A:22:06:A7:83
Device 00:1A:22:06:A7:83 (public)
        Name: CC-RT-BLE
        Alias: CC-RT-BLE
        Paired: yes
        Trusted: yes
        Blocked: no
        Connected: no
        LegacyPairing: no
        UUID: Generic Access Profile    (00001800-0000-1000-8000-00805f9b34fb)
        UUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)
        UUID: Device Information        (0000180a-0000-1000-8000-00805f9b34fb)
        UUID: Vendor specific           (3e135142-654f-9090-134a-a6ff5bb77046)
        UUID: Vendor specific           (9e5d1e47-5c13-43a0-8635-82ad38a1386f)
        ManufacturerData Key: 0x0000
        ManufacturerData Value:
  00 00 00 00 00 00 00 00 00                       .........

Dadurch ist das Thermostat nicht mehr mit der calor BT-App steuerbar (und umgekehrt). Unter Umständen wird nicht nach Enter passkey gefragt. Wichtig ist die Erfolgsmeldung.
Die Befehle bedeuten im Einzelnen:

$ sudo bluetoothctl

Startet das Bluetoothctl-Tool, das eine Befehlszeilenschnittstelle zu BlueZ ist. sudo ist häufig nicht erforderlich. Die Ausgabe sollte ähnlich der folgenden aussehen:

[CHG] Controller E4:5F:01:F0:0E:98 Pairable: yes
[bluetooth]#

Die Zeile „[CHG] Controller“ (oder auch [NEW]) zeigt die Informationen zu deinem Bluetooth-Chip an. Die letzte Zeile ist die Eingabeaufforderung von bluetoothctl.

Da der Kopplungsvorgang eine Authentifizierung per PIN beinhaltet, ist eine Registrierung bei einem Authentifizierungsagenten erforderlich. Der Agent bearbeitet die PIN-Abfrage. Gib dazu Folgendes ein:

[bluetooth]# agent on
Agent registered 
[bluetooth]# default-agent 
Default agent request successful 
[bluetooth]#

Beachte, dass die Registrierung des Agenten während der Kopplung mit einem Gerät, das keine Benutzerbestätigung für den Kopplungsversuch erfordert, keine negativen Auswirkungen hat und sicher ist.
An dieser Stelle kannst du mit der Suche nach entfernten Bluetooth-Geräten fortfahren:

[bluetooth]# scan on
Discovery started
[CHG] Controller 00:1A:7D:XX:XX:XX Discovering: yes
[NEW] Device 41:86:FB:XX:XX:XX 41-86-FB-...
[NEW] Device 00:1A:22:XX:XX:XX CC-RT-BLE <== EQ3 Device, erkennbar an CC-RT-BLE
[CHG] Device 41:86:FB:XX:XX:XX RSSI: -56
[NEW] Device 00:1A:22:XX:XX:XX CC-RT-BLE <== EQ3 Device, erkennbar an CC-RT-BLE
[CHG] Device 41:86:FB:XX:XX:XX RSSI: -70
[NEW] Device 5A:64:25:XX:XX:XX 5A-64-25-...
[NEW] Device <bluetooth address> <name>

Stoppt man den Scan mit [bluetooth]# scan off, so werden die Ergebnisse der Geräteerkennung nach einer gewissen Zeit ungültig.

[DEL] Device 00:1A:22:XX:XX:XX CC-RT-BLE

Vorher kann das Pairing gestartet werden:

[bluetooth]# pair 00:1A:22:06:A7:83

Nun einfach der Anzeige folgen. Am Ende sollte eine Erfolgsmeldung stehen. Falls nicht, die Prozedur ab [bluetooth]# scan on wiederholen. Danach muss das Gerät noch als Vertrauenswürdig deklariert

[bluetooth]# trust 00:1A:22:06:A7:83

und wieder getrennt werden

[bluetooth]# disconnect 00:1A:22:06:A7:83

Danach kannst du über

[bluetooth]# info 00:1A:22:06:A7:83

nachsehen, ob alles korrekt ist. Das Gerät kann nun in FHEM definiert werden.

Einrichten mit Perl-Modul 10_EQ3BT

Die eQ-3 Heizkörperthermostate können einfach über define <name> EQ3BT <mac address> eingebunden werden.

Mittlerweile wird nur noch das fhempy-Modul empfohlen

Einrichten mit fhempy

fhempy ermöglicht das Schreiben von FHEM-Modulen in der Programmiersprache Python. Erforderlich ist Python 3.9 oder höher (NICHT 2!), weshalb Debian Bullseye erforderlich ist. Es ist auch möglich, fhempy auf Peers zu installieren, um dadurch die Bluetooth-Reichweite zu erhöhen. Dadurch ist eine komplette Abdeckung des Hauses möglich. Auf den Peers muss FHEM nicht installiert werden. Neben dem Raspberry Pi Zero eignet sich auch z.B. der Radxa Rock Pi Zero, getestet mit Armbian. Ein Radxa Pi S ist sehr verführerisch. Dabei ist aber auf den SoC zu achten. Der alte RK3308B (ohne S) läuft nur unter dem Radxa debos (buster) mit Bluetooth. Mit Armbian und einem Bluetooth-Dongle geht es aber auch. Die Peers können aus FHEM heraus verwaltet werden.

Installation auf FHEM-Server

Um die Heizkörperthermostate unter fhempy einzurichten, sind zunächst einige Vorarbeiten erforderlich. Das Einrichten geht dann genau so simpel. Nach dem obligatorischen sudo apt-get update && sudo apt-get upgrade werden die benötigten Python-Pakete mit

sudo apt install python3 python3-pip python3-dev libffi-dev libssl-dev libjpeg-dev zlib1g-dev autoconf build-essential libglib2.0-dev libdbus-1-dev bluez libbluetooth-dev git libprotocol-websocket-perl

Das dauert eine Weile. Ich empfehle eine Tasse koffeinhaltiges Heißgetränk. Ist die Installation abgeschlossen, geht es an die Konfiguration von FHEM. Zunächst laden wir per Update die benötigten Dateien herunter:

update add https://raw.githubusercontent.com/dominikkarall/fhempy/master/controls_pythonbinding.txt
update

Ist das Update abgeschlossen, können wir fhempy einrichten:

define fhempy_local BindingsIo fhempy

Es wird automatisch fhempyserver und fhempy_local eingerichtet. Auch hier gilt: nicht nervös werden, wenn fhempy_local nicht sofort connected anzeigt.

Hiermit sind die Vorbereitungen abgeschlossen. Das Thermostat kann nun mit

define <name> fhempy eq3bt <MAC-Adresse>

eingebunden werden. Die benötigten Module werden automatisch nachgeladen.

Installation des fhempy-Peer

fhempy läuft nicht nur lokal auf dem FHEM-Server. Zur Reichweitenerhöhung kann auch ein fhempy-Peer auf einem oder mehreren RasPi’s installiert und diese über die Wohnung verteilt werden. Geeignet ist natürlich auch ein RasPi, der zur Visualisierung dient.

WICHTIG!! Die folgenden Befehle dürfen nur auf dem Remote-RasPi und nicht auf der FHEM-Instanz ausgeführt werden.

Zunächst müssen die benötigten Python-Pakete wie oben beschrieben installiert werden. Installiere nun fhempy als User pi

pip3 install --upgrade fhempy

Überprüfe, ob die Hauptinstanz auf dem FHEM-Server läuft und starte dann fhempy als User pi auf dem Peer

fhempy

Nach kurzer Zeit siehst du die ankommende FHEM-Verbindung. Nun noch die systemd-Konfiguration, damit fhempy automatisch gestartet wird

curl -sL https://raw.githubusercontent.com/fhempy/fhempy/master/install_systemd_fhempy.sh | sudo -E bash -

fhempy läuft nun unter dem User pi. Möchtest du das ändern, so schau in die Datei fhempy.service im Verzeichnis /etc/systemd/system/ Hinterher das sudo systemctl daemon-reload nicht vergessen. Der Peer sollte in FHEM automatisch erkannt werden (beruht auf Zeroconf). Sollte das nicht der Fall sein, kann der Peer auch manuell definiert werden

define fhempy_peer_IP BindingsIo IP:15733 fhempy

Bekannte Probleme

Fehlermeldung nach fhempy-Installation

Meldet pip3 folgendes

  WARNING: The script normalizer is installed in '/home/myname/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.

so fehlt der Pfad zu fhempy und fhempy kann nicht aufgerufen werden. Es ist folgender Befehl aufzurufen

export PATH=$PATH:/home/myname/.local/bin

also z.B.

export PATH=$PATH:/home/pi/.local/bin

Keine Reaktion auf Einstellen der Offset-Temperatur

Zur Zeit scheint es ein Softwareproblem beim Einstellen der Offset-Temperatur über Bluetooth zu geben (Version 146 oder kleiner). Die Einstellung wird übertragen, wirkt sich aber nicht auf das Thermostat aus. Erst wenn man die Einstellung über das Menü am Thermostat bestätigt (oder gleich dort einstellt), reagiert das Thermostat. Das Problem tritt auch bei der Bedienung über die App auf.

Pairing wird hartnäckig verweigert

Manchmal klappt das Pairing nicht, obwohl alles in Ordnung scheint. Ein sudo hciconfig hci0 down, gefolgt von einem hciconfig hci0 up eventuell mit einem sudo hciconfig hci0 reset dazwischen kann helfen.

Links

• fhempy-Projekt auf Github
• Pairing der Thermostate
• Forums-Beitrag