mirror of
https://github.com/espressif/esp-idf.git
synced 2024-09-20 00:36:01 -04:00
Merge branch 'docs/run_spellcheck_on_docs' into 'master'
docs(misc): fixed typos found with codespell See merge request espressif/esp-idf!29893
This commit is contained in:
Marius Vikhammer
commit
ae6a41298d
@ -1,4 +1,4 @@
|
||||
[codespell]
|
||||
skip = build,*.yuv
|
||||
ignore-words-list = ser,dout,rsource
|
||||
ignore-words-list = ser,dout,rsource,fram
|
||||
write-changes = true
|
||||
|
||||
@ -53,7 +53,7 @@ There are two additional menuconfig options not mentioned above:
|
||||
|
||||
2. *Timeout for flushing last trace data to host on panic* (:ref:`CONFIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO`). The option is only meaningful in streaming mode and it controls the maximum time that the tracing module will wait for the host to read the last data in case of panic.
|
||||
|
||||
3. *UART RX/TX ring buffer size* (:ref:`CONFIG_APPTRACE_UART_TX_BUFF_SIZE`). The size of the buffer depends on the amount of data transfered through the UART.
|
||||
3. *UART RX/TX ring buffer size* (:ref:`CONFIG_APPTRACE_UART_TX_BUFF_SIZE`). The size of the buffer depends on the amount of data transferred through the UART.
|
||||
|
||||
4. *UART TX message size* (:ref:`CONFIG_APPTRACE_UART_TX_MSG_SIZE`). The maximum size of the single message to transfer.
|
||||
|
||||
|
||||
@ -97,7 +97,7 @@ The frame format with no fragment:
|
||||
- 1
|
||||
* - Data
|
||||
- ${Data Length}
|
||||
* - CheckSum (Most Siginificant Bit)
|
||||
* - CheckSum (Most Significant Bit)
|
||||
- 2
|
||||
|
||||
If the frag frame bit in the **Frame Control** field is enabled, there would be a 2-byte **Total Content Length** field in the **Data** field. This **Total Content Length** field indicates the length of the remaining part of the frame and also tells the remote how much memory needs to be allocated.
|
||||
@ -121,7 +121,7 @@ The frame format with fragments:
|
||||
* - Data
|
||||
- * Total Content Length: 2
|
||||
* Content: ${Data Length} - 2
|
||||
* - CheckSum (Most Siginificant Bit)
|
||||
* - CheckSum (Most Significant Bit)
|
||||
- 2
|
||||
|
||||
Normally, the control frame does not contain data bits, except for ACK Frame.
|
||||
@ -144,7 +144,7 @@ The format of ACK Frame:
|
||||
- 1
|
||||
* - Data
|
||||
- Acked Sequence Number: 2
|
||||
* - CheckSum (Most Siginificant Bit)
|
||||
* - CheckSum (Most Significant Bit)
|
||||
- 2
|
||||
|
||||
|
||||
|
||||
@ -50,7 +50,7 @@ SPI Flash Configuration
|
||||
|
||||
Each ESP-IDF application or bootloader .bin file contains a header with :ref:`CONFIG_ESPTOOLPY_FLASHMODE`, :ref:`CONFIG_ESPTOOLPY_FLASHFREQ`, :ref:`CONFIG_ESPTOOLPY_FLASHSIZE` embedded in it. These are used to configure the SPI flash during boot.
|
||||
|
||||
The :ref:`first-stage-bootloader` in ROM reads the :ref:`second-stage-bootloader` header information from flash and uses this infomation to load the rest of the :ref:`second-stage-bootloader` from flash. However, at this time the system clock speed is lower than configured and not all flash modes are supported. When the :ref:`second-stage-bootloader` then runs, it will reconfigure the flash using values read from the currently selected app binary's header (and NOT from the :ref:`second-stage-bootloader` header). This allows an OTA update to change the SPI flash settings in use.
|
||||
The :ref:`first-stage-bootloader` in ROM reads the :ref:`second-stage-bootloader` header information from flash and uses this information to load the rest of the :ref:`second-stage-bootloader` from flash. However, at this time the system clock speed is lower than configured and not all flash modes are supported. When the :ref:`second-stage-bootloader` then runs, it will reconfigure the flash using values read from the currently selected app binary's header (and NOT from the :ref:`second-stage-bootloader` header). This allows an OTA update to change the SPI flash settings in use.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
|
||||
@ -361,7 +361,7 @@ The following are some project/build variables that are available as build prope
|
||||
* If :ref:`CONFIG_APP_PROJECT_VER_FROM_CONFIG` option is set, the value of :ref:`CONFIG_APP_PROJECT_VER` will be used.
|
||||
* Else, if ``PROJECT_VER`` variable is set in project CMakeLists.txt file, its value will be used.
|
||||
* Else, if the ``PROJECT_DIR/version.txt`` exists, its contents will be used as ``PROJECT_VER``.
|
||||
* Else, if ``VERSION`` argument is passed to the ``project()`` call in the CMakeLists.txt file as ``project(... VERSION x.y.z.w )`` then it will be used as ``PROJECT_VER``. The ``VERSION`` argument must be compilant with the `cmake standard <https://cmake.org/cmake/help/v3.16/command/project.html>`_.
|
||||
* Else, if ``VERSION`` argument is passed to the ``project()`` call in the CMakeLists.txt file as ``project(... VERSION x.y.z.w )`` then it will be used as ``PROJECT_VER``. The ``VERSION`` argument must be compliant with the `cmake standard <https://cmake.org/cmake/help/v3.16/command/project.html>`_.
|
||||
* Else, if the project is located inside a Git repository, the output of git description will be used.
|
||||
* Otherwise, ``PROJECT_VER`` will be "1".
|
||||
- ``EXTRA_PARTITION_SUBTYPES``: CMake list of extra partition subtypes. Each subtype description is a comma-separated string with ``type_name, subtype_name, numeric_value`` format. Components may add new subtypes by appending them to this list.
|
||||
@ -1298,7 +1298,7 @@ These are properties that describe the build. Values of build properties can be
|
||||
.. code-block:: cmake
|
||||
|
||||
idf_build_get_property(python PYTHON)
|
||||
message(STATUS "The Python intepreter is: ${python}")
|
||||
message(STATUS "The Python interpreter is: ${python}")
|
||||
|
||||
- BUILD_DIR - build directory; set from ``idf_build_process`` BUILD_DIR argument
|
||||
- BUILD_COMPONENTS - list of components included in the build; set by ``idf_build_process``
|
||||
@ -1590,7 +1590,7 @@ No Longer Available in CMake
|
||||
Some features are significantly different or removed in the CMake-based system. The following variables no longer exist in the CMake-based build system:
|
||||
|
||||
- ``COMPONENT_BUILD_DIR``: Use ``CMAKE_CURRENT_BINARY_DIR`` instead.
|
||||
- ``COMPONENT_LIBRARY``: Defaulted to ``$(COMPONENT_NAME).a``, but the library name could be overriden by the component. The name of the component library can no longer be overriden by the component.
|
||||
- ``COMPONENT_LIBRARY``: Defaulted to ``$(COMPONENT_NAME).a``, but the library name could be overridden by the component. The name of the component library can no longer be overridden by the component.
|
||||
- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. Use ``CMAKE_C_COMPILER``, ``CMAKE_C_LINK_EXECUTABLE``, ``CMAKE_OBJCOPY``, etc instead. `Full list here <cmake language variables_>`_.
|
||||
- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. These are no longer provided, external projects should detect any required host toolchain manually.
|
||||
- ``COMPONENT_ADD_LDFLAGS``: Used to override linker flags. Use the CMake `target_link_libraries`_ command instead.
|
||||
|
||||
@ -65,7 +65,7 @@ Error message will typically look like this::
|
||||
|
||||
.. note:: If :doc:`ESP-IDF monitor <tools/idf-monitor>` is used, addresses in the backtrace will be converted to file names and line numbers.
|
||||
|
||||
- The first line mentions the error code as a hexadecimal value, and the identifier used for this error in source code. The latter depends on :ref:`CONFIG_ESP_ERR_TO_NAME_LOOKUP` option being set. Address in the program where error has occured is printed as well.
|
||||
- The first line mentions the error code as a hexadecimal value, and the identifier used for this error in source code. The latter depends on :ref:`CONFIG_ESP_ERR_TO_NAME_LOOKUP` option being set. Address in the program where error has occurred is printed as well.
|
||||
|
||||
- Subsequent lines show the location in the program where :c:macro:`ESP_ERROR_CHECK` macro was called, and the expression which was passed to the macro as an argument.
|
||||
|
||||
|
||||
@ -14,16 +14,16 @@ ESP-BLE-MESH Terminology
|
||||
- Detailed Explanation
|
||||
* - Unprovisioned Device
|
||||
- A device that is not a member of a mesh network is known as an unprovisioned device.
|
||||
- Examples: lighting devices, temperature control devices, manufacturing equipments and electric doors, etc.
|
||||
- Examples: lighting devices, temperature control devices, manufacturing equipment and electric doors, etc.
|
||||
* - Node
|
||||
- A node is a provisioned device.
|
||||
- The role of unprovisioned device will change to node after being provisioned to ESP-BLE-MESH network. Nodes (such as lighting devices, temperature control devices, manufacturing equipments, and electric doors) are devices that can send, receive, or relay messages in ESP-BLE-MESH network, and they can optionally support one or more subnets.
|
||||
- The role of unprovisioned device will change to node after being provisioned to ESP-BLE-MESH network. Nodes (such as lighting devices, temperature control devices, manufacturing equipment, and electric doors) are devices that can send, receive, or relay messages in ESP-BLE-MESH network, and they can optionally support one or more subnets.
|
||||
* - Relay Node
|
||||
- A node that supports the Relay feature and has the Relay feature enabled is known as a Relay node.
|
||||
- Relay nodes can receive and resend ESP-BLE-MESH messages, so the messages can be transferred further. Users can decide whether or not to enable forwarding function of nodes according to nodes' status. Messages can be relayed for multiple times, and each relay is considered as a "hop". Messages can hop up to 126 times, which is enough for message transmission in a wide area.
|
||||
* - Proxy Node
|
||||
- A node that supports the Proxy feature and has the Proxy feature enabled is known as a Proxy node.
|
||||
- Proxy nodes receive messages from one bearer (it generally includes advertising bearer and GATT bearer) and resend it from another one. The purpose is to connect communication equipments that only support GATT bearer to ESP-BLE-MESH network. Generally, mobile apps need a Proxy node to access Mesh network. Without Proxy nodes, mobile apps cannot communicate with members in Mesh network.
|
||||
- Proxy nodes receive messages from one bearer (it generally includes advertising bearer and GATT bearer) and resend it from another one. The purpose is to connect communication equipment that only support GATT bearer to ESP-BLE-MESH network. Generally, mobile apps need a Proxy node to access Mesh network. Without Proxy nodes, mobile apps cannot communicate with members in Mesh network.
|
||||
* - Friend Node
|
||||
- A node that supports the Friend feature, has the Friend feature enabled, and has a friendship with a node that supports the Low Power feature is known as a Friend node.
|
||||
- Friend node, like the backup of Low Power node (LPN), can store messages that are sent to Low Power node and security updates; the stored information will be transferred to Low Power node when Low Power node needs it. Low Power node must establish "friendship" with another node that supports the Friend Feature to reduce duty cycle of its receiver, thus power consumption of Low Power node can be reduced. Low Power node needs to find a Friend node to establish a friendship with it. The process involved is called "friendship establishment". Cooperation between Low Power node and Friend nodes enables Low Power node to schedule the use of the radio, thus Low Power node can receive messages at an appropriate or lower frequency without the need of keeping listening. Low Power node will poll Friend node to see if there is new message.
|
||||
|
||||
@ -68,7 +68,7 @@ Select this option by choosing ``Integrate RAM into memory map`` from :ref:`CONF
|
||||
|
||||
This is the most basic option for external RAM integration. Most likely, you will need another, more advanced option.
|
||||
|
||||
During the ESP-IDF startup, external RAM is mapped into the data virtual address space. The address space is dynamically allocated. The length will be the mininum length between the PSRAM size and the available data virtual address space size.
|
||||
During the ESP-IDF startup, external RAM is mapped into the data virtual address space. The address space is dynamically allocated. The length will be the minimum length between the PSRAM size and the available data virtual address space size.
|
||||
|
||||
Applications can manually place data in external memory by creating pointers to this region. So if an application uses external memory, it is responsible for all management of the external RAM: coordinating buffer usage, preventing corruption, etc.
|
||||
|
||||
|
||||
@ -90,7 +90,7 @@ Information how many breakpoints are set and where is shown in window "Breakpoin
|
||||
|
||||
Three breakpoints are set / maximum two are allowed
|
||||
|
||||
If you now click "Resume" (click ``blink_task()`` under "Tread #8", if "Resume" button is grayed out), the processor will run and halt at a breakpoint. Clicking "Resume" another time will make it run again, halt on second breakpoint, and so on.
|
||||
If you now click "Resume" (click ``blink_task()`` under "Thread #8", if "Resume" button is grayed out), the processor will run and halt at a breakpoint. Clicking "Resume" another time will make it run again, halt on second breakpoint, and so on.
|
||||
|
||||
You will be also able to see that LED is changing the state after each click to "Resume" program execution.
|
||||
|
||||
@ -104,7 +104,7 @@ Halting the Target Manually
|
||||
|
||||
When debugging, you may resume application and enter code waiting for some event or staying in infinite loop without any break points defined. In such case, to go back to debugging mode, you can break program execution manually by pressing "Suspend" button.
|
||||
|
||||
To check it, delete all breakpoints and click "Resume". Then click "Suspend". Application will be halted at some random point and LED will stop blinking. Debugger will expand tread and highlight the line of code where application halted.
|
||||
To check it, delete all breakpoints and click "Resume". Then click "Suspend". Application will be halted at some random point and LED will stop blinking. Debugger will expand thread and highlight the line of code where application halted.
|
||||
|
||||
.. figure:: ../../../_static/debugging-target-halted-manually.jpg
|
||||
:align: center
|
||||
@ -545,7 +545,7 @@ If your are blinking LED connected to GPIO4, then you should see fourth bit bein
|
||||
...
|
||||
0x3ff44004: 0x00000010
|
||||
|
||||
Now, when the LED is off, that corresponds to ``0x3ff44004: 0x00000000`` being displayed, try using ``set`` command to set this bit by writting ``0x00000010`` to the same memory location::
|
||||
Now, when the LED is off, that corresponds to ``0x3ff44004: 0x00000000`` being displayed, try using ``set`` command to set this bit by writing ``0x00000010`` to the same memory location::
|
||||
|
||||
(gdb) x /1wx 0x3FF44004
|
||||
0x3ff44004: 0x00000000
|
||||
|
||||
@ -222,7 +222,7 @@ OpenOCD flashing command ``program_esp`` has the following format:
|
||||
- ``image_file`` - Path to program image file.
|
||||
- ``offset`` - Offset in flash bank to write image.
|
||||
- ``verify`` - Optional. Verify flash contents after writing.
|
||||
- ``reset`` - Optional. Reset target after programing.
|
||||
- ``reset`` - Optional. Reset target after programming.
|
||||
- ``exit`` - Optional. Finally exit OpenOCD.
|
||||
- ``compress`` - Optional. Compress image file before programming.
|
||||
- ``encrypt`` - Optional. Encrypt binary before writing to flash. Same functionality with ``idf.py encrypted-flash``
|
||||
|
||||
@ -18,7 +18,7 @@ Breakpoints and Watchpoints Available
|
||||
What Else Should I Know About Breakpoints?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Emulating part of hardware breakpoints using software flash ones means that the GDB command ``hb myFunction`` which is invoked for function in flash will use pure hardware breakpoint if it is avalable otherwise one of the 32 software flash breakpoints is used. The same rule applies to ``b myFunction``-like commands. In this case GDB will decide what type of breakpoint to set itself. If ``myFunction`` is resided in writable region (IRAM) software IRAM breakpoint will be used otherwise hardware or software flash breakpoint is used as it is done for ``hb`` command.
|
||||
Emulating part of hardware breakpoints using software flash ones means that the GDB command ``hb myFunction`` which is invoked for function in flash will use pure hardware breakpoint if it is available otherwise one of the 32 software flash breakpoints is used. The same rule applies to ``b myFunction``-like commands. In this case GDB will decide what type of breakpoint to set itself. If ``myFunction`` is resided in writable region (IRAM) software IRAM breakpoint will be used otherwise hardware or software flash breakpoint is used as it is done for ``hb`` command.
|
||||
|
||||
|
||||
.. _jtag-debugging-tip-flash-mappings:
|
||||
@ -26,7 +26,7 @@ Emulating part of hardware breakpoints using software flash ones means that the
|
||||
Flash Mappings vs SW Flash Breakpoints
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In order to set/clear software breakpoints in flash, OpenOCD needs to know their flash addresses. To accomplish conversion from the {IDF_TARGET_NAME} address space to the flash one, OpenOCD uses mappings of program's code regions resided in flash. Those mappings are kept in the image header which is prepended to program binary data (code and data segments) and is specific to every application image written to the flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found application image, but there can be the cases when it will not work, e.g., partition table is not at standard flash location or even there can be multiple images: one factory and two OTA and you may want to debbug any of them. To cover all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of application image to debug. The command has the following format:
|
||||
In order to set/clear software breakpoints in flash, OpenOCD needs to know their flash addresses. To accomplish conversion from the {IDF_TARGET_NAME} address space to the flash one, OpenOCD uses mappings of program's code regions resided in flash. Those mappings are kept in the image header which is prepended to program binary data (code and data segments) and is specific to every application image written to the flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found application image, but there can be the cases when it will not work, e.g., partition table is not at standard flash location or even there can be multiple images: one factory and two OTA and you may want to debug any of them. To cover all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of application image to debug. The command has the following format:
|
||||
|
||||
``esp appimage_offset <offset>``
|
||||
|
||||
|
||||
@ -555,7 +555,7 @@ The example below is an excerpt from a possible linker script template. It defin
|
||||
|
||||
.iram0.text :
|
||||
{
|
||||
/* Code marked as runnning out of IRAM */
|
||||
/* Code marked as running out of IRAM */
|
||||
_iram_text_start = ABSOLUTE(.);
|
||||
|
||||
/* Markers referencing iram0_text */
|
||||
@ -571,7 +571,7 @@ The example below is an excerpt from a possible linker script template. It defin
|
||||
|
||||
.iram0.text :
|
||||
{
|
||||
/* Code marked as runnning out of IRAM */
|
||||
/* Code marked as running out of IRAM */
|
||||
_iram_text_start = ABSOLUTE(.);
|
||||
|
||||
/* Marker referencing iram0_text */
|
||||
@ -611,7 +611,7 @@ Then the corresponding excerpt from the generated linker script will be as follo
|
||||
|
||||
.iram0.text :
|
||||
{
|
||||
/* Code marked as runnning out of IRAM */
|
||||
/* Code marked as running out of IRAM */
|
||||
_iram_text_start = ABSOLUTE(.);
|
||||
|
||||
/* Placement rules generated from the processed fragments, placed where the marker was in the template */
|
||||
|
||||
@ -390,7 +390,7 @@ The following configuration options reduces the final binary size of almost any
|
||||
- Do not enable :ref:`CONFIG_COMPILER_CXX_EXCEPTIONS`, :ref:`CONFIG_COMPILER_CXX_RTTI`, or set the :ref:`CONFIG_COMPILER_STACK_CHECK_MODE` to Overall. All of these options are already disabled by default, but they have a large impact on binary size.
|
||||
- Disabling :ref:`CONFIG_ESP_ERR_TO_NAME_LOOKUP` removes the lookup table to translate user-friendly names for error values (see :doc:`/api-guides/error-handling`) in error logs, etc. This saves some binary size, but error values will be printed as integers only.
|
||||
- Setting :ref:`CONFIG_ESP_SYSTEM_PANIC` to ``Silent reboot`` saves a small amount of binary size, however this is **only** recommended if no one will use UART output to debug the device.
|
||||
:CONFIG_IDF_TARGET_ARCH_RISCV: - Seting :ref:`CONFIG_COMPILER_SAVE_RESTORE_LIBCALLS` reduces binary size by replacing inlined prologues/epilogues with library calls.
|
||||
:CONFIG_IDF_TARGET_ARCH_RISCV: - Setting :ref:`CONFIG_COMPILER_SAVE_RESTORE_LIBCALLS` reduces binary size by replacing inlined prologues/epilogues with library calls.
|
||||
- If the application binary uses only one of the security versions of the protocomm component, then the support for others can be disabled to save some code size. The support can be disabled through :ref:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_0`, :ref:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_1` or :ref:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_2` respectively.
|
||||
|
||||
.. note::
|
||||
|
||||
@ -238,7 +238,7 @@ To list all available root level options, run ``idf.py --help``. To list options
|
||||
|
||||
.. important::
|
||||
|
||||
Note that some older versions of CCache_ may exhibit bugs on some platforms, so if files are not rebuilt as expected, try disabling CCache_ and rebuiling the project. To enable CCache_ by default, set the ``IDF_CCACHE_ENABLE`` environment variable to a non-zero value.
|
||||
Note that some older versions of CCache_ may exhibit bugs on some platforms, so if files are not rebuilt as expected, try disabling CCache_ and rebuilding the project. To enable CCache_ by default, set the ``IDF_CCACHE_ENABLE`` environment variable to a non-zero value.
|
||||
|
||||
- ``-v`` flag causes both ``idf.py`` and the build system to produce verbose build output. This can be useful for debugging build problems.
|
||||
- ``--cmake-warn-uninitialized`` (or ``-w``) causes CMake to print uninitialized variable warnings found in the project directory only. This only controls CMake variable warnings inside CMake itself, not other types of build warnings. This option can also be set permanently by setting the ``IDF_CMAKE_WARN_UNINITIALIZED`` environment variable to a non-zero value.
|
||||
|
||||
@ -2316,7 +2316,7 @@ Wi-Fi HT20/40
|
||||
|
||||
Similarly, in AP mode, the actual bandwidth is negotiated between AP and the stations that connect to the AP. It is HT40 if the AP and one of the stations support HT40, otherwise it is HT20.
|
||||
|
||||
In station/AP coexist mode, the station/AP can configure HT20/40 seperately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in {IDF_TARGET_NAME}. For example, the configured bandwidth of AP is HT40, the configured primary channel is 6, and the configured secondary channel is 10. The station is connected to an router whose primary channel is 6 and secondary channel is 2, then the actual channel of AP is changed to primary 6 and secondary 2 automatically.
|
||||
In station/AP coexist mode, the station/AP can configure HT20/40 separately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in {IDF_TARGET_NAME}. For example, the configured bandwidth of AP is HT40, the configured primary channel is 6, and the configured secondary channel is 10. The station is connected to an router whose primary channel is 6 and secondary channel is 2, then the actual channel of AP is changed to primary 6 and secondary 2 automatically.
|
||||
|
||||
Theoretically, the HT40 can gain better throughput because the maximum raw physicial (PHY) data rate for HT40 is 150 Mbps while it is 72 Mbps for HT20. However, if the device is used in some special environment, e.g., there are too many other Wi-Fi devices around the {IDF_TARGET_NAME} device, the performance of HT40 may be degraded. So if the applications need to support same or similar scenarios, it is recommended that the bandwidth is always configured to HT20.
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@ Application Example
|
||||
|
||||
Check :example:`bluetooth/bluedroid/classic_bt` folder in ESP-IDF examples, which contains the following application:
|
||||
|
||||
* This is a SPP demo. This demo can discover the service, connect, send and recive SPP data :example:`bluetooth/bluedroid/classic_bt/bt_spp_acceptor`, :example:`bluetooth/bluedroid/classic_bt/bt_spp_initiator`
|
||||
* This is a SPP demo. This demo can discover the service, connect, send and receive SPP data :example:`bluetooth/bluedroid/classic_bt/bt_spp_acceptor`, :example:`bluetooth/bluedroid/classic_bt/bt_spp_initiator`
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
@ -7,7 +7,7 @@ Introduction
|
||||
|
||||
The esp-idf-kconfig_ package that ESP-IDF uses is based on kconfiglib_, which is a Python extension to the Kconfig_ system. Kconfig provides a compile-time project configuration mechanism and offers configuration options of several types (e.g., integers, strings, and Booleans). Kconfig files specify dependencies between options, default values of options, the way options are grouped together, etc.
|
||||
|
||||
For the full list of available features, please see Kconfig_ and `kconfiglib extentions`_.
|
||||
For the full list of available features, please see Kconfig_ and `kconfiglib extensions`_.
|
||||
|
||||
.. _project-configuration-menu:
|
||||
|
||||
@ -76,4 +76,4 @@ By convention, all option names are upper-case letters with underscores. When Kc
|
||||
.. _Kconfig: https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt
|
||||
.. _esp-idf-kconfig: https://pypi.org/project/esp-idf-kconfig/
|
||||
.. _kconfiglib: https://github.com/ulfalizer/Kconfiglib
|
||||
.. _kconfiglib extentions: https://pypi.org/project/kconfiglib/#kconfig-extensions
|
||||
.. _kconfiglib extensions: https://pypi.org/project/kconfiglib/#kconfig-extensions
|
||||
|
||||
@ -78,7 +78,7 @@ When transmitting packets, the assigned source MAC address must be written into
|
||||
Type/Length
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
The type/length field is a 2-byte field. If the value in this field is <= 1500 (decimal), it is considered a length field and it specifies the amount of non-padding data which follows in the data field. If the value is >= 1536, it represents the protocol the following packet data belongs to. The followings are the most common type values:
|
||||
The type/length field is a 2-byte field. If the value in this field is <= 1500 (decimal), it is considered a length field and it specifies the amount of non-padding data which follows in the data field. If the value is >= 1536, it represents the protocol the following packet data belongs to. The following are the most common type values:
|
||||
|
||||
* IPv4 = 0800H
|
||||
* IPv6 = 86DDH
|
||||
|
||||
@ -194,7 +194,7 @@ The table below provides more information on pin usage, and please note the comm
|
||||
|
||||
.. note::
|
||||
|
||||
- Strapping pin: GPIO0, GPIO2, GPIO5, GPIO12 (MTDI), and GPIO15 (MTDO) are strapping pins. For more infomation, please refer to `ESP32 datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`_.
|
||||
- Strapping pin: GPIO0, GPIO2, GPIO5, GPIO12 (MTDI), and GPIO15 (MTDO) are strapping pins. For more information, please refer to `ESP32 datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`_.
|
||||
- SPI0/1: GPIO6-11 and GPIO16-17 are usually connected to the SPI flash and PSRAM integrated on the module and therefore should not be used for other purposes.
|
||||
- JTAG: GPIO12-15 are usually used for inline debug.
|
||||
- GPI: GPIO34-39 can only be set as input mode and do not have software-enabled pullup or pulldown functions.
|
||||
|
||||
@ -162,7 +162,7 @@ The table below provides more information on pin usage, and please note the comm
|
||||
|
||||
.. note::
|
||||
|
||||
- Strapping pin: GPIO2, GPIO3, GPIO6, and GPIO7 are strapping pins. For more infomation, please refer to `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__.
|
||||
- Strapping pin: GPIO2, GPIO3, GPIO6, and GPIO7 are strapping pins. For more information, please refer to `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__.
|
||||
- SPI0/1: GPIO18-24 are usually used for SPI flash and not recommended for other uses.
|
||||
- USB-JTAG: GPIO 25 and 26 are used by USB-JTAG by default. In order to use them as GPIOs, USB-JTAG will be disabled by the drivers.
|
||||
|
||||
|
||||
@ -179,7 +179,7 @@ The table below provides more information on pin usage, and please note the comm
|
||||
|
||||
.. note::
|
||||
|
||||
- Strapping pin: GPIO4, GPIO5, GPIO8, GPIO9, and GPIO15 are strapping pins. For more infomation, please refer to `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__.
|
||||
- Strapping pin: GPIO4, GPIO5, GPIO8, GPIO9, and GPIO15 are strapping pins. For more information, please refer to `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__.
|
||||
- SPI0/1: GPIO24-30 are usually used for SPI flash and not recommended for other uses.
|
||||
- USB-JTAG: GPIO 12 and 13 are used by USB-JTAG by default. In order to use them as GPIOs, USB-JTAG will be disabled by the drivers.
|
||||
- For chip variants with an SiP flash built in, GPIO24 ~ GPIO30 are dedicated to connecting the SiP flash; GPIO10 ~ GPIO11 are not led out to any chip pins; therefore, only the remaining 22 GPIO pins are available.
|
||||
|
||||
@ -299,7 +299,7 @@ The table below provides more information on pin usage, and please note the comm
|
||||
|
||||
.. note::
|
||||
|
||||
- Strapping pin: GPIO34, GPIO35, GPIO36, GPIO37, and GPIO38 are strapping pins. For more infomation, please refer to `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__.
|
||||
- Strapping pin: GPIO34, GPIO35, GPIO36, GPIO37, and GPIO38 are strapping pins. For more information, please refer to `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__.
|
||||
- USB-JTAG: GPIO 24 and 25 are used by USB-JTAG by default. In order to use them as GPIOs, USB-JTAG will be disabled by the drivers.
|
||||
|
||||
---
|
||||
|
||||
@ -239,7 +239,7 @@ The table below provides more information on pin usage, and please note the comm
|
||||
|
||||
.. note::
|
||||
|
||||
- Strapping pin: GPIO0, GPIO45 and GPIO46 are strapping pins. For more infomation, please refer to `ESP32-S2 datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`_
|
||||
- Strapping pin: GPIO0, GPIO45 and GPIO46 are strapping pins. For more information, please refer to `ESP32-S2 datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`_
|
||||
- SPI0/1: GPIO26-32 are usually used for SPI flash and PSRAM and not recommended for other uses.
|
||||
- JTAG: GPIO39-42 are usually used for inline debug.
|
||||
- GPI: GPIO46 is fixed to pull-down and is input only.
|
||||
|
||||
@ -249,7 +249,7 @@ The table below provides more information on pin usage, and please note the comm
|
||||
|
||||
.. Note::
|
||||
|
||||
- Strapping pin: GPIO0, GPIO3, GPIO45 and GPIO46 are strapping pins. For more infomation, please refer to `ESP32-S3 datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`_.
|
||||
- Strapping pin: GPIO0, GPIO3, GPIO45 and GPIO46 are strapping pins. For more information, please refer to `ESP32-S3 datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`_.
|
||||
- SPI0/1: GPIO26-32 are usually used for SPI flash and PSRAM and not recommended for other uses. When using Octal Flash or Octal PSRAM or both, GPIO33~37 are connected to SPIIO4 ~ SPIIO7 and SPIDQS. Therefore, on boards embedded with ESP32-S3R8 / ESP32-S3R8V chip, GPIO33~37 are also not recommended for other uses.
|
||||
- USB-JTAG: GPIO 19 and 20 are used by USB-JTAG by default. In order to use them as GPIOs, USB-JTAG will be disabled by the drivers.
|
||||
|
||||
|
||||
@ -155,7 +155,7 @@ I2C slave requires the configuration that specified by :cpp:type:`i2c_slave_conf
|
||||
- :cpp:member:`i2c_master_bus_config_t::intr_priority` Set the priority of the interrupt. If set to ``0`` , then the driver will use a interrupt with low or medium priority (priority level may be one of 1,2 or 3), otherwise use the priority indicated by :cpp:member:`i2c_master_bus_config_t::intr_priority` Please use the number form (1,2,3) , not the bitmask form ((1<<1),(1<<2),(1<<3)). Please pay attention that once the interrupt priority is set, it cannot be changed until :cpp:func:`i2c_del_master_bus` is called.
|
||||
- :cpp:member:`i2c_slave_config_t::addr_bit_len` sets true if you need the slave to have a 10-bit address.
|
||||
:SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE: - :cpp:member:`i2c_slave_config_t::stretch_en` Set true if you want the slave controller stretch works, please refer to [`TRM <{IDF_TARGET_TRM_EN_URL}#i2c>`__] to learn how I2C stretch works.
|
||||
:SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE: - :cpp:member:`i2c_slave_config_t::broadcast_en` Set true to enable the slave broadcase. When the slave receives the general call address 0x00 from the master and the R/W bit followed is 0, it responds to the master regardless of its own address.
|
||||
:SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE: - :cpp:member:`i2c_slave_config_t::broadcast_en` Set true to enable the slave broadcast. When the slave receives the general call address 0x00 from the master and the R/W bit followed is 0, it responds to the master regardless of its own address.
|
||||
:SOC_I2C_SLAVE_SUPPORT_I2CRAM_ACCESS: - :cpp:member:`i2c_slave_config_t::access_ram_en` Set true to enable the non-fifo mode. Thus the I2C data fifo can be used as RAM, and double addressing will be synchronised opened.
|
||||
:SOC_I2C_SLAVE_SUPPORT_SLAVE_UNMATCH: - :cpp:member:`i2c_slave_config_t::slave_unmatch_en` Set true to enable the slave unmatch interrupt. If master send command address cannot match the slave address, and unmatch interrupt will be triggered.
|
||||
|
||||
|
||||
@ -122,7 +122,7 @@ ESP32-P4 I2S 0~2 I2S 0 I2S 0 I2S 0~2 none none
|
||||
Standard Mode
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
In standard mode, there are always two sound channels, i.e., the left and right channels, which are called "slots". These slots support 8/16/24/32-bit width sample data. The communication format for the slots mainly includes the followings:
|
||||
In standard mode, there are always two sound channels, i.e., the left and right channels, which are called "slots". These slots support 8/16/24/32-bit width sample data. The communication format for the slots mainly includes the following:
|
||||
|
||||
- **Philips Format**: Data signal has one-bit shift comparing to the WS signal, and the duty of WS signal is 50%.
|
||||
|
||||
|
||||
@ -420,7 +420,7 @@ A bytes encoder is created by calling :cpp:func:`rmt_new_bytes_encoder`. The byt
|
||||
A configuration structure :cpp:type:`rmt_bytes_encoder_config_t` should be provided in advance before calling :cpp:func:`rmt_new_bytes_encoder`:
|
||||
|
||||
- :cpp:member:`rmt_bytes_encoder_config_t::bit0` and :cpp:member:`rmt_bytes_encoder_config_t::bit1` are necessary to specify the encoder how to represent bit zero and bit one in the format of :cpp:type:`rmt_symbol_word_t`.
|
||||
- :cpp:member:`rmt_bytes_encoder_config_t::msb_first` sets the bit endianess of each byte. If it is set to true, the encoder encodes the **Most Significant Bit** first. Otherwise, it encodes the **Least Significant Bit** first.
|
||||
- :cpp:member:`rmt_bytes_encoder_config_t::msb_first` sets the bit endianness of each byte. If it is set to true, the encoder encodes the **Most Significant Bit** first. Otherwise, it encodes the **Least Significant Bit** first.
|
||||
|
||||
Besides the primitive encoders provided by the driver, the user can implement his own encoder by chaining the existing encoders together. A common encoder chain is shown as follows:
|
||||
|
||||
|
||||
@ -237,7 +237,7 @@ The application can call ``sdio_slave_transmit`` to send packets. In this case,
|
||||
There are several ways to use the ``arg`` in the queue parameter:
|
||||
|
||||
1. Directly point ``arg`` to a dynamic-allocated buffer, and use the ``arg`` to free it when transfer finished.
|
||||
2. Wrap transfer informations in a transfer structure, and point ``arg`` to the structure. You can use the structure to do more things like::
|
||||
2. Wrap transfer information in a transfer structure, and point ``arg`` to the structure. You can use the structure to do more things like::
|
||||
|
||||
typedef struct {
|
||||
uint8_t* buffer;
|
||||
|
||||
@ -15,7 +15,7 @@ Some features are not supported on all ESP chips and Flash chips. You can check
|
||||
|
||||
.. note::
|
||||
|
||||
When Flash optional features listed in this page are used, aside from the capability of ESP chips, and ESP-IDF verison you are using, you will also need to make sure these features are supported by flash chips used.
|
||||
When Flash optional features listed in this page are used, aside from the capability of ESP chips, and ESP-IDF version you are using, you will also need to make sure these features are supported by flash chips used.
|
||||
|
||||
- If you are using an official Espressif modules/SiP. Some of the modules/SiPs always support the feature, in this case you can see these features listed in the datasheet. Otherwise please contact `Espressif's business team <https://www.espressif.com/en/contact-us/sales-questions>`_ to know if we can supply such products for you.
|
||||
|
||||
@ -169,7 +169,7 @@ Restrictions
|
||||
|
||||
By default, space over 16 MBytes on flash mentioned above can be used for ``data saving``, like file system.
|
||||
|
||||
Furhtermore, to map data/instructions to 32-bit physical address space (so as to be accessed by the CPU), please enable the config ``IDF_EXPERIMENTAL_FEATURES`` and ``BOOTLOADER_CACHE_32BIT_ADDR_QUAD_FLASH``.
|
||||
Furthermore, to map data/instructions to 32-bit physical address space (so as to be accessed by the CPU), please enable the config ``IDF_EXPERIMENTAL_FEATURES`` and ``BOOTLOADER_CACHE_32BIT_ADDR_QUAD_FLASH``.
|
||||
|
||||
Please note that, this option is experimental, which means it can not be used on all flash chips stably. For more information, please contact Espressif Business Support.
|
||||
|
||||
|
||||
@ -157,7 +157,7 @@ Method of Measurements
|
||||
|
||||
.. note::
|
||||
|
||||
If the specified clock cycles for measurement is too samll, the result may be inaccurate, but increasing clock cycles will increase the power consumption as well. Additionally, the response of the touch sensor will slow down if the total time of the inverval and measurement is too long.
|
||||
If the specified clock cycles for measurement is too small, the result may be inaccurate, but increasing clock cycles will increase the power consumption as well. Additionally, the response of the touch sensor will slow down if the total time of the interval and measurement is too long.
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
@ -165,7 +165,7 @@ Method of Measurements
|
||||
|
||||
.. note::
|
||||
|
||||
If the specified charge and discharge cycles for measurement is too samll, the result may be inaccurate, but increasing charge and discharge cycles will increase the power consumption as well. Additionally, the response of the touch sensor will slow down if the total time of the inverval and measurement is too long.
|
||||
If the specified charge and discharge cycles for measurement is too small, the result may be inaccurate, but increasing charge and discharge cycles will increase the power consumption as well. Additionally, the response of the touch sensor will slow down if the total time of the interval and measurement is too long.
|
||||
|
||||
Optimization of Measurements
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -239,7 +239,7 @@ Filtering of Measurements
|
||||
|
||||
There is an internal touch channel that is not connected to any external GPIO. The measurements from this denoise pad can be used to filters out interference introduced on all channels, such as noise introduced by the power supply and external EMI.
|
||||
|
||||
The denoise paramaters are set with the function :cpp:func:`touch_pad_denoise_set_config` and started by with :cpp:func:`touch_pad_denoise_enable`
|
||||
The denoise parameters are set with the function :cpp:func:`touch_pad_denoise_set_config` and started by with :cpp:func:`touch_pad_denoise_enable`
|
||||
|
||||
There is also a configurable hardware implemented IIR-filter (infinite impulse response). This IIR-filter is configured with the function :cpp:func:`touch_pad_filter_set_config` and enabled by calling :cpp:func:`touch_pad_filter_enable`
|
||||
|
||||
|
||||
@ -28,7 +28,7 @@ Check out the example functions ``http_rest_with_url`` and ``http_rest_with_host
|
||||
Persistent Connections
|
||||
----------------------
|
||||
|
||||
Persistent connection means that the HTTP client can re-use the same connection for several exchanges. If the server does not request to close the connection with the ``Connection: close`` header, the connection is not dropped but is instead kept open and used for further requests.
|
||||
Persistent connection means that the HTTP client can reuse the same connection for several exchanges. If the server does not request to close the connection with the ``Connection: close`` header, the connection is not dropped but is instead kept open and used for further requests.
|
||||
|
||||
To allow ESP HTTP client to take full advantage of persistent connections, one should make as many requests as possible using the same handle instance. Check out the example functions ``http_rest_with_url`` and ``http_rest_with_hostname_path`` in the application example. Here, once the connection is created, multiple requests (``GET``, ``POST``, ``PUT``, etc.) are made before the connection is closed.
|
||||
|
||||
|
||||
@ -112,7 +112,7 @@ Check HTTP server example under :example:`protocols/http_server/simple` where ha
|
||||
Persistent Connections
|
||||
----------------------
|
||||
|
||||
HTTP server features persistent connections, allowing for the re-use of the same connection (session) for several transfers, all the while maintaining context specific data for the session. Context data may be allocated dynamically by the handler in which case a custom function may need to be specified for freeing this data when the connection/session is closed.
|
||||
HTTP server features persistent connections, allowing for the reuse of the same connection (session) for several transfers, all the while maintaining context specific data for the session. Context data may be allocated dynamically by the handler in which case a custom function may need to be specified for freeing this data when the connection/session is closed.
|
||||
|
||||
Persistent Connections Example
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -66,7 +66,7 @@ Broker address can be set by usage of :cpp:class:`address <esp_mqtt_client_confi
|
||||
|
||||
The :cpp:member:`uri <esp_mqtt_client_config_t::broker_t::address_t::uri>` field is used in the format ``scheme://hostname:port/path``.
|
||||
|
||||
- Curently support ``mqtt``, ``mqtts``, ``ws``, ``wss`` schemes
|
||||
- Currently support ``mqtt``, ``mqtts``, ``ws``, ``wss`` schemes
|
||||
- MQTT over TCP samples:
|
||||
|
||||
- ``mqtt://mqtt.eclipseprojects.io``: MQTT over TCP, default port 1883
|
||||
|
||||
@ -6,7 +6,7 @@ Unified Provisioning
|
||||
Overview
|
||||
>>>>>>>>
|
||||
|
||||
The unified provisioning support in the ESP-IDF provides an extensible mechanism to the developers to configure the device with the Wi-Fi credentials and/or other custom configuration using various transports and different security schemes. Depending on the use case, it provides a complete and ready solution for Wi-Fi network provisioning along with example iOS and Android applications. The developers can choose to extend the device-side and phone-app side implementations to accommodate their requirements for sending additional configuration data. The followings are the important features of this implementation:
|
||||
The unified provisioning support in the ESP-IDF provides an extensible mechanism to the developers to configure the device with the Wi-Fi credentials and/or other custom configuration using various transports and different security schemes. Depending on the use case, it provides a complete and ready solution for Wi-Fi network provisioning along with example iOS and Android applications. The developers can choose to extend the device-side and phone-app side implementations to accommodate their requirements for sending additional configuration data. The following are the important features of this implementation:
|
||||
|
||||
1. **Extensible Protocol**
|
||||
|
||||
|
||||
@ -198,7 +198,7 @@ Alternatively, :cpp:func:`nvs_flash_secure_init` API function can also be used t
|
||||
NVS Security Provider
|
||||
---------------------
|
||||
|
||||
The component :component:`nvs_sec_provider` stores all the implementation-specific code for the NVS encryption schemes and would also accomodate any future schemes. This component acts as an interface to the :component:`nvs_flash` component for the handling of encryption keys. :component:`nvs_sec_provider` has a configuration menu of its own, based on which the selected security scheme and the corresponding settings are registered for the :component:`nvs_flash` component.
|
||||
The component :component:`nvs_sec_provider` stores all the implementation-specific code for the NVS encryption schemes and would also accommodate any future schemes. This component acts as an interface to the :component:`nvs_flash` component for the handling of encryption keys. :component:`nvs_sec_provider` has a configuration menu of its own, based on which the selected security scheme and the corresponding settings are registered for the :component:`nvs_flash` component.
|
||||
|
||||
.. only:: SOC_HMAC_SUPPORTED
|
||||
|
||||
|
||||
@ -58,7 +58,7 @@ There are the following functions available:
|
||||
|
||||
In general, all iterators obtained via :cpp:func:`nvs_entry_find` have to be released using :cpp:func:`nvs_release_iterator`, which also tolerates ``NULL`` iterators.
|
||||
|
||||
:cpp:func:`nvs_entry_find` and :cpp:func:`nvs_entry_next` set the given iterator to ``NULL`` or a valid iterator in all cases except a parameter error occured (i.e., return ``ESP_ERR_NVS_NOT_FOUND``). In case of a parameter error, the given iterator will not be modified. Hence, it is best practice to initialize the iterator to ``NULL`` before calling :cpp:func:`nvs_entry_find` to avoid complicated error checking before releasing the iterator.
|
||||
:cpp:func:`nvs_entry_find` and :cpp:func:`nvs_entry_next` set the given iterator to ``NULL`` or a valid iterator in all cases except a parameter error occurred (i.e., return ``ESP_ERR_NVS_NOT_FOUND``). In case of a parameter error, the given iterator will not be modified. Hence, it is best practice to initialize the iterator to ``NULL`` before calling :cpp:func:`nvs_entry_find` to avoid complicated error checking before releasing the iterator.
|
||||
|
||||
|
||||
Security, Tampering, and Robustness
|
||||
@ -101,7 +101,7 @@ Instead of calling the ``nvs_partition_gen.py`` tool manually, the creation of t
|
||||
* - Parameter
|
||||
- Description
|
||||
* - ``partition``
|
||||
- Name of the NVS parition
|
||||
- Name of the NVS partition
|
||||
* - ``csv``
|
||||
- Path to CSV file to parse
|
||||
|
||||
@ -114,12 +114,12 @@ Instead of calling the ``nvs_partition_gen.py`` tool manually, the creation of t
|
||||
* - Parameter
|
||||
- Description
|
||||
* - ``FLASH_IN_PROJECT``
|
||||
- Name of the NVS parition
|
||||
- Name of the NVS partition
|
||||
* - ``DEPENDS``
|
||||
- Specify files on which the command depends
|
||||
|
||||
|
||||
If ``FLASH_IN_PROJECT`` is not specified, the image will still be generated, but you will have to flash it manually using ``idf.py <partition>-flash`` (e.g., if your parition name is ``nvs``, then use ``idf.py nvs-flash``).
|
||||
If ``FLASH_IN_PROJECT`` is not specified, the image will still be generated, but you will have to flash it manually using ``idf.py <partition>-flash`` (e.g., if your partition name is ``nvs``, then use ``idf.py nvs-flash``).
|
||||
|
||||
``nvs_create_partition_image`` must be called from one of the component ``CMakeLists.txt`` files. Currently, only non-encrypted partitions are supported.
|
||||
|
||||
|
||||
@ -45,7 +45,7 @@ For more details, see **{IDF_TARGET_NAME} Technical Reference Manual** > **eFuse
|
||||
:SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK and SOC_ECDSA_SUPPORTED: * EFUSE_BLK9 (also named EFUSE_BLK_KEY5) can be used for any purpose except for flash encryption or ECDSA (due to a HW bug);
|
||||
:SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK and not SOC_ECDSA_SUPPORTED: * EFUSE_BLK9 (also named EFUSE_BLK_KEY5) can be used for any purpose except for flash encryption (due to a HW bug);
|
||||
:not SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK: * EFUSE_BLK9 (also named EFUSE_BLK_KEY5) can be used as key (for secure_boot or flash_encryption) or for user purposes;
|
||||
* EFUSE_BLK10 (also named EFUSE_BLK_SYS_DATA_PART2) is reseved for system purposes.
|
||||
* EFUSE_BLK10 (also named EFUSE_BLK_SYS_DATA_PART2) is reserved for system purposes.
|
||||
|
||||
.. only:: esp32c2
|
||||
|
||||
@ -163,9 +163,9 @@ Solution: Describe ``SERIAL_NUMBER`` to be included in ``USER_DATA``. (``USER_DA
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
Field at FEILD, EFUSE_BLK3, 0, 50 out of range FEILD.MAJOR_NUMBER, EFUSE_BLK3, 60, 32
|
||||
Field at FIELD, EFUSE_BLK3, 0, 50 out of range FIELD.MAJOR_NUMBER, EFUSE_BLK3, 60, 32
|
||||
|
||||
Solution: Change ``bit_start`` for ``FIELD.MAJOR_NUMBER`` from 60 to 0, so ``MAJOR_NUMBER`` is in the ``FEILD`` range.
|
||||
Solution: Change ``bit_start`` for ``FIELD.MAJOR_NUMBER`` from 60 to 0, so ``MAJOR_NUMBER`` is in the ``FIELD`` range.
|
||||
|
||||
``efuse_table_gen.py`` Tool
|
||||
---------------------------
|
||||
@ -216,7 +216,7 @@ Supported Coding Scheme
|
||||
* ``Repeat`` (value 2).
|
||||
|
||||
The coding scheme affects only EFUSE_BLK1, EFUSE_BLK2 and EFUSE_BLK3 blocks. EUSE_BLK0 block always has a coding scheme ``None``.
|
||||
Coding changes the number of bits that can be written into a block, the block length is constant 256, some of these bits are used for encoding and not avaliable for the user.
|
||||
Coding changes the number of bits that can be written into a block, the block length is constant 256, some of these bits are used for encoding and not available for the user.
|
||||
|
||||
When using a coding scheme, the length of the payload that can be written is limited (for more details ``20.3.1.3 System Parameter coding_scheme``):
|
||||
|
||||
|
||||
@ -77,7 +77,7 @@
|
||||
e_download is disabled or enabled. 1: disabled. 0:
|
||||
enabled
|
||||
DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0) Represents whether flash encrypt function is disab = False R/W (0b0)
|
||||
led or enabled(except in SPI boot mode). 1: disabl
|
||||
led or enabled(except in SPI boot mode). 1: disable
|
||||
ed. 0: enabled
|
||||
SPI_BOOT_CRYPT_CNT (BLOCK0) Enables flash encryption when 1 or 3 bits are set = Disable R/W (0b000)
|
||||
and disables otherwise
|
||||
@ -105,7 +105,7 @@
|
||||
SECURE_VERSION (BLOCK0) Represents the version used by ESP-IDF anti-rollba = 0 R/W (0x0000)
|
||||
ck feature
|
||||
SECURE_BOOT_DISABLE_FAST_WAKE (BLOCK0) Represents whether FAST VERIFY ON WAKE is disabled = False R/W (0b0)
|
||||
or enabled when Secure Boot is enabled. 1: disabl
|
||||
or enabled when Secure Boot is enabled. 1: disable
|
||||
ed. 0: enabled
|
||||
BLOCK_KEY0 (BLOCK4)
|
||||
Purpose: USER
|
||||
|
||||
@ -76,7 +76,7 @@
|
||||
e_download is disabled or enabled. 1: disabled. 0:
|
||||
enabled
|
||||
DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0) Represents whether flash encrypt function is disab = False R/W (0b0)
|
||||
led or enabled(except in SPI boot mode). 1: disabl
|
||||
led or enabled(except in SPI boot mode). 1: disable
|
||||
ed. 0: enabled
|
||||
SPI_BOOT_CRYPT_CNT (BLOCK0) Enables flash encryption when 1 or 3 bits are set = Disable R/W (0b000)
|
||||
and disables otherwise
|
||||
@ -107,7 +107,7 @@
|
||||
SECURE_VERSION (BLOCK0) Represents the version used by ESP-IDF anti-rollba = 0 R/W (0x0000)
|
||||
ck feature
|
||||
SECURE_BOOT_DISABLE_FAST_WAKE (BLOCK0) Represents whether FAST VERIFY ON WAKE is disabled = False R/W (0b0)
|
||||
or enabled when Secure Boot is enabled. 1: disabl
|
||||
or enabled when Secure Boot is enabled. 1: disable
|
||||
ed. 0: enabled
|
||||
BLOCK_KEY0 (BLOCK4)
|
||||
Purpose: USER
|
||||
|
||||
@ -31,7 +31,7 @@
|
||||
eset at low level. 10: enable printing when GPIO8
|
||||
is reset at high level. 11: force disable printing
|
||||
HYS_EN_PAD (BLOCK0) Represents whether the hysteresis function of corr = False R/W (0b0)
|
||||
esponding PAD is enabled. 1: enabled. 0:disabled
|
||||
corresponding PAD is enabled. 1: enabled. 0:disabled
|
||||
DCDC_VSET (BLOCK0) Set the dcdc voltage default = 0 R/W (0b00000)
|
||||
PXA0_TIEH_SEL_0 (BLOCK0) TBD = 0 R/W (0b00)
|
||||
PXA0_TIEH_SEL_1 (BLOCK0) TBD = 0 R/W (0b00)
|
||||
@ -100,7 +100,7 @@
|
||||
SPI_DOWNLOAD_MSPI_DIS (BLOCK0) Set this bit to disable accessing MSPI flash/MSPI = False R/W (0b0)
|
||||
ram by SYS AXI matrix during boot_mode_download
|
||||
DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0) Represents whether flash encrypt function is disab = False R/W (0b0)
|
||||
led or enabled(except in SPI boot mode). 1: disabl
|
||||
led or enabled(except in SPI boot mode). 1: disable
|
||||
ed. 0: enabled
|
||||
FORCE_USE_KEY_MANAGER_KEY (BLOCK0) Set each bit to control whether corresponding key = 0 R/W (0x0)
|
||||
must come from key manager.. 1 is true; 0 is false
|
||||
@ -139,7 +139,7 @@
|
||||
SECURE_VERSION (BLOCK0) Represents the version used by ESP-IDF anti-rollba = 0 R/W (0x0000)
|
||||
ck feature
|
||||
SECURE_BOOT_DISABLE_FAST_WAKE (BLOCK0) Represents whether FAST VERIFY ON WAKE is disabled = False R/W (0b0)
|
||||
or enabled when Secure Boot is enabled. 1: disabl
|
||||
or enabled when Secure Boot is enabled. 1: disable
|
||||
ed. 0: enabled
|
||||
BLOCK_KEY0 (BLOCK4)
|
||||
Purpose: USER
|
||||
|
||||
@ -48,7 +48,7 @@ Virtual Memory Capabilities
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
4 MB external memory addresses (from 0x40400000 to 0x40800000) which have the :cpp:enumerator:`MMU_MEM_CAP_EXEC` and :cpp:enumerator:`MMU_MEM_CAP_READ` capabilities are not avaiable for users to allocate, due to hardware limitations.
|
||||
4 MB external memory addresses (from 0x40400000 to 0x40800000) which have the :cpp:enumerator:`MMU_MEM_CAP_EXEC` and :cpp:enumerator:`MMU_MEM_CAP_READ` capabilities are not available for users to allocate, due to hardware limitations.
|
||||
|
||||
|
||||
You can call :cpp:func:`esp_mmu_map_get_max_consecutive_free_block_size` to know the largest consecutive mappable block size with certain capabilities.
|
||||
|
||||
@ -239,7 +239,7 @@ The created object can now be used to perform operations on the target device:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Erase otadata, reseting the device to factory app
|
||||
# Erase otadata, resetting the device to factory app
|
||||
target.erase_otadata()
|
||||
|
||||
# Erase contents of OTA app slot 0
|
||||
|
||||
@ -98,7 +98,7 @@ Dynamic Frequency Scaling and Peripheral Drivers
|
||||
|
||||
When DFS is enabled, the APB frequency can be changed multiple times within a single RTOS tick. The APB frequency change does not affect the operation of some peripherals, while other peripherals may have issues. For example, Timer Group peripheral timers keeps counting, however, the speed at which they count changes proportionally to the APB frequency.
|
||||
|
||||
Peripheral clock sources such as ``REF_TICK``, ``XTAL``, ``RC_FAST`` (i.e., ``RTC_8M``), their frequencies will not be inflenced by APB frequency. And therefore, to ensure the peripheral behaves consistently during DFS, it is recommanded to select one of these clocks as the peripheral clock source. For more specific guidelines, please refer to the "Power Management" section of each peripheral's "API Reference > Peripherals API" page.
|
||||
Peripheral clock sources such as ``REF_TICK``, ``XTAL``, ``RC_FAST`` (i.e., ``RTC_8M``), their frequencies will not be inflenced by APB frequency. And therefore, to ensure the peripheral behaves consistently during DFS, it is recommended to select one of these clocks as the peripheral clock source. For more specific guidelines, please refer to the "Power Management" section of each peripheral's "API Reference > Peripherals API" page.
|
||||
|
||||
Currently, the following peripheral drivers are aware of DFS and use the ``ESP_PM_APB_FREQ_MAX`` lock for the duration of the transaction:
|
||||
|
||||
|
||||
@ -16,7 +16,7 @@ The ULP LP-Core coprocessor has the following features:
|
||||
Compiling Code for the ULP LP-Core
|
||||
----------------------------------
|
||||
|
||||
The ULP LP-Core code is compiled together with your ESP-IDF project as a separate binary and automatically embedded into the main project binary. To acheive this do the following:
|
||||
The ULP LP-Core code is compiled together with your ESP-IDF project as a separate binary and automatically embedded into the main project binary. To achieve this do the following:
|
||||
|
||||
1. Place the ULP LP-Core code, written in C or assembly (with the ``.S`` extension), in a dedicated directory within the component directory, such as ``ulp/``.
|
||||
|
||||
|
||||
@ -29,7 +29,7 @@ The ``program`` array is an array of ``ulp_insn_t``, i.e., ULP coprocessor instr
|
||||
|
||||
To generate branch instructions, special ``M_`` preprocessor defines are used. ``M_LABEL`` define can be used to define a branch target. Label identifier is a 16-bit integer. ``M_Bxxx`` defines can be used to generate branch instructions with target set to a particular label.
|
||||
|
||||
Implementation note: these ``M_`` preprocessor defines will be translated into two ulp_insn_t values: one is a token value which contains label number, and the other is the actual instruction. ``ulp_process_macros_and_load`` function resolves the label number to the address, modifies the branch instruction to use the correct address, and removes the extra ``ulp_insn_t`` token which contains the label numer.
|
||||
Implementation note: these ``M_`` preprocessor defines will be translated into two ulp_insn_t values: one is a token value which contains label number, and the other is the actual instruction. ``ulp_process_macros_and_load`` function resolves the label number to the address, modifies the branch instruction to use the correct address, and removes the extra ``ulp_insn_t`` token which contains the label number.
|
||||
|
||||
Here is an example of using labels and branches::
|
||||
|
||||
|
||||
@ -172,7 +172,7 @@ The following config options control TWDT configuration. They are all enabled by
|
||||
JTAG & Watchdogs
|
||||
----------------
|
||||
|
||||
While debugging using OpenOCD, the CPUs are halted every time a breakpoint is reached. However if the watchdog timers continue to run when a breakpoint is encountered, they will eventually trigger a reset making it very difficult to debug code. Therefore OpenOCD will disable the hardware timers of both the interrupt and task watchdogs at every breakpoint. Moreover, OpenOCD will not reenable them upon leaving the breakpoint. This means that interrupt watchdog and task watchdog functionality will essentially be disabled. No warnings or panics from either watchdogs will be generated when the {IDF_TARGET_NAME} is connected to OpenOCD via JTAG.
|
||||
While debugging using OpenOCD, the CPUs are halted every time a breakpoint is reached. However if the watchdog timers continue to run when a breakpoint is encountered, they will eventually trigger a reset making it very difficult to debug code. Therefore OpenOCD will disable the hardware timers of both the interrupt and task watchdogs at every breakpoint. Moreover, OpenOCD will not re-enable them upon leaving the breakpoint. This means that interrupt watchdog and task watchdog functionality will essentially be disabled. No warnings or panics from either watchdogs will be generated when the {IDF_TARGET_NAME} is connected to OpenOCD via JTAG.
|
||||
|
||||
|
||||
API Reference
|
||||
|
||||
@ -33,7 +33,7 @@ The simplest case is when the code is not based on any licensed previous work, e
|
||||
Less Restrictive Parts of ESP-IDF
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Some parts of ESP-IDF are deliberately under less restrictive licenses in order to ease their re-use in commercial closed source projects. This is the case for :project:`ESP-IDF examples <examples>` which are in Public domain or under the Creative Commons Zero Universal (CC0) license. The following header can be used in such source files::
|
||||
Some parts of ESP-IDF are deliberately under less restrictive licenses in order to ease their reuse in commercial closed source projects. This is the case for :project:`ESP-IDF examples <examples>` which are in Public domain or under the Creative Commons Zero Universal (CC0) license. The following header can be used in such source files::
|
||||
|
||||
/*
|
||||
* SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
|
||||
|
||||
@ -228,7 +228,7 @@ The scripts introduced in this step install compilation tools required by ESP-ID
|
||||
If changing the ``IDF_TOOLS_PATH``, make sure it is exported in the environment before running any ESP-IDF tools or scripts.
|
||||
|
||||
.. note::
|
||||
Using ``IDF_TOOLS_PATH`` in variable assignement, e.g., ``IDF_TOOLS_PATH="$HOME/required_idf_tools_path" ./install.sh``, without prior exporting, will not work in most shells because the variable assignment will not affect the current execution environment, even if it's exported/changed in the sourced script.
|
||||
Using ``IDF_TOOLS_PATH`` in variable assignment, e.g., ``IDF_TOOLS_PATH="$HOME/required_idf_tools_path" ./install.sh``, without prior exporting, will not work in most shells because the variable assignment will not affect the current execution environment, even if it's exported/changed in the sourced script.
|
||||
|
||||
.. _get-started-set-up-env:
|
||||
|
||||
|
||||
@ -24,7 +24,7 @@ The document consists of the following major sections:
|
||||
|
||||
- `Getting started`_: Provides an overview of the ESP32-DevKitM-1 and hardware/software setup instructions to get started.
|
||||
- `Hardware reference`_: Provides more detailed information about the ESP32-DevKitM-1's hardware.
|
||||
- `Related Documents`_: Gives links to related documentaiton.
|
||||
- `Related Documents`_: Gives links to related documentation.
|
||||
|
||||
|
||||
Getting Started
|
||||
|
||||
@ -81,7 +81,7 @@ The ESP32-S2-Kaluga-1 board has connectors for boards with:
|
||||
|
||||
ESP32-S2-Kaluga-1 (click to enlarge)
|
||||
|
||||
All the four extension boards are specially desgined to support the following features:
|
||||
All the four extension boards are specially designed to support the following features:
|
||||
|
||||
* Touch panel control
|
||||
* Six touch buttons
|
||||
|
||||
@ -68,7 +68,7 @@ The ESP32-S2-Kaluga-1 board has connectors for boards with:
|
||||
|
||||
- Extension header (ESP-LyraT-8311A, ESP-LyraP-LCD32)
|
||||
- Camera header (ESP-LyraP-CAM)
|
||||
- Touch FPC coneector (ESP-LyraP-TouchA)
|
||||
- Touch FPC connector (ESP-LyraP-TouchA)
|
||||
- LCD FPC connector (no official extension boards yet)
|
||||
- I2C FPC connector (no official extension boards yet)
|
||||
|
||||
@ -82,7 +82,7 @@ The ESP32-S2-Kaluga-1 board has connectors for boards with:
|
||||
|
||||
ESP32-S2-Kaluga-1 (click to enlarge)
|
||||
|
||||
All the four extension boards are specially desgined to support the following features:
|
||||
All the four extension boards are specially designed to support the following features:
|
||||
|
||||
* Touch panel control
|
||||
* Six touch buttons
|
||||
|
||||
@ -475,7 +475,7 @@ LCD
|
||||
Independent TX/RX channels
|
||||
""""""""""""""""""""""""""
|
||||
|
||||
The minimum control unit in new I2S driver are now individual TX/RX channels instead of an entire I2S controller (that consistes of multiple channels).
|
||||
The minimum control unit in new I2S driver are now individual TX/RX channels instead of an entire I2S controller (that consists of multiple channels).
|
||||
|
||||
- The TX and RX channels of the same I2S controller can be controlled separately, meaning that they are configured such that they can be started or stopped separately.
|
||||
- The :cpp:type:`i2s_chan_handle_t` handle type is used to uniquely identify I2S channels. All the APIs require the channel handle and users need to maintain the channel handles by themselves.
|
||||
@ -516,7 +516,7 @@ LCD
|
||||
|
||||
To use the new I2S driver, please follow these steps:
|
||||
|
||||
1. Call :cpp:func:`i2s_new_channel` to acquire channel handles. We should specify the work role and I2S port in this step. Besides, the TX or RX channel handle will be generated by the driver. Inputting both two TX and RX channel handles is not necessary but at least one handle is needed. In the case of inputting both two handles, the driver will work at the duplex mode. Both TX and RX channels will be avaliable on a same port, and they will share the MCLK, BCLK and WS signal. But if only one of the TX or RX channel handle is inputted, this channel will only work in the simplex mode.
|
||||
1. Call :cpp:func:`i2s_new_channel` to acquire channel handles. We should specify the work role and I2S port in this step. Besides, the TX or RX channel handle will be generated by the driver. Inputting both two TX and RX channel handles is not necessary but at least one handle is needed. In the case of inputting both two handles, the driver will work at the duplex mode. Both TX and RX channels will be available on a same port, and they will share the MCLK, BCLK and WS signal. But if only one of the TX or RX channel handle is inputted, this channel will only work in the simplex mode.
|
||||
2. Call :func:`i2s_channel_init_std_mode`, :func:`i2s_channel_init_pdm_rx_mode`, :func:`i2s_channel_init_pdm_tx_mode` or :func:`i2s_channel_init_tdm_mode` to initialize the channel to the specified mode. Corresponding slot, clock and GPIO configurations are needed in this step.
|
||||
3. (Optional) Call :cpp:func:`i2s_channel_register_event_callback` to register the ISR event callback functions. I2S events now can be received by the callback function synchronously, instead of from the event queue asynchronously.
|
||||
4. Call :cpp:func:`i2s_channel_enable` to start the hardware of I2S channel. In the new driver, I2S does not start automatically after installed, and users are supposed to know clearly whether the channel has started or not.
|
||||
|
||||
@ -34,7 +34,7 @@ SDMMC/SDSPI
|
||||
|
||||
SD card frequency on SDMMC/SDSPI interface can be now configured through ``sdmmc_host_t.max_freq_khz`` to a specific value, not only ``SDMMC_FREQ_PROBING`` (400 kHz), ``SDMMC_FREQ_DEFAULT`` (20 MHz), or ``SDMMC_FREQ_HIGHSPEED`` (40 MHz). Previously, in case you have specified a custom frequency other than any of the above-mentioned values, the closest lower-or-equal one was selected anyway.
|
||||
|
||||
Now, the underlaying drivers calculate the nearest fitting value, given by available frequency dividers instead of an enumeration item selection. This could cause troubles in communication with your SD card without a change of the existing application code.If you encounter such an issue, please, keep trying different frequencies around your desired value unless you find the one working well. To check the frequency value calculated and actually applied, use ``void sdmmc_card_print_info(FILE* stream, const sdmmc_card_t* card)`` function.
|
||||
Now, the underlying drivers calculate the nearest fitting value, given by available frequency dividers instead of an enumeration item selection. This could cause troubles in communication with your SD card without a change of the existing application code.If you encounter such an issue, please, keep trying different frequencies around your desired value unless you find the one working well. To check the frequency value calculated and actually applied, use ``void sdmmc_card_print_info(FILE* stream, const sdmmc_card_t* card)`` function.
|
||||
|
||||
FatFs
|
||||
-----
|
||||
|
||||
@ -28,7 +28,7 @@ The Cache Error Interrupt API (functions/types/macros prefixed with ``esp_cache_
|
||||
----------------------
|
||||
|
||||
* The function ``bootloader_common_get_reset_reason()`` has been removed. Please use the function ``esp_rom_get_reset_reason()`` in the ROM component.
|
||||
* The functions ``esp_secure_boot_verify_sbv2_signature_block()`` and ``esp_secure_boot_verify_rsa_signature_block()`` have been removed without replacement. We do not expect users to use these directly. If they are indeed still neccessary, please open a feature request on `GitHub <https://github.com/espressif/esp-idf/issues/new/choose>`_ explaining why these functions are necessary to you.
|
||||
* The functions ``esp_secure_boot_verify_sbv2_signature_block()`` and ``esp_secure_boot_verify_rsa_signature_block()`` have been removed without replacement. We do not expect users to use these directly. If they are indeed still necessary, please open a feature request on `GitHub <https://github.com/espressif/esp-idf/issues/new/choose>`_ explaining why these functions are necessary to you.
|
||||
|
||||
Brownout
|
||||
--------
|
||||
@ -125,7 +125,7 @@ FreeRTOS
|
||||
Legacy API and Data Types
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Previously, the ``configENABLE_BACKWARD_COMPATIBILITY`` option was set by default, thus allowing pre FreeRTOS v8.0.0 function names and data types to be used. The ``configENABLE_BACKWARD_COMPATIBILITY`` is now disabled by default, thus legacy FreeRTOS names/types are no longer supportd by default. Users should do one of the followings:
|
||||
Previously, the ``configENABLE_BACKWARD_COMPATIBILITY`` option was set by default, thus allowing pre FreeRTOS v8.0.0 function names and data types to be used. The ``configENABLE_BACKWARD_COMPATIBILITY`` is now disabled by default, thus legacy FreeRTOS names/types are no longer supported by default. Users should do one of the following:
|
||||
|
||||
- Update their code to remove usage of legacy FreeRTOS names/types.
|
||||
- Enable the :ref:`CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY` to explicitly allow the usage of legacy names/types.
|
||||
|
||||
@ -159,7 +159,7 @@ The flash encryption operation is controlled by various eFuses available on {IDF
|
||||
.. note::
|
||||
|
||||
* R/W access control is available for all the eFuse bits listed in the table above.
|
||||
* The default value of these bits is 0 afer manufacturing.
|
||||
* The default value of these bits is 0 after manufacturing.
|
||||
|
||||
Read and write access to eFuse bits is controlled by appropriate fields in the registers ``WR_DIS`` and ``RD_DIS``. For more information on {IDF_TARGET_NAME} eFuses, see :doc:`eFuse manager <../api-reference/system/efuse>`. To change protection bits of eFuse field using espefuse.py, use these two commands: read_protect_efuse and write_protect_efuse. Example ``espefuse.py write_protect_efuse DISABLE_DL_ENCRYPT``.
|
||||
|
||||
@ -180,7 +180,7 @@ Assuming that the eFuse values are in their default states and the firmware boot
|
||||
|
||||
2. Firmware bootloader reads the ``{IDF_TARGET_CRYPT_CNT}`` eFuse value (``0b0000000``). Since the value is ``0`` (even number of bits set), it configures and enables the flash encryption block. It also sets the ``FLASH_CRYPT_CONFIG`` eFuse to 0xF. For more information on the flash encryption block, see *{IDF_TARGET_NAME} Technical Reference Manual* > *eFuse Controller (eFuse)* > *Flash Encryption Block* [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].
|
||||
|
||||
3. Fimware bootloader first checks if a valid key is already present in the eFuse (e.g., burned using espefuse tool), then the process of key generation is skipped and the same key is used for flash encryption process. Otherwise, Firmware bootloader uses RNG (random) module to generate an AES-256 bit key and then writes it into the ``flash_encryption`` eFuse. The key cannot be accessed via software as the write and read protection bits for the ``flash_encryption`` eFuse are set. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software.
|
||||
3. Firmware bootloader first checks if a valid key is already present in the eFuse (e.g., burned using espefuse tool), then the process of key generation is skipped and the same key is used for flash encryption process. Otherwise, Firmware bootloader uses RNG (random) module to generate an AES-256 bit key and then writes it into the ``flash_encryption`` eFuse. The key cannot be accessed via software as the write and read protection bits for the ``flash_encryption`` eFuse are set. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software.
|
||||
|
||||
4. Flash encryption block encrypts the flash contents - the firmware bootloader, applications and partitions marked as ``encrypted``. Encrypting in-place can take time, up to a minute for large partitions.
|
||||
|
||||
@ -1052,7 +1052,7 @@ The following sections provide some reference information about the operation of
|
||||
- If the ``CODING_SCHEME`` eFuse is set to ``0`` (default, "None" Coding Scheme) then the eFuse key block is 256 bits and the key is stored as-is (in reversed byte order).
|
||||
- If the ``CODING_SCHEME`` eFuse is set to ``1`` (3/4 Encoding) then the eFuse key block is 192 bits (in reversed byte order), so overall entropy is reduced. The hardware flash encryption still operates on a 256-bit key, after being read (and un-reversed), the key is extended as ``key = key[0:255] + key[64:127]``.
|
||||
|
||||
- AES algorithm is used inverted in flash encryption, so the flash encryption "encrypt" operation is AES decrypt and the "decrypt" operation is AES encrypt. This is for performance reasons and does not alter the effeciency of the algorithm.
|
||||
- AES algorithm is used inverted in flash encryption, so the flash encryption "encrypt" operation is AES decrypt and the "decrypt" operation is AES encrypt. This is for performance reasons and does not alter the efficiency of the algorithm.
|
||||
|
||||
- Each 32-byte block (two adjacent 16-byte AES blocks) is encrypted with a unique key. The key is derived from the main flash encryption key in ``flash_encryption``, XORed with the offset of this block in the flash (a "key tweak").
|
||||
|
||||
@ -1094,9 +1094,9 @@ The following sections provide some reference information about the operation of
|
||||
Flash Encryption Algorithm
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- {IDF_TARGET_NAME} use the XTS-AES block chiper mode with 256 bit size for flash encryption.
|
||||
- {IDF_TARGET_NAME} use the XTS-AES block cipher mode with 256 bit size for flash encryption.
|
||||
|
||||
- XTS-AES is a block chiper mode specifically designed for disc encryption and addresses the weaknesses other potential modes (e.g., AES-CTR) have for this use case. A detailed description of the XTS-AES algorithm can be found in `IEEE Std 1619-2007 <https://ieeexplore.ieee.org/document/4493450>`_.
|
||||
- XTS-AES is a block cipher mode specifically designed for disc encryption and addresses the weaknesses other potential modes (e.g., AES-CTR) have for this use case. A detailed description of the XTS-AES algorithm can be found in `IEEE Std 1619-2007 <https://ieeexplore.ieee.org/document/4493450>`_.
|
||||
|
||||
- The flash encryption key is stored in one ``BLOCK_KEYN`` eFuse and, by default, is protected from further writes or software readout.
|
||||
|
||||
@ -1109,9 +1109,9 @@ The following sections provide some reference information about the operation of
|
||||
Flash Encryption Algorithm
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- {IDF_TARGET_NAME} use the XTS-AES block chiper mode with 256 bit size for flash encryption. In case the 128-bit key is stored in the eFuse key block, the final 256-bit AES key is obtained as SHA256(EFUSE_KEY0_FE_128BIT).
|
||||
- {IDF_TARGET_NAME} use the XTS-AES block cipher mode with 256 bit size for flash encryption. In case the 128-bit key is stored in the eFuse key block, the final 256-bit AES key is obtained as SHA256(EFUSE_KEY0_FE_128BIT).
|
||||
|
||||
- XTS-AES is a block chiper mode specifically designed for disc encryption and addresses the weaknesses other potential modes (e.g., AES-CTR) have for this use case. A detailed description of the XTS-AES algorithm can be found in `IEEE Std 1619-2007 <https://ieeexplore.ieee.org/document/4493450>`_.
|
||||
- XTS-AES is a block cipher mode specifically designed for disc encryption and addresses the weaknesses other potential modes (e.g., AES-CTR) have for this use case. A detailed description of the XTS-AES algorithm can be found in `IEEE Std 1619-2007 <https://ieeexplore.ieee.org/document/4493450>`_.
|
||||
|
||||
- The flash encryption key is stored in ``BLOCK_KEY0`` eFuse and, by default, is protected from further writes or software readout.
|
||||
|
||||
|
||||
@ -581,7 +581,7 @@ Secure Boot Best Practices
|
||||
|
||||
Key revocation is not applicable unless secure boot is successfully enabled. Also, a key is not revoked in case of invalid signature block or invalid image digest, it is only revoked in case the signature verification fails, i.e., revoke key only if failure in step 3 of :ref:`verify_image`
|
||||
|
||||
Once a key is revoked, it can never be used for verfying a signature of an image. This feature provides strong resistance against physical attacks on the device. However, this could also brick the device permanently if all the keys are revoked because of signature verification failure.
|
||||
Once a key is revoked, it can never be used for verifying a signature of an image. This feature provides strong resistance against physical attacks on the device. However, this could also brick the device permanently if all the keys are revoked because of signature verification failure.
|
||||
|
||||
.. _secure-boot-v2-technical-details:
|
||||
|
||||
|
||||
@ -79,7 +79,7 @@ Flash Encryption Best Practices
|
||||
|
||||
.. only:: SOC_ECDSA_SUPPORTED
|
||||
|
||||
{IDF_TARGET_NAME} also supportes ECDSA peripheral for generating hardware-accelerated ECDSA digital signatures. ECDSA private key can be directly programmed in an eFuse block and marked as read protected from the software.
|
||||
{IDF_TARGET_NAME} also supports ECDSA peripheral for generating hardware-accelerated ECDSA digital signatures. ECDSA private key can be directly programmed in an eFuse block and marked as read protected from the software.
|
||||
|
||||
{IDF_TARGET_SIG_PERI} peripheral can help to establish the **Secure Device Identity** to the remote endpoint, e.g., in the case of TLS mutual authentication based on the {IDF_TARGET_CIPHER_SCHEME} cipher scheme.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user