1 PROTOCOL BETWEEN HOST AND MASTER PIC
2 ====================================
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.)
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.
13 First Second ASCII Message Brief
14 Byte byte etc. name description
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
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
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)
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.)
48 HELLO, AAARGH and debugging output
49 ----------------------------------
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.
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
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.
64 Apart from debugging output, the PIC should send nothing before HELLO
65 and nothing after AAARGH.
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.)
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.
83 Track and CDU Track and CDU
84 disabled -------ON-------> enabled
87 | |Short circuit detected
93 fixes the short Short circuit
94 (User Fault indicator lit)
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).
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).
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).
115 ----ON-----> CDU is ------CHARGED---> CDU is charged
116 charging _. and ready
123 is recharging <----POINTED---- Point is changing
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.
135 POLARITY and POLARISED
136 ----------------------
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.
142 The command is of variable length (but at least two bytes):
144 > 1 0010 RRR E RRR... POLARITY Set polarity
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 reversal segment 1; The next bit (2nd most significant bit in the
149 first byte) corresponds to track reversal segment 2; and so on.
151 Bits which do not correspond to defined reversal segments will be
152 ignored by the PICs. The host must send exactly as many bytes as are
153 necessary to include all of the reversal segments for each reversers
154 board (for every potential reversal segment, regardless of whether
155 that segment is a defined segment corresponding to some actual track).
157 For example, if there are 14 reversible segments (numbered 1 to 14)
158 then the following message
159 1 0010 000 1 000 1000 0 111 1010 Actual message
160 (E RRR) (E RRR RRRR) (E RRR R---) } helpful annotations
161 1 111 1111 } and commentary
162 123 456 7890 123 4567 }
163 specifies to reverse segments 7 and 11 to 14. The trailing bits are
164 for segments 15 to 17 and are ignored. (Note that the assignment of
165 physical segments to segment numbers is complex due to bit-twiddling.
166 see detpic/reverse.asm and layout/data2safety.)
168 The PIC will reply to POLARITY with POLARISED when the polarity change
169 is complete. The host must not send another POLARITY until then.
172 NMRADATA and NMRAFULL
173 ---------------------
175 The data bits in all of the bytes of the NMRADATA command (including
176 the first) are simply transmitted as NMRA data to the track (most
177 significant bit first). The top `end of packet' bit is not
180 The first 14 data bits in the NMRA packet should be 1s. (i.e. the
181 first two complete bytes should be 11111111 11111111). Packets
182 beginning with a different first byte are reserved for other commands
183 to the PIC and the 14 idle bits are a requirement of the NMRA
186 The maximum NMRA message length is 15 bytes each carrying 7 bits of
187 actual NMRA data (i.e. 105 bits).
189 Up to three NMRADATA commands may be supplied by the host to the
190 master PIC, and their will be transmitted in sequence. After each
191 NMRADATA is completed, the PIC will send an NMRAFULL message to the
192 host. In the NMRAFULL message, F is the number of completely-received
193 NMRADATA commands awaiting transmission to the track.
195 If the PIC runs out of NMRA data, it will transmit an NMRA idle
196 stream. It is an error for the host to try to have more than three
197 outstanding NMRADATA commands.
203 The DETECT command indicates to the host whether there is currently a
204 train being detected at a specific location. The PIC must send a
205 DETECT with Y=1 when a train is detected in a location where there was
206 previously none, and with Y=0 when a train ceases to be detectable for
207 more than a small amount of time.
209 At HELLO, the host will assume that no trains are being detected.
212 RAM (data) memory map
213 =====================
215 The data memory map (for PIC18F458) looks like this:
217 0x000-0x05f Access bank RAM - RAM locations accessible via
218 access bank instructions; also form part of
220 0x060-0x0ff Remainder of RAM page 0, accessible only via correct
221 BSR setting (ie, BSR==0), INDF, etc.
223 0x100-0x1ff RAM page 1, accessible only via bank switching etc.
224 0x200-0x2ff RAM page 2, accessible only via bank switching etc.
225 0x300-0x3ff RAM page 3, accessible only via bank switching etc.
226 0x400-0x4ff RAM page 4, accessible only via bank switching etc.
227 0x500-0x5ff RAM page 5, accessible only via bank switching etc.
229 0x600-0xeff Nothing here, don't try to access.
231 0xf00-0xf5f SFR's (memory-mapped peripherals etc.) accessible
232 only via correct BSR, INDF, etc - but these are only
233 the CAN SFR's and we do not use the CAN controller.
234 0xf60-0xfff SFR's accessible via access bank (also form part
238 See common.inc for actual uses of the RAM areas.
241 Program (flash etc.) memory map
242 ===============================
244 Program memory map (for PIC18F458) looks like this:
246 0x00 0000- Program memory
247 0x00 7fff Contains actual program instructions and can also
248 contain preprogrammed data provided via special .asm
249 files. Notable contents and addresses:
250 0x00 0000 reset vector
251 0x00 0008 high-priority interrupt vector
252 0x00 0018 low-priority interrupt vector
253 See common.inc for some special tables in here, for
254 morse messages, pin/hardware-object definitions, etc.
256 0x20 0000- ID locations
257 0x20 0007 Programming which varies per PIC. Programmed by
258 idlocs*.asm which are made by make-idlocs and
259 included in perpic*.hex. Contents:
263 bits 4-0 = PIC number (guaranteed to be
264 in the range 0..31 inclusive)
266 bit 7 = 1 for the main PIC (#0)
268 bit 6 = 1 for Reversers board, 0 for Detectors
269 bits 0-5 = currently unused, set to 0
271 0x20 0002- } not currently used,
272 0x20 0007 } may contain anything
274 0x30 0000- Hardware configuration
275 0x30 000f Defines (clock source, WDT operation, etc.)
276 Probably best not to touch. `config.asm' provides
277 correct contents, which is included in *-withcfg.hex
280 0x3f fffe- Hardware device ID
281 0x3f ffff Fixed at manufacturing time; can be read to discover
282 hardware type and version (probably not very useful)
284 0xf0 0000- EEPROM data area
285 0xf0 00ff Not currently used by us
287 0x01 0000- } These locations, not listed above,
288 0x1f ffff } do not correspond to anything - there
289 0x20 0008- } is no hardware or memory in the chip
290 0x2f ffff } at these locations.
292 0x3f fffd } Accessing them isn't useful
293 0x40 0000- } and should probably be avoided.
297 (Buffer page 50 0000h reserved for NMRA) XXXX these look wrong
298 (Buffer page 40 0000h reserved for i2c) XXXX -iwj
304 (slave addresses will be 10xxxxx where xxxxx=PIC number above)