Merge pull request DCC-EX#36 from DCC-EX/sphinx

catchup

docs/about/contributing/website/structure.rst

@@ -63,6 +63,7 @@ Pages *generally* follow the basic structure:
   * `Product Icon`_ (where appropriate)
   * `Page Heading`_
   * `Comfort Level Logos`_
+  * `GitHub Issues Link`_
   * `On This Page - Table of Contents`_ (on longer pages with multiple headings)
   * `Page Content`_
     * `Page Heading <Headings and Sub Headings>`_
@@ -198,6 +199,25 @@ Refer to :ref:`about/contributing/website/basic-rst:images` below for details on
 
 ----
 
+GitHub Issues Link
+------------------
+
+It is recommended to include links to the appropriate product's GitHub issue templates by using the appropriate expansion on the same line as the comfort level expansions.
+
+* \|githublink-ex-turntable\|
+* \|githublink-ex-turntable-button\|
+* \|githublink-ex-turntable-button2\|
+* \|githublink-ex-dccinspector-button\|
+* \|githublink-ex-dccinspector-button2\|
+* \|githublink-ex-webthrottle-button\|
+* \|githublink-ex-webthrottle-button2\|
+* \|githublink-ex-installer-button\|
+* \|githublink-ex-installer-button2\|
+* \|githublink-ex-commandstation-button\|
+* \|githublink-ex-commandstation-button2\|
+
+----
+
 On This Page - Table of Contents
 --------------------------------
 

docs/about/contributing/website/style-guide.rst

@@ -120,5 +120,4 @@ Style Guidelines
   * Blank line use **\|** on its own line
   * Paragraph break that a 'float right' element must not be placed before a point use **\|force-break\|**  |br| useful if the 'float right' element is being placed beside another 'float right' element, rather than below.
 
-* To add a horizontal line, use **\-\-\-\-** (four hypens) on its own line
-* 
+* To add a horizontal line, use **\-\-\-\-** (four hypens) on its own line

docs/ex-commandstation/advanced-setup/index.rst

@@ -7,13 +7,13 @@
 Advanced Options
 ****************
 
-|tinkerer| |engineer|
+|tinkerer| |engineer| |githublink-ex-commandstation-button2|
 
 .. sidebar::
 
-    .. contents:: On this page
-        :depth: 1
-        :local:
+  .. contents:: On this page
+      :depth: 1
+      :local:
 
 These pages describe the major supported hardware options for building a |EX-CS|, along with some guidance for some of the unsupported options. They are primarily targeted at |tinkerer-text| and |engineer-text| level.  However there are some options that are suitable for a |conductor-text|.  If however, you identify as a |conductor-text| and only wish to install the recommended hardware we suggest that you look at the simplified :doc:`/ex-commandstation/get-started/index` page.
 
@@ -51,9 +51,9 @@ Whilst the Uno and Nano options are fairly popular and also relatively simple, t
 The other item of specific note is the Mega2560 + WiFi which, while appearing a good alternative to a standard Mega2560, suffers from quality control issues, and numerous users have had poor experiences getting this to function correctly. While this option is supported, it is definitely *buyer beware!*
 
 .. toctree::
-    :maxdepth: 2
-    
-    supported-microcontrollers/index
+  :maxdepth: 2
+
+  supported-microcontrollers/index
 
 
 Motor Drivers
@@ -64,9 +64,9 @@ As with microcontrollers, there is a selection of supported motor drivers to cho
 However, if you need more current than these can provide, then you need to consider the IBT_2 or IRF3205 options.
 
 .. toctree::
-    :maxdepth: 2
-    
-    /reference/hardware/motor-boards
+  :maxdepth: 2
+
+  /reference/hardware/motor-boards
 
 Connection Options
 ==================
@@ -96,28 +96,28 @@ A WiFi connection can provide this network connection, either in |Access Point M
 To use WiFi, you will need something other than an Uno or Nano with a connected WiFi shield or board. Follow the links below to understand the supported options.
 
 .. toctree::
