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.27 von BiDiB, Stand 07.04.2017.

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 keine weiteren Daten. Der Knoten wird freigegeben, ab diesen Zeitpunkt sind spontane Meldungen (z. B. auf Grund von Änderungen von Belegungszuständen oder wegen neu gefundener Hardware) möglich. Die Nachricht wird von Knoten automatisch an alle Unterknoten weitergereicht (vererbt). Es erfolgt keine Quittung.

    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:

    Das BiDiB-System wird blockiert, ab diesen Zeitpunkt erfolgen keine spontanen Meldungen mehr. Ereignisse, welche im Zustand SYS_DISABLE passieren, werden nicht zwischengespeichert, Knotenzustände lassen sich aber gezielt abfragen. Die Nachricht wird von Knoten automatisch an alle Unterknoten weitergereicht (vererbt) und ist daher nur an den Knoten 0 zu adressieren. Es erfolgt keine Quittung.

  • 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 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 diesen Funktion.)

  • MSG_SYS_IDENTIFY:

    Es folgen 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 von 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 kann erfolgen auch wieder Zugriffe auf Knoten und die Weiterleitungen von Nachrichten, 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_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_LOGON_REJECTED:

    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_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.
    TCODE3110ffffffffff = Uhrbeschleunigungsfaktor, fffff=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_LOGON_ACKMSG_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.
    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 letzten Nachricht mit 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.
    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_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.

Aufstellung der allgemeinen Features
NummerNameBedeutung
252 FEATURE_STRING_SIZE Maximale Stringlänge für Stringvariablen. Wertebereich: 0; 8…24
(Fehlt das Feature FEATURE_STRING_SIZE, 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:

    alle Featureeinstellungen abfragen. Es folgt kein Byte. Die Antwort besteht aus einer Nachricht MSG_FEATURE_COUNT, welche die Anzahl der vorhandene Features angibt. Ist diese Anzahl 0, hat der Knoten keine Features. Der Knoten setzt intern den Zähler für die MSG_FEATURE_GETNEXT-Abfragen zurück.

  • 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 Feature-Nachrichten (welche mit einer Reihe MSG_FEATURE_GETNEXT abgeholt werden). Damit kann der Host kontrollieren, ob nach der Abfrage MSG_FEATURE_GETALL alle Feature-Nachrichten eingetroffen sind.

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 und -inhalt ist 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 antworten mit einer MSG_VENDOR Nachricht, diese enthält auch wieder V_NAME und V_VALUE.

  • 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.

V_NAME und V_VALUE sind ASCII-Folgen. Wenn die Folge mit einer Ziffer 0…9 beginnt, so handelt es sich um einen numerischen Wert. V_NAME sollen in der Regel mit einem Buchstaben beginnen. Mit numerischen Werten für V_NAME wird die klassische CV-Programmierung emuliert, der Adressbereich wird (wie in Dekoderbeschreibungen üblich) bei 1 beginnend gezählt. Damit kann direkt eine Usereingabe an den Knoten weitergereicht werden. V_NAME = "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). 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.

  • MSG_STRING_SET:

    Setzen einer Stringvariable im Knoten. Es folgen weitere Bytes, welche den angesprochenen Namensraum, den angesprochenen String und den String selbst angeben.

    Der Node antwortet jeweils mit einer MSG_STRING. Diese Funktion ist im Knoten nur verfügbar, wenn das FEATURE_STRING_SIZE existiert und einen Wert > 0 hat.

    MSG_STRING_SET Parameter
    ParameterBeschreibung
    NAME_SPACE bezeichnet den Namensraum innerhalb des Knotens, Wertebereich 0…255
    • 0: Knoten allgemein
    • 1…255: reserviert
    STRING_ID bezeichnet den angesprochenen String innerhalb des Namensraumes.
    Namensraum 0:
    • STRING_ID = 0: Produktname, readonly, von Hersteller vorgegeben.
    • STRING_ID = 1: Username, read/write, vom Anwender einstellbar.
    • STRING_ID = 2…n: reserviert
    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.
    Hinweise:
    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.
    Wenn die Antwort auf einen String die Size 0 ergibt, so existiert der String nicht.
    Vom Anwender veränderliche Strings (z. B. Username) 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 im Namespace 0 ist ein Kurzname für den Knoten, welcher der Anwender vergibt, z. B.: HBF-links-Signale
  • MSG_STRING_GET:

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

    Der Node antwortet jeweils mit einer MSG_STRING. Diese Funktion ist im Knoten nur verfügbar, wenn das FEATURE_STRING_SIZE existiert und einen Wert > 0 hat.

    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.

    Es folgen weitere Bytes, welche den angesprochenen Namensraum, den angesprochenen String und den String selbst angeben. Siehe hierzu MSG_STRING_SET.