From d89dd0d1fa4a05161b5ac9955c7dd893e070f95d Mon Sep 17 00:00:00 2001
From: Asbelos <asbelos@btinternet.com>
Date: Mon, 13 Mar 2023 00:53:42 +0000
Subject: [PATCH] command ref work in progress

---
 Release_Notes/CommandRef.md | 76 +++++++++++++++++++++++--------------
 1 file changed, 48 insertions(+), 28 deletions(-)

diff --git a/Release_Notes/CommandRef.md b/Release_Notes/CommandRef.md
index 6420471..c06e388 100644
--- a/Release_Notes/CommandRef.md
+++ b/Release_Notes/CommandRef.md
@@ -4,24 +4,37 @@ General points:
   - Commands below have a single character opcode and parameters.
   Even <JA> is actually read as <J A> 
   - Keyword parameters are shown in upper case but may be entered in mixed case.
-  - value parameters are numeric.
+  - value parameters are decimal numeric (unless otherwise noted)
   - [something]  indicates its optional.
-  - Not all commands have a response, and not all responses come from the last commands that you have issued.
+  - Not all commands have a response, and broadcasts mean that not all responses come from the last commands that you have issued.
    
 Startup status
-<s>
+<s> Return status like
+    <iDCC-EX V-4.2.22 / MEGA / STANDARD_MOTOR_SHIELD G-devel-202302281422Z>
+    also returns defined turnout list:
+    <H id 1|0>   1=thrown
 
-Track power management
-<1>
-<1 MAIN|PROG|JOIN>
-<0>
-<0 MAIN|PROG>
+Track power management. After power commands a power state is broadcast to all throttles.
+
+<1>                Power on all
+<1 MAIN|PROG|JOIN> Power on MAIN or PROG track
+<1 JOIN>           Power on MAIN and PROG track but send main track data on both.
+<0>                Power off all tracks 
+<0 MAIN|PROG>      Power off main or prog track
+
+Basic manual loco control
+<t locoid speed direction>  Throttle loco. 
+    speed in JMRI-form  (-1=ESTOP, 0=STOP, 1..126 = DCC speeds 2..127)
+    direction 1=forward, 0=reverse
+    For response see broadcast <l>
+
+<F locoid function 1|0>     Set loco function 1=ON, 0-OFF
+    For response see broadcast <l>
+
+<!>  emergency stop all locos
+<T id 0|1|T|C>  Control turnout id, 0=C=Closed, 1=T=Thrown
+       response broadcast <H id 0|1>
 
-Basic manual control
-<t cab speed direction> 
-<F cab function 1|0>
-<!>
-<T id 0|1|T|C>
 
 DCC accessory control
 <a address subaddress activate [onoff]>
@@ -35,25 +48,30 @@ Note: Turnouts are best defined in myAutomation.h where a turnout description ca
 <T id VPIN vpin>
 <T id DCC addr subaddr>
 <T id DCC linearaddr>
+   Valid commands respond with <O>
+
+Outputs (Used by JMRI, not required by EXRAIL)
+<Z id vpin active>   Define an output pin that JMRI can set by id 
+<Z id activate>      Activate an output pin by id
 
 
-Outputs
-<Z id activate>
-<Z id vpin iflag>
+Sensors (Used by JMRI, not required by EXRAIL)
+<S id vpin pullup> define a sensor to be monitored.
+   Responses <Q id> and <q id> as sensor changes  
 
-Sensors 
-<S id vpin pullup>
+Decoder programming - main track
+<w cab cv value> POM write value to cv on loco
+<b cab cv bit value> POM write bit to cv on loco
 
-Decoder programming
-<w cab cv value>
-<b cab cv bit value>
-<W cabid>
-<W cv value>
-<V cv value>
-<V cv bit value>
-<R>
-<R cv>
-<B cv bit value>
+Decoder Programming - prog track
+<W cabid>  Clear consist and write new cab id (includes long/short settings)
+           Responds <W cabid> or <W -1> for error
+<W cv value> Write value to cv
+
+<V cv predictedValue> Read cv value, much faster if prediction is correct. 
+<V cv bit predictedValue>      Read CV bit
+
+<R>         Read drive-away loco id. (May be a consist id)
 <D ACK ON|OFF>
 <D ACK LIMIT|MIN|MAX|RETRY value>
 <D PROGBOOST>
@@ -152,6 +170,8 @@ Obsolete commands/formats
 <B cv bit value obsolete obsolete>
 <R cv obsolete obsolete>
 <W cv value obsolete obsolete>
+<R cv>            V command is much faster if prediction is correct.
+<B cv bit value>  V command is much faster if prediction is correct.
 
 Broadcast responses
 Note: broadcasts are sent to all throttles when appropriate (usually because something has changed)