-    :maxdepth: 2
-    
-    supported-connections/index
-    supported-wifi/index
+  :maxdepth: 2
+
+  supported-connections/index
+  supported-wifi/index
 
 Ethernet
 --------
 
 If you prefer a physical network connection, you will need an Ethernet shield or board to provide a network connection for |wiThrottle| apps or |Engine Driver| to connect to.
 
 .. toctree::
-    :maxdepth: 2
-    
-    supported-ethernet/index
+  :maxdepth: 2
+
+  supported-ethernet/index
 
 Bluetooth
 ---------
 
 .. toctree::
-    :maxdepth: 1
-    
-    /reference/hardware/bluetooth
+  :maxdepth: 1
+
+  /reference/hardware/bluetooth
 
 LCD/OLED Screens
 ================
@@ -138,9 +138,9 @@ The simplest option, requiring only a simple download, is to use |EX-I|. There a
 The Arduino IDE requires some software to be installed on your computer, however due to the flexibility this provides can be a better alternative than |EX-I|.
 
 .. toctree::
-    :maxdepth: 2
-    
-    installation-options/index
+  :maxdepth: 2
+
+  installation-options/index
 
 
 Startup Configuration
@@ -151,9 +151,9 @@ In general, modifying the startup configuration should not be required.
 However, there are occasions when the startup configuration does need modification to ensure any changed parameters persist after the |EX-CS| is shutdown or restarted. These changes are usually as a result of a conversation with the developers.
 
 .. toctree::
-    :maxdepth: 1
-    
-    startup-config
+  :maxdepth: 1
+
+  startup-config
 
 Throttle (Controller) Options
 =============================
@@ -163,16 +163,32 @@ If you wish to take your |EX-CS| experience further, then there are various diff
 These tend to be aimed more at the |tinkerer-text| and |engineer-text| levels.
 
 .. toctree::
-    :maxdepth: 2
-    
-    controllers
+  :maxdepth: 2
+
+  controllers
 
 
-DCC++ Commands
-==============
+DCC-EX Commands
+===============
 
 .. toctree::
-    :maxdepth: 1
+  :maxdepth: 1
 
-    /reference/software/command-reference
-    /reference/software/command-summary
+  /reference/software/command-reference
+  /reference/software/command-summary
+
+*Under Development:* Track Manager (formerly DC Districts)
+==========================================================
+
+.. note:: 
+
+  |NOT-IN-PROD-VERSION|
+
+  Track Manager (formerly known as DC Districts) is a new feature under development to control up to 8 tracks (or districts) with the option to run each as either a DCC main or programming track, or a DC track.
+
+  As this is under active development, changes will happen regularly, so it's best to keep up to date with any discussions via our `Discord server <https://discord.gg/PuPnNMp8Qf>`_.
+
+.. toctree:: 
+  :maxdepth: 1
+
+  track-manager

docs/ex-commandstation/advanced-setup/track-manager.rst

