cebpic/README.protocol

   1 PROTOCOL BETWEEN HOST AND MASTER PIC
   2 ====================================
   3
   4 9600 8N1 over the serial port.  The PIC must obey the host's flow
   5 control line, so that if the host gets backed up none of the PICs
   6 messages can get lost.  (If this is too hard, then the PIC should
   7 attempt to buffer some data while the host is busy but if the PIC's
   8 buffer gets too full it should panic.)
   9
  10 Each message consists of a number of 8-bit bytes.  The top bit of each
  11 byte is 1 iff there is another byte in the message.
  12
  13  First       Second      ASCII  Message   Brief
  14   Byte        byte etc.  or hex  name      description
  15
  16 From host to PIC:
  17
  18  > 1 0100 TTT  0 TTTTTTT  (a0)  POINT     Point T fire
  19  > 1 1111 111  ....       (ff)  NMRADATA  NMRA data
  20  > 1 0001 XXX  0 XXXXXXX  (88+) PING      Ping `X' (please Pong `X')
  21  > 1 0010 RRR  E RRR...   (90+) POLARITY  Set polarity
  22  > 1 0011 000  0 MMMMMMM  (98+) WATCHDOG  W'dog reset, t/o <M*16>ms from now
  23  > 0 0100 001             (21)  ON        Power on
  24  > 0 0100 000             (20)  OFF       Power off
  25
  26  > 00000000                     CRASHED   Acknowledge panic, go to readout mode
  27  > 00000001                     ACKSERERR RS232 framing or overrung (panic'd)
  28
  29 ; In crash readout mode:
  30 ;
  31 ;       00000000  MS    Select crash readout mode if not already
  32 ;                       Reset crash readout pointer to 0
  33 ;
  34 ;       1vvvvvvv  M     Prepare byte 0vvvvvvv for transmission to the slave
  35 ;
  36 ;       0000nnnn  M     (n>0) prepare to receive nnnn bytes from slave
  37 ;       0001nnnn  M     (n>0) transmit nnnn bytes of our own from the
  38 ;                         readout pointer
  39 ;
  40 ;       001sssss  M     Select slave S^0x10.  Then:
  41 ;                        After 1vvvvvvv
  42 ;                         Transmit just 0vvvvvvv to slave
  43 ;                         and then send some some unspecified byte to host
  44 ;                        After 0000nnnn
  45 ;                         Receive nnnn bytes, forwarding each one
  46 ;                         to the host.
  47 ;                        After the transaction is complete, 1vvvvvvv
  48 ;                         or 0000nnnn must be specified again before
  49 ;                         001sssss is repeated.
  50 ;
  51 ;       01bbbbbb  MS    Supply 6 bits for crash readout pointer
  52 ;                        (crash readout mode only)
  53 ;                        Effect is   FSR << 6; FSR |= bbbbbb
  54
  55 From PIC to host:
  56
  57  < 1 001Y SSS  0 SSSSSSS  (9?)  DETECT    Train is (Y=1) or is not (Y=0) at S
  58  < 1 0001 XXX  0 XXXXXXX  (88+) PONG      Pong `X' (reply to Ping `X')
  59  < 0 000 1001             (HT)  HELLO     I am booted
  60  < 0 000 1011             (VT)  AAARGH    Followed by debug chars (only)
  61  < 0 000 1101             (CR)  WATCHDOG  Timeout happened
  62  < 0 000 0111             (BEL) FAULT     Fault exists
  63  < 0 000 0110             (ACK) FIXED     Fault now fixed
  64  < 0 0100 PPP             (20+) POINTED   Point change done using capacitor P
  65  < 0 0101 PPP             (28+) CHARGED   Point capacitor P is now charged
  66  < 0 00000 FF                   NMRADONE  Have processed F NMRADATA message(s)
  67
  68  < 0000 1010              (LF)  } debugging output        0x0a (newline) and
  69  < 001C CCCC                    } (works with terminal      0x20-0x7e
  70  < 01CC CCCC except 0111 1111   }  emulator, or host logs)  (printing ASCII)
  71
  72 (These are all shown big-endian, and all of the numerical
  73 representations are big-endian too.  Where a number is split across
  74 two or more bytes, the relevant bits are to be concatenated, in the
  75 order shown, ie bits from the MS byte first, into a larger number.)
  76
  77
  78 HELLO, AAARGH and debugging output
  79 ----------------------------------
  80
  81 When the master PIC starts up and has confirmed that all is well (all
  82 of the other PICs are there, etc), it should send HELLO once.
  83
  84 If the host makes a mistake (eg, sends an unknown command, or does
  85 something else wrong) or something goes horribly wrong, the master PIC
  86 should send AAARGH.
  87
  88 The PIC may always send printing ASCII characters and spaces and
  89 newlines (ie, bytes 0x0a, 0x20-0x7e).  These will print out nicely in
  90 a terminal emulator, if that's what's running on the host.  If the
  91 host is running the real software, that software will put the
  92 characters sent in its log or somewhere else nicely accessible.
  93
  94 Apart from debugging output, the PIC should send nothing before HELLO
  95 and nothing after AAARGH.
  96
  97
  98 POWER AND FAULT
  99 ---------------
 100
 101 The host can send ON and OFF to turn the track (and various other
 102 stuff) on and off.  After ON, the track power should be enabled and
 103 transmitting NMRA idle, and the CDU should be enabled.
 104
 105 If the power is ON, and a track power short circuit is detected, the
 106 PIC should send FAULT.  When the short circuit is removed, the PIC
 107 should send FIXED but not fully reenable track power; track power
 108 should be reenabled when the host transmits ON.
 109
 110
 111        Track and CDU                     Track and CDU
 112         disabled      -------ON------->   enabled
 113                 .
 114                /|\                           |
 115                 |                            |Short circuit detected
 116                  \                           |
 117                   \FIXED                   FAULT
 118                    \                         |
 119                     \__________________      V
 120                         operator       `
 121                     fixes the short     Short circuit
 122                                       (User Fault indicator lit)
 123
 124
 125
 126 POINTS and CDU
 127 --------------
 128
 129 The ON command should cause the CDU to be enabled (and of course all
 130 point motor outputs should be disabled first - see README.circuitry).
 131
 132 Following ON the host must wait until it receives CHARGED before
 133 attempting to change a point.  After CHARGED it may send POINT, to
 134 activate the point and direction specified by T.  The PICs will report
 135 POINTED when the point has stopped moving, and CHARGED when the CDU is
 136 ready to change another point (the host may not send POINT for a point
 137 on the same CDU until then).
 138
 139 Currently there is only one CDU so P is always 0 (but the PICs need
 140 not check that the received P value is 0; they may simply assume it).
 141
 142
 143     ----ON-----> CDU is  ------CHARGED---> CDU is charged
 144                  charging              _.  and ready
 145                                        /|
 146                         ,----CHARGED--'       |
 147                        /                      |POINT
 148                       /                       |
 149            Point has '                        V
 150          changed; CDU
 151         is recharging  <----POINTED----  Point is changing
 152
 153
 154
 155 PING and PONG
 156 -------------
 157
 158 The host may send PING at any time; the PIC should reply with PONG
 159 with the same X as was in the PING message.  The host may not send
 160 another PING until the first one's PONG has come back.
 161
 162
 163 POLARITY and POLARISED
 164 ----------------------
 165
 166 The POLARITY command may be sent whether the track power is enabled or
 167 disabled.  The polarity of each segment is `unreversed' after ON; it
 168 remains constant until from then on except as modified by POLARITY.
 169
 170 The command is of variable length (but at least two bytes):
 171
 172  > 1 0010 RRR  E RRR...         POLARITY  Set polarity
 173
 174 Each byte after the first contains 7 more R bits.  The first R bit
 175 (most significant R bit in the first byte) corresponds to track
 176 reversal segment 1; The next bit (2nd most significant bit in the
 177 first byte) corresponds to track reversal segment 2; and so on.
 178
 179 Bits which do not correspond to defined reversal segments will be
 180 ignored by the PICs.  The host must send exactly as many bytes as are
 181 necessary to include all of the reversal segments for each reversers
 182 board (for every potential reversal segment, regardless of whether
 183 that segment is a defined segment corresponding to some actual track).
 184
 185 For example, if there are 14 reversible segments (numbered 1 to 14)
 186 then the following message
 187    1 0010 000    1 000 1000    0 111 1010     Actual message
 188   (E      RRR)  (E RRR RRRR)  (E RRR R---)    } helpful annotations
 189                           1      111 1111     }  and commentary
 190           123      456 7890      123 4567     }
 191 specifies to reverse segments 7 and 11 to 14.  The trailing bits are
 192 for segments 15 to 17 and are ignored.  (Note that the assignment of
 193 physical segments to segment numbers is complex due to bit-twiddling.
 194 see detpic/reverse.asm and layout/data2safety.)
 195
 196 The PIC will reply to POLARITY with POLARISED when the polarity change
 197 is complete.  The host must not send another POLARITY until then.
 198
 199
 200 NMRADATA and NMRAFULL
 201 ---------------------
 202
 203 The data bits in all of the bytes of the NMRADATA command (including
 204 the first) are simply transmitted as NMRA data to the track (most
 205 significant bit first).  The top `end of packet' bit is not
 206 transmitted, though.
 207
 208 The first 14 data bits in the NMRA packet should be 1s.  (i.e. the
 209 first two complete bytes should be 11111111 11111111).  Packets
 210 beginning with a different first byte are reserved for other commands
 211 to the PIC and the 14 idle bits are a requirement of the NMRA
 212 specification.
 213
 214 The maximum NMRA message length is 15 bytes each carrying 7 bits of
 215 actual NMRA data (i.e. 105 bits).
 216
 217 Up to three NMRADATA commands may be supplied by the host to the
 218 master PIC, and their will be transmitted in sequence.  After each
 219 NMRADATA is completed, the PIC will send an NMRAFULL message to the
 220 host.  In the NMRAFULL message, F is the number of completely-received
 221 NMRADATA commands awaiting transmission to the track.
 222
 223 If the PIC runs out of NMRA data, it will transmit an NMRA idle
 224 stream.  It is an error for the host to try to have more than three
 225 outstanding NMRADATA commands.
 226
 227
 228 DETECT
 229 ------
 230
 231 The DETECT command indicates to the host whether there is currently a
 232 train being detected at a specific location.  The PIC must send a
 233 DETECT with Y=1 when a train is detected in a location where there was
 234 previously none, and with Y=0 when a train ceases to be detectable for
 235 more than a small amount of time.
 236
 237 At HELLO, the host will assume that no trains are being detected.
 238
 239
 240 RAM (data) memory map
 241 =====================
 242
 243 The data memory map (for PIC18F458) looks like this:
 244
 245  0x000-0x05f    Access bank RAM - RAM locations accessible via
 246                  access bank instructions; also form part of
 247                  RAM page 0
 248  0x060-0x0ff    Remainder of RAM page 0, accessible only via correct
 249                  BSR setting (ie, BSR==0), INDF, etc.
 250
 251  0x100-0x1ff    RAM page 1, accessible only via bank switching etc.
 252  0x200-0x2ff    RAM page 2, accessible only via bank switching etc.
 253  0x300-0x3ff    RAM page 3, accessible only via bank switching etc.
 254  0x400-0x4ff    RAM page 4, accessible only via bank switching etc.
 255  0x500-0x5ff    RAM page 5, accessible only via bank switching etc.
 256
 257  0x600-0xeff    Nothing here, don't try to access.
 258
 259  0xf00-0xf5f    SFR's (memory-mapped peripherals etc.) accessible
 260                  only via correct BSR, INDF, etc - but these are only
 261                  the CAN SFR's and we do not use the CAN controller.
 262  0xf60-0xfff    SFR's accessible via access bank (also form part
 263                  of RAM page 15).
 264
 265
 266 See common.inc for actual uses of the RAM areas.
 267
 268
 269 Program (flash etc.) memory map
 270 ===============================
 271
 272 Program memory map (for PIC18F458) looks like this:
 273
 274   0x00 0000-    Program memory
 275   0x00 7fff      Contains actual program instructions and can also
 276                  contain preprogrammed data provided via special .asm
 277                  files.  Notable contents and addresses:
 278                    0x00 0000  reset vector
 279                    0x00 0008  high-priority interrupt vector
 280                    0x00 0018  low-priority interrupt vector
 281                  See common.inc for some special tables in here, for
 282                  morse messages, pin/hardware-object definitions, etc.
 283
 284   0x20 0000-    ID locations
 285   0x20 0007      Programming which varies per PIC.  Programmed by
 286                  idlocs*.asm which are made by make-idlocs and
 287                  included in perpic*.hex.  Contents:
 288
 289                 0x20 0000
 290                   bits 7-5 = 000
 291                   bits 4-0 = PIC number (guaranteed to be
 292                              in the range 0..31 inclusive)
 293                 0x20 0001
 294                   bit 7     = 1 for the main PIC (#0)
 295                               0 otherwise
 296                   bit 6     = 1 for Reversers board, 0 for Detectors
 297                   bits 0-5  = currently unused, set to 0
 298
 299                 0x20 0002-  } not currently used,
 300                 0x20 0007   }  may contain anything
 301
 302   0x30 0000-    Hardware configuration
 303   0x30 000f      Defines (clock source, WDT operation, etc.)
 304                  Probably best not to touch.  `config.asm' provides
 305                  correct contents, which is included in *-withcfg.hex
 306                  and perpic*.hex.
 307
 308   0x3f fffe-    Hardware device ID
 309   0x3f ffff      Fixed at manufacturing time; can be read to discover
 310                  hardware type and version (probably not very useful)
 311
 312   0xf0 0000-    EEPROM data area
 313   0xf0 00ff      Not currently used by us
 314
 315   0x01 0000-    } These locations, not listed above,
 316   0x1f ffff     }   do not correspond to anything - there
 317   0x20 0008-    }   is no hardware or memory in the chip
 318   0x2f ffff     }   at these locations.
 319   0x30 0010-    }
 320   0x3f fffd     } Accessing them isn't useful
 321   0x40 0000-    }   and should probably be avoided.
 322   0xef ffff     }
 323
 324
 325 (Buffer page 50 0000h reserved for NMRA)    XXXX these look wrong
 326 (Buffer page 40 0000h reserved for i2c)     XXXX   -iwj
 327
 328
 329
 330 I2C
 331 ===
 332 (slave addresses will be 10xxxxx where xxxxx=PIC number above)