Kursthemen

  • Übersicht

    Der im Rahmen des Themenabends durchgeführte Kurs erklärt die ersten Schritte der Einrichtung und Konfiguration einer ZigBee basierten Homeautomation. Dabei geht es nicht darum bestehende - kommerzielle - Gateways zur Verwaltung von ZigBee Geräten einzusetzen, sondern auf einem RaspberryPi oder ähnlichen Rechnern unter Linux ein Gateway zusammen mit einem CC2531 Netzwerksniffer aufzubauen.

  • Vorbereitung

    Für den Kurs wird keine explizite Hard- oder Software benötigt und die Teilnehmer können dem Vortrag und den Vorführungen folgen. Es ist aber möglich selber die einzelnen Schritte nachzuvollziehen und ebenfalls über den eigenen Rechner ein ZigBee Netz aufzubauen.

    Dafür wird folgendes benötigt:

    Auf den Debugger für den CC2531 und das Adapterkabel kann verzichtet werden, wenn ein CC2531 mit vorinstallierter Coordinator - Software für zigbee2mqtt gekauft wird. Damit fällt dann auch der Installationsschritt zum flashen des CC2531 weg.

    Neben dem CC2531 können auch andere Coordinator eingesetzt werden. Diese sind in der Liste der unterstützten Coordinatoren aufgelistet.

    Zusammen mit einem Laptop mit Linux oder einem RaspberryPi mit Raspberry Pi OS können alle Schritte nachvollzogen werden. Beim Paketmanager gehen wir von einem Debian-basierenden Grundsystem aus.

    Eine Liste weiterer Endgeräte, die mit dem Gateway in der aktuellen Version genutzt werden können ist auf der Projektseite auf GitHub zu finden.

    • Aufspielen der Firmware auf den CC2531

      Um auf den CC2531 die geeignete Firmware aufzuspielen wird ein CC Debugger von Texas Instruments sowie ein Adapter benötigt. Diese sind über einige Plattformen wie z. B. Amazon bestellbar (Debugger, Adapter).

      Zusätzlich wird die entsprechende Firmware und das Tool zum Flashen benötigt.

      Firmware

      Die für uns interessante Firmware wird auf der GitHub Seite des Gateways zur Verfügung gestellt und dort auch immer wieder aktualisiert. Dabei gibt es dort 2 verschiedene Varianten des Firmware:

      • Coordinator
      • Router

      Die Coordinator Firmware ist für die Verwaltung der Geräte zuständig und ist quasi der Netzverwalter. Alleine kann ein Coordinator in der aktuellen Firmware - Version bis zu 30 Geräte direkt verwalten.

      sudo apt install -y tmux unzip
      wget https://github.com/Koenkk/Z-Stack-firmware/raw/master/coordinator/Z-Stack_3.0.x/bin/CC2531_20190425.zip
      unzip CC2531_DEFAULT_20190425.zip

      Um mehr Geräte nutzen zu können werden Router benötigt. Diese können entweder durch CC2531 mit Router Firmware oder durch Dauerstrom Geräte wie z. B. dem Osram Smart+ Plug zur Verfügung gestellt werden. Dabei ist es abhängig von den Geräten selber wie viele Geräte sie wiederum verwalten können.

      Flashen

      Zum Flashen unter Linux wird cc-tool benötigt. Dieses lässt sich problemlos per git herunterladen und lokal compilieren und nutzen:

      sudo apt install -y git autoconf libtool libboost-dev libboost-all-dev libusb-1.0-0-dev

      git clone https://github.com/dashesy/cc-tool.git
      cd cc-tool
      ./bootstrap
      ./configure
      make

      Danach müssen sowohl der CC Debugger als auch der damit verbundene CC2531 an den Rechner angeschlossen werden. Die LED am CC Debugger wird dann zunächst rot leuchten. Nach einem Druck auf die Reset - Taste sollte sie dann grün leuchten.

      Sollte der CC Debugger weiterhin rot leuchten, sicherheitshalber richtige Polung der Anschlüsse überprüfen!

      Damit ist der CC Debugger im Programmiermodus und die Firmware kann aufgespielt werden:

      $ sudo ./cc-tool -e -w ../CC2531ZNP-with-SBL.hex
      Programmer: CC Debugger
      Target: CC2531
      Erasing flash...
      Completed
      Writing flash (241 KB)...
      Completed (17.95 s.)

      Damit ist die Vorbereitung des CC2531 abgeschlossen und der kann benutzt werden.

      • Herunterladen und Einrichten des Gateways

        Als Gateway nutzen wir zigbee2mqtt von Koenkk. Das Gateway ist komplett auf GitHub zu finden.

        Herunterladen

        Um auch einfach wieder Updates durchführen zu können sollte das Gateway per Git heruntergeladen und verwaltet werden:

        sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
        sudo chown -R pi: /opt/zigbee2mqtt

        Wir gehen dabei davon aus, dass die Installation auf einem RaspberryPi stattfindet und der Benutzer der Benutzer pi ist. Ansonsten bitte anpassen.

        Um die Software laufen zu lassen muss die Umgebung zur Verfügung gestellt werden. Dies ist Node.js mit npm.

        sudo curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
        sudo apt-get install -y nodejs git make g++ gcc

        Mit den folgenden Aufrufen sollte die Version getestet werden:

        node --version  # Should output v10.X oder v12.X
        npm --version  # Should output 6.X

        Danach können dann die Module installiert und konfiguriert werden:

        cd /opt/zigbee2mqtt
        npm ci

        Damit ist das Gateway vorbereitet, kann aber noch nicht gestartet werden, da noch kein Mosquitto MQTT Server zur Verfügung steht um die Daten des Gateways zu speichern.

        • Einrichtung des Mosquitto MQTT Servers

          Der Mosquitto MQTT Server ist für die Zwischenspeicherung der Nachrichten, die vom ZigBee - Netzwerk kommen und dahin gehen sollen zuständig. Er funktioniert wie ein Telegramm - Dienst. Das Gateway kann z. B. den Zustand eines Schalters an eine Adresse (topic) des MQTT senden. Clients wie z. B. NodeRed oder OpenHAB2 etc. können nun an dieser Adresse lauschen (subscribe) und bekommen dadurch jede Änderung der Daten an dieser Adresse mit. Dadurch können sie sofort auf die Änderung reagieren von von sich aus auf eine Adresse eine Naschricht schicken oder Aktionen auslösen.

          Für die Grundinstallation ohne jegliche Absicherung des Dienstes reicht die folgende Zeile:

          sudo apt-get install mosquitto mosquitto-clients -y

          Vor dem Produktiveinsatz des Dienstes sollte die Kommunikation zwischen MQTT server und weiteren externen Geräten abgesichert werden.

          • Anpassen der Konfiguration, erster Start

            Der Datei /opt/zigbee2mqtt/data/configuration.yaml liegt die Konfiguration für das Gateway. Falls der MQTT nicht auf dem lokalen Rechner läuft oder es eine Anpassung für den Benutzernamen und das Kennwort gibt, können diese hier eingetragen werden:

            # MQTT settings
            mqtt:
              # MQTT base topic for zigbee2mqtt MQTT messages
              base_topic: zigbee2mqtt
              # MQTT server URL
              server: 'mqtt://localhost'
              # MQTT server authentication, uncomment if required:
              # user: my_user
              # password: my_password

            Es handelt sich hierbei um eine yaml - Datei. Bei diesem Dateityp ist es wichtig die Einrückungen (Leerschritte) beizubehalten.

            Zusätzlich zu dem Einrichten des mqtt - Gateways sollte dem ZigBee - Netzwerk eine eigene Netzwerkadresse gegeben werden. Diese sollte möglichst nicht manuell sondern automatisch generiert werden um sie einmalig zu halten.

            Ein zusätzlicher Eintrag in die Konfigurationsdatei mit dem folgenden Inhalt sorgt für die automatische Generierung einer Netzwerkadresse:

            advanced:
                network_key: GENERATE

            Nun steht dem ersten Start nicht mehr im Weg:

            cd /opt/zigbee2mqtt
            npm start

            Der Server sollte nun melden, dass er an den MQTT Server verbunden ist.

            Geräte, die in den Verbindungsmodus geschaltet wurden sollten nun auch sichtbar werden.

            Die Meldungen, die nun vom an den MQTT Server geschickt und dort gespeichert werden lassen sich über den folgenden Befehl abrufen:

            mosquitto_sub -t \#
            • Anpassen des friendly_name

              Jedes Gerät hat seine eindeutige ID, aber die ID kann sich keiner merken. Daher kann in der Datei /opt/zigbee2mqtt/data/configuration.yaml der friendly_name angepasst werden um einen sprechenden Namen für die Geräte zu bekommen.

              Dazu zunächst den Server stoppen (mit STRG+C oder systemctl stop zigbee2mqtt) und die Datei dann editieren.

              Beispiel:

              devices:
                '0xacb01baa0a0031b0':
                  friendly_name: 'smartplug01'

              Nach dem Neustart des Dienstest nutzt der Server dann statt der bisherigen ID den friendly_name.

              Weitere Konfigurationsparameter sind auf der Website zu finden: https://www.zigbee2mqtt.io/information/configuration.html

              • Geräte per MQTT direkt steuern

                Nachdem unsere Steckdose einen sprechenden Namen hat, können wir an das Gerät Nachrichten schicken (geht natürlich auch mit den IDs, ist aber mühsamer):

                mosquitto_pub -t zigbee2mqtt/smartplug01/set -m '{ "state": "OFF" }'
                mosquitto_pub -t zigbee2mqtt/smartplug01/set -m '{ "state": "ON" }'

                Der Nachrichteninhalt ist dabei ein JSON - Element, dass das Gateway auswertet und entsprechende Kommandos verschickt. Um ein Kommando zu senden wir an den Topic, der über mosquitto_sub ausgelesen wurde ein /set angehangen und die Nachricht dorthin geschickt.

                Das Gateway selber informiert auch über Vorgänge und lässt sich per MQTT steuern: https://www.zigbee2mqtt.io/information/mqtt_topics_and_message_structure.html

                Für einige Geräte sind sogar OTA-Updates verfügbar:

                zigbee2mqtt/bridge/log {"type":"ota_update","message":"Update of '0x7cb03eaa00ab1390' at 2.17%,
                +- 24 minutes remaining","meta":{"status":"update_progress","device":"0x7cb03eaa00ab1390",
                "progress":2.17}} zigbee2mqtt/bridge/log {"type":"ota_update","message":"Update of '0x7cb03eaa00ab1390' at 100%",
                "meta":{"status":"update_progress","device":"0x7cb03eaa00ab1390","progress":100}} zigbee2mqtt/bridge/log {"type":"ota_update","message":"Finished update of '0x7cb03eaa00ab1390',
                from '{\"softwareBuildID\":\"V1.04.93\",\"dateCode\":\"20140331CNWT****\"}' to
                '{\"softwareBuildID\":\"V1.05.10\",\"dateCode\":\"20140331CNWT****\"}'",
                "meta":{"status":"update_succeeded","device":"0x7cb03eaa00ab1390",
                "from":{"softwareBuildID":"V1.04.93","dateCode":"20140331CNWT****"},
                "to":{"softwareBuildID":"V1.05.10","dateCode":"20140331CNWT****"}}}
                • Automatischer Start des Dienstes

                  Es ist sinnvoll den Dienst so einzurichen, dass er beim Systemstart automatisch startet und nicht immer auf der Konsole per Hand aufgerufen werden muss.

                  Dazu kann die Datei /etc/systemd/system/zigbee2mqtt.service mit folgendem Inhalt angelegt werden:

                  [Unit]
                  Description=zigbee2mqtt
                  After=network.target
                  [Service]
                  ExecStart=/usr/bin/npm start
                  WorkingDirectory=/opt/zigbee2mqtt
                  StandardOutput=inherit
                  StandardError=inherit
                  Restart=always
                  User=pi
                  [Install]
                  WantedBy=multi-user.target

                  Nach dem Anlegen kann er Dienst direkt für den Systemstart eingebunden und gestartet werden:

                  sudo systemctl enable --now zigbee2mqtt.service

                  Ausgaben des Dienstes können jetzt über journalctl ausgelesen werden:

                  sudo journalctl --unit zigbee2mqtt.service


                  • Installation und Einrichtung von Home Assistant

                    Ein schneller Weg um eine Oberfläche für die ZigBee Geräte zu bekommen ist die Software Home Assistant. Diese Software unterstützt eine Vielzahl an IoT - Geräten unter anderem auch ZigBee über mqtt.

                    Die Installation unter Debian:

                    apt install -y libffi-dev
                    useradd -m homeassistant -G dialout
                    mkdir /opt/homeassistant /home/homeassistant/.homeassistant
                    chown -R homeassistant: /opt/homeassistant /home/homeassistant
                    sudo -u homeassistant -i
                    cd /opt/homeassistant
                    python3.7 -m venv .
                    source bin/activate
                    pip3 install wheel homeassistant colorlog
                    exit
                    echo >/etc/systemd/system/home-assistant@.service <<HERE
                    [Unit]
                    Description=Home Assistant
                    After=network-online.target
                    [Service]
                    Type=simple
                    User=%i
                    WorkingDirectory=/home/%i/.homeassistant
                    ExecStart=/opt/homeassistant/bin/hass -c "/home/%i/.homeassistant"
                    Restart=always
                    RestartSec=5s
                    [Install]
                    WantedBy=multi-user.target
                    HERE
                    systemctl enable --now home-assistant@homeassistant.service

                    Nach der Installation kann über Port 8123 des Rechners auf den Home Assistant zugegriffen werden.

                    Im Home Assistant muss dann unter den Integrationen das MQTT - Modul aktiviert und auf den Server localhost konfiguriert werden. Damit die Integration vollständig ist, muss in der zigbee2mqtt configuration.yaml die homeasssistan integration aktiviert sein.