BiDiB, ein universelles Steuerprotokoll für Modellbahnen

BiDiB - Bidirektionaler Bus - Logo

Inhaltsverzeichnis

Allgemeines

Das Protokoll BiDiB dient zur Kontrolle einer Modellbahnanlage. Es ermöglicht die Ansteuerung von Loks, Zubehör und sichere Übertragung von Rückmelderinformationen aus der Modellbahnanlage an den steuernden Rechner.

BiDiB kann über verschiedene Übertragungsmedien transportiert werden, dabei wird das Framing und die Sicherung der Nachrichten gewährleistet.

Eine Erläuterung der hier verwendeten Begriffe und der Protokollgrundzüge findet sich im allgemeinen Teil der Protokollbeschreibung, gleiches gilt auch für die Hinweise zur Benutzung und zur Lizenz.

Dieser Abschnitt der Protokollbeschreibung erläutert nur einen Teil der Nachrichten.

Revisionsstand

Dieses Dokument beschreibt Revision 1.29 von BiDiB, Stand 21.07.2023.

Die Revisionsgeschichte ist dem allgemeinen Teil zu entnehmen.

4.1. System-Nachrichten

Die Systemnachrichten sind verpflichtend für alle BiDiB-Knoten mit der Ausnahme von 'Bootloader'-Knoten, siehe hierzu MSG_SYS_MAGIC für detaillierte Angaben.

4.1.1. Downlink: System-Nachrichten

Allgemeine Systemnachrichten

  • MSG_SYS_GET_MAGIC:

    Der adressierte BiDiB-Knoten soll die Systemkennung übermitteln. Es folgen keine weiteren Daten. Diese Nachricht soll als erste Nachricht vor jeden anderen Nachricht gesendet werden.

    Der Knoten antwortet mit der SYS_MAGIC, welche auch das prinzipielle Verhalten des Knotens beschreibt.

  • MSG_SYS_GET_P_VERSION:

    Abfrage der unterstützten Protokollversion von BiDiB. Es folgen keine weiteren Daten.

    Der entsprechende Knoten antwortet mit der von seiner Software unterstützten Version des Protokoll.

  • MSG_SYS_ENABLE:

    Es folgen 0 oder 2 Byte Daten. Der Knoten wird freigegeben, ab diesen Zeitpunkt sind spontane Meldungen (z. B. aufgrund von Änderungen von Belegungszuständen oder wegen neu gefundener Hardware) möglich. Die Nachricht gilt rekursiv für alle Unterknoten.

    MSG_SYS_ENABLE Parameter
    ParameterBeschreibung
    CLASS_ENABLEL Class-Bits der Klassen, für deren zugehörige Nachrichten die spontane Aussendung erlaubt wird. Spontane Systemnachrichten werden erlaubt, sobald irgendeines der Bits gesetzt ist.
    CLASS_ENABLEH

    Hubs reichen die Nachricht automatisch an alle Unterknoten weiter, es genügt daher im Host nur den Knoten 0 zu adressieren. Es erfolgt keine Quittung.

    Der optionale Parameter CLASS_ENABLE ist seit Protokollversion 0.9 verfügbar. Fehlt er, so wird 0xDF 0x00 als Wert angenommen, d.h. Bedienfunktionen sind ausgenommen.

    Hinweise:
    MSG_SYS_ENABLE steuert nur die Freigabe spontaner Nachrichten, man kann ohne SYS_ENABLE mit dem Knoten normal kommunizieren und dessen Funktionen benutzen.
    Wenn nach einen MSG_SYS_ENABLE ein weiterer Knoten hinzukommen, so hat dieser von der Vererbung nichts mitbekommen. Dieser Knoten muss nach dem NODETAB_CHANGE_ACK mit dem aktuellen Zustand von SYS_ENABLE versorgt werden.
    Bei der Initialisierung wird empfohlen, zuerst Knotentabelle und Features komplett einzulesen und als Abschluss der Initialisierung MSG_SYS_ENABLE zu senden.
  • MSG_SYS_DISABLE:

    Es folgen 0 oder 2 Byte Daten. Das BiDiB-System wird blockiert, ab diesen Zeitpunkt erfolgen keine spontanen Meldungen mehr. Ereignisse, welche im Zustand SYS_DISABLE passieren, werden nicht für später zwischengespeichert, Knotenzustände lassen sich aber gezielt abfragen. Die Nachricht gilt rekursiv für alle Unterknoten.

    MSG_SYS_DISABLE Parameter
    ParameterBeschreibung
    CLASS_DISABLEL Class-Bits der Klassen, für deren zugehörige Nachrichten die spontane Aussendung abgeschalten wird. Spontane Systemnachrichten bleiben solange erlaubt, sobald irgendeines der Bits gesetzt ist.
    CLASS_DISABLEH

    Hubs reichen die Nachricht automatisch an alle Unterknoten weiter, es genügt daher im Host nur den Knoten 0 zu adressieren. Es erfolgt keine Quittung.

    Der optionale Parameter CLASS_DISABLE ist seit Protokollversion 0.9 verfügbar. Fehlt er, so wird 0xFF 0xFF als Wert angenommen, d.h. sämtliche Spontannachrichten werden blockiert.

  • MSG_SYS_GET_UNIQUE_ID:

    Abfrage der Unique-ID und des Konfigurations-Fingerprints des Knotens. Es folgen keine weiteren Daten.

    Der entsprechende Knoten antwortet mit MSG_SYS_UNIQUE_ID.

    (Die Unique-ID eines Knotens ist auch in der Knotentabelle seines Interfaces hinterlegt).

  • MSG_SYS_GET_SW_VERSION:

    Abfrage der installierten Softwareversion(en) des Knotens. Es folgen keine weiteren Daten. Der Knoten antwortet mit einer MSG_SYS_SW_VERSION.

  • MSG_SYS_PING:

    Es folgt ein Byte.

    Der entsprechende Knoten im BiDiB-System wird veranlasst, eine quasi leere Nachricht (MSG_SYS_PONG) zurück zu senden. Diese Antwort muss binnen 250ms eintreffen, ansonsten hat der Host den entsprechenden Knoten als ausgefallen anzusehen. Das als Parameter übergebene Byte wird bei MSG_SYS_PONG zurückgesendet.

  • MSG_LOCAL_PING:

    Diese Nachricht wird nur auf lokaler Ebene verwendet, um die Ausfallprüfung (keep-alive) der Transportschicht (z. B. serielle Schnittstelle) zu unterstützen.

    Es folgen keine weiteren Daten.

    Der entsprechende Knoten im BiDiB-System wird veranlasst, eine Nachricht des Typs MSG_LOCAL_PONG zurück zu senden. Diese Antwort muss binnen 250ms eintreffen, ansonsten betrachtet das Interface den entsprechenden Knoten als ausgefallen und meldet diesen Ausfall mittels einer MSG_NODE_LOST an den Host.

    (Im Falle des BiDiBus übernimmt der Token und die Antwort auf den Token diese Ausfallüberprüfung.)

  • MSG_SYS_IDENTIFY:

    Es folgt ein weiteres Byte. 0: Identify wird abgeschaltet, 1: Identify wird eingeschaltet.

    Der entsprechende Knoten im BiDiB-System wird veranlasst, lokal eine Anzeige für Identify anzuzeigen (z. B. eine blinkende LED). Der Knoten antwortet mit einer MSG_SYS_IDENTIFY_STATE Nachricht.

  • MSG_SYS_GET_ERROR:

    Die letzte aufgetretene (und nicht bereits per Spontanmeldung abgesendete) Fehlermeldung wird ausgelesen. Der Fehlerspeicher wird durch das Lesen gelöscht. Sollte kein Fehler vorliegen, so wird eine leere Fehlermeldung (also Fehlernummer 0) zurückgeliefert.

  • MSG_LOCAL_SYNC:

    Diese Nachricht wird nur auf lokaler Ebene verwendet, um die Systemzeit in der Transportschicht zu synchronisieren.

    Es folgen zwei Bytes (TIMEL, TIMEH) mit der BiDiB-Systemzeit, TIME gibt dabei den Zeitpunkt des letzten Framemarkers vor der Nachricht an. Der Knoten stellt seine lokale Uhr auf den empfangenen Zeitstempel, eventuelle Datenlaufzeiten sind dabei durch entsprechende Offsets zu kompensieren. Die Nachricht wird nicht beantwortet.

    Beispiel: Ein Knoten empfängt MSG_LOCAL_SYNC 3. Die Zeit vom Framesignal bis zur Bearbeitung der Nachricht beträgt 2 ms. Die interne Uhr wird also auf 5 gestellt.

