ESPEasy/docs/source/Network/NW001.rst

.. include:: _network_substitutions.repl

.. _NW001_page:

|NW001_typename|
==================================================

|NW001_shortinfo|

Network details
---------------

Type: |NW001_type|

Name: |NW001_name|

Status ESP32: |NW001_status|

Status ESP8266: |NW001_status_lb|

GitHub: |NW001_github|_

Maintainer: |NW001_maintainer|

.. include:: Network_standard_parameters.repl

.. include:: ESP_Hosted_MCU.repl

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.



Wifi Settings
-------------

Include Hidden SSID
^^^^^^^^^^^^^^^^^^^

When checked, ESPEasy is allowed to connect to hidden SSID networks.

.. note:: Do not use channels 12 .. 14 for Hidden SSID networks as those are often not found using "Active Scan", which is needed to find hidden SSID networks.


Hidden SSID Slow Connect
^^^^^^^^^^^^^^^^^^^^^^^^

Added: 2023-11-20

Some access points with hidden SSID do not react to a broadcast connect attempt with a given SSID.
For example Mikrotik routers and access points only allow connecting to a hidden SSID when specifically addressed.
This may cause a significant slow down connecting to a hidden AP when there are lots of hidden access points with a relative strong signal.

This is enabled by default.


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
----------

.. versionchanged:: 2.0
  ...

  |added|
  Major overhaul for 2.0 release.

.. versionadded:: 1.0
  ...

  |added|
  Initial release version.

Description
-----------