Merge branch 'sphinx' of https://github.com/flash62au/dcc-ex.github.io into sphinx

Author: flash62au

docs/_static/images/esp32/espduino-32-L298-voltage-divider.png

@@ -233,25 +233,25 @@ Numerous I/O pins are connected to other devices or perform multiple functions w
   :header-rows: 1
 
   Vpin,Pin,Digital,Analogue,PWM,Vpin,Pin,Digital,Analogue,PWM
-  800,PC10,Y,N,N,820,PC7,Y,N,N
+  800,PC10,Y,N,N,820,PC7,Y,N,Y
   801,PC12,Y,N,N,821,PA9,Y,Y,Y
-  802,PA15,Y,N,N,822,PA8,Y,N,Y
-  803,PB7,Y,N,N,823,PB10,Y,N,Y
-  804,PC15,Y,N,Y,824,PB4,Y,N,N
-  805,PC2,Y,N,Y,825,PB5,Y,N,Y
+  802,PA15,Y,N,Y,822,PA8,Y,N,Y
+  803,PB7,Y,N,Y,823,PB10,Y,N,Y
+  804,PC15,Y,N,N,824,PB4,Y,N,Y
+  805,PC2,Y,N,N,825,PB5,Y,N,Y
   806,PC3,Y,N,N,826,PB3,Y,N,Y
-  807,PC11,Y,Y,Y,827,PA10,Y,N,Y
-  808,PD2,Y,Y,Y,828,PC8,Y,N,N
-  809,PA0,Y,Y,N,829,PC6,Y,N,Y
-  810,PA1,Y,Y,Y,830,PC5,Y,Y,Y
-  811,PA4,Y,Y,N,831,PA12,Y,N,Y
-  812,PB0,Y,Y,N,832,PA11,Y,N,Y
-  813,PC1,Y,Y,N,833,PB12,Y,N,Y
-  814,PC0,Y,Y,N,834,PB2,Y,N,Y
+  807,PC11,Y,Y,N,827,PA10,Y,N,Y
+  808,PD2,Y,Y,N,828,PC8,Y,N,N
+  809,PA0,Y,Y,Y,829,PC6,Y,N,Y
+  810,PA1,Y,Y,Y,830,PC5,Y,Y,N
+  811,PA4,Y,Y,N,831,PA12,Y,N,N
+  812,PB0,Y,Y,Y,832,PA11,Y,N,Y
+  813,PC1,Y,Y,N,833,PB12,Y,N,N
+  814,PC0,Y,Y,N,834,PB2,Y,N,N
   815,PC9,Y,N,Y,835,PB1,Y,N,Y
   816,PA5,Y,N,Y,836,PB15,Y,N,Y
   817,PA6,Y,N,Y,837,PB14,Y,N,Y
-  818,PA7,Y,Y,N,838,PB13,Y,N,Y
+  818,PA7,Y,Y,Y,838,PB13,Y,N,Y
   819,PB6,Y,Y,Y,839,PC4,Y,Y,N
 
 |

docs/ex-ioexpander/supported-devices.rst

