WRP - Wireless Railroad Protocol

WRP, Wireless Railroad Protocol

Version: 0.06

XBEE-Modulen

Handregler

Prinzipieller Aufbau

WRP Protokoll

[header]

8 Bit

Gibt die Größe der Nachricht in Bytes an, Bereich 0-127; Ein gesetztes MSB bedeutet, diese Nachricht ist bestätigt und kommt von der Zentrale. Ein gelöschtes MSB bedeutet eine Anforderung oder Anfrage an die Zentrale. Nachrichten an die Zentrale können (und sollen), müssen aber nicht bestätigt werden. State-Nachrichten an die Zentrale müssen bestätigt werden, erst dann gilt der neue State als bestätigt.
Die Länge ist in Bytes angegeben, der header selbst wird nicht mitgezählt. Ein header=0 markiert das Ende einer Befehlssequenz. Wenn das Ende der Befehlssequenz durch die Art der Übertragung sicher erkannt werden kann (z.B. bei ZigBEE/XBEE wird die Zahl der übertragenen Bytes mitgeliefert), dann kann die Endemarkierung entfallen. Der Nachrichtenempfänger muß in diesem Fall das Ende selber abprüfen.

[type]

4 Bit (0..3)

Gibt die Klasse der Nachricht an. Es sind folgende Klassen definiert:

1	state
2	loco
3	accessory
4	feedback
5	programming
14	clock
15	system

[opcode]

4 Bit (4..7)

Gibt innerhalb einer Nachrichtenklasse die anforderte oder auszuführende Operation an. z.B. speed setting|function setting|...

[addr]

16 Bit

Optional: Gibt innerhalb einer Nachrichtenklasse die Nummer des Objekts (z.B. Lok) an, die für diese Operation verwendet werden soll. [addr] = 0xFFFF bezeichnet i.d.R. einen Broadcast, d.h. die Nachricht gilt für alle Objekte in dieser Klasse. Dieser Wert wird 'little endian' übertragen, d.h. das niederwertige Byte kommt zuerst.

[data]

0 Byte ... 64 Byte, byteweise organisiert.

Enthält die notwendigen Daten und Parameter zum Befehl.

type: state

state

0x1

type: state
Wert	opcode	Bedeutung
0x0	OFF	Das System wird abgeschaltet.
0x1	STOP	Alle Loks werden mittels Nothalt angehalten, jedoch Weichen können nach wie vor geschaltet werden. Wenn Stop von der Zentrale nicht unterstützt wird, so wird OFF ausgeführt.
0x2	SOFT-STOP	Alle Loks werden mit Fahrstufe 0 (also mit ihrer eigenen Verzögerung) angehalten, Weichen können weiterhin geschaltet werden. Wenn Soft-Stop von der Zentrale nicht unterstützt wird, so wird STOP ausgeführt.
0x3	GO	Wiederaufnahme des Betriebes
0x8	PROG	Programmiermode
0xD	BUSY	Die Basestation bzw. der Funkkanal ist nicht mehr aufnahmefähig. Jeder Funkteilnehmer soll für mind. 100ms keine weiteren Nachrichten absenden.
0xE	DISCONNECT	Base Station is no longer connected to a command station.
0xF	QUERY	Abfrage des aktuellen Status. Wenn die Basestation dieses Kommando erhält, sendet sie den Status erneut ab.

(Anmerkung hierzu: der Broadcast der XBEE-Module hat relativ große Latenz und Bandbreitenoverhead, deshalb benutzt z.B. das Gateway hier die Einzeladressierung.)

type: loco

loco

0x2

type: loco

Wert

opcode

Bedeutung

0x0

ESTOP

Hält die Lok [addr] mittels Notstop (DCC Fahrbefehl mit Wert 1) an. Es können auch mehrere Loks (jeweils Adresse als 16-Bitwort) in einer Nachricht übermittelt werden. Diese weiteren Loks werden als Liste von 16-Bit Werten (little endian) im Datenfeld übertragen.
ESTOP ist nur zulässig auf Adressen, welche vorher diesem Handregler zugeteilt wurden. ESTOP löst keinen Eigentümerwechsel aus, der bisherige Eigentümer erhält auch keine Benachrichtung (obwohl der Nothalt durchgeführt wird).

0x1

CONTROL

