Zum Thema Commandref

Damian · 28 Dezember 2021, 19:04:20

siehe: https://forum.fhem.de/index.php/topic,125038.msg1196382.html#msg1196382

Benni · 29 Dezember 2021, 22:21:59

Ich bin mir jetzt nicht so sicher ob im Sinne von:

https://wiki.fhem.de/wiki/SVN_Nutzungsregeln#commandref-Regeln

ein Link auf das wiki ausreichend ist!

Ich finde es halt in sofern schade, dass damit die Offline-Doku für das Modul quasi keine Information mehr enthält.
Vor allem, da FHEM an sich mit "Cloud-Free" wirbt
Gerade DOIF ist ja ein Modul ist, das ansonsten keine Cloud benötigt.
Wenn das Schule macht sind wir bei FHEM demnächst so weit wie bei M$ und anderen, wo jede Doku nur noch Online verfügbar ist.

Man sollte hier vielleicht differenzieren zwischen minimaler Commandref (!) und ausführlicher Doku, mit Beispielen und Trallala.

Auf der anderen Seite haben wir aber auch schon die Fragmentierung in svn und diverse einbindbare git-repositories. Kann man auch so oder so sehen.

gb#

marvin78 · 30 Dezember 2021, 06:52:27

Man muss einfach nur lernen zwischen Doku und Beispielsammlung zu unterscheiden. Dann ist klar, was wohin gehört und dann kann man auch Doif endlich richtig dokumentieren.
.

Damian · 30 Dezember 2021, 10:00:55

Zitat von: marvin78 am 30 Dezember 2021, 06:52:27
Man muss einfach nur lernen zwischen Doku und Beispielsammlung zu unterscheiden. Dann ist klar, was wohin gehört und dann kann man auch Doif endlich richtig dokumentieren.
.

Eine DOIF-Dokumentation, die aus Syntaxbeschreibung bestehen würde, würden die wenigsten FHEM-User verstehen. Wenn ich etwas nachschlagen will, dann schlage ich dort nach, wo ich die Syntax nachlesen kann und gleich ein typisches Beispiel ansehen kann um diese zu verstehen, ohne irgendwo im Web nach Anwendungsbeispielen zu suchen. Das ist genauso z. B. beim notify oder at (wo ist die Doku zum Dummy

), deren Doku-Umfang mit Beispielen! in der Commandref dürfte im gleichen Verhältnis zu deren Funktionsumfang stehen, wie die DOIF-Doku zu DOIF-Funktionsumfang.

Abgesehen davon lässt sich Dokumentation im Wiki einfacher erstellen und pflegen, besser strukturieren und wesentlich übersichtlicher gestalten.

Damian · 30 Dezember 2021, 10:07:32

Zitat von: Benni am 29 Dezember 2021, 22:21:59
Ich bin mir jetzt nicht so sicher ob im Sinne von:

https://wiki.fhem.de/wiki/SVN_Nutzungsregeln#commandref-Regeln

ein Link auf das wiki ausreichend ist!

Ich finde es halt in sofern schade, dass damit die Offline-Doku für das Modul quasi keine Information mehr enthält.
Vor allem, da FHEM an sich mit "Cloud-Free" wirbt
Gerade DOIF ist ja ein Modul ist, das ansonsten keine Cloud benötigt.
Wenn das Schule macht sind wir bei FHEM demnächst so weit wie bei M$ und anderen, wo jede Doku nur noch Online verfügbar ist.

Man sollte hier vielleicht differenzieren zwischen minimaler Commandref (!) und ausführlicher Doku, mit Beispielen und Trallala.

Auf der anderen Seite haben wir aber auch schon die Fragmentierung in svn und diverse einbindbare git-repositories. Kann man auch so oder so sehen.

gb#

Naja, zur Laufzeit wird keine Cloud benötigt. Dokumentation zu irgendetwas ist nicht sicherheitsrelevant und steht heutzutage natürlich im Netz - wo denn sonst

martinp876 · 05 Januar 2022, 10:13:38

