mirror of
https://github.com/espressif/esp-idf.git
synced 2024-09-20 00:36:01 -04:00
doc: update twai api reference for esp32c6
This commit is contained in:
morris
parent
a83165fea0
commit
aeaef08f0e
@ -115,7 +115,6 @@ api-reference/peripherals/sdspi_share
|
||||
api-reference/peripherals/adc_continuous
|
||||
api-reference/peripherals/adc_oneshot
|
||||
api-reference/peripherals/usb_host
|
||||
api-reference/peripherals/twai
|
||||
api-reference/peripherals/hmac
|
||||
api-reference/peripherals/usb_device
|
||||
api-reference/peripherals/sdspi_host
|
||||
|
||||
@ -1,12 +1,19 @@
|
||||
Two-Wire Automotive Interface (TWAI)
|
||||
====================================
|
||||
|
||||
{IDF_TARGET_TWAI_NUM:default="1", esp32c6="2"}
|
||||
|
||||
.. -------------------------------- Overview -----------------------------------
|
||||
|
||||
.. only:: esp32c6
|
||||
|
||||
.. warning::
|
||||
{IDF_TARGET_NAME} has {IDF_TARGET_TWAI_NUM} TWAI controllers, but at the moment, the driver can only support ``TWAI0`` due to the limitation of the driver structure.
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The Two-Wire Automotive Interface (TWAI) is a real-time serial communication protocol suited for automotive and industrial applications. It is compatible with ISO11898-1 Classical frames, thus can support Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID). The {IDF_TARGET_NAME}'s peripherals contains a TWAI controller that can be configured to communicate on a TWAI bus via an external transceiver.
|
||||
The Two-Wire Automotive Interface (TWAI) is a real-time serial communication protocol suited for automotive and industrial applications. It is compatible with ISO11898-1 Classical frames, thus can support Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID). The {IDF_TARGET_NAME} contains {IDF_TARGET_TWAI_NUM} TWAI controller(s) that can be configured to communicate on a TWAI bus via an external transceiver.
|
||||
|
||||
.. warning::
|
||||
The TWAI controller is not compatible with ISO11898-1 FD Format frames, and will interpret such frames as errors.
|
||||
@ -39,7 +46,7 @@ TWAI Messages
|
||||
TWAI Messages are split into Data Frames and Remote Frames. Data Frames are used to deliver a data payload to other nodes, whereas a Remote Frame is used to request a Data Frame from other nodes (other nodes can optionally respond with a Data Frame). Data and Remote Frames have two frame formats known as **Extended Frame** and **Standard Frame** which contain a 29-bit ID and an 11-bit ID respectively. A TWAI message consists of the following fields:
|
||||
|
||||
- 29-bit or 11-bit ID: Determines the priority of the message (lower value has higher priority).
|
||||
- Data Length Code (DLC) between 0 to 8: Indicates the size (in bytes) of the data payload for a Data Frame, or the amount of data to request for a Remote Frame.
|
||||
- Data Length Code (DLC) between 0 to 8: Indicates the size (in bytes) of the data payload for a Data Frame, or the amount of data to request for a Remote Frame.
|
||||
- Up to 8 bytes of data for a Data Frame (should match DLC).
|
||||
|
||||
Error States and Counters
|
||||
@ -70,7 +77,7 @@ The TWAI controller's interface consists of 4 signal lines known as **TX, RX, BU
|
||||
|
||||
**BUS-OFF:** The BUS-OFF signal line is **optional** and is set to a low logic level (0V) whenever the TWAI controller reaches a bus-off state. The BUS-OFF signal line is set to a high logic level (3.3V) otherwise.
|
||||
|
||||
**CLKOUT:** The CLKOUT signal line is **optional** and outputs a prescaled version of the controller's source clock (APB Clock).
|
||||
**CLKOUT:** The CLKOUT signal line is **optional** and outputs a prescaled version of the controller's source clock.
|
||||
|
||||
.. note::
|
||||
An external transceiver **must internally loopback the TX to RX** such that a change in logic level to the TX signal line can be observed on the RX line. Failing to do so will cause the TWAI controller to interpret differences in logic levels between the two signal lines as a loss in arbitration or a bit error.
|
||||
@ -139,7 +146,7 @@ The TWAI driver contains an alert feature that is used to notify the application
|
||||
|
||||
.. note::
|
||||
When enabling alerts, the ``TWAI_ALERT_AND_LOG`` flag can be used to cause the TWAI driver to log any raised alerts to UART. However, alert logging is disabled and ``TWAI_ALERT_AND_LOG`` if the :ref:`CONFIG_TWAI_ISR_IN_IRAM` option is enabled (see :ref:`placing-isr-into-iram`).
|
||||
|
||||
|
||||
.. note::
|
||||
The ``TWAI_ALERT_ALL`` and ``TWAI_ALERT_NONE`` macros can also be used to enable/disable all alerts during configuration/reconfiguration.
|
||||
|
||||
@ -152,16 +159,18 @@ The operating bit rate of the TWAI driver is configured using the :cpp:type:`twa
|
||||
2. **Timing Segment 1** consists of 1 to 16 time quanta before sample point
|
||||
3. **Timing Segment 2** consists of 1 to 8 time quanta after sample point
|
||||
|
||||
{IDF_TARGET_MAX_BRP:default="128", esp32="128", esp32s2="32768", esp32c3="16384"}
|
||||
{IDF_TARGET_MAX_BRP:default="128", esp32="128", esp32s2="32768", esp32c3="16384", esp32c6="16384"}
|
||||
|
||||
The **Baudrate Prescaler** is used to determine the period of each time quantum by dividing the TWAI controller's source clock (80 MHz APB clock). On the {IDF_TARGET_NAME}, the ``brp`` can be **any even number from 2 to {IDF_TARGET_MAX_BRP}**.
|
||||
The **Baudrate Prescaler** is used to determine the period of each time quantum by dividing the TWAI controller's source clock. On the {IDF_TARGET_NAME}, the ``brp`` can be **any even number from 2 to {IDF_TARGET_MAX_BRP}**. Alternatively, you can decide the resolution of each quantum, by setting :cpp:member:`twai_timing_config_t::quanta_resolution_hz` to a non-zero value. In this way, the driver can calculate the underlying ``brp`` value for you. It's useful when you set different clock sources but want the bitrate to keep the same.
|
||||
|
||||
Supported clock source for a TWAI controller is listed in the :cpp:type:`twai_clock_source_t` and can be specified in :cpp:member:`twai_timing_config_t::clk_src`.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
If the ESP32 is a revision 2 or later chip, the ``brp`` will **also support any multiple of 4 from 132 to 256**, and can be enabled by setting the :ref:`CONFIG_ESP32_REV_MIN` to revision 2 or higher.
|
||||
|
||||
.. packetdiag:: ../../../_static/diagrams/twai/bit_timing.diag
|
||||
:caption: Bit timing configuration for 500kbit/s given BRP = 8
|
||||
:caption: Bit timing configuration for 500kbit/s given BRP = 8, clock source frequency is 80MHz
|
||||
:align: center
|
||||
|
||||
The sample point of a bit is located on the intersection of Timing Segment 1 and 2. Enabling **Triple Sampling** will cause 3 time quanta to be sampled per bit instead of 1 (extra samples are located at the tail end of Timing Segment 1).
|
||||
@ -175,40 +184,28 @@ Bit timing **macro initializers** are also available for commonly used bit rates
|
||||
|
||||
.. list::
|
||||
|
||||
- ``TWAI_TIMING_CONFIG_1MBITS()``
|
||||
- ``TWAI_TIMING_CONFIG_800KBITS()``
|
||||
- ``TWAI_TIMING_CONFIG_500KBITS()``
|
||||
- ``TWAI_TIMING_CONFIG_250KBITS()``
|
||||
- ``TWAI_TIMING_CONFIG_125KBITS()``
|
||||
- ``TWAI_TIMING_CONFIG_100KBITS()``
|
||||
- ``TWAI_TIMING_CONFIG_50KBITS()``
|
||||
- ``TWAI_TIMING_CONFIG_25KBITS()``
|
||||
:esp32s2: - ``TWAI_TIMING_CONFIG_20KBITS()``
|
||||
:esp32s2: - ``TWAI_TIMING_CONFIG_16KBITS()``
|
||||
:esp32s2: - ``TWAI_TIMING_CONFIG_12_5KBITS()``
|
||||
:esp32s2: - ``TWAI_TIMING_CONFIG_10KBITS()``
|
||||
:esp32s2: - ``TWAI_TIMING_CONFIG_5KBITS()``
|
||||
:esp32s2: - ``TWAI_TIMING_CONFIG_1KBITS()``
|
||||
:esp32s3: - ``TWAI_TIMING_CONFIG_20KBITS()``
|
||||
:esp32s3: - ``TWAI_TIMING_CONFIG_16KBITS()``
|
||||
:esp32s3: - ``TWAI_TIMING_CONFIG_12_5KBITS()``
|
||||
:esp32s3: - ``TWAI_TIMING_CONFIG_10KBITS()``
|
||||
:esp32s3: - ``TWAI_TIMING_CONFIG_5KBITS()``
|
||||
:esp32s3: - ``TWAI_TIMING_CONFIG_1KBITS()``
|
||||
:esp32c3: - ``TWAI_TIMING_CONFIG_20KBITS()``
|
||||
:esp32c3: - ``TWAI_TIMING_CONFIG_16KBITS()``
|
||||
:esp32c3: - ``TWAI_TIMING_CONFIG_12_5KBITS()``
|
||||
:esp32c3: - ``TWAI_TIMING_CONFIG_10KBITS()``
|
||||
:esp32c3: - ``TWAI_TIMING_CONFIG_5KBITS()``
|
||||
:esp32c3: - ``TWAI_TIMING_CONFIG_1KBITS()``
|
||||
- :c:macro:`TWAI_TIMING_CONFIG_1MBITS`
|
||||
- :c:macro:`TWAI_TIMING_CONFIG_800KBITS`
|
||||
- :c:macro:`TWAI_TIMING_CONFIG_500KBITS`
|
||||
- :c:macro:`TWAI_TIMING_CONFIG_250KBITS`
|
||||
- :c:macro:`TWAI_TIMING_CONFIG_125KBITS`
|
||||
- :c:macro:`TWAI_TIMING_CONFIG_100KBITS`
|
||||
- :c:macro:`TWAI_TIMING_CONFIG_50KBITS`
|
||||
- :c:macro:`TWAI_TIMING_CONFIG_25KBITS`
|
||||
:not esp32: - :c:macro:`TWAI_TIMING_CONFIG_20KBITS`
|
||||
:not esp32: - :c:macro:`TWAI_TIMING_CONFIG_16KBITS`
|
||||
:not esp32: - :c:macro:`TWAI_TIMING_CONFIG_12_5KBITS`
|
||||
:not esp32: - :c:macro:`TWAI_TIMING_CONFIG_10KBITS`
|
||||
:not esp32: - :c:macro:`TWAI_TIMING_CONFIG_5KBITS`
|
||||
:not esp32: - :c:macro:`TWAI_TIMING_CONFIG_1KBITS`
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
Revision 2 or later of the ESP32 also supports the following bit rates:
|
||||
|
||||
- ``TWAI_TIMING_CONFIG_20KBITS()``
|
||||
- ``TWAI_TIMING_CONFIG_16KBITS()``
|
||||
- ``TWAI_TIMING_CONFIG_12_5KBITS()``
|
||||
- :c:macro:`TWAI_TIMING_CONFIG_20KBITS`
|
||||
- :c:macro:`TWAI_TIMING_CONFIG_16KBITS`
|
||||
- :c:macro:`TWAI_TIMING_CONFIG_12_5KBITS`
|
||||
|
||||
Acceptance Filter
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -120,7 +120,7 @@ The following drivers will hold the ``ESP_PM_APB_FREQ_MAX`` lock while the drive
|
||||
- **SPI slave**: between calls to :cpp:func:`spi_slave_initialize` and :cpp:func:`spi_slave_free`.
|
||||
- **Ethernet**: between calls to :cpp:func:`esp_eth_driver_install` and :cpp:func:`esp_eth_driver_uninstall`.
|
||||
- **WiFi**: between calls to :cpp:func:`esp_wifi_start` and :cpp:func:`esp_wifi_stop`. If modem sleep is enabled, the lock will be released for the periods of time when radio is disabled.
|
||||
- **TWAI**: between calls to :cpp:func:`twai_driver_install` and :cpp:func:`twai_driver_uninstall`.
|
||||
:SOC_TWAI_SUPPORTED: - **TWAI**: between calls to :cpp:func:`twai_driver_install` and :cpp:func:`twai_driver_uninstall` (only when the clock source is set to :cpp:enumerator:`TWAI_CLK_SRC_APB`).
|
||||
:SOC_BT_SUPPORTED and esp32: - **Bluetooth**: between calls to :cpp:func:`esp_bt_controller_enable` and :cpp:func:`esp_bt_controller_disable`. If Bluetooth modem sleep is enabled, the ``ESP_PM_APB_FREQ_MAX`` lock will be released for the periods of time when radio is disabled. However the ``ESP_PM_NO_LIGHT_SLEEP`` lock will still be held, unless :ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` option is set to "External 32kHz crystal".
|
||||
:SOC_BT_SUPPORTED and not esp32: - **Bluetooth**: between calls to :cpp:func:`esp_bt_controller_enable` and :cpp:func:`esp_bt_controller_disable`. If Bluetooth modem sleep is enabled, the ``ESP_PM_APB_FREQ_MAX`` lock will be released for the periods of time when radio is disabled. However the ``ESP_PM_NO_LIGHT_SLEEP`` lock will still be held.
|
||||
|
||||
|
||||
@ -120,7 +120,7 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求，
|
||||
- **SPI slave**：从调用 :cpp:func:`spi_slave_initialize` 至 :cpp:func:`spi_slave_free` 期间。
|
||||
- **Ethernet**：从调用 :cpp:func:`esp_eth_driver_install` 至 :cpp:func:`esp_eth_driver_uninstall` 期间。
|
||||
- **WiFi**：从调用 :cpp:func:`esp_wifi_start` 至 :cpp:func:`esp_wifi_stop` 期间。如果启用了调制解调器睡眠模式，广播关闭时将释放此管理锁。
|
||||
- **TWAI**：从调用 :cpp:func:`twai_driver_install` 至 :cpp:func:`twai_driver_uninstall` 期间。
|
||||
:SOC_TWAI_SUPPORTED: - **TWAI**：从调用 :cpp:func:`twai_driver_install` 至 :cpp:func:`twai_driver_uninstall` 期间 (只有在 TWAI 时钟源选择为 :cpp:enumerator:`TWAI_CLK_SRC_APB` 的时候生效)。
|
||||
:SOC_BT_SUPPORTED and esp32: - **Bluetooth**：从调用 :cpp:func:`esp_bt_controller_enable` 至 :cpp:func:`esp_bt_controller_disable` 期间。如果启用了蓝牙调制解调器，广播关闭时将释放此管理锁。但依然占用 ``ESP_PM_NO_LIGHT_SLEEP`` 锁，除非将 :ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` 选项设置为 “外部 32 kHz 晶振”。
|
||||
:SOC_BT_SUPPORTED and not esp32: - **Bluetooth**：从调用 :cpp:func:`esp_bt_controller_enable` 至 :cpp:func:`esp_bt_controller_disable` 期间。如果启用了蓝牙调制解调器，广播关闭时将释放此管理锁。但依然占用 ``ESP_PM_NO_LIGHT_SLEEP`` 锁。
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user