@@ -1539,6 +1539,15 @@ For a good example of this refer to :ref:`exrail/tips:realistic turnout sequence
 |_| > **description** - The description that will be assigned to the turnout/point, or |BR|
 |_| > *HIDDEN* - keyword - if used instead of the "description" the Turnout/point will not appear in the lists sent to throttle/controllers |BR|
 
+.. collapse:: For example: (click to show)
+
+  .. code-block:: cpp
+
+    TURNOUT(100, 26, 0, "Coal Yard")                  // DCC accessory turnout at linear address 101.
+    PIN_TURNOUT(101, 164, "Switching Yard")           // Pin turnout on an MCP23017 I/O expander module.
+    SERVO_TURNOUT(102, 102, 400, 100, Slow, HIDDEN)   // A servo turnout on a PCA9685 servo module that is hidden from throttles.
+    VIRTUAL_TURNOUT(103, "Lumber Yard")               // A virtual turnout which will trigger an automation sequence when CLOSE or THROW is sent.
+
 |hr-dashed|
 
 .. _ifclosed:
@@ -1609,15 +1618,6 @@ Throws a defined turnout/point.
 *Parameters:* |BR|
 |_| > **turnout_id** - The id of the turnout/point to throw |BR|
 
-.. collapse:: For example: (click to show)
-
-  .. code-block:: cpp
-
-    TURNOUT(100, 26, 0, "Coal Yard")                  // DCC accessory turnout at linear address 101.
-    PIN_TURNOUT(101, 164, "Switching Yard")           // Pin turnout on an MCP23017 I/O expander module.
-    SERVO_TURNOUT(102, 102, 400, 100, Slow, HIDDEN)   // A servo turnout on a PCA9685 servo module that is hidden from throttles.
-    VIRTUAL_TURNOUT(103, "Lumber Yard")               // A virtual turnout which will trigger an automation sequence when CLOSE or THROW is sent.
-
 |hr-dashed|
 
 .. _toggle_turnout:

docs/exrail/exrail-command-reference.rst

@@ -63,7 +63,7 @@ You can have the command references for |DCC-EX| shown through the Script Output
 
 .. rst-class:: dcclink
 
-   `DCC-EX + JMRI Custom GUI Buttons SetUp </_static/documents/DCC-EX_4.1_JMRI_Script+Button_Instructions.pdf>`_
+   `DCC-EX + JMRI Custom GUI Buttons SetUp </_static/documents/DCC-EX_4.1_JMRI_Script%20Button_Instructions.pdf>`_
 
 .. rst-class:: clearer
 

docs/reference/downloads/documents.rst

@@ -104,8 +104,8 @@ From top to bottom the pins are: `IO0`, `5V` (incorrectly labelled `IOREF` on th
   :scale: 10%
 
 
-Using an Arduino Motor Shield R3 or clone
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using an Arduino Motor Shield R3
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 To avoid damaging the ESP32's analog inputs, the `IOREF` pin on must be bent outwards or cut so it will not go into the ESPDUINO-32 socket. Then use a jumper from the `3.3v` pin to `IOREF` on the |motor shield| itself.
 
 For DCC current sensing bend or cut the `A0` and `A1` pins because by default they are connected to `GPIO2` and `GPIO4` on the ESP32 which are not useable at the same time as WiFi.
@@ -115,6 +115,27 @@ Instead, on the top of the |motor shield| connect `A0` to `A2` and `A1` to `A3`
   :alt: MotorShield configuration for ESP32
   :scale: 50%
 
+Additional information on the use of L298 Clone motor shields 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Bend the IOREF pin and jumper to the 3.3v pin, as is done for the Genuine Arduino Motor Shield R3. |BR|
+For current sensing, bend the A0 and A1 pins.  Current sensing will use A2 and A3, but clone motor shields require modifications. |BR|
+|_| > Add voltage divider resistors. |BR|
+|_| |_| Track A - - 5k/20k MAIN |BR|
+|_| |_| |_| |_| 5k - A0-A2 |BR|
+|_| |_| |_| |_| 20k - GND-A2 |BR|
+|_| |_| Track B - - 5K/20K/100K PROG |BR|
+|_| |_| |_| |_| 5k - A1-A3 |BR|
+|_| |_| |_| |_| 20k - GND-A3 |BR|
+|_| |_| |_| |_| 100k - 3v3-A3 |BR|
+|_| > The voltage divider resistor circuit is also utilizing the Schottky diodes present on pins A2 and A3 to limit ADC input voltage. |BR|
+|_| > Note:  the 100k resistor provides a voltage boost, which will result in overcurrent issues on the 
+programming track.  You can use <D PROGBOOST> to forego the 250mA trip current, or update the 
+code in MotorDriver.h
+
+.. image:: /_static/images/esp32/espduino-32-L298-voltage-divider.png
+  :alt: L298 motor shield - voltage divider resistors
+  :scale: 15%
+
 Using a |DCC-EX| EX-MotorShield8874
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -134,16 +155,17 @@ Building DCC-EX for ESP32
 
 The easiest way of building DCC-EX for the ESP32 is via EX-Installer by selecting the ESP32 option. Click here for :doc:`EX-Installer installation instructions </ex-commandstation/installer-diy>`.
 
-Adding ESP32 support to the Arduino IDE
-----------------------------------------
-
-In order to compile for the Espressif ESP32 platforms, you will need to add the board definitions to the |Arduino IDE|. To do this, follow the instructions on the `official Espressif guide <https://espressif-docs.readthedocs-hosted.com/projects/arduino-esp32/en/latest/installing.html#installing-using-arduino-ide>`_.
-
 Adding ESP32 support to VS Code and PlatformIO
 ----------------------------------------------
 
 When using VS Code and PlatformIO it will auto-configure from the entry in the platformio.ini file when you select the ESP32 target to be built.
 
-.. note::
-    The ESP32 board package version 2.0.17 is required.
+Adding ESP32 support to the Arduino IDE
+----------------------------------------
 
