EX-Toolbox updates for the WiFi setup page

Author: flash62au

docs/_static/images/ex-toolbox/wifi_setup_ap_mode.png

@@ -38,7 +38,7 @@
     # 'sphinx.ext.ifconfig',
     # 'sphinx.ext.viewcode',
     # 'sphinx.ext.graphviz',
-    'sphinx_sitemap',
+    # 'sphinx_sitemap',
     # 'sphinx.ext.inheritance_diagram',
     'sphinxcontrib.spelling',
     'sphinx_toolbox.collapse',

docs/_static/images/ex-toolbox/wifi_setup_sta_mode.png

@@ -5,9 +5,9 @@
 .. include:: /include/include-ex-cs.rst
 |EX-CS-LOGO|
 
-************************************
-WiFi Configuration for version 5.7+
-************************************
+*************************************
+WiFi Configuration for version 5.7.0+
+*************************************
 
 |SUITABLE| |tinkerer| |engineer| |support-button|
 
@@ -28,11 +28,11 @@ Also see `WiFi configuration (CSB1 or ESP32 ONLY) <https://dcc-ex.com/mkdocs-tes
 Background
 ===========
 
-Prior to version 5.7.0, WiFi configuration for |EX-CS| was done through options in the ``config.h`` file. This method required users to modify the firmware (by editing `config.h``) and recompile it for their specific WiFi settings.
+Prior to version 5.7.0, WiFi configuration for |EX-CS| was done through options in the ``config.h`` file. This method required users to modify the firmware (by editing ``config.h``) and recompile it for their specific WiFi settings.
 
 From version 5.7.0, WiFi configuration options in ``config.h`` are *ignored* by the CSB1 or ESP32 EX-CommandStations.  
 
-It is now necessary to use a new WiFi configuration method, which involves connecting to the |EX-CS| *after you have flashed the firmware.*  You do so by connecting to the |EX-CS| via USB or by connecting to the WiFi Access Point network of the CS. (Note that the WiFi Access Point network approach has limitations. See below.)
+It is now necessary to use a new WiFi configuration method, which involves connecting to the |EX-CS| *after you have flashed the firmware.*  You do so by connecting to the |EX-CS| via USB or by connecting to the WiFi Access Point network of the CS and issuing a set of new commands. (Note that the WiFi Access Point network approach has limitations. See below.)
 
 The advantage of this is that it is independent of the flashing process, and will remember your WiFi settings across firmware updates and changes.
 
@@ -56,7 +56,7 @@ WiFi on the |EX-CS| has two possible operating modes:
 
 There are some additional settings that are not modes but effect the wifi connection:
 
-* **Channel**: If you need to use an alternate channel in Access Point mode(we recommend using only 1,6, or 11) you may change it.
+* **Channel**: If you need to use an alternate channel in Access Point mode (we recommend using only 1,6, or 11) you may change it.
 
 * **Hidden AP mode**: If enabled, the Command Station's WiFi network will not be visible in the list of available networks on devices. This can enhance security by making it less obvious to potential attackers, but it also means that users will need to manually enter the network name (SSID) to connect.
 
@@ -73,6 +73,8 @@ There are some additional settings that are not modes but effect the wifi connec
 Using USB vs WiFi - Limitations of WiFi
 =========================================
 
+There are significant limitations to be aware of when configuring WiFi settings over WiFi compared to using a USB connection:
+
 Only **Station (STA) mode** and the **HOSTNAME** can be changed over WiFi.
 
 **Access Point (AP)** mode changes require a serial/USB connection. 

docs/conf.py

@@ -499,6 +499,73 @@ You can manually restart the readings with the :guilabel:`Start` button.  This w
 
 ----
 
+WiFi Setup
+=================
+
+(The WiFi Settings screen is only available when connected to EX-CommandStation version 5.7.0 and above.)
+
+Prior to version 5.7.0, WiFi configuration for |EX-CS| was done through options in the ``config.h`` file. This method required users to modify the firmware (by editing ``config.h``) and recompile it for their specific WiFi settings.
+
+From version 5.7.0, it is necessary to use a new WiFi configuration method, which involves connecting to the |EX-CS| *after you have flashed the firmware.*  You do so by connecting to the |EX-CS| via USB or by connecting to the WiFi Access Point network of the CS and issuing a set of new commands. 
+
+See the :doc:`/ex-commandstation/advanced-setup/supported-wifi/wifi-config_v5_7` page for more details.
+
+|EX-TB| provides a screen to allow you to issue the necessary commands to change the WiFi settings of your |EX-CS|.
+
+.. figure:: /_static/images/ex-toolbox/wifi_setup_sta_mode.png
+   :alt: WiFi Settings Screen - STA mode
+   :scale: 20%
+   :align: right
+
+   EX-Toolbox WiFi Settings Screen - STA Mode
+
+Station Mode
+-------------
+
+Station Mode WiFi configuration is available from the 'WiFi Setup' screen, when 'WiFi Station Mode' is selected in the drop down list at the top of the screen.
+
+The Station Mode WiFi configuration allows you to set the `SSID` and `password` of the WiFi network that your |EX-CS| will connect to, and also allows you to set the `hostname` of the |EX-CS| on that network.
+
+To change the *Station Mode* enter a `SSID` (the name of the network), and a `password` of at least 8 characters and presse either the :guilabel:`Set Station` button for a permanent change, or the :guilabel:`Set Temp` button for a temporary change.
+
+To change the *hostname* enter the hostname and press the :guilabel:`Set Hostname` button.
+
+|force-break|
+
+.. figure:: /_static/images/ex-toolbox/wifi_setup_ap_mode.png
+   :alt: WiFi Settings Screen - AP mode
+   :scale: 20%
+   :align: right
+
+   EX-Toolbox WiFi Settings Screen - AP Mode
+
+Access Point Mode
+-----------------
+
+Access Point Mode WiFi configuration is available from the 'WiFi Setup' screen, when 'WiFi Access Point Mode' is selected in the drop down list at the top of the screen.
+
+The Access Point Mode WiFi configuration allows you to set the `SSID`, `password` and optional `Channel` of the WiFi Access Point network that your |EX-CS| will create, and also allows you to set the `hostname` of the |EX-CS| on that network.
+
+.. note::
+
+   The 'Access Point' mode buttons will not become avaliable if you are connected to the |EX-CS| via WiFi, as you can't change the Access Point mode settings over WiFi.  You need to be connected via USB to change the Access Point mode settings.
+
+To change the *Access Point* enter a `SSID` (the name of the network), and a `Password` of at least 8 characters and press the :guilabel:`Set Access Point` button.
+
+To change the *hostname* enter the hostname and press the :guilabel:`Set Hostname` button.
+
+|HR-DASHED|
+
+.. note::
+
+   In every case above where you press one of the buttons, the Command Station will restart to apply the new settings. You will need to reconnect to the Command Station.
+
+See the :doc:`/ex-commandstation/advanced-setup/supported-wifi/wifi-config_v5_7` page for more details on the meaning of these settings.
+
+|force-break|
+
+----
+
 Secondary Screens
 =================