Documentation: Added installation of ESPHome dashboard; extended lib.…

…backup to backup and restore ESPHome configurations

dev/sample_plugin/plugin.yaml

@@ -22,6 +22,7 @@ plugin:
 
     multi_instance: false           # plugin supports multi instance
     restartable: unknown            # plugin supports stopping and starting again, must be implemented
+    #configuration_needed: False     # False: The plugin will be enabled by the Admin GUI without configuration
     classname: SamplePlugin         # class containing the plugin
 
 parameters:

doc/user/source/entwicklung/virtual_env.rst

@@ -1,14 +1,14 @@
 Virtuelle Umgebungen
 ====================
 
-Wenn außer SmartHomeNG noch weitere Software mit Python auf dem gleichen System läuft, 
+Wenn außer SmartHomeNG noch weitere Software mit Python auf dem gleichen System läuft,
 kann es sinnvoll sein die einzelnen Python Umgebungen voneinander zu trennen und eine
 virtuelle Umgebung zu nutzen.
 
-Dazu gibt es verschiedene Ansätze. Zwei Artikel in englisch über 
+Dazu gibt es verschiedene Ansätze. Zwei Artikel in englisch über
 `Pipenv & Virtual Environments <https://docs.python-guide.org/dev/virtualenvs/>`__ und
-`Why the Need for Virtual Environments <https://realpython.com/python-virtual-environments-a-primer/>`__ 
-sind lesenswert. Eine Übersicht findet sich auf 
+`Why the Need for Virtual Environments <https://realpython.com/python-virtual-environments-a-primer/>`__
+sind lesenswert. Eine Übersicht findet sich auf
 `Stackoverflow <https://stackoverflow.com/questions/41573587/what-is-the-difference-between-venv-pyvenv-pyenv-virtualenv-virtualenvwrappe>`__.
 
 Danach werden aktuell (Stand November 2020) empfohlen:
@@ -18,6 +18,15 @@ Danach werden aktuell (Stand November 2020) empfohlen:
 * `Python.org <Python.org>`__ --> `venv <https://docs.python.org/3/library/venv.html>`__
 * `Real Python <https://realpython.com/intro-to-pyenv/>`__ --> `Pyenv <https://github.com/pyenv/pyenv#installation>`__
 
+.. hint::
+
+    Seit SmartHomeNG v1.10 wird der Betrieb von SmartHomeNG in virtuellen standardmäßig unterstützt und empfohlen
+    (siehe auch :doc:`Komplettanleitung </installation/komplettanleitung/02_smarthomeng>`).
+
+    Eine ausführlichere Beschreibung zur Unterstützung virtueller Environments in SmartHomeNG ist in der
+    :doc:`Referenz </referenz/python/virtual_environments>` zu finden.
+
+|
 
 Venv
 ----
@@ -30,31 +39,31 @@ erstellt und aktiviert. Pip wird aktualisiert und die Basisabhängigkeiten von S
 
 .. code-block:: bash
 
-   cd /usr/local/smarthome                         # Eventuell an anderes Basisverzeichnis anpassen 
+   cd /usr/local/smarthome                         # Eventuell an anderes Basisverzeichnis anpassen
    python3 -m venv env
    source env/bin/activate                         # Aktivieren der virtuellen Umgebung für diese Shell
    python3 -m pip install pip --upgrade            # Pip für virtuelle Umgebung aktualisieren
    python3 -m pip install -r requirements/base.txt # Installieren der Bibliotheken für die Basis von SmartHomeNG
 
 Nun sollten die Abhängigkeiten für die Basis von SmartHomeNG erfüllt sein.
-Einige Plugins brauchen eventuell weitere Bibliotheken. Jedes Plugin bringt eine eigene 
+Einige Plugins brauchen eventuell weitere Bibliotheken. Jedes Plugin bringt eine eigene
 ``requirements.txt`` Datei mit. Die benötigten Bibliotheken können installiert werden mit:
 
 .. code-block:: bash
 
-   cd /usr/local/smarthome                            # Eventuell an anderes Basisverzeichnis anpassen 
+   cd /usr/local/smarthome                            # Eventuell an anderes Basisverzeichnis anpassen
    source env/bin/activate                            # Aktivieren der virtuellen Umgebung für diese Shell
    pip install -r plugins/pluginname/requirements.txt # Installieren der Bibliotheken für das Plugin <pluginname>
 
