Merge remote-tracking branch 'upstream/develop' into conf-1

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:

dev/sample_smartdevice_plugin/__init__.py

@@ -62,7 +62,7 @@ class example(SmartDevicePlugin):
     def _set_device_defaults(self):
 
         # you can add initialisations and internal defaults here
-        
+
         # for demonstation purposes, we want to use the null connection
         self._parameters[PLUGIN_ATTR_CONNECTION] = CONN_NULL
         self._use_callbacks = True
@@ -87,6 +87,18 @@ def on_disconnect(self, by=None):
         """ callback if connection is broken. """
         self.logger.info('example plugin disconnected')
 
+    # if you want to use the suspend/resume feature, you can overwrite these
+    # methods and customize to your liking. If not, you can safely delete them
+    # These are then called after suspending or resuming the plugin.
+
+    def on_suspend(self):
+        """ called when suspend is enabled. Overwrite as needed """
+        self.logger.info('suspend enabled, on_suspend called')
+
+    def on_resume(self):
+        """ called when suspend is disabled. Overwrite as needed """
+        self.logger.info('suspend disabled, plugin resumed, on_resume called')
+
 
 # needed to start operation in standalone mode
 # as we don't have a run_standalone() method, only struct generation can be used

dev/sample_smartdevice_plugin/plugin.yaml

@@ -59,6 +59,20 @@ parameters:
             de: 'Intervall für regelmäßiges Lesen'
             en: 'interval for cyclic reading'
 
+    delay_initial_read:
+        type: num
+        default: 0
+        description:
+            de: 'Verzögerung für das erstmalige Lesen beim Start (in Sekunden)'
+            en: 'delay for initial command read on start (in seconds)'
+
+    resume_initial_read:
+        type: bool
+        defaul: false
+        description:
+            de: 'Bei resume vom Plugin erstmaliges Lesen erneut durchführen'
+            en: 'Repeat initial read on resume'
+
     # select if ex_custom1/2/3 item attributes should be inherited by sub-items
     # !! irrelevant if ex_custom1/2/3 not implemented
     recursive_custom:

dev/sample_smartdevice_standalone_plugin/__init__.py

@@ -87,6 +87,18 @@ def on_disconnect(self, by=None):
         """ callback if connection is broken. """
         self.logger.info('example plugin disconnected')
 
+    # if you want to use the suspend/resume feature, you can overwrite these
+    # methods and customize to your liking. If not, you can safely delete them
+    # These are then called after suspending or resuming the plugin.
+
+    def on_suspend(self):
+        """ called when suspend is enabled. Overwrite as needed """
+        self.logger.info('suspend enabled, on_suspend called')
+
+    def on_resume(self):
+        """ called when suspend is disabled. Overwrite as needed """
+        self.logger.info('suspend disabled, plugin resumed, on_resume called')
+
 #
 # methods for standalone mode
 #

dev/sample_smartdevice_standalone_plugin/plugin.yaml

@@ -59,6 +59,20 @@ parameters:
             de: 'Intervall für regelmäßiges Lesen'
             en: 'interval for cyclic reading'
 
+    delay_initial_read:
+        type: num
+        default: 0
+        description:
+            de: 'Verzögerung für das erstmalige Lesen beim Start (in Sekunden)'
+            en: 'delay for initial command read on start (in seconds)'
+
+    resume_initial_read:
+        type: bool
+        defaul: false
+        description:
+            de: 'Bei resume vom Plugin erstmaliges Lesen erneut durchführen'
+            en: 'Repeat initial read on resume'
+
     # select if ex_custom1/2/3 item attributes should be inherited by sub-items
     # !! irrelevant if ex_custom1/2/3 not implemented
     recursive_custom:

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,145 @@
+
+.. 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.
+
+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, wird das ESPHome Dashboard in einem eigenen virtuellen Environment
+installiert. Die minimal benötigte Python Version für ESPHome ist zurzeit Python 3.9.
+
+Zur Installation und Verwaltung von ESPHome sind Skripte im ``tools`` Verzeichnis der SmartHomeNG Installation
+vorhanden.
+
+Die Installation erfolgt mithilfe des Skripts `esphome_install`.
+
+.. code-block:: bash
+
+    $ esphome_install
+
+Das Skript
+
+  - prüft ob eine für ESPHome benötigte Python Version auf dem System gefunden wird
+  - erstellt ein virtuelles Environment mit der entsprechenden Python Version
+  - aktiviert das erstellte virtuelle Environment
+  - installiert ESPHome in das virtuelle Environment
+  - zeigt anschließend die Version von ESPHome an, die installiert wurde
+  - und erzeugt das Verseichnis in dem die Konfigurationen für ESPHome gespeichert werden
+
+Die Dateien aus dem erzeugten Verzeichnis ``/usr/local/smarthome/var/esphome/config`` werden beim Backup und Restore
+der SmartHomeNG Konfiguration mit gesichert bzw. zurück restauriert.
+
+|
+
+ESPHome Dashboard starten und testen
+====================================
+
+Das ESPHome Dashboard kann im aktuellen Terminal Fenster mit dem Befehl
+
+.. code-block:: bash
+
+    $ esphome_start
+
+gestartet werden und mit Ctrl-C wieder beendet werden.
+
+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:: /installation/assets/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.
+
+Da ESPHome in ein virtuelles Environment installiert wurde, muss dieses virtuelle Environment zum starten dest
+Dienstes genutzt werden. Es muss der Python Interpreter aus diesem virtuellen Environment genutzt werden um
+esphome zu betreiben. Dazu muss der folgende Text in die Datei ``/etc/systemd/system/esphome.service`` eingefügt werden:
+
+.. code-block:: bash
+
+    [Unit]
+    Description=ESPHome-dashboard daemon
+    After=network-online.target
+
+    [Service]
+    Type=simple
+    ExecStart=/usr/local/smarthome/tools/esphome_start
+    User=smarthome
+    Restart=on-failure
+    RestartSec=30
+    TimeoutStartSec=900
+    RestartForceExitStatus=5
+    Environment="PATH=/usr/local/smarthome/venvs/py_esphome/bin:/usr/local/sbin:/usr$
+
+    [Install]
+    WantedBy=default.target
+
+|
+
+Starten des Dienstes
+====================
+
+Der so vorbereitete Dienst kann über den **systemctl** Befehl gestartet
+werden.
+
+.. code-block:: bash
+
+   sudo systemctl start esphome.service
+
+Wenn alles ok ist, kann der Autostart aktiviert werden:
+
+.. code-block:: bash
+
+   sudo systemctl enable esphome.service
+
+Bei Systemstart wird nun das ESPHome Dashboard automatisch gestartet.
+
+Um den Dienst wieder auszuschalten und den Neustart bei Systemstart zu
+verhindern nutzt man:
+
+.. code-block:: bash
+
+   sudo systemctl disable esphome.service
+
+Um zu sehen, ob das ESPHome Dashboard läuft, genügt ein
+
+.. code-block:: bash
+
+   systemctl status esphome.service
+
+Läuft es noch nicht und man möchte sozusagen manuell starten reicht ein:
+
+.. code-block:: bash
+
+   sudo systemctl start esphome.service
+
+Ein Neustart des Dashboards würde mit
+
+.. code-block:: bash
+
+   sudo systemctl restart esphome.service
+
+funktionieren, ein Stop von SmartHomeNG entsprechend
+
+.. code-block:: bash
+
+   sudo systemctl stop esphome.service
+

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.