Systemnachrichten für die Busverwaltung

(Hinweis zur Implementierung: diese Nachrichten sind mandatory, aber diese Nachrichten beinhalten nur bei Interface-Knoten variable Daten, einfache Endknoten haben konstante Daten. D.h. die Antworten auf MSG_NODETAB_GET* usw. sind als Konstanten ablegbar und damit auch auf sehr kleinen Microcontrollern implementierbar). BiDiB verfügt über eine automatische Zuordnung der Knoten (z. B. Melder, Booster usw.). Diese Zuordnung ist im Interface hinterlegt und kann dort abgeholt werden. Hierfür sind folgende Nachrichten vorgesehen:

  • MSG_SYS_RESET:

    Das BiDiB-System wird hinsichtlich der Hostschnittstelle zurückgesetzt und die Zuordnung aller Knoten wird erneut durchgeführt. Die bisherige Zuordnungstabelle verliert ihre Gültigkeit.

    Wenn diese Nachricht an einen Knoten gerichtet wird, so soll sich dieser Knoten aus dem Bus ausloggen (durch eine Wartezeit von 1s) und anschließend erneut einloggen. Interne Zustände des Knotens können dabei verloren gehen.

    Achtung: Durch ein MSG_SYS_RESET gehen alle noch nicht ausgelieferten Nachrichten sowohl im Uplink als auch im Downlink verloren, auch geht das BiDiB-System in den Zustand SYS_DISABLE, es ist also nach einem Reset die Konsistenz der Daten zu prüfen und die Informationen vom BiDiB-System neu einzulesen.

    Achtung: Durch ein MSG_SYS_RESET wird eine Busstruktur zurückgesetzt, im Falles des BiDiBus (RS485) bedeutet das eine Pause von einer Sekunde auf dem Bus, damit alle Unterknoten in den Zustand Disconnected wechseln. Erst nach dieser Zeit wird der Bus neu aufgebaut und die Knotentabelle wird wieder gültig. In dieser Zeit wird MSG_NODETAB_GETALL mit 0 beantwortet.

    Achtung: Erst wenn der Knotentabelle wieder gültig geworden ist, dann können auch wieder Zugriffe auf Knoten und die Weiterleitungen von Nachrichten erfolgen, insbesondere auch von Broadcast-Nachrichten wie z. B. MSG_SYS_ENABLE oder MSG_SYS_CLOCK.

    Ein Knoten kann von sich aus einen Reset anfordern: Dies geschieht durch Senden einer Fehlermeldung mit dem Fehlercode BIDIB_ERR_RESET_REQUIRED.

  • MSG_NODETAB_GETALL:

    Mit diesem Befehl wird das Interface veranlasst, die aktuelle Zurordnungstabelle von Unique-ID und lokaler Adresse auszugeben. Diese Ausgabe erfolgt als Reihe von Nachrichten, es wird mit einer MSG_NODETAB_COUNT begonnen, gefolgt von MSG_NODETAB, welche jeweils durch eine MSG_NODETAB_GETNEXT ausgelöst wird.

    Während die Ausgabe läuft, führen weitere Anfragen mit MSG_NODETAB_GETALL zu einem Abbruch und Neustart der Übertragung.

    Sollte eine solche Tabelle noch nicht vorliegen, antwortet das Interface mit einer Nachricht MSG_NODETAB_COUNT = 0. In diesem Fall muss der Host nach ein paar ms erneut nachfragen.

    Liegt die Tabelle vor, antwortet das Interface mit MSG_NODETAB_COUNT = 'Tabellenlänge'.

    Hinweis:
    Diese Nachricht findet nur auf Knoten Verwendung, welche in ihrer Unique-ID einen Hub angemeldet haben. Knoten, welche keine Substruktur beinhalten, beantworten diese Anfrage trotzdem, in diesem Fall ist die Knotentabelle nur einen Eintrag lang, lokale Adresse ist 0.
  • MSG_NODETAB_GETNEXT:

    Mit diesem Befehl wird das Interface veranlasst, die nächste Zeile der Knotentabelle zu senden. Es folgen keine Parameter.

    Der Knoten antwortet mit einer MSG_NODETAB Nachricht. Liegt keine Zeile (mehr) vor, antwortet er mit MSG_NODE_NA 255. Hat sich die Knotentabelle seit der letzen Übertragung von MSG_NODETAB_COUNT verändert, antwortet er mit MSG_NODETAB_COUNT und beginnt bei den MSG_NODETAB-Nachrichten von vorn (mit der inkrementierten Versionsnummer).

  • MSG_GET_PKT_CAPACITY:

    Mit diesem Befehl kann man aus einem Knoten auslesen, welche maximale Nachrichtenlänge er verarbeiten kann. Dies entspricht der maximalen Länge einer Nachrichtensequenz, wenn diese nur aus der einen Nachricht besteht, und damit der maximalen Anzahl an Bytes in einem Paket (zwischen zwei Frame-Markierungen).

    Der Knoten antwortet mit einer MSG_PKT_CAPACITY Nachricht. Antwortet der Knoten nicht oder mit einem Wert unter 64, gilt die standardmäßige Beschränkung auf 64.

  • MSG_NODE_CHANGED_ACK:

    Es folgt ein Byte mit der Sequenznummer (Versionsnummer der Knotentabelle) der NODE_NEW- bzw. NODE_LOST-Nachricht, welche bestätigt wird. Diese Nachricht sendet der Host innerhalb von 250ms an ein Interface, wenn es von diesem eine Mitteilung über einen verlorenen oder neu hinzugekommenen Knoten erhalten hat. Wenn das Interface die gleiche Versionsnummer der Knotentabelle bestätigt bekommen hat, die es bei der letzten Änderungsmitteilung gesandt hat, so wird diese und alle vorangegangenen Änderungen als quittiert angesehen.

  • MSG_LOCAL_LOGON_ACK (vormals MSG_LOGON_ACK):

    Diese Nachricht wird nur auf lokaler Ebene verwendet, um die Adressvergabe der Transportschicht (z. B. BiDiBus) zu regeln.

    Es folgt ein Byte mit der lokalen Adresse (NODE_ADDR) und 7 Bytes mit der Unique-ID. Nur wenn der Knoten die empfangene Unique-ID identisch zu seiner internen Unique-ID geprüft hat, darf er seine lokale Adresse auf empfangene NODE_ADDR einstellen.

    Die Nachricht wird als Broadcast und mit der MSG_NUM = 0 gesendet. Sie wird immer interpretiert, selbst wenn (noch) kein Logonversuch unternommen wurde. Es ist damit auch möglich, einem Knoten eine lokale Adresse vor dem allgemeinen Logon zuzuteilen.

  • MSG_LOCAL_LOGON_REJECTED (vormals MSG_LOGON_RECJECTED):

    Diese Nachricht wird nur auf lokaler Ebene verwendet, um die Adressvergabe der Transportschicht (z. B. BiDiBus) zu regeln.

    Es folgen 7 Bytes mit der Unique-ID. Die Anmeldeversuche eines angesprochenen Knoten werden damit abgewiesen.

    Mögliche Ursache für das Abweisen des Logons können sein:

    • Die Interfacetabelle ist voll, die max. mögliche Zahl an Teilnehmern ist erreicht.
    • Es wurde eine doppelte Unique-ID auf dem Bus erkannt

    Zugleich mit der MSG_LOCAL_LOGON_REJECTED schickt das Interface eine Fehlermeldung mit BIDIB_ERR_BUS an den Host ab.

