Expand on MQTT Plugin documentation.

[rhuss]

Extended plugin documentation for MQTT plugins and added missing fields. Most of the information is extracted from the source.

Adds also more context to the YAML examples as mentioned in #664

[rhuss]

How is the English translation created? Is it done manually or by some tooling? If done manually, I'm happy to translate the extra content.

Also, it might make sense to extract the pipeline-specific configuration that applies to other plugins (like the HTTP plugin) into a separate section so that it can be referenced from the MQTT and HTTP plugin documentation.

[rhuss]

Another question: For the writing case - what variables are available in which context? The current example is not helpful as it only mentions var, which is just a placeholder. Later in the docs, I also found enable in an example. What is the list, and what can be used in the templates as variables? It's a bit confusing.

[rhuss]

@naltatis @andig hier eine Ergaenzung der unvollstaendigen Dokumentation für das MQTT plugin. Vielleicht koennte man die pipeline parameter aber auch rausziehen, da sie ja auch für andere plugins gueltig sind. Wenn das gewuenscht ist, lasst es mich wissen.

[andig]

Ich werde damit nicht glücklich. Wir sollten:

• Pipeline vom Rest trennen
• Konkrete Beispiele für Charger etc nicht in MQTT mischen

[andig]

M.E. gehört das hier nicht hin

[rhuss]

Ich finde schon. Siehe meine Begruendung in meinem Kommentar unten. tl;dr - Es ist ein Beispiel, dazu gehoert auch eine Hilfestellung wo man die section verwenden kann, insbesondere wenn es auf jede Einrueckung ankommt. Je mehr Kontext, umso besser.

[andig]

Das gehört nicht in ein Beispiel sondern in eine grundsätzliche Erläuterung.

[rhuss]

Gerne, genauso wie beim HTTP plugin nehme ich an.

[andig]

Watt hat nix mit MQTT zu tun.

[rhuss]

In der urspr. Dokumentation steht

scale: 0.001 # floating point factor applied to result, e.g. for Wh to kWh conversion

Nach was muss ich den konvertieren ? Meinem Eindruck erwarte evcc für die UI, das alles Werte in W bzw. Wh erwartet wird. Der Kommentr is ja aber auch falsch, das es Wh in mWh umrechnen wuerde.

[andig]

source gibt für jedes Plugin, das muss in eine allgemeine Section zu Plugins

[rhuss]

Es ist klar, dass vieles was ich an dem MQTT plugin beschrieben habe, allegemein gueltig ist (ebenso wie auch das HTTP plugin plugin-generische Sachen beschreibt).

Das Ziel war zunaechst MQTT ausfuehrlich zu beschreiben, um nicht zu viel zu aendern oder umzustellen.

Ich kann aber auch gerne daran arbeiten, das Dokument umzustrukturieren und einen allgemeinen Abschnitt einzufuegen, der plugin-generische Sachen bechreibt.

Auch wuerde ich da erklaeren wie das Zusammenspiel von {{.var}} und ${var:%d} ist. Das wuerde ich sogar evtl. in einem ganz eigenen Dokument beschreiben, da es ja evtl. nicht nur für Plugins zutrifft (z.b. auch Funktionen wie timeRound oder die sprig Funktionen).

Das ist alles deutlich mehr Arbeit als der PR hier, daher wuerde ich das vorher gerne abklaeren, um nicht umsonst herumzubasteln.

Bei den Beispielen bin ich allerdings etwas anderer Meinung: IMO sollte immer auch genug Kontext mitgeliefert werden um auch zu verstehen wo diese besagte Konfiguration eingesetzt wird. Insbesondere bei einem fragilen Format wie YAML ist ein Beispiel wie:

source: http
uri: https://volkszaehler/api/data/<uuid>.json?from=now
method: GET # default HTTP method
headers:
  - content-type: application/json
auth: # basic authentication
  type: basic
  user: foo
  password: bar
insecure: false # set to true to trust self-signed certificates
jq: .data.tuples[0][1] # parse response json
scale: 0.001 # floating point factor applied to result, e.g. for kW to W conversion
timeout: 10s # timeout in golang duration format, see https://golang.org/pkg/time/#ParseDuration

schwierig zu verstehen. Wo kann ich das verwenden ? Top-level ? Auf welcher YAML Ebene ? Meiner Meinung nach sollte jedes YAML Beispiel von der obersten Ebene beginnen.

Generell gibt es zuwenig Beispiele die self-contained sind. (Achja, jq & scale sind uebrigens auch nicht http plugin spezifisch).

[naltatis]

schwierig zu verstehen. Wo kann ich das verwenden ? Top-level ? Auf welcher YAML Ebene ? Meiner Meinung nach sollte jedes YAML Beispiel von der obersten Ebene beginnen.

Ja, dem würde ich voll zustimmen. Dann hat der Nutzer ne Chance das einfach wiederzufinden, ohne sich den Kontext selbst erschließen oder ausprobieren zu müssen.

[andig]

Es würde genügen das einmal einführend zu erläutern. Genau so wie die Bedeutung von source. Lieber top-down als alle Details je Plugin wiederholt.

[rhuss]