Einstellen von Speed, Dir, Licht, Funktionen F1-F28 der Lok [addr]. Die Werte sind im Datenfeld kodiert. Wenn ein Handregler diese Nachricht an eine Zentrale senden, so heißt dass, er will die Lok auch übernehmen.

data[0]

Bitfeld

Bit	Bedeutung
0	Operated: 0: die Lok ist aktuell frei und kann übernommen werden. 1: die Lok ist an anderer Stelle in Benutzung; sie kann übernommen werden, wird dabei jedoch von einer anderen Kontrollinstanz geklaut.
3..1	reserviert
6..4	Format: 000: DCC14 (14 speed steps) 001: reserveriert 010: DCC28 011: DCC128 (126 speed steps) 1xx: reserveriert
7	Richtung, 0=vorwärts, 1=rückwärts

data[1]

Geschwindigkeit (1)

data[2]

FL, F4 - F1; 3 MSB sind reserviert. Die Bitorder ist: FL, F4, F3, F2, F1

data[3]

F8 - F5

data[4]

F20 - F13

data[5]

F28 - F21

0x2

DRIVE

Einstellen von Speed, Dir der Lok [addr]. Die Werte sind im Datenfeld kodiert. Wenn ein Handregler diese Nachricht an eine Zentrale senden, so heißt dass, er will die Lok auch übernehmen.

data[0]

Bitfeld

Bit	Bedeutung
0	Operated: 0: die Lok ist aktuell frei und kann übernommen werden. 1: die Lok ist in Benutzung; sie kann übernommen werden, wird dabei jedoch von einer anderen Kontrollinstanz geklaut.
3..1	reserviert
6..4	Format: 000: DCC14 (14 speed steps) 001: reserveriert 010: DCC28 011: DCC128 (126 speed steps) 1xx: reserveriert
7	Richtung, 0=vorwärts, 1=rückwärts

data[1]

Geschwindigkeit (1)

0x4

QUERY

Abfragen der Lokparameter. Die Zentrale antwortet mit mit einer CONTROL-Nachricht, die Lok wird dabei nicht übernommen.

0x5

STOLEN

Die Lok wurde an anderer Stelle übernommen. Diese Nachricht erhält der Client, welcher zuletzt die Lok kontrollierte. (2)

0x6

ERROR

Die Lok kann nicht gesteuert werden (Masternachricht). Normalerweise ist ein Fehler aufgetreten beim Versuch, die Lok zu steuern. (z.B. Lokbuffer voll)

0x8

RESERVE

Die Lok wird gegen Übernahme durch einen anderen Regler gesichert. Wenn diese Nachricht vom Master kommt, konnte die Lok nicht übernommen werden. (3)

0x9

FREE

Die Lokreservierung ist aufgehoben. (3)

0xF

LOCATE

Die Lok [addr] wurde vom railcom Detektor SID (Sensor ID) erkannt.

data[0]	Lowbyte der SID
data[1]	Highbyte der SID

(1) Die Geschwindigkeit wird immer als Ganzzahl von 0 bis * kodiert, z.B. bei DCC126 also von 0 bis 126. Fahrstufe 1 bedeutet langsame Fahrt (und nicht Nothalt wie bei der Gleisausgabe); Es liegt im Ermessen der Basisstation, diese Angabe je nach verwendetem Digitalsystem und/oder Decoder in die Fahrstufen des Zieles umzurechnen, i.d.R. werden aber die Fahrstufen 1:1 durchgereicht.
(2) Ein Client, welchem die Kontrolle über eine Lok entzogen wurde, darf erst nach einer Bedieneraktion zu dieser Lok wieder versuchen, die Lok wieder unter Kontrolle zu nehmen. Beispielsweise sind automatische Sequenzen (Massensimulation) abzubrechen. Der Client darf aber die aktuellen Parameter dieser Lok nachfragen (QUERY) um seine Anzeige aktuell zu halten, jedoch nicht öfter als 3 Anfragen/s.
(3) Die Mechanismen zum Schützen und Freigeben sind optional.

type: accessory

accessory

0x3

