Protocol documentation.

diff --git a/protocol.txt b/protocol.txt
new file mode 100644 (file)
index 0000000..416dea3
--- /dev/null
+++ b/protocol.txt
@@ -0,0 +1,249 @@
+Derived from
+http://translate.google.com/translate?js=n&prev=_t&hl=cs&ie=UTF-8&layout=2&eotf=1&sl=de&tl=en&u=http%3A%2F%2Fslotbaer.de%2Findex.php%2Fscx-digital%2F63-scx-digital-daten-protokoll&act=url
+
+Original source
+http://slotbaer.de/index.php/scx-digital/63-scx-digital-daten-protokoll
+
+Outline
+=======
+The control unit broadcasts data packets across the track.
+The packets are 9 bytes long, and the structure is the following:
+
+0x55 packet_type data_byte1..6 crc
+
+The Ole Seeberg's interface adds 0x05 (05 = O.S. :-) after each packet.
+This byte can be safely ignored.
+
+There can be noise on the track, so sometimes the packets are received
+by a reader with an incorrect checksum. Those should be discarded.
+
+The bus reader apparently does not report packets which are sent by
+the cars.
+
+Packet types
+============
+
+0xAA - bus free time
+--------------------
+Format: 0x55 0xAA N1 N2 0xF0 0xF0 0xF0 0xF0 CRC
+
+Sent twice after the car crosses the finish line. This is a message
+to the car instructing it to send its ID after the given delay.
+The delay is the ratio of the N1 and N2 numbers. No need to handle
+this, it is for cars, not race management.
+
+N1, N2 - fraction specifiying the bus free time. My Pit box with 020 firmware
+       sends the first packet with 0x0C 0x06, and the second one with
+       0x18 0x06
+
+Example:
+55 AA 0C 06 F0 F0 F0 F0 7B
+55 AA 18 06 F0 F0 F0 F0 93
+
+
+0xCC - car programming
+----------------------
+Format: 0x55 0xCC CTRL 0xFE 0xFF 0xFF 0xFF 0xFF CRC
+
+Sent twice when matching the car to the particular controller. 
+
+CTRL:
+       Bit 7 - always 1
+       Bits 6-3 - always 0
+       Bits 2-0 - number of the controller (starting from 0)
+
+Example:
+TBD
+
+
+0xD0 - reset
+------------
+Format: 0x55 0xD0 0xFF N1 N2 0xAA 0xAA 0xAA CRC
+
+N1, N2 forms the ratio, probably used as a challenge for car control units
+
+Example:
+55 D0 FF 0A 05 AA AA AA AD
+
+
+0xD3 - standings
+----------------
+Format: 0x55 0xD3 P0-P5 CRC
+
+Sent after passing the start/finish line for the first time in a race
+and then every 300 ms.
+
+P0-P5: one byte for each position, starts with the leader.
+       0xFF means there is no car on this position (for example,
+       when not all cars have passed the start line)
+       Bit 7 - 1 if the car is more than 15 laps behind the leader
+       Bits 6-3 - number of laps behind the leader (0-15, set to 0
+               when bit 7 is set to 1)
+       Bits 2-0 - vehicle number (0-5)
+
+Example:
+55 D3 81 FF FF FF FF FF 2C
+
+
+0xD4 - lap time
+---------------
+Format: 0x55 0xD4 ID R1 R2 MS T1 T2 CRC
+
+Sent after passing the finish line and then every 300 ms.
+Lap count and last lap time of the specified vehicle.
+
+ID: car number (0-5)
+R1: Round number - higher byte
+R2: Round number - lower byte (bit 0 is always zero)
+MS: miscellaneous
+       Bits 7-4 - always 0
+       Bit 3 - least significant bit of T1
+       Bit 2 - unknown
+       Bit 1 - unknown
+       Bit 0 - least significant bit of R2
+T1: Lap time - higher byte (bit 0 is always zero)
+T2: Lap time - lower byte
+
+So the lap number is 256*R1 + R2 + MS & 0x01, and the time is
+256*T1 + (MS & 0x08 ? 1 : 0)
+
+Example:
+55 D4 01 00 00 01 00 00 59  (round 1 - after crossing the start line)
+55 D4 01 00 02 08 00 E8 32  (round 2)
+55 D4 01 00 02 0D 00 B6 3C  (round 3)
+55 D4 01 00 04 0C 04 98 69  (round 4)
+
+
+0xD5 - race start
+-----------------
+Format: 0x055 0xD5 DI R2-R0 0xFF 0xFF CRC
+
+Sent when the Start button is pressed for two seconds, i.e. before
+the start of the race.
+
+DI - lap counting direction. 0x00 means counting from 0 upwards,
+       0xFF means counting from preset number of laps downwards.
+R2-R0 - number of laps. Only lower 4 bits are used, so the count
+       can be obtained as 256*R2 + 16*R1 + R0
+
+Example:
+55 D5 00 FF FF FF FF FF 83
+
+
+0xD6 - fuel level
+-----------------
+Format: 0x55 0xD6 F0-F2 N1 N2 B CRC
+
+Sent about every 500 ms, current fuel level
+
+F0-F2 - encodes the fuel level for each car in 4 bits (values 0-8);
+       car 0 is in higher-order bits of F0 (F0 >> 4), car 5
+       is in lower-order bits of F2 (F2 & 0x0F).
+N1,N2 - fuel consumption ratio (e.g. 0x14 0x50 means 0.25, 0x00 0x50
+       means the race w/o fuel consumption).
+B - 0xAA, but the source reports that 0xFF has been rarely seen here as well.
+
+Example:
+55 D6 88 88 88 00 50 AA 3D
+55 D6 88 18 88 14 50 AA 7F
+
+
+0xD7 - brake setting
+--------------------
+Format: 0x55 0xD7 CT BR 0x83 0x93 0xDB 0xFF CRC
+
+CT - the controller which had the back button pressed (0-5)
+BR - brake level (0x00 - 0 %, 0x02 - 50 %, 0x04 - 100 %)
+
+Example:
+TBD
+
+
+0xDB - qualification
+--------------------
+Format: 0x55 0xDB R2-R0 NR 0xFF 0xFF CRC
+
+Sent after the start of the qualification.
+
+R2-R0 - number of laps. Only lower 4 bits are used, so the count
+       can be obtained as 256*R2 + 16*R1 + R0
+NR - number of cars participating in the qualification
+
+
+0xDC - end of the race
+----------------------
+Format: 0x55 0xDC 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF CRC
+
+Sent twice when the last vehicle crosses the finish line or the race is stopped.
+
+Example:
+55 DC FF FF FF FF FF FF DF
+
+
+0xDD - race start
+-----------------
+Format: 0x55 0xDD 0x00 0xAA 0xAA 0xAA 0xAA 0xAA CRC
+
+Sent twice after the reset packet (0xD0) has been sent twice.
+
+Example:
+55 DD 00 AA AA AA AA AA 42
+
+
+0xDE - display change
+---------------------
+Format: 0x55 0xDE WE 0xFF 0xFF 0xFF 0xFF 0xFF CRC
+
+WE - 0 or 1
+
+Sent in the RES mode: after the SELECT button is pressed for the
+first time, no packet is sent. The second time the packet with WE = 0
+is sent, the third time two packets are sent (one weith WE = 0 and
+one with WE = 1), and the fourth time two packets are sent
+(one with WE = 1 and one with WE = 0).
+
+Example:
+TBD
+
+
+0xEE - finish line
+------------------
+Format: 0x05 0xEE R0-R5 CRC
+
+Sent after the car crosses the finish line and sends back its ID.
+
+R0-R5 - one byte for each car. 0xE7 means that this car has crossed the
+       finish line, every other value means it did not cross it:
+       0xAA is sent for unconnected controllers.
+       My pit box with 020 firmware has been seen sending either
+       0xF0 or 0xFE values as well
+
+Example:
+55 EE F0 E7 F0 AA AA AA 3C
+55 EE FE FE E7 AA AA AA 1E
+
+
+0xFF - controller status
+------------------------
+Format: 0x55 0xFF R0-R5 CRC
+
+Sent approximately every 102 ms, or when the change is detected.
+
+R0-R5: For each controller there is one byte.
+       0xAA - set when the controller is not connected
+       otherwise, the bits have the following meaning:
+       Bit 7 - always 1
+       Bit 6 - always 1
+       Bit 5 - lights (0 = on, 1 = off)
+               (note the lights setting is reported for each controller,
+               even though the control unit can set it only for all cars
+               at once)
+       Bit 4 - back button (0 = pressed, 1 = not pressed)
+       Bits 3-0 - throttle (values 0-12 in normal mode, 0-8 in junior mode,
+               and 0-6 in the pit lane)
+
+Example:
+55 FF F0 F0 F0 AA AA AA 7D
+- controllers 1-3 present and idle, 4-6 not connected
+
+