Protocol over new hostside stdin and to multiplexer:

 U<   possibly-asynchronous messages from realtime
 R<   ditto, but saved for replay too
 S    messages to simulation log

 D<   static data printed by topology-dump

 C>   commands (reflected to other clients)
 L>   commands implemented by multiplexer and not reflected to other clients
 O<   framming output from commands

Messages from the multiplexer to its clients are always prefixed
with a relevance character, shown as ? below.  In messages from
realtime, the ? is absent.  ? may be
      -   result of command by another client
      +   result of command by us
      &   asynchronous, not related to a specific command
      =   related to this actual multiplexer client connection
      |   result of replay

======================================================================

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 in junk    <byte> [<byte>...]
 U< ?picioh in aargh   <byte> [<byte>...]
 U< ?picioh in hello   <byte> [<byte>...]
 U< ?picioh in off     <byte> [<byte>...]
 U< ?picioh in toolong <byte> [<byte>...]
 U< ?picioh in msg     <byte> [<byte>...]

 R< ?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< ?detect <segment-name> 0|1		  decoded `picio in detect[01]'
 U< ?detect-flap <segment-name> <count>

 Suppression (see parse-proto-spec and realtime.c:serial_transmit)
	nmra data/done	ping/		special in	other out
	detect		 pong		(see above)	msg in (also in-info)
  -v0	 suppressed	 suppressed	 raw with type	 cooked
  -v1	 suppressed	 only unignored	 raw with type	 cooked
  -v2	 suppressed	 cooked		 raw with type	 cooked
  -v3	 both		 both		 raw with type	 both

POSSIBLY-ASYNCHRONOUS REPORTING OF INTERNAL STATE CHANGES ETC.

 U< ?resolving <some message about resolution algorithm>

 R< ?resolution inexplicable <segment>
 R< ?resolution mispositioned head|tail <train> <crush-ending-seg> <distance>
 R< ?resolution movpos-change-failed <segment>/<poscombname>
 R< ?resolution problems <number-of-problems>

 R< ?stastate <state>

 U< ?warning <type>[ <arguments>] :  <warning message>
 U< ?warning watchdog : PIC watchdog timer triggered
 U< ?warning spurious <count> : spurious short circuit (fault) etc.

 U< ?warning realtime-failed reason SIG*|exit*|E*|... : <explanation>
 U< ?warning realtime-failed stderr : <emsg>
 U< ?warning realtime-failed stderr-unreadable : <emsg>
 U< ?warning save-dump-failed [<filename> [<errno>]] : <emsg>
 U< ?info save-dump <dumpdir>

 U< ?train <train> signalling-problem ....
 U< ?train <train> signalling-problem <problematic-segment>|- : <message>

 R< ?train <train> at [-]<segment>:<maxinto>+-<uncertainty> forwards|backwards
 R< ?train <train> has <markchar>[-]<segment>[/<movposcomb>]....
       <markchar> is * for det_expected
                     ! for foredetect
                     @ for det_ignore

 R< ?train <train> speed commanding <speedstep>

 R< ?movpos <segment> feat <feat> <posn> point|relay
 R< ?movpos <segment> position <overallposn> moving
 R< ?movpos <segment> position <overallposn> stable
            <overallposn> may be ? for unknown

 U< ?debug <context> : <debug message>

 U< ?info [<stuff>] : <informational message>
 U< ?info movfeat-collapsing-unknown <segment> : will set previously [etc.]

MESSAGES TO SIMULATION LOG

 S  picioh in suppressed <byte> [<byte>...]
 S  picioh in suppressed-detect <byte> [<byte>...]
 S  command-in <command> <args>....
 S  timestamp <seconds>.<microseconds>
 S  timer-event <class>.<instance>
 S  0|1                   detection, same segment as last suppressed-detect

======================================================================

COMMANDS AND RESPONSES

 C> <command> [<arguments>...]
  results in:
 O< ?nak <errorcode> [<remaining info>] [: <message...>]
 O< ?executing <command> [<arguments>...]
  consequential messages including picio, signalling problems etc.
  which may be U< R< then one of these
 O< ?ack <command> ok
 O< ?ack <command> <errorcode>
 O< ?ack <command> <errorcode> [<remaining info>] : <remaining error msg>...
 O< ?ack <command> SignallingPredictedProblem \
          <problematic-train> <problematic-segment>|- : <error message>...

 O< ?ack <command> CommandPreconditionsViolated direction
  response to speed command which specified a direction, if the train
  is actually facing the other direction

    when these come through the multiplexer, everything which is a
    result of _other_ clients' activities, between <executing> and
    <ack> inclusive, is prefixed with `-' if they are not due to
    this client or `+' if they are.

    Some commands have ! at the start of their name
    - that means they are privileged.

======================================================================

MULTIPLEXER FACILITIES

 U< =connected                           } on
 U< =permission normal|super             } initial
  or                                     }  connection
 U< =denied                              }
  and later perhaps
 U< =failed : <message>              } regardless of
 U< =failed client-io : <message>    }   selected message patterns
                                     }  and then connection closed
  There is no need to ask to quit - just send eof

 L> select [~]<pattern>...
    first match wins; ~ discards the message.
    in pattern
        -+./:=0-9a-zA-Z  match themselves
        _                matches nonempty sequence of whitespace
	*                matches any non-whitespace
        ?                matches any single character
    <pattern>_ is matched against <message><spc>
    if no match, it is as if the following patterns were appended
       ~-* ~&* ~+debug *
    default, on initial connection, is
       ?info ?warning
    (plus the above)

 L> replay [[~]<glob-pattern>...]     if none, uses result from select
 O< +executing replay
 R< |<all messages saved for replay, ie those marked with R< above,
      matching the patterns, all of which will be prefixed with | this time>
 O< +ack replay ok

 L> select-replay [~]<glob-pattern>...
      like select and replay combined


MULTIPLEXER-IMPLEMENTED FUNCTIONALITY AFFECTING WHOLE SYSTEM

 C> [!]<command> <args>...
 O< ?nak|executing...ack...  as above

 C> !realtime auto              set automatic restarting; starts if applicable
 C> !realtime kill              kill current instance, if auto awaits off
 C> !realtime restart           kill and restart
 C> !realtime stop              } set manual mode, stop
 C> !realtime start             } set manual mode, start as specified,
 C> !realtime start-manual      }   restarting if already running
 C> !save-dump


======================================================================

CHIEF COMMANDS

 speed <trainpname> <step> [forwards|backwards]
 !speed <trainpname> <step>

 noop [<anything>...]

 adjunct   <feattargetname>       -|+|^ <adjunct>|* [[-|+|^] ...]
 !nmrafeat <trainpname>|<addrnum> -|+|^ <nmranum>   [[-|+|^] ...]

 route            <seg> <movposcomb>  [<maxms>]
 route <before>|- <seg> <after>|-     [<maxms>]    any suitable movposcomb

 route+ <as above>    change even segments owned by a train's route
 route++ <as above>   even queue changes for segments currently under a train
 !route <as above>    just do it, don't ask safety system

 movfeat <seg> <feat> <posn> [<maxms>]
 movfeat+ <as above>                           } see route+
 movfeat++ <as above>                          } see route++
 !movfeat <as above>                           } see !route

 direction <train> forwards|backwards|change

 !invert [<segpname> ...]               each one named is toggled

DIRECT NMRA AND PIC INSTRUCTIONS

                                            Example (always the same msg):
 C> !nmra [<slot>] [<nmra-command [<nmra-args>...]]    nmra speed28 3 13 1
 C> !nmra [<slot>] [=<nmra-bytes>]                     nmra =0348
 C> !nmra [<slot>] [:<nmra-bytes-with-csum>]           nmra :03484b
 C> !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
 C> !nmra <slot>
   cancels the relevant retransmission.

                                            Example (always the same msg):
 C> !pic =<pic-bytes>                                   pic =a003
 C> !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>
 do exactly the same.

======================================================================

TOPOLOGY DUMP

 D< topology segment <segment> <n_movfeats> <n_poscombs> i|n
 D< topology movfeat <segment> <feat> <posns> <weight> point|relay
 D< topology movposcomb <segment> <pname>|- \
             <posn> <dist> [-]<backwards>|- [-]<forwards>|-
 D< topology movfeatfixed <segment> <feat> <posn>