[Doku] Themensammlung zu MQTT allgemein
-
@hydrotec sagte in [Doku] Themensammlung zu MQTT allgemein:
Ich hatte versucht, mich weitestgehenst an die Styleguide Dokumentation zu halten.
Und so wirklich glücklich bin ich mit der jetzigen Formatierung auch nicht.
Wie ich ja schon einmal erwähnt hatte, sind das meine ersten Gehversuche zu Markdown.
Wenn es dir nichts ausmacht, und du die Zeit dafür hast, könntest du mir bitte ein Beispiel zur Verfügung stellen,
wie du das umsetzen würdest. Also nicht die ganze Seite, nur ein zwei Blöcke, für mich zur Vorlage.
Gerne direkt in der von mir erstellten Doku.
Letztendlich soll es ja allen hilfreich sein, und ich kann mich zu Markdown weiterbilden.
Vorab schon ein Dankeschön.Mach ich, aber erst heute Abend.
A.
-
@asgothian sagte in [Doku] Themensammlung zu MQTT allgemein:
Mach ich, aber erst heute Abend.
Wie du Zeit hast, Danke
-
@hydrotec sagte in [Doku] Themensammlung zu MQTT allgemein:
Dann habe ich wohl den Hinweis in der Style Dokumentation missverstanden.
Anscheinend.
Der Zeilenumbruch sollte im RAW zu sehen sein, damit es dort nicht zu unendlichen Zeilenlängen kommt.
80 Zeichen ist auch nicht wirklich in Stein gemeißelt -
@homoran
OK, hab die Doku noch einmal etwas angepasst.
Jetzt sieht es auch für mich besser aus.@Asgothian
Für den Fall, das du das mit der Formatierung gemeint hast, dann hat es sich wohl erledigt.
Solltest du dennoch Verbesserungen vornehmen wollen, gerne doch.Bin für jeden Hinweis dankbar.
So, jetzt erst einmal Mittagspause
Angenehmen Nachmittag noch. -
@hydrotec sagte in [Doku] Themensammlung zu MQTT allgemein:
Für den Fall, das du das mit der Formatierung gemeint hast, dann hat es sich wohl erledigt.
Solltest du dennoch Verbesserungen vornehmen wollen, gerne doch.
Bin für jeden Hinweis dankbar.Es hat sich zum Teil erledigt. Die seltsamen Zeilenumbrüche sind weg, die fehlende Strukturierung fehlt immer noch und sprachlich gibt es immer noch einiges an Stolpersteinen, i.e. Formulierungen die man bei einem Gespräch so anwenden würde, die aber in einem Text fehl am Platz sind. Als Beispiel nur dieses:
"Diese Struktur wird meistens von den Herstellern vorgegeben, kann jedoch ebenso von Anwendern definiert werden. Kommt darauf an, um was für eine Art von Gerät es sich handelt."
Und auch wenn es kleinlich erscheint - es sind viel zu viele Kommata im Text
Ich geh da heute Abend mal drüber.
A.
-
@asgothian sagte in [Doku] Themensammlung zu MQTT allgemein:
Ich geh da heute Abend mal drüber.
Bitte bedenkt aber, dass diese "Vorgaben" formal zwar korrekt sind, in Bezug auf die geplante Leserschaft aber nicht zu stark in unverständliches Fachchinesisch gewandelt werden sollte.
-
@hydrotec sagte in [Doku] Themensammlung zu MQTT allgemein:
EDIT:
Wieviele Zeichen sind denn in der offiziellen Doku mmöglich, bevor ein automatischer Zeilenumbruch stattfindet.
Weiss das zufällig jemand?Da gibt es soweit ich weis keine Grenze. Bei den Änderungen die ich auf git gemacht hatte, habe ich mich auch immer versucht an den 80 Zeichen zu orientieren.
Allerdings sind die Zeilenumbrüche nur beim editieren in Github zu sehen, beim speichern verschwinden sie und in der Doku dann auch nicht mehr zu sehen. -
@fredf sagte in [Doku] Themensammlung zu MQTT allgemein:
Da gibt es soweit ich weis keine Grenze.
so kenne ich das auch. Das geht "unendlich". Dann wird der horizontale Scrollbalken schwer aktiv
-
@homoran sagte in [Doku] Themensammlung zu MQTT allgemein:
@asgothian sagte in [Doku] Themensammlung zu MQTT allgemein:
Ich geh da heute Abend mal drüber.
Bitte bedenkt aber, dass diese "Vorgaben" formal zwar korrekt sind, in Bezug auf die geplante Leserschaft aber nicht zu stark in unverständliches Fachchinesisch gewandelt werden sollte.
Ich werd es versuchen
-
@asgothian sagte in [Doku] Themensammlung zu MQTT allgemein:
Ich werd es versuchen
Danke!
Sonst hab ich wieder die Arbeit alles downwardkompatibel zu reverten
-
@homoran @hydrotec
Um es mir einfach zu machen hab ich einen Fork von @hydrotec's Doku repo angelegt und da mal Hand an den Text gelegt. Ich hoffe das- die Anpassungen nicht zu komplex geworden sind
- ich mich damit nicht zu weit aus dem Fenster gelehnt habe
Zum lesen: hier
A.
-
@hydrotec
Du hast in der Grafik die Richtungen bei Subscribe und Publish nicht konsistent. In Konfig B sind die Pfeile zwischen MQTT Client und Broker falsch rum.
Außerdem würde ich nicht sagen, dass ein Topic eine Verzeichnisstruktur ist, sondern eher (natürlich nur ein Vorschlag)Topics können zur Vereinfachung hierarchisch, ähnlich wie wie Verzeichnisstrukturen, aufgebaut sein. Die Hierarchien sind dabei nicht vorgegeben oder standardisiert. So kann es z.B. <Raum>/<Gerätetyp>/<Gerät>/<Attribut> (Wohnzimmer/Lichter/Deckenlicht/Verbindungsstatus) genau so genau so geben, wie <Gerätetyp>/<Raum>/<Gerät>/<...>
Tipp: Bei vielen Geräten kann man konfigurieren, wie sie ihre Informationen dem Broker mitteilen und wie die Topics strukturiert sein sollen. Eine einheitliche Struktur erleichtert die spätere Bearbeitung. -
Vielen lieben Dank, das du dir die zeit genommen hast. Nach erstem Überfliegen bin ich echt begeistert.
Werde mir das morgen noch einmal in Ruhe ansehen, heute Abend ist mir leider was dazwischen gekommen.@ostfrieseunterwegs sagte in [Doku] Themensammlung zu MQTT allgemein:
Du hast in der Grafik die Richtungen bei Subscribe und Publish nicht konsistent.
Da hast du vollkommen Recht. Hab die Pfeile einfach nur durchgeschleust.
Werde ich noch anpassen. Dankeschön für den Hinweis.
Deine Beschreibung zu den Topics werde ich mir morgen auch noch einmal zu Gemüte führen. -
@ostfrieseunterwegs sagte in [Doku] Themensammlung zu MQTT allgemein:
Außerdem würde ich nicht sagen, dass ein Topic eine Verzeichnisstruktur ist, sondern eher (natürlich nur ein Vorschlag)
ich hatte den Begriff "Datenpaket" vorgeschlagen
-
Guten Morgen,
hab den Bereich "Protokoll" der Doku nun noch einmal, unter Berücksichtigung eurer Vorschläge, überarbeitet.
Hoffentlich nicht verschlimmbessert.
Wenn ich noch einmal eure Zeit in Anspruch nehmen, und eure Meinung dazu erfahren dürfte,
wäre ich sehr dankbar.Gruß, Karsten
-
@hydrotec
Bei den Adaptern könntest Du vlt auf den prinzipiellen Unterschied hinweisen:
Es gibt spezielle Adapter, wie z.B. den Sonoff (Tasmota) Adapter. Er kommuniziert zwar über MQTT mit den Geräten, aber nur, wenn diese ihre Payload auch im Tasmota-Standard (keine Ahnung, ob das das der richtige Begriff ist) aufbauen. Der Vorteil ist, dass diese Adapter die Payload, die im JSON Format vorliegt, in Attribute zerlegen und automatisch entsprechende Datenpunkte in ioBroker anlegen. Der Nachteil ist, dass man bei den einbindbaren Geräten eingeschränkt ist.
Die beiden nativen MQTT Adapter (Client/Broker, Client) sind prinzipiell vollkommen offen, was die Struktur und Art der Payload angeht. Der Nachteil ist, dass der Anwender eventuell weitere Verarbeitungsschritte selbst einfügen muss um in ioBroker einzelne Datenpunkte für Attribute anzulegen. -
Danke für deine Anregung.
Bei dem Thema "Adapter" innerhalb der Doku bin ich noch nicht fertig.
Bin dran -
@ostfrieseunterwegs sagte in [Doku] Themensammlung zu MQTT allgemein:
Es gibt spezielle Adapter, wie z.B. den Sonoff (Tasmota) Adapter. Er kommuniziert zwar über MQTT mit den Geräten, aber nur, wenn diese ihre Payload auch im Tasmota-Standard (keine Ahnung, ob das das der richtige Begriff ist) aufbauen.
ich bin da der Meinung, man sollte nur auf diese Adapter hinweisen, dass sie intern mit MQTT arbeiten und deswegen auf doppelte Portbelegung geachtet werden muss
@hydrotec
Also im Prinzip Punkt 1 und 2 nach unten schieben und 3/4 als echte MQTT-Adapter beschreiben. Ich weiß, dein Screenshot sortiert es anders -
@homoran sagte in [Doku] Themensammlung zu MQTT allgemein:
ich bin da der Meinung, man sollte nur auf diese Adapter hinweisen, dass sie intern mit MQTT arbeiten und deswegen auf doppelte Portbelegung geachtet werden muss
Dieses sehe ich auch so. Das bestimmte Adapter intern mit einem Protokoll arbeiten welches auch von anderen genutzt ist sollte nicht dazu führen das man darauf im Detail eingeht. Das ist am Ende für die Nutzer nicht relevant.
-
@hydrotec sagte in [Doku] Themensammlung zu MQTT allgemein:
@mickym sagte in MQTT Broker/Client Adapter:
Wenn Du alle Adapter raussuchst, die MQTT sprechen, ist das ggf. gefährlich.
Das ist, zumindest bis jetzt, nicht der Plan.
Wenn ich alle Adapter in Betracht ziehe, welche auch nur in geringster Form mit dem MQTT-Protokoll zu tun haben,
würde es meiner Meinung nach, den Rahmen einer allgemeinen Dokumentation sprengen.
In der Doku werde ich unter den Adaptern nur diejenigen erwähnen,
welche über den Filter "MQTT" auf der Admin Oberfläche gefunden werden.Mein aktueller Plan sieht eine detailierte Beschreibung eines Adapters nicht vor.
Ich werde lediglich den Adapter "MQTT Broker/Client" dazu verwenden um die jeweilige Möglichkeit (Broker/Client),
wie sie in ioBroker machbar ist, aufzuzeigen.
Details gehören meiner Meinung nach in die Adapter-Beschreibung.@homoran sagte in [Doku] Themensammlung zu MQTT allgemein:
Also im Prinzip Punkt 1 und 2 nach unten schieben und 3/4 als echte MQTT-Adapter beschreiben.
Das ist nur eine Aufzählung der Adapter, welche unter dem Stichwort "MQTT" als Filter auf der Admin-Oberfläche gefunden werden. Ich glaube nicht das es einen Unterschied macht, an welcher Position welcher Adapter erwähnt wird.
Sie werden nicht ausführlich beschrieben, und an einer Hilfestellung/Entscheidungsmatrix bin ich noch am überlegen wie ich das allgemein umsetzen kann. Wenn jemand vorhat ein Tutorial zu bestimmten MQTT Adaptern zu erstellen, nur zu, nehm ich gerne als Hinweis in die allgemeine Dokumentation mit auf.
