Skip to content

Commit bf1aec8

Browse files
xcguangxcguang
committed
Merge branch 'docs/add_how_to_enable_silence_mode_docs' into 'master'
docs: add how_to_enable_silence_mode docs See merge request application/esp-at!1593
2 parents 102d512 + b0e1cb4 commit bf1aec8

File tree

8 files changed

+698
-2
lines changed

8 files changed

+698
-2
lines changed

‎docs/en/Compile_and_Develop/How_to_build_project_with_web_page.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,9 @@ Enter a commit message to describe the changes you have made. Click ``Commit & P
247247

248248
Submit Changes (Click to Enlarge)
249249

250+
.. note::
251+
If you want to enable or disable the AT firmware's :ref:`silence mode <silence-mode-usage>`, please refer to the :doc:`How to enable or disable silence mode <How_to_configure_silence_mode>` document.
252+
250253
.. _at-wc-action-compile:
251254

252255
Step 6. Compile the AT firmware using GitHub Actions

‎docs/en/Compile_and_Develop/How_to_clone_project_and_compile_it.rst‎

Lines changed: 236 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,9 +104,244 @@ Select the following configuration options for your {IDF_TARGET_NAME} if it is y
104104

105105
- Select the ``Platform name`` for your {IDF_TARGET_NAME}. For example, select ``PLATFORM_{IDF_TARGET_CFG_PREFIX}`` for {IDF_TARGET_NAME} series of products. ``Platform name`` is defined in :component_file:`factory_param_data.csv <customized_partitions/raw_data/factory_param/factory_param_data.csv>`.
106106
- Select the ``Module name`` for your {IDF_TARGET_NAME}. For example, select ``{IDF_TARGET_COMPILE_MNAME}`` for the {IDF_TARGET_PRODUCT_NAME} module. ``Module name`` is defined in :component_file:`factory_param_data.csv <customized_partitions/raw_data/factory_param/factory_param_data.csv>`.
107-
- Enable or disable ``silence mode``. If enabled, it will remove some logs and reduce the firmware size. Generally, it should be disabled.
107+
108+
.. _esp-at_silence_mode_cfg:
109+
110+
- Before selecting to enable or disable silence mode, please read the :doc:`documentation <../Compile_and_Develop/How_to_configure_silence_mode>` to understand silence mode. Generally, it should be disabled.
108111
- The above three option items will not appear if the file ``build/module_info.json`` exists. So please delete it if you want to reconfigure the module information.
109112