Es ist halt die Frage ob jede ein Referenz Maual top-down liest oder man direkt zu einzelnen Punkten springt (so wie ich). Ich finde, etwas Redundanz schadet in diesem Fall wirklich nicht, man ueberfliegt die Beispiele ja auch, wenn man sich nicht damit direkt beschaeftigt. Ausserdem hat es auch einen Memorisierungseffekt (d.h. man lernt das YAML-Schema generelle besser und muss nicht immer hin und her springen). Für alte Hasen wie euch sicher vielleicht etwas nervig, aber für Newcomer ist das schon wertvoll.

[andig]

Ich sehe das anders. Unserer Doku fehlt an der Stelle noch eine bessere Struktur. Das heilt man idealerweise nicht durch Aufblasen einzelner Blöcke.

[naltatis]

@andig mach gerne einen Vorschlag für eine bessere Struktur. Ich seh das in der Tat so wie @rhuss. Leute (inklusive mir!) scrollen durch die Doku und suchen nach Code-Blöcken, die für ihren Einsatzzweck geeignet aussehen. Nur die wenigsten werden den gesamten Fließtext auf der Seite vollständig lesen und sich mental eine Struktur unseres Konfigurationsmodells machen. Vor allem nicht, wenn sie neu loslegen wollen.

Genau deswegen haben wir ja bei den Geräten auch den größeren Code-Block-Stil gewählt:

meters:
  - name: my_pv
    type: template
    template: apsystems-ez1
    usage: pv
    host: 192.0.2.2 # IP-Adresse oder Hostname

Ich finde es konsequent, das hier auch zu machen.

[andig]

Ohne das as-is angeschaut zu haben:

• Integration von "custom" Geräten
• Unterschiedliche "custom" Gerätetypen (meter, charger, vehicle)
• Plugins (Auswahl, Konfiguration)
• Beispiele

[rhuss]

Ok, wenn nichts dagegen spricht, wuerde ich einen Vorschlag auf Basis der bestehenden Dokumentation machen. Da Dokumentation mit GitHub PRs immer recht muehsam ist zu diskutieren/reviewen, hab ich mal ein Google Docs gestartet auf dem wir arbeiten koennen bevor wir es dann in Markdown giessen.

Das grobe Geruest fuer die Pugin Dokumentation habe ich https://docs.google.com/document/d/19ERhOWujB-5kMJ0UMOlMNu3qs6MUgn6oYjPXsUH5AM0/edit?usp=sharing schon mal hier angelegt und die bestehende Dokumentation zugeordnet.

Es sind immer noch bewusst Redundanzen in der Beschreibung der Parameter und auch der Beispiele enthalten um sie eigenstaendig ohne viel herumnavigieren gelesen und verstanden werden kann (d.h. die Dokumentation der einzelnen Plugins kann in Isolation gelesen werden). "self-contained" ist hier das Stichwort und ich bin immer noch dafuer dies für eine Nachschlage-Dokumentation aus der man auch beispiele herauskopiert so zu behalten. Dokumentation ist kein Code, d.h DRY ist sogar oft unerwuenscht wenn es den Lesefluss zu oft unterbricht und man staendig hin und her springe muesste (die Pflege der Links ist auch aufwendig)

Wenn das soweit ok ist, wuerde ich dann an diesem Dokument weiterarbeiten und euch um Reviews bitten. Falls das aber nicht gewuenscht ist, sagt es mir bitte aber auch, um nicht umsonst Energie reinzubuttern.

Ok ?

[andig]

Dokumentation ist kein Code, d.h DRY ist sogar oft unerwuenscht wenn es den Lesefluss zu oft unterbricht und man staendig hin und her springe muesste (die Pflege der Links ist auch aufwendig)

Ich will Dir da gar nicht widersprechen. Aber: DRY ist KEIN Ersatz für eine gute top-down Struktur die vom Groben ins Feine geht. Und diese hat m.E. Prio vor immer neuen Details die man dann später wieder mühsam deduplizieren muss.

Konsens?

[rhuss]

Ich will Dir da gar nicht widersprechen. Aber: DRY ist KEIN Ersatz für eine gute top-down Struktur die vom Groben ins Feine geht. Und diese hat m.E. Prio vor immer neuen Details die man dann später wieder mühsam deduplizieren muss.

Konsens?

Ja, denke das kriegen wir hin. Ich gebe dir auf jeden Fall, das die top-struktur sehr wichtig ist, die auch in der aktuellen Dokumentation vermisse.

Z.b. was mir immer noch nicht 100% klar ist, was in der zweite YAML Ebene alles wann verwendet werden kann (also z.b. 'enerby', 'power', ... unterhalb 'meter', 'charger', ...). Das koennte man in einer Tabelle auch auflisten und dann z.b. erwaehnen ob dazu das Plugin lesen oder schreibend benutzt wird.

Aber ich glaube, wir sollten ein eigenes issue aufmachen und nicht diesen armen PR totreiten :)

[andig]

Common ist da nur source und dann hängt es vom Plugin ab. Alle Vorhandenen siehst Du im Repo oder suchst in den Templates nach source:

[rhuss]

Closed in favor of #678