Systemnachrichten für die Anlagenverwaltung

(Hinweis zur Implementierung: diese Nachrichten sind mandatory)

  • MSG_SYS_CLOCK:

    Mit diesem Befehl wird eine Anlagen-Modelluhrzeit übertragen. Diese Anlagenuhr läuft typischerweise beschleunigt gegenüber der Echtzeit. Es folgen vier Bytes (TCODE0, TCODE1, TCODE2, TCODE3) mit der Angabe der Uhrzeit. Die Kodierung dieser Bytes stimmt mit der Kodierung des entsprechenden DCC-Befehls überein.

    Aufbau Modellzeit
    FeldKodierungBedeutung
    TCODE000mmmmmmmmmmmm = Angabe der Minute, Wertebereich 0…59.
    TCODE1100HHHHHHHHHH = Angabe der Stunde, Wertebereich 0…23.
    TCODE201000wwwwww = Wochentag, 0=Montag, 1=Dienstag, ... 6=Sonntag.
    TCODE311ffffffffffff = Uhrbeschleunigungsfaktor, ffffff=0 heißt Uhr angehalten.

    Die Daten bestehen jeweils aus einem 2 Bit Feld (Typ) und 6 Bit Wert. Der Host sendet das komplette Zeitpaket jede Modellbahn-Minute.

    Wenn die Anlage angehalten wird, soll der Uhrbeschleunigungsfaktor 0 gesendet werden.

    Auf Busimplementationen soll diese Nachricht bevorzugt als Broadcast gesendet werden.

4.1.2. Uplink: System-Nachrichten