type: loco
Wert	opcode	Bedeutung
0x0	A_QUERY	Abfragen der Stellung. Durch eine Abfrage der Stellung wird die Weiche automatisch in die Watchliste aufgenommen. Die Zentrale antwortet mit mit einer A_POSIT-Nachricht.
0x1	A_SET	Der Zubehördekoder mit der Adresse [addr] wird mit Begriff in data[0] angesteuert. [addr] steht hier für die echte (DCC-)Adresse und wird bei 0 beginnend gezählt. Zweibegriffige Zubehördekoder werden mit (aspect 0 = red) und (aspect 1 = green) angesteuert. (Die Zentrale erzeugt den Einschaltbefehl auf dem zugehörigen (gepaartem) Spulenausgang.)
0x2	A_RESET	Der Zubehördekoder mit der Adresse [addr] wird mit Begriff in data[0] angesteuert. (Coil off, Abschaltbefehl; die Zentrale schickt den DCC-Abschaltbefehl an den Dekoder, anschließend wird eine eventuelle Stellungsrückmeldung eingelesen.)
0x3	A_POSIT	Anzeige der Stellung (Nachricht von der Zentrale). Dieser Befehl ist wie A_SET kodiert, er löst aber keine Aktion aus. (Nur Stellungsanzeige). Wenn beim Aspect das MSB (0xFF) gesetzt ist, ist die Weiche noch nicht umgelaufen bzw. die Stellung unbekannt.
0x4	WATCH	Mit diesem Kommando kann ein Client die in [addr] übergebene Weiche beobachten lassen. Er wird dann bei Zustandsänderungen dieser Weiche automatisch benachrichtigt. Eine Basisstation muß mind. 4 Beobachtungsplätze je Regler anbieten; sollte keine Beobachtungsplätze mehr frei sein, antwortet die Zentrale mit UNWATCH.
0x5	UNWATCH	Mit diesem Kommando wird die Beobachtung wieder aufgehoben. Wenn bei UNWATCH der Parameter [addr] == 0xFFFF ist, dann werden alle aktuell gesetzten Beobachtungen dieses Handreglers gelöscht.
0x8	XA_SET	Der Extended Zubehördekoder mit der Adresse [addr] wird mit Begriff in data[0] angesteuert.
0x9	XA_POSIT	Anzeige der Stellung (Nachricht von der Zentrale). Dieser Befehl ist wie XA_SET kodiert, er löst aber keine Aktion aus.
0xA	XA_QUERY	Abfragen der Stellung. Die Zentrale antwortet mit mit einer XA_POSIT-Nachricht

type: feedback

feedback

0x4

type: feedback
Wert	opcode	Bedeutung
0x0	FEVENT	Ein oder mehrere Sensorereignisse wird übermittelt. Jedes Sensorereignis ist als 16 bit kodiert, little endian. Sensorereignisse sind in ADDR und DATA[0/1] usw. kodiert. Je Meldung dürfen maximal 16 Sensorereignisse übertragen werden.
0x1	FQUERY	Abfrage von Rückmeldeereignissen. Die Databytes enthalten die Adressen der angefragten Ereignisse. Je Abfrage dürfen maximal 16 Sensorereignisse abgefragt werden.
0x2	BIDI	Meldung eines Railcomereignisses (noch genauer zu definieren)
0x3	QBIDI	Abfragen eines Railcomereignisses (noch genauer zu definieren)

Sensorereignis
Bit 15..12	Bit 11..0	Bedeutung
0b0000	ADDR	Das Rückmeldebit mit der Adresse ADDR ist nicht gesetzt.
0b1000	ADDR	Das Rückmeldebit mit der Adresse ADDR ist gesetzt.
......		reserviert.

type: programming

programming

0x5

type: programming

Wert

opcode

Bedeutung

0x0

PROG_STAT

Statusreport beim Programmieren

0	Programmieren fehlerfrei beendet [addr] enthält 0 oder die Lokadresse (wenn der letzte Vorgang ein Programmieren auf dem Hauptgleis war) data[0] und data[1] enthalten die CV Adresse data[2] enthält den gelesenen/geschriebenen Inhalt.
1	offen, keine Dekoderantwort [addr] enthält 0 oder die Lokadresse (wenn der letzte Vorgang ein Programmieren auf dem Hauptgleis war)
2	läuft noch
3	Kurzschluß

Der Statusreport bezeiht sich immer auf den letzen Programmiervorgang, dies gilt (bis auf weiteres) auch bei mehreren parallel ausgelösten Programmiervorgängen.

