Merge branch 'docs/add_app_examples_for_spi_master_twai_etc' into 'master'

docs: Update application examples for spi master, twai, and spi_slave

See merge request espressif/esp-idf!33276

docs/en/api-reference/peripherals/spi_master.rst

@@ -795,12 +795,13 @@ Please note that the ISR is disabled during flash operation by default. To keep
     4. ``cs_ena_pretrans`` is not compatible with the Command and Address phases of full-duplex transactions.
 
 
-Application Example
--------------------
+Application Examples
+--------------------
 
-The code example for using the SPI master half duplex mode to read/write an AT93C46D EEPROM (8-bit mode) can be found in the :example:`peripherals/spi_master/hd_eeprom` directory of ESP-IDF examples.
+- :example:`peripherals/spi_master/hd_eeprom` demonstrates how to use the SPI master half duplex mode to read/write an AT93C46D EEPROM (8-bit mode) on {IDF_TARGET_NAME}.
+
+- :example:`peripherals/spi_master/lcd` demonstrates how to use the SPI master driver to display an animation on the LCD. With the help of the DMA, we can do render and flush in parallel. This example also illustrates using the SPI transaction hook function to drive the D/C signal level.
 
-The code example for using the SPI master full duplex mode to drive a SPI_LCD (e.g. ST7789V or ILI9341) can be found in the :example:`peripherals/spi_master/lcd` directory of ESP-IDF examples.
 
 API Reference - SPI Common
 --------------------------

docs/en/api-reference/peripherals/spi_slave.rst

@@ -246,11 +246,15 @@ Restrictions and Known Issues
     If DMA is enabled, a Device's launch edge is half of an SPI clock cycle ahead of the normal time, shifting to the Master's actual latch edge. In this case, if the GPIO matrix is bypassed, the hold time for data sampling is 68.75 ns and no longer a half of an SPI clock cycle. If the GPIO matrix is used, the hold time will increase to 93.75 ns. The Host should sample the data immediately at the latch edge or communicate in SPI modes 1 or 3. If your Host cannot meet these timing requirements, initialize your Device without DMA.
 
 
-Application Example
--------------------
+Application Examples
+--------------------
 
 The code example for Device/Host communication can be found in the :example:`peripherals/spi_slave` directory of ESP-IDF examples.
 
+- :example: `peripherals/spi_slave/receiver` demonstrates how to configure an SPI slave to receive data from an SPI master and implement handshaking to manage data transfer readiness.
+
+- :example: `peripherals/spi_slave/sender` demonstrate how to configure an SPI master to send data to an SPI slave and use handshaking to ensure proper timing for data transmission.
+
 
 API Reference
 -------------

docs/en/api-reference/peripherals/spi_slave_hd.rst

@@ -122,10 +122,16 @@ Receiving General Purpose Interrupts from the Master
 When the master sends ``CMD8``, ``CMD9`` or ``CMDA``, the slave corresponding is triggered. Currently the ``CMD8`` is permanently used to indicate the termination of ``Rd_DMA`` segments. To receive general-purpose interrupts, register callbacks for ``CMD9`` and ``CMDA`` when the slave is initialized, see :ref:`spi_slave_hd_callbacks`.
 
 
-Application Example
--------------------
+.. only:: not esp32
 
-The code example for Device/Host communication can be found in the :example:`peripherals/spi_slave_hd` directory of ESP-IDF examples.
+  Application Examples
+  --------------------
+
+  The code example for Device/Host communication can be found in the :example:`peripherals/spi_slave_hd` directory of ESP-IDF examples.
+
+  - :example: `peripherals/spi_slave_hd/append_mode` demonstrates how to use the SPI Slave HD driver and ESSL driver to communicate (ESSL driver is an encapsulated layer based on SPI Master driver to communicate with halfduplex mode SPI Slave).
+
+  - :example: `peripherals/spi_slave_hd/segment_mode` demonstrate two ways to use the SPI Slave Halfduplex Segment Mode: Using the SPI Slave Halfduplex driver with two tasks repeating transactions with the SPI Master, and using the ESP Serial Slave Link APIs for multiple exchanges with the slave.
 
 
 API Reference

