From a3b9f6d8dff0faf0dc036810bb61618c9313690a Mon Sep 17 00:00:00 2001 From: Peter Akers Date: Sun, 17 May 2026 15:01:21 +1000 Subject: [PATCH 1/2] basic page for the new WiFi doco --- .../supported-wifi/wifi-config_v5_7.rst | 182 ++++++++++++++++++ docs/ex-commandstation/include_installer.rst | 2 +- docs/ex-commandstation/rtr-wifi-setup.rst | 2 +- docs/ex-installer/installing.rst | 2 +- 4 files changed, 185 insertions(+), 3 deletions(-) create mode 100644 docs/ex-commandstation/advanced-setup/supported-wifi/wifi-config_v5_7.rst diff --git a/docs/ex-commandstation/advanced-setup/supported-wifi/wifi-config_v5_7.rst b/docs/ex-commandstation/advanced-setup/supported-wifi/wifi-config_v5_7.rst new file mode 100644 index 0000000000..8389a3bf88 --- /dev/null +++ b/docs/ex-commandstation/advanced-setup/supported-wifi/wifi-config_v5_7.rst @@ -0,0 +1,182 @@ +:orphan: + +.. include:: /include/include.rst +.. include:: /include/include-l3.rst +.. include:: /include/include-ex-cs.rst +|EX-CS-LOGO| + +************************************ +WiFi Configuration for version 5.7+ +************************************ + +|SUITABLE| |tinkerer| |engineer| |support-button| + +.. sidebar:: + :class: sidebar-on-this-page + + .. contents:: On this page + :depth: 2 + :local: + +This page is exclusively for users of |EX-CS| version 5.7.0 and later. Version 5.7.0 is currently in the experimental / development (DEVEL) phase and is not recommended for general users. + +If you are using an earlier version, please see :doc:`WiFi Config `. + +Also see `WiFi configuration (CSB1 or ESP32 ONLY) `_ on the new web site for more technical information. + + +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 source code and recompile it for their specific WiFi settings, which could be cumbersome and error-prone. + +From version 5.7.0, config.h options for WiFi configuration in ``config.h`` ignored by CSB1 or ESP32 EX-CommandStations. + +It is now necessary to use the 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.) + +The advantage of this is that it is independent of the flashing process, and will remeber your WiFi settings across firmware updates and changes. + +You can configuring WiFi settings through: + +a) |EX-WT| (via USB), +b) |EX-TB| (via USB or over WiFi), +c) the serial monitor / device monitor of |EX-I|, the **Arduino IDE** or **VSC** (via USB) +d) any wifi throttle or app that can send the appropriate commands to the |EX-CS| over WiFi + +|EX-WT| and |EX-TB| provide a user-friendly interface for configuring WiFi settings, while the serial monitor method allows for more direct access to the configuration process but requires more technical knowledge. + +The different modes +==================== + +WiFi on the |EX-CS| has two operating modes: + +* **Access point (AP) mode** means the Command station acts as its own private WiFi network so throttle devices must connect first to the Command Station WiFi network. + +* **Station (STA) mode** means the command station connects to your WiFi router and appears as a device on that network. If the WiFi is configured for STA mode, but fails to connect to your router, it will fall back to AP mode in much the same way as smart plugs, lights etc. + +The are some additional settings that are not mode but effect the wifi connection: + +* **Hidden AP mode**: When 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. + +* **Temporary STA mode**: When enabled, the Command Station will start in Station mode and connect to an existing Wifi network. But will forget this setting the next time the |EX-CS| is restarted. + +* The **HOSTNAME** setting allows you to set the name that appears in you Throttle app, once you have connected to the appropriate network for the Command Station. + +Accessing via USB vs WiFi +========================== + +Only **Station (STA) mode** can be changed over WiFi. + +**Access Point (AP)** mode changes require a serial connection. + +Changing the settings +====================== + +EX-WebThrotttle +----------------- + +1. Connect your PC to the |EX-CS| via USB. Open the |EX-WT| and select the appropriate COM port for your |EX-CS|. You should see the current WiFi settings displayed in the interface. See :doc:`EX-WebThrottle ` for more details. + +2. Go to the ``Wifi Setup`` page from the menu or the toolbar buttons. + + - To set the **Access Point (AP) mode**, enter the SSID and password for the Command Station's WiFi network and click the :guilabel:`Set Access Point` button. You can optional set a channel for the AP mode, but it is not required, and generally not recommended. + + The Command Station will restart and create its own WiFi network with the specified SSID and password. + + To set the **Station (STA) mode**, enter the SSID and password for your existing WiFi network (eg your home router) and click the :guilabel:`Set Station Mode` button. The Command Station will attempt to connect to the specified WiFi network. If the connection is successful, it will operate in Station mode. If the connection fails, it will revert to Access Point mode. + + - To set the **Temporary Station (STA) mode**, enter the SSID and password for your existing WiFi network and click the :guilabel:`Set Temporary Station Mode` button. The Command Station will attempt to connect to the specified WiFi network. If the connection is successful, it will operate in Station mode. If the connection fails, it will revert to Access Point mode. + + - To set the **Hostname**, enter the desired hostname and click the :guilabel:`Set Hostname` button. The Command Station will update its hostname, which will be visible in your Throttle app when connected to the appropriate network. + +In every case above, the Command Station will restart to apply the new settings. You will need to reconnecting to the Command Station in the |EX-WT| interface. + +**Resetting the Wifi settings** + +The :guilabel:`Reset WiFi Settings` button on the WiFi Setup page will reset all WiFi settings to their default values. This will cause the Command Station to restart and create its own WiFi network in Access Point mode with the default SSID and password. + +---- + +EX-Toolbox +----------------- + +|EX-TB| provides a similar interface to the |EX-WT| for configuring WiFi settings, but it can be accessed either via USB or over WiFi. The process for changing WiFi settings in the |EX-TB| is essentially the same as in the |EX-WT|, with the same options for AP mode, STA mode, Temporary STA mode and Hostname. + + +1. Connect your PC to the |EX-TB| via USB or Wifi. See :doc:`EX-Toolbox ` for more details. + +2. go to the ``WiFi Setup`` page from the menu or the toolbar buttons and follow the same steps as outlined for the |EX-WT| above. + +Note: Only **Station (STA) mode** can be changed over WiFi. **Access Point (AP)** mode changes require a USB connection. + +In every case above, the Command Station will restart to apply the new settings. You will need to reconnecting to the Command Station in the |EX-TB| interface. + +---- + +EX-Installer, Arduino IDE, VSC, throttle apps +---------------------------------------------- + +The process for configuring WiFi settings using the serial monitor or device monitor on any of the EX-Installer, Arduino IDE, VSC or WiFi throttle apps are esentially the same. + +In every case below, the Command Station will restart to apply the new settings. You will need to reconnecting to the Command Station in the app's interface. + +Changing to Station Mode¶ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +i.e. your home router. You will need to issue the command: + +```cpp + +``` +e.g. Sets the STA mode to connect to a router with SSID "routerSSID" and password + +The command station will attempt to connect to this network immediately, and on each rerstart. If it fails to connect, it will revert to AP mode. + +Changing the Access Point settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To give the Access point a specific name and a password that will not be revealed on the OLED use the command: + +```cpp + +``` +e.g. Sets the AP name to "MyCSB1" and the password to "SpamWonderfulSpam": + +The AP mode password must be at least 8 characters long. + +The default channel is set to "11". If you need to use an alternate channel (we recommend using only 1,6, or 11) you may change it with the command: + +```cpp + +``` + +Use a phone WiFi analyser app to see which channels are relatively quiet in your area. + +Hidden Access Point mode +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In some environments you may want to hide the SSID from phones scanning for access points. If you do hide the SSID, it is still possible to connect by entering the SSID manually on the phone/tablet. + +```cpp + +``` + +Configuring the Host Name +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The default hostname "DCCEX" but you can change this if you have more than one CS on your network to make them show up with different names. Host names containing "DCCEX" are more readily found by WiFi throttles. + +```cpp + +``` + +e.g. Sets the hostname to "DCCEX-MYCSB1": + +Clearing WiFi settings +~~~~~~~~~~~~~~~~~~~~~~~~ + +```cpp + +``` + +WiFi will revert to the internally generated ssid and password. \ No newline at end of file diff --git a/docs/ex-commandstation/include_installer.rst b/docs/ex-commandstation/include_installer.rst index d4106dc658..f762d48493 100644 --- a/docs/ex-commandstation/include_installer.rst +++ b/docs/ex-commandstation/include_installer.rst @@ -347,7 +347,7 @@ You can configure the WiFi for EX-CommandStation two ways: .. note:: - |SUITABLE| |tinkerer| |engineer| |BR| For the |EX-CSB1-SHORT| and DIY ESP32 based Command Stations, the Experimental / Develpment (DEVEL) versions of the software from 5.7.0 ignore the WiFi configuration in the config.h file. see `WiFi configuration (CSB1 or ESP32 ONLY) `_ for more information. + |SUITABLE| |tinkerer| |engineer| |BR| For the |EX-CSB1-SHORT| and DIY ESP32 based Command Stations, the Experimental / Development (DEVEL) versions of the software from 5.7.0 ignore the WiFi configuration in the config.h file. see `WiFi configuration (CSB1 or ESP32 ONLY) `_ for more information. Use my EX-CommandStation as an Access Point diff --git a/docs/ex-commandstation/rtr-wifi-setup.rst b/docs/ex-commandstation/rtr-wifi-setup.rst index 49c8734bb6..5917c0dd14 100644 --- a/docs/ex-commandstation/rtr-wifi-setup.rst +++ b/docs/ex-commandstation/rtr-wifi-setup.rst @@ -33,7 +33,7 @@ If you wish to run trains from your phone, tablet or other |WiThrottle protocol| .. note:: - |SUITABLE| |tinkerer| |engineer| |BR| For the |EX-CSB1-SHORT| and DIY ESP32 based Command Stations, the Expermental / Develpment (DEVEL) versions of the software from 5.7.0 ignore the WiFi configuration in the config.h file. see `WiFi configuration (CSB1 or ESP32 ONLY) `_ for more information. + |SUITABLE| |tinkerer| |engineer| |BR| For the |EX-CSB1-SHORT| and DIY ESP32 based Command Stations, the Expermental / Development (DEVEL) versions of the software from 5.7.0 ignore the WiFi configuration in the config.h file. see `WiFi configuration (CSB1 or ESP32 ONLY) `_ for more information. |HR-HEAVY| diff --git a/docs/ex-installer/installing.rst b/docs/ex-installer/installing.rst index aca824c213..fc851393ab 100644 --- a/docs/ex-installer/installing.rst +++ b/docs/ex-installer/installing.rst @@ -474,7 +474,7 @@ You can configure the WiFi for **EX-CommandStation** two ways: .. note:: - |SUITABLE| |tinkerer| |engineer| |BR| For the |EX-CSB1-SHORT| and DIY ESP32 based Command Stations, the Experimental / Develpment (DEVEL) versions of the software from 5.7.0 ignore the WiFi configuration in the config.h file. see `WiFi configuration (CSB1 or ESP32 ONLY) `_ for more information. + |SUITABLE| |tinkerer| |engineer| |BR| For the |EX-CSB1-SHORT| and DIY ESP32 based Command Stations, the Experimental / Development (DEVEL) versions of the software from 5.7.0 ignore the WiFi configuration in the config.h file. see `WiFi configuration (CSB1 or ESP32 ONLY) `_ for more information. Use my EX-CommandStation as an Access Point ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 218ac35fca9d683493c61052960e753bf689d089 Mon Sep 17 00:00:00 2001 From: Peter Akers Date: Sun, 17 May 2026 15:17:50 +1000 Subject: [PATCH 2/2] Update wifi-config_v5_7.rst --- .../supported-wifi/wifi-config_v5_7.rst | 56 ++++++++++--------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/docs/ex-commandstation/advanced-setup/supported-wifi/wifi-config_v5_7.rst b/docs/ex-commandstation/advanced-setup/supported-wifi/wifi-config_v5_7.rst index 8389a3bf88..7c6e78ad4e 100644 --- a/docs/ex-commandstation/advanced-setup/supported-wifi/wifi-config_v5_7.rst +++ b/docs/ex-commandstation/advanced-setup/supported-wifi/wifi-config_v5_7.rst @@ -34,7 +34,7 @@ From version 5.7.0, config.h options for WiFi configuration in ``config.h`` igno It is now necessary to use the 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.) -The advantage of this is that it is independent of the flashing process, and will remeber your WiFi settings across firmware updates and changes. +The advantage of this is that it is independent of the flashing process, and will remember your WiFi settings across firmware updates and changes. You can configuring WiFi settings through: @@ -65,9 +65,11 @@ The are some additional settings that are not mode but effect the wifi connectio Accessing via USB vs WiFi ========================== -Only **Station (STA) mode** can be changed over WiFi. +Only **Station (STA) mode** and the **HOSTNAME** can be changed over WiFi. -**Access Point (AP)** mode changes require a serial connection. +**Access Point (AP)** mode changes require a serial/USB connection. + +---- Changing the settings ====================== @@ -105,9 +107,9 @@ EX-Toolbox 1. Connect your PC to the |EX-TB| via USB or Wifi. See :doc:`EX-Toolbox ` for more details. -2. go to the ``WiFi Setup`` page from the menu or the toolbar buttons and follow the same steps as outlined for the |EX-WT| above. +2. Go to the ``WiFi Setup`` page from the menu or the toolbar buttons and follow the same steps as outlined for the |EX-WT| above. -Note: Only **Station (STA) mode** can be changed over WiFi. **Access Point (AP)** mode changes require a USB connection. +Note: Only **Station (STA) mode** and the **HOSTNAME** can be changed over WiFi. **Access Point (AP) mode** changes require a USB connection. In every case above, the Command Station will restart to apply the new settings. You will need to reconnecting to the Command Station in the |EX-TB| interface. @@ -120,14 +122,15 @@ The process for configuring WiFi settings using the serial monitor or device mon In every case below, the Command Station will restart to apply the new settings. You will need to reconnecting to the Command Station in the app's interface. -Changing to Station Mode¶ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Changing to Station Mode +~~~~~~~~~~~~~~~~~~~~~~~~~~ i.e. your home router. You will need to issue the command: -```cpp - -``` +.. code-block:: cpp + + + e.g. Sets the STA mode to connect to a router with SSID "routerSSID" and password The command station will attempt to connect to this network immediately, and on each rerstart. If it fails to connect, it will revert to AP mode. @@ -137,18 +140,19 @@ Changing the Access Point settings To give the Access point a specific name and a password that will not be revealed on the OLED use the command: -```cpp - -``` +.. code-block:: cpp + + + e.g. Sets the AP name to "MyCSB1" and the password to "SpamWonderfulSpam": The AP mode password must be at least 8 characters long. The default channel is set to "11". If you need to use an alternate channel (we recommend using only 1,6, or 11) you may change it with the command: -```cpp - -``` +.. code-block:: cpp + + Use a phone WiFi analyser app to see which channels are relatively quiet in your area. @@ -157,26 +161,26 @@ Hidden Access Point mode In some environments you may want to hide the SSID from phones scanning for access points. If you do hide the SSID, it is still possible to connect by entering the SSID manually on the phone/tablet. -```cpp - -``` +.. code-block:: cpp + + Configuring the Host Name -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~ The default hostname "DCCEX" but you can change this if you have more than one CS on your network to make them show up with different names. Host names containing "DCCEX" are more readily found by WiFi throttles. -```cpp - -``` +.. code-block:: cpp + + e.g. Sets the hostname to "DCCEX-MYCSB1": Clearing WiFi settings ~~~~~~~~~~~~~~~~~~~~~~~~ -```cpp - -``` +.. code-block:: cpp + + WiFi will revert to the internally generated ssid and password. \ No newline at end of file