How to use Toolbox, Toolbox erklärt.

There are 5 replies in this Thread which has previously been viewed 912 times. The latest Post (January 30, 2024 at 6:46 PM) was by _[Deleted]_.

  • In diesem Thread möchte ich euch erklären wie genau die Toolbox, funktioniert, etwas, das ich mittlerweile in nahezu allen meinen Shelly-Scripts integriert habe.

    Was ist die Shelly Script Toolbox?

    Die Shelly Script Toolbox ist ein Ensemble von Funktionen innerhalb eines Shelly Scripts, welche von mir entwickelt wurden, um die Verwendung vorhandener Shelly-Funktionen und -Abläufe zu vereinfachen. Sie fungiert im Grunde als ein praktischer Werkzeugkasten, der das Erstellen von Shelly-Scripts beschleunigt und vereinfacht.

    Warum nicht einfach die nativen Shelly-Funktionen nutzen?

    Die Verwendung der nativen Shelly-Funktionen kann oft Nachteile mit sich bringen, denn sie sind häufig nicht mit effizienten Error Handling ausgestattet und verfügen über lange, komplexe Bezeichnungen, die bei häufigem Einsatz viel Memory beanspruchen können. Darüber hinaus werden die von den Entwicklern festgelegten Limits, innerhalb Shelly Scripts, von den nativen Shelly-Funktionen nicht berücksichtigt, was unerwünschte Ergebnisse zur Folge haben kann. Die Script Toolbox versucht, solche Probleme zu umgehen. Eine Limit Überschreitung führt nicht zum Abbruch des Scripts, sondern zu einer entsprechenden Fehlermeldung, bzw wird um das Limit herum jongliert, durch Warteschlangen etc. Natürlich gibt es Situationen, in denen die direkte Verwendung der nativen Funktionen sinnvoller ist. Dennoch zeigt die Toolbox ihre Stärke insbesondere bei wiederholter Nutzung bestimmter nativer Funktionen und bei der Automation von einfachen Abläufen.

    Wie kann ich die Toolbox in meinen Shelly Scripts nutzen?

    Zuerst einmal benötigt die Toolbox mindesten einen Shelly Gen2 mit der FW >1.0.8 oder besser.

    Die Integration der Toolbox in das eigene Shelly Script ist simpel, einfach am Ende des Scripts die Toolbox einfügen und eine Main() Funktion definieren.

    Link zur Toolbox:

    _[Deleted]_
    February 5, 2024 at 5:16 PM

    Die Toolbox besteht also aus einer Reihe von Tools, die das Erstellen von Shelly-Scripts effizienter und schneller gestalten.

    Um den Code so kompakt wie möglich zu halten und den Memory Verbrauch zu minimieren, ist die Toolbox stark komprimiert. In diesem Thread werde ich aber detailliert auf die einzelnen Tools der Toolbox eingehen und ausführlich dokumentieren, wie die jeweiligen Funktionen arbeiten, also ein How to use the Toolbox. Dies wird natürlich nicht über Nacht passieren, sondern einige Zeit in anspruch nehmen.

    Edited 4 times, last by _[Deleted]_ (February 5, 2024 at 5:20 PM).

  • Main()

    Zur Erhöhung der Skript Stabilität ist es erforderlich, dass vor der Verwendung einer Toolbox Funktion, eine Main() Funktion im Script definiert wird. Die Main() Funktion wird in der Toolbox automatisch von der Setup() Funktion aufgerufen und sollte den eigentlichen Haupt Code Block enthalten.

    In der Main() Funktion wird also der eigentliche Code festlegt.

    Anhand des beigefügten Beispiels wird deutlich, dass nach dem Durchlaufen des Setup() die in der Main() Funktion hinterlegten Anweisungen ausgeführt werden.

    Vor dem Ausführen der Main() Funktion ist eine kurze Verzögerung eingebaut. Dies dient als Sicherheitsmaßnahme, da das unmittelbare Ausführen von komplexen Code nach einem Shelly-Start zu einem Script-Abbruch führen kann. Dieses Verhalten ist auf einen bekannten Shelly FW Bug zurückzuführen, der bisher noch nicht behoben wurde. Darüber hinaus ist die Main() Funktion innerhalb Setup() in einen Try-Catch-Block eingebettet. Welcher die meisten auftretenden Fehler abfängt und sie an die ErrorMsg() Toolbox-Funktion übergibt. Die ErrorMsg() Funktion formatiert die Fehlermeldung und gibt den Fehler als Log / Consolen Eintrag aus, das ganze passiert ohne das Script abzubrechen.

    Weitere Informationen über die Setup() und ErrorMsg() Funktion der Toolbox ist weiter unten in jeweils separaten Beiträgen vorzufinden.

    Main() Beispiel:

    Screenshot 2024-01-01 19.01.09.png
    pasted-from-clipboard.png


    In dem nachfolgenden Beispielcode wurde absichtlich ein Fehler im Haupt Code Block eingebaut. Doch das Skript bleibt weiterhin aktiv und bricht nicht ab, wie es normalerweise der Fall wäre.

    Main() Error Beispiel:

    pasted-from-clipboard.png

    Screenshot 2024-01-01 20.08.37.png

    Die folgende Fehlermeldung wird erzeugt, beim Versuch, die Toolbox samt Setup() zu verwenden, ohne vorher eine Main() Funktion, zu definieren:

    pasted-from-clipboard.png

    Hier nochmal der Main Code Block den man vorher selbst definieren muss, function Main() { }

    Edited 24 times, last by _[Deleted]_ (January 25, 2024 at 9:24 PM).

  • Setup()

    Die Setup() Funktion innerhalb der Toolbox ist ein spezielles Tool, das ausschließlich von der Toolbox selbst verwendet wird.

    Diese Funktion wird am Ende der Toolbox aufgerufen. Ihre Hauptaufgabe umfasst die Prüfung, der Main() Funktion. Also ob diese im Script definiert wurde und ob dies auch vor der Toolbox passiert ist. Die Main() Funktion wird mit einer leichten Verzögerung von etwa 2 Sekunden in einem Try-Catch-Block ausgeführt. Diese kurze Verzögerung ist entscheidend, um einen bekannten Shelly FW Bug zu verhindern, der bei einem Shelly Neustart zu einem Script Abbruch führen kann. Darüber hinaus prüft Setup() die callLimit Variable. An dieser Stelle bietet sich auch die Möglichkeit, weitere Variable Checks einzubauen, um vor dem eigentlichen Start des Scripts zusätzliche Einstellungen oder Optionen zu überprüfen. Zusätzlich generiert die Setup() Funktion bei jedem Script Start eine Status Konsolenausgabe im Format: Status: started Script _[ scriptName ]_.

    Die meisten Fehler, die im Main() Code Block auftreten, werden von der Setup() Funktion abgefangen und an die ErrorMsg() Toolbox-Funktion weitergeleitet. Anschließend versucht Setup(), im Fehlerfall, alle 2 Sekunden erneut den Main() Code Block auszuführen. Der Setup() Teil benötigt einen Timer-Slot. Der globale Timer-Handler (tH9) dafür, wird am Ende der Toolbox initialisiert. Dieser globale Timer-Handler wird mit der Toolbox Cqueue() geteilt.

    - Die Setup() Nutzung ist abhängig vom ErrorMsg() Tool und nur zusammen mit diesem Tool möglich.

    Der Setup() Teil in der Toolbox:

    Screenshot 2024-01-02 19.57.09.png

    Setup() Aufruf am Ende der Toolbox:

    Screenshot 2024-01-02 18.49.45.png

    Die Variable scriptN (Script Name) wird von der Setup() Funktion in der Script Start Konsolenausgabe verwendet.

    Einige der nativen Shelly-Funktionen werden am Ende der Toolbox einfach nur umbenannt, scriptN wird durch die nun umbenannten nativen Shelly-Funktionen am Ende der Toolbox ermittelt.

    Als Variable scriptID (Script ID), scriptN (Script Name) und info (Shelly Infos) werden einige Standardwerte dauerhaft gespeichert, sodass diese Werte im gesamten Script zugänglich sind.

    Die Script Start Konsolenausgabe:

    pasted-from-clipboard.png

    Hier ist eine detaillierte und übersichtliche Darstellung der Setup() Toolbox Funktion:

    Screenshot 2024-01-02 19.53.11.png

    Hier das ganze als einfaches Code Beispiel, versehen mit ausführlichen Kommentaren:

    Edited 22 times, last by _[Deleted]_ (January 25, 2024 at 9:23 PM).

  • ErrorMsg()

    Die Funktion ErrorMsg() ist ein praktisches Tool mit dem Hauptzweck, Fehlerobjekte aus einem Try Catch Block zu formatieren. Sie stellt eine verbesserte Alternative zur Print() Funktion dar, insbesondere da die Print-Ausgabe unerwünschte "Error: Error:" Einträge aufwies. Aus diesem Grund entstand die Idee, eine eigenständige Funktion zu entwickeln, die sich speziell auf die ansprechende Darstellung und Ausgabe von Fehlerobjekten konzentriert.

    Mit der Zeit hat sich die ErrorMsg() Funktion weiterentwickelt und bietet nun in Verbindung mit dem Cut() Tool die Möglichkeit, mühelos individuelle Tooltips/Infos einzufügen. Durch die Verwendung der Variable "i" innerhalb der ErrorMsg() Funktion können benutzerdefinierte Tooltips, bzw. ergänzende Informationen bei bestimmten Fehlermeldungen nahtlos integriert werden. Zum Beispiel wird bei einem Call Timeout automatisch eine prägnante Info-Meldung ergänzt, die auf mögliche Probleme wie eine falsche URL hinweist "Info: maybe --> wrong URL or device may be offline". Diese Flexibilität erlaubt es, auch zukünftig einfach weitere Informationen hinzuzufügen, insbesondere wenn bestimmte Toolbox-Tools nicht korrekt angewendet werden oder temporäre zusätzliche Informationen benötigt werden.

    Ein weiteres Merkmal der ErrorMsg() Funktion ist, dass sie nicht nur das Fehlerobjekt ( e ) als Parameter erhält, sondern auch einen Fehler Titel-String ( s ). Dies bietet die Möglichkeit, durch den Titel individuelle Zusatzinformationen zur Fehlermeldung hinzuzufügen. Idealerweise ist der Titel passend zum jeweiligen Funktionsblock zu wählen, in dem der Try-Catch-Block eingebettet ist. Zusätzliche Informationen wie Fehler-Zeilen und Fehler-Stack werden standardmäßig ausgeblendet, da sie in vielen Fällen nicht erforderlich sind und meist nicht wirklich zum Ursprung des Fehlers passen. Wenn jedoch der Bedarf besteht, diese Informationen auszugeben, kann sie durch die Übergabe einer dritten Variable ( deBug ), die für die Ausgabe truthy sein muss, ausgegeben werden. Eine debug boolean Flag Variable bietet sich hierbei idealerweise an.

    Syntax:

    ErrorMsg(error_object, titel_string, debug);

    MeaningParameter in ToolboxTypeDescription
    error_objecteObject, (only a error object)the error Object created by a try catch block or by new Error()
    titel_stringsStringA Title String that will be Shown inside the log before the Error mssage.
    debugdeBugtruthy value, ( Boolean )Setting this to true will add information about where exactly the error might have occurred, to the Error: msg.


    - Die ErrorMsg() Nutzung ist abhängig vom Cut() Tool und nur zusammen mit diesem Tool möglich.

    Der ErrorMsg() Tool Teil in der Toolbox:

    Screenshot 2024-01-10 16.22.32.png

    Hier eine detaillierte und übersichtliche Darstellung der ErrorMsg() Toolbox Funktion:

    Screenshot 2024-01-10 16.32.11.png

    Hier das ganze als einfaches Code Beispiel, versehen mit ausführlichen Kommentaren

    Beispiel_0 nochmal verdeutlicht:

    Screenshot 2024-01-10 16.59.11 (1).png

    Ausgabe:

    Screenshot 2024-01-10 17.06.13.png

    Beispiel_1:

    Screenshot 2024-01-10 17.08.44 (1).png

    Ausgabe:

    Screenshot 2024-01-10 17.13.21.png

    Beispiel_2:

    Screenshot 2024-01-10 17.16.11 (1).png

    Ausgabe:

    Screenshot 2024-01-10 17.21.43 (1).png

    Beispiel_3

    Screenshot 2024-01-10 17.43.31 (1).png

    Beispiel_3 als Code:

    Ausgabe + Custom Extra Infos:

    Screenshot 2024-01-10 17.49.07 (1).png

    Edited 14 times, last by _[Deleted]_ (January 30, 2024 at 11:22 PM).

  • Cut()

    Das Cut() Tool ist im Grunde eine Kombination aus indexOf() und slice(). Es ermöglicht auf einfache Weise, Teile aus einem String oder einem Array zu extrahieren. Dieses Tool dient nicht nur dem ausschneiden von Daten, sondern auch zur schnellen Filterung bestimmter Kriterien oder Werte, insbesondere wenn es in Verbindung mit einer IF-Anweisung genutzt wird. Wenn die Funktion aufgerufen wird, benötigt sie als ersten Parameter die vollständigen Daten( f ) als String oder Array und als zweite Parameter einen Key( k ), der den Punkt markiert, ab dem der Schnitt erfolgt, dabei handelt es sich um eine Art Suchbegriff bzw. Wert nach dem in den übergebenen Daten gesucht wird. Wie bei einem Video-Editor Cut Tool wird alles ab diesem Punkt abgeschnitten und von der Cut() Funktion zurückgegeben. Der Key ( k ) wird als Number oder String übergeben. Falls Cut() den Key nicht in den Daten wiederfindet, wird "null" zurückgegeben.

    Optional kann als dritten Parameter ein Cut Offset( o ) angegeben werden, ebenfalls als Number oder String. Wenn ein String verwendet wird, ermittelt das Cut() Tool automatisch die Länge des Strings und verwendet dies als Offset. Auf diese Weise kann der Key, beim Ausschneiden recht einfach aus den extrahierten Daten ausgeschlossen werden.

    Eine Cut Anwendung mit Cut Key-Offset, würde in etwa so aussehen print(Cut("ShellShellySellerie","Shelly","Shelly")); --Cut-Ausgabe--> Sellerie

    Es gibt auch einen optionalen vierten Parameter der den Cut ab dem Key invertiert( i ). Hierfür muss der übergebene Wert truthy sein, idealerweise "true" oder "1". Dadurch wird der Teil vor dem Key ausgeschnitten, der Cut wird also invertiert, und die extrahierten Daten werden von der Cut() Funktion ausgegeben. Es ist jedoch zu beachten, dass der vierte Parameter nur nutzbar ist, wenn der dritte Parameter vorher festgelegt wurde. Falls kein Offset benötigt wird und der Cut trotzdem invertiert werden soll, muss als dritter Parameter trotzdem ein Offset von 0 vorhanden sein.

    Syntax:

    cutout_rest= Cut(full_data, key, offset, invert_cut);

    MeaningParameter in ToolboxTypeDescription
    full_datafString or ArrayFull data for cutting or searching in it.
    keykString, Number or BooleanValue to be searched for within f (full data) and marks the cutting point.
    offsetoNumber or StringCutting point offset. If the offset is a string, then the string.length is used.
    invert_cutitruthy value, ( Boolean ) Reverse the cut at the cutting point.
    cutout_restreturn valueString, Number or BooleanReturns the cutout rest or null if the key is not found in full_data.


    - Die Cut() Nutzung ist abhängig vom ErrorMsg() Tool und nur zusammen mit diesem Tool möglich.

    Der Cut() Tool Teil in der Toolbox:

    Screenshot 2024-01-17 22.04.03.png

    Hier ist eine detaillierte und übersichtliche Darstellung der Cut() Toolbox Funktion:

    Screenshot 2024-01-17 22.06.32.png


    Hier das ganze als einfaches Code Beispiel, versehen mit ausführlichen Kommentaren:

    Beispiel_0 bis Beispiel_3:

    Screenshot 2024-01-17 22.52.49 (1) (1) (3).png

    Beispiel_4 bis Beispiel_7:

    Screenshot 2024-01-18 00.26.15 (1) (1) (1).png

    Beispiel_8 bis Beispiel_10:

    Screenshot 2024-01-18 01.39.12 (3) (1) (2).png

    Beispiel_11 bis Beispiel_14:

    Screenshot 2024-01-18 02.52.34 (1) (2).png

    Alle Beispiele nochmals als Code:

    Edited 39 times, last by _[Deleted]_ (January 30, 2024 at 10:54 PM).

  • This threads contains one more post that have been hidden for guests, please register yourself or log-in to continue reading.