Allgemeine Systemnachrichten

  • MSG_SYS_MAGIC:

    Übertragung der Systemkennung: Diese Variable dient zum Identifizieren und zur Kontrolle der Übertragung. Es folgen zwei Datenbytes, MAGICL, MAGICH, welche die Systemkennung darstellen. Die Systemkennung wird mit laufendem Nachrichtenindex 0 übertragen, damit kann die Nachrichtenfolge hostseitig einsynchronisiert werden.

    Kodierung der Systemkennung
    MAGICLMAGICHBedeutung
    0xFE0xAFBIDIB_SYS_MAGIC = Standard BiDiB-Knoten
    0x0D0xB0BIDIB_BOOT_MAGIC = Nur reduzierter Bootloader
    ……reserviert

    Wenn ein Knoten bei der Abfrage der SYS_MAGIC mit BIDIB_BOOT_MAGIC = 0xB00D antwortet, so handelt es sich um einen in seiner Funktionalität stark reduzierten Knoten, welcher nur den Bootloader aktiviert hat. Dieser Knoten beherrscht nur einen kleinen Teil der BiDiB-Nachrichten (siehe Tabelle), er kennt keine Featureabfragen, hat jedoch das Feature FEATURE_FW_UPDATE_MODE (254) = 1 gesetzt (obwohl es nicht abfragbar ist). Auch die Fehlererkennung und -behandlung in diesem Knoten ist reduziert, die Prüfung der Integrität der Datenübertragung (CRC) ist jedoch verpflichtend. Dieser Knoten hat keine ClassID-Bits gesetzt.

    Nachrichten eines Knotens mit BIDIB_BOOT_MAGIC
    DownstreamUpstream
    MSG_SYS_GET_MAGICMSG_SYS_MAGIC
    MSG_SYS_GET_P_VERSIONMSG_SYS_P_VERSION
    MSG_SYS_GET_SW_VERSIONMSG_SYS_SW_VERSION
    MSG_SYS_IDENTIFYMSG_SYS_IDENTIFY_STATE
    MSG_FW_UPDATE_OPMSG_FW_UPDATE_STAT
    MSG_SYS_RESET 
    MSG_LOCAL_LOGON_ACKMSG_LOCAL_LOGON
    MSG_SYS_GET_UNIQUE_IDMSG_SYS_UNIQUE_ID
    Hinweise:
    Ziel dieses reduzierten Befehlsumfanges ist die Möglichkeit, einen kleinen Bootloader zu realisieren, welcher in den Bootbereich-Speicher kleinerer Prozessoren passt (<4k).
    MSG_SYS_GET_UNIQUE_ID ist nur verpflichtend für Knoten, bei denen die Unique-ID nicht durch die Abfrage der Knotentabelle des übergeordneten Interfaces ermittelt werden kann. (Grund: das Hostprogramm braucht die Unique-ID, um eine zugehörige Firmware zu ermitteln).
    Sofern es die Speichergröße erlaubt, soll der Bootloader mit normaler BiDiB-Funktionalität realisiert werden.
  • MSG_SYS_PONG:

    Es folgt ein Byte. Diese Nachricht erfolgt als Antwort auf eine MSG_SYS_PING Anfrage, dabei wird das bei PING übergebene Byte wieder zurückgesendet.

  • MSG_LOCAL_PONG:

    Diese Nachricht wird nur auf lokaler Ebene verwendet, um die Ausfallprüfung der Transportschicht (z. B. serielle Schnittstelle) zu unterstützen.

    Leere Nachricht, es folgen keine weiteren Daten. Diese Nachricht ist die Antwort zu MSG_LOCAL_PING.

  • MSG_SYS_P_VERSION:

    Übertragung der unterstützten Protokollversion. Es folgen zwei Datenbytes, welche die Protokollversion von BiDiB kodieren.

    MSG_SYS_P_VERSION Parameter
    ParameterBeschreibung
    P_VERSIONL Nebenversionsnummer
    P_VERSIONH Hauptversionsnummer
  • MSG_SYS_UNIQUE_ID:

    Der Knoten sendet seine eindeutige Kennung. Es folgen 7 Bytes mit der Unique-ID und optional 4 Bytes mit einem Konfigurations-Fingerprint.

    Der Fingerprint ist eine 32-bittige Prüfsumme über sämtliche Einstellungen des Knotens. Dazu gehören:

    • Features (MSG_FEATURE)
    • Userkonfiguration (MSG_VENDOR und MSG_STRING)
    • Accessorykonfiguration (MSG_ACCESSORY_PARA)
    • Portkonfiguration (MSG_LC_CONFIGX)
    • Makrokonfiguration (MSG_LC_MACRO und MSG_LC_MACRO_PARA)

    Explizit ausgenommen sind sämtliche Bus- und Betriebszustände (auch solche die über Neustarts hinweg persistiert werden), unterstützte Protokollversionen und Firmwarestände (solange sich nichts anderes ändert).

    Der Fingerprint wird vom Knoten mittels einer guten (gleichverteilten, chaotischen, effizienten) aber nicht notwendigerweise kryptographischen Hashfunktion errechnet. Ändert sich ein Konfigurationswert, ändert sich auch der Fingerprint.

    Hinweise:
    Fingerprinting ist optional für Knoten. Wird es nicht unterstützt, wird nur die Unique-ID übertragen.
    Die Hashfunktion muss bei jeder Anfrage den aktuellen Wert liefern, es genügt nicht sie nur einmal beim Knotenstart zu berechnen. Zur Steigerung der Effizienz ist es auch möglich, einen inkrementellen Algorithmus zu wählen der jede Änderung einer Einstellung einzeln mit ins Ergebnis einbezieht.
    Der Fingerprint dient dem schnellen Laden von Knotenkonfigurationen beim Sitzungsstart. Ein Host kann sich die einmal abgefragten oder geschriebenen Konfigurationswerte für einen Knoten zusammen mit dem dazugehörigen Fingerprint lokal speichern. Trifft er das nächste Mal auf den Knoten, kann er sie anhand der Unique-ID und des Fingerprints im Speicher identifizieren und direkt laden ohne den Knoten abfragen zu müssen.
  • MSG_SYS_SW_VERSION:

    Übertragung der Softwareversion: Es folgen 1 bis 16 Tripel (je 3 Bytes), diese kodieren den Softwarestand des Knotens und evtl. assoziierter knoteninterner Subsysteme. Der Wertebereich ist herstellerspezifisch. In jedem Tripel wird der Subänderungsindex als erstes, der Hauptänderungsindex als letztes übertragen. Eine jeweils neuere Version hat einen numerisch größeren Änderungsindex.

    Das erste Tripel beschreibt die Softwareversion des Knotens selbst, weitere Tripel können für fest dem Knoten zugeordnete Untersysteme (Coprozessoren, Boardversionen u.ä.) verwendet werden.

    Anmerkung: bis zur Spezifikationsrevision 1.21 war nur ein Triple als Antwort erlaubt.

  • MSG_SYS_IDENTIFY_STATE:

    Es folgt ein Byte mit dem Zustand des Identify: 0: abgeschaltet, 1: eingeschaltet.

    Diese Nachricht wird gesendet, wenn entweder per Hostbefehl (MSG_SYS_IDENTIFY) oder lokal per Taster die Identifizierung des Knotens ausgelöst oder abgeschaltet wurde.

    Empfehlung: Sollte der Taster für Identify mehrfach belegt sein (z. B. wenn ein Dekoder auch per DCC Adresse-Lernen programmiert werden kann), so soll ein kurzer Tastendruck Identify auslösen, ein langer Tastendruck das DCC-Lernen. Mit dieser Empfehlung soll gleiches Verhalten über verschiedene Baugruppen hinweg realisiert werden.

  • MSG_SYS_ERROR:

    Fehlermeldung eines Knotens. Die Fehlermeldungen erfolgen entweder nach einer Abfrage (per MSG_SYS_GET_ERROR), spontan (sofern der Knoten enabled ist), oder anstatt der Antwort (bei Verwerfen der Nachricht). Es folgt ein Byte mit der Fehlerart sowie fallweise weitere Parameter. Je nach Fehlerart wird die Verarbeitung der Daten nicht mehr möglich sein.

    Kodierung der Fehlerart
    WertNameBedeutung
    0x00 BIDIB_ERR_NONE Der Knoten hat keinen Fehler (mehr) im Fehlerspeicher.
    0x01 BIDIB_ERR_TXT Der Knoten sendet eine Textfehlermeldung: es folgt ein Byte mit Angabe der Länge, gefolgt von ASCII-Zeichen der Fehlermeldung.
    0x02 BIDIB_ERR_CRC Die empfangene Nachricht (bzw. das Nachrichtenpaket) hatte einen CRC-Fehler, es folgt ein Byte mit der MSG_NUM der fehlerhaften Nachricht. Der Knoten verwirft das empfangene Nachrichtenpaket.
    Hinweis: diese Nachricht ist nur sinnvoll bei Punkt-zu-Punkt Verbindungen, bei physikalischen Strukturen mit gleichzeitigem Empfang mehrerer Teilnehmer erfolgt keine Fehlermeldung.
    0x03 BIDIB_ERR_SIZE Die empfangene Nachricht weist eine zu geringe Länge auf (zu wenig Parameter). Es folgt ein Byte mit der MSG_NUM. Der Knoten verwirft die empfangene Nachricht.
    0x04 BIDIB_ERR_SEQUENCE Die empfangene Nachrichtenfolge weist einen Sequenzfehler auf, es sind Nachrichten verloren gegangen. Es folgt ein Byte mit der MSG_NUM der aktuell erwarteten Nachricht (bei korrekter Sequenz) sowie optional ein Byte mit der MSG_NUM der aktuellen Nachricht, also der ersten wieder richtig empfangenen Nachricht. Der Knoten bearbeitet jedoch die empfangenen Nachrichten und übernimmt die aktuelle Sequenznummer als neuen Startpunkt.
    0x05 BIDIB_ERR_PARAMETER Die empfangene Nachrichten weist einen Parameterfehler auf. es folgt ein Byte mit der MSG_NUM der Nachricht, welche den Fehler enthielt. Die Nachricht wird nicht bearbeitet.
    0x10 BIDIB_ERR_BUS Die diesem Knoten zugeordnete Unterstruktur hat einen Busfehler. Es folgt ein Byte mit der Fehlernummer:
    0Kurzschluss
    1Bus unterbrochen, fehlende Abschlusswiderstände
    2zu viele Abschlusswiderstände
    3Anmeldefehler, Inkonsistenzen in der Knotentabelle.
    4Anmeldefehler, zu viele Knoten in dieser Ebene.
    5Busfehler, Overrun am Busmaster aufgetreten (normalerweise Folge eines Programmierfehlers).
    6Busfehler, Token am Busmaster aufgetreten.
    0x11 BIDIB_ERR_ADDRSTACK Eine Nachricht von einem Unterknoten enthält 3 lokale Adressen, d.h. der verfügbare Adressstack ist bereits erschöpft (weil da zu viele Ebenen hintereinander liegen) und die Nachricht kann nicht mehr geroutet werden.
    Es folgen 4 Bytes: NODE ADDR_STACK
    NODE: der Knoten, welche die zu lange Adresse eingereicht hat. ADDR_STACK: die restlichen Bytes dieser zu langen Adresse. Damit kann der Host die Ebene identifizieren, in welcher die Adressverletzung auftrat.
    0x12 BIDIB_ERR_IDDOUBLE Es versucht sich ein Knoten anzumelden, welcher bereits angemeldet ist oder der dieselbe ID hat wie ein bereits in der Knotentabelle enthaltener.
    Es folgen optional 7 Bytes mit der Unique-ID des Knotens.
    0x13 BIDIB_ERR_SUBCRC Eine Nachricht von einem Unterknoten konnte wegen eines CRC-Fehlers nicht empfangen werden.
    Es folgt 1 Byte: NODE
    NODE: Lokale Adresse des gerade adressierten Knotens.
    0x14 BIDIB_ERR_SUBTIME Eine Nachricht von einem Unterknoten konnte nicht komplett empfangen werden, timeout.
    Es folgt 1 Byte. NODE
    NODE: Lokale Adresse des gerade adressierten Knotens.
    0x15 BIDIB_ERR_SUBPAKET Ein Paket mit einer Nachricht von einem Unterknoten hatte eine Konsistenzfehler in der Size-Angabe.
    Es folgt 1 Byte mit der NODE-Adresse und optional weitere Bytes mit dem Inhalt des Pakets.
    NODE: Lokale Adresse des gerade adressierten Knotens.
    0x16 BIDIB_ERR_OVERRUN Ein Interface konnte die übermittelten Nachrichten nicht mehr auf seiner nachgeordneten Struktur weitersenden, es sind Nachrichten verlorengegangen.
    0x20 BIDIB_ERR_HW Der Knoten hat einen internen Fehler festgestellt. Es folgt ein Byte mit der Fehlernummer (Herstellerspezifisch)
    0x21 BIDIB_ERR_RESET_REQUIRED Der Knoten ist (z. B. durch Umkonfiguration von CVs) in einem Zustand, welcher einen Reset erfordert.
    0x30 BIDIB_ERR_NO_SECACK_BY_HOST Die Maximalzahl an Wiederholungen von Belegtmeldungsnachrichten wurde erreicht ohne dass der Host den Zustand quittiert hat.

