arduino/esp8266
1
0
Fork 0
mirror of https://github.com/esp8266/Arduino.git synced 2025-07-21 21:22:31 +03:00
Code Activity

documentation: Arduino IDE options: fix hyperlinks and format (#8158)

Browse Source 
(this time, sphinx was used locally)
This commit is contained in:
david gauchard
2021-06-22 03:39:53 +02:00
committed by GitHub
parent e55dfc3a0e
commit d283541380
1 changed files with 90 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
doc/ideoptions.rst
View File

@ -31,8 +31,8 @@ Upload Speed
This the UART speed setup for flashing the ESP. It is not related with the 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 UART(Serial) speed programmed from inside the sketch, if enabled. Default
values are legacy. The highest speed option (around 1Mbaud) should always values are legacy. The highest speed option (around 1Mbaud) should always
work. For specific boards, defaults can be updated using the <boards>.txt work. For specific boards, defaults can be updated using the `board.txt
builder. generator <faq/a05-board-generator.rst>`__.
CPU Frequency CPU Frequency
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
@ -70,7 +70,7 @@ list, the first one of each size is the default and suitable for many cases.
Example: ``4MB (FS:2MB OTA:~1019KB)``: Example: ``4MB (FS:2MB OTA:~1019KB)``:
- 4MB is the flash chip size (= 4 MBytes, sometimes oddly noted 32Mbits) - 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) - ``OTA:~1019KB`` (around 1MB) is used for Over The Air flashing (note that OTA binary can be gzip-ed)
- ``FS:2MB`` means that 2MBytes are used for an internal filesystem (LittleFS). - ``FS:2MB`` means that 2MBytes are used for an internal filesystem (LittleFS).
Flash Mode Flash Mode
@ -82,17 +82,18 @@ 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 esp8266, the fastest mode may not be working. Note that ESP8285 requires
the ``DOUT`` mode. the ``DOUT`` mode.
Here is some more insights about that in `esp32 forums<https://www.esp32.com/viewtopic.php?t=1250#p5523>`__. Here is some more insights about that in `esp32 forums <https://www.esp32.com/viewtopic.php?t=1250#p5523>`__.
Reset Method Reset Method
~~~~~~~~~~~~ ~~~~~~~~~~~~
On some boards (commonly NodeMCU, Lolin/Wemos) an electronic trick allows to | 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 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 is the default ``dtr (aka nodemcu)`` option. It provides an extra-easy way of
flashing from serial port. When not available, the ``no dtr`` option can be flashing from serial port.
used in conjunction with a flash button on the board (or by driving the ESP | When not available, the ``no dtr`` option can be
dedicated GPIOs to boot in flash mode at power-on). 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 Debug Port
~~~~~~~~~~ ~~~~~~~~~~
@ -104,7 +105,7 @@ There are three UART options:
- Serial1 - Serial1
When on ``Serial`` or ``Serial1`` options (see When on ``Serial`` or ``Serial1`` options (see
`reference<reference.rst#serial>`__), messages are sent at 74880 bauds at `reference <reference.rst#serial>`__), messages are sent at 74880 bauds at
boot time then baud rate is changed to user configuration in sketch. These boot time then baud rate is changed to user configuration in sketch. These
messages are generated by the internal bootloader. Subsequent serial data messages are generated by the internal bootloader. Subsequent serial data
are coming either from the firmware, this Arduino core, and user application. are coming either from the firmware, this Arduino core, and user application.
@ -112,17 +113,18 @@ are coming either from the firmware, this Arduino core, and user application.
Debug Level Debug Level
~~~~~~~~~~~ ~~~~~~~~~~~
There are a number of options. The first (``None``) is explained by itself. There are a number of options.
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 - The first (``None``) is explained by itself.
developper trying to debug some issues. - 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 variant
~~~~~~~~~~~~ ~~~~~~~~~~~~
`lwIP<https://en.wikipedia.org/wiki/LwIP>`__ is the internal network `lwIP <https://en.wikipedia.org/wiki/LwIP>`__ is the internal network
software stack. It is highly configurable and comes with features that can software stack. It is highly configurable and comes with features that can
be enabled, at the price of RAM or FLASH space usage. be enabled, at the price of RAM or FLASH space usage.
@ -130,7 +132,7 @@ 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. compromise. Note that cores v2.x were or could be using the lwIP-v1 stack.
Only lwIP-v2 is available on cores v3+. Only lwIP-v2 is available on cores v3+.
- ``v2 Lower Memory`` - v2 Lower Memory
This is lwIP-v2 with MSS=536 bytes. MSS is TCP's `Maximum Segment Size`, 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 and different from MTU (IP's Maximum Transfer Unit) which is always 1480
@ -142,13 +144,13 @@ Only lwIP-v2 is available on cores v3+.
UDP and other IP protocols are not affected by MSS value. UDP and other IP protocols are not affected by MSS value.
- ``v2 Higher Bandwidth`` - v2 Higher Bandwidth
When streaming large amount of data, prefer this option. It uses more 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 memory (MSS=1460) so it allows faster transfers thanks to a smaller number
of packets providing lower overhead and higher bandwidth. of packets providing lower overhead and higher bandwidth.
- ``... (no features)`` - ... (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:
@ -158,89 +160,88 @@ 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 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 SACK-OUT (= no Selective ACKnowledgements for OUTput):
| 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 ...`` - IPv6 ...
With these options, IPv6 is enabled, with features. It uses about 20-30KB With these options, IPv6 is enabled, with features. It uses about 20-30KB
of supplementary flash space. of supplementary flash space.
``VTable location`` VTable location
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
This is the mechanism used in C++ to support dynamic dispatch of virtual 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 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 bytes, but in very specific cases they can be stored in Heap space, or IRAM
space (both in RAM). 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.
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
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
- C++ exceptions are disabled by default. Consequently the ``new`` There are a number of available espressif firmwares. The first / default
operator will cause a general failure and a reboot when memory is full. 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.
Note that the C-``malloc`` function always returns ``nullptr`` when SSL Support
memory is full. ~~~~~~~~~~~
- Enabled: on this Arduino core, exceptions are possible. Note that they The first and default choice (``All SSL ciphers``) is good. The second
are quite ram and flash consuming. option enables only the main ciphers and can be used to lower flash
occupation.
``Stack protection`` MMU (Memory Management Unit)
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- This is disabled by default 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``.
- When Enabled, the compiler generated extra code to check for stack Non-32-Bit Access
overflows. When this happens, an exception is raised with a message and ~~~~~~~~~~~~~~~~~
the ESP reboots.
``Erase Flash`` 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()``.
- ``Only sketch``: When WiFi is enabled at boot and persistent WiFi With the non-default option ``Byte/Word access``, an exception manager
credentials are enabled, these data are preserved across flashings. allows to transparently use them as if they were byte-accessible. As a
Filesystem is preserved. 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.
- ``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.