@@ -0,0 +1,74 @@
+.. include:: /include/include-ex-cs.rst 
+.. include:: /include/include.rst
+.. include:: /include/include-l2.rst
+|EX-CS-LOGO|
+
+**********************************
+*Under Development:* Track Manager
+**********************************
+
+|tinkerer| |engineer| |githublink-ex-commandstation-button2|
+
+.. sidebar::
+
+   .. contents:: On this page
+      :depth: 2
+      :local:
+
+.. warning:: 
+
+  This feature is under active development, meaning commands, features, and behaviour may change without notice. While we endeavour to keep these features functional, our development releases are updated regularly and we cannot guarantee there are no bugs that will have unexpected results.
+
+  If using our development release and, especially, the Track Manager feature, we highly recommend keeping in touch with conversations and developments via our `Discord server <https://discord.gg/PuPnNMp8Qf>`_.
+
+  You can also use our new GitHub issue templates to report a bug: |githublink-ex-commandstation-button2|
+
+Formerly referred to as "DC Districts", Track Manager is a new feature under active development to allow an |EX-CS| with the correct hardware and software to control up to 8 separate tracks in different modes including DCC main, DCC programming, and DC.
+
+One key item to note with DC vs. DCC is that in DCC mode, forward/reverse is determined by the DCC decoder, not the track, whereas in DC mode the direction is dependent upon the track polarity.
+
+Hardware requirements
+=====================
+
+In order to utilise Track Manager's DC mode, your motor shield must have a brake pin, and this must be defined in your "config.h" motor shield definition.
+
+If you are using a non-standard motor shield, you will need to validate if it is capable of this configuration. We will populate the list of compatible motor shields over time.
+
+If your intention is only to have multiple DCC main or programming tracks, this is not required.
+
+Track Manager commands
+======================
+
+To configure Track Manager, a new command ``<= trackletter mode [id]>`` has been added, where:
+
+* ``trackletter`` is A through H
+* ``mode`` is one of MAIN, PROG, DC, DCX, or OFF (DCX is DC with reversed polarity)
+* ``id`` is the cab ID required when specifying DC or DCX
+
+To display the current Track Manager configuration use the command ``<=>``.
+
+For example, to configure a DCC main track, a DCC programming track, a DC track (using cab ID 100), and a reversed polarity DC track (using cab ID 101), these commands are required:
+
+.. code-block:: 
+
+  <= A MAIN>
+  <= B PROG>
+  <= C DC 100>
+  <= D DCX 101>
+
+.. note:: 
+
+  When specifying a DC or DCX cab ID, be sure not to use one of your existing DCC locomotive IDs, otherwise and command sent to control a loco on that DC or DCX track will also operate your DCC loco with the same address.
+
+Note on PWM frequency
+=====================
+
+Different microcontrollers utilise different PWM frequencies, and at present, these default frequencies are in use rather than using software to define them.
+
+The side effect of these differing frequencies is that you may notice humming or sometimes squealing noises from older DC motors.
+
+The known PWM frequencies are:
+
+* Mega2560 - 122.55Hz
+* ESP32 - variable
+* Others (eg. STM32 Nucleo) - typically 1000Hz

docs/ex-commandstation/inputs-outputs/sensors/which-sensor-type.rst

@@ -80,6 +80,12 @@ Hall effect sensors consist of a hall effect device mounted between the track ra
   * - Can be used to detect a train entering or exiting a specific point on a layout (caveat being the point at which the magnet is attached)
     - Can only detect the point at which the magnet is attached, not the front/rear of a train
 
+.. note:: 
+
+  It's been observed that the reliability of hall effect sensors can be improved by connecting them to MCP23017 I/O expanders and using the interrupt capability rather than simply letting the polling cycles detect the sensor changes.
+
+  Refer to :ref:`reference/developers/hal:hal programming interface` for further information on using the interrupt pin.
+
 Block occupancy detectors
 =========================
 

docs/ex-webthrottle/index.rst

@@ -151,7 +151,7 @@ The options button lets you save labels to go on your function buttons for each
 Going Further / Developing
 ===========================
 
-If you want to really delve into how this works and help us improve it with your comments or your development skills, please contact us.
+If you want to really delve into how this works and help us improve it with your comments or your development skills, please contact us. You can also read through our :doc:`/about/contributing/webthrottle` page for info on preparing to view and contribute to the code.
 
 To load the Chrome DevTools to look at logging and be able to manually enter "write" commands for testing, click on the Menu (the 3 vertical dots in the upper right hand corner of the Chrome Window), then select "more tools" and then "Developer Tools". Or you can just hit "Ctrl-Shift-I".
 
@@ -160,4 +160,4 @@ Looking for some help with EX-WebThrottle?
 
 To raise a bug report, feature request, support request, or submit Beta test results, feel free to use our handy GitHub templates accessible by clicking this button:
 
-|githublink-ex-webthrottle-button|
+|githublink-ex-webthrottle-button|

docs/include/include-l1.rst

@@ -76,35 +76,39 @@
    :target: ../levels.html#tinkerer
 ..
 .. |engineer-no-text| image:: /_static/images/level_icons/engineer.png
-   :alt: Engineer Hat
-   :scale: 40%
-   :target: ../levels.html#engineer
+  :alt: Engineer Hat
+  :scale: 40%
+  :target: ../levels.html#engineer
 ..
 .. |conductor-text| raw:: html
 