docs/en/api-reference/peripherals/twai.rst

@@ -593,11 +593,11 @@ The following example shows how to calculate the acceptance mask given multiple
 Application Examples
 ^^^^^^^^^^^^^^^^^^^^
 
-**Network Example:** The TWAI Network example demonstrates communication between two {IDF_TARGET_NAME}s using the TWAI driver API. One TWAI node acts as a network master that initiates and ceases the transfer of data from another node acting as a network slave. The example can be found via :example:`peripherals/twai/twai_network`.
+**Network Example:** :example:`peripherals/twai/twai_network` demonstrates communication between two {IDF_TARGET_NAME}s using the TWAI driver API. One TWAI node acts as a network master that initiates and ceases the transfer of data from another node acting as a network slave.
 
-**Alert and Recovery Example:** This example demonstrates how to use the TWAI driver's alert and bus-off recovery API. The example purposely introduces errors on the bus to put the TWAI controller into the Bus-Off state. An alert is used to detect the Bus-Off state and trigger the bus recovery process. The example can be found via :example:`peripherals/twai/twai_alert_and_recovery`.
+**Alert and Recovery Example:** :example:`peripherals/twai/twai_alert_and_recovery` demonstrates how to use the TWAI driver's alert and bus recovery features on {IDF_TARGET_NAME}, by initializing the driver, creating tasks for message transmission and alert handling, triggering bit errors to enter the Bus-Off state, and initiating the Bus-Off recovery process.
 
-**Self-Test Example:** This example uses the No Acknowledge Mode and Self Reception Request to cause the TWAI controller to send and simultaneously receive a series of messages. This example can be used to verify if the connections between the TWAI controller and the external transceiver are working correctly. The example can be found via :example:`peripherals/twai/twai_self_test`.
+**Self-Test Example:** :example:`peripherals/twai/twai_self_test` demonstrates how a node can transmit TWAI messages to itself using the TWAI driver's "No Acknowledgement" mode and Self Reception Requests, testing the proper connection of a target to a working external transceiver.
 
 
 .. ---------------------------- API Reference ----------------------------------

docs/zh_CN/api-reference/peripherals/spi_master.rst

