wip new protocol document and coherency

diff --git a/hostside/README.commands b/hostside/README.commands
index 73599403386d2179ccef873bb4c96060cb60b960..fc37c0c63fc5bc860d502d0a9924bc1383f6da1d 100644 (file)
--- a/hostside/README.commands
+++ b/hostside/README.commands
@@ -1,51 +1,89 @@
 Protocol over new hostside stdin and to multiplexer:
 
+======================================================================
+
+POSSIBLY-ASYNCHRONOUS REPORTING OF MESSAGES TO/FROM (MASTER) PIC
+
+ U< picioh <timestamp> out <byte> [<byte>...]
+       In principle, all output to PICs, in raw form, but
+       subject to suppression
+
+ U< picioh <timestamp> in junk    <byte> [<byte>...]
+ U< picioh <timestamp> in aargh   <byte> [<byte>...]
+ U< picioh <timestamp> in hello   <byte> [<byte>...]
+ U< picioh <timestamp> in off     <byte> [<byte>...]
+ U< picioh <timestamp> in toolong <byte> [<byte>...]
+ U< picioh <timestamp> in msg     <byte> [<byte>...]
+
+ U< picio out polarity <[<segment>[,...]]>     literal < and > bracket segs
+ U< picio out unknown                          data printed in assoc'd picioh
+
+ U< picio in <messagename> [<objectnum>]
+ U< picio out <messagename> [<objectnum>]
+
+ U< picio in-info detect 0|1 <segment-name>    decoded `picio in detect[01]'
+
+ Suppression (see parse-proto-spec and realtime.c:serial_transmit)
+       nmra data       ping/pong       special in      other out
+       nmra done       detect          (see above)     msg in (also in-info)
+  -v0   suppressed      suppressed      raw with type   cooked
+  -v1   suppressed      suppressed      raw with type   cooked
+  -v2   suppressed      cooked          raw with type   cooked
+  -v3   both            both            raw with type   both
+
+ U< resolving <some message about resolution algorithm>
+
+ U< resolution inexplicable <segment>
+ U< resolution movpos-change-failed <segment>/<poscombname>
+ U< resolution problems <number-of-problems>
+
+ U< stastate <state>
+
+ U< warning <type>[ <arguments>] :  <warning message>
+ U< warning watchdog : PIC watchdog timer triggered
+ U< warning spurious <count> : spurious short circuit (fault) etc.
+
+
+======================================================================
+
+COMMANDS AND RESPONSES
+
+ P> <command> [<arguments>...]
+  results in:
+ R< executing <command>
+  consequential messages including picio, signalling problems etc.
+  then one of these
+ R< ack <command> ok
+ R< ack <command> <errorcode>
+ R< ack <command> <errorcode> : <remaining error message>...
+
+======================================================================
+
+DIRECT NMRA AND PIC INSTRUCTIONS
+
                                             Example (always the same msg):
- P> nmra [<slot>] [<nmra-command [<nmra-args>...]]    nmra speed28 3 13 1
- P> nmra [<slot>] [=<nmra-bytes>]                     nmra =0348
- P> nmra [<slot>] [:<nmra-bytes-with-csum>]           nmra :03484b
- P> nmra [<slot>] [_<pic-literal-bytes>]              nmra _7f7f00644197
+ P> !nmra [<slot>] [<nmra-command [<nmra-args>...]]    nmra speed28 3 13 1
+ P> !nmra [<slot>] [=<nmra-bytes>]                     nmra =0348
+ P> !nmra [<slot>] [:<nmra-bytes-with-csum>]           nmra :03484b
+ P> !nmra [<slot>] [_<pic-literal-bytes>]              nmra _7f7f00644197
    in each case <slot> (if present) is *<slotname> or %<slotname> and
    indicates that the message should be put in the retransmission
    cycle, and cancels any previous message with the same <slotname>.
    <slotname> may be empty.  * indicates urgent
- P> nmra <slot>
+ P> !nmra <slot>
    cancels the relevant retransmission.
 
                                             Example (always the same msg):
- P> pic =<pic-bytes>                                   pic =a003
- P> pic <pic-command> [<pic-args...]                   pic point 3
+ P> !pic =<pic-bytes>                                   pic =a003
+ P> !pic <pic-command> [<pic-args...>]                  pic point 3
        the latter for commands with no `...' in README.protocol only
 
  Keen readers will observe that
-    pic =<pic-bytes>    and
-    nmra _<pic-bytes>
+    !pic =<pic-bytes>    and
+    !nmra _<pic-bytes>
  do exactly the same.
 
- P> polarity <bit-string-in-hex>....
-       where, eg, with 14 segments,
-                        [      1]    [111 1111]    reversible
-              [123]     [56 7890]    [123 4567]     segment number
-        1 0010 000    1 000 1000    0 111 1010     example POLARITY
-        1 0010 RRR    1 RRR RRRR    0 RRR R---      from README.protocol
-               RRR      RRR RRRR      RRR R        actual R bits
-               \__        ___/\__      ___/         ... which map ...
-                  RRRRRRRR       RRRRRR             ... into data ...
-                  RRRRRRRR       RRRRRR--           ... like this.
-                  00000010       00111100
-                                 [ 1111111]         reversible
-                  [12345678]     [90123456]          segment number
-                    0x02           0x3c            hex values
-                       023c                         hex data string
-
- Up< pic-out <hex-bytes...>
- Up< pic-in <hex-bytes...>
-
- U< count <type> <number-in-decimal>
-      eg  count polarity 14
- U< pic detect 1|0 <S>
- U< pic point <P>
- U< pic pointed <P>
- U< pic charged <P>
- U< polarity <bit-string-in-hex>....
- U< polarised <bit-string-in-hex>....
+
+
+ack ok commandname
+ack errorcode commandname

