[Diskussion für Wiki] Registerbezeichnungen A-Z (Namen, Erklärungen)

Pfriemler · 29 November 2017, 23:19:58

Auf vielfachen Wunsch und in Ausgliederung aus der Diskussion zu einer Oberflächenerweiterung für HM habe ich einen neuen WIKI-Artikel begonnen:
Homematic-Register von A-Z (Namen, Erklärung)

Die Seite ist dafür gedacht, alle bekannten Register von Homematic zu listen, den Namen zu erklären und grundlegende Beschreibungen zu liefern. Einsatz- und Code-Beispiele sind in den Geräte-Wiki-Einträgen, den "Homematic Type"-Artikeln oder "Codeschnipseln" besser aufgehoben und würden die Liste nur unnötig aufblähen.

Ergänzend zur dortigen Diskussionsseite, die (später) fachlichem Diskurs vorbehalten sei, möchte ich hier dazu aufrufen, den Artikel gelegentlich zu lesen, mir Verbesserungsvorschläge oder sonstige Anmerkungen zu machen - und auch mitzutun, wenn weitgehend Einigkeit über das Schema herrscht.
Insbesondere dankbar bin ich auch für Hinweise, wo das eine oder andere bereits erschöpfend erklärt ist. "Meinen" Homematic-Register programmieren-Artikel habe ich bereits beliehen und werde ihn dort mit Verweis auf diesen neuen Index ausdünnen.

Der Prozess ist gerade erst angefangen und beinhaltet einige Fleißarbeit. Die Erläuterungen sind eine erste Fassung. Wer meint, etwas nicht zu verstehen: bitte sagt es.

Eigentlich wollte ich jedem Register ein Unterkapitel spendieren. Aber das Inhaltsverzeichnis würde ausufern. Daher gefällt mir die Tabellenform so wesentlich besser. Weitere Spalten wie ausführliche Beschreibung oder Übersetzung, Wertebereich etc. habe ich zugunsten einer vermutlich sehr variablen Fließtextmenge dann doch in der zweiten Spalte integriert, dort jeweils in die erste Zeile.
Einwände?

Thorsten Pferdekaemper · 30 November 2017, 10:08:09

Hi,
hier ist ein Dump von alles Registern, die in FHEM bekannt sind (soweit ich das sehe). Es ist so zu lesen, dass die ungeraden $VAR-Angabe der Name des Registers ist und die geraden die jeweiligen dazugehörigen Eigenschaften. Die Eigenschaft 't' ist meistens ein kurzer erklärender Text.
Gruß,
Thorsten

EDIT: Das ganze wieder rausgeworfen, da es mit den code-Tags Schwierigkeiten gab.

Pfriemler · 30 November 2017, 10:20:53

Danke, das hilft mir beim Zusammensuchen. Den Kauderwelsch kann ich lesen.

Die kurzen Texte dürften die sein, die auch in "regList" ausgegeben werden und von Deiner Designstudie?

P.S.: Mit den Codetags stimmt was nicht.

marvin78 · 30 November 2017, 10:22:54

Aufteilen auf mehrere Code-Bereiche, dann klappt's auch mit Code Tags. So lange Codes können sie nicht handeln.

Thorsten Pferdekaemper · 30 November 2017, 10:32:56

Zitat von: Pfriemler am 30 November 2017, 10:20:53
Die kurzen Texte dürften die sein, die auch in "regList" ausgegeben werden und von Deiner Designstudie?

Ja und ja.

Zitat
P.S.: Mit den Codetags stimmt was nicht.

Seltsam, in der Vorschau sah das gut aus.

Ich hab's jetzt hier als Anhang drangehängt.
Gruß,
Thorsten

Pfriemler · 30 November 2017, 18:36:01

Zitat von: Thorsten Pferdekaemper am 30 November 2017, 10:32:56
Ich hab's jetzt hier als Anhang drangehängt.

Gesichert und lesbar.

Zur Sache: Wiederhole meine Frage insbesondere an die, die sich so eine Registerliste gewünscht haben: Ist das so angefangen ok? Soll ich so weitermachen?
Bei Thorstens Reaktion impliziere ich das JA jetzt mal ...

edit: Also bei insgesamt 442 bekannten Registern dürfte eine Tabelle die einzige Option darstellen. Das werde ich mir mal auch ein Programm zusammenbasteln, was die Register nach Listen vorsortiert und anschließend alphabetisch sortiert und die relevanten Daten inkl. Wertetabellen herauszieht. Und dann eine Datenbank mit den Erläuterungstexten dazu. So könnte man die Tabelle auch später reorganisieren ohne dass eine komplizierte händische Suche fällig wird.

