Network - WiFi Station¶
.
Network details¶
Type: Network
Name: WiFi Station
Status ESP32: NORMAL
Status ESP8266: NORMAL
GitHub: _NW001_WiFi_STA.cpp
Maintainer: TD-er
Network Settings¶
Route Priority¶
(ESP32 only)
When using multiple network interfaces, like WiFi, Ethernet or PPP LTE Modem, it must be made clear which interface should be used for new connections initiated from ESPEasy to some other host.
The connected network interface with the highest Route Priority is considered to be the default route.
Default Route Priority values are:
WiFi STA = 100
Ethernet = 50
PPP (LTE modem) = 20
WiFi AP = 10
Fallback Interface¶
(ESP32 only)
Note
The concept of a Fallback Interface is available on ESP8266, but only for WiFi AP. This is a special case, which is discussed here: Network - WiFi AP .
A network interface can be marked as “Fallback Interface”.
A fallback interface will only be scheduled to start when:
A non-fallback interface failed to connect.
Route Priority changed to a value which is less than the set priority for the fallback interface.
The scheduled delay to start the fallback interface is set as “Delay Startup” (see below).
A fallback interface will be stopped when there is a default route with a route priority higher than the set Route Priority of the fallback interface.
It is possible to set multiple interfaces as Fallback Interface. The fallback order can be tweaked using the Delay Startup and Route Priority.
N.B. Network interfaces which should be started at boot, should not be marked as Fallback Interface.
Example use cases¶
Disable fallback on the WiFi AP and have it active continuously, allowing other nodes/devices to use the ESP node to act as a router/gateway using “NAPT”.
Have WiFi STA set as fallback for Ethernet (or PPP for a LTE modem). When there is no connection via Ethernet (or PPP) you can try using WiFi STA as backup.
Have PPP (for connection via LTE) as fallback, so it will only be used if any of the other interfaces failed to get a connection.
Have Ethernet set to lowest startup delay, WiFi STA as fallback with longer startup delay and PPP as fallback with the longest startup delay. This way the preferred interface is Ethernet, WiFi the second and as last resort the LTE modem.
Delay Startup¶
For various reasons, it can be useful to not immediately start a network interface at boot. For example to reduce the power consumption as most network interfaces may draw significant more power for a short time when starting.
Another use case can be to check some sensor value before deciding to either start the network interface or enter deep sleep again.
The set value (in msec) is the delay from boot before starting the network interface.
Delay Startup for Fallback Interface¶
A Fallback Interface is not started at boot. The set Delay Startup is then used as delay to schedule starting the network interface. See “Fallback Interface” for more information.
Append Name to Hostname¶
(ESP32 only)
When multiple network interfaces may connect to the same network (e.g. WiFi STA and Ethernet), it can be useful to set different hostnames per network interface.
With this option checked, the network interface name as listed on the “Network” tab overview page will be appended to the hostname as used for that network interface.
For example on an ESPEasy node called “ESPEasy”, the WiFi STA interface will then use “ESPEasy-WiFi” as hostname.
This will be used in for example DHCP requests and when using mDNS.
Default setting is to have it disabled for WiFi STA and enabled for all other network interfaces.
Block Web Access¶
When checked, the ESPEasy web interface cannot be accessed via the IP-range of the network interface.
Note
The PPP Network Interface (ESP32-only) will have this checked by default, since you typically can’t access devices from the network of the mobile provider. If this is possible for some odd reason, you very likely would never want to allow this.
Enable IPv6¶
(ESP32 only)
Checking this checkbox, will allow the network device to use IPv6.
Collect Network Stats¶
(ESP32 only, not included in all builds)
Checking this checkbox, will allow to collect network statistics like:
Connected Station Count (AP only)
RSSI (WiFi, PPP)
TX Power (WiFi STA)
BER (Bit Error Rate, only on PPP)
TX Bytes
RX Bytes
ESP-Hosted-MCU¶
(ESP32-P4 only)
Recently Espressif introduced a new concept along with the ESP32-P4. These ESP32-P4 chips do not have any RF hardware present, so they don’t support WiFi, Bluetooth or 802.15.4 (Zigbee)
This means boards with an ESP32-P4 and WiFi support do have a secondary Esp module present, like an ESP32-C6. This secondary module does run the “ESP-Hosted-MCU” firmware. In theory it should be possible to run just about any combination of ESP32-xx with an ESP32-P4, however currently only ESP32-C6 is supported even though there are ESP32-P4 boards with an ESP32-C5 being sold.
The protocol used between the processor running ESPEasy and the secondary ESP can change over time, so it is important to keep both firmware versions in sync.
ESPEasy does show information on both firmware/protocol versions on the WiFi Station config page.
For example:
ESP-Host Fw Version: 2.12.3
ESP-Hosted-MCU Fw Version: 2.12.3
ESP-Hosted-MCU Chip: ESP32-C6
MAC: E4:B3:23:A9:3F:68
Update ESP-Hosted-MCU Firmware¶
It has been made relatively easy to update the secondary ESP using the wifiotahostedmcu command.
This does not require any extra parameters. It only needs a direct connection to the internet. Either via the WiFi module itself, or via Ethernet.
This will then try to download the matching firmware version from GitHub.
Update ESP-Hosted-MCU fw. version 0.0.6¶
The ESP32-C6 is running the ESP-Hosted-MCU firmware from Espressif. Typically new boards are running version 0.0.6 of that firmware, which doesn’t yet support a lot of WiFi commands. And even worse, when trying to call unsupported commands, the whole ESP32-P4 board may crash. One of those commands not yet supported in this early version is to query the firmware version.
As soon as ESPEasy is installed on a new ESP32-P4 board and a network connection is active (with access to the internet), it is strongly adviced to run the command wifiotahostedmcu via the console. This will then install the most recent ESP-Hosted-MCU firmware matching the installed build of ESPEasy. Typically this will be the Ethernet network interface which is present on most ESP32-P4 boards.
Since the state the WiFi firmware of a freshly installed ESP32-P4 is unknown, the wifi STA adapter is set to ‘disabled’ by default. The Ethernet interface will be set active. (as long as there aren’t any new boards with a different Ethernet chip) To set the WiFi STA interface to enabled, enter the following command via the serial console:
networkenable,1
Don’t forget to save the settings using the save command, or else the network interface will be disabled again after a reboot.
This is also why WiFi STA is always index 1 and WiFi AP is index 2.
N.B. There is of course also the networkdisable command.
Wifi Credentials¶
Main WiFi credentials, stored in security.dat file.
SSID:
WPA Key:
Fallback SSID:
Fallback WPA Key:
Wifi Credentials Extra¶
(ESP32-only)
The extra credentials stored in here are stored not in the security.dat file, but in devsecurity.dat
Note
Credentials entered via the setup page are stored here (ESP32 only).
Wifi Settings¶
Passive WiFi Scan¶
There are 2 methods of scanning for access points:
Active Scan: Scan by sending a probe request.
Passive Scan: No probe request is sent out. Just switch to the specific channel and wait for a beacon.
The default scan is an active scan.
When WiFi channels 12 - 14 have to be used, but cannot be found, try to switch to use “Passive Scan”.
Note
When using hidden SSID networks, Active scan is likely the only option that will work.
WiFi IP Settings¶
Options to setup static IP for the ESP’s WiFi STA network interface.
Leave these empty to use DHCP.
ESP WiFi IP
ESP WiFi Gateway
ESP WiFi Subnetmask
ESP WiFi DNS
WiFi Mode¶
Force WiFi B/G¶
Force the WiFi to use only 802.11-B or -G protocol (not -N) Since the 802.11 G mode of the ESP is more tolerant to noise, it may improve link stability on some nodes.
WiFi Band Mode¶
(ESP32-C5 Only)
The ESP32-C5 does support both 2.4 GHz and 5 GHz Wi-Fi.
The options are:
2.4 GHz only
5 GHz only
2.4 GHz + 5 GHz
This setting limits which bands will be allowed to connect to a configured access point.
Note
Scanning both 2.4 GHz and 5 GHz bands takes longer to connect as it typically takes upto 6 seconds to scan all channels.
WiFi Power¶
Force WiFi no sleep¶
This option will set the WiFi sleep mode to no sleep. This may cause the node to consume maximum power and should only be used for testing purposes. It may even lead to more instability on nodes where the power supply is not sufficient or the extra heat cannot be dissipated.
Since changing the mode back to the default setting may lead to crashes in some core versions, this option is only enabled when starting the node. To activate a change of this setting, a reboot is required.
Max WiFi TX Power¶
(Added: 2021-01-26)
The default TX power of an ESP unit is:
802.11 b: +20 dBm
802.11 g: +17 dBm
802.11 n: +14 dBm
For some units it can help to reduce the TX power of the WiFi. As of now the exact reason why this may improve stability is a bit unclear. For example, the power supply may be slightly underdimensioned, or the antenna impedance isn’t perfect. (can be affected by a lot of factors)
The effect of a reduction in TX power is of course lower energy consumption, but also a reduction in WiFi range as the received signal strength on the access point will be lower. The unit for WiFi TX power is expressed in dBm, which makes it very easy to calculate the effect.
Note
dBm represents an absolute power level (in mWatt) while dB is a relative index. RSSI is a bit confusing in its unit of measure as both dBm and dB are used. As a rule of thumb, if the RSSI is expressed as a negative value, it is usually referring to dBm. For positive values (i.e. 0 .. 100) it is in dB. To further confuse the understanding, our ESPs use an RSSI of +31 as an error code.
The relation between TX power in dBm and Watt:
20 dBm = 0.1 Watt (= 30 mA @3.3V)
10 dBm = 0.01 Watt
0 dBm = 0.001 Watt
-10 dBm = 0.0001 Watt
Every 10 dBm lower is a factor 10 less energy sent from the antenna. N.B. Since most ESP boards use a linear voltage regulator from 5V to 3.3V, the power reduction can be as high as 0.15 Watt.
See also “WiFi Sensitivity Margin”
For example the AP does receive the signal from your ESP node with an RSSI of -60 dBm. If we lower the TX power from 20 dBm to 10 dBm, the access point will receive our signal with an RSSI of -70 dBm.
Lowering the TX power can also be useful to make it more likely a node will connect to an access point close to the node in a setup with a number of access points using the same SSID. Most access points will disconnect a node if its signal drops below a certain RSSI value. (some brands of access points allow to set this threshold)
WiFi Sensitivity Margin¶
(Added: 2021-01-26)
See also WiFi TX Power.
The ESP boards have a RX sensitivity depending on the used WiFi connection protocol:
802.11 b: –91 dbm (11 Mbps)
802.11 g: –75 dbm (54 Mbps)
802.11 n: –72 dbm (MCS7)
These are the numbers for an ESP8266.
N.B. The ESP32 is more sensitive for lower bit rates, but we use these more conservative ones.
The WiFi Sensitivity Margin is added to these RX sensitivity numbers above.
Our dynamic WiFi TX power strategy is based on the following assumptions:
Without any changes in TX power on both the ESP as well as the access point (AP), we can assume the signal strength attenuates the same from the AP to the ESP as the return path from the ESP to the AP. Meaning if we see the signal from an AP has an RSSI value of -60 dBm, we can assume the AP receiving our signal has a similar signal strength with an RSSI of -60 dBm.
An access point usually has a better RX sensitivity than an ESP board.
With these assumptions in mind, we can lower our WiFi TX power.
Let’s assume the ESP is connected to an access point using 802.11N and we see an RSSI of -60 dBm. Without lowering TX power on the ESP, the access point will receive the ESP with an RSSI of -60 dBm.
When the TX power on this ESP is lowered from 14 dBm to 4 dBm, the access point will receive the ESP with an RSSI of -70 dBm. This is still within the stated -72 dBm RX sensitivity.
However for improved stability, it is wise to add some margin. For example a margin of 5 dBm. When applying this margin of +5 dBm, the ESP must try to match its output power to make sure the access point will receive the ESP with an RSSI of at least - 67 dBm. The set TX output power will then be (-60 dBm - -67 dBm =) +7 dBm, which is still a significant improvement in power consumption.
This margin can also be used to compensate for an access point which is set to a non default TX power. For example, it is good practice to lower the TX power of an access point to improve separation and take over in a network with multiple APs set to use the same SSID to provide roaming. Since these offsets are also expressed in dBm, they can be used without conversion for correcting this margin.
Negative margin: Used for access point with better RX sensitivity (high SNR) and/or lowered TX power
Positive margin: Used for access point with lower RX sensitivity (low SNR) and/or increased TX power
Note
It is almost always a bad idea to increase TX power of an access point. The signal from the access point may cover a longer range, but the RX sensitivity is not improved thus the client can not reply. It also affects other WiFi networks in the neighborhood, causing more interference.
Note
Changing the antenna of an access point for a “High Gain Antenna” does improve TX range as well as RX sensitivity and thus cancel each other out regarding this margin setting. A high gain antenna is more directional than traditional antennas.
To get a feeling of RSSI values (in dBm) in relation to the experienced link quality:
-30 dBm: Amazing
-67 dBm: Very Good
-70 dBm: Okay
-80 dBm: Not Good
-90 dBm: Likely Unstable
Link quality depends on more then just the RSSI. For example a connection with lower band width (e.g. 802.11g compared to 802.11n) is usually more forgiving.
The actual link quality depends on the ratio between received signal strength (RSSI) and the noise floor. The noise floor is simply erroneous background transmissions that are emitted from either other devices that are too far away for the signal to be intelligible, or by devices that are inadvertently creating interference on the same frequency. Some brands of access points can show the current noise floor and/or the SNR.
For example, if a signal is received at -80 dBm and the noise floor is -100 dBm, the effective signal-to-noise ratio (SNR) is 20 dB, which is still very usable for ESP nodes as we don’t send lots of data.
For a stable link the SNR should be > 15 dB. The SNR does have big of impact on how responsive an ESPEasy node will ‘feel’ when operating it.
Sending with a very strong signal may also affect the link stability of other nodes as it will increase the noise floor for all access points in the neighborhood.
For best link stability of all nodes, it is best to target somewhere between -67 and -70 dBm. Therefore the default value of +3dB margin will attempt to let the access point receive with a signal strength of roughly that sweet spot.
Of course nodes with an already high signal attenuation cannot send with more than the max allowed TX power of roughly 20.5 dBm. Trying to reach this sweet spot in signal strength is just a best effort and not a guarantee.
Send With Max TX Power¶
With this option checked, the TX-power will not be continuously adjusted, but just set at the max. set value.
WiFi Tweaks¶
Connect Retry Attempts¶
Number of retry attempts to connect to a specific access point, before counting as ‘failed’.
Restart WiFi Lost Conn¶
Force a complete WiFi radio shutdown & restart when connection with access point is lost.
Note
This is also useful to use when there are access points in the neighborhood configured with different country code set. The actual configured country code can be seen on the WiFi scan page. (ESP32-only)
Use Last Connected AP from RTC¶
Added: 2021-06-20
The last used (stable) connection is stored in RTC memory. This will survive a reboot (and deep sleep) as long as the unit remains powered.
On WiFi reconnect, the stored last active connection is tried first. This can reduce the time needed to reconnect on a reboot, or when waking from deep sleep.
Side effect is that if a node cannot see the stronger configured AP when connecting, it may never try to connect to the stronger AP as on reconnect the last used is tried first.
Especially on mesh networks this appears to cause a lot of instability, therefore this is now made an optional feature.
This is no new functionality, as it was present before and also enabled by default.
New default value since 2021-06-20: unchecked
Enable SDK WiFi Auto Reconnect¶
Added: 2023-04-05
Some dual band access points (2.4 GHz and 5 GHz) try to balance connected nodes over these bands, based on their signal strength. This is called “Band Steering”.
WiFi clients supporting 802.11k and/or 802.11v can be redirected to another band and/or other meshed access point. Older WiFi clients, not supporting these protocols, will briefly be disconnected to force them to reconnect. Hopefully to another access point or frequency band.
The problem is that such disconnects cause issues with Espressif modules, messing up the internal state of the WiFi.
ESPEasy does act on WiFi events. But these events are not always dealt with in due time, messing up the connected state even more. In such cases, where “Band Steering” cannot be disabled, one can enable the Espressif SDK WiFi Auto Reconnect option. This will act much faster on these disconnect events. However it also seems to suppress some WiFi events.
Whenever ESPEasy calls for a disconnect, or the disconnect takes longer than such a very brief disconnect initiated by the Band Steering algorithm of the access point, ESPEasy will turn off the WiFi and turn it on again as if “Restart WiFi Lost Conn” was enabled.
Periodical send Gratuitous ARP¶
The ESP node may sometimes miss ARP broadcast packets and thus not answer them if needed. This may lead to the situation where a packet sent to the node cannot be delivered, since the switch does not know how to route the packet. To overcome this, the ESP node may send a Gratuitous ARP packet, which is essentially an answer to a request which hasn’t been made. These gratuitous ARP packets however may help the switch to remember which MAC address is connected via what port.
By default the ESP will send out such a gratuitous ARP packet every time it receives an IP address and also when it was unable to make a connection to a host. It could be the other host was replying, but the packet was not routable to the ESP node.
This Periodical send Gratuitous ARP option will send these kind of ARP packets
continuously with some interval.
This interval is defined in the source code in TIMER_GRATUITOUS_ARP_MAX (e.g. 5000 msec)
Change log¶
Changed in version 2.0: …
added Major overhaul for 2.0 release.
Added in version 1.0: …
added Initial release version.