0x1

RDCV

Lesen einer CV (Read).

[addr]	enthält 0 oder die Lokadresse; 0: Lesen auf dem Programmiergleis >0: Lesen mittels Hauptgleisprogrammierung (PoM und BiDi)
data[0][1]	Adresse der CV, welche gelesen werden soll. Codierung 1..1024, little endian

Nach einem Read-Befehl muß das Ergebnis mit einem PQUERY abgeholt werden.

0x2

WRCV

Schreiben einer CV.

[addr]	enthält 0 oder die Lokadresse; 0: Schreiben auf dem Programmiergleis >0: Schreiben mittels Hauptgleisprogrammierung (PoM)
data[0][1]	Adresse der CV, welche geschrieben wird. Codierung 1..1024, little endian
data[2]	Der zu schreibende Inhalt

0x3

PQUERY

Abfrage Programmierergebnis
Die Zentrale antwortet mit einer PROG_STAT Nachricht.

Nach Absenden eines Programmiergleisbefehls kann (muß aber nicht) die Zentrale mit einem Status PROG MODE antworten. Ein Status PROG MODE zeigt an, dass jetzt eine Programmierung läuft und der normale Betrieb unterbrochen ist. Bei Programmieren auf dem Hauptgleis erfolgt kein Umschalten in den PROG MODE. Eine Multi-Mode-fähige Zentrale kann die Programmierung parallel zum normalen Betrieb durchführen, hier kann dann der normale Betrieb weiterlaufen.

type: clock

clock

0xe

type: clock

Wert

opcode

Bedeutung

0x0

CLKOFF

Die Uhr wird angehalten.

0x1

CLKON

Die Uhr (mit bereits bekannten Parametern) wird eingeschaltet. Sie läuft bei der bisherigen Zeit weiter.

0x2

CLKSET

Die Datenbyte data0 bis data3 enthalten die Uhrbefehl (analog zu DCC und Xpressnet)

data[0]	0x00 + set minute (0..59)
data[1]	0x80 + set hour (0..23)
data[2]	0x40 + set day of week (0..6))
data[3]	0xC0 + speed-up (clock multiplier 1..31)

Wenn diese Nachricht von der Zentrale gesendet wird, wird Broadcast verwendet. Alle 4 Bytes sind verpflichtend, wenn ein Feld unverändert bleiben soll (weil z.B. keine Eingabemöglichkeit dafür vorgesehen ist), dann wird der entsprechende Parameter außerhalb des gültigen Bereiches übertragen.

0x3

CLKQRY

Abfragen der Uhrzeit. Die Zentrale antwortet mit mit einer CLKSET-Nachricht.

type: system

system

0xf

type: system

Wert

opcode

Bedeutung

0x0

IDLE

Diese Nachricht hat keinen Inhalt, sie wird von der Zentrale zyklisch (mind. alle 2s) gesendet. IDLE wird nicht gesendet, wenn irgendein anderes Paket (z.B. clock oder state) bereits (innerhalb der Zykluszeit) an diesen Client gesendet wurde.
(Broadcast-)Pakete enthalten die PAN und MAC der Basisstation. Handregler können anhand dieser Parameter entscheiden, zu welcher Basisstation sie Kontakt aufnehmen.
Handregler müssen sich bei der Basisstation regelmäßig melden (z.B. auch mit einer IDLE-Nachricht), ansonsten bucht die Basisstation den Handregler aus (Zustand SILENT) und hält alle Loks an, die von diesem Handregler gefahren wurden. Im Zustand SILENT ist der Handregler aber noch an der Zentrale angemeldet und wird auch mit Nachrichten versorgt. Jedoch wird allen Nachrichten des Typs State oder Clock eine weitere Nachricht SILENT mit angehängt.

Die IDLE-Quittierung ist bei einem ungesicherten Funkkanal erforderlich. Ist die Verbindung zwischen Master und Client bereits durch ein Quittungsverfahren abgesichert (wie es z.B. bei ZigBEE der Fall ist), so sind die erhaltenen Empfangsquittungen des Clients ausreichend, um den Zustand ACTIVE dieses Clients zu halten. Wenn zukünftig Sleep-Modi aktiviert werden, übernimmt das IDLE auch die Funktion des Netzwerk-Beacon.