Ich bin dann mal weg ...

So ganz kapier ich noch nicht alles. min, max, lit, litInv, c (lit wenn lit(Inv) existiert), l (Liste), u (unit) sind mir dann wohl klar, na und t natülich.
s?, f?, d?, a?
=> ein Blick in die HMConfig.pm ... da steht das meiste ja auch schon, inkl. Erläuterung. Und sortiert isses auch schon gut.
Das muss jetzt sacken...

FranzB94 · 01 Dezember 2017, 17:46:47

Hi Pfriemler!

Prima. Der Anfang ist gemacht.
Die Tabelle im Designvorschlag 2 sollte aber mMn noch in mehr Spalten eingeteilt werden:

register - Register | range - Wertebereich | peer - Peer | description - Beschreibung

Es ist richtig, dass die Geräte(-bezeichnungen), die Register, die Wertebereiche und die englische Kurzbeschreibung in der hm.pm enthalten ist. Ziel der derzeitigen Aktion sollte es sein, die deutsche Bedeutung der englischen Registerbezeichnungen für Einsteiger zu erklären. Weiterhin sollte der Zusammenhang bzw. die Abfolge der Register bei Befehlen erklärt werden, damit auch der Einsteiger Abläufe erstellen kann.
Die Idee, mit einer Datenbank zu arbeiten ist sehr gut.

Gruß Franz

Pfriemler · 01 Dezember 2017, 21:29:56

Den Wertebereich (bzw. bei Literalen die möglichen Werte) in eine extra Spalte auszulagern wird tatsächlich sinnvoll sein.

Aber was meinst du mit der peer-Spalte?

Wuppi68 · 01 Dezember 2017, 21:41:13

auch wenn es blöde klingt ....

die (Werte) Register sind vergleichbar einfach

Da finde ich die State Machine deutlich spannender und habe die bis heute nicht verstanden

Und ja, das Einsteiger PDF habe ich auch schon mehrfach daraufhin durchgeackert

martinp876 · 01 Dezember 2017, 22:25:24

Was habt ihr vor?
Sämtliche Register sind in hmconfig enthalten. Mit Adresse, Wertebereich und literal.
Register einzeln zu beschreiben ist sinnlos. Es sind Gruppen und als solche zu beschreiben.

Im Prinzip sind die im einsteigerdoc seit Urzeiten 90% beschrieben. Wenn die Beschreibung unverständlich ist, sollte sie eben überarbeitet werden.
Wenn das Prinzip einer Zustandsmaschine nicht klar ist sollte das einmal nachgelesen werden. Allerdings ist es für Experten. Un die verstehen statemachine.

Alle anderen sollten sich auf Templates stützen. Experten können diese einfach erstellen und verbreiten.

Pfriemler · 01 Dezember 2017, 23:09:11

lass mich mal machen und schaue dann. Sollte davon was ins Einsteigerdoc passen, gern. Die Statemachine werde ich nicht umfänglich neu erklären.

Ja, es steht in HMConfig. Aber nicht jeder kann das flüssig lesen. Die Vorgruppierung dort ist aber in der Tat sinnvoll. Allerdings wäre eine umfassende Erklärung der Registerzusammenhänge eher was für "Homematic type"-Artikel.

martinp876 · 02 Dezember 2017, 09:20:49

Ich dachte nicht, das jeder hmconfig verstehen soll. Es war ein Hinweis an dich, da du nach einer kompletten Liste der Register gefragt hast.
Des weiteren kannst du gerne die statemachine erklären oder das einsteigerdoc überarbeiten. Das kann man sicher verbessern. Unschön würde ich sehen, wenn es mehrfach erklärt wird. Wenn du alles umgänglich erklärst und das gesamte einsteigerdoc hm abbildest sollte man es zurückziehen. Es ist sonst immer problematisch für Anwender die nun gültige doc zu finden. Aus einem Hause sollte nur eine kommen.
Feel free das Doc zu überarbeiten, in Wiki zu integrieren oder zu löschen. Nur keine Konkurrenz erstellen.

Was mich wundert ist weiter der Ansatz, jedes Register separat zu erklären. Das verstehe ich nicht. Einige Register sollten von halbwegs aufgeweckten Usern allein durch die Kurzbeschreibung oder den Namen schon erklärt sein. Ein batlevel.... was könnte das bedeuten.... ein valvemaxpos könnte die maximale Position der Ventilöffnung sein. Ok, eine valveerrpos könnte hinterfragt werden. Die Position, wenn das Ventil in Fehler geht? Was könnten Fehler sein? Wissen wir nicht umgänglich. Sollte eigentlich einleuchtend sein, dass Batterie leer so etwas sein sollte. Und dass das entfernen einer Batterie das Ventil nicht in diese Position schiebt. Das geht zu schnell, kann nicht funktionieren.