Systemnachrichten für die Busverwaltung

(Anmerkung zur Implementierung: diese Nachrichten sind nur bei Interface-Knoten mit variablen Daten, einfache Endknoten haben konstante Daten, entsprechende Antworten können also statisch im Flashspeicher des Prozessors abgelegt werden).

  • MSG_NODETAB_COUNT:

    Diese Nachricht wird vor der Übertragung einzelner MSG_NODETAB gesendet, wenn der Host mit MSG_NODETAB_GETALL angefragt hat. Es folgt ein Byte mit der Länge der Knotentabelle. Diese Tabelle wird anschließend mit einer entsprechenden Anzahl an MSG_NODETAB_GETNEXT-Abfragen abgeholt.

  • MSG_NODETAB:

    Es folgen 9 Bytes mit einem Eintrag der Zuordnungstabelle:

    MSG_NODETAB Parameter
    ParameterBeschreibung
    NODETAB_VERSION Aktuelle Version der Tabelle, wird bei jeder Änderung inkrementiert, Überlauf: 255→1
    NODE_ADDR Zugewiesene lokale Adresse des Knotens (Wertebereich 0…127)
    Adresse 0 steht für den Knoten selbst.
    UNIQUE_ID[7] Die Unique-ID des Knotens, diese besteht aus 7 Bytes

    Wenn ein Knoten keine Unterknoten hat (also auch kein Class-Bit 'Hub' in der Unique-ID gesetzt hat), so ist die Knotentabelle nur einen Eintrag lang, und enthält den Knoten selbst.

    Die Übertragung der Knotentabelle erfolgt mit einer oder mehreren MSG_NODETAB-Nachrichten. Während die Übertragung läuft, sollen keine Knoten der Tabelle hinzugefügt oder entnommen werden. Erfolgt dennoch eine Änderung, beginnt das Interface wieder von vorn mit MSG_NODETAB_COUNT.

  • MSG_PKT_CAPACITY:

    Mit dieser Nachricht teilt ein Knoten dem Host mit, welche maximale Nachrichtenlänge er lokal verarbeiten kann. Dies ist in der Regel begrenzt durch die Größe des Empfangspuffers für Pakete der jeweiligen Transportschicht (welche ansonsten transparent für den Host ist). Die Länge entspricht bei paketbasierter Übertragung von Nachrichtensequenzen der maximalen Anzahl von Bytes für den Paketinhalt (als eine Sequenz mit nur einer Nachricht), z. B. 64 beim BiDiBus.

    Es folgt eine Längenangabe, bestehend aus einem Byte, Wertebereich 64…127. Der Minimalwert ist 64, kleinere Werte sind reserviert und zu ignorieren. (MSB ist reserviert für length-extension)

  • MSG_NODE_NA:

    Es folgt ein Byte mit der (lokalen) Nummer des angesprochenen Knotens. Die Meldung wird vom Interface zurückgesendet, wenn der Host versucht, einen Knoten anzusprechen, welcher nicht (oder nicht mehr) in der Liste ist.

    Diese Nachricht (mit Knoten 255) wird auch gesendet, wenn bei der Übertragung mittels MSG_NODETAB_GETNEXT bereits alle Knoten übertragen wurden.

  • MSG_NODE_LOST:

    Es folgt die aktuelle Versionsnummer der Knotentabelle, und der Tabelleneintrag des verlorenen Knotens (siehe MSG_NODETAB), bestehend aus lokaler Adresse (1 Byte) und Unique-ID (7-Bytes).

    Ein bereits angemeldeter Knoten antwortet nicht mehr.

    Wenn es sich bei dem verlorenen Knoten z. B. um einen Melder handelt, so kann (und soll) der Host geeignete Maßnahmen einleiten (partieller oder allgemeiner Nothalt, Verkehrslenkung). Die MSG_NODE_LOST des Interfaces muss vom Host bestätigt werden. Sollte sie innerhalb von 250ms nicht bestätigt werden, so wird sie von Interface max. 16 Mal wiederholt.

    Wenn es sich bei dem verlorenen Knoten um einen Hub handelt, so sind implizit auch alle Knoten hinter diesem Hub verloren.

  • MSG_NODE_NEW:

    Es wurde ein neuer, bisher nicht vorhandener Knoten erkannt und der Knoten-Liste hinzugefügt. Es folgt die aktuelle Versionsnummer der Knotentabelle, und der Tabelleneintrag dieses neuen Knotens (siehe MSG_NODETAB), bestehend aus lokaler Adresse (1 Byte) und Unique-ID (7-Bytes).

    Die Nachrichten für MSG_NODE_LOST und MSG_NODE_NEW werden erst nach dem erstmaligen Einlesen der Knotentabelle gesendet und nur dann, wenn das (Spontan-)Enable des Interfaces gesetzt ist. MSG_NODE_NEW muss ebenso wie MSG_NODE_LOST vom Host bestätigt werden (mittels MSG_NODE_CHANGED_ACK oder einer Komplettabfrage beginnend mit MSG_NODETAB_GETALL), ansonsten erfolgen bis zu 16 Wiederholungen.

    Wenn mehrere Änderungen hintereinander auftreten, so wird jedes Mal die Versionsnummer inkrementiert und eine Nachricht erzeugt, wiederholt wird aber nur die letzte Änderung.

  • MSG_STALL:

    Es folgt ein Byte, welches den Zustand kennzeichnet.

    0: Der Knoten arbeitet normal
    1: Ein Knoten sendet diese Nachricht, wenn er feststellt, dass sein Ausgangsdatenpuffer voll zu werden droht und deswegen die aktuelle Downstream-Nachricht nicht mehr bearbeitet werden kann. Ein solche Situation kann eintreten, wenn der Host den Knoten mit Anfragen 'zuschüttet'. Sie kann auch eintreten, wenn z. B. eine Zwischenebene des BiDiB-Baumes eine geringere Transportbandbreite hat: das entsprechende Interface schafft es nicht mehr, die vom Host übergebenen Daten auf seiner Unterstruktur weiterzugeben. Bei MSG_STALL eines Interfaces darf daher der Host auch keine Nachrichten mehr an Subknoten des Interfaces schicken.

    Ein MSG_STALL 1 wird vom Knoten mit einem MSG_STALL 0 wieder aufgehoben.

    Hinweis:
    Es ist in BiDiB gewünscht und zulässig, dass der Host Nachrichten an einen Knoten zusammenfasst und gemeinsam überträgt. Dabei darf es allerdings nicht zu einer Überlastung des Knotens kommen. Diese tritt z. B. bei einer BiDiBus-Struktur dann ein, wenn die in einem Paket übertragenen Nachrichten mehr als 48 Bytes in Summe an Antworten generieren.
    D.h. man kann ohne weiteres einen Block aus MSG_GET_SW_VERSION, MSG_GET_P_VERSION, MSG_FEATURE_GETALL, MSG_FEATURE_GETNEXT, MSG_FEATURE_GETNEXT, MSG_FEATURE_GETNEXT schicken, um die Daten des Knotens einzulesen.
  • MSG_LOCAL_LOGON (vormals MSG_LOGON):

    Diese Nachricht wird nur auf lokaler Ebene verwendet, um die Adressvergabe der Transportschicht (z. B. BiDiBus) zu regeln.

    Es folgen 7 Bytes mit der Unique-ID. Der Knoten versucht sich anzumelden. Diese Nachricht wird beim Systemstart verwendet, um die lokale Buszuteilung abzuklären.

