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