113+
.. only:: esp32
114+
115+
For example, set ``Platform name`` to ``ESP32``, ``Module name`` to ``WROOM-32``, and enable silence mode as follows:
116+
117+
.. code-block:: none
118+
119+
$ ./build.py install
120+
Ready to install ESP-IDF prerequisites..
121+
122+
... (more lines of install ESP-IDF prerequisites)
123+
124+
Ready to install ESP-AT prerequisites..
125+
126+
... (more lines of install ESP-IDF prerequisites)
127+
128+
Platform name:
129+
1. PLATFORM_ESP32
130+
2. PLATFORM_ESP32C3
131+
3. PLATFORM_ESP32C2
132+
4. PLATFORM_ESP32C6
133+
5. PLATFORM_ESP32S2
134+
choose(range[1,5]):1
135+
136+
Module name:
137+
1. WROOM-32 (Firmware description: TX:17 RX:16)
138+
2. WROVER-32 (Firmware description: need PSRAM, TX:22 RX:19)
139+
3. PICO-D4 (Firmware description: TX:22 RX:19)
140+
4. SOLO-1 (Firmware description: not recommended for new design, TX:17 RX:16)
141+
5. MINI-1 (Firmware description: TX:17 RX:16, ESP32-U4WDH chip inside)
142+
6. ESP32-SDIO (Firmware description: communicate with MCU via SDIO)
143+
7. ESP32-D2WD (Firmware description: 2MB flash, No OTA)
144+
choose(range[1,7]):1
145+
146+
Enable silence mode to remove some logs and reduce the firmware size?
147+
0. No
148+
1. Yes
149+
choose(range[0,1]):1
150+
Platform name:ESP32 Module name:WROOM-32 Silence:1
151+
Cloning into 'esp-idf'...
152+
153+
... (more lines of clone esp-idf)
154+
155+
Ready to set up ESP-IDF tools..
156+
157+
... (more lines of set up ESP-IDF tools)
158+
159+
All done! You can now run:
160+
161+
./build.py build
162+
163+
.. only:: esp32c2
164+
165+
For example, set ``Platform name`` to ``ESP32C2``, ``Module name`` to ``ESP32C2-4MB``, and disable silence mode as follows:
166+
167+
.. code-block:: none
168+
169+
$ ./build.py install
170+
Ready to install ESP-IDF prerequisites..
171+
172+
... (more lines of install ESP-IDF prerequisites)
173+
174+
Ready to install ESP-AT prerequisites..
175+
176+
... (more lines of install ESP-IDF prerequisites)
177+
178+
Platform name:
179+
1. PLATFORM_ESP32
180+
2. PLATFORM_ESP32C3
181+
3. PLATFORM_ESP32C2
182+
4. PLATFORM_ESP32C6
183+
5. PLATFORM_ESP32S2
184+
choose(range[1,5]):3
185+
186+
Module name:
187+
1. ESP32C2-2MB (Firmware description: single Wi-Fi, 2MB, TX:7 RX:6)
188+
2. ESP32C2-4MB (Firmware description: Wi-Fi + BluFi, 4MB, TX:7 RX:6)
189+
3. ESP32C2-BLE-2MB (Firmware description: single BLE, 2MB, TX:7 RX:6)
190+
choose(range[1,3]):2
191+
192+
Enable silence mode to remove some logs and reduce the firmware size?
193+
0. No
194+
1. Yes
195+
choose(range[0,1]):0
196+
Platform name:ESP32C2 Module name:ESP32C2-4MB Silence:0
197+
Cloning into 'esp-idf'...
198+
199+
... (more lines of clone esp-idf)
200+
201+
Ready to set up ESP-IDF tools..
202+
203+
... (more lines of set up ESP-IDF tools)
204+
205+
All done! You can now run:
206+
207+
./build.py build
208+
209+
.. only:: esp32c3
210+
211+
For example, set ``Platform name`` to ``ESP32C3``, ``Module name`` to ``MINI-1``, and disable silence mode as follows:
212+
213+
.. code-block:: none
214+
215+
$ ./build.py install
216+
Ready to install ESP-IDF prerequisites..
217+
218+
... (more lines of install ESP-IDF prerequisites)
219+
220+
Ready to install ESP-AT prerequisites..
221+
222+
... (more lines of install ESP-IDF prerequisites)
223+
224+
Platform name:
225+
1. PLATFORM_ESP32
226+
2. PLATFORM_ESP32C3
227+
3. PLATFORM_ESP32C2
228+
4. PLATFORM_ESP32C6
229+
5. PLATFORM_ESP32S2
230+
choose(range[1,5]):2
231+
232+
Module name:
233+
1. MINI-1 (Firmware description: TX:7 RX:6)
234+
2. ESP32C3-SPI (Firmware description: communicate with MCU via SPI)
235+
3. ESP32C3_RAINMAKER (Firmware description: support rainmaker cloud, TX:7 RX:6)
236+
choose(range[1,3]):1
237+
238+
Enable silence mode to remove some logs and reduce the firmware size?
239+
0. No
240+
1. Yes
241+
choose(range[0,1]):0
242+
Platform name:ESP32C3 Module name:MINI-1 Silence:0
243+
Cloning into 'esp-idf'...
244+
245+
... (more lines of clone esp-idf)
246+
247+
Ready to set up ESP-IDF tools..
248+
249+
... (more lines of set up ESP-IDF tools)
250+
251+
All done! You can now run:
252+
253+
./build.py build
254+
255+
.. only:: esp32c6
256+
257+
For example, set ``Platform name`` to ``ESP32C6``, ``Module name`` to ``ESP32C6-4MB``, and disable silence mode as follows:
258+
259+
.. code-block:: none
260+
261+
$ ./build.py install
262+
Ready to install ESP-IDF prerequisites..
263+
264+
... (more lines of install ESP-IDF prerequisites)
265+
266+
Ready to install ESP-AT prerequisites..
267+
268+
... (more lines of install ESP-IDF prerequisites)
269+
270+
Platform name:
271+
1. PLATFORM_ESP32
272+
2. PLATFORM_ESP32C3
273+
3. PLATFORM_ESP32C2
274+
4. PLATFORM_ESP32C6
275+
5. PLATFORM_ESP32S2
276+
choose(range[1,5]):4
277+
278+
Module name:
279+
1. ESP32C6-4MB (Firmware description: TX:7 RX:6)
280+
choose(range[1,1]):1
281+
282+
Enable silence mode to remove some logs and reduce the firmware size?
283+
0. No
284+
1. Yes
285+
choose(range[0,1]):0
286+
Platform name:ESP32C6 Module name:ESP32C6-4MB Silence:0
287+
288+
Cloning into 'esp-idf'...
289+
290+
... (more lines of clone esp-idf)
291+
292+
Ready to set up ESP-IDF tools..
293+
294+
... (more lines of set up ESP-IDF tools)
295+
296+
All done! You can now run:
297+
298+
./build.py build
299+
300+
.. only:: esp32s2
301+
302+
For example, set ``Platform name`` to ``ESP32S2``, ``Module name`` to ``MINI``, and disable silence mode as follows:
303+
304+
.. code-block:: none
305+
306+
$ ./build.py install
307+
Ready to install ESP-IDF prerequisites..
308+
309+
... (more lines of install ESP-IDF prerequisites)
310+
311+
Ready to install ESP-AT prerequisites..
312+
313+
... (more lines of install ESP-IDF prerequisites)
314+
315+
Platform name:
316+
1. PLATFORM_ESP32
317+
2. PLATFORM_ESP32C3
318+
3. PLATFORM_ESP32C2
319+
4. PLATFORM_ESP32C6
320+
5. PLATFORM_ESP32S2
321+
choose(range[1,5]):5
322+
323+
Module name:
324+
1. MINI (Firmware description: TX:17 RX:21)
325+
choose(range[1,1]):1
326+
327+
Enable silence mode to remove some logs and reduce the firmware size?
328+
0. No
329+
1. Yes
330+
choose(range[0,1]):0
331+
Platform name:ESP32S2 Module name:MINI Silence:0
332+
333+
Cloning into 'esp-idf'...
334+
335+
... (more lines of clone esp-idf)
336+
337+
Ready to set up ESP-IDF tools..
338+
339+
... (more lines of set up ESP-IDF tools)
340+
341+
All done! You can now run:
342+
343+
./build.py build
344+
110345
.. _esp-at-hardware-connection:
111346