diff --git a/hostside/TODO b/hostside/TODO
index 3f26849fdecc93ec023a13ff5e231b4eb2d51d32..1d1bbba2c848615c028cf6b26a116ad2a296cd74 100644 (file)
--- a/hostside/TODO
+++ b/hostside/TODO
@@ -1,3 +1,13 @@
+currently
+       eliminating logmsg and documenting the resulting protocol
+also want to
+       say something from movpos when we change a point
+       say something from prediction when we confirm a plan
+               at least segment ownership and intended movposcombs
+       change `resolving' to debugs (new `debugmsg' function?)
+       document commands [!]movfeat and speed
+       stop all trains command ?
+
 optional but maybe before can test:
        wiring to gui display
 

diff --git a/hostside/commands.c b/hostside/commands.c
index c17e3524e40feab4da2cc1aabe0d3f3ebac2b189..9f5b1e4776cd91d9ad33aa46620fe1525d8638ce 100644 (file)
--- a/hostside/commands.c
+++ b/hostside/commands.c
@@ -30,7 +30,7 @@ struct ManualRetransmitNode {
 
 static void cmd_ppc(Train *tra, Segment *seg, void *pu, const char *message) {
   const CmdInfo *ci= pu;
-  oprintf(UPO,"ack SignallingPredictedProblem %s %s", ci->name, message);
+  oprintf(UPO,"ack %s SignallingPredictedProblem : %s", ci->name, message);
 }
 
 #define MUSTECRPREDICT(requester) do{                                  \
@@ -268,11 +268,11 @@ static int cmd_speed(ParseState *ps, const CmdInfo *ci) {
 }
 
 const CmdInfo toplevel_cmds[]= {
-  { "pic",        cmd_pic         },
-  { "nmra",       cmd_nmra,       },
+  { "!pic",       cmd_pic         },
+  { "!nmra",      cmd_nmra,       },
   { "noop",       cmd_noop        },
   { "movfeat",    cmd_movfeat     },
-  { "movfeat!",   cmd_movfeat, 1  },
+  { "!movfeat",   cmd_movfeat, 1  },
   { "speed",      cmd_speed       },
   { 0 }
 };

diff --git a/hostside/realtime.c b/hostside/realtime.c
index c16b4a76543892dbf996bb2609077271b6103c0b..b2e36730696fe1b1a9324233ce986215b25a4d73 100644 (file)
--- a/hostside/realtime.c
+++ b/hostside/realtime.c
@@ -210,7 +210,7 @@ static void oprint_nmradata(const PicInsn *pi) {
 static const CmdInfo *ci;
 
 int vbadcmd(ParseState *ps, const char *fmt, va_list al) {
-  oprintf(UPO,"ack BadCmd %s: ", ci->name);
+  oprintf(UPO,"ack %s BadCmd : ", ci->name);
   ovprintf(UPO,fmt,al);
   return EC_BadCmd;
 }
@@ -221,9 +221,9 @@ static void command_doline(ParseState *ps, CommandInput *cmdi_arg) {
   ci= some_needword_lookup(ps, toplevel_cmds, "command");
   r= ci->fn(ps,ci);
   switch (r) {
-  case 0:  oprintf(UPO, "ack ok %s\n", ci->name);                    break;
+  case 0:  oprintf(UPO, "ack %s ok\n", ci->name);                    break;
   case EC_BadCmd:                                                    break;
-  default: oprintf(UPO, "ack %s %s\n", errorcodelist[r], ci->name);  break;
+  default: oprintf(UPO, "ack %s %s\n", ci->name, errorcodelist[r]);  break;
   }
 }
 

diff --git a/hostside/startup.c b/hostside/startup.c
index 5f55c1389aee47351694bd6a896acd2c4a4c9c55..07a1c521ff2ce5bde99f3be45b33c1678d138fec 100644 (file)
--- a/hostside/startup.c
+++ b/hostside/startup.c
@@ -202,7 +202,7 @@ void on_pic_wtimeout(const PicInsnInfo *pii, const PicInsn *pi, int objnum) {
   if (sta_state <= Sta_Settling) return;
   if (sta_state == Sta_Resolving || sta_state == Sta_Finalising)
     die("PIC sent WTIMEOUT in Resolving or Finalising");
-  oprintf(UPO, "warning watchdog \"PIC watchdog timer triggered\"\n");
+  oprintf(UPO, "warning watchdog : PIC watchdog timer triggered\n");
 }
 
 void on_pic_hello(const PicInsnInfo *pii, const PicInsn *pi, int objnum)
@@ -210,8 +210,8 @@ void on_pic_hello(const PicInsnInfo *pii, const PicInsn *pi, int objnum)
 void on_pic_aaargh(const PicInsnInfo *pii, const PicInsn *pi, int objnum)
   { abort(); }
 void on_pic_spurious(const PicInsnInfo *pii, const PicInsn *pi, int objnum) {
-  oprintf(UPO,"warning spurious %d \"spurious short circuit (fault)"
-         " detection interrupts\"", objnum);
+  oprintf(UPO,"warning spurious %d : spurious short circuit (fault)"
+         " detection interrupts", objnum);
 }
 
 static SegmentNum on_pic_detect_prep(int detyn, int objnum) {
@@ -221,7 +221,7 @@ static SegmentNum on_pic_detect_prep(int detyn, int objnum) {
       (segn= info_segmentmap[objnum]) < 0)
     die("PIC sent detect%d @#%#x not in map",detyn,objnum);
 
-  oprintf(UPO,"picio in detect%d %s\n",detyn,info_segments[segn].pname);
+  oprintf(UPO,"picio in-info detect %d %s\n",detyn,info_segments[segn].pname);
 
   return segn;
 }