eine syntaktische Kommandobeschreibung mache ich immer online - im code beiliegend. Somit sehe ich das 3-stufig
1) liste aller Kommandos mit required und optional parameter
=> insbesondere hilfreich für Entites mit vielen Kommandos
=> schneller Überblick über Reihenfolge der Parameter, schreibweise, options - in listenform
=> kurze notes möglich
=> Beschreibung eines Kommandos sollte in 1 Zeile passen
=> da im Code liegend wird dies auch gleich zum Parsen des Inputs genutzt (siehe Vorschlag https://forum.fhem.de/index.php/topic,125067.0.html)
Insbesonder Module deren entities unterschiedliche Kommandos unterstützen (das trifft sicher 99% der Home-Automation familien) ist eine Kommando-kurzübersicht hilfreich, m.E. Pflicht (incl dedicted attr list)

2)commandref
ist mit mehr prosa versehen - Beschreibung wird eingeblendet. Das MUSS offline funktionieren - oder abgeschafft werden. Online geht hier nicht.

3) Wiki
Hier steht die Handhabung

DOIF ist sicher kein Paradebeispiel für diese Art von Dokumentation. Es ist eher als Meta-sprache angelegt - und ist wohl nur im Wiki zu erklären. Es als Massstab für die Doku zu sehen ist m.E. grundsätzlich ungeeignet.

Damian · 05 Januar 2022, 16:44:15

Ich werde den Großteil der DOIF-Doku in der Commandref belassen, da inzwischen für die Attribute oder Set-Befehle, eine lokale Hilfe eingeblendet wird und viele Querverweise existieren. Ich habe mich lange Zeit gegen Wiki-Einträge gesträubt, weil dort auch andere, unwissende "Unsinn" verfassen können. Allerdings habe ich positive Erfahrung bei der Beschreibung des komplexen DOIF-Attributes uiTable https://wiki.fhem.de/wiki/DOIF/uiTable_Schnelleinstieg gesammelt - dort traut sich offenbar keiner seinen Senf dazu zu tun - und das ist auch gut so. Auf jeden Fall kann ich aus meiner Erfahrung sagen, dass sich Dokumentation mit diversen Formatierungsmöglichkeiten im Wiki wesentlich einfacher erstellen und pflegen lässt, als es im Sourcecode zu tun.

martinp876 · 15 Januar 2022, 12:53:56

nun habe ich mir DOIF einmal angesehen - bezüglich Doku:
Commandref existiert eigentlich nur in Deutsch. Ich dachte immer die standart-Sprache ist Englisch. Wenn nur eine Sprache existiert sollte man das deutlic machen. Die Fragmente in Englisch kann man geradezu weglassen - oder eben vervollständigen. Da ist man mit einem auto-übersetzer noch besser dran.

Irgend etwas scheint nicht korrekt dokumentiert zu sein - zumindst ich bekomme die Bespiele mit "package ui_Table" nicht zum Laufen. Den einfachen Hinweis, was bei mir nicht installiert ist, habe ich zumindest noch nicht gefunden.

uiTable is ein echt cooles feature - wenn ich es einmal zum Laufen bekomme. Allerdings ist es M.E. völlig falsche aufgehängt. DOIF ist ein "Event 2 trigger" funktion welche auf Basis von Events irgend etwas auslöst.
uiTable ist - so ist es auch beschrieben, ein Web-Frontend. Es hat eigentlich mich DOIF garnichts zu tun. Ich finde es daher exterm schade, dass es nicht so angelegt ist. Für mich sieht es so aus, dass ein Autor sich eine - mit Sicherheit! - coole Funktion/Feature hat einfalle lassen - und es eben einmal in irgend ein gerade greifbares Modul eingebaut, welches gerade in seinem Edditor offen war. Für den System-gedanken halte ich das für nicht hilfreich.
De-fakto bietet DOIF eine reine Visualisierung von beliebigen Enties an.

Sinnvoll wäre, ein eigenes Modul zu erstellen, was ich überall einsetzen kann - oder einen Helper welcher von jeden Device genutzt werden kann.

Damian · 15 Januar 2022, 14:42:20

Zitat von: martinp876 am 15 Januar 2022, 12:53:56
nun habe ich mir DOIF einmal angesehen - bezüglich Doku:
Commandref existiert eigentlich nur in Deutsch. Ich dachte immer die standart-Sprache ist Englisch. Wenn nur eine Sprache existiert sollte man das deutlic machen. Die Fragmente in Englisch kann man geradezu weglassen - oder eben vervollständigen. Da ist man mit einem auto-übersetzer noch besser dran.

Irgend etwas scheint nicht korrekt dokumentiert zu sein - zumindst ich bekomme die Bespiele mit "package ui_Table" nicht zum Laufen. Den einfachen Hinweis, was bei mir nicht installiert ist, habe ich zumindest noch nicht gefunden.

