From e959f97a8cabd91fd29cea0207390ef94360e180 Mon Sep 17 00:00:00 2001 From: David Gauchard Date: Sat, 9 Dec 2023 00:32:56 +0100 Subject: [PATCH 1/7] WiFi config(): warning for legacy idioms (https://github.com/esp8266/Arduino/pull/9031#issuecomment-1839256347) --- libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h | 1 + 1 file changed, 1 insertion(+) diff --git a/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h b/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h index 62461dbaec..ab576b3fbf 100644 --- a/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h +++ b/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h @@ -49,6 +49,7 @@ class ESP8266WiFiSTAClass: public LwipIntf { // two and one parameter version. 2nd parameter is DNS like in Arduino // IPv4 only + [[deprecated("It is discouraged to use this 1 or 2 parameters network configuration legacy function config(ip[,dns]) because it sets the router (and ommited dns) to an arbitrary address")]] bool config(IPAddress local_ip, IPAddress dns = INADDR_ANY); bool setDNS(IPAddress dns1, IPAddress dns2 = INADDR_ANY); From a68b4eff33900119e3e823030f4019373b864705 Mon Sep 17 00:00:00 2001 From: David Gauchard Date: Sat, 9 Dec 2023 01:07:00 +0100 Subject: [PATCH 2/7] amend doc --- doc/esp8266wifi/station-class.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/esp8266wifi/station-class.rst b/doc/esp8266wifi/station-class.rst index 4c4bb9d5c3..82b05ef361 100644 --- a/doc/esp8266wifi/station-class.rst +++ b/doc/esp8266wifi/station-class.rst @@ -103,7 +103,7 @@ Note that to reenable DHCP, all three parameters as 0.0.0.0 (local_ip, gateway a .. code:: cpp - WiFi.config(local_ip, gateway, subnet) + WiFi.config(local_ip, gateway, subnet) (discouraged, dns is not set but it is useful) WiFi.config(local_ip, gateway, subnet, dns1) WiFi.config(local_ip, gateway, subnet, dns1, dns2) @@ -122,16 +122,16 @@ The following IP configuration may be provided: (like e.g. *www.google.co.uk*) and translate them for us to IP addresses -For Arduino networking API compatibilty the ESP8266WiFi library supports for IPv4 additional versions of the ``config`` function. +For Arduino networking API compatibility, the ESP8266WiFi library supports IPv4-only additional versions of the ``config`` function: .. code:: cpp - WiFi.config(local_ip) - WiFi.config(local_ip, dns) - WiFi.config(local_ip, dns, gateway) + WiFi.config(local_ip) (discouraged, for retro compatibility: dns=gateway=···.1) + WiFi.config(local_ip, dns) (discouraged, for retro compatibility: gateway=···.1) + WiFi.config(local_ip, dns, gateway) (discouraged, for retro compatibility: subnet/netmask quite unavoidable) WiFi.config(local_ip, dns, gateway, subnet) -Versions where some of ``dns``, ``gateway`` and ``subnet`` parameters are not specified use a default value. Default ``subnet`` is 255.255.255.0. Default ``gateway`` and ``dns`` are derived from ``local_ip`` by changing the last number to 1. To return to DHCP you can use ``WiFi.config(INADDR_NONE);``. +Versions where some of ``dns``, ``gateway`` and ``subnet`` parameters are not specified use a default value. Default ``subnet`` is 255.255.255.0. Default ``gateway`` and ``dns`` are derived from ``local_ip`` by changing the last number to 1 (discouraged). To return to DHCP you can use ``WiFi.config(INADDR_NONE);``. **Warning: The default values for dns, gateway and subnet may not match your router's settings.** Also please note, that ``config(local_ip, gateway)`` is not supported and ``WiFi.config(local_ip, gateway, subnet)`` doesn't set the DNS server IP. From 5ba81b6d5e0df42ef5ab61eab711df816bdef9d9 Mon Sep 17 00:00:00 2001 From: David Gauchard Date: Sat, 9 Dec 2023 15:33:22 +0100 Subject: [PATCH 3/7] improve comments ? --- doc/esp8266wifi/station-class.rst | 8 ++++---- libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/esp8266wifi/station-class.rst b/doc/esp8266wifi/station-class.rst index 82b05ef361..2569e217eb 100644 --- a/doc/esp8266wifi/station-class.rst +++ b/doc/esp8266wifi/station-class.rst @@ -103,7 +103,7 @@ Note that to reenable DHCP, all three parameters as 0.0.0.0 (local_ip, gateway a .. code:: cpp - WiFi.config(local_ip, gateway, subnet) (discouraged, dns is not set but it is useful) + WiFi.config(local_ip, gateway, subnet) (discouraged, insufficiently accurate, for Arduino API portability) WiFi.config(local_ip, gateway, subnet, dns1) WiFi.config(local_ip, gateway, subnet, dns1, dns2) @@ -126,9 +126,9 @@ For Arduino networking API compatibility, the ESP8266WiFi library supports IPv4- .. code:: cpp - WiFi.config(local_ip) (discouraged, for retro compatibility: dns=gateway=···.1) - WiFi.config(local_ip, dns) (discouraged, for retro compatibility: gateway=···.1) - WiFi.config(local_ip, dns, gateway) (discouraged, for retro compatibility: subnet/netmask quite unavoidable) + WiFi.config(local_ip) (discouraged, insufficiently accurate, for Arduino API portability) + WiFi.config(local_ip, dns) (discouraged, insufficiently accurate, for Arduino API portability) + WiFi.config(local_ip, dns, gateway) (discouraged, insufficiently accurate, for Arduino API portability) WiFi.config(local_ip, dns, gateway, subnet) Versions where some of ``dns``, ``gateway`` and ``subnet`` parameters are not specified use a default value. Default ``subnet`` is 255.255.255.0. Default ``gateway`` and ``dns`` are derived from ``local_ip`` by changing the last number to 1 (discouraged). To return to DHCP you can use ``WiFi.config(INADDR_NONE);``. diff --git a/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h b/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h index ab576b3fbf..12faa3dc18 100644 --- a/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h +++ b/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h @@ -49,7 +49,7 @@ class ESP8266WiFiSTAClass: public LwipIntf { // two and one parameter version. 2nd parameter is DNS like in Arduino // IPv4 only - [[deprecated("It is discouraged to use this 1 or 2 parameters network configuration legacy function config(ip[,dns]) because it sets the router (and ommited dns) to an arbitrary address")]] + [[deprecated("It is discouraged to use this 1 or 2 parameters network configuration legacy function config(ip[,dns]) because it is insufficiently accurate")]] bool config(IPAddress local_ip, IPAddress dns = INADDR_ANY); bool setDNS(IPAddress dns1, IPAddress dns2 = INADDR_ANY); From e124071b1e2455ab4a26757d4db7177a70cdbbd2 Mon Sep 17 00:00:00 2001 From: David Gauchard Date: Sat, 9 Dec 2023 16:55:30 +0100 Subject: [PATCH 4/7] ditto --- doc/esp8266wifi/station-class.rst | 4 +++- libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/esp8266wifi/station-class.rst b/doc/esp8266wifi/station-class.rst index 2569e217eb..08469d8e10 100644 --- a/doc/esp8266wifi/station-class.rst +++ b/doc/esp8266wifi/station-class.rst @@ -131,7 +131,9 @@ For Arduino networking API compatibility, the ESP8266WiFi library supports IPv4- WiFi.config(local_ip, dns, gateway) (discouraged, insufficiently accurate, for Arduino API portability) WiFi.config(local_ip, dns, gateway, subnet) -Versions where some of ``dns``, ``gateway`` and ``subnet`` parameters are not specified use a default value. Default ``subnet`` is 255.255.255.0. Default ``gateway`` and ``dns`` are derived from ``local_ip`` by changing the last number to 1 (discouraged). To return to DHCP you can use ``WiFi.config(INADDR_NONE);``. +Versions where some of ``dns``, ``gateway`` and ``subnet`` parameters are not specified use a default value. Default ``subnet`` is 255.255.255.0. Default ``gateway`` and ``dns`` are derived from ``local_ip`` by changing the last number to 1 (It is discouraged to use these default values as they may not apply to every network configuration). + +To return to DHCP you can use ``WiFi.config(INADDR_NONE);``. **Warning: The default values for dns, gateway and subnet may not match your router's settings.** Also please note, that ``config(local_ip, gateway)`` is not supported and ``WiFi.config(local_ip, gateway, subnet)`` doesn't set the DNS server IP. diff --git a/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h b/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h index 12faa3dc18..ad1b655a55 100644 --- a/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h +++ b/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.h @@ -49,7 +49,7 @@ class ESP8266WiFiSTAClass: public LwipIntf { // two and one parameter version. 2nd parameter is DNS like in Arduino // IPv4 only - [[deprecated("It is discouraged to use this 1 or 2 parameters network configuration legacy function config(ip[,dns]) because it is insufficiently accurate")]] + [[deprecated("It is discouraged to use this 1 or 2 parameters network configuration legacy function config(ip[,dns]) as chosen defaults may not match the local network configuration")]] bool config(IPAddress local_ip, IPAddress dns = INADDR_ANY); bool setDNS(IPAddress dns1, IPAddress dns2 = INADDR_ANY); From 7032cad2e71576d2b9e62d8b8044bc97f0c75274 Mon Sep 17 00:00:00 2001 From: David Gauchard Date: Sun, 10 Dec 2023 23:47:40 +0100 Subject: [PATCH 5/7] more detailed comments --- doc/esp8266wifi/station-class.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/esp8266wifi/station-class.rst b/doc/esp8266wifi/station-class.rst index 08469d8e10..30d9cf13f5 100644 --- a/doc/esp8266wifi/station-class.rst +++ b/doc/esp8266wifi/station-class.rst @@ -99,11 +99,11 @@ config Disable `DHCP `__ client (Dynamic Host Configuration Protocol) and set the IP configuration of station interface to user defined arbitrary values. The interface will be a static IP configuration instead of values provided by DHCP. -Note that to reenable DHCP, all three parameters as 0.0.0.0 (local_ip, gateway and subnet as ``INADDR_ANY``) must be passed back to config() and re-connecting is needed. +Note that to reenable DHCP, all three parameters (local_ip, gateway and subnet) as IPv4 ``0U`` (= 0.0.0.0) must be passed back to config() and re-connecting is needed. .. code:: cpp - WiFi.config(local_ip, gateway, subnet) (discouraged, insufficiently accurate, for Arduino API portability) + WiFi.config(local_ip, gateway, subnet) (for Arduino API portability, discouraged as chosen defaults may not match the local network configuration) WiFi.config(local_ip, gateway, subnet, dns1) WiFi.config(local_ip, gateway, subnet, dns1, dns2) @@ -126,14 +126,14 @@ For Arduino networking API compatibility, the ESP8266WiFi library supports IPv4- .. code:: cpp - WiFi.config(local_ip) (discouraged, insufficiently accurate, for Arduino API portability) - WiFi.config(local_ip, dns) (discouraged, insufficiently accurate, for Arduino API portability) - WiFi.config(local_ip, dns, gateway) (discouraged, insufficiently accurate, for Arduino API portability) + WiFi.config(local_ip) (for Arduino API portability, discouraged as chosen defaults may not match the local network configuration) + WiFi.config(local_ip, dns) (for Arduino API portability, discouraged as chosen defaults may not match the local network configuration) + WiFi.config(local_ip, dns, gateway) (for Arduino API portability, discouraged as chosen defaults may not match the local network configuration) WiFi.config(local_ip, dns, gateway, subnet) -Versions where some of ``dns``, ``gateway`` and ``subnet`` parameters are not specified use a default value. Default ``subnet`` is 255.255.255.0. Default ``gateway`` and ``dns`` are derived from ``local_ip`` by changing the last number to 1 (It is discouraged to use these default values as they may not apply to every network configuration). +Versions where some of ``dns``, ``gateway`` and ``subnet`` parameters are not specified use a default value. Default ``subnet`` is 255.255.255.0. Default ``gateway`` and ``dns`` are derived from ``local_ip`` by changing the last number to 1. It is discouraged to use these default values as they may not apply to every network configuration. -To return to DHCP you can use ``WiFi.config(INADDR_NONE);``. +Reminder : To reenable DHCP you can use ``WiFi.config(0U, 0U, 0U);``. **Warning: The default values for dns, gateway and subnet may not match your router's settings.** Also please note, that ``config(local_ip, gateway)`` is not supported and ``WiFi.config(local_ip, gateway, subnet)`` doesn't set the DNS server IP. From af59e953d7ba83e2907a4b176c3b345da2415261 Mon Sep 17 00:00:00 2001 From: David Gauchard Date: Sun, 10 Dec 2023 23:55:10 +0100 Subject: [PATCH 6/7] same warning for generic interface --- cores/esp8266/LwipIntfDev.h | 1 + 1 file changed, 1 insertion(+) diff --git a/cores/esp8266/LwipIntfDev.h b/cores/esp8266/LwipIntfDev.h index 7f8ae02291..baf4de6fa2 100644 --- a/cores/esp8266/LwipIntfDev.h +++ b/cores/esp8266/LwipIntfDev.h @@ -69,6 +69,7 @@ class LwipIntfDev: public LwipIntf, public RawDev const IPAddress& arg3 = IPADDR_NONE, const IPAddress& dns2 = IPADDR_NONE); // two and one parameter version. 2nd parameter is DNS like in Arduino. IPv4 only + [[deprecated("It is discouraged to use this 1 or 2 parameters network configuration legacy function config(ip[,dns]) as chosen defaults may not match the local network configuration")]] boolean config(IPAddress local_ip, IPAddress dns = INADDR_ANY); // default mac-address is inferred from esp8266's STA interface From 269b7009fa06dd3077bc9dd2642b17afd546aac2 Mon Sep 17 00:00:00 2001 From: David Gauchard Date: Sun, 10 Dec 2023 23:56:25 +0100 Subject: [PATCH 7/7] style --- cores/esp8266/LwipIntfDev.h | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/cores/esp8266/LwipIntfDev.h b/cores/esp8266/LwipIntfDev.h index baf4de6fa2..daf63e935d 100644 --- a/cores/esp8266/LwipIntfDev.h +++ b/cores/esp8266/LwipIntfDev.h @@ -69,8 +69,10 @@ class LwipIntfDev: public LwipIntf, public RawDev const IPAddress& arg3 = IPADDR_NONE, const IPAddress& dns2 = IPADDR_NONE); // two and one parameter version. 2nd parameter is DNS like in Arduino. IPv4 only - [[deprecated("It is discouraged to use this 1 or 2 parameters network configuration legacy function config(ip[,dns]) as chosen defaults may not match the local network configuration")]] - boolean config(IPAddress local_ip, IPAddress dns = INADDR_ANY); + [[deprecated("It is discouraged to use this 1 or 2 parameters network configuration legacy " + "function config(ip[,dns]) as chosen defaults may not match the local network " + "configuration")]] boolean + config(IPAddress local_ip, IPAddress dns = INADDR_ANY); // default mac-address is inferred from esp8266's STA interface boolean begin(const uint8_t* macAddress = nullptr, const uint16_t mtu = DEFAULT_MTU);