arduino/esp8266
1
0
Fork 0
mirror of https://github.com/esp8266/Arduino.git synced 2025-04-21 10:26:06 +03:00
Code
esp8266/doc/ideoptions.rst
M Hightower d3c102e717
Update documentation and arduino debug options (#8837) 
* Update documentation

Describe how to improve Exception Decoder results.

Updated build option details.

* Added d-a-v's code. And updated description and debug macro.

* Update doc

Updated platform.txt - positioned -Os such that it can be overridden by `build.opt`.

Add suggestion of using `-Og` which may improve the Decoder's line number correlation
with the problem in the source code.

Untested adjustments to platformio-build.py

* Fixed code formatting

* Fixed example

Previously `-O3` in the example had no effect. It was overridden by later flags.
Reording the `-Os` allowed changing optimization to  work. Somehow this triggered
a new warning "Stream.h:50:7: warning: 'f.Stream::_startMillis' may be used
uninitialized in this function". Replaced `-O3` with `-Og`.

* Proposed "Debug port" menu change
Preserves a pathway for `build.opt` override.

* Update boards.txt.py and docs - WIP

* Improve organization of optimization content.
Use "Debug Optimization" for menu name.
The menu item defines the initial optimization.
platform.txt - optimization parameter can be overridden by build.opt.

* Add fallback value for build.debug_optim to platform.txt

* update text and undo changes to platformio-build.py

* tweak text

* Added ':orphan:' mark to a06-global-build-options.rst

* Update doc. Added link in page index to 'Improving Exception Decoder Results'

* Update text to reference PR#8868 improvements for leaf function.
2023-03-29 11:16:33 +02:00

292 lines
10 KiB
ReStructuredText
Raw Blame History

esp8266 configuration
=====================
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).
Note about PlatformIO
---------------------
`PlatformIO specific documentation
<https://docs.platformio.org/en/latest/platforms/espressif8266.html#espressif-8266>`__
is also available. Note that this link is available here for reference and
is not maintained by the esp8266 Arduino core platform team.
Arduino IDE Tools Menu
----------------------
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 `board.txt
generator <faq/a05-board-generator.rst>`__.
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-ed)
- ``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 (aka 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
developer trying to debug some issues.
Debug Optimization
~~~~~~~~~~~~~~~~~~
Due to the limited resources on the device, our default compiler optimizations
focus on creating the smallest code size (``.bin`` file). That is fine for
release but not ideal for debugging.
``Debug Optimization`` use to improve Exception Decoder results.
- ``Lite`` impact on code size uses ``-fno-optimize-sibling-calls`` to alter
the ``-Os`` compiler option to place more caller addresses on the Stack.
- ``Optimum`` offers better quality stack content for the Exception Decoder at
the expense of a larger code size. It uses the ``-Og`` compiler option, which
turns off optimizations that can make debugging difficult while keeping
others.
- ``None`` no changes for debugging continue using ``-Os``.
Take note some sketches may start working after changing the optimization. Or
fail less often. And it is also possible (not likely) that source code that
was working with ``-Os`` may break with ``-Og``.
For more topic depth, read `Improving Exception Decoder Results <faq/a02-my-esp-crashes.rst#improving-exception-decoder-results>`__
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.
NONOS SDK Version
~~~~~~~~~~~~~~~~~~
Our Core is based on [Espressif NONOS SDK](https://github.com/espressif/ESP8266_NONOS_SDK).
- **2.2.1+100 (190703)** (default)
- 2.2.1+119 (191122)
- 2.2.1+113 (191105)
- 2.2.1+111 (191024)
- 2.2.1+61 (190313)
- 2.2.1 (legacy)
- 3.0.5 (experimental)
See our issue tracker in regards to default version selection.
* `#6724 (comment) <https://github.com/esp8266/Arduino/pull/6724#issuecomment-556243781>`__
* `#6826 <https://github.com/esp8266/Arduino/pull/6826>`__
Notice that 3.x.x is provided **as-is** and remains **experimental**.
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.
View Git Blame Copy Permalink