@@ -798,9 +798,10 @@ GPSPI 外设的时钟源可以通过设置 :cpp:member:`spi_device_handle_t::cfg
 应用示例
 -------------------
 
-查看使用 SPI 主机驱动程序在半双工模式下读取/写入 AT93C46D EEPROM（8 位模式）的示例代码，请前往 ESP-IDF 示例的 :example:`peripherals/spi_master/hd_eeprom` 目录。
+- :example:`peripherals/spi_master/hd_eeprom` 演示了如何使用 SPI 主机驱动程序的半双工模式来读写 AT93C46D EEPROM（8 位模式）。
+
+:example:`peripherals/spi_master/lcd` 演示了如何使用 SPI 主驱动程序在 LCD 上显示动画。借助 DMA，可以实现并行渲染和刷新。该示例还说明了如何使用 SPI 事务钩子函数来驱动 D/C 信号电平。
 
-查看使用 SPI 主机驱动程序在全双工模式下驱动 LCD 屏幕（如 ST7789V 或 ILI9341）的示例代码，请前往 ESP-IDF 示例的 :example:`peripherals/spi_master/lcd` 目录。
 
 API 参考 - SPI Common
 --------------------------

docs/zh_CN/api-reference/peripherals/spi_slave.rst

@@ -249,10 +249,14 @@ SPI 从机的工作频率最高可达 {IDF_TARGET_MAX_FREQ} MHz。如果时钟
 应用示例
 -------------------
 
-从机设备/主机通信的示例代码存放在 ESP-IDF 示例项目的 :example:`peripherals/spi_slave` 目录下。
+如需查看从机/主机通信的代码示例，请前往 :example:`peripherals/spi_slave_hd` 目录。
+
+- :example: `peripherals/spi_slave/receiver` 演示了如何配置 SPI 从机以接收来自 SPI 主机的数据，并通过握手机制管理数据传输的准备状态。
+
+- :example: `peripherals/spi_slave/sender` 演示了如何配置 SPI 主机将数据发送到 SPI 从机，并通过握手来确保数据传输的时机恰当。
 
 
 API 参考
--------------
+------------
 
 .. include-build-file:: inc/spi_slave.inc

docs/zh_CN/api-reference/peripherals/spi_slave_hd.rst

@@ -122,10 +122,16 @@ SPI 从机半双工模式
 当主机发送 ``CMD8``、``CMD9`` 或 ``CMDA`` 时，从机会触发相应的动作。目前，``CMD8`` 固定用于指示 ``Rd_DMA`` 段的终止。要接收通用中断，可以在从机初始化时为 ``CMD9`` 和 ``CMDA`` 注册回调函数，详情请参阅 :ref:`spi_slave_hd_callbacks`。
 
 
-应用示例
--------------------
+.. only:: not esp32
 
-查看从机设备/主机通信的示例代码，请前往 ESP-IDF 示例的 :example:`peripherals/spi_slave_hd` 目录。
+  应用示例
+  -------------------
+
+  查看从机设备/主机通信的示例代码，请前往 ESP-IDF 示例的 :example:`peripherals/spi_slave_hd` 目录。
+
+  :example:`peripherals/spi_slave_hd/append_mode` 演示了如何使用 SPI Slave HD 驱动程序和 ESSL 驱动程序进行通信（ESSL 驱动程序是基于 SPI 主机驱动程序的封装层，用于与半双工模式的 SPI 从设备通信）。
+
+  :example:`peripherals/spi_slave_hd/segment_mode` 演示了两种使用 SPI 从机半双工分段模式的方法：一种是使用 SPI 从机半双工驱动程序，通过两个任务与 SPI 主机进行多次通信；另一种是使用 ESP 串行从机连接 API 与从机进行多次数据交换。
 
 
 API 参考

docs/zh_CN/api-reference/peripherals/twai.rst

@@ -593,11 +593,11 @@ TWAI 驱动程序通过 :cpp:type:`twai_message_t` 结构体的不同位字段
 应用示例
 ^^^^^^^^
 
-**网络示例：** TWAI 网络示例演示了如何通过 TWAI 驱动程序 API 在两个 {IDF_TARGET_NAME} 之间通信。其中一个 TWAI 节点为网络主节点，负责启动和终止与另一个网络从节点之间的数据传输。请参阅 :example:`peripherals/twai/twai_network`。
+**网络示例：** :example:`peripherals/twai/twai_network` 演示了如何通过 TWAI 驱动程序 API 在两个 {IDF_TARGET_NAME} 之间进行通信。其中一个 TWAI 节点为网络主节点，负责启动和终止与另一个网络从节点之间的数据传输。
 
-**报警和恢复示例：** 此示例演示了如何使用 TWAI 驱动程序的报警和离线恢复 API。该示例故意在总线上引入错误，将 TWAI 控制器置于离线状态。报警检测离线状态，并触发离线恢复过程。请参阅 :example:`peripherals/twai/twai_alert_and_recovery`。
+**报警和恢复示例：** :example:`peripherals/twai/twai_alert_and_recovery` 演示了如何在 {IDF_TARGET_NAME} 上使用 TWAI 驱动程序的报警和离线恢复 API。通过初始化驱动程序，该示例创建消息传输和警报处理任务，触发比特错误进入 Bus-Off 离线状态，报警检测离线状态，并触发 Bus-Off 离线恢复过程。
 
-**自测示例：** 此示例使用无应答模式和自接收请求，使 TWAI 控制器发送并同时接收一系列报文。此示例可用于验证 TWAI 控制器与外部收发器之间的连接是否正常。请参阅 :example:`peripherals/twai/twai_self_test`。
+**自测示例：** :example:`peripherals/twai/twai_self_test` 演示了节点如何使用 TWAI 驱动程序的无应答模式和自接收请求，向自身传输 TWAI 消息。此示例可用于测试目标芯片与外部收发器之间的连接是否正常。
 
 
 .. ---------------------------- API Reference ----------------------------------