uiTable is ein echt cooles feature - wenn ich es einmal zum Laufen bekomme. Allerdings ist es M.E. völlig falsche aufgehängt. DOIF ist ein "Event 2 trigger" funktion welche auf Basis von Events irgend etwas auslöst.
uiTable ist - so ist es auch beschrieben, ein Web-Frontend. Es hat eigentlich mich DOIF garnichts zu tun. Ich finde es daher exterm schade, dass es nicht so angelegt ist. Für mich sieht es so aus, dass ein Autor sich eine - mit Sicherheit! - coole Funktion/Feature hat einfalle lassen - und es eben einmal in irgend ein gerade greifbares Modul eingebaut, welches gerade in seinem Edditor offen war. Für den System-gedanken halte ich das für nicht hilfreich.
De-fakto bietet DOIF eine reine Visualisierung von beliebigen Enties an.

Sinnvoll wäre, ein eigenes Modul zu erstellen, was ich überall einsetzen kann - oder einen Helper welcher von jeden Device genutzt werden kann.

Das kann man natürlich sehen, wie man will. Würde FHEM einen internationalen Ruhm erlangen, hätte ich längst den englischen Part ergänzt. Für 3% der FHEM-User war mir seinerzeit der Aufwand für eine ständige Übersetzung neuer Features (und es waren einige) zu hoch.

uiTable sollte mit der aktuellen FHEM-Version funktionieren. Im Verzeichnis pgm2 sollte sich die Datei doif.js befinden.

Naja, uiTable arbeitet ebenfalls ereignisgesteuert, daher wird der größte Programmteil von DOIF: Auswertung von Ereignistriggern mit [<DOIF-Syntax für Ereignistrigger>] benötigt.

An solchen Beispielen: https://wiki.fhem.de/wiki/DOIF/Automatisierung#Beschattungssteuerung_abh.C3.A4ngig_von_der_Zimmertemperatur_und_Sonneneinstrahlung_f.C3.BCr_mehrere_Szenarien_mit_Visualisierung
kann man sehen, dass die Steuerung und Web-Frontend in einem Modul keine schlechte Idee sein muss.

DOIF ist inzwischen mehr als nur eine Alternative zu notify oder at. Bevor man ein Modul für etwas entwickelt, kann man überlegen, ob evtl. eine DOIF-Definition mit Web-Frontend schneller zu einer zufriedenstellenden Lösung für eine Aufgabe führt. Insb. im Perlmodus kann man sich nach Belieben austoben.

Damian · 16 Januar 2022, 19:39:17

Und zu:

ZitatSinnvoll wäre, ein eigenes Modul zu erstellen, was ich überall einsetzen kann - oder einen Helper welcher von jeden Device genutzt werden kann.

Du kannst, bis auf die SVG-Funktion card, alle SVG-uiTable-Funktionen unmittelbar im devStateIcon eines beliebigen Devices nutzen - da sie nur HTML-Code generieren.

Z. B.

Code Auswählen

defmod Aussensensor CUL_WS 1
attr Aussensensor devStateIcon {ui_Table::temp_hum_ring(ReadingsVal($name,"temperature",0),ReadingsVal($name,"humidity",0))}

Benni · 16 Januar 2022, 22:10:58

Zitat von: Damian am 16 Januar 2022, 19:39:17
Du kannst, bis auf die SVG-Funktion card, alle SVG-uiTable-Funktionen unmittelbar im devStateIcon eines beliebigen Devices nutzen - da sie nur HTML-Code generieren.

Z. B.

Code Auswählen Erweitern
defmod Aussensensor CUL_WS 1 attr Aussensensor devStateIcon {ui_Table::temp_hum_ring(ReadingsVal($name,"temperature",0),ReadingsVal($name,"humidity",0))}

Aber auch nur, wenn man auch irgendwo ein DOIF hat

Code Auswählen


Undefined subroutine &ui_Table::temp_hum_ring called at (eval 41651044) line 1.

gb#

Damian · 16 Januar 2022, 22:51:37

Zitat von: Benni am 16 Januar 2022, 22:10:58
Aber auch nur, wenn man auch irgendwo ein DOIF hat

Code Auswählen Erweitern
Undefined subroutine &ui_Table::temp_hum_ring called at (eval 41651044) line 1.