+In order to compile for the Espressif ESP32 platforms, you will need to add the board definitions to the |Arduino IDE|. To do this, follow the instructions on the `official Espressif guide <https://espressif-docs.readthedocs-hosted.com/projects/arduino-esp32/en/latest/installing.html#installing-using-arduino-ide>`_.
+
+.. note::
+  
+  ESP32 Espressif boards package version 2.0.17 is required. |BR|
+  Select board:  ESP32 Dev module 

docs/reference/hardware/microcontrollers/esp32.rst

@@ -367,12 +367,13 @@ From top to bottom the pins are: `IO0`, `5V` (incorrectly labelled `IOREF` on th
   :scale: 10%
 
 
-Using an Arduino Motor Shield R3 or clone
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using an Arduino Motor Shield R3
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 To avoid damaging the ESP32's analog inputs, the `IOREF` pin on must be bent outwards or cut so it will not go into the ESPDUINO-32 socket. Then use a jumper from the `3.3v` pin to `IOREF` on the |motor shield| itself.
 
-For DCC current sensing bend or cut the `A0` and `A1` pins because by default they are connected to `GPIO2` and `GPIO4` on the ESP32 which are not useable at the same time as WiFi.
-Instead, on the top of the |motor shield| connect `A0` to `A2` and `A1` to `A3` via jumpers. This will then automatically work when you select STANDARD_MOTOR_SHIELD as the MotorShield in config.h because the definition is in place when ESP32 is selected as the build target.
+For DCC current sensing bend or cut the `A0` and `A1` pins because by default they are connected to `GPIO2` and `GPIO4` on the ESP32 which are not useable at the same time as WiFi. |BR|
+Instead, on the top of the |motor shield| connect `A0` to `A2` and `A1` to `A3` via jumpers. This will then automatically work when you select STANDARD_MOTOR_SHIELD as the MotorShield in config.h because the definition is in place when ESP32 is selected as the build target. |BR|
+> Note:  L298 Clone motor shields require a voltage divider circuit.  :ref:`Link to further detail. <reference/hardware/microcontrollers/esp32:Additional information on the use of L298 Clone motor shields>`
 
 .. image:: /_static/images/esp32/espduino-32-motor-shield-fritzing.png
   :alt: MotorShield configuration for ESP32

docs/reference/hardware/microcontrollers/microcontrollers.rst

@@ -204,7 +204,8 @@ Stacking EX-MotorShield8874s
 
 This is **definitely** advanced Tinkerer/Engineer level work. Do **not** attempt it without some confidence you know what you are doing electronically. Future revisions of the EX-MotorShield8874 will look at alternative ways to expand the number of DCC districts.
 
-This article covers both stacking an Arduino Motor Shield R3 (or clone) and an EX-MotorShield8874, and stacking two EX-MotorShield8874s.
+This article covers both stacking an Arduino Motor Shield R3 and an EX-MotorShield8874, and stacking two EX-MotorShield8874s. |BR|
+> Note that L298 clone motor shields can be used on 5V Mega, etc., but require modification for use with 3.3V ESP32-WROOM and Nucleo-F4.  :ref:`Link to further detail. <reference/hardware/microcontrollers/esp32:Additional information on the use of L298 Clone motor shields>`
 
 Stacking an Arduino Motor Shield R3 and EX-MotorShield8874
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/reference/hardware/motorboards/ex-motor-shield-8874.rst

@@ -2041,7 +2041,7 @@ To monitor one or more Arduino pins for sensor triggers, first define/edit/delet
 
   *Parameters:* |BR|
   |_| > **id:** identifier of the Sensor (0-32767) (You pick the ID & they are shared between Turnouts, Sensors and Outputs) |BR|
-  |_| > **vpin:** vpin of the input to be controlled by the sensor object For Arduino input pins, this is the same as the digital pin number. For servo inputs and I/O expanders, it is the pin number defined for the HAL device (if present), for example 164-179 for pins on the first MCP23017 GPIO expander module, and 180-195 for the second MCP23017 module.|BR|
+  |_| > **vpin:** vpin of the input to be controlled by the sensor object For Arduino input pins, this is the same as the digital pin number. For servo inputs and I/O expanders, it is the pin number defined for the HAL device (if present), for example 164-179 for pins on the first MCP23017 GPIO expander module, and 180-195 for the second MCP23017 module. |BR|
   |_| > **pullup:** one of  |BR|
   |_| |_| |_| |_| • 1=Use pull-up resistor ACTIVE=LOW  |BR|
   |_| |_| |_| |_| • 0=don't use pull-up resistor ACTIVE=HIGH
@@ -2121,7 +2121,7 @@ Outputs (Configuring the EX-CommandStation)
 -------------------------------------------
 
 .. contents:: In This Section
-    :depth: 4
+    :depth: 5
     :local:
     :class: in-this-section
 
@@ -2132,7 +2132,21 @@ Definitions and state (ACTIVE/INACTIVE) for pins are retained in EEPROM and rest
 The default is to set each defined pin to active or inactive according to its restored state. 
 However, the default behaviour can be modified so that any pin can be forced to be either active or inactive upon power-up regardless of its previous state before power-down.  
 
-To have |EX-CS| utilise one or more Arduino pins as custom outputs, first define/edit/delete output definitions using the following variation of the ``<Z>`` command:  
+To have |EX-CS| utilise one or more Arduino pins as custom outputs, first define/edit/delete output definitions using the following variation of the ``<Z>`` command, or the lowercase ``<z>`` command can be used with no pre-definition required.   
+
+|hr-dashed|
+
+.. _native-command-lower-z-vpin-activate:
+
+``<z vpin> or <z -vpin>`` - Control an output pin; no setup required
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  *Parameters for the lowercase z command:* |BR|
+  |_| > **vpin:** the pin or vpin number of the output |BR|
+  |_| |_| |_| |_| • positive vpin = ACTIVE/HIGH  |BR|
+  |_| |_| |_| |_| • negative vpin = INACTIVE/LOW
+  
+  *Response:* N/A
 
 |hr-dashed|
 

docs/reference/software/command-summary-consolidated.rst

@@ -72,7 +72,7 @@ A simplified representation of what the dual (PWM) signals might look like throu
 Additional Notes
 ================
 
-This is not zero (0) stretching. We do not support the zero stretching address function, found on Digitrax and Lenz command Stations on purpose. The constant dual DCC electrical signal may damage certain types of older DC motors if left on for a long time.|BR| **So never put a DC locomotive on a DCC track.**
+This is not zero (0) stretching. We do not support the zero stretching address function, found on Digitrax and Lenz command Stations on purpose. The constant dual DCC electrical signal may damage certain types of older DC motors if left on for a long time. |BR| **So never put a DC locomotive on a DCC track.**
 
 Unlike Digitrax and Lenz 0 Zero stretching DCC (PWM) signal which leaves the engine lit up and humming loudly with the throttle and engine at 0 speed, because it is receiving a Dual DCC(PWM) aka AC signal, while the |EX-CS| TrackManager is dead quiet and at rest at 0 speed.
 

docs/trackmanager/technical-details.rst

@@ -5,6 +5,8 @@
 
 # runs only on haba's deploy:
 type -p afslog > /dev/null && afslog
+type -p klist > /dev/null && klist
+test -f `echo $KRB5CCNAME  | sed s/FILE://1` && ls -l `echo $KRB5CCNAME  | sed s/FILE://1`
 
 # here is the real start
 ##########################
@@ -18,22 +20,22 @@ fi
 
 # activate prepared venv
 . venv/bin/activate
+set -x
+while sleep 60 && touch ../run/timestamp; do
 
-while sleep 1; do
+    git fetch --dry-run 2>&1 | cut -c 26- | awk ' $2 == "->" && $1 != "gh-pages" { print "touch ../branch/"$1"/update-me"}' | bash
 
-    git fetch --dry-run 2>&1 | awk ' $4 != "" { print "touch ../branch/"$2"/update-me"}' | bash
-
-    for DIR in ../branch/*/update-me ; do
+    for DIR in `ls -d ../branch/*/update-me 2>/dev/null`  ; do
 	BRANCH=`echo $DIR | awk -F/ '{print $3}'`
 	#BRANCH=`git branch | egrep '^\*' | sed 's/. //1'`
-	git checkout "$BRANCH"
-	git pull
-	pip3 install -r requirements.txt || exit 255
-	sphinx-build -M html docs/. "../branch/$BRANCH/" -W --keep-going 2>&1 | cat > "../branch/$BRANCH/lastrun.log"
+	git checkout "$BRANCH"                                           2>&1 | cat > "../branch/$BRANCH/lastrun.log"
+	git pull                                                         2>&1 | cat >> "../branch/$BRANCH/lastrun.log"
+	pip3 install -r requirements.txt                                 2>&1 | cat >> "../branch/$BRANCH/lastrun.log"
+	sphinx-build -M html docs/. "../branch/$BRANCH/" -W --keep-going --write-all --fresh-env 2>&1 | cat >> "../branch/$BRANCH/lastrun.log"
 	rm "../branch/$BRANCH/update-me"
     done
     # still in testing, break here
-    break
+    # break
 done
 
 #deactivate venv