4.2. Abfragen oder Setzen von Feature-Einstellungen

Vorbemerkung: Es gibt unterschiedliche Implementierung und auch Anforderungen an ein BiDiB-System, welche auch teilweise anlagenspezifisch sind. Zudem können auf einer Anlage Knoten mit unterschiedlichen Eigenschaften installiert sein.

Beispiele:
In einer mit Mittelleiter installieren Modellanlage ist die Richtungsauswertung ungültig; der Anwender wird diese Eigenschaft hier im Belegtmelder abwählen (müssen).
der Belegtmelder der Firma xyz kann Strommessung, die Software der Firma abc kann diese aber nicht auswerten. Also wird die Software der Fa. abc die Übertragung von Strommesswerten abwählen.

Aus diesem Grund gibt es im Protokoll die Möglichkeit, Eigenschaften des Knotens abzufragen und den Knoten zu konfigurieren, d.h. diese Eigenschaft freizugeben. Dies geschieht über die Feature-Einstellungen. Wenn ein Knoten eine bestimmte Eigenschaft nicht unterstützt, so kann die entsprechende Feature-Einstellung nicht umgestellt werden. Der Host kann dies durch Prüflesen der vorgenommenen Einstellung kontrollieren.

Vom Knoten selbst dürfen Features nur beim Power-Up verändert werden. Der PC liest Features einmalig ein und geht dann davon aus, dass die Hardware diese gemeldeten Eigenschaften hat.

Das Beantworten von Featurenachrichten ist für Knoten verpflichtend, Features selbst jedoch nicht. Die ID's für bestimmte Featureeinstellung sind verpflichtend. Nicht vergebene Feature-IDs sind reserviert. Erweiterungen der Features (neue ID's) sind zuvor beim Arbeitskreis BiDiB zu beantragen.

Ein vollständige Liste aller Feature-IDs ist in der Datei bidib_messages.h enthalten.

Aufstellung der allgemeinen Features
NummerNameBedeutung
112 FEATURE_CELL_NUMBER Logische Kennung des Knotens (besonders für Funk, Meshsysteme)
0: Nur ein globaler Kanal.
1…n: Nummer der Funkzelle.
113 FEATURE_RF_CHANNEL Verwendeter HF-Kanal
0…83: Kanalnummer im 2.4GHz Band
84…255: reserviert.
250 FEATURE_STRING_NAMESPACES_AVAILABLE Verfügbarkeit der String-Namensräume als Bitfeld:
  • Bit 0 - Namensraum 0. Gesetzt wenn FEATURE_STRING_SIZE > 0.
  • Bit 1 - Namensraum 1. Gesetzt wenn FEATURE_STRING_DEBUG vorhanden und schreibbar.
  • Bit 2 - Namensraum 2. Gesetzt wenn der Knoten über Accessory-Textausgabe verfügt.
  • Bit 3…7 - reserviert, mit 0 zu kodieren.
Fehlt das Feature FEATURE_STRING_NAMESPACES_AVAILABLE, ist die Verfügbarkeit der Namensräume 0 und 1 nur über FEATURE_STRING_SIZE bzw. FEATURE_STRING_DEBUG impliziert.
251 FEATURE_STRING_DEBUG Verwendung des String-Namensraums 1. Wertebereich: 0 (aus), 1 (Modus für 7 Text-Streams); Default 0.
252 FEATURE_STRING_SIZE Maximale Stringlänge für Stringvariablen im Namensraum 0. Wertebereich: 0; 8…24
(Fehlt das Feature FEATURE_STRING_SIZE bzw. hat es den Wert 0, so kann der Knoten keine Stringnachrichten verarbeiten.)
253 FEATURE_RELEVANT_PID_BITS Anzahl der relevanten Bits für die Produktkennung in der Unique-ID. Wertebereich: 0…31.
Default 16. (Fehlt das Feature FEATURE_RELEVANT_PID_BITS, so erfolgt die Aufteilung 16 Bit / 16 Bit.)
4.2.1. Downlink: Nachrichten für das Abfragen oder Setzen von Feature-Einstellungen
  • MSG_FEATURE_GETALL:

    Mit dieser Nachricht beginnt die Abfrage aller Featurewerte. Es folgt optional ein Byte, welches dem Knoten signalisiert, dass der Host das Streaming der Featurewerte wünscht. Der Knoten setzt intern den Zähler für die MSG_FEATURE_GETNEXT-Abfragen zurück und antwortet mit der Nachricht MSG_FEATURE_COUNT, welche die Anzahl der vorhandene Features angibt. Ist diese Anzahl 0, hat der Knoten keine Features.

    Hat der optionale Parameter den Wert 1, signalisiert dies dem Knoten dass er selbständig mit dem Senden der Feature-Nachrichten beginnen soll ohne auf MSG_FEATURE_GETNEXT-Abfragen zu warten. Der optionale Parameter mit dem Wert 0 signalisiert, dass der Host das Streaming der Featurewerte nicht wünscht. Die Werte 2..255 sind reserviert.
    Die Unterstützung dieser Funktionalität ist optional, wird aber für Knoten ab ausgewiesener Protokollversion 0.8 empfohlen.

  • MSG_FEATURE_GETNEXT:

    Mit dieser Nachricht wird ein Featurewert abgefragt. Es folgt kein Byte. Die Antwort besteht entweder aus einer MSG_FEATURE (wobei der Knoten selbst das jeweils nächste FEATURE auswählt und sendet) oder aus einer MSG_FEATURE_NA Nachricht (mit feature_num = 255), wenn bereits alle Features übermittelt wurden.

  • MSG_FEATURE_GET:

    ein einzelnes Feature abfragen. Es folgt ein Byte mit der Featurenummer, welche abgefragt wird.

    Der Knoten antwortet mit einer MSG_FEATURE.

  • MSG_FEATURE_SET:

    ein einzelnes Feature einstellen. Es folgen zwei Bytes: Featurenummer, Wert.

    Der Knoten antwortet mit einer MSG_FEATURE als Bestätigung. Sollte ein Wert übermittelt worden sein, welcher nicht einstellbar war, wird der tatsächlich eingestellte Wert zurückgesendet.

Die Kodierung der Feature-Sets für die jeweiligen Klassen ist den Dokumentationen der einzelnen Klassen zu entnehmen.

Wenn ein Knoten mit einer Feature-ID angesprochen wird, und dieses Feature am Knoten nicht bekannt ist, so wird eine MSG_FEATURE_NA (=feature not available) zurückgesendet.

4.2.2. Uplink: Nachrichten für Featuremitteilungen

