Skip to content

Commit e55dfc3

Browse files
d-a-vd-a-v
authored
Documentation: Arduino IDE specific options for esp82xx (#8154)
1 parent 78e6328 commit e55dfc3

File tree

4 files changed

+249
-2
lines changed

4 files changed

+249
-2
lines changed

‎boards.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ menu.dbg=Debug port
1919
menu.lvl=Debug Level
2020
menu.ip=lwIP Variant
2121
menu.vt=VTables
22-
menu.exception=Exceptions
22+
menu.exception=C++ Exceptions
2323
menu.stacksmash=Stack Protection
2424
menu.wipe=Erase Flash
2525
menu.sdk=Espressif FW

‎doc/ideoptions.rst

+246
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
Arduino IDE: esp8266 specificities in Tools menu
2+
================================================
3+
4+
Overview
5+
--------
6+
7+
There are a number of specific options for esp8266 in the Arduino IDE Tools
8+
menu. Not all of them are available for every board. If one is needed and
9+
not visible, please try using the generic esp8266 or esp8285 board.
10+
11+
In every menu entry, the first option is the default one and is suitable for
12+
most users (except for flash size in the generic ESP8266 board).
13+
14+
Specific option list
15+
--------------------
16+
17+
Board
18+
~~~~~
19+
20+
Most of the time there is only one type of ESP8266 chip and only one type of
21+
ESP8285(1M) chip shipped with hardware or DIY boards. Capabilities are the
22+
same everywhere. Hardware devices differ only on routed GPIO and external
23+
components.
24+
25+
If a specific hardware is not available in this list, "Generic ESP82xx"
26+
always work.
27+
28+
Upload Speed
29+
~~~~~~~~~~~~
30+
31+
This the UART speed setup for flashing the ESP. It is not related with the
32+
UART(Serial) speed programmed from inside the sketch, if enabled. Default
33+
values are legacy. The highest speed option (around 1Mbaud) should always
34+
work. For specific boards, defaults can be updated using the <boards>.txt
35+
builder.
36+
37+
CPU Frequency
38+
~~~~~~~~~~~~~
39+
40+
Any ESP82xx can run at 80 or 160MHz.
41+
42+
Crystal Frequency
43+
~~~~~~~~~~~~~~~~~
44+
45+
This is the on-board crystal frequency (26 or 40Mhz). Default is 26MHz.
46+
But the chip was designed with 40MHz. It explains the default strange 74880
47+
baud rate at boot, which is 115200\*26/40 (115200 being quite a lot used
48+
by default nowadays).
49+
50+
Flash Size
51+
~~~~~~~~~~
52+
53+
With the Arduino core, ESP82xx can use at most 1MB to store the main sketch
54+
in flash memory.
55+
56+
ESP8285 has 1MB internal flash capacity. ESP8266 is always shipped with an
57+
external flash chip that is most often 1MB (esp01, esp01s, lots of
58+
commercial appliances), 4MB (DIY boards like wemos/lolin D1 mini or nodemcu)
59+
or 16MB (lolin D1 mini pro). But configurations with 2MB and 8MB also
60+
exist. This core is also able to use older 512KB chips that are today not
61+
much used and officially deprecated by Espressif.
62+
63+
Flash space is divided into 3 main zones. The first is the user program
64+
space, 1MB at most. The second is enough space for the OTA ability. The
65+
third, the remaining space, can be used to hold a filesystem (LittleFS).
66+
67+
This list proposes many different configurations. In the generic board
68+
list, the first one of each size is the default and suitable for many cases.
69+
70+
Example: ``4MB (FS:2MB OTA:~1019KB)``:
71+
72+
- 4MB is the flash chip size (= 4 MBytes, sometimes oddly noted 32Mbits)
73+
- ``OTA:~1019KB`` (around 1MB) is used for Over The Air flashing (note that OTA binary can be ``gzip``-ped)
74+
- ``FS:2MB`` means that 2MBytes are used for an internal filesystem (LittleFS).
75+
76+
Flash Mode
77+
~~~~~~~~~~
78+
79+
There are four options. The most compatible and slowest is ``DOUT``. The
80+
fasted is ``QIO``. ESP8266 mcu is able to use any of these modes, but
81+
depending on the flash chips capabilities and how it is connected to the
82+
esp8266, the fastest mode may not be working. Note that ESP8285 requires
83+
the ``DOUT`` mode.
84+
85+
Here is some more insights about that in `esp32 forums<https://www.esp32.com/viewtopic.php?t=1250#p5523>`__.
86+
87+
Reset Method
88+
~~~~~~~~~~~~
89+
90+
On some boards (commonly NodeMCU, Lolin/Wemos) an electronic trick allows to
91+
use the UART DTR line to reset the esp8266 *and* put it in flash mode. This
92+
is the default ``dtr/nodemcu`` option. It provides an extra-easy way of
93+
flashing from serial port. When not available, the ``no dtr`` option can be
94+
used in conjunction with a flash button on the board (or by driving the ESP
95+
dedicated GPIOs to boot in flash mode at power-on).
96+
97+
Debug Port
98+
~~~~~~~~~~
99+
100+
There are three UART options:
101+
102+
- disabled
103+
- Serial
104+
- Serial1
105+
106+
When on ``Serial`` or ``Serial1`` options (see
107+
`reference<reference.rst#serial>`__), messages are sent at 74880 bauds at
108+
boot time then baud rate is changed to user configuration in sketch. These
109+
messages are generated by the internal bootloader. Subsequent serial data
110+
are coming either from the firmware, this Arduino core, and user application.
111+
112+
Debug Level
113+
~~~~~~~~~~~
114+
115+
There are a number of options. The first (``None``) is explained by itself.
116+
The last (``NoAssert - NDEBUG``) is even quieter than the first (some
117+
internal guards are skipped to save more flash).
118+
119+
The other ones may be used when asked by a maintainer or if you are a
120+
developper trying to debug some issues.
121+
122+
lwIP variant
123+
~~~~~~~~~~~~
124+
125+
`lwIP<https://en.wikipedia.org/wiki/LwIP>`__ is the internal network
126+
software stack. It is highly configurable and comes with features that can
127+
be enabled, at the price of RAM or FLASH space usage.
128+
129+
There are 6 variants. As always, the first and default option is a good
130+
compromise. Note that cores v2.x were or could be using the lwIP-v1 stack.
131+
Only lwIP-v2 is available on cores v3+.
132+
133+
- ``v2 Lower Memory``
134+
135+
This is lwIP-v2 with MSS=536 bytes. MSS is TCP's `Maximum Segment Size`,
136+
and different from MTU (IP's Maximum Transfer Unit) which is always 1480
137+
in our case.
138+
Using such value for MSS is 99.9% compatible with any TCP peers, allows to
139+
store less data in RAM, and is consequently slower when transmitting large
140+
segments of data (using TCP) because of a larger overhead and latency due to
141+
smaller payload and larger number of packets.
142+
143+
UDP and other IP protocols are not affected by MSS value.
144+
145+
- ``v2 Higher Bandwidth``
146+
147+
When streaming large amount of data, prefer this option. It uses more
148+
memory (MSS=1460) so it allows faster transfers thanks to a smaller number
149+
of packets providing lower overhead and higher bandwidth.
150+
151+
- ``... (no features)``
152+
153+
Disabled features to get more flash space and RAM for users are:
154+
155+
- No IP Forwarding (=> no NAT),
156+
157+
- No IP Fragmentation and reassembly,
158+
159+
- No AutoIP (not getting 169.254.x.x on DHCP request when there is no DHCP answer),
160+
161+
- No SACK-OUT (= no Selective ACKnowledgements for OUTput):
162+
163+
no better stability with long distance TCP transfers,
164+
165+
- No listen backlog (no protection against DOS attacks for TCP server).
166+
167+
- ``IPv6 ...``
168+
169+
With these options, IPv6 is enabled, with features. It uses about 20-30KB
170+
of supplementary flash space.
171+
172+
``VTable location``
173+
~~~~~~~~~~~~~~~~~~~
174+
175+
This is the mechanism used in C++ to support dynamic dispatch of virtual
176+
methods. By default these tables are stored in flash to save precious RAM
177+
bytes, but in very specific cases they can be stored in Heap space, or IRAM
178+
space (both in RAM).
179+
180+
``C++ Exceptions``
181+
~~~~~~~~~~~~~~~~~~
182+
183+
- C++ exceptions are disabled by default. Consequently the ``new``
184+
operator will cause a general failure and a reboot when memory is full.
185+
186+
Note that the C-``malloc`` function always returns ``nullptr`` when
187+
memory is full.
188+
189+
- Enabled: on this Arduino core, exceptions are possible. Note that they
190+
are quite ram and flash consuming.
191+
192+
``Stack protection``
193+
~~~~~~~~~~~~~~~~~~~~
194+
195+
- This is disabled by default
196+
197+
- When Enabled, the compiler generated extra code to check for stack
198+
overflows. When this happens, an exception is raised with a message and
199+
the ESP reboots.
200+
201+
``Erase Flash``
202+
~~~~~~~~~~~~~~~
203+
204+
- ``Only sketch``: When WiFi is enabled at boot and persistent WiFi
205+
credentials are enabled, these data are preserved across flashings.
206+
Filesystem is preserved.
207+
208+
- ``Sketch + WiFi settings``: persistent WiFi settings are not
209+
preserved accross flashings. Filesystem is preserved.
210+
211+
- ``All Flash``: WiFi settings and Filesystems are erased.
212+
213+
``Espressif Firmware``
214+
~~~~~~~~~~~~~~~~~~~~~~
215+
216+
There are a number of available espressif firmwares. The first / default
217+
choice is fine. Only try with others after reading on the issue tracker
218+
that something has to be tried with them. Note that Espressif obsoleted
219+
all of them at the time of writing.
220+
221+
``SSL Support``
222+
~~~~~~~~~~~~~~~
223+
224+
The first and default choice (``All SSL ciphers``) is good. The second
225+
option enables only the main ciphers and can be used to lower flash
226+
occupation.
227+
228+
``MMU`` (Memory Management Unit)
229+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
230+
231+
Head to its `specific documentation<mmu.rst>`__. Note that there is an option
232+
providing an additional 16KB of IRAM to your application which can be used
233+
with ``new`` and ``malloc``.
234+
235+
``Non-32-Bit Access``
236+
~~~~~~~~~~~~~~~~~~~~~
237+
238+
On esp82xx architecture, DRAM can be accessed byte by byte, but read-only
239+
flash space (``PROGMEM`` variables) and IRAM cannot. By default they can
240+
only be safely accessed in a compatible way using special macros
241+
``pgm_read_some()``.
242+
243+
With the non-default option ``Byte/Word access``, an exception manager
244+
allows to transparently use them as if they were byte-accessible. As a
245+
result, any type of access works but in a very slow way for the usually
246+
illegal ones. This mode can also be enabled from the ``MMU`` options.

‎doc/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Welcome to ESP8266 Arduino Core's documentation!
66
:caption: Contents:
77

88
Installing <installing>
9+
Arduino IDE options <ideoptions>
910
Reference <reference>
1011
Libraries <libraries>
1112
File system <filesystem>

‎tools/boards.txt.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -1634,7 +1634,7 @@ def all_boards ():
16341634
print('menu.lvl=Debug Level')
16351635
print('menu.ip=lwIP Variant')
16361636
print('menu.vt=VTables')
1637-
print('menu.exception=Exceptions')
1637+
print('menu.exception=C++ Exceptions')
16381638
print('menu.stacksmash=Stack Protection')
16391639
print('menu.wipe=Erase Flash')
16401640
print('menu.sdk=Espressif FW')

0 commit comments

Comments
 (0)