Skip to content

Commit 9545952

Browse files
flash62auflash62au
authored
Merge pull request #1258 from flash62au/sphinx
basic page for the new WiFi doco
2 parents 40a0f19 + 218ac35 commit 9545952

4 files changed

Lines changed: 189 additions & 3 deletions

File tree

‎docs/ex-commandstation/advanced-setup/supported-wifi/wifi-config_v5_7.rst‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
:orphan:
2+
3+
.. include:: /include/include.rst
4+
.. include:: /include/include-l3.rst
5+
.. include:: /include/include-ex-cs.rst
6+
|EX-CS-LOGO|
7+
8+
************************************
9+
WiFi Configuration for version 5.7+
10+
************************************
11+
12+
|SUITABLE| |tinkerer| |engineer| |support-button|
13+
14+
.. sidebar::
15+
:class: sidebar-on-this-page
16+
17+
.. contents:: On this page
18+
:depth: 2
19+
:local:
20+
21+
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.
22+
23+
If you are using an earlier version, please see :doc:`WiFi Config <wifi-config>`.
24+
25+
Also see `WiFi configuration (CSB1 or ESP32 ONLY) <https://dcc-ex.com/mkdocs-test/products/ex-commandstation/config-wifi-esp32/#configuring-the-host-name>`_ on the new web site for more technical information.
26+
27+
28+
Background
29+
===========
30+
31+
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.
32+
33+
From version 5.7.0, config.h options for WiFi configuration in ``config.h`` ignored by CSB1 or ESP32 EX-CommandStations.
34+
35+
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.)
36+
37+
The advantage of this is that it is independent of the flashing process, and will remember your WiFi settings across firmware updates and changes.
38+
39+
You can configuring WiFi settings through:
40+
41+
a) |EX-WT| (via USB),
42+
b) |EX-TB| (via USB or over WiFi),
43+
c) the serial monitor / device monitor of |EX-I|, the **Arduino IDE** or **VSC** (via USB)
44+
d) any wifi throttle or app that can send the appropriate commands to the |EX-CS| over WiFi
45+
46+
|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.
47+
48+
The different modes
49+
====================
50+
51+
WiFi on the |EX-CS| has two operating modes:
52+
53+
* **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.
54+
55+
* **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.
56+
57+
The are some additional settings that are not mode but effect the wifi connection:
58+
59+
* **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.
60+
61+
* **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.
62+
63+
* 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.
64+
65+
Accessing via USB vs WiFi
66+
==========================
67+
68+
Only **Station (STA) mode** and the **HOSTNAME** can be changed over WiFi.
69+
70+
**Access Point (AP)** mode changes require a serial/USB connection.
71+
72+
----
73+
74+
Changing the settings
75+
======================
76+
77+
EX-WebThrotttle
78+
-----------------
79+
80+
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 </ex-webthrottle/index>` for more details.
81+
82+
2. Go to the ``Wifi Setup`` page from the menu or the toolbar buttons.
83+
84+
- 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.
85+
86+
The Command Station will restart and create its own WiFi network with the specified SSID and password.
87+
88+
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.
89+
90+
- 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.
91+
92+
- 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.
93+
94+
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.
95+
96+
**Resetting the Wifi settings**
97+
98+
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.
99+
100+
----
101+
102+
EX-Toolbox
103+
-----------------
104+
105+
|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.
106+
107+
108+
1. Connect your PC to the |EX-TB| via USB or Wifi. See :doc:`EX-Toolbox </ex-toolbox/using>` for more details.
109+
110+
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.
111+
112+
Note: Only **Station (STA) mode** and the **HOSTNAME** can be changed over WiFi. **Access Point (AP) mode** changes require a USB connection.
113+
114+
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.
115+
116+
----
117+
118+
EX-Installer, Arduino IDE, VSC, throttle apps
119+
----------------------------------------------
120+
121+
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.
122+
123+
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.
124+
125+
Changing to Station Mode
126+
~~~~~~~~~~~~~~~~~~~~~~~~~~
127+
128+
i.e. your home router. You will need to issue the command:
129+
130+
.. code-block:: cpp
131+
132+
<C WIFI "routerSSID" "routerPassword">
133+
134+
e.g. Sets the STA mode to connect to a router with SSID "routerSSID" and password
135+
136+
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+
138+
Changing the Access Point settings
139+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
140+
141+
To give the Access point a specific name and a password that will not be revealed on the OLED use the command:
142+
143+
.. code-block:: cpp
144+
145+
<C WIFI AP "MyCSB1" "SpamWonderfulSpam">
146+
147+
e.g. Sets the AP name to "MyCSB1" and the password to "SpamWonderfulSpam":
148+
149+
The AP mode password must be at least 8 characters long.
150+
151+
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:
152+
153+
.. code-block:: cpp
154+
155+
<C WIFI AP "MyCSB1" "SpamWonderfulSpam" 6>
156+
157+
Use a phone WiFi analyser app to see which channels are relatively quiet in your area.
158+
159+
Hidden Access Point mode
160+
~~~~~~~~~~~~~~~~~~~~~~~~~~
161+
162+
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.
163+
164+
.. code-block:: cpp
165+
166+
<C WIFI HIDDENAP "MyCSB1" "SpamWonderfulSpam" 6>
167+
168+
Configuring the Host Name
169+
~~~~~~~~~~~~~~~~~~~~~~~~~~
170+
171+
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.
172+
173+
.. code-block:: cpp
174+
175+
<C WIFI HOSTNAME "DCCEX-MYCSB1">
176+
177+
e.g. Sets the hostname to "DCCEX-MYCSB1":
178+
179+
Clearing WiFi settings
180+
~~~~~~~~~~~~~~~~~~~~~~~~
181+
182+
.. code-block:: cpp
183+
184+
<C WIFI DEFAULT>
185+
186+
WiFi will revert to the internally generated ssid and password.

‎docs/ex-commandstation/include_installer.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -347,7 +347,7 @@ You can configure the WiFi for EX-CommandStation two ways:
347347

348348
.. note::
349349

350-
|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) <https://dcc-ex.com/mkdocs-test/products/ex-commandstation/config-wifi-esp32/>`_ for more information.
350+
|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) <https://dcc-ex.com/mkdocs-test/products/ex-commandstation/config-wifi-esp32/>`_ for more information.
351351

352352

353353
Use my EX-CommandStation as an Access Point

‎docs/ex-commandstation/rtr-wifi-setup.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ If you wish to run trains from your phone, tablet or other |WiThrottle protocol|
3333

3434
.. note::
3535

36-
|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) <https://dcc-ex.com/mkdocs-test/products/ex-commandstation/config-wifi-esp32/>`_ for more information.
36+
|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) <https://dcc-ex.com/mkdocs-test/products/ex-commandstation/config-wifi-esp32/>`_ for more information.
3737

3838

3939
|HR-HEAVY|

‎docs/ex-installer/installing.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -474,7 +474,7 @@ You can configure the WiFi for **EX-CommandStation** two ways:
474474

475475
.. note::
476476

477-
|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) <https://dcc-ex.com/mkdocs-test/products/ex-commandstation/config-wifi-esp32/>`_ for more information.
477+
|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) <https://dcc-ex.com/mkdocs-test/products/ex-commandstation/config-wifi-esp32/>`_ for more information.
478478

479479
Use my EX-CommandStation as an Access Point
480480
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

0 commit comments

Comments
 (0)