-Es gilt daran zu denken, das es Python Bibliotheken gibt, die weitere Pakete benötigen die nur mit 
+Es gilt daran zu denken, das es Python Bibliotheken gibt, die weitere Pakete benötigen die nur mit
 apt installiert werden können. In diesem Fall sollte es einen Hinweis in der Readme des Plugins geben.
 
 Jedes mal wenn man SmartHomeNG mit einer virtuellen Umgebung nutzen will,
 muß diese in der aktuellen Shell aktiviert werden:
 
 .. code-block:: bash
 
-   cd /usr/local/smarthome                         # Eventuell an anderes Basisverzeichnis anpassen 
+   cd /usr/local/smarthome                         # Eventuell an anderes Basisverzeichnis anpassen
    source env/bin/activate                         # Aktivieren der virtuellen Umgebung für diese Shell
 
 Die virtuelle Umgebung kann deaktiviert werden durch den Befehl ``deactivate`` in der aktuellen Shell.
@@ -64,7 +73,7 @@ Pyenv
 
 Pyenv ist in der Lage mit unterschiedlichen Python Versionen umzugehen. Das ist dann sinnvoll um einen
 Code mit verschiedenen Interpretern laufen zu lassen und zu testen.
-Da Pyenv nicht im Lieferumfang von Python enthalten ist, muß es extra installiert werden. 
+Da Pyenv nicht im Lieferumfang von Python enthalten ist, muß es extra installiert werden.
 Die Anweisungen und Nutzungsbeschreibung finden sich im `Github Repo <https://github.com/pyenv/pyenv>`__
 für das Pyenv Projekt.
 
@@ -77,7 +86,7 @@ Pipenv
 Pipenv kombiniert Pip mit virtuellen Umgebungen und kann Pyenv automatisch verwenden,
 um verschiedene Versionen von Python für jedes Projekt zu installieren und zu verwenden.
 
-Unter `Pipenv: A Guide to the New Python Packaging Tool <https://realpython.com/pipenv-guide/>`__ 
+Unter `Pipenv: A Guide to the New Python Packaging Tool <https://realpython.com/pipenv-guide/>`__
 gibt es eine englischsprachige Einführung.
 
 

doc/user/source/installation/anforderungen.rst

@@ -171,19 +171,20 @@ Python Versionen
 Minimum Python Version
 ----------------------
 
-Die absolute Minimum Python Version in der SmartHomeNG startet wurde mit SmartHomeNG v1.9 auf **Python 3.7** angehoben,
-da Features verwendet werden, die Unter Python 3.6 und davor nicht vorhanden sind und da Python 3.6 im Dezember 2021
-End-of-Life (End of security fixes) gegangen ist. Bei einer Neuinstallation wird jedoch empfohlen auf einer der
-neueren Python Versionen (3.8, 3.9 oder 3.10) aufzusetzen.
+Die absolute Minimum Python Version in der SmartHomeNG startet wurde bereits mit SmartHomeNG v1.10 auf **Python 3.8**
+angehoben.
+Da auch Python 3.8 im Oktober 2024 den Status **End-of-Life** (End of security fixes) erreicht, wird empfohlen
+bei einer Neuinstallation auf einer der neueren offizell in SmartHomeNG unterstützten Python Versionen
+(3.10, 3.11 oder 3.12) aufzusetzen.
 
-Die aktuelle Version von SmartHomeNG setzt Python der **Version 3.7** oder neuer voraus. Bei Einsatz einer älteren
+Die aktuelle Version von SmartHomeNG setzt Python der **Version 3.8** oder neuer voraus. Bei Einsatz einer älteren
 Python Version, startet SmartHomeNG nicht.
 
 
 Unterstützte Python Versionen
 -----------------------------
 