Was erklärt werden sollte sind m.e eher Zusammenhänge, welch ein das einsteigerdoc nicht abdeckt. Ich denke die conditiontable kommt etwas zu kurz. Außerdem die virtuellen Kanäle eines Sommers sowie die Logic Verknüpfungen der selben. Weiter dessen kompletter Else Registerbranche.

Ich bin gespannt auf deine docu.
Ich sehe allerdings klar 2 Level:
Expert: der weiss sowieso was eine statemachine ist( ist in der Technik eine ganz normale Betrachtung, keine hm Erfindung) . Der kann mitdenken und braucht nur einige Hinweise.
Admin: dem sollte man komplette Anwendungen zu Verfügung stellen. Die macht man üblicherweise in Form von Templates. ( Muss auch nicht mein Ansatz von Templates sein- aber readytouse entities sollten es sein, keine Anleitungen setzen diese 5regs, peere hier und da....)

Das template kann man dann beschreiben.
M.e. setzen die wenigsten die Register für einen banalen treppenhausschalter mit bm sinnvoll. Mit dem template wäre das erledigt. Wer will schaut sich die Details an, wer nur anwenden will eben nicht.

Welchen Leserkreis willst du erreichen?

FranzB94 · 02 Dezember 2017, 10:15:01

Hi!

@Pfriemler: Du hast eigentlich Recht, diese peer-Spalte ist nicht unbedingt notwendig, da sie in der Regel mit required gefüllt oder leer ist. Wenn man ein "get <HM-Gerät> regList" aufruft, dann erscheinen die von mir angegebenen Spalten in dieser Reihenfolge.

@Martin:
Ich wiederhole meine Meinung aus: https://forum.fhem.de/index.php/topic,78425.45.html

ZitatIch habe großen Respekt vor der programmiertechnischen Umsetzung der HM-Geräte durch Martin. Leider treibt mich das lesen des durch ihn verfassten Anhanges an Ulli's Grundlagendokumentes in schiere Verzweiflung. Der Text ist in Alltags-Straßendeutsch geschrieben und in einer Form, wie man sie verwendet wenn man die Thematik erklärt bekommt und sich dabei Kurznotizen macht. Damit kann ein Einsteiger/Fortgeschrittener aber nichts anfangen, da er die Zusammenhänge nicht kennt und sie aus dem Text auch nicht erfährt.

Zitat von: martinp876 am 02 Dezember 2017, 09:20:49
Was erklärt werden sollte sind m.e eher Zusammenhänge, welch ein das einsteigerdoc nicht abdeckt. Ich denke die conditiontable kommt etwas zu kurz. Außerdem die virtuellen Kanäle eines Sommers sowie die Logic Verknüpfungen der selben.Weiter dessen kompletter Else Registerbranche.

Wer soll denn bitte solch ein Buchstabengewirr verstehen?
Die Hilferufe im HM-Bereich sind doch vielfältig, aber es gibt keine verständlichen Anleitungen.

Noch einmal: Martin, es will und wird Dir keiner Deinen guten Ruf und Deine Kompetenz in der HM-Programmierung absprechen. Du solltest also im Sinne der Sache Deine Unterstützung einbringen.

Gruß Franz

marvin78 · 02 Dezember 2017, 11:36:14

@Martin. In großen Teilen gebe ich dir recht ABER es gibt tatsächlich noch User, die zwischen den beiden Gruppen liegen und das sogar in mehreren Schattierungen. Es gibt nicht nur Experten und Admins. Es gibt tatsächlich auch die Leute, denen man einzelne Register etwas ausführlicher erklärt und die dann die Zusammenhänge besser verstehen. Manchmal ist es nur ein kleiner Schubs.

Pfriemler · 02 Dezember 2017, 17:16:05

Mir geht es nicht um eine Neufassung des Einsteigerdocs, diesbezüglich bin ich voll bei Martin. Hier geht es erst mal um nichts mehr als eine sinnvolle Zusammenfassung und Gruppierung der Register, Kurzbeschreibungen (die es bereits gibt) und einer Übersetzung (die es noch nicht gibt) nebst evtl. kurzer Erläuterungen.
Es wird sich als Nebeneffekt sicher einstellen, dass man bei eingehender Lektüre recht schnell den Sinn der Registerbezeichnungen selbst erahnen kann. Dann reicht im Zweifel ein Nachsehen im Wiki ob man richtig liegt.