BiDiB
Protokoll
BiDiB, ein universelles Steuerprotokoll für Modellbahnen
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.4. Firmware-Updates
Ein Modul kann nach einen Firmwareupdate seine Unique-ID wechseln, es sind auch Module möglich, welche zu Beginn nur Firmware-Update beherrschen. In diesem Fall melden sie sich normal an, es sind jedoch alle Class-Bits auf Null gesetzt.
4.4.1. Ablauf eines Firmware-Updates
Für eine Fehlerbehebung oder das Nachrüsten neuer Funktionen ist es wünschenswert, dass Knoten die Fähigkeit zum Update ihrer Software haben. Ob und wie die Software eines Knotens aktualisiert werden kann, wird durch ein Feature festgelegt.
Im folgenden ist der Ablauf für FEATURE_FW_UPDATE_MODE = 1 exemplarisch dargestellt:
- Der Host sendet an den Node die Nachricht, dass ein Firmware-Update erfolgen soll. (MSG_FW_UPDATE_OP, Parameter BIDIB_MSG_FW_UPDATE_OP_ENTER) Diese Nachricht enthält zur Sicherheit die Unique-ID des Nodes. Ab diesem Zeitpunkt sind keinerlei sonstigen Befehle mehr erlaubt, der Node geht in einen eingeschränkten Mode, im dem nur Firmware-Update-Befehle ausgewertet werden.
- Der Node sendet eine 'Ready'-Nachricht, mit der er anzeigt, dass er bereit zum Empfang der Firmware ist.
- Der Host sendet eine Nachricht, welche den Typ bzw. Zielspeicher der folgenden Firmware angibt – z. B. Inhalt des Flash-Speichers.
- Der Node quittiert den Empfang und zeigt an, dass er die Datensätze erwartet.
- Der Host liest die Intel-Hex-Datei (wird vom Hersteller des Nodes bereitgestellt) ein und sendet diese Zeile für Zeile an den Node. Die Übertragung erfolgt direkt im ASCII-Format. Beim Erzeugen der Hex-Datei ist die max. Nachrichtenlänge zu beachten, die Hex-Records sind z. B. in Größe 16 Bytes je Zeile zu formatieren.
- Der Node quittiert den Empfang jeder Zeile und zeigt damit an, dass er bereit für weitere Datensätze ist. Erst nach der Quittung darf der Host die nächste Zeile senden.
- Als letztes sendet der Host eine Nachricht, dass die letzte Zeile übertragen wurde und eventuelle Fragmente noch in den Speicher geschrieben werden sollen.
- Der Node sendet eine 'Ready'-Nachricht und ist wieder bereit, ein weiteres Firmware-Paket entgegen zu nehmen.
Am Ende des Firmwareupdates sendet der Host ein Kommando zum Reboot bzw. Exit. Der Node quittiert diese Nachricht, wartet dann 1s (damit meldet ihn das Interface ab), startet dann neu und wird automatisch neu angemeldet. Es wird empfohlen, durch Maßnahmen innerhalb der Firmware (z. B. CRC-Prüfung beim Start), die vollständige und korrekte Übertragung der Firmware zu prüfen.
Da sich der Knoten nach dem FW-Update neu anmeldet, hat er keine Kenntnis über den Systemzustand (ob Spontanmeldungen erlaubt sind oder nicht) und sendet keine Spontanmeldungen. Fallweise muss man (wie auch bei jedem anderen neuen Knoten) eine entsprechende MSG_SYS_ENABLE an den neuen Knoten senden.
4.4.2. Features für FW-Update
Nummer | Name | Bedeutung |
---|---|---|
254 | FEATURE_FW_UPDATE_MODE | 0: kein FW-Update möglich 1: FW-Update im Intel-Hex-Verfahren möglich. Die maximale Zeilenlänge beträgt 16 Daten-Bytes (d.h. die Intelhex-Zeile beginnt mit ':10' oder kleiner). |
Zielspeicherbereiche:
Je nach Implementierung des Nodes können dort unterschiedliche Zielspeicherbereiche vorhanden sein: z. B. Flash, EEPROM, usw. Für jeden dieser Zielspeicherbereiche gibt es ein Updatefile vom Hersteller.
Für Updatefiles ist ein einheitliches Namensschema festgelegt:
Platzhalter | Verwendung |
---|---|
name_version | Name der Firmware, diese soll erkennbar Hersteller und Produkt kennzeichnen sowie eine Versionsbezeichnung haben. Alle Datei für verschiedene Zielbereiche müssen den gleichen String für name_version verwenden. |
ddd | Zielspeicherbereich, 3-stellig, mit führenden 0 aufgefüllt. |
hex | Dateierweiterung, hier wird fest die Erweiterung .hex verwendet. |
xyz_occupancydetector_v1_23f.000.hex xyz_occupancydetector_v1_23f.001.hex
000 und 001 wäre hier dann die jeweilige Nummer des Ziel-Speicherbereichs. Es wird empfohlen, den Bereich 000 für den Hauptprogrammspeicher zu verwenden und 001 für den Konfigurationsspeicher (EEPROM).
4.4.3. Downlink: Nachrichten für FW-Update
Auch gilt ein strenges Quittungsverfahren: jede Nachricht des Hosts muss von Node quittiert werden, erneute Nachrichten dürfen nur gesendet werden, wenn die Quittung der vorherigen Nachricht vorliegt. (Grund hierfür sind fallweise Speicherzeiten, in denen der Node den Programmspeicher beschreibt und daher nicht in der Lage ist, normalen Programmcode auszuführen.)
- MSG_FW_UPDATE_OP:
Es folgen ein weiteres Byte, welche die durchzuführende Operation angibt. Abhängig von diesem Byte können weitere Parameter folgen.
Der Node antwortet jeweils mit einer MSG_FW_UPDATE_STAT.
Kodierung des Firmwareupdate-Operationstyps Wert Name Bedeutung 0x00 BIDIB_MSG_FW_UPDATE_OP_ENTER Node soll in den Update-Modus wechseln.
Es folgen 7 Byte mit der Unique-ID des Nodes. Nur wenn die Unique-ID mit der des Nodes übereinstimmt, darf der Node in den Update-Mode wechseln.
Der Node antwortet mit einer MSG_FW_UPDATE_STAT(BIDIB_MSG_FW_UPDATE_STAT_READY), falls er im Bootloader ist, bzw. mit einer MSG_FW_UPDATE_STAT(BIDIB_MSG_FW_UPDATE_STAT_EXIT), falls er nicht in den Bootloader wechseln konnte.0x01 BIDIB_MSG_FW_UPDATE_OP_EXIT Node soll den Update-Modus verlassen. 0x02 BIDIB_MSG_FW_UPDATE_OP_SETDEST Auswahl Zielspeicher. Mit diesem Befehl wird der Zielbereich festgelegt, in welchem die folgenden Daten gespeichert werden sollen. Es folgt ein Byte mit der Nummer des Zielbereiches. Der Knoten antwortet mit einer MSG_FW_UPDATE_STAT(BIDIB_MSG_FW_UPDATE_STAT_DATA).
0: Flash (Applikation)
1: EEPROM0x03 BIDIB_MSG_FW_UPDATE_OP_DATA Daten: Für den aktuell gewählten Zielspeicher wird eine Dateneinheit gesendet. Die Daten werden als Zeile einer Intel-Hex-Datei übertragen. 'White'-Charakters (also 0x20, 0x09, 0x0D und 0x0a) werden dabei nicht mit übertragen. 0x04 BIDIB_MSG_FW_UPDATE_OP_DONE Für den aktuell gewählten Zielspeicher sind keine weiteren Daten mehr vorhanden, Node soll den Update des Zielspeichers durchführen. Der Node antwortet mit einer MSG_FW_UPDATE_STAT(BIDIB_MSG_FW_UPDATE_STAT_READY).
4.4.4. Uplink: Nachrichten für FW-Update
- MSG_FW_UPDATE_STAT:
Nach einem MSG_FW_UPDATE_OP Befehl wird immer eine Statusnachricht gesendet. Es folgen zwei Bytes:
MSG_FW_UPDATE_STAT Parameter Parameter Beschreibung STATUS Prozess-Status Kodierung des Firmwareupdate-Operationsstatus Wert Name Bedeutung 0x00 BIDIB_MSG_FW_UPDATE_STAT_READY Node ist im Update-Modus, betriebsbereit. 0x01 BIDIB_MSG_FW_UPDATE_STAT_EXIT Node verlässt den Update-Modus. Der Node bestätigt diese Nachricht und meldet sich von seiner übergeordnete Struktur ab (z. B. durch eine hinreichend lange Wartezeit am BiDiBus).
Anschließend führt er einen Reset durch und meldet sich neu an.0x02 BIDIB_MSG_FW_UPDATE_STAT_DATA Node erwartet (weitere) Daten. 0x255 BIDIB_MSG_FW_UPDATE_STAT_ERROR Node hat einen Fehler festgestellt und den aktuellen Vorgang abgebrochen. Er verbleibt im vorherigen Zustand. TIMEOUT
bzw. ERRORNach erfolgreicher Ausführung gibt das Byte die vom Host mindestens einzuhaltende Zeit an, bis das nächste Paket gesendet werden darf: Wert Bedeutung 0 Die nächste Nachricht an den Node darf sofort versendet werden. 1…255 Die nächste Nachricht an den Node soll erst nach einer Pause gesendet werden. Der Wert gibt deren Länge in Einheiten von 10ms an. Wert Name Bedeutung 1 BIDIB_FW_UPDATE_ERROR_NO_DEST Zielspeicherbereich nicht vorhanden. 2 BIDIB_FW_UPDATE_ERROR_RECORD Fehler im Record (z. B. ungültige Zeichen). 3 BIDIB_FW_UPDATE_ERROR_ADDR Record außerhalb des Speichers. 4 BIDIB_FW_UPDATE_ERROR_CHECKSUM Prüfsummenfehler im Hex-Record. 5 BIDIB_FW_UPDATE_ERROR_SIZE Record zu groß. 6 BIDIB_FW_UPDATE_ERROR_APPCRC CRC Fehler auf Applikation, Firmware nicht gestartet.