From 7ce908549f72e91a294e95170e4ff8df0180c192 Mon Sep 17 00:00:00 2001 From: david gauchard Date: Sun, 20 Jun 2021 23:23:10 +0200 Subject: [PATCH 01/11] documentation: Arduino IDE tools menu --- boards.txt | 2 +- doc/ideoptions.rst | 204 ++++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 1 + tools/boards.txt.py | 2 +- 4 files changed, 207 insertions(+), 2 deletions(-) create mode 100644 doc/ideoptions.rst diff --git a/boards.txt b/boards.txt index 9a0a7d94ff..17bd238568 100644 --- a/boards.txt +++ b/boards.txt @@ -18,7 +18,7 @@ menu.dbg=Debug port menu.lvl=Debug Level menu.ip=lwIP Variant menu.vt=VTables -menu.exception=Exceptions +menu.exception=C++ Exceptions menu.stacksmash=Stack Protection menu.wipe=Erase Flash menu.sdk=Espressif FW diff --git a/doc/ideoptions.rst b/doc/ideoptions.rst new file mode 100644 index 0000000000..436305816a --- /dev/null +++ b/doc/ideoptions.rst @@ -0,0 +1,204 @@ +Arduino IDE: esp8266 specificities in Tools menu +================================================ + +Overview +-------- + +There are a number of specific options for esp8266 in the Arduino IDE Tools +menu. Not all of them are available for every board. If one is needed and +not visible, please try using the generic esp8266 or esp8285 board. + +Specific option list +-------------------- + +Board +~~~~~ + +Most of the time there is only one ESP8266 chip and only one ESP8285(1M) +chip shipped with hardware or DIY boards. Capabilities are the same +everywhere. Hardware differ only on routed GPIO and external components. + +If a specific hardware is not available in this list, "Generic ESP82xx" +always work. + +Upload Speed +~~~~~~~~~~~~ + +The is the serial speed setup for flashing the ESP. It is not related with +the serial speed programmed from inside the sketch, is enabled. Default +values are legacy. The highest speed option (around 1Mbaud) should always +work. Defaults can be updated using the .txt builder. + +CPU Frequency +~~~~~~~~~~~~~ + +Any ESP82xx can run at 80 or 160MHz. + +Crystal Frequency +~~~~~~~~~~~~~~~~~ + +This is the on-board crytal frequency (26 or 40Mhz). Default is 26. But +the chip was designed with 40MHz. That explains the strange 74880 default +serial baud rate at boot, which is 115200*26/40 (115200 being what everybody +uses by default nowadays). + +Flash Size +~~~~~~~~~~ + +With the Arduino core, ESP82xx can use 1MB at most to store the main sketch. + +ESP8285 have a 1MB internal flash capacity. ESP8266 are shipped with an +external flash chip that is most often 1MB(esp01, esp01s, lots of +appliances), 4MB (DIY boards like wemos/lolin D1 mini or nodemcu) or 16MB +(lolin D1 mini pro). But configuration with 2MB 8MB also exist. This core +is also able to use older 512KB chips that are today not much used and +officially deprecated by Espressif. + +Flash space is divided into 3 main zones. +The first is the user program space, 1MB at most. +The second is enough space for the OTA ability. +The third, the remaining space, can be used for a filesystem (LittleFS). + +The list propose many different configurations. In the generic board list, +the first one of each size is the default and most commonly used. + +Example: ``4MB (FS:2MB OTA:~1019KB)`` +- 4MB is the flash chip size (= 4 MBytes oddly noted 16Mbits sometimes but not here) +- ``OTA:~1019KB`` (around 1MB) is used for Over The Air flashing (note that this one can be ``gzip``-ped +- ``FS:2MB`` means that 2MBytes are used for an internal filesystem (LittleFS). + +Flash Mode +~~~~~~~~~~ + +There are four options. The most compatible and slowest is ``DOUT``. The +fasted is `QIO``. Every esp8266 is able to use any of these modes, but +depending on the flash chips capabilities and how it is connected to the +esp8266, the fastest mode may not be valid. Note that esp8285 requires the +``DOUT`` mode. +Here is some more insights about that on `esp32 forums`__. + +Reset Method +~~~~~~~~~~~~ + +On some boards (commonly NodeMCU, Lolin/Wemos) an electronic trick allows to +use the UART DTR line to reset the esp8266 *and* put it in flash mode. This +is the default ``dtr/nodemcu`` option and allows an extra easy way of +flashing. When not available, the ``no dtr`` option can be used in +conjunction with a flash button on the board (or by driving the ESP GPIO to +boot in flash mode at poweron). + +Debug Port +~~~~~~~~~~ + +There are three options: +- disabled +- Serial +- Serial1 + +When on ``Serial`` or ``Serial1`` option (see ), +messages are sent at 74880 bauds at boot time then baud rate is changed to +user configuration is sketch. These messages are generated by the internal +bootloader. After boots messages are coming either from the firmware or the +arduino core. + +Debug Level +~~~~~~~~~~~ + +There are a number of option. The first ``None`` explains itself. The last +``NoAssert - NDEBUG`` is even quieter than the first (some internal guards +are skipped). + +The other ones may be used when asked by a maintainer or if you are a +developper trying to debug some issues. + +lwIP variant +~~~~~~~~~~~~ + +`lwIP`__ is the internal network +software stack. It is highly configurable and comes with features that can +be enabled, at the price of RAM or FLASH space usage. + +There are 6 variants. As always, the first and default option is a good +compromise. Note that cores v2.x were or could be using the lwIP-v1 stack. +Only lwIP-v2 is available on core v3+. + +- ``v2 Lower Memory`` + This is lwIP-v2 with MSS=536 bytes. MSS is `Maximum Segment Size`, used + for TCP only and different from MTU which is always 1480 in our case. + Using such value for MSS is 99.9% compatible with TCP peers, allows to + store less data in RAM, and is consequently slower when transmitting + larges segments of data using TCP. + +- ``v2 Higher Bandwidth`` + + When streaming data, prefer this option. It uses more memory (MSS=1460) + so it allows faster tranfers thanks to a lower overhead between data + segments. + +- ``... (no features)`` + Disabled features to get more flash space and RAM for users are: + - No IP Forwarding (=> no NAT) + - No IP Fragmentation an reassembly + - No AutoIP (not getting 169.254.x.x on DHCP request without DHCP server) + - No SACK-OUT (= No TCP output selective acknowledgements): + no better stability with long distance TCP transfers + - No listen backlog (no protection against DOS attacks for TCP server) + +- ``IPv6 ...`` + With these options, IPv6 is enabled, with features. It uses about 20-30KB + of supplementary flash space. + +- ``VTable location`` + This is the mechanism used in C++ to support dynamic dispatch of virtual + methods. By default these tables are stored in flash to save precious RAM + bytes, but in very specific cases they can be stored in Heap space, or IRAM + space (both in RAM). + +- ``C++ Exceptions`` + - C++ exceptions are disabled by default. Consequently the ``new`` + operator will cause a general failure and a reboot when memory is full. + Note that the ``malloc`` function always returns ``nullptr`` when memory + is full. + - Enabled: on this arduino core platform, exceptions are possible but they + are quite ram and flash consuming. Worth for teaching though. + +- ``Stack protection`` + - Disabled by default + - When Enabled, the compiler generated extra code to check for stack + overflows. When this happens, an exception is raised with a message and + the ESP reboots. + +- ``Erase Flash`` + - ``Only sketch``: When WiFi is enabled at boot and persistent WiFi + credentials are enabled, these data are preserved across flashings. + Filesystem is preserved. + - ``Sketch + WiFi settings``: persistent WiFi settings are not + preserved accross flashings. Filesystem is preserved. + - ``All Flash``: WiFi settings and Filesystems are erased. + +- ``Espressif Firmware`` + There are a number of available espressif firmwares. The first / default + choice is fine. Only try with others after reading on the issue tracker + that something has to be tried with them. Note that Espressif obsoleted + all of them at the time of writing. + +- ``SSL Support`` + The first and default choice (``All SSL ciphers``) is good. The second + options enables only the main ciphers and has to be used to lower flash + usage. + +- ``MMU`` (Memory Management Unit) + Head to its `specific documentation`__. Note that there is an option + providing an additional 16KB of IRAM to your application which can be used + with ``new`` and ``malloc``. + +- ``Non-32-Bit Access`` + On esp82xx architecture, DRAM can be accessed by by byte, but not + read-only flash space (``PROGMEM`` variables) and IRAM. + By default they can only be safely accessed in a compatible way using + special macros ``pgm_read_()`` + + With the non-default option ``Byte/Word access``, an exception manager + allows to transparently use them as if they were byte-accessible. As a + result, any type of access work but in a very slow way. This mode can + also be enabled from the ``MMU`` options. diff --git a/doc/index.rst b/doc/index.rst index dcc5f69628..5f3ec247c6 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -6,6 +6,7 @@ Welcome to ESP8266 Arduino Core's documentation! :caption: Contents: Installing + Arduino IDE options Reference Libraries File system diff --git a/tools/boards.txt.py b/tools/boards.txt.py index 434a8c2723..09c9866d9a 100755 --- a/tools/boards.txt.py +++ b/tools/boards.txt.py @@ -1633,7 +1633,7 @@ def all_boards (): print('menu.lvl=Debug Level') print('menu.ip=lwIP Variant') print('menu.vt=VTables') - print('menu.exception=Exceptions') + print('menu.exception=C++ Exceptions') print('menu.stacksmash=Stack Protection') print('menu.wipe=Erase Flash') print('menu.sdk=Espressif FW') From a033e0cac7dbc15dfc24e9415ba1999218eab0a5 Mon Sep 17 00:00:00 2001 From: david gauchard Date: Mon, 21 Jun 2021 11:30:55 +0200 Subject: [PATCH 02/11] doc: update --- doc/ideoptions.rst | 136 ++++++++++++++++++++++++--------------------- 1 file changed, 72 insertions(+), 64 deletions(-) diff --git a/doc/ideoptions.rst b/doc/ideoptions.rst index 436305816a..693f93f5a6 100644 --- a/doc/ideoptions.rst +++ b/doc/ideoptions.rst @@ -8,6 +8,9 @@ There are a number of specific options for esp8266 in the Arduino IDE Tools menu. Not all of them are available for every board. If one is needed and not visible, please try using the generic esp8266 or esp8285 board. +In every menu entry, the first option is the default one and is suitable for +most users. + Specific option list -------------------- @@ -25,7 +28,7 @@ Upload Speed ~~~~~~~~~~~~ The is the serial speed setup for flashing the ESP. It is not related with -the serial speed programmed from inside the sketch, is enabled. Default +the serial speed programmed from inside the sketch, if enabled. Default values are legacy. The highest speed option (around 1Mbaud) should always work. Defaults can be updated using the .txt builder. @@ -37,44 +40,46 @@ Any ESP82xx can run at 80 or 160MHz. Crystal Frequency ~~~~~~~~~~~~~~~~~ -This is the on-board crytal frequency (26 or 40Mhz). Default is 26. But -the chip was designed with 40MHz. That explains the strange 74880 default -serial baud rate at boot, which is 115200*26/40 (115200 being what everybody +This is the on-board crystal frequency (26 or 40Mhz). Default is 26MHz. +But the chip was designed with 40MHz. That explains the default strange +74880 baud rate at boot, which is 115200*26/40 (115200 being what everybody uses by default nowadays). Flash Size ~~~~~~~~~~ -With the Arduino core, ESP82xx can use 1MB at most to store the main sketch. +With the Arduino core, ESP82xx can use at most 1MB to store the main sketch +in flash memory. -ESP8285 have a 1MB internal flash capacity. ESP8266 are shipped with an +ESP8285 has 1MB internal flash capacity. ESP8266 is always shipped with an external flash chip that is most often 1MB(esp01, esp01s, lots of appliances), 4MB (DIY boards like wemos/lolin D1 mini or nodemcu) or 16MB -(lolin D1 mini pro). But configuration with 2MB 8MB also exist. This core +(lolin D1 mini pro). But configurations with 2MB 8MB also exist. This core is also able to use older 512KB chips that are today not much used and officially deprecated by Espressif. -Flash space is divided into 3 main zones. -The first is the user program space, 1MB at most. -The second is enough space for the OTA ability. -The third, the remaining space, can be used for a filesystem (LittleFS). +Flash space is divided into 3 main zones. The first is the user program +space, 1MB at most. The second is enough space for the OTA ability. The +third, the remaining space, can be used to hold a filesystem (LittleFS). + +This list propose many different configurations. In the generic board list, +the first one of each size is the default and suitable for many cases. -The list propose many different configurations. In the generic board list, -the first one of each size is the default and most commonly used. +Example: ``4MB (FS:2MB OTA:~1019KB)``: -Example: ``4MB (FS:2MB OTA:~1019KB)`` -- 4MB is the flash chip size (= 4 MBytes oddly noted 16Mbits sometimes but not here) -- ``OTA:~1019KB`` (around 1MB) is used for Over The Air flashing (note that this one can be ``gzip``-ped +- 4MB is the flash chip size (= 4 MBytes, sometimes oddly noted 16Mbits) +- ``OTA:~1019KB`` (around 1MB) is used for Over The Air flashing (note that this one can be ``gzip``-ped) - ``FS:2MB`` means that 2MBytes are used for an internal filesystem (LittleFS). Flash Mode ~~~~~~~~~~ -There are four options. The most compatible and slowest is ``DOUT``. The -fasted is `QIO``. Every esp8266 is able to use any of these modes, but +There are four options. The most compatible and slowest is ``DOUT``. The +fasted is ``QIO``. ESP8266 mcu is able to use any of these modes, but depending on the flash chips capabilities and how it is connected to the -esp8266, the fastest mode may not be valid. Note that esp8285 requires the -``DOUT`` mode. +esp8266, the fastest mode may not be working. Note that ESP8285 requires +the ``DOUT`` mode. + Here is some more insights about that on `esp32 forums`__. Reset Method @@ -82,31 +87,32 @@ Reset Method On some boards (commonly NodeMCU, Lolin/Wemos) an electronic trick allows to use the UART DTR line to reset the esp8266 *and* put it in flash mode. This -is the default ``dtr/nodemcu`` option and allows an extra easy way of -flashing. When not available, the ``no dtr`` option can be used in -conjunction with a flash button on the board (or by driving the ESP GPIO to -boot in flash mode at poweron). +is the default ``dtr/nodemcu`` option. It provides an extra-easy way of +flashing from serial port. When not available, the ``no dtr`` option can be +used in conjunction with a flash button on the board (or by driving the ESP +dedicated GPIOs to boot in flash mode at power-on). Debug Port ~~~~~~~~~~ There are three options: + - disabled - Serial - Serial1 -When on ``Serial`` or ``Serial1`` option (see ), +When on ``Serial`` or ``Serial1`` option (see `reference`__), messages are sent at 74880 bauds at boot time then baud rate is changed to -user configuration is sketch. These messages are generated by the internal +user configuration in sketch. These messages are generated by the internal bootloader. After boots messages are coming either from the firmware or the arduino core. Debug Level ~~~~~~~~~~~ -There are a number of option. The first ``None`` explains itself. The last -``NoAssert - NDEBUG`` is even quieter than the first (some internal guards -are skipped). +There are a number of options. The first (``None``) is explained by itself. +The last ``NoAssert - NDEBUG`` is even quieter than the first (some internal +guards are skipped to save more flash). The other ones may be used when asked by a maintainer or if you are a developper trying to debug some issues. @@ -124,25 +130,27 @@ Only lwIP-v2 is available on core v3+. - ``v2 Lower Memory`` This is lwIP-v2 with MSS=536 bytes. MSS is `Maximum Segment Size`, used - for TCP only and different from MTU which is always 1480 in our case. - Using such value for MSS is 99.9% compatible with TCP peers, allows to - store less data in RAM, and is consequently slower when transmitting - larges segments of data using TCP. + for TCP only and different from MTU which is always 1480 in our case. + Using such value for MSS is 99.9% compatible with any TCP peers, allows to + store less data in RAM, and is consequently slower when transmitting large + segments of data using TCP because of a larger overhead and latency due to + smaller payload and larger number of packets. - ``v2 Higher Bandwidth`` - When streaming data, prefer this option. It uses more memory (MSS=1460) - so it allows faster tranfers thanks to a lower overhead between data - segments. + When streaming large amount of data, prefer this option. It uses more + memory (MSS=1460) so it allows faster transfers thanks to a smaller number + of packets providing lower overhead and higher bandwidth. - ``... (no features)`` Disabled features to get more flash space and RAM for users are: - - No IP Forwarding (=> no NAT) - - No IP Fragmentation an reassembly - - No AutoIP (not getting 169.254.x.x on DHCP request without DHCP server) - - No SACK-OUT (= No TCP output selective acknowledgements): - no better stability with long distance TCP transfers - - No listen backlog (no protection against DOS attacks for TCP server) + + - No IP Forwarding (=> no NAT) + - No IP Fragmentation an reassembly + - No AutoIP (not getting 169.254.x.x on DHCP request without DHCP server) + - | No SACK-OUT (= No TCP output selective acknowledgements): + no better stability with long distance TCP transfers + - No listen backlog (no protection against DOS attacks for TCP server) - ``IPv6 ...`` With these options, IPv6 is enabled, with features. It uses about 20-30KB @@ -155,26 +163,26 @@ Only lwIP-v2 is available on core v3+. space (both in RAM). - ``C++ Exceptions`` - - C++ exceptions are disabled by default. Consequently the ``new`` - operator will cause a general failure and a reboot when memory is full. - Note that the ``malloc`` function always returns ``nullptr`` when memory - is full. - - Enabled: on this arduino core platform, exceptions are possible but they - are quite ram and flash consuming. Worth for teaching though. + - | C++ exceptions are disabled by default. Consequently the ``new`` + operator will cause a general failure and a reboot when memory is full. + | Note that the C-``malloc`` function always returns ``nullptr`` when + memory is full. + - Enabled: on this arduino core platform, exceptions are possible. Note + that they are quite ram and flash consuming. - ``Stack protection`` - - Disabled by default - - When Enabled, the compiler generated extra code to check for stack - overflows. When this happens, an exception is raised with a message and - the ESP reboots. + - This is disabled by default + - When Enabled, the compiler generated extra code to check for stack + overflows. When this happens, an exception is raised with a message and + the ESP reboots. - ``Erase Flash`` - - ``Only sketch``: When WiFi is enabled at boot and persistent WiFi - credentials are enabled, these data are preserved across flashings. - Filesystem is preserved. - - ``Sketch + WiFi settings``: persistent WiFi settings are not - preserved accross flashings. Filesystem is preserved. - - ``All Flash``: WiFi settings and Filesystems are erased. + - ``Only sketch``: When WiFi is enabled at boot and persistent WiFi + credentials are enabled, these data are preserved across flashings. + Filesystem is preserved. + - ``Sketch + WiFi settings``: persistent WiFi settings are not + preserved accross flashings. Filesystem is preserved. + - ``All Flash``: WiFi settings and Filesystems are erased. - ``Espressif Firmware`` There are a number of available espressif firmwares. The first / default @@ -185,18 +193,18 @@ Only lwIP-v2 is available on core v3+. - ``SSL Support`` The first and default choice (``All SSL ciphers``) is good. The second options enables only the main ciphers and has to be used to lower flash - usage. + occupation. - ``MMU`` (Memory Management Unit) - Head to its `specific documentation`__. Note that there is an option + Head to its `specific documentation`__. Note that there is an option providing an additional 16KB of IRAM to your application which can be used with ``new`` and ``malloc``. - ``Non-32-Bit Access`` - On esp82xx architecture, DRAM can be accessed by by byte, but not - read-only flash space (``PROGMEM`` variables) and IRAM. - By default they can only be safely accessed in a compatible way using - special macros ``pgm_read_()`` + On esp82xx architecture, DRAM can be accessed byte by byte, but read-only + flash space (``PROGMEM`` variables) and IRAM cannot. By default they can + only be safely accessed in a compatible way using special macros + ``pgm_read_some()`` With the non-default option ``Byte/Word access``, an exception manager allows to transparently use them as if they were byte-accessible. As a From 2f715afe6f74f477bf22c3e7508738c9321b3a4f Mon Sep 17 00:00:00 2001 From: david gauchard Date: Mon, 21 Jun 2021 11:35:33 +0200 Subject: [PATCH 03/11] ditto --- doc/ideoptions.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/doc/ideoptions.rst b/doc/ideoptions.rst index 693f93f5a6..989dc20b2e 100644 --- a/doc/ideoptions.rst +++ b/doc/ideoptions.rst @@ -129,6 +129,7 @@ compromise. Note that cores v2.x were or could be using the lwIP-v1 stack. Only lwIP-v2 is available on core v3+. - ``v2 Lower Memory`` + This is lwIP-v2 with MSS=536 bytes. MSS is `Maximum Segment Size`, used for TCP only and different from MTU which is always 1480 in our case. Using such value for MSS is 99.9% compatible with any TCP peers, allows to @@ -143,8 +144,8 @@ Only lwIP-v2 is available on core v3+. of packets providing lower overhead and higher bandwidth. - ``... (no features)`` - Disabled features to get more flash space and RAM for users are: + Disabled features to get more flash space and RAM for users are: - No IP Forwarding (=> no NAT) - No IP Fragmentation an reassembly - No AutoIP (not getting 169.254.x.x on DHCP request without DHCP server) @@ -153,16 +154,19 @@ Only lwIP-v2 is available on core v3+. - No listen backlog (no protection against DOS attacks for TCP server) - ``IPv6 ...`` + With these options, IPv6 is enabled, with features. It uses about 20-30KB of supplementary flash space. - ``VTable location`` + This is the mechanism used in C++ to support dynamic dispatch of virtual methods. By default these tables are stored in flash to save precious RAM bytes, but in very specific cases they can be stored in Heap space, or IRAM space (both in RAM). - ``C++ Exceptions`` + - | C++ exceptions are disabled by default. Consequently the ``new`` operator will cause a general failure and a reboot when memory is full. | Note that the C-``malloc`` function always returns ``nullptr`` when @@ -171,12 +175,14 @@ Only lwIP-v2 is available on core v3+. that they are quite ram and flash consuming. - ``Stack protection`` + - This is disabled by default - When Enabled, the compiler generated extra code to check for stack overflows. When this happens, an exception is raised with a message and the ESP reboots. - ``Erase Flash`` + - ``Only sketch``: When WiFi is enabled at boot and persistent WiFi credentials are enabled, these data are preserved across flashings. Filesystem is preserved. @@ -185,22 +191,26 @@ Only lwIP-v2 is available on core v3+. - ``All Flash``: WiFi settings and Filesystems are erased. - ``Espressif Firmware`` + There are a number of available espressif firmwares. The first / default choice is fine. Only try with others after reading on the issue tracker that something has to be tried with them. Note that Espressif obsoleted all of them at the time of writing. - ``SSL Support`` + The first and default choice (``All SSL ciphers``) is good. The second options enables only the main ciphers and has to be used to lower flash occupation. - ``MMU`` (Memory Management Unit) + Head to its `specific documentation`__. Note that there is an option providing an additional 16KB of IRAM to your application which can be used with ``new`` and ``malloc``. - ``Non-32-Bit Access`` + On esp82xx architecture, DRAM can be accessed byte by byte, but read-only flash space (``PROGMEM`` variables) and IRAM cannot. By default they can only be safely accessed in a compatible way using special macros From e4a96a688c3752f7b22986477b80737233bed6a7 Mon Sep 17 00:00:00 2001 From: david gauchard Date: Mon, 21 Jun 2021 11:38:48 +0200 Subject: [PATCH 04/11] ditto --- doc/ideoptions.rst | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/doc/ideoptions.rst b/doc/ideoptions.rst index 989dc20b2e..46d8988a1a 100644 --- a/doc/ideoptions.rst +++ b/doc/ideoptions.rst @@ -146,11 +146,16 @@ Only lwIP-v2 is available on core v3+. - ``... (no features)`` Disabled features to get more flash space and RAM for users are: + - No IP Forwarding (=> no NAT) + - No IP Fragmentation an reassembly + - No AutoIP (not getting 169.254.x.x on DHCP request without DHCP server) - - | No SACK-OUT (= No TCP output selective acknowledgements): - no better stability with long distance TCP transfers + + - No SACK-OUT (= No TCP output selective acknowledgements): + | no better stability with long distance TCP transfers + - No listen backlog (no protection against DOS attacks for TCP server) - ``IPv6 ...`` @@ -167,16 +172,18 @@ Only lwIP-v2 is available on core v3+. - ``C++ Exceptions`` - - | C++ exceptions are disabled by default. Consequently the ``new`` - operator will cause a general failure and a reboot when memory is full. + - C++ exceptions are disabled by default. Consequently the ``new`` + | operator will cause a general failure and a reboot when memory is full. | Note that the C-``malloc`` function always returns ``nullptr`` when - memory is full. + | memory is full. + - Enabled: on this arduino core platform, exceptions are possible. Note that they are quite ram and flash consuming. - ``Stack protection`` - This is disabled by default + - When Enabled, the compiler generated extra code to check for stack overflows. When this happens, an exception is raised with a message and the ESP reboots. @@ -186,8 +193,10 @@ Only lwIP-v2 is available on core v3+. - ``Only sketch``: When WiFi is enabled at boot and persistent WiFi credentials are enabled, these data are preserved across flashings. Filesystem is preserved. + - ``Sketch + WiFi settings``: persistent WiFi settings are not preserved accross flashings. Filesystem is preserved. + - ``All Flash``: WiFi settings and Filesystems are erased. - ``Espressif Firmware`` From f64f96b54207f523ec3f555326a1ff46f8050bed Mon Sep 17 00:00:00 2001 From: david gauchard Date: Mon, 21 Jun 2021 11:40:49 +0200 Subject: [PATCH 05/11] ditto --- doc/ideoptions.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/doc/ideoptions.rst b/doc/ideoptions.rst index 46d8988a1a..00b937d7f9 100644 --- a/doc/ideoptions.rst +++ b/doc/ideoptions.rst @@ -153,8 +153,9 @@ Only lwIP-v2 is available on core v3+. - No AutoIP (not getting 169.254.x.x on DHCP request without DHCP server) - - No SACK-OUT (= No TCP output selective acknowledgements): - | no better stability with long distance TCP transfers + - No SACK-OUT (= No TCP output selective acknowledgements): + + no better stability with long distance TCP transfers - No listen backlog (no protection against DOS attacks for TCP server) @@ -172,10 +173,11 @@ Only lwIP-v2 is available on core v3+. - ``C++ Exceptions`` - - C++ exceptions are disabled by default. Consequently the ``new`` - | operator will cause a general failure and a reboot when memory is full. - | Note that the C-``malloc`` function always returns ``nullptr`` when - | memory is full. + - C++ exceptions are disabled by default. Consequently the ``new`` + operator will cause a general failure and a reboot when memory is full. + + Note that the C-``malloc`` function always returns ``nullptr`` when + memory is full. - Enabled: on this arduino core platform, exceptions are possible. Note that they are quite ram and flash consuming. From baa03c5241fe52da5f0e42690e3216bfc8e739ed Mon Sep 17 00:00:00 2001 From: david gauchard Date: Mon, 21 Jun 2021 11:43:39 +0200 Subject: [PATCH 06/11] ditto --- doc/ideoptions.rst | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/doc/ideoptions.rst b/doc/ideoptions.rst index 00b937d7f9..b4149bbeff 100644 --- a/doc/ideoptions.rst +++ b/doc/ideoptions.rst @@ -147,17 +147,17 @@ Only lwIP-v2 is available on core v3+. Disabled features to get more flash space and RAM for users are: - - No IP Forwarding (=> no NAT) + - No IP Forwarding (=> no NAT) - - No IP Fragmentation an reassembly + - No IP Fragmentation an reassembly - - No AutoIP (not getting 169.254.x.x on DHCP request without DHCP server) + - No AutoIP (not getting 169.254.x.x on DHCP request without DHCP server) - - No SACK-OUT (= No TCP output selective acknowledgements): + - No SACK-OUT (= No TCP output selective acknowledgements): - no better stability with long distance TCP transfers + no better stability with long distance TCP transfers - - No listen backlog (no protection against DOS attacks for TCP server) + - No listen backlog (no protection against DOS attacks for TCP server) - ``IPv6 ...`` @@ -173,33 +173,33 @@ Only lwIP-v2 is available on core v3+. - ``C++ Exceptions`` - - C++ exceptions are disabled by default. Consequently the ``new`` - operator will cause a general failure and a reboot when memory is full. + - C++ exceptions are disabled by default. Consequently the ``new`` + operator will cause a general failure and a reboot when memory is full. - Note that the C-``malloc`` function always returns ``nullptr`` when - memory is full. + Note that the C-``malloc`` function always returns ``nullptr`` when + memory is full. - - Enabled: on this arduino core platform, exceptions are possible. Note - that they are quite ram and flash consuming. + - Enabled: on this arduino core platform, exceptions are possible. Note + that they are quite ram and flash consuming. - ``Stack protection`` - - This is disabled by default + - This is disabled by default - - When Enabled, the compiler generated extra code to check for stack - overflows. When this happens, an exception is raised with a message and - the ESP reboots. + - When Enabled, the compiler generated extra code to check for stack + overflows. When this happens, an exception is raised with a message and + the ESP reboots. - ``Erase Flash`` - - ``Only sketch``: When WiFi is enabled at boot and persistent WiFi - credentials are enabled, these data are preserved across flashings. - Filesystem is preserved. + - ``Only sketch``: When WiFi is enabled at boot and persistent WiFi + credentials are enabled, these data are preserved across flashings. + Filesystem is preserved. - - ``Sketch + WiFi settings``: persistent WiFi settings are not - preserved accross flashings. Filesystem is preserved. + - ``Sketch + WiFi settings``: persistent WiFi settings are not + preserved accross flashings. Filesystem is preserved. - - ``All Flash``: WiFi settings and Filesystems are erased. + - ``All Flash``: WiFi settings and Filesystems are erased. - ``Espressif Firmware`` From 0b791e8ce2e21dceaaa9ff35c28014c46271d9a8 Mon Sep 17 00:00:00 2001 From: david gauchard Date: Mon, 21 Jun 2021 11:53:54 +0200 Subject: [PATCH 07/11] ditto --- doc/ideoptions.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/doc/ideoptions.rst b/doc/ideoptions.rst index b4149bbeff..229f51ca45 100644 --- a/doc/ideoptions.rst +++ b/doc/ideoptions.rst @@ -101,18 +101,18 @@ There are three options: - Serial - Serial1 -When on ``Serial`` or ``Serial1`` option (see `reference`__), -messages are sent at 74880 bauds at boot time then baud rate is changed to -user configuration in sketch. These messages are generated by the internal -bootloader. After boots messages are coming either from the firmware or the -arduino core. +When on ``Serial`` or ``Serial1`` option (see +`reference`__), messages are sent at 74880 bauds at +boot time then baud rate is changed to user configuration in sketch. These +messages are generated by the internal bootloader. Subsequent serial data +are coming either from the firmware, this Arduino core, user application. Debug Level ~~~~~~~~~~~ There are a number of options. The first (``None``) is explained by itself. -The last ``NoAssert - NDEBUG`` is even quieter than the first (some internal -guards are skipped to save more flash). +The last (``NoAssert - NDEBUG``) is even quieter than the first (some +internal guards are skipped to save more flash). The other ones may be used when asked by a maintainer or if you are a developper trying to debug some issues. @@ -126,7 +126,7 @@ be enabled, at the price of RAM or FLASH space usage. There are 6 variants. As always, the first and default option is a good compromise. Note that cores v2.x were or could be using the lwIP-v1 stack. -Only lwIP-v2 is available on core v3+. +Only lwIP-v2 is available on cores v3+. - ``v2 Lower Memory`` @@ -147,17 +147,17 @@ Only lwIP-v2 is available on core v3+. Disabled features to get more flash space and RAM for users are: - - No IP Forwarding (=> no NAT) + - No IP Forwarding (=> no NAT), - - No IP Fragmentation an reassembly + - No IP Fragmentation and reassembly, - - No AutoIP (not getting 169.254.x.x on DHCP request without DHCP server) + - No AutoIP (not getting 169.254.x.x on DHCP request when there is no DHCP answer), - - No SACK-OUT (= No TCP output selective acknowledgements): + - No SACK-OUT (= No TCP ``out``put ``s``elective ``ack``nowledgements): - no better stability with long distance TCP transfers + no better stability with long distance TCP transfers, - - No listen backlog (no protection against DOS attacks for TCP server) + - No listen backlog (no protection against DOS attacks for TCP server). - ``IPv6 ...`` @@ -179,8 +179,8 @@ Only lwIP-v2 is available on core v3+. Note that the C-``malloc`` function always returns ``nullptr`` when memory is full. - - Enabled: on this arduino core platform, exceptions are possible. Note - that they are quite ram and flash consuming. + - Enabled: on this Arduino core, exceptions are possible. Note that they + are quite ram and flash consuming. - ``Stack protection`` @@ -225,7 +225,7 @@ Only lwIP-v2 is available on core v3+. On esp82xx architecture, DRAM can be accessed byte by byte, but read-only flash space (``PROGMEM`` variables) and IRAM cannot. By default they can only be safely accessed in a compatible way using special macros - ``pgm_read_some()`` + ``pgm_read_some()``. With the non-default option ``Byte/Word access``, an exception manager allows to transparently use them as if they were byte-accessible. As a From cd16dab47e8324a125c8ad8cd839fe20e125c2ed Mon Sep 17 00:00:00 2001 From: david gauchard Date: Mon, 21 Jun 2021 11:56:03 +0200 Subject: [PATCH 08/11] ditto --- doc/ideoptions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/ideoptions.rst b/doc/ideoptions.rst index 229f51ca45..386f39315e 100644 --- a/doc/ideoptions.rst +++ b/doc/ideoptions.rst @@ -153,7 +153,7 @@ Only lwIP-v2 is available on cores v3+. - No AutoIP (not getting 169.254.x.x on DHCP request when there is no DHCP answer), - - No SACK-OUT (= No TCP ``out``put ``s``elective ``ack``nowledgements): + - No SACK-OUT (= no Selective ACKnowledgements for OUTput): no better stability with long distance TCP transfers, From a45d3737b133ad6294e308b8680983250d099b4c Mon Sep 17 00:00:00 2001 From: david gauchard Date: Mon, 21 Jun 2021 12:04:16 +0200 Subject: [PATCH 09/11] ditto --- doc/ideoptions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/ideoptions.rst b/doc/ideoptions.rst index 386f39315e..8a42deaf39 100644 --- a/doc/ideoptions.rst +++ b/doc/ideoptions.rst @@ -42,7 +42,7 @@ Crystal Frequency This is the on-board crystal frequency (26 or 40Mhz). Default is 26MHz. But the chip was designed with 40MHz. That explains the default strange -74880 baud rate at boot, which is 115200*26/40 (115200 being what everybody +74880 baud rate at boot, which is 115200\*26/40 (115200 being what everybody uses by default nowadays). Flash Size @@ -67,7 +67,7 @@ the first one of each size is the default and suitable for many cases. Example: ``4MB (FS:2MB OTA:~1019KB)``: -- 4MB is the flash chip size (= 4 MBytes, sometimes oddly noted 16Mbits) +- 4MB is the flash chip size (= 4 MBytes, sometimes oddly noted 32Mbits) - ``OTA:~1019KB`` (around 1MB) is used for Over The Air flashing (note that this one can be ``gzip``-ped) - ``FS:2MB`` means that 2MBytes are used for an internal filesystem (LittleFS). From 1e52a8f7f19ffdf671e337775544d1ab9943cd7e Mon Sep 17 00:00:00 2001 From: David Gauchard Date: Mon, 21 Jun 2021 16:06:27 +0200 Subject: [PATCH 10/11] updates --- doc/ideoptions.rst | 69 +++++++++++++++++++++++++--------------------- 1 file changed, 37 insertions(+), 32 deletions(-) diff --git a/doc/ideoptions.rst b/doc/ideoptions.rst index 8a42deaf39..24f4a75f89 100644 --- a/doc/ideoptions.rst +++ b/doc/ideoptions.rst @@ -9,7 +9,7 @@ menu. Not all of them are available for every board. If one is needed and not visible, please try using the generic esp8266 or esp8285 board. In every menu entry, the first option is the default one and is suitable for -most users. +most users (except for flash size in the generic ESP8266 board). Specific option list -------------------- @@ -17,9 +17,10 @@ Specific option list Board ~~~~~ -Most of the time there is only one ESP8266 chip and only one ESP8285(1M) -chip shipped with hardware or DIY boards. Capabilities are the same -everywhere. Hardware differ only on routed GPIO and external components. +Most of the time there is only one type of ESP8266 chip and only one type of +ESP8285(1M) chip shipped with hardware or DIY boards. Capabilities are the +same everywhere. Hardware devices differ only on routed GPIO and external +components. If a specific hardware is not available in this list, "Generic ESP82xx" always work. @@ -27,10 +28,11 @@ always work. Upload Speed ~~~~~~~~~~~~ -The is the serial speed setup for flashing the ESP. It is not related with -the serial speed programmed from inside the sketch, if enabled. Default +This the UART speed setup for flashing the ESP. It is not related with the +UART(Serial) speed programmed from inside the sketch, if enabled. Default values are legacy. The highest speed option (around 1Mbaud) should always -work. Defaults can be updated using the .txt builder. +work. For specific boards, defaults can be updated using the .txt +builder. CPU Frequency ~~~~~~~~~~~~~ @@ -41,9 +43,9 @@ Crystal Frequency ~~~~~~~~~~~~~~~~~ This is the on-board crystal frequency (26 or 40Mhz). Default is 26MHz. -But the chip was designed with 40MHz. That explains the default strange -74880 baud rate at boot, which is 115200\*26/40 (115200 being what everybody -uses by default nowadays). +But the chip was designed with 40MHz. It explains the default strange 74880 +baud rate at boot, which is 115200\*26/40 (115200 being quite a lot used +by default nowadays). Flash Size ~~~~~~~~~~ @@ -52,23 +54,23 @@ With the Arduino core, ESP82xx can use at most 1MB to store the main sketch in flash memory. ESP8285 has 1MB internal flash capacity. ESP8266 is always shipped with an -external flash chip that is most often 1MB(esp01, esp01s, lots of -appliances), 4MB (DIY boards like wemos/lolin D1 mini or nodemcu) or 16MB -(lolin D1 mini pro). But configurations with 2MB 8MB also exist. This core -is also able to use older 512KB chips that are today not much used and -officially deprecated by Espressif. +external flash chip that is most often 1MB (esp01, esp01s, lots of +commercial appliances), 4MB (DIY boards like wemos/lolin D1 mini or nodemcu) +or 16MB (lolin D1 mini pro). But configurations with 2MB and 8MB also +exist. This core is also able to use older 512KB chips that are today not +much used and officially deprecated by Espressif. Flash space is divided into 3 main zones. The first is the user program space, 1MB at most. The second is enough space for the OTA ability. The third, the remaining space, can be used to hold a filesystem (LittleFS). -This list propose many different configurations. In the generic board list, -the first one of each size is the default and suitable for many cases. +This list proposes many different configurations. In the generic board +list, the first one of each size is the default and suitable for many cases. Example: ``4MB (FS:2MB OTA:~1019KB)``: - 4MB is the flash chip size (= 4 MBytes, sometimes oddly noted 32Mbits) -- ``OTA:~1019KB`` (around 1MB) is used for Over The Air flashing (note that this one can be ``gzip``-ped) +- ``OTA:~1019KB`` (around 1MB) is used for Over The Air flashing (note that OTA binary can be ``gzip``-ped) - ``FS:2MB`` means that 2MBytes are used for an internal filesystem (LittleFS). Flash Mode @@ -80,7 +82,7 @@ depending on the flash chips capabilities and how it is connected to the esp8266, the fastest mode may not be working. Note that ESP8285 requires the ``DOUT`` mode. -Here is some more insights about that on `esp32 forums`__. +Here is some more insights about that in `esp32 forums`__. Reset Method ~~~~~~~~~~~~ @@ -95,17 +97,17 @@ dedicated GPIOs to boot in flash mode at power-on). Debug Port ~~~~~~~~~~ -There are three options: +There are three UART options: - disabled - Serial - Serial1 -When on ``Serial`` or ``Serial1`` option (see +When on ``Serial`` or ``Serial1`` options (see `reference`__), messages are sent at 74880 bauds at boot time then baud rate is changed to user configuration in sketch. These messages are generated by the internal bootloader. Subsequent serial data -are coming either from the firmware, this Arduino core, user application. +are coming either from the firmware, this Arduino core, and user application. Debug Level ~~~~~~~~~~~ @@ -130,13 +132,16 @@ Only lwIP-v2 is available on cores v3+. - ``v2 Lower Memory`` - This is lwIP-v2 with MSS=536 bytes. MSS is `Maximum Segment Size`, used - for TCP only and different from MTU which is always 1480 in our case. + This is lwIP-v2 with MSS=536 bytes. MSS is TCP's `Maximum Segment Size`, + and different from MTU (IP's Maximum Transfer Unit) which is always 1480 + in our case. Using such value for MSS is 99.9% compatible with any TCP peers, allows to store less data in RAM, and is consequently slower when transmitting large - segments of data using TCP because of a larger overhead and latency due to + segments of data (using TCP) because of a larger overhead and latency due to smaller payload and larger number of packets. + UDP and other IP protocols are not affected by MSS value. + - ``v2 Higher Bandwidth`` When streaming large amount of data, prefer this option. It uses more @@ -173,11 +178,11 @@ Only lwIP-v2 is available on cores v3+. - ``C++ Exceptions`` - - C++ exceptions are disabled by default. Consequently the ``new`` - operator will cause a general failure and a reboot when memory is full. + - C++ exceptions are disabled by default. Consequently the ``new`` + operator will cause a general failure and a reboot when memory is full. - Note that the C-``malloc`` function always returns ``nullptr`` when - memory is full. + Note that the C-``malloc`` function always returns ``nullptr`` when + memory is full. - Enabled: on this Arduino core, exceptions are possible. Note that they are quite ram and flash consuming. @@ -211,7 +216,7 @@ Only lwIP-v2 is available on cores v3+. - ``SSL Support`` The first and default choice (``All SSL ciphers``) is good. The second - options enables only the main ciphers and has to be used to lower flash + option enables only the main ciphers and can be used to lower flash occupation. - ``MMU`` (Memory Management Unit) @@ -229,5 +234,5 @@ Only lwIP-v2 is available on cores v3+. With the non-default option ``Byte/Word access``, an exception manager allows to transparently use them as if they were byte-accessible. As a - result, any type of access work but in a very slow way. This mode can - also be enabled from the ``MMU`` options. + result, any type of access works but in a very slow way for the usually + illegal ones. This mode can also be enabled from the ``MMU`` options. From 4cd81964b9b356c2b0621fe216c85bc5dd2a9244 Mon Sep 17 00:00:00 2001 From: David Gauchard Date: Mon, 21 Jun 2021 16:57:19 +0200 Subject: [PATCH 11/11] paragraph style fix --- doc/ideoptions.rst | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/doc/ideoptions.rst b/doc/ideoptions.rst index 24f4a75f89..ff133f44d2 100644 --- a/doc/ideoptions.rst +++ b/doc/ideoptions.rst @@ -169,14 +169,16 @@ Only lwIP-v2 is available on cores v3+. With these options, IPv6 is enabled, with features. It uses about 20-30KB of supplementary flash space. -- ``VTable location`` +``VTable location`` +~~~~~~~~~~~~~~~~~~~ This is the mechanism used in C++ to support dynamic dispatch of virtual methods. By default these tables are stored in flash to save precious RAM bytes, but in very specific cases they can be stored in Heap space, or IRAM space (both in RAM). -- ``C++ Exceptions`` +``C++ Exceptions`` +~~~~~~~~~~~~~~~~~~ - C++ exceptions are disabled by default. Consequently the ``new`` operator will cause a general failure and a reboot when memory is full. @@ -187,7 +189,8 @@ Only lwIP-v2 is available on cores v3+. - Enabled: on this Arduino core, exceptions are possible. Note that they are quite ram and flash consuming. -- ``Stack protection`` +``Stack protection`` +~~~~~~~~~~~~~~~~~~~~ - This is disabled by default @@ -195,7 +198,8 @@ Only lwIP-v2 is available on cores v3+. overflows. When this happens, an exception is raised with a message and the ESP reboots. -- ``Erase Flash`` +``Erase Flash`` +~~~~~~~~~~~~~~~ - ``Only sketch``: When WiFi is enabled at boot and persistent WiFi credentials are enabled, these data are preserved across flashings. @@ -206,26 +210,30 @@ Only lwIP-v2 is available on cores v3+. - ``All Flash``: WiFi settings and Filesystems are erased. -- ``Espressif Firmware`` +``Espressif Firmware`` +~~~~~~~~~~~~~~~~~~~~~~ There are a number of available espressif firmwares. The first / default choice is fine. Only try with others after reading on the issue tracker that something has to be tried with them. Note that Espressif obsoleted all of them at the time of writing. -- ``SSL Support`` +``SSL Support`` +~~~~~~~~~~~~~~~ The first and default choice (``All SSL ciphers``) is good. The second option enables only the main ciphers and can be used to lower flash occupation. -- ``MMU`` (Memory Management Unit) +``MMU`` (Memory Management Unit) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Head to its `specific documentation`__. Note that there is an option providing an additional 16KB of IRAM to your application which can be used with ``new`` and ``malloc``. -- ``Non-32-Bit Access`` +``Non-32-Bit Access`` +~~~~~~~~~~~~~~~~~~~~~ On esp82xx architecture, DRAM can be accessed byte by byte, but read-only flash space (``PROGMEM`` variables) and IRAM cannot. By default they can