-   <a style="font-weight: bold; font-style: italic; color: #00a3b9;" href="../levels.html#conductor">Conductor</a>
+  <a style="font-weight: bold; font-style: italic; color: #00a3b9;" href="../levels.html#conductor">Conductor</a>
 ..
 .. |tinkerer-text| raw:: html
 
-   <a style="font-weight: bold; font-style: italic; color: #00a3b9;" href="../levels.html#tinkerer">Tinkerer</a>
+  <a style="font-weight: bold; font-style: italic; color: #00a3b9;" href="../levels.html#tinkerer">Tinkerer</a>
 ..
 .. |engineer-text| raw:: html
 
-   <a style="font-weight: bold; font-style: italic; color: #00a3b9;" href="../levels.html#engineer">Engineer</a>
+  <a style="font-weight: bold; font-style: italic; color: #00a3b9;" href="../levels.html#engineer">Engineer</a>
 ..
 .. |githublink-ex-turntable-button2| raw:: html
 
-   <a href="https://github.com/DCC-EX/Turntable-EX/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../_static/images/buttons/github-bug.png" style="width: 169px;" /></a>
+  <a href="https://github.com/DCC-EX/Turntable-EX/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../_static/images/buttons/github-bug.png" style="width: 169px;" /></a>
 ..
 .. |githublink-ex-dccinspector-button2| raw:: html
 
-   <a href="https://github.com/DCC-EX/DCCInspector-EX/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../_static/images/buttons/github-bug.png" style="width: 169px;" /></a>
+  <a href="https://github.com/DCC-EX/DCCInspector-EX/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../_static/images/buttons/github-bug.png" style="width: 169px;" /></a>
 ..
 .. |githublink-ex-webthrottle-button2| raw:: html
 
-   <a href="https://github.com/DCC-EX/WebThrottle-EX/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../_static/images/buttons/github-bug.png" style="width: 169px;" /></a>
+  <a href="https://github.com/DCC-EX/WebThrottle-EX/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../_static/images/buttons/github-bug.png" style="width: 169px;" /></a>
 ..
 .. |githublink-ex-installer-button2| raw:: html
 
-   <a href="https://github.com/DCC-EX/exInstaller/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../_static/images/buttons/github-bug.png" style="width: 169px;" /></a>
+  <a href="https://github.com/DCC-EX/exInstaller/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../_static/images/buttons/github-bug.png" style="width: 169px;" /></a>
+..
+.. |githublink-ex-commandstation-button2| raw:: html
+
+  <a href="https://github.com/DCC-EX/CommandStation-EX/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../_static/images/buttons/github-bug.png" style="width: 169px;" /></a>
 ..

docs/include/include-l2.rst

@@ -110,4 +110,8 @@
 .. |githublink-ex-installer-button2| raw:: html
 
    <a href="https://github.com/DCC-EX/exInstaller/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../../_static/images/buttons/github-bug.png" style="width: 169px;" /></a>
+..
+.. |githublink-ex-commandstation-button2| raw:: html
+
+  <a href="https://github.com/DCC-EX/CommandStation-EX/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../../_static/images/buttons/github-bug.png" style="width: 169px;" /></a>
 ..

docs/include/include-l3.rst

@@ -110,4 +110,8 @@
 .. |githublink-ex-installer-button2| raw:: html
 
    <a href="https://github.com/DCC-EX/exInstaller/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../../../_static/images/buttons/github-bug.png" style="width: 169px;" /></a>
+..
+.. |githublink-ex-commandstation-button2| raw:: html
+
+  <a href="https://github.com/DCC-EX/CommandStation-EX/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../../../_static/images/buttons/github-bug.png" style="width: 169px;" /></a>
 ..

docs/include/include.rst

@@ -199,4 +199,8 @@
 .. |githublink-ex-installer-button| raw:: html
 
    <a href="https://github.com/DCC-EX/exInstaller/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../_static/images/buttons/github-bug.png" style="width: 50%; height: 50%;" /></a>
+..
+.. |githublink-ex-commandstation-button| raw:: html
+
+   <a href="https://github.com/DCC-EX/CommandStation-EX/issues/new/choose" target="_blank" title="Create a bug report, request a new feature, or request help"><img src="../_static/images/buttons/github-bug.png" style="width: 50%; height: 50%;" /></a>
 ..