-Die älteste offiziell unterstützte Python Version für SmartHomeNG Release 1.9.x ist **Python 3.7**. (Diese Version
+Die älteste offiziell unterstützte Python Version für SmartHomeNG Release 1.11.x ist **Python 3.10**. (Diese Version
 muss nicht mit der *Minimum Python Version* übereinstimmen.
 
 Die Grundregel nach der sich der Support für Python Versionen richten
@@ -226,9 +227,10 @@ ist in der folgenden Tabelle aufgelistet:
   "3.8",   "security",     "14\. Oktober 2019",    "Oktober 2024"
   "3.9",   "security",     "5\. Oktober 2020",     "Oktober 2025"
   "3.10",  "security",     "4\. Oktober 2021",     "Oktober 2026"
-  "3.11",  "bugfix",       "24\. Oktober 2022",    "Oktober 2027"
+  "3.11",  "security",     "24\. Oktober 2022",    "Oktober 2027"
   "3.12",  "bugfix",       "2\. Oktober 2023",     "Oktober 2028"
   "3.13",  "prerelease",   "1\. Oktober 2024",     "Oktober 2029"
+  "3.13",  "feature",      "1\. Oktober 2025",     "Oktober 2030"
 
 
 Python (und PHP) Versionen unter Linux

doc/user/source/installation/komplettanleitung/09_esphome.rst

@@ -0,0 +1,101 @@
+
+.. index:: ESPHome; ESPHome Dashboard Installation
+
+.. role:: bluesup
+.. role:: redsup
+
+===============================
+ESPHome Dashboard :redsup:`new`
+===============================
+
+Wenn ESPHome Devices mit SmartHomeNG verwendet werden sollen, kann es hilfreich sein das ESPHome Dashboard auf dem
+Rechner zu installieren, auf dem SmartHomeNG läuft.
+
+Im folgenden wird beschrieben, wie das ESPHome Dashboard auf dem SmartHomeNG System installiert werden sollte.
+
+|
+
+Virtuelles Environment erstellen
+================================
+
+Das ESPHome Dashboard verwendet eine recht große Anzahl von Python Packages. Um Konflikte mit Packages/Package-Versionen
+die in SmartHomeNG verwendet werden zu vermeiden, sollte das ESPHome Dashboard in einem eigenen virtuellen Environment
+laufen.
+
+Das virtuelle Environemnt hierfür wird mit dem folgenden Befehl angelegt:
+
+.. code-block:: bash
+
+    $ make_venv 3.10 esphome
+
+|
+
+ESPHome Dashboard installieren
+==============================
+
+Das ESPHome Dashboard muss im laufenden virtuellen Environment installiert werden. Das virtuelle Environment muss dazu
+vorher mit dem folgenden Befehl aktiviert werden:
+
+.. code-block:: bash
+
+    $ source act epshome
+
+Nun kann das ESPHome Dashboard mit den folgenden Befehlen angelegt werden:
+
+.. code-block:: bash
+
+    (py_esphome) $ pip3 install wheel
+    (py_esphome) $ pip3 install esphome
+
+Nun sollte das ESPHome Dashboard installiert sein. Mit dem folgenden Befehl kann die Installation überprüft und
+die installierte Version angezeigt werden:
+
+.. code-block:: bash
+
+    (py_esphome) $ esphome version
+    Version: 2024.9.2
+
+Nun muss noch das Verzeichnis angelegt werden, in dem die Konfigurationen für ESPHome gespeichert werden.
+
+.. code-block:: bash
+
+    (py_esphome) $ mkdir /usr/local/smarthome/var/esphome
+    (py_esphome) $ mkdir /usr/local/smarthome/var/esphome/config
+
+Die Dateien aus dem Verzeichnis ``/usr/local/smarthome/var/esphome/config`` werden beim Backup und Restore der
+Konfiguration von SmartHomeNG mit gesichert bzw. zurück gespielt.
+
+|
+
+ESPHome Dashboard starten und testen
+====================================
+
+Innerhalb des virtuellen Environments wird das Dashboard mit dem folgenden Befehl gestartet:
+
+.. code-block:: bash
+
+    (py_esphome) $ cd /Users/Martin/ESPHome
+    (py_esphome) $ esphome dashboard /usr/local/smarthome/var/esphome/config
+
+Nun sollte das Dashboard mit einem Browser (Chrome oder Safari) aufgerufen werden können. Die URL dazu ist
+
+    <Name/ip des SmartHomeNG Systems>:6052
+
+Nun sollte das ESPHome Dashboard angezeigt werden.
+
+Der folgende Screenshot zeigt das Dashboard, welches im lokalen Netzwerk bereits ein ESPHome Device entdeckt
+(discovered) hat.
+
+.. image:: /_static/img/esphome-dashboard.jpg
+   :class: screenshot
+
+|
+
+ESPHome Dashboard als Dienst einrichten
+=======================================
+
+Damit das ESPHome Dashboard bei jedem Start des Systems automatisch gestartet wird, muss es als Dienst eingerichtet
+werden.
+
+...
+

doc/user/source/installation/komplettanleitung/komplettanleitung.rst

@@ -34,4 +34,5 @@ Es bietet sich an die allererste Installation einfach in einer virtuellen Maschi
    06_onewire
    07_samba
    08_shng_daemon
+   09_esphome
 

doc/user/source/referenz/python/virtual_environments.rst

@@ -70,7 +70,7 @@ Jetzt kann mit dem folgenden Befehl ein virtual Environment erstellt werden, wel
 
 .. code-block:: bash
 
-    $ make_env 3.10
+    $ make_venv 3.10
 
 Während der Anlage wird das Environment aktiviert, um einige norwendige Python Packages in das Environment zu
 installieren bzw. zu aktualisieren.

lib/backup.py

@@ -117,6 +117,7 @@ def create_backup(conf_base_dir, base_dir, filename_with_timestamp=False, before
     structs_dir = os.path.join(conf_dir, 'structs')
     uf_dir = os.path.join(conf_dir, 'functions')
     var_dir = os.path.join(conf_dir, 'var')
+    esphome_conf_dir = os.path.join(conf_dir, 'var', 'esphome', 'config')
 
     # create new zip file
     #backupzip = zipfile.ZipFile(backup_dir + os.path.sep + backup_filename, mode='w')
@@ -174,6 +175,10 @@ def create_backup(conf_base_dir, base_dir, filename_with_timestamp=False, before
     arc_dir = 'infos'
     backup_file(backupzip, source_dir, arc_dir, 'systeminfo.yaml')
 
+    # backup files from /var/esphome/config
+    backup_directory(backupzip, esphome_conf_dir, '.yaml', 'esphome_config')
+
+    # create and backup list of installed pip packages
     shpypi = Shpypi.get_instance()
     if shpypi is None:
         shpypi = Shpypi()
@@ -237,21 +242,25 @@ def backup_file(backupzip, source_dir, arc_dir, filename):
     return
 
 
-def backup_directory(backupzip, source_dir, extenstion='.yaml'):
+def backup_directory(backupzip, source_dir, extenstion='.yaml', dest_dir=None):
     """
     Backup all files with a certain extension from the given directory to a zip-archive
 
     :param backupzip: Name of the zip-archive (full pathname)
     :param source_dir: Directory where the yaml-files to backup are located
     :param extenstion: Extension of the files to backup (default is .yaml)
     """
-    path = source_dir.split(os.path.sep)
-    dir = path[len(path)-1]
-    arc_dir = dir + os.path.sep
-    files = []
-    for filename in os.listdir(source_dir):
-        if filename.endswith(extenstion) or extenstion == '.*':
-            backup_file(backupzip, source_dir, arc_dir, filename)
+    if os.path.isdir(source_dir):
+        path = source_dir.split(os.path.sep)
+        dir = path[len(path)-1]
+        if dest_dir is None:
+            arc_dir = dir + os.path.sep
+        else:
+            arc_dir = dest_dir + os.path.sep
+        files = []
+        for filename in os.listdir(source_dir):
+            if filename.endswith(extenstion) or extenstion == '.*':
+                backup_file(backupzip, source_dir, arc_dir, filename)
 
     return
 
@@ -288,6 +297,7 @@ def restore_backup(conf_base_dir, base_dir, config_etc=False):
     scenes_dir = os.path.join(conf_dir, 'scenes')
     structs_dir = os.path.join(conf_dir, 'structs')
     uf_dir = os.path.join(conf_dir, 'functions')
+    esphome_conf_dir = os.path.join(conf_dir, 'var', 'esphome', 'config')
 
     archive_file = ''
     for filename in os.listdir(restore_dir):
@@ -323,18 +333,21 @@ def restore_backup(conf_base_dir, base_dir, config_etc=False):
     # restore files to /items
     restore_directory(restorezip, 'items', items_dir, overwrite)
 
-    # backup files from /logic
+    # restore files to /logic
     restore_directory(restorezip, 'logics', logic_dir, overwrite)
 
-    # backup files from /scenes
+    # restore files to /scenes
     restore_directory(restorezip, 'scenes', scenes_dir, overwrite)
 
-    # backup files from /structs
+    # restore files to /structs
     restore_directory(restorezip, 'structs', structs_dir, overwrite)
 
-    # backup files from /functions
+    # restore files to /functions
     restore_directory(restorezip, 'functions', uf_dir, overwrite)
 
+    # restore files to /var/esphome/config
+    restore_directory(restorezip, 'esphome_config', esphome_conf_dir, overwrite)
+
     # mark zip-file as restored
     logger.info(f"- marking zip-file as restored")
     os.rename(restorezip_filename, restorezip_filename + '.done')