document new state behaviours for OFF and CDU

[trains.git] / cebpic / README.protocol

diff --git a/cebpic/README.protocol b/cebpic/README.protocol
index f3fc16f336761984a55e3f32d1b8592b713c08e0..df31395c25d08045bf0ff54cc05282694f8f2360 100644 (file)
--- a/cebpic/README.protocol
+++ b/cebpic/README.protocol
@@ -11,27 +11,33 @@ Each message consists of a number of 8-bit bytes.  The top bit of each
 byte is 1 iff there is another byte in the message.
 
  First       Second      ASCII  Message          Brief
-  Byte        byte etc.                 name      description
+  Byte        byte etc.         or hex  name      description
 
 From host to PIC:
 
- > 1 0100 TTT  0 TTTTTTT       POINT     Point T fire
- > 1 1111 111  ....             NMRADATA  NMRA data
- > 1 0001 XXX  0 XXXXXXX        PING     Ping `X' (please Pong `X')
- > 1 0010 RRR  E RRR...         POLARITY  Set polarity
- > 0 0100 001                   ON       Power on
- > 0 0100 000                   OFF      Power off
+ > 1 0100 TTT  0 TTTTTTT  (a0)  POINT    Point T fire
+ > 1 1111 111  ....       (ff)  NMRADATA  NMRA data
+ > 1 0001 XXX  0 XXXXXXX  (88+)        PING      Ping `X' (please Pong `X')
+ > 1 0010 RRR  E RRR...   (90+)        POLARITY  Set polarity
+ > 1 0011 000  0 MMMMMMM  (98+)        WATCHDOG  W'dog reset, t/o <M*16>ms from now
+ > 0 0010 001             (11) ON        Power on
+ > 0 0010 000             (10) OFF       Power off
 
- > 00000000                     CRASHED   Acknowledge panic, go to readout mode
+;> 00000000                     CRASHED   Acknowledge panic, go to readout mode
+;> 00001002               (0a) TELLMODE  Confirm mode - say HELLO or CRASHED
+;                                          if crashed, undoes the effect of ack
 
 ; In crash readout mode:
 ;
 ;      00000000  MS    Select crash readout mode if not already
 ;                      Reset crash readout pointer to 0
 ;
+;      00001000        Acknowledge RS232 framing error or overrun
+;      00001001        Reboot
+;
 ;      1vvvvvvv  M     Prepare byte 0vvvvvvv for transmission to the slave
 ;
-;      0000nnnn  M     (n>0) prepare to receive nnnn bytes from slave
+;      00000nnn  M     (n>0) prepare to receive nnnn bytes from slave
 ;      0001nnnn  M     (n>0) transmit nnnn bytes of our own from the
 ;                        readout pointer
 ;
@@ -52,15 +58,16 @@ From host to PIC:
 
 From PIC to host:
 
- < 1 001Y SSS  0 SSSSSSS        DETECT   Train is (Y=1) or is not (Y=0) at S
- < 1 0001 XXX  0 XXXXXXX        PONG     Pong `X' (reply to Ping `X')
+ < 1 001Y SSS  0 SSSSSSS  (9?) DETECT    Train is (Y=1) or is not (Y=0) at S
+ < 1 0001 XXX  0 XXXXXXX  (88+)        PONG      Pong `X' (reply to Ping `X')
  < 0 000 1001             (HT)  HELLO    I am booted
  < 0 000 1011             (VT)  AAARGH   Followed by debug chars (only)
+ < 0 000 1101             (CR)  WATCHDOG  Timeout happened
  < 0 000 0111             (BEL) FAULT    Fault exists
  < 0 000 0110             (ACK) FIXED    Fault now fixed
- < 0 0100 PPP                   POINTED          Point change done using capacitor P
- < 0 0101 PPP                   CHARGED          Point capacitor P is now charged
- < 0 00000 FF                   NMRADONE  Have processed F NMRADATA message(s)
+ < 0 0100 PPP             (20+)        POINTED   Point change done using capacitor P
+ < 0 0101 PPP             (28+)        CHARGED   Point capacitor P is now charged
+ < 0 00000 FF                  NMRADONE  Have processed F NMRADATA message(s)
 
  < 0000 1010              (LF)  } debugging output        0x0a (newline) and
  < 001C CCCC                    } (works with terminal      0x20-0x7e
@@ -97,9 +104,7 @@ POWER AND FAULT
 
 The host can send ON and OFF to turn the track (and various other
 stuff) on and off.  After ON, the track power should be enabled and
-transmitting NMRA idle, and the CDU should be enabled.  (ON - or the
-things that might precede ON such as FAULT etc. - should clear the
-data from any previous NMRADATA commands.)
+transmitting NMRA idle, and the CDU should be enabled.
 
 If the power is ON, and a track power short circuit is detected, the
 PIC should send FAULT.  When the short circuit is removed, the PIC
@@ -109,8 +114,8 @@ should be reenabled when the host transmits ON.
 
        Track and CDU                     Track and CDU
         disabled      -------ON------->          enabled
-               .      (clears NMRA
-              /|\      buffers)             |
+               .
+              /|\                           |
                |                            |Short circuit detected
                 \                           |
                  \FIXED                   FAULT
@@ -121,6 +126,11 @@ should be reenabled when the host transmits ON.
                                      (User Fault indicator lit)
 
 
+If OFF is issued in the first 500ms following a short circuit, it will
+be ignored; if the short circuit persists, OFF during the following
+period will go to the `Track and CDU disabled' state without sending
+FIXED.
+
 
 POINTS and CDU
 --------------
@@ -150,6 +160,10 @@ not check that the received P value is 0; they may simply assume it).
        is recharging  <----POINTED----  Point is changing
 
 
+Note that OFF will turn the CDU off, and a short circuit (FAULT) will
+turn it off 500ms later (this delay avoids losing races where the host
+sends a point change instruction just before a short happens).
+
 
 PING and PONG
 -------------