gb#

ja, das Modul muss einmal geladen sein, ein

Code Auswählen

defmod di DOIF

sollte dann schon reichen.

Beta-User · 01 Februar 2022, 10:53:41

Könntest du bei Gelegenheit bitte den Anker aus #7620 rausnehmen? Der zerstört nämlich den vermutlich eigentlich erwünschten Link zu dummy (auch in anderen Modulen)...

Code Auswählen

<a name="setList"></a>

Generell wünschenswert wäre, bei der Überarbeitung der commandref gleich auf die "id"-Verankerung umzustellen, dann passiert sowas nicht mehr ganz so einfach (das betrifft dann aber auch dummy).

rudolfkoenig · 01 Februar 2022, 11:44:59

Zitat[...] (das betrifft dann aber auch dummy).

Habe dummy von <a name=""> auf <a id=""> umgebaut.

Beta-User · 01 Februar 2022, 11:49:57

Zitat von: rudolfkoenig am 01 Februar 2022, 11:44:59
Habe dummy von <a name=""> auf <a id=""> umgebaut.

Danke!
(Du warst etwas schnell, sonst hättest du einen patch bekommen

).

Ralf9 · 06 Februar 2022, 15:48:04

Zitat
Code Auswählen Erweitern
<a name="setList"></a>
Generell wünschenswert wäre, bei der Überarbeitung der commandref gleich auf die "id"-Verankerung umzustellen,

Ist das mit der "id"-Verankerung irgendwo beschrieben?

Ich habe beim 00_Signalduino Modul ein "set raw" und ein "get raw"
Bei der "get raw" Schaltfläche wird der gleiche Text wie bei "set raw" angezeigt

Code Auswählen

	<a name="SIGNALduinoset"></a>
	<b>SET</b>
	...
	<a name="raw"></a>
	<li>raw<br>
	Geben Sie einen SIGNALduino-Firmware-Befehl aus, 

	<a name="SIGNALduinoget"></a>
	<b>Get</b>
	...
	<a name="raw"></a>
	<li>raw<br>
	Abh&auml;ngig von der installierten Firmware! Somit k&ouml;nnen Sie einen SIGNALduino-Firmware-Befehl direkt ausf&uuml;hren

Gruß Ralf

rudolfkoenig · 06 Februar 2022, 16:32:49

ZitatIst das mit der "id"-Verankerung irgendwo beschrieben?

Bestimmt, kann aber auf Anhieb nicht sagen wo.
Ich empfehle die Doku von 98_dummy.pm anzuschauen.

Beta-User · 06 Februar 2022, 16:33:33

Zitat von: Ralf9 am 06 Februar 2022, 15:48:04
Ist das mit der "id"-Verankerung irgendwo beschrieben?

Ich habe beim 00_Signalduino Modul ein "set raw" und ein "get raw"
Bei der "get raw" Schaltfläche wird der gleiche Text wie bei "set raw" angezeigt
Code Auswählen Erweitern
<a name="SIGNALduinoset"></a> SET ... <a name="raw"></a> <li>raw Geben Sie einen SIGNALduino-Firmware-Befehl aus, <a name="SIGNALduinoget"></a> Get ... <a name="raw"></a> <li>raw Abhängig von der installierten Firmware! Somit können Sie einen SIGNALduino-Firmware-Befehl direkt ausführen

Gruß Ralf

https://forum.fhem.de/index.php/topic,118915.msg1133644.html#msg1133644 war der Ausgangspunkt. Gibt noch einen Thread dazu, in dem auch Spezialfälle behandelt werden, aber im svn-log sollten sich Beispiele finden lassen, z.b. jüngst HUEBridge.
Edit: gefunden - https://forum.fhem.de/index.php/topic,120779.0.html

Ralf9 · 06 Februar 2022, 22:00:05

Danke, die normalen Fälle bekomme ich damit hin.
Das mit dem "data-pattern=" passt noch nicht.
Z.B: Ich habe ein "set cc1101_patable_433" und "set cc1101_patable_868" und möchte dafür den selben Text verwenden

Code Auswählen

=begin html_DE

<a id="SIGNALduino"></a>
<h3>SIGNALduino</h3>

	<a id="SIGNALduino-set"></a>
	<b>SET</b>

		<a id="SIGNALduino-set-cc1101_patable_433" data-pattern="SIGNALduino-set-cc1101_patable_.*"></a>
		<li><code>cc1101_patable</code> , &Auml;nderung der PA-Tabelle (Leistungsverst&auml;rkung f&uuml;r HF-Senden)</li>

