From: ian Date: Sat, 21 May 2005 01:19:16 +0000 (+0000) Subject: full protocol with message formats etc, as discussed the other day X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ijackson/git?a=commitdiff_plain;h=9784c6305201ce3bbe34063cbf6e3d17b97aa5fd;p=trains.git full protocol with message formats etc, as discussed the other day --- diff --git a/cebpic/README.protocol b/cebpic/README.protocol index b7f78b8..86204e4 100644 --- a/cebpic/README.protocol +++ b/cebpic/README.protocol @@ -1,22 +1,209 @@ -NMRA -==== +PROTOCOL BETWEEN HOST AND MASTER PIC +==================================== -NMRA packets from the computer to the PIC should consist of 8-bit bytes. +9600 8N1 over the serial port. The PIC must obey the host's flow +control line, so that if the host gets backed up none of the PICs +messages can get lost. (If this is too hard, then the PIC should +attempt to buffer some data while the host is busy but if the PIC's +buffer gets too full it should panic.) -bits 6-0 contain the data to be sent to the track -bit 7 is 1 if the byte is the last in the packet and 0 otherwise - -The first 14 data bits in the NMRA packet should be 1s. -(i.e. the first two complete bytes should be 01111111 01111111) -(packets beginning with some other sequence are reserved for non-NMRA messages) +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. -Maximum NMRA message length = 15 bytes (i.e. 105 bits). -Messages longer than this will cause things to get confused at the moment. + First Second ASCII Message Brief + Byte byte etc. name description -baud rate 9600 -most significant bit first -8n1 +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 + +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') + < 0 000 1001 (HT) HELLO I am booted + < 0 000 1011 (VT) AAARGH Followed by debug chars (only) + < 0 000 0111 (BEL) FAULT Fault exists + < 0 000 0110 (ACK) FIXED Fault now fixed + < 0 000 0100 POLARISED Set polarity done + < 0 0100 PPP POINTED Point change done using capacitor P + < 0 0101 PPP CHARGED Point capacitor P is now charged + < 0 00000 FF NMRAFULL F pending NMRA messages + + < 0000 1010 (LF) } debugging output 0x0a (newline) and + < 001C CCCC } (works with terminal 0x20-0x7e + < 01CC CCCC except 0111 1111 } emulator, or host logs) (printing ASCII) + +(These are all shown big-endian, and all of the numerical +representations are big-endian too. Where a number is split across +two or more bytes, the relevant bits are to be concatenated, in the +order shown, ie bits from the MS byte first, into a larger number.) + + +HELLO, AAARGH and debugging output +---------------------------------- + +When the master PIC starts up and has confirmed that all is well (all +of the other PICs are there, etc), it should send HELLO once. + +If the host makes a mistake (eg, sends an unknown command, or does +something else wrong) or something goes horribly wrong, the master PIC +should send AAARGH. + +The PIC may always send printing ASCII characters and spaces and +newlines (ie, bytes 0x0a, 0x20-0x7e). These will print out nicely in +a terminal emulator, if that's what's running on the host. If the +host is running the real software, that software will put the +characters sent in its log or somewhere else nicely accessible. + +Apart from debugging output, the PIC should send nothing before HELLO +and nothing after AAARGH. + + +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.) + +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 +should send FIXED but not fully reenable track power; track power +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 + \ | + \__________________ V + operator ` + fixes the short Short circuit + (User Fault indicator lit) + + + +POINTS and CDU +-------------- + +The ON command should cause the CDU to be enabled (and of course all +point motor outputs should be disabled first - see README.circuitry). + +Following ON the host must wait until it receives CHARGED before +attempting to change a point. After CHARGED it may send POINT, to +activate the point and direction specified by T. The PICs will report +POINTED when the point has stopped moving, and CHARGED when the CDU is +ready to change another point (the host may not send POINT for a point +on the same CDU until then). + +Currently there is only one CDU so P is always 0 (but the PICs need +not check that the received P value is 0; they may simply assume it). + + + ----ON-----> CDU is ------CHARGED---> CDU is charged + charging _. and ready + /| + ,----CHARGED--' | + / |POINT + / | + Point has ' V + changed; CDU + is recharging <----POINTED---- Point is changing + + + +PING and PONG +------------- + +The host may send PING at any time; the PIC should reply with PONG +with the same X as was in the PING message. The host may not send +another PING until the first one's PONG has come back. + + +POLARITY and POLARISED +---------------------- + +The POLARITY command may be sent whether the track power is enabled or +disabled. The polarity of each segment is `unreversed' after ON; it +remains constant until from then on except as modified by POLARITY. + +The command is of variable length (but at least two bytes): + + > 1 0010 RRR E RRR... POLARITY Set polarity + +Each byte after the first contains 7 more R bits. The first R bit +(most significant R bit in the first byte) corresponds to track +detection segment 1; The next bit (2nd most significant bit in the +first byte) corresponds to track detection segment 2; and so on. + +Bits which do not correspond to defined track detection segments will +be sent as 0 by the host but may be ignored by the PICs. The host +must send exactly as many bytes as are necessary to include all of the +defined segments. + +For example, if there are 14 detection segments (numbered 1 to 14) +then the following message + 1 0010 000 1 000 1000 0 111 1010 Actual message + (E RRR) (E RRR RRRR) (E RRR R---) } helpful annotations + 1 111 1111 } and commentary + 123 456 7890 123 4567 } +specifies to reverse segments 7 and 11 to 14. The trailing bits are +for segments 15 to 17 and are ignored. + +The PIC will reply to POLARITY with POLARISED when the polarity change +is complete. The host must not send another POLARITY until then. + + +NMRADATA and NMRAFULL +--------------------- + +The data bits in all of the bytes of the NMRADATA command (including +the first) are simply transmitted as NMRA data to the track (most +significant bit first). The top `end of packet' bit is not +transmitted, though. + +The first 14 data bits in the NMRA packet should be 1s. (i.e. the +first two complete bytes should be 11111111 11111111). Packets +beginning with a different first byte are reserved for other commands +to the PIC and the 14 idle bits are a requirement of the NMRA +specification. + +The maximum NMRA message length is 15 bytes each carrying 7 bits of +actual NMRA data (i.e. 105 bits). + +Up to three NMRADATA commands may be supplied by the host to the +master PIC, and their will be transmitted in sequence. After each +NMRADATA is completed, the PIC will send an NMRAFULL message to the +host. In the NMRAFULL message, F is the number of completely-received +NMRADATA commands awaiting transmission to the track. + +If the PIC runs out of NMRA data, it will transmit an NMRA idle +stream. It is an error for the host to try to have more than three +outstanding NMRADATA commands. + + +DETECT +------ + +The DETECT command indicates to the host whether there is currently a +train being detected at a specific location. The PIC must send a +DETECT with Y=1 when a train is detected in a location where there was +previously none, and with Y=0 when a train ceases to be detectable for +more than a small amount of time. + +At HELLO, the host will assume that no trains are being detected. RAM (data) memory map @@ -62,7 +249,7 @@ Program memory map (for PIC18F458) looks like this: 0x00 0018 low-priority interrupt vector See common.inc for some special tables in here, for morse messages, pin/hardware-object definitions, etc. - + 0x20 0000- ID locations 0x20 0007 Programming which varies per PIC. Programmed by idlocs*.asm which are made by make-idlocs and @@ -79,13 +266,13 @@ Program memory map (for PIC18F458) looks like this: 0x20 0002- } not currently used, 0x20 0007 } may contain anything - + 0x30 0000- Hardware configuration 0x30 000f Defines (clock source, WDT operation, etc.) Probably best not to touch. `config.asm' provides correct contents, which is included in *-withcfg.hex and perpic*.hex. - + 0x3f fffe- Hardware device ID 0x3f ffff Fixed at manufacturing time; can be read to discover hardware type and version (probably not very useful) @@ -93,10 +280,10 @@ Program memory map (for PIC18F458) looks like this: 0xf0 0000- EEPROM data area 0xf0 00ff Not currently used by us - 0x01 0000- } These locations, not listed above, - 0x1f ffff } do not correspond to anything - there - 0x20 0008- } is no hardware or memory in the chip - 0x2f ffff } at these locations. + 0x01 0000- } These locations, not listed above, + 0x1f ffff } do not correspond to anything - there + 0x20 0008- } is no hardware or memory in the chip + 0x2f ffff } at these locations. 0x30 0010- } 0x3f fffd } Accessing them isn't useful 0x40 0000- } and should probably be avoided.