hostside/README.commands

   1 Protocol over new hostside stdin and to multiplexer:
   2
   3  U<   possibly-asynchronous messages from realtime
   4  R<   ditto, but saved for replay too
   5  S    messages to simulation log
   6
   7  D<   static data printed by topology-dump
   8
   9  C>   commands (reflected to other clients)
  10  L>   commands implemented by multiplexer and not reflected to other clients
  11  O<   framming output from commands
  12
  13 Messages from the multiplexer to its clients are always prefixed
  14 with a relevance character, shown as ? below.  In messages from
  15 realtime, the ? is absent.  ? may be
  16       -   result of command by another client
  17       +   result of command by us
  18       &   asynchronous, not related to a specific command
  19       =   related to this actual multiplexer client connection
  20       |   result of replay
  21
  22 ======================================================================
  23
  24 POSSIBLY-ASYNCHRONOUS REPORTING OF MESSAGES TO/FROM (MASTER) PIC
  25
  26  U< ?picioh <timestamp> out <byte> [<byte>...]
  27         In principle, all output to PICs, in raw form, but
  28         subject to suppression
  29
  30  U< ?picioh in junk    <byte> [<byte>...]
  31  U< ?picioh in aargh   <byte> [<byte>...]
  32  U< ?picioh in hello   <byte> [<byte>...]
  33  U< ?picioh in off     <byte> [<byte>...]
  34  U< ?picioh in toolong <byte> [<byte>...]
  35  U< ?picioh in msg     <byte> [<byte>...]
  36
  37  R< ?picio out polarity <[<segment>[,...]]>     literal < and > bracket segs
  38  U< ?picio out unknown                          data printed in assoc'd picioh
  39
  40  U< ?picio in <messagename> [<objectnum>]
  41  U< ?picio out <messagename> [<objectnum>]
  42
  43  U< ?detect <segment-name> 0|1            decoded `picio in detect[01]'
  44  U< ?detect-flap <segment-name> <count>
  45
  46  Suppression (see parse-proto-spec and realtime.c:serial_transmit)
  47         nmra data/done  ping/           special in      other out
  48         detect           pong           (see above)     msg in (also in-info)
  49   -v0    suppressed      suppressed      raw with type   cooked
  50   -v1    suppressed      only unignored  raw with type   cooked
  51   -v2    suppressed      cooked          raw with type   cooked
  52   -v3    both            both            raw with type   both
  53
  54 POSSIBLY-ASYNCHRONOUS REPORTING OF INTERNAL STATE CHANGES ETC.
  55
  56  U< ?resolving <some message about resolution algorithm>
  57
  58  R< ?resolution inexplicable <segment>
  59  R< ?resolution mispositioned head|tail <train> <crush-ending-seg> <distance>
  60  R< ?resolution movpos-change-failed <segment>/<poscombname>
  61  R< ?resolution problems <number-of-problems>
  62
  63  R< ?stastate <state>
  64
  65  U< ?warning <type>[ <arguments>] :  <warning message>
  66  U< ?warning watchdog : PIC watchdog timer triggered
  67  U< ?warning spurious <count> : spurious short circuit (fault) etc.
  68
  69  U< ?warning realtime-failed reason SIG*|exit*|E*|... : <explanation>
  70  U< ?warning realtime-failed stderr : <emsg>
  71  U< ?warning realtime-failed stderr-unreadable : <emsg>
  72  U< ?warning save-dump-failed [<filename> [<errno>]] : <emsg>
  73  U< ?info save-dump <dumpdir>
  74
  75  U< ?train <train> signalling-problem ....
  76  U< ?train <train> signalling-problem <problematic-segment>|- : <message>
  77
  78  R< ?train <train> at [-]<segment>:<maxinto>+-<uncertainty> forwards|backwards
  79  R< ?train <train> has <markchar>[-]<segment>[/<movposcomb>]....
  80        <markchar> is * for det_expected
  81                      ! for foredetect
  82                      @ for det_ignore
  83
  84  R< ?train <train> speed commanding <speedstep>
  85
  86  R< ?movpos <segment> feat <feat> <posn> point|relay
  87  R< ?movpos <segment> position <overallposn> moving
  88  R< ?movpos <segment> position <overallposn> stable
  89             <overallposn> may be ? for unknown
  90
  91  U< ?debug <context> : <debug message>
  92
  93  U< ?info [<stuff>] : <informational message>
  94  U< ?info movfeat-collapsing-unknown <segment> : will set previously [etc.]
  95
  96 MESSAGES TO SIMULATION LOG
  97
  98  S  picioh in suppressed <byte> [<byte>...]
  99  S  picioh in suppressed-detect <byte> [<byte>...]
 100  S  command-in <command> <args>....
 101  S  timestamp <seconds>.<microseconds>
 102  S  timer-event <class>.<instance>
 103  S  0|1                   detection, same segment as last suppressed-detect
 104
 105 ======================================================================
 106
 107 COMMANDS AND RESPONSES
 108
 109  C> <command> [<arguments>...]
 110   results in:
 111  O< ?nak <errorcode> [<remaining info>] [: <message...>]
 112  O< ?executing <command> [<arguments>...]
 113   consequential messages including picio, signalling problems etc.
 114   which may be U< R< then one of these
 115  O< ?ack <command> ok
 116  O< ?ack <command> <errorcode>
 117  O< ?ack <command> <errorcode> [<remaining info>] : <remaining error msg>...
 118  O< ?ack <command> SignallingPredictedProblem \
 119           <problematic-train> <problematic-segment>|- : <error message>...
 120
 121  O< ?ack <command> CommandPreconditionsViolated direction
 122   response to speed command which specified a direction, if the train
 123   is actually facing the other direction
 124
 125     when these come through the multiplexer, everything which is a
 126     result of _other_ clients' activities, between <executing> and
 127     <ack> inclusive, is prefixed with `-' if they are not due to
 128     this client or `+' if they are.
 129
 130     Some commands have ! at the start of their name
 131     - that means they are privileged.
 132
 133 ======================================================================
 134
 135 MULTIPLEXER FACILITIES
 136
 137  U< =connected                           } on
 138  U< =permission normal|super             } initial
 139   or                                     }  connection
 140  U< =denied                              }
 141   and later perhaps
 142  U< =failed : <message>              } regardless of
 143  U< =failed client-io : <message>    }   selected message patterns
 144                                      }  and then connection closed
 145   There is no need to ask to quit - just send eof
 146
 147  L> select [~]<pattern>...
 148     first match wins; ~ discards the message.
 149     in pattern
 150         -+./:=0-9a-zA-Z  match themselves
 151         _                matches nonempty sequence of whitespace
 152         *                matches any non-whitespace
 153         ?                matches any single character
 154     <pattern>_ is matched against <message><spc>
 155     if no match, it is as if the following patterns were appended
 156        ~-* ~&* ~+debug *
 157     default, on initial connection, is
 158        ?info ?warning
 159     (plus the above)
 160
 161  L> replay [[~]<glob-pattern>...]     if none, uses result from select
 162  O< +executing replay
 163  R< |<all messages saved for replay, ie those marked with R< above,
 164       matching the patterns, all of which will be prefixed with | this time>
 165  O< +ack replay ok
 166
 167  L> select-replay [~]<glob-pattern>...
 168       like select and replay combined
 169
 170
 171 MULTIPLEXER-IMPLEMENTED FUNCTIONALITY AFFECTING WHOLE SYSTEM
 172
 173  C> [!]<command> <args>...
 174  O< ?nak|executing...ack...  as above
 175
 176  C> !realtime auto              set automatic restarting; starts if applicable
 177  C> !realtime kill              kill current instance, if auto awaits off
 178  C> !realtime restart           kill and restart
 179  C> !realtime stop              } set manual mode, stop
 180  C> !realtime start             } set manual mode, start as specified,
 181  C> !realtime start-manual      }   restarting if already running
 182  C> !save-dump
 183
 184
 185 ======================================================================
 186
 187 CHIEF COMMANDS
 188
 189  speed <trainpname> <step> [forwards|backwards]
 190  !speed <trainpname> <step>
 191
 192  noop [<anything>...]
 193
 194  adjunct   <feattargetname>       -|+|^ <adjunct>|* [[-|+|^] ...]
 195  !nmrafeat <trainpname>|<addrnum> -|+|^ <nmranum>   [[-|+|^] ...]
 196
 197  route            <seg> <movposcomb>  [<maxms>]
 198  route <before>|- <seg> <after>|-     [<maxms>]    any suitable movposcomb
 199
 200  route+ <as above>    change even segments owned by a train's route
 201  route++ <as above>   even queue changes for segments currently under a train
 202  !route <as above>    just do it, don't ask safety system
 203
 204  movfeat <seg> <feat> <posn> [<maxms>]
 205  movfeat+ <as above>                           } see route+
 206  movfeat++ <as above>                          } see route++
 207  !movfeat <as above>                           } see !route
 208
 209  direction <train> forwards|backwards|change
 210
 211  !invert [<segpname> ...]               each one named is toggled
 212
 213 DIRECT NMRA AND PIC INSTRUCTIONS
 214
 215                                             Example (always the same msg):
 216  C> !nmra [<slot>] [<nmra-command [<nmra-args>...]]    nmra speed28 3 13 1
 217  C> !nmra [<slot>] [=<nmra-bytes>]                     nmra =0348
 218  C> !nmra [<slot>] [:<nmra-bytes-with-csum>]           nmra :03484b
 219  C> !nmra [<slot>] [_<pic-literal-bytes>]              nmra _7f7f00644197
 220    in each case <slot> (if present) is *<slotname> or %<slotname> and
 221    indicates that the message should be put in the retransmission
 222    cycle, and cancels any previous message with the same <slotname>.
 223    <slotname> may be empty.  * indicates urgent
 224  C> !nmra <slot>
 225    cancels the relevant retransmission.
 226
 227                                             Example (always the same msg):
 228  C> !pic =<pic-bytes>                                   pic =a003
 229  C> !pic <pic-command> [<pic-args...>]                  pic point 3
 230        the latter for commands with no `...' in README.protocol only
 231
 232  Keen readers will observe that
 233     !pic =<pic-bytes>    and
 234     !nmra _<pic-bytes>
 235  do exactly the same.
 236
 237 ======================================================================
 238
 239 TOPOLOGY DUMP
 240
 241  D< topology segment <segment> <n_movfeats> <n_poscombs> i|n
 242  D< topology movfeat <segment> <feat> <posns> <weight> point|relay
 243  D< topology movposcomb <segment> <pname>|- \
 244              <posn> <dist> [-]<backwards>|- [-]<forwards>|-
 245  D< topology movfeatfixed <segment> <feat> <posn>