Beta-User · 07 Februar 2022, 09:04:58

Nach meinem Verständnis werden die "Pfade" für "data-pattern" nach dem Kontext ermittelt, siehe z.B. "evalSpecials" und "msgCommand" in https://svn.fhem.de/trac/changeset/25556/trunk/fhem/FHEM.

Versuch's mal so:

Code Auswählen

<a id="SIGNALduino-set-cc1101_patable" data-pattern="cc1101_patable_.*"></a>
(Das ganze wäre aber in dem verlinkten Thread m.E. besser aufgehoben).

Nachträge

@Rudi: bzgl. Monitoring gibt es einen Vorschlag: https://forum.fhem.de/index.php?action=post;quote=1205785;topic=125662.0;last_msg=1205785

@Wzut (falls du hier mitliest): für readingsWatcher siehe https://forum.fhem.de/index.php/topic,49408.msg1204138.html#msg1204138

Ralf9 · 07 Februar 2022, 22:26:05

ZitatVersuch's mal so:
Code Auswählen Erweitern
<a id="SIGNALduino-set-cc1101_patable" data-pattern="cc1101_patable_.*"></a>

Damit funktioniert's auch nicht.
Anscheinend ist bei mir dafür irgendeine Bedingung nicht erfüllt.

Da der Text recht kurz ist, habe ich es jetzt ohne das "data-pattern" gemacht und für beide set Befehle den selben Text geschrieben.

Gruß Ralf

Beta-User · 08 Februar 2022, 05:57:12

Zitat von: Ralf9 am 07 Februar 2022, 22:26:05
Damit funktioniert's auch nicht.
Anscheinend ist bei mir dafür irgendeine Bedingung nicht erfüllt.

Hmm, manchmal ist das komisch und vom Umfeld abhängig, prinzipiell sollte es aber so gehen.
Wenn du einen Link postest, schaue ich es mir bei Gelegenheit an.

rudolfkoenig · 08 Februar 2022, 14:01:26

ZitatDas mit dem "data-pattern=" passt noch nicht.
Z.B: Ich habe ein "set cc1101_patable_433" und "set cc1101_patable_868" und möchte dafür den selben Text verwenden

Mit

Code Auswählen

    <a id="SIGNALduino-set-cc1101_patable_433" data-pattern="cc1101_patable_.*"></a>

funktioniert bei mir auf der FHEMWEB Detailseite die dynamische Anzeige der Hilfe nach dem Auswahl eines Befehls.
Der oben abgebildete Hilfetext ist in der commandref-Version irrefuehrend, da die eigentlichen Befehle nicht genannt werden.

Ralf9 · 08 Februar 2022, 19:05:08

Ich hab nun rausgefunden warums bei mir nicht funktioniert hat, ich hatte dies als Beispiel verwendet:

Zitat von: Beta-User am 07 Juli 2021, 12:45:35
Zum einen gibt es in RandomTimer mit onCmd bzw. offCmd zwei Attribute, die fast dasselbe machen. Eigentlich wollte ich schlicht denselben Text verwenden, aber das klappt nicht, dass das auch bei onCmd erscheint:
Code Auswählen Erweitern
<li><a id="RandomTimer-attr-offCmd" data-pattern="RandomTimer-attr-o.*Cmd"></a> <code>onCmd, offCmd</code> Setting the on-/offCmd changes the command sent to the device. Default <code>onCmd</code> is <code>set <device> on</code>. The device can be specified by a @. Examples

ich hatte so wie im Beispiel in "data-pattern=" die komplette ID Bezeichnung geschrieben:

Code Auswählen

<a id="SIGNALduino-set-cc1101_patable_433" data-pattern="SIGNALduino-set-cc1101_patable_.*"></a>

wenn ich nun bei "data-pattern=" nur den letzten Teil der ID Bezeichnung reinschreibe, dann funktionierts:

Code Auswählen

<a id="SIGNALduino-set-cc1101_patable_433" data-pattern="cc1101_patable_.*"></a>

Im 00_cul Modul funktioniert auch folgendes:

Code Auswählen

<a id="CUL-set-sens" data-pattern="freq|bWidth|rAmpl|sens"></a>

Gruß Ralf