Keyestudio EX8874 updates

Keyestudio EX8874 updates

Author: Ash-4

docs/reference/.nav.yml

@@ -6,6 +6,7 @@ nav:
   - TrackManager: trackmanager
   - Command Station Internal Architecture: command-station-arch.md
   - Throttle Writers Guide: throttle-writers-guide.md
+  - EXRAIL Commands: ./products/ex-commandstation/exrail/command-list.md
   - Legacy Command Reference: legacy-command-reference.md
   - EX-CSB1: ex-csb1
   - ESP32: esp32

docs/reference/esp32/esp32-keyestudio.md

@@ -26,13 +26,13 @@ hide:
 
 ## Incorrect IOREF voltage
 
-The IOREF pin is labeled a `5V` on the board.
+![ACEBOTT IOREF](/_static/images/esp32/esp32-keyestudio-ioref.png){ width=15% align=left }
 
-![ACEBOTT IOREF](/_static/images/esp32/esp32-keyestudio-ioref.png){ width=15% }
+The pin in the IOREF location is 5V and labeled `5V` on the board.
 
-The IOREF voltage will not be correct for this board combination.
+EX8874 requires IOREF voltage at 3.3V when used with ESP32 or other 3.3V microprocessors.
 
-<span style="color:red">Warning:</span> Without modification the ADC inputs will receive up to 5V when the IOREF pin is 5V which will damage the board and likely destroy it. ***As such it is vital that the modifications below are made.***
+<span style="color:red">Warning:</span> Without modification the ADC inputs and I2C pins will receive up to 5V when the IOREF pin is 5V which will damage the ESP32 board and likely destroy it. ***As such it is vital that the modifications below are made.***
 
 - Option A: The prefered work-around to the incorrect 5V pin is to modify the EX8874, using the `3V3 IOREF Override` solder pad on the EX8874.
 
@@ -53,18 +53,18 @@ Note:
 Add the following lines to your `config.h` and remove any existing `#define MOTOR_SHIELD_TYPE ...` line.
 
 ```cpp
-#define EX8874_KEYES_ESP32 F("EX8874_KEYES_ESP32"),\
-  new MotorDriver(25/* 3*/, 19/*12*/, UNUSED_PIN, 13/*9*/, 32/*A0*/, 1.52, 5000, 36 /*A4*/), \
-  new MotorDriver(23/*11*/, 18/*13*/, UNUSED_PIN, 12/*8*/, 33/*A1*/, 1.52, 5000, 39 /*A5*/)
-#define MOTOR_SHIELD_TYPE EX8874_KEYES_ESP32
+  #define EX8874_KEYES_ESP32 F("EX8874_KEYES_ESP32"), \  
+    new MotorDriver(25/* 3*/, 19/*12*/, UNUSED_PIN, 13/*9*/, 32/*A0*/, 1.52, 5000, 36 /*A4*/), \  
+    new MotorDriver(23/*11*/, 18/*13*/, UNUSED_PIN, 12/*8*/, 33/*A1*/, 1.52, 5000, 39 /*A5*/)  
+  #define MOTOR_SHIELD_TYPE EX8874_KEYES_ESP32
 ```
 
 - When one EX8874 motor shield is used with Keyestudio IOT ESP32 PLUS Development Board, the default EX8874 pins are used.  
 
-|output|Current<br/>Sense|PWM<br/>Enable|DIR<br/>Signal|Brake|Fault|Notes|
+|<br/>output|Current<br/>Sense|*PWM*<br/>Enable|*DIR*<br/>Signal|<br/>Brake|<br/>Fault|<br/>Notes|
 |:--:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|
-|A|32 pA0|25 p3|19 p12|9 p9|36 pA4||
-|B|33 pA1|23 p11|18 p13|8 p8|39 pA8||
+|A|32 pA0|25 p3|19 p12|13 p9|36 pA4|Default pins|
+|B|33 pA1|23 p11|18 p13|12 p8|39 pA5||
 
 ### Single EX8874 Checklist
 