Für die Antwort einer Featureabfrage werden folgende Nachrichtentypen verwendet:

  • MSG_FEATURE:

    es folgt eine Byte mit der Feature-Nummer und ein Byte mit dem Wert. Logische Features sind bei 1 aktiviert, bei 0 deaktiviert.

  • MSG_FEATURE_NA:

    Diese Nachricht wird gesendet, wenn ein Feature angefragt wurde, das auf diesem Knoten nicht verfügbar ist. Es folgt ein Byte mit der (nicht implementierten) Feature-Nummer.

    Ebenso wird diese Nachricht (mit Feature-Nummer 255) gesendet, wenn bei einer Reihenabfrage mit MSG_FEATURE_GETNEXT bereits alles übermittelt wurde.

  • MSG_FEATURE_COUNT:

    Diese Nachricht wird vor der Übertragung gesendet, wenn der Host mit MSG_FEATURE_GETALL angefragt hat. Es folgt ein Byte mit der Anzahl der vorhandenen Features und optional ein Byte zur Ankündigung des Übertragungsmodus.

    Das Modus-Byte wird mit dem Wert 1 übertragen, wenn der Host Streaming angefordert hat und es vom Knoten unterstützt wird. Der Knoten beginnt selbständig mit dem Senden der MSG_FEATURE, wobei er selbst für die Datenflusskontrolle verantwortlich ist und auch während einer laufenden Übertragung voll abfragbar bleibt. Mit der Anzahl kann der Host kontrollieren, ob alle Feature-Nachrichten eingetroffen sind.

    Andernfalls werden die Feature-Werte einzeln mit einer Reihe von MSG_FEATURE_GETNEXT abgeholt. Mit der Anzahl kann der Host eine entsprechende Anzahl von Anfragen stellen.

4.3. Nachrichten zur Userkonfiguration

Es gibt fallweise herstellerspezifische Parameter, welche über die normale Konfiguration hinausgehen. Für diese wird seitens des Protokoll nur die Übertragungstechnik definiert, Parameterbezeichnung, -inhalt und -bedeutung sind Sache des Herstellers.

Vendor-spezifische Datenübertragungen dürfen nicht für Steuer-, Rückmelde- und sonstige Befehle verwendet werden, für die es im normalen Protokoll ein Pendant gibt.

Bevor diese Parameter übertragen werden, muss der entsprechende Knoten mit seiner UNIQUE-ID aktiviert werden. Zwischen VENDOR_ENABLE und VENDOR_DISABLE sind keine anderen Nachrichten außer VENDOR_** zulässig. Erst nachdem der Knoten MSG_VENDOR_DISABLE bestätigt hat, sind Zugriffe auf diesen Knoten wieder erlaubt.

4.3.1. Downlink: Nachrichten zur Userkonfiguration
  • MSG_VENDOR_ENABLE:

    Es folgen 7 Bytes der zuvor ausgelesenen UNIQUE-ID. Der Knoten antwortet mit MSG_VENDOR_ACK.

  • MSG_VENDOR_DISABLE:

    Es folgen keine weiteren Daten; der Knoten ist wieder deaktiviert. Der Knoten antwortet mit MSG_VENDOR_ACK.

  • MSG_VENDOR_SET:

    Es folgen Daten, die wie folgt aufgebaut sind:

    VENDOR_DATA ::= V_NAME  V_VALUE
V_NAME ::= LENGTH  V_NAME_STR
V_NAME_STR ::= V_NAME_CHAR | V_NAME_CHAR  V_NAME_STR
V_VALUE ::= LENGTH  V_VALUE_STR
V_VALUE_STR ::= ε | V_VALUE_CHAR V_VALUE_STR

    Der Knoten speichert den Parameterwert in seiner Konfiguration, sofern ihm der Schlüssel (V_NAME) bekannt ist. Er antwortet mit einer MSG_VENDOR Nachricht, diese enthält denselben V_NAME und den gespeicherten Wert. Tritt bei der Verabeitung ein Fehler auf, kann der gespeicherte Wert von dem in MSG_VENDOR_SET übertragenen Wert abweichen, in der Regel wird dann der vorherige Wert beibehalten.

  • MSG_VENDOR_GET:

    Es folgen Daten, die wie folgt aufgebaut sind:

    V_NAME ::= LENGTH  V_NAME_STR
V_NAME_STR ::= V_NAME_CHAR | V_NAME_CHAR  V_NAME_STR

    Der Knoten antworten mit einer MSG_VENDOR Nachricht, diese enthält denselben V_NAME und den gespeicherten Wert dieses Parameters. Ist der Schlüssel (V_NAME) dem Knoten nicht bekannt, so antwortet der Knoten mit dem leeren Wert (V_VALUE = 0x00 "").

Die Knotenkonfiguration wird wie ein assoziatives Feld (Schlüssel-Wert-Paare) behandelt. V_NAME und V_VALUE sind ASCII-Folgen, damit kann eine Nutzereingabe direkt an den Knoten weitergereicht werden. Wenn die Folge aus Ziffern 0…9 besteht, so handelt es sich um einen numerischen Wert. Die Schlüssel (V_NAME) sollen in der Regel mit einem Buchstaben beginnen. Das Prinzip ist vergleichbar mit den Einträgen in einer Ini-Datei.

Es wird empfohlen, sprechende Namen für die Parameter und ihre Werte zu verwenden, sich dabei aber auf etwa 32 Bytes Gesamtlänge zu beschränken. Ein hartes Limit ist durch die Paketgröße gegeben, bei maximaler Nachrichtenlänge von 64 Bytes bleiben 55 Bytes für die beiden Strings V_NAME_STR und V_VALUE_STR.

Mit numerischen Werten für V_NAME und V_VALUE wird die klassische CV-Programmierung emuliert, der Adressbereich wird (wie in Dekoderbeschreibungen üblich) bei 1 beginnend gezählt. V_NAME = 0x01 "0" ist unzulässig.

