diff --git a/boards.txt b/boards.txt index 7262dd923..85c8ecba4 100644 --- a/boards.txt +++ b/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 diff --git a/doc/ideoptions.rst b/doc/ideoptions.rst new file mode 100644 index 000000000..ff133f44d --- /dev/null +++ b/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 .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`__. + +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`__), 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`__ 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`__. 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. diff --git a/doc/index.rst b/doc/index.rst index dcc5f6962..5f3ec247c 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 2d099e850..f89d0e976 100755 --- a/tools/boards.txt.py +++ b/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')