@@ -87,35 +87,39 @@ Add the following lines to your `config.h` and remove any existing `#define MOTO
 
       b. Cut the “Regulator Enable” trace on the bottom of the board
 
-      b. Use of solder pad for 8 alternate pins (not the fault pins)
+      c. Use of solder pads for 8 alternate pins (not the **Fault** pins)
             
-      c. \^ for Fault pins, the pins on the ESP32 board labeled `io2` and `io4` will need to be bent about 90 degrees so that jumpers can be put on them.  `io2` will need to be jumpered to `A4` on the EX8874. `io4` will need to be jumpered to `A5` on the EX8874.
+      d. Jumpers are required to connect **Fault** pins on the top EX8874 to `io2` and `io4` pins:  
+      &nbsp; &nbsp; \- The pins on the ESP32 board labeled `io2` and `io4` can be bent about 45 degrees to accommodate jumpers.  
+      &nbsp; &nbsp; \- Bend out pins A4 and A5 on the top EX8874.  
+      &nbsp; &nbsp; \- Jumper `io2` to `A4` on the top EX8874.  
+      &nbsp; &nbsp; \- Jumper `io4` to `A5` on the top EX8874.  
 
 See the [Stacking two motor shields on the EX8874 page](../../products/ex-motorshield8874/ex-motorshield8874.md#steps-to-stack) for details on how to alter the board for this combination.
 
 ### First EX8874
 
-|output|Current<br/>Sense|PWM<br/>Enable|DIR<br/>Signal|Brake|Fault|Notes|
+|<br/>output|Current<br/>Sense|*PWM*<br/>Enable|*DIR*<br/>Signal|<br/>Brake|<br/>Fault|<br/>Notes|
 |:--:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|
-|A|32 pA0|25 p3|19 p12|9 p9|36 pA4|Default pins|
-|B|33 pA1|23 p11|18 p13|8 p8|39 pA8||
+|A|32 pA0|25 p3|19 p12|13 p9|36 pA4|Default pins|
+|B|33 pA1|23 p11|18 p13|12 p8|39 pA5||
 
 ### Second EX8874
 
-|output|Current<br/>Sense|PWM<br/>Enable|DIR<br/>Signal|Brake|Fault|Notes|
+|<br/>output|Current<br/>Sense|*PWM*<br/>Enable|*DIR*<br/>Signal|<br/>Brake|<br/><span style="color:red">Fault|<br/>Notes|
 |:--:|:-----:|:-----:|:-----:|:-----:|:-----:|:-------------:|
-|C|34 pA2|26 p2|5 p10|14 p7|<span style="color:green">2 </span><span style="color:red">pA4</span>|use alternates for 8 pins|
-|D|35 pA3|16 p5|17 p4|27 p6|<span style="color:green">4 </span><span style="color:red">pA5</span>|\^ <span style="color:red">Bend</span> & <span style="color:green">jumper</span>. See notes|
+|C|34 pA2|26 p2|5 p10|14 p7|<span style="color:red">2 </span><span style="color:red">pA4</span>|use alternates for 8 pins|
+|D|35 pA3|16 p5|17 p4|27 p6|<span style="color:red">4 </span><span style="color:red">pA5</span>|<span style="color:red">Bend</span> & <span style="color:red">jumper</span>. See notes|
 
 - A custom motor define will be needed in `config.h`
 
 ```cpp
-#define EX8874X2_KEYES_ESP32 F("EX8874X2_KEYES_ESP32"), \
-  new MotorDriver(25/* 3*/, 19/*12*/, UNUSED_PIN, 13/*9*/, 32/*A0*/, 1.52, 5000, 36/*A4*/), \
-  new MotorDriver(23/*11*/, 18/*13*/, UNUSED_PIN, 12/*8*/, 33/*A1*/, 1.52, 5000, 39/*A5*/), \
-  new MotorDriver(26/* 2*/,  5/*10*/, UNUSED_PIN, 14/*7*/, 34/*A4*/, 1.52, 5000, 2 /*A4*/), \ 
-  new MotorDriver(16/* 5*/, 17/* 4*/, UNUSED_PIN, 27/*6*/, 35/*A5*/, 1.52, 5000, 4 /*A5*/)`
-#define MOTOR_SHIELD_TYPE EX8874X2_KEYES_ESP32`
+  #define EX8874X2_KEYES_ESP32 F("EX8874X2_KEYES_ESP32"), \  
+    new MotorDriver(25/* 3*/, 19/*12*/, UNUSED_PIN, 13/*9*/, 32/*A0*/, 1.52, 5000, 36/*A4*/), \  
+    new MotorDriver(23/*11*/, 18/*13*/, UNUSED_PIN, 12/*8*/, 33/*A1*/, 1.52, 5000, 39/*A5*/), \  
+    new MotorDriver(26/* 2*/,  5/*10*/, UNUSED_PIN, 14/*7*/, 34/*A4*/, 1.52, 5000, 2 /*A4*/), \ 
+    new MotorDriver(16/* 5*/, 17/* 4*/, UNUSED_PIN, 27/*6*/, 35/*A5*/, 1.52, 5000, 4 /*A5*/)  
+  #define MOTOR_SHIELD_TYPE EX8874X2_KEYES_ESP32
 ```
 
 ### Stacked EX8874 Checklist