Documentation: Arduino IDE specific options for esp82xx (#8154)

boards.txt

@@ -19,7 +19,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

doc/ideoptions.rst

@@ -0,0 +1,246 @@
+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.
+
+In every menu entry, the first option is the default one and is suitable for
+most users (except for flash size in the generic ESP8266 board).
+
+Specific option list
+--------------------
+
+Board
+~~~~~
+
+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.
+
+Upload Speed
+~~~~~~~~~~~~
+
+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.  For specific boards, defaults can be updated using the <boards>.txt
+builder.
+
+CPU Frequency
+~~~~~~~~~~~~~
+
+Any ESP82xx can run at 80 or 160MHz.
+
+Crystal Frequency
+~~~~~~~~~~~~~~~~~
+
+This is the on-board crystal frequency (26 or 40Mhz).  Default is 26MHz. 
+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
+~~~~~~~~~~
+
+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
+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 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 OTA binary 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``.  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 working.  Note that ESP8285 requires
+the ``DOUT`` mode.
+
+Here is some more insights about that in `esp32 forums<https://www.esp32.com/viewtopic.php?t=1250#p5523>`__.
+
+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.  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 UART options:
+
+- disabled
+- Serial
+- Serial1
+
+When on ``Serial`` or ``Serial1`` options (see
+`reference<reference.rst#serial>`__), 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, and 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 other ones may be used when asked by a maintainer or if you are a
+developper trying to debug some issues.
+
+lwIP variant
+~~~~~~~~~~~~
+
+`lwIP<https://en.wikipedia.org/wiki/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 cores v3+.
+
+- ``v2 Lower Memory``
+
+  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
+  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
+  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 and reassembly,
+
+  -  No AutoIP (not getting 169.254.x.x on DHCP request when there is no DHCP answer),
+
+  -  No SACK-OUT (= no Selective ACKnowledgements for OUTput):
+
+     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 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.
+
+``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.
+
+  -  ``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
+  option enables only the main ciphers and can be used to lower flash
+  occupation.
+
+``MMU`` (Memory Management Unit)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  Head to its `specific documentation<mmu.rst>`__.  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
+  ``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
+  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.

doc/index.rst

@@ -6,6 +6,7 @@ Welcome to ESP8266 Arduino Core's documentation!
    :caption: Contents:
 
    Installing <installing>
+   Arduino IDE options <ideoptions>
    Reference <reference>
    Libraries <libraries>
    File system <filesystem>

tools/boards.txt.py

@@ -1634,7 +1634,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')