112347
Step 4. Connect Your Device

‎docs/en/Compile_and_Develop/How_to_configure_silence_mode.rst‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
How to Enable Silence Mode
2+
==========================
3+
4+
:link_to_translation:`zh_CN:[中文]`
5+
6+
Introduction
7+
--------------
8+
9+
.. _silence-mode-usage:
10+
11+
Silence mode is a compilation configuration option for ESP-AT firmware that controls the behavior of AT logs (i.e., logs output from the :term:`AT log port`). It is generally recommended to disable this option. While enabling it may reduce the size of the application firmware, you should **prioritize** the following two methods for reducing the firmware size:
12+
13+
- In :ref:`python build.py menuconfig <esp-at-project-config>`, navigate to Component config > AT to disable the unnecessary AT features.
14+
- Refer to the optimization methods outlined in the `Minimizing Binary Size <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/api-guides/performance/size.html#minimizing-binary-size>`_ documentation.
15+
16+
.. list-table:: Advantages and Disadvantages of Enabling and Disabling Silence Mode
17+
:header-rows: 1
18+
:widths: 25 25 40
19+
20+
* - Silence Mode
21+
- Advantages
22+
- Disadvantages
23+
* - Disabled (i.e., set to 0, recommended)
24+
- Enable logging for some AT functions
25+
- The size of the application firmware (esp-at.bin) will increase, potentially exceeding the allocated application partition size in the code and resulting in a compilation failure (refer to :ref:`compilation failure log <compilation-failure-log>`).
26+
* - Enabled (i.e., set to 1, not recommended)
27+
- Reduced size of the application firmware (esp-at.bin)
28+
- This mode will remove some AT logs and make the `CONFIG_LOG_DEFAULT_LEVEL <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/kconfig.html?highlight=log%20output#config-log-default-level>`_ configuration ineffective, preventing AT from outputting logs at the corresponding log levels, which will increase the difficulty of debugging AT functions.
29+
30+
.. _compilation-failure-log:
31+
32+
Compilation Failure Log Example:
33+
34+
.. code-block:: none
35+
36+
$ ./build.py build
37+
38+
... (more lines of build ESP-AT)
39+
40+
Generated /path/to/esp-at/build/esp-at.bin
41+
[836/838] cd /path/to/esp-at/build/esp-at.bin
42+
FAILED: esp-idf/esptool_py/CMakeFiles/app_check_size
43+
cd /path/to/esp-at/build/esp-idf/esptool_py && [...]/bin/python /path/to/esp-at/esp-idf/components/partition_table/check_sizes.py --offset 0x8000 partition --type app /path/to/esp-at/build/partition_table/partition-table.bin /path/to/esp-at/build/esp-at.bin
44+
Error: app partition is too small for binary esp-at.bin size 0x135ae0:
45+
- Part 'ota_0' 0/16 @ 0xd0000 size 0x130000 (overflow 0x5ae0)
46+
ninja: build stopped: subcommand failed.
47+
48+
Configuration
49+
--------------
50+
51+
- Enable or disable the silence mode configuration:
52+
53+
- :doc:`Compile ESP-AT Project Locally <../Compile_and_Develop/How_to_clone_project_and_compile_it>`
54+
55+
Configure the ``silence mode`` as ``No`` (or ``Yes``) in step 3 Install Environment to disable (or enable) the silence mode.
56+
57+
.. _silence-mode-usage-1:
58+
59+
- :doc:`Compile ESP-AT Project on the GitHub Webpage <../Compile_and_Develop/How_to_build_project_with_web_page>`
60+
61+
Modify the value of ``silence_mode`` in the `esp-at/.github/workflows/build_template_{IDF_TARGET_PATH_NAME}.yml <https://github.com/espressif/esp-at/blob/master/.github/workflows/build_template_{IDF_TARGET_PATH_NAME}.yml>`_ file in step 5.3 Commit changes to enable or disable the silence mode. For example, to enable silence mode, set it to:
62+
63+
.. only:: esp32
64+
65+
::
66+
67+
- name: Configure prerequisites
68+
run: |
69+
# set module information
70+
silence_mode=1
71+
# set the silence_sdkconfig.defaults file path
72+
silence_sdkconfig=module_config/module_<your_module_name>/sdkconfig_silence.defaults
73+
mkdir build
74+
echo -e "{\"platform\": \"PLATFORM_{IDF_TARGET_CFG_PREFIX}\", \"module\": \"${{ inputs.module_name }}\", \"silence\": ${silence_mode}}" > build/module_info.json
75+
76+
.. only:: not esp32
77+
78+
::
79+
80+
- name: Configure prerequisites
81+
run: |
82+
# set module information
83+
silence_mode=1
84+
mkdir build
85+
echo -e "{\"platform\": \"PLATFORM_{IDF_TARGET_CFG_PREFIX}\", \"module\": \"${{ inputs.module_name }}\", \"silence\": ${silence_mode}}" > build/module_info.json
86+
87+
- Please flash the compiled AT firmware to the module, and then execute the :ref:`AT+GMR <cmd-GMR>` command to confirm whether the enable or disable of silence mode is successful.
88+
89+
- If silence mode is enabled, the response of the AT+GMR command should include ``s-``, for example:
90+
91+
::
92+
93+
AT+GMR
94+
AT version:3.5.0.0-dev(s-88b4ea4...
95+
96+
... (more lines of version information)
97+
98+
OK
99+
100+
- If silence mode is disabled, the response of the AT+GMR command should **NOT** include ``s-``, for example:
101+
102+
::
103+
104+
AT+GMR
105+
AT version:3.5.0.0-dev(88b4ea4...
106+
107+
... (more lines of version information)
108+
109+
OK

‎docs/en/Compile_and_Develop/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,4 @@ How to Compile and Develop Your Own AT Project
2727
How to Download the Latest Temporary Version of AT Firmware from GitHub <How_to_download_the_latest_temporary_version_of_AT_from_github>
2828
at.py tool <tools_at_py>
2929
AT API Reference <AT_API_Reference>
30+
How to Configure Silence Mode <How_to_configure_silence_mode>

‎docs/zh_CN/Compile_and_Develop/How_to_build_project_with_web_page.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,9 @@
247247

248248
提交修改（点击放大）
249249

250+
.. note::
251+
如果您想要启用或禁用 AT 固件的 :ref:`silence mode <silence-mode-usage>`，请参考 :doc:`如何启用或禁用 silence mode <How_to_configure_silence_mode>` 文档。
252+
250253
.. _at-wc-action-compile:
251254

252255
第六步：GitHub Actions 编译 AT 固件

0 commit comments

Comments
 (0)