0x1

SILENT

Mit diesem Opcode teilt die Basisstation dem Handregler mit, dass er ausgebucht wurde und die von ihm kontrollierten Lokomotiven angehalten wurden. Bevor der Handregler neue Befehle absetzt, muß er sich erneut anmelden. Diese Nachricht wird anstelle von IDLE gesendet und auch an alle Clock oder Systemzustandsmeldungen angehängt.

0x2

APPLY

Mit diesem Opcode kann sich ein Client um Aufnahme an der Basisstation bewerben oder sich abmelden. Erst wenn der APPLY von der Zentrale bestätigt wurde, kann und darf der Client Befehle absetzen. APPLY muß die erste und auch einzige Nachricht innerhalb eines Paketes sein.

addr	=0	der Funkhandregler meldet sich ab. Die Zentrale bucht den Handregler aus und stoppt alle Lokomotiven, die von diesen Handregler gefahren wurden.
	=id	Der Funkhandregler meldet sich mit seiner Hardware-Enum (id) an. (MFT = 1)

0x3

GRANTED

Mit diesem Opcode bestätigt die Zentrale die An- oder Abmeldung. Erst wenn die Granted-Message eingegangen ist, dann darf der Handregler Befehle absenden.

0x4

CONNECT

Mit dem Opcode connect kann festgelegt, ob sich weitere Handregler an das Funknetz anschließen dürfen oder nicht.

addr	=0	es werden keine weiteren Funkhandregler aufgenommen.
	=1	das Funknetzwerk ist offen für neue Handregler (Voreinstellung nach dem Start)
	=2	alle aktuell bekannten Funkhandregler werden von der Basisstation permanent als zugelassen gespeichert.

Diese Funktion verhindert, dass sich unerwünscht Handregler in das System einwählen können. Dies könnte z.B. auf Ausstellungen störend sein.

0x6

SYSINFO

0	Anzeige der Vebindungsqualität. (Link Quality Show) Es wird der momentane RSSI-Wert übermittelt.
1	Power Level, Wertebereich 0..100.

0x7

SYSQUERY

0	Abfrage der Verbindungsqualität. (Link Quality) Zugleich mit der Abfrage wird auch der eigene RSSI übermittelt. Als Anwort wird eine SYSINFO gesendet. Diese Nachricht kann auch zum Sicherstellen der Verbindung dienen, sie wird dann zyklisch wiederholt und kann IDLE ersetzen.
1	Power Level Abfrage

0x8

PICTURE

Es wird ein Bild einer Lok übertragen; [addr] enthält die Bildkennung (Picture-ID). Ein Bild hat typischerweise nicht innerhalb einer Nachricht Platz, hier werden also Nachrichten kaskadiert. Details folgen, wie das Bild genau kodiert wird:(Bildtyp, colors,x,y,page,store)

0x9

LOCO_DB

lok database text transfer:

addr	16	Lokadresse, little endian
speedsteps	8	echte Fahrstufen der Lok (14, 28, 126)
Picture-ID	16	zugeordnetes Bild
Lokname length	8	Anzahl Zeichen Lokname (0..10)
Lokname	0..80	Lokname (ASCII)

0xC

FIRMWARE

Downloadpaket für Firmwareupdate. Details folgen (addr, size, (i/n), store)

0xE

CS_CV_QRY

CV der Zentrale abfragen. [addr] enthält die Adresse der abzufragenden CV. Die Zentrale antwortet mit einer CS_CV_SET Nachricht.
Hinweis: die Zugriffe auf Configvariablen der Zentrale dürfen nur von einem Handregler aus zur gleichen Zeit abgesetzt werden. Treffen während der Bearbeitung weitere Anfragen (z.B. von anderen Handreglern) ein, so werden diese ignoriert. Diese Zentralenreservierung wird automatisch bei Beantwortung oder zwangsweise nach einer Sekunde wieder aufgehoben.

0xF

CS_CV_SET

CV der Zentrale setzen. [addr] enthält die Adresse der zu setzenden CV, [data[0]] ist der Inhalt. Die Zentrale antwortet mit einer CS_CV_SET Nachricht.

turnout database transfer

Beispiele:

Verbindungsaufbau:

Copyright:

Links:

XBEE konfigurieren

OpenDCC