Beispiele für MSG_VENDOR*:
MSG_VENDOR_GET 0x01 0x38 (=1 '8'): Es wird die CV 8 (bei üblichen Dekodern = Herstellerkennung) gelesen: 1 ist hier die Länge des Strings, welcher nur aus dem ASCII-Zeichen für 8 besteht.
MSG_VENDOR_SET 8 'S'C'H'W'E'L'L'E' 3 '2'5'5': Die Nachricht beginnt mit der Kennung MSG_VENDOR_SET, dann kommt die Längenangabe von 8, gefolgt vom Parameternamen 'SCHWELLE'. Es folgt wieder eine Längenangabe (3), dann der Parameterwert (hier 255).
DCC-Mapping:
Das so genannte DCC-Mapping nutzt ebenfalls Vendor-Nachrichten, die ausführlich im Support-Teil im Kapitel DCC-Mapping beschrieben werden.
  • MSG_STRING_SET:

    Senden eines Strings an den Knoten. Es folgen weitere Bytes, welche den angesprochenen Namensraum, den angesprochenen Identifier (zu setzende Variable, Kanal) und den String selbst angeben.

    Diese Funktion ist im Knoten nur verfügbar wenn vom entsprechenden Feature angekündigt.

    MSG_STRING_SET Parameter
    ParameterBeschreibung
    NAME_SPACE bezeichnet den Namensraum innerhalb des Knotens, Wertebereich 0…255
    • 0: String-Variablen im Knoten allgemein
    • 1: Debug-Streams
    • 2: Textausgabe für Accessories, über Aspect anwählbar wo BIDIB_ACCESSORY_PARA_USES_STRINGS = 1
    • 3…255: reserviert
    STRING_ID bezeichnet den angesprochenen String innerhalb des Namensraumes.
    Namensraum 0:
    • STRING_ID = 0: Produktname, readonly, vom Hersteller vorgegeben.
    • STRING_ID = 1: Knotenname, read/write, vom Anwender einstellbar (daher auch "Username").
    • STRING_ID = 2…255: reserviert
    Namensraum 1 (im Downstream, MSG_STRING_SET):
    • STRING_ID = 0: Standard Input eines Textterminal.
    • STRING_ID = 1…255: reserviert
    Namensraum 1 (im Upstream, MSG_STRING):
    • STRING_ID = 0: Standard Output, als Reaktion auf Stdin-Eingaben.
    • STRING ID = 1: Standard Error, als Reaktion auf Stdin-Eingaben. Unabhängig vom Terminal auftretende Fehler werden normal als Knotenfehler mit MSG_SYS_ERROR gemeldet.
    • STRING ID = 2: Logmeldungen mit Warning-Level
    • STRING ID = 3: Logmeldungen mit Info-Level
    • STRING ID = 4: Logmeldungen mit Debug-Level
    • STRING ID = 5: Logmeldungen mit Trace-Level
    • STRING_ID = 6…255: reserviert
    Namensraum 2:
    • STRING_ID = 0: Default-Anzeige (zum Beispiel leerer String)
    • STRING_ID = 1…N: weitere Texte, die als Accessory-Aspekt zur Anzeige auswählbar sind (siehe BIDIB_ACCESSORY_PARA_USES_STRINGS)
    • STRING_ID = 255: kommaseparierte Liste, beginnend mit Anzahl verfügbarer Einträge (max. 128) und maximaler Länge pro String jeweils als Dezimalstring kodiert; weitere Parameter können folgen. Der String ist typischerweise nicht schreibbar.
    SIZE bezeichnet die Stringlänge.
    • 0: String nicht existent.
    • 1…127: Anzahl der Zeichen.
    CHARS String, kodiert im Zeichensatz ISO 8859-1 (reiner 8-Bitcode). Das Byte 0x00 darf im String nicht vorkommen.

    Der Knoten antwortet (bei Namensraum 0 und 2) mit MSG_STRING und dem neu gespeicherten Wert. Ist der geschriebene String länger als zulässig, wird er vom Knoten gekürzt oder die Nachricht wird mit BIDIB_ERR_PARAMETER abgelehnt. Wenn die Antwort für einen String die Size 0 ergibt, so existiert der String nicht.

    Hinweise zum Namensraum 0:
    Das FEATURE_STRING_SIZE legt fest, wie lang die Zeichenfolgen im Knoten max. sein können. Aus Rücksicht auf die Darstellung in Hostprogrammen ist das auf eine max. Länge von 8 bis 24 Zeichen beschränkt. Existiert das FEATURE_STRING_SIZE nicht (oder hat den Wert 0), so kann der Knoten nicht mit Strings umgehen.
    Der Knoten antwortet jeweils mit MSG_STRING und dem neu gespeicherten Wert. Wenn die Antwort auf einen String die Size 0 ergibt, so existiert der String nicht.
    Vom Anwender veränderliche Strings (z. B. Knotenname) sind bei Auslieferung mit ' ' (= Leerzeichen) und einer Länge 1 vorzubelegen. Damit sind Hostprogramme in der Lage, leicht zwischen Auslieferungszustand und 'bereits benutzerkonfiguriert' zu unterscheiden.
    Der STRING 1 ist ein Kurzname für den Knoten, welcher der Anwender vergibt, z. B.: HBF-links-Signale.
    Hinweise zum Namensraum 1:
    Das FEATURE_STRING_DEBUG legt fest, wie der Namensraum 1 benutzt wird. Hat es den Wert 1, kann der Knoten ein einfaches Textterminal bereitstellen und MSG_STRING-Nachrichten für Debugausgaben auf verschiedenen Kanälen verwenden. Existiert das Feature nicht oder hat den Wert 0, sind Debugausgaben abgeschaltet.
    Jeder Kanal stellt einen Textstream aus UTF8-Bytes dar, die übertragenen Zeichen aus jeder Nachricht werden aneinandergehängt. Beispiel: Eine Folge von MSG_STRING 1 0 3 "abc", MSG_STRING 1 0 3 "def" wird also genauso interpretiert wie eine MSG_STRING 1 0 6 "abcdef".
    Als Trennzeichen wird der Zeilenumbruch \n verwendet. So lassen sich auch lange Ein- und Ausgaben transportieren, die Darstellung mehrerer Kanäle kann zeilenweise erfolgen. Ein Sequenzfehler in der Übertragung soll wie ein Zeilenumbruch behandelt werden.
    Der Sender soll dabei die maximal sinnvolle Nachrichtenlänge ausnutzen, um Overhead zu vermeiden. Auf MSG_STRING_SET oder MSG_STRING_GET wird keine Antwort erwartet, es kann aber Knoten geben die mit einem leeren String antworten. Die Ausgaben per MSG_STRING werden als Spontannachrichten behandelt. Für die Pufferung ist der Knoten verantwortlich, eine Flut von Lognachrichten soll andere Upstreamnachrichten nicht blockieren. Mit der eingeschränkt verfügbaren Bandbreite soll verantwortungsvoll umgegangen werden.
    Die Befehlsyntax auf dem Terminal ist frei wählbar, Eingaben dürfen vom Knoten beliebig ignoriert werden. Die Auswahl der Logausgaben kann hartkodiert werden (z.B. beim Debugging während des Entwicklungsprozesses) oder dynamisch über die Eingabe erfolgen.
    Für die Übertragung von Binärdaten dient das Update-Protokoll.
    Hinweise zu Namensraum 2:
    Das Bit 2 des FEATURE_STRING_NAMESPACES_AVAILABLE legt fest, ob der Namensraum 2 verfügbar ist und insbesondere dessen STRING_ID 255.
    Um mit MSG_STRING_SET dynamisch den Text je Accessory setzen zu können, sollte es mindestens so viele Texteinträge geben wie Accessories, damit man jedem Accessory einen festen Index zuordnen und den entsprechenden Begriff zuweisen kann.
    Die Speicherung erfolgt flüchtig im RAM, die beim Knotenstart verfügbaren Werte können jedoch konfigurierbar sein.
  • MSG_STRING_GET:

    Abfragen einer Stringvariable im Knoten. Es folgen weitere Bytes, welche den angesprochenen Namensraum und den angesprochenen Identifier angeben.

    Diese Funktion ist im Knoten nur verfügbar wenn vom entsprechenden Feature (FEATURE_STRING_SIZE, FEATURE_STRING_NAMESPACES_AVAILABLE) angekündigt.

    Der Knoten antwortet mit einer MSG_STRING die den abgefragten String enthält. Sofern ein String nicht existiert, wird SIZE = 0 zurückgegeben.

4.3.2. Uplink: Nachrichten für Userconfig

Für die Antwort einer Userconfig wird folgender Nachrichtentyp verwendet:

  • MSG_VENDOR:

    Es folgen Daten, die wie folgt aufgebaut sind:

    VENDOR_DATA ::= V_NAME  V_VALUE
V_NAME ::= LENGTH  V_NAME_STR
V_NAME_STR ::= V_NAME_CHAR | V_NAME_CHAR  V_NAME_STR
V_VALUE ::= LENGTH  V_VALUE_STR
V_VALUE_STR ::= ε | V_VALUE_CHAR  V_VALUE_STR
  • MSG_VENDOR_ACK:

    Es folgt ein Datum: 0: kein Userconfig-Mode, 1: Bestätigung, dass der Knoten im Userconfig-Mode ist.

  • MSG_STRING:

    Diese Nachricht ist die Antwort auf eine MSG_STRING_SET oder MSG_STRING_GET. Im Namensraum 1 kann die Nachricht auch spontan gesendet werden, wenn dies freigegeben ist.

    Es folgen weitere Bytes, welche den angesprochenen Namensraum, den angesprochenen Identifier, die Stringlänge und den String selbst angeben. Reihenfolge und Format der Parameter entsprechen MSG_STRING_SET, zur Bedeutung siehe dort.