Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

doc: updated peripherals api-reference for s2

Browse source
This commit is contained in:
Marius Vikhammer 2019-12-13 11:49:10 +08:00 committed by Angus Gratton
parent 46dab1b4e8
commit 105567d077
24 changed files with 526 additions and 326 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
docs/Doxyfile
View file

@ -103,9 +103,10 @@ INPUT = \
$(IDF_PATH)/components/driver/include/driver/spi_common.h \
$(IDF_PATH)/components/driver/include/driver/spi_master.h \
$(IDF_PATH)/components/driver/include/driver/spi_slave.h \
$(IDF_PATH)/components/driver/$(IDF_TARGET)/include/touch_sensor.h \
$(IDF_PATH)/components/driver/esp32s2/include/temp_sensor.h \
$(IDF_PATH)/components/driver/include/driver/timer.h \
$(IDF_PATH)/components/driver/include/driver/touch_pad.h \
$(IDF_PATH)/components/driver/include/driver/touch_sensor_common.h \
$(IDF_PATH)/components/driver/include/driver/uart.h \
$(IDF_PATH)/components/esp_adc_cal/include/esp_adc_cal.h \
$(IDF_PATH)/components/soc/include/hal/rmt_types.h \

1
docs/build_docs.py
View file

@ -57,7 +57,6 @@ def main():
build_dir = os.path.realpath(os.path.join(args.build_dir, language, target))
build_docs(language, target, build_dir)
def build_docs(language, target, build_dir):
print("Building language:%s target:%s build_dir:%s" % (language, target, build_dir))
try:

69
docs/en/api-reference/peripherals/adc.rst
View file

@ -1,14 +1,17 @@
Analog to Digital Converter
===========================
{IDF_TARGET_ADC1_CH0: default="GPIO 0", esp32="GPIO 36"}
{IDF_TARGET_ADC2_CH7: default="GPIO 0", esp32="GPIO 27"}
Overview
--------
The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs supporting a total of 18 measurement channels (analog enabled pins).
.. only:: esp32
The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs supporting a total of 18 measurement channels (analog enabled pins).
The ADC driver API supports ADC1 (8 channels, attached to GPIOs 32 - 39), and ADC2 (10 channels, attached to GPIOs 0, 2, 4, 12 - 15 and 25 - 27). However, the usage of ADC2 has some restrictions for the application:
1. ADC2 is used by the Wi-Fi driver. Therefore the application can only use ADC2 when the Wi-Fi driver has not started.
@ -17,6 +20,14 @@ The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Regis
- :ref:`ESP32 DevKitC <esp-modules-and-boards-esp32-devkitc>`: GPIO 0 cannot be used due to external auto program circuits.
- :ref:`ESP-WROVER-KIT <esp-modules-and-boards-esp-wrover-kit>`: GPIO 0, 2, 4 and 15 cannot be used due to external connections for different purposes.
.. only:: esp32s2
The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs supporting a total of 20 measurement channels (analog enabled pins).
The ADC driver API supports ADC1 (10 channels, attached to GPIOs 1 - 10), and ADC2 (10 channels, attached to GPIOs 11 - 20). However, the usage of ADC2 has some restrictions for the application:
1. ADC2 is used by the Wi-Fi driver. Therefore the application can only use ADC2 when the Wi-Fi driver has not started.
Configuration and Reading ADC
-----------------------------
@ -31,7 +42,9 @@ Then it is possible to read ADC conversion result with :cpp:func:`adc1_get_raw`
.. note:: Since the ADC2 is shared with the WIFI module, which has higher priority, reading operation of :cpp:func:`adc2_get_raw` will fail between :cpp:func:`esp_wifi_start()` and :cpp:func:`esp_wifi_stop()`. Use the return code to see whether the reading is successful.
It is also possible to read the internal hall effect sensor via ADC1 by calling dedicated function :cpp:func:`hall_sensor_read`. Note that even the hall sensor is internal to ESP32, reading from it uses channels 0 and 3 of ADC1 (GPIO 36 and 39). Do not connect anything else to these pins and do not change their configuration. Otherwise it may affect the measurement of low value signal from the sensor.
.. only:: esp32
It is also possible to read the internal hall effect sensor via ADC1 by calling dedicated function :cpp:func:`hall_sensor_read`. Note that even the hall sensor is internal to ESP32, reading from it uses channels 0 and 3 of ADC1 (GPIO 36 and 39). Do not connect anything else to these pins and do not change their configuration. Otherwise it may affect the measurement of low value signal from the sensor.
This API provides convenient way to configure ADC1 for reading from :doc:`ULP <../../api-guides/ulp>`. To do so, call function :cpp:func:`adc1_ulp_enable` and then set precision and attenuation as discussed above.
@ -40,7 +53,7 @@ There is another specific function :cpp:func:`adc2_vref_to_gpio` used to route i
Application Examples
--------------------
Reading voltage on ADC1 channel 0 (GPIO 36)::
Reading voltage on ADC1 channel 0 ({IDF_TARGET_ADC1_CH0})::
#include <driver/adc.h>
@ -53,7 +66,7 @@ Reading voltage on ADC1 channel 0 (GPIO 36)::
The input voltage in above example is from 0 to 1.1V (0 dB attenuation). The input range can be extended by setting higher attenuation, see :cpp:type:`adc_atten_t`.
An example using the ADC driver including calibration (discussed below) is available in esp-idf: :example:`peripherals/adc`
Reading voltage on ADC2 channel 7 (GPIO 27)::
Reading voltage on ADC2 channel 7 ({IDF_TARGET_ADC2_CH7})::
#include <driver/adc.h>
@ -72,14 +85,16 @@ Reading voltage on ADC2 channel 7 (GPIO 27)::
The reading may fail due to collision with Wi-Fi, should check it.
An example using the ADC2 driver to read the output of DAC is available in esp-idf: :example:`peripherals/adc2`
Reading the internal hall effect sensor::
.. only: esp32
#include <driver/adc.h>
Reading the internal hall effect sensor::
...
#include <driver/adc.h>
adc1_config_width(ADC_WIDTH_BIT_12);
int val = hall_sensor_read();
...
adc1_config_width(ADC_WIDTH_BIT_12);
int val = hall_sensor_read();
@ -132,32 +147,32 @@ Calibration values are used to generate characteristic curves that account for t
ESP32 Chip Surface Marking
If you would like to purchase chips or modules with calibration, double check with distributor or Espressif directly.
If you would like to purchase chips or modules with calibration, double check with distributor or Espressif directly.
.. highlight:: none
.. highlight:: none
If you are unable to check the date code (i.e. the chip may be enclosed inside a canned module, etc.), you can still verify if **eFuse Vref** is present by running `espefuse.py <https://github.com/espressif/esptool/wiki/espefuse>`_ tool with ``adc_info`` parameter ::
If you are unable to check the date code (i.e. the chip may be enclosed inside a canned module, etc.), you can still verify if **eFuse Vref** is present by running `espefuse.py <https://github.com/espressif/esptool/wiki/espefuse>`_ tool with ``adc_info`` parameter ::
$IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 adc_info
$IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 adc_info
Replace ``/dev/ttyUSB0`` with {IDF_TARGET_NAME} board's port name.
Replace ``/dev/ttyUSB0`` with {IDF_TARGET_NAME} board's port name.
A chip that has specific **eFuse Vref** value programmed (in this case 1093mV) will be reported as follows::
A chip that has specific **eFuse Vref** value programmed (in this case 1093mV) will be reported as follows::
ADC VRef calibration: 1093mV
ADC VRef calibration: 1093mV
In another example below the **eFuse Vref** is not programmed::
In another example below the **eFuse Vref** is not programmed::
ADC VRef calibration: None (1100mV nominal)
ADC VRef calibration: None (1100mV nominal)
For a chip with two point calibration the message will look similar to::
For a chip with two point calibration the message will look similar to::
ADC VRef calibration: 1149mV
ADC readings stored in efuse BLK3:
ADC1 Low reading (150mV): 306
ADC1 High reading (850mV): 3153
ADC2 Low reading (150mV): 389
ADC2 High reading (850mV): 3206
ADC VRef calibration: 1149mV
ADC readings stored in efuse BLK3:
ADC1 Low reading (150mV): 306
ADC1 High reading (850mV): 3153
ADC2 Low reading (150mV): 389
ADC2 High reading (850mV): 3206
Application Example
^^^^^^^^^^^^^^^^^^^

26
docs/en/api-reference/peripherals/can.rst
View file

@ -6,22 +6,30 @@ Controller Area Network (CAN)
Overview
--------
The {IDF_TARGET_NAME}'s peripherals contains a CAN Controller that supports Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID) of the CAN2.0B specification.
.. only:: esp32s2
.. warning::
The {IDF_TARGET_NAME} CAN controller is not compatible with CAN FD frames and will interpret such frames as errors.
.. note::
This programming guide is split into the following sections:
The CAN driver is not updated for {IDF_TARGET_NAME} and is temporarily disabled.
1. :ref:`basic-can-concepts`
.. only:: esp32
2. :ref:`signals-lines-and-transceiver`
The {IDF_TARGET_NAME}'s peripherals contains a CAN Controller that supports Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID) of the CAN2.0B specification.
3. :ref:`configuration`
.. warning::
The {IDF_TARGET_NAME} CAN controller is not compatible with CAN FD frames and will interpret such frames as errors.
4. :ref:`driver-operation`
This programming guide is split into the following sections:
5. :ref:`examples`
1. :ref:`basic-can-concepts`
2. :ref:`signals-lines-and-transceiver`
3. :ref:`configuration`
4. :ref:`driver-operation`
5. :ref:`examples`
.. --------------------------- Basic CAN Concepts ------------------------------

15
docs/en/api-reference/peripherals/dac.rst
View file

@ -1,16 +1,15 @@
Digital To Analog Converter
===========================
{IDF_TARGET_DAC_CH_1: default = "GPIO25", esp32 = "GPIO25", esp32s2 = "GPIO17"}
{IDF_TARGET_DAC_CH_2: default = "GPIO26", esp32 = "GPIO26", esp32s2 = "GPIO18"}
Overview
--------
.. only:: esp32
{IDF_TARGET_NAME} has two 8-bit DAC (digital to analog converter) channels, connected to {IDF_TARGET_DAC_CH_1} (Channel 1) and {IDF_TARGET_DAC_CH_2} (Channel 2).
{IDF_TARGET_NAME} has two 8-bit DAC (digital to analog converter) channels, connected to GPIO25 (Channel 1) and GPIO26 (Channel 2).
.. only:: esp32s2beta
{IDF_TARGET_NAME} has two 8-bit DAC (digital to analog converter) channels, connected to GPIO17 (Channel 1) and GPIO18 (Channel 2).
The DAC driver allows these channels to be set to arbitrary voltages.
@ -22,7 +21,7 @@ For other analog output options, see the :doc:`Sigma-delta Modulation module <si
Application Example
-------------------
Setting DAC channel 1 (GPIO 25) voltage to approx 0.78 of VDD_A voltage (VDD * 200 / 255). For VDD_A 3.3V, this is 2.59V::
Setting DAC channel 1 ({IDF_TARGET_DAC_CH_1}) voltage to approx 0.78 of VDD_A voltage (VDD * 200 / 255). For VDD_A 3.3V, this is 2.59V::
#include <driver/dac.h>
@ -41,7 +40,7 @@ GPIO Lookup Macros
Some useful macros can be used to specified the GPIO number of a DAC channel, or vice versa.
e.g.
1. ``DAC_CHANNEL_1_GPIO_NUM`` is the GPIO number of channel 1 (25);
2. ``DAC_GPIO26_CHANNEL`` is the channel number of GPIO 26 (channel 2).
1. ``DAC_CHANNEL_1_GPIO_NUM`` is the GPIO number of channel 1 ({IDF_TARGET_DAC_CH_1});
2. ``DAC_{IDF_TARGET_DAC_CH_2}_CHANNEL`` is the channel number of GPIO 26 (channel 2).
.. include-build-file:: inc/dac_channel.inc

6
docs/en/api-reference/peripherals/esp_slave_protocol.rst
View file

@ -6,6 +6,12 @@ Communication with ESP SDIO Slave
ESP SDIO slave initialization
------------------------------
.. only:: esp32s2
.. note::
{IDF_TARGET_NAME} does not have a SDIO peripheral.
The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the standard
SDIO initialization process (Sector 3.1.2 of `SDIO Simplified
Specification <https://www.sdcard.org/downloads/pls/>`_). In this specification

4
docs/en/api-reference/peripherals/gpio.rst
View file

@ -11,10 +11,12 @@ Overview
- Note that GPIO6-11 are usually used for SPI flash.
- GPIO34-39 can only be set as input mode and do not have software pullup or pulldown functions.
.. only:: esp32s2beta
.. only:: esp32s2
The {IDF_TARGET_NAME} chip features 43 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal.
- Note that GPIO26-32 are usually used for SPI flash.
- GPIO46 is fixed to pull-down and is input only
There is also separate "RTC GPIO" support, which functions when GPIOs are routed to the "RTC" low-power and analog subsystem. These pin functions can be used when in deep sleep, when the :doc:`Ultra Low Power co-processor <../../api-guides/ulp>` is running, or when analog functions such as ADC/DAC/etc are in use.

8
docs/en/api-reference/peripherals/i2s.rst
View file

@ -6,7 +6,13 @@ Overview
I2S (Inter-IC Sound) is a serial, synchronous communication protocol that is usually used for transmitting audio data between two digital audio devices.
{IDF_TARGET_NAME} integrates two I2S controllers, referred to as I2S0 and I2S1, both of which can be used for streaming audio and video digital data.
.. only:: esp32
{IDF_TARGET_NAME} contains two I2S peripherals. These peripherals can be configured to input and output sample data via the I2S driver.
.. only:: esp32s2
{IDF_TARGET_NAME} contains one I2S peripheral. These peripherals can be configured to input and output sample data via the I2S driver.
An I2S bus consists of the following lines:

23
docs/en/api-reference/peripherals/ledc.rst
View file

@ -6,9 +6,15 @@ LED Control
Introduction
------------
The LED control (LEDC) peripheral is primarily designed to control the intensity of LEDs, although it can also be used to generate PWM signals for other purposes as well. It has 16 channels which can generate independent waveforms that can be used, for example, to drive RGB LED devices.
.. only:: esp32
A half of LEDC's channels operate in high speed mode. This mode is implemented in hardware and offers automatic and glitch-free changing of the PWM duty cycle. The other half of channels operate in low speed mode, where the moment of change depends on the application software. Each group of channels is also able to use different clock sources.
The LED control (LEDC) peripheral is primarily designed to control the intensity of LEDs, although it can also be used to generate PWM signals for other purposes as well. It has 16 channels which can generate independent waveforms that can be used, for example, to drive RGB LED devices.
A half of LEDC's channels operate in high speed mode. This mode is implemented in hardware and offers automatic and glitch-free changing of the PWM duty cycle. The other half of channels operate in low speed mode, where the moment of change depends on the application software. Each group of channels is also able to use different clock sources, but this feature is not yet supported in the LEDC driver.
.. only:: esp32s2
A half of LEDC's channels operate in high speed mode. This mode is implemented in hardware and offers automatic and glitch-free changing of the PWM duty cycle. The other half of channels operate in low speed mode, where the moment of change depends on the application software. Each group of channels is also able to use different clock sources.
The PWM controller can automatically increase or decrease the duty cycle gradually, allowing for fades without any processor interference.
@ -131,17 +137,20 @@ For registration of a handler to address this interrupt, call :cpp:func:`ledc_is
LEDC High and Low Speed Mode
----------------------------
Of the total 8 timers and 16 channels available in the LED PWM Controller, half of them are dedicated to operation in high speed mode and the other half in low speed mode. Selection of a low or high speed timer or channel is done with the parameter :cpp:type:`ledc_mode_t` that can be found in applicable function calls.
.. only:: esp32
The advantage of high speed mode is glitch-free changeover of the timer settings. This means that if the timer settings are modified, the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the background, e.g., when :cpp:func:`ledc_timer_config` or :cpp:func:`ledc_timer_set` is called.
.. only:: esp32
The advantage of high speed mode is hardware-supported, glitch-free changeover of the timer settings. This means that if the timer settings are modified, the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the background, e.g., when :cpp:func:`ledc_timer_config` or :cpp:func:`ledc_timer_set` is called.
For additional details regarding speed modes, refer to `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver.
.. only:: esp32s2beta
For additional details regarding speed modes, refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_URL}>`_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver.
For additional details regarding speed modes, refer to `ESP32-S2 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf>`_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver.
.. only:: esp32s2
.. note::
All the timers and channels in the {IDF_TARGET_NAME}'s LED PWM Controller only support low speed mode.
.. _ledc-api-supported-range-frequency-duty-resolution:

17
docs/en/api-reference/peripherals/mcpwm.rst
View file

@ -1,7 +1,9 @@
MCPWM
=====
{IDF_TARGET_NAME} has two MCPWM units which can be used to control different types of motors. Each unit has three pairs of PWM outputs.
.. This peripheral is ESP32 only
ESP32 has two MCPWM units which can be used to control different types of motors. Each unit has three pairs of PWM outputs.
.. figure:: ../../../_static/mcpwm-overview.png
:align: center
@ -89,13 +91,8 @@ There are couple of ways to adjust a signal on the outputs and changing how the
Synchronization signals are referred to using two different enumerations. First one :cpp:type:`mcpwm_io_signals_t` is used together with function :cpp:func:`mcpwm_gpio_init` when selecting a GPIO as the signal input source. The second one :cpp:type:`mcpwm_sync_signal_t` is used when enabling or disabling synchronization with :cpp:func:`mcpwm_sync_enable` or :cpp:func:`mcpwm_sync_disable`.
.. only:: esp32
* Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `ESP32 Technical Reference Manual`_.
.. only:: esp32s2beta
* Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `ESP32-S2 Technical Reference Manual`_.
* Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `{IDF_TARGET_NAME} Technical Reference Manual`_.
Capture
-------
@ -153,7 +150,7 @@ To use the carrier submodule, it should be first initialized by calling :cpp:fun
The carrier parameters may be then alerted at a runtime by calling dedicated functions to change individual fields of the :cpp:type:`mcpwm_carrier_config_t` structure, like :cpp:func:`mcpwm_carrier_set_period`, :cpp:func:`mcpwm_carrier_set_duty_cycle`, :cpp:func:`mcpwm_carrier_output_invert`, etc.
This includes enabling and setting duration of the first pulse of the career with :cpp:func:`mcpwm_carrier_oneshot_mode_enable`. For more details please refer to "PWM Carrier Submodule" section of the `ESP32 Technical Reference Manual`_.
This includes enabling and setting duration of the first pulse of the career with :cpp:func:`mcpwm_carrier_oneshot_mode_enable`. For more details please refer to "PWM Carrier Submodule" section of the `{IDF_TARGET_NAME} Technical Reference Manual`_.
To disable carrier functionality call :cpp:func:`mcpwm_carrier_disable`.
@ -174,9 +171,7 @@ Examples of using MCPWM for motor control: :example:`peripherals/mcpwm`:
* Brushed DC motor control - :example:`peripherals/mcpwm/mcpwm_brushed_dc_control`
* Servo motor control - :example:`peripherals/mcpwm/mcpwm_servo_control`
.. _ESP32 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
.. _ESP32-S2 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf
.. _{IDF_TARGET_NAME} Technical Reference Manual: {IDF_TARGET_TRM_URL}
API Reference

13
docs/en/api-reference/peripherals/pcnt.rst
View file

@ -13,17 +13,22 @@ Functionality Overview
Description of functionality of this API has been broken down into four sections:
* :ref:`pcnt-api-configuration` - describes counter's configuration parameters and how to setup the counter.
* :ref:`pcnt-api-operating-the-counter` - provides information on control functions to pause, measure and clear the counter.
* :ref:`pcnt-api-operating-the-counter` - provides information on control functions to pause, measure and clear the counter.
* :ref:`pcnt-api-filtering-pulses` - describes options to filtering pulses and the counter control signals.
* :ref:`pcnt-api-using-interrupts` - presents how to trigger interrupts on specific states of the counter.
* :ref:`pcnt-api-using-interrupts` - presents how to trigger interrupts on specific states of the counter.
.. _pcnt-api-configuration:
Configuration
-------------
.. only:: esp32
The PCNT module has eight independent counting "units" numbered from 0 to 7. In the API they are referred to using :cpp:type:`pcnt_unit_t`. Each unit has two independent channels numbered as 0 and 1 and specified with :cpp:type:`pcnt_channel_t`.
The PCNT module has eight independent counting "units" numbered from 0 to 7. In the API they are referred to using :cpp:type:`pcnt_unit_t`. Each unit has two independent channels numbered as 0 and 1 and specified with :cpp:type:`pcnt_channel_t`.
.. only:: esp32s2
The PCNT module has four independent counting "units" numbered from 0 to 3. In the API they are referred to using :cpp:type:`pcnt_unit_t`. Each unit has two independent channels numbered as 0 and 1 and specified with :cpp:type:`pcnt_channel_t`.
The configuration is provided separately per unit's channel using :cpp:type:`pcnt_config_t` and covers:
@ -78,7 +83,7 @@ There are five counter state watch events, defined in :cpp:type:`pcnt_evt_type_t
* Threshold 0 or Threshold 1 values set using function :cpp:func:`pcnt_set_event_value`.
* Pulse count = 0
To register, enable or disable an interrupt to service the above events, call :cpp:func:`pcnt_isr_register`, :cpp:func:`pcnt_intr_enable`. and :cpp:func:`pcnt_intr_disable`. To enable or disable events on reaching threshold values, you will also need to call functions :cpp:func:`pcnt_event_enable` and :cpp:func:`pcnt_event_disable`.
To register, enable or disable an interrupt to service the above events, call :cpp:func:`pcnt_isr_register`, :cpp:func:`pcnt_intr_enable`. and :cpp:func:`pcnt_intr_disable`. To enable or disable events on reaching threshold values, you will also need to call functions :cpp:func:`pcnt_event_enable` and :cpp:func:`pcnt_event_disable`.
In order to check what are the threshold values currently set, use function :cpp:func:`pcnt_get_event_value`.

22
docs/en/api-reference/peripherals/rmt.rst
View file

@ -91,7 +91,13 @@ There couple of typical steps to setup and operate the RMT and they are discusse
3. `Change Operation Parameters`_
4. `Use Interrupts`_
The RMT has eight channels numbered from zero to seven. Each channel is able to independently transmit or receive data. They are referred to using indexes defined in structure :cpp:type:`rmt_channel_t`.
.. only:: esp32
The RMT has eight channels numbered from zero to seven. Each channel is able to independently transmit or receive data. They are referred to using indexes defined in structure :cpp:type:`rmt_channel_t`.
.. only:: esp32s2
The RMT has four channels numbered from zero to three. Each channel is able to independently transmit or receive data. They are referred to using indexes defined in structure :cpp:type:`rmt_channel_t`.
Configure Driver
@ -153,7 +159,7 @@ Now, depending on how the channel is configured, we are ready to either `Transmi
Transmit Data
-------------
Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized by the RMT controller, later called an 'item', is provided in a structure :cpp:type:`rmt_item32_t`, see :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_caps.h`. Each item consists of two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure of an item is presented below.
Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized by the RMT controller, later called an 'item', is provided in a structure :cpp:type:`rmt_item32_t`, see :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_struct.h`. Each item consists of two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure of an item is presented below.
.. packetdiag::
:caption: Structure of RMT items (L - signal level)
@ -186,7 +192,15 @@ Another way to provide data for transmission is by calling :cpp:func:`rmt_fill_t
Receive Data
------------
Before starting the receiver we need some storage for incoming items. The RMT controller has 512 x 32-bits of internal RAM shared between all eight channels. In typical scenarios it is not enough as an ultimate storage for all incoming (and outgoing) items. Therefore this API supports retrieval of incoming items on the fly to save them in a ring buffer of a size defined by the user. The size is provided when calling :cpp:func:`rmt_driver_install` discussed above. To get a handle to this buffer call :cpp:func:`rmt_get_ringbuf_handle`.
.. only:: esp32
Before starting the receiver we need some storage for incoming items. The RMT controller has 512 x 32-bits of internal RAM shared between all eight channels.
.. only:: esp32s2
Before starting the receiver we need some storage for incoming items. The RMT controller has 256 x 32-bits of internal RAM shared between all four channels.
In typical scenarios it is not enough as an ultimate storage for all incoming (and outgoing) items. Therefore this API supports retrieval of incoming items on the fly to save them in a ring buffer of a size defined by the user. The size is provided when calling :cpp:func:`rmt_driver_install` discussed above. To get a handle to this buffer call :cpp:func:`rmt_get_ringbuf_handle`.
With the above steps complete we can start the receiver by calling :cpp:func:`rmt_rx_start` and then move to checking what's inside the buffer. To do so, you can use common FreeRTOS functions that interact with the ring buffer. Please see an example how to do it in :example:`peripherals/rmt/ir_protocols`.
@ -242,7 +256,7 @@ The RMT controller triggers interrupts on four specific events describes below.
Setting or clearing an interrupt enable mask for specific channels and events may be also done by calling :cpp:func:`rmt_set_intr_enable_mask` or :cpp:func:`rmt_clr_intr_enable_mask`.
When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_struct.h`, where N is the RMT channel number [0, 7] and the ``event_name`` is one of four events described above.
When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_struct.h`, where N is the RMT channel number [0, n] and the ``event_name`` is one of four events described above.
If you do not need an ISR anymore, you can deregister it by calling a function :cpp:func:`rmt_isr_deregister`.

131
docs/en/api-reference/peripherals/sd_pullup_requirements.rst
View file

@ -3,7 +3,7 @@ SD Pull-up Requirements
Espressif hardware products are designed for multiple use cases which may require different pull states on pins. For this reason, the pull state of particular pins on certain products will need to be adjusted to provide the pull-ups required in the SD bus.
SD pull-up requirements apply to cases where ESP32 uses the SPI controller to communicate with SD cards. When an SD card is operating in SPI mode or 1-bit SD mode, the CMD and DATA (DAT0 - DAT3) lines of the SD bus must be pulled up by 10 kOhm resistors. Slaves should also have pull-ups on all above-mentioned lines (regardless of whether these lines are connected to the host) in order to prevent SD cards from entering a wrong state.
SD pull-up requirements apply to cases where {IDF_TARGET_NAME} uses the SPI controller to communicate with SD cards. When an SD card is operating in SPI mode or 1-bit SD mode, the CMD and DATA (DAT0 - DAT3) lines of the SD bus must be pulled up by 10 kOhm resistors. Slaves should also have pull-ups on all above-mentioned lines (regardless of whether these lines are connected to the host) in order to prevent SD cards from entering a wrong state.
By default, the MTDI bootstrapping pin is incompatible with the DAT2 line pull-up if the flash voltage is 3.3 V. For more information, see :ref:`mtdi_strapping_pin` below.
@ -29,42 +29,67 @@ This section provides an overview of compatibility issues that might occur when
Systems on a Chip (SoCs)
^^^^^^^^^^^^^^^^^^^^^^^^
- ESP32 (except for D2WD versions, see `ESP32 datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_):
.. only:: esp32
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`strapping_conflicts_dat2` for models with 3.3 V flash chip
- ESP32 (except for D2WD versions, see `ESP32 datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_):
- ESP32-D2WD:
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`strapping_conflicts_dat2` for models with 3.3 V flash chip
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`no_pull-up_on_gpio12`
- ESP32-D2WD:
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`no_pull-up_on_gpio12`
.. only:: esp32s2
.. note::
No chips listed for ESP32-S2 yet.
Systems in Packages (SIP)
^^^^^^^^^^^^^^^^^^^^^^^^^
- ESP32-PICO-D4:
.. only:: esp32
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`strapping_conflicts_dat2`
- ESP32-PICO-D4:
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`strapping_conflicts_dat2`
.. only:: esp32s2
.. note::
No chips listed for ESP32-S2 yet.
Modules
^^^^^^^
- ESP32-WROOM-32 Series, including ESP32-WROOM-32, ESP32-WROOM-32D, ESP32-WROOM-32U, and ESP32-SOLO-1
.. only:: esp32
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`strapping_conflicts_dat2`
- ESP32-WROOM-32 Series, including ESP32-WROOM-32, ESP32-WROOM-32D, ESP32-WROOM-32U, and ESP32-SOLO-1
- ESP32-WROVER Series, including ESP32-WROVER and ESP32-WROVER-I
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`strapping_conflicts_dat2`
- :ref:`sd_pull-up_no_pull-ups`
- ESP32-WROVER Series, including ESP32-WROVER and ESP32-WROVER-I
- ESP32-WROVER-B Series, including ESP32-WROVER-B and ESP32-WROVER-IB
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`strapping_conflicts_dat2`
- ESP32-WROVER-B Series, including ESP32-WROVER-B and ESP32-WROVER-IB
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`strapping_conflicts_dat2`
.. only:: esp32s2
.. note::
No chips listed for ESP32-S2 yet.
.. _sdio_dev_kits:
@ -72,40 +97,48 @@ Modules
Development Boards
^^^^^^^^^^^^^^^^^^
- ESP32-PICO-KIT, including PICO-KIT v4.1, v4.0, and v3
.. only:: esp32
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`strapping_conflicts_dat2`
- :ref:`gpio2_strapping_pin`
- ESP32-PICO-KIT, including PICO-KIT v4.1, v4.0, and v3
- ESP32-DevKitC, including ESP32-DevKitC v4 and v2
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`strapping_conflicts_dat2`
- :ref:`gpio2_strapping_pin`
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`strapping_conflicts_dat2`
- :ref:`gpio2_strapping_pin`
- ESP32-DevKitC, including ESP32-DevKitC v4 and v2
- ESP-WROVER-KIT
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`strapping_conflicts_dat2`
- :ref:`gpio2_strapping_pin`
- Required pull-ups are provided
- :ref:`pull-up_conflicts_on_gpio13` (v4.1, v3, v2, and v1)
- :ref:`strapping_conflicts_dat2` (v4.1, v2, and v1)
- :ref:`gpio2_strapping_pin` (v2, v1)
- ESP-WROVER-KIT
You can determine the version of your ESP23-WROVER-KIT by checking which module is mounted on it:
- Required pull-ups are provided
- :ref:`pull-up_conflicts_on_gpio13` (v4.1, v3, v2, and v1)
- :ref:`strapping_conflicts_dat2` (v4.1, v2, and v1)
- :ref:`gpio2_strapping_pin` (v2, v1)
- ESP32-WROVER-B on v4.1
- ESP32-WROVER on v3
- ESP32-WROOM-32 on v1 and v2
You can determine the version of your ESP23-WROVER-KIT by checking which module is mounted on it:
- ESP32-LyraTD-MSC
- ESP32-WROVER-B on v4.1
- ESP32-WROVER on v3
- ESP32-WROOM-32 on v1 and v2
- Required pull-ups are provided
- :ref:`strapping_conflicts_dat2`
- ESP32-LyraTD-MSC
- ESP32-LyraT
- Required pull-ups are provided
- :ref:`strapping_conflicts_dat2`
- Required pull-ups are provided
- :ref:`pull-up_conflicts_on_gpio13`
- ESP32-LyraT
- Required pull-ups are provided
- :ref:`pull-up_conflicts_on_gpio13`
.. only:: esp32s2
.. note::
No chips listed for ESP32-S2 yet.
Non-Espressif Hosts
@ -159,7 +192,7 @@ To resolve the conflict, you have the following options:
Burning eFuses is irreversible! The issue list above might be out of date, so please make sure that the module you are burning has a 3.3 V flash chip by checking the information on http://www.espressif.com/. If you burn the 3.3 V eFuses on a module with a 1.8 V flash chip, the module will stop functioning.
If you are sure that you need to irreversibly burn eFuses, go to your ESP-IDF directory and run the following command:
.. code-block:: bash
components/esptool_py/esptool/espefuse.py set_flash_voltage 3.3V
@ -178,13 +211,13 @@ To resolve the conflict, you have the following options:
BURN
VDD_SDIO setting complete.
To check the status of the eFuses, run::
To check the status of the eFuses, run::
``components/esptool_py/esptool/espefuse.py summary``
If running from an automated flashing script, ``espefuse.py`` has an option ``--do-not-confirm``.
For more details, see the `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ (PDF).
For more details, see the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_URL}>`_ (PDF).
2. **If using 1-bit SD mode or SPI mode**, disconnect the DAT2 pin and make sure it is pulled high. For this, do one the following:
@ -230,7 +263,9 @@ MTDI Strapping Pin
MTDI (GPIO12) is used as a bootstrapping pin to select the output voltage of an internal regulator (VDD_SDIO) which powers the flash chip. This pin has an internal pull-down, so, if left unconnected, it will read low at startup, which will lead to selecting the default 3.3 V operation.
All ESP32-WROVER modules, excluding ESP32-WROVER-B, use 1.8 V flash and have internal pull-ups on GPIO12. Other modules that use 3.3 V flash have no pull-ups on the GPIO12 pin, and this pin is slightly pulled down internally.
.. only:: esp32
All ESP32-WROVER modules, excluding ESP32-WROVER-B, use 1.8 V flash and have internal pull-ups on GPIO12. Other modules that use 3.3 V flash have no pull-ups on the GPIO12 pin, and this pin is slightly pulled down internally.
When adding a pull-up to this pin for SD card operation, consider the following:
@ -263,7 +298,7 @@ The following abbreviations are used in the table:
* - **15**
- CMD
- WPU
-
-
* - **2**
- DAT0
- WPD
@ -271,7 +306,7 @@ The following abbreviations are used in the table:
* - **4**
- DAT1
- WPD
-
-
* - **12**
- DAT2
- PU for 1.8 V flash; WPD for 3.3 V flash
@ -279,4 +314,4 @@ The following abbreviations are used in the table:
* - **13**
- DAT3
- WPU
-
-

22
docs/en/api-reference/peripherals/sdio_slave.rst
View file

@ -4,14 +4,22 @@ SDIO Card Slave Driver
Overview
--------
The ESP32 SDIO Card peripherals (Host, Slave) shares two sets of pins as below table.
The first set is usually occupied by SPI0 bus which is responsible for the SPI flash holding the code to run.
This means SDIO slave driver can only runs on the second set of pins while SDIO host is not using it.
.. only:: esp32s2
The SDIO slave can run under 3 modes: SPI, 1-bit SD and 4-bit SD modes, which
is detected automatically by the hardware. According to the SDIO
specification, CMD and DAT0-3 lines should be pulled up no matter in 1-bit,
4-bit or SPI mode.
.. note::
{IDF_TARGET_NAME} does not have a SDIO peripheral.
.. only:: esp32
The ESP32 SDIO Card peripherals (Host, Slave) shares two sets of pins as below table.
The first set is usually occupied by SPI0 bus which is responsible for the SPI flash holding the code to run.
This means SDIO slave driver can only runs on the second set of pins while SDIO host is not using it.
The SDIO slave can run under 3 modes: SPI, 1-bit SD and 4-bit SD modes, which
is detected automatically by the hardware. According to the SDIO
specification, CMD and DAT0-3 lines should be pulled up no matter in 1-bit,
4-bit or SPI mode.
Connections
^^^^^^^^^^^

79
docs/en/api-reference/peripherals/sdmmc_host.rst
View file

@ -3,47 +3,54 @@ SDMMC Host Driver
Overview
--------
.. only:: esp32s2
ESP32's SDMMC host peripheral has two slots:
.. note::
- Slot 0 (:c:macro:`SDMMC_HOST_SLOT_0`) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX.
- Slot 1 (:c:macro:`SDMMC_HOST_SLOT_1`) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX.
{IDF_TARGET_NAME} does not have a SDMMC host peripheral.
Pin mappings of these slots are given in the table below.
.. only:: esp32
+--------+-------------+-------------+
| Signal | Slot 0 | Slot 1 |
+========+=============+=============+
| CMD | GPIO11 | GPIO15 |
+--------+-------------+-------------+
| CLK | GPIO6 | GPIO14 |
+--------+-------------+-------------+
| D0 | GPIO7 | GPIO2 |
+--------+-------------+-------------+
| D1 | GPIO8 | GPIO4 |
+--------+-------------+-------------+
| D2 | GPIO9 | GPIO12 |
+--------+-------------+-------------+
| D3 | GPIO10 | GPIO13 |
+--------+-------------+-------------+
| D4 | GPIO16 | |
+--------+-------------+-------------+
| D5 | GPIO17 | |
+--------+-------------+-------------+
| D6 | GPIO5 | |
+--------+-------------+-------------+
| D7 | GPIO18 | |
+--------+-------------+-------------+
| CD | any input via GPIO matrix |
+--------+---------------------------+
| WP | any input via GPIO matrix |
+--------+---------------------------+
ESP32's SDMMC host peripheral has two slots:
The Card Detect and Write Protect signals can be routed to arbitrary pins using the GPIO matrix. To reserve the pins, set the ``gpio_cd`` and ``gpio_wp`` members of the :cpp:class:`sdmmc_slot_config_t` structure before calling :cpp:func:`sdmmc_host_init_slot`. Please note that it is not advised to specify a Card Detect pin when working with SDIO cards, because the card detect signal in ESP32 can also trigger SDIO slave interrupt.
- Slot 0 (:c:macro:`SDMMC_HOST_SLOT_0`) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX.
- Slot 1 (:c:macro:`SDMMC_HOST_SLOT_1`) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX.
.. warning::
Pins used by Slot 0 (``HS1_*``) are also used to connect the SPI flash chip in ESP32-WROOM and ESP32-WROVER modules. These pins cannot be shared between an SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set eFuses accordingly.
Pin mappings of these slots are given in the table below.
+--------+-------------+-------------+
| Signal | Slot 0 | Slot 1 |
+========+=============+=============+
| CMD | GPIO11 | GPIO15 |
+--------+-------------+-------------+
| CLK | GPIO6 | GPIO14 |
+--------+-------------+-------------+
| D0 | GPIO7 | GPIO2 |
+--------+-------------+-------------+
| D1 | GPIO8 | GPIO4 |
+--------+-------------+-------------+
| D2 | GPIO9 | GPIO12 |
+--------+-------------+-------------+
| D3 | GPIO10 | GPIO13 |
+--------+-------------+-------------+
| D4 | GPIO16 | |
+--------+-------------+-------------+
| D5 | GPIO17 | |
+--------+-------------+-------------+
| D6 | GPIO5 | |
+--------+-------------+-------------+
| D7 | GPIO18 | |
+--------+-------------+-------------+
| CD | any input via GPIO matrix |
+--------+---------------------------+
| WP | any input via GPIO matrix |
+--------+---------------------------+
The Card Detect and Write Protect signals can be routed to arbitrary pins using the GPIO matrix. To reserve the pins, set the ``gpio_cd`` and ``gpio_wp`` members of the :cpp:class:`sdmmc_slot_config_t` structure before calling :cpp:func:`sdmmc_host_init_slot`. Please note that it is not advised to specify a Card Detect pin when working with SDIO cards, because the card detect signal in ESP32 can also trigger SDIO slave interrupt.
.. warning::
Pins used by Slot 0 (``HS1_*``) are also used to connect the SPI flash chip in ESP32-WROOM and ESP32-WROVER modules. These pins cannot be shared between an SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set eFuses accordingly.
Supported Speed Modes
@ -74,7 +81,7 @@ Other functions, such as the ones given below, will be called by the SD/MMC prot
- :cpp:func:`sdmmc_host_set_bus_width`
- :cpp:func:`sdmmc_host_set_card_clk`
- :cpp:func:`sdmmc_host_do_transaction`
- :cpp:func:`sdmmc_host_do_transaction`
Configuring Bus Width and Frequency

4
docs/en/api-reference/peripherals/sdspi_host.rst
View file

@ -8,7 +8,7 @@ The SD SPI host driver allows using the SPI2 (HSPI) or SPI3 (VSPI) controller fo
The SD SPI host driver has the following modes:
- **SPI mode**: offers lower throughput but makes pin selection more flexible. With the help of the GPIO matrix, an SPI peripheral's signals can be routed to any ESP32 pin.
- **SPI mode**: offers lower throughput but makes pin selection more flexible. With the help of the GPIO matrix, an SPI peripheral's signals can be routed to any {IDF_TARGET_NAME} pin.
- **1-bit SD mode**: offers higher throughput but requires routing the signals through their dedicated IO_MUX pins only.
The SD SPI driver uses software-controlled CS signal.
@ -32,7 +32,7 @@ Only the following driver's API functions are normally used by most applications
Other functions are mostly used by the protocol level SD/SDIO/MMC driver via function pointers in the :cpp:type:`sdmmc_host_t` structure. For more details, see :doc:`the SD/SDIO/MMC Driver <../storage/sdmmc>`.
.. note::
SD over SPI does not support speeds above :c:macro:`SDMMC_FREQ_DEFAULT` due to the limitations of the SPI driver.

4
docs/en/api-reference/peripherals/sigmadelta.rst
View file

@ -4,9 +4,9 @@ Sigma-delta Modulation
Introduction
------------
ESP32 has a second-order sigma-delta modulation module. This driver configures the channels of the sigma-delta module.
{IDF_TARGET_NAME} has a second-order sigma-delta modulation module. This driver configures the channels of the sigma-delta module.
Functionality Overview
Functionality Overview
----------------------
There are eight independent sigma-delta modulation channels identified with :cpp:type:`sigmadelta_channel_t`. Each channel is capable to output the binary, hardware generated signal with the sigma-delta modulation.

95
docs/en/api-reference/peripherals/spi_master.rst
View file

@ -1,11 +1,11 @@
SPI Master Driver
=================
SPI Master driver is a program that controls ESP32's SPI peripherals while they function as masters.
SPI Master driver is a program that controls {IDF_TARGET_NAME}'s SPI peripherals while they function as masters.
Overview of ESP32's SPI peripherals
-----------------------------------
Overview of {IDF_TARGET_NAME}'s SPI peripherals
-----------------------------------------------
ESP32 integrates four SPI peripherals.
@ -48,7 +48,7 @@ The SPI master driver governs communications of Hosts with Devices. The driver s
.. warning::
The SPI master driver has the concept of multiple Devices connected to a single bus (sharing a single ESP32 SPI peripheral). As long as each Device is accessed by only one task, the driver is thread safe. However, if multiple tasks try to access the same SPI Device, the driver is **not thread-safe**. In this case, it is recommended to either:
The SPI master driver has the concept of multiple Devices connected to a single bus (sharing a single {IDF_TARGET_NAME} SPI peripheral). As long as each Device is accessed by only one task, the driver is thread safe. However, if multiple tasks try to access the same SPI Device, the driver is **not thread-safe**. In this case, it is recommended to either:
- Refactor your application so that each SPI peripheral is only accessed by a single task at a time.
- Add a mutex lock around the shared Device using :c:macro:`xSemaphoreCreateMutex`.
@ -154,12 +154,12 @@ Driver Usage
Organize the Driver Usage into subsections that will reflect the general usage experience of the users, e.g.,
Configuration
Add stuff about the configuration API here, and the various options in configuration (e.g., configure for interrupt vs. polling), and optional configuration
Transactions
Describe how to execute a normal transaction (i.e., where data is larger than 32 bits). Describe how to configure between big and little-endian.
Describe how to execute a normal transaction (i.e., where data is larger than 32 bits). Describe how to configure between big and little-endian.
- Add subsub section on how to optimize when transmitting less than 32 bits
- Add subsub section on how to transmit mixed transactions to the same device
@ -195,11 +195,11 @@ When the transaction data size is equal to or less than 32 bits, it will be sub-
Transactions with Integers Other Than ``uint8_t``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
An SPI Host reads and writes data into memory byte by byte. By default, data is sent with the most significant bit (MSB) first, as LSB first used in rare cases. If a value less than 8 bits needs to be sent, the bits should be written into memory in the MSB first manner.
An SPI Host reads and writes data into memory byte by byte. By default, data is sent with the most significant bit (MSB) first, as LSB first used in rare cases. If a value less than 8 bits needs to be sent, the bits should be written into memory in the MSB first manner.
For example, if ``0b00010`` needs to be sent, it should be written into a ``uint8_t`` variable, and the length for reading should be set to 5 bits. The Device will still receive 8 bits with 3 additional "random" bits, so the reading must be performed correctly.
On top of that, ESP32 is a little-endian chip, which means that the least significant byte of ``uint16_t`` and ``uint32_t`` variables is stored at the smallest address. Hence, if ``uint16_t`` is stored in memory, bits [7:0] are sent first, followed by bits [15:8].
On top of that, {IDF_TARGET_NAME} is a little-endian chip, which means that the least significant byte of ``uint16_t`` and ``uint32_t`` variables is stored at the smallest address. Hence, if ``uint16_t`` is stored in memory, bits [7:0] are sent first, followed by bits [15:8].
For cases when the data to be transmitted has the size differing from ``uint8_t`` arrays, the following macros can be used to transform data to the format that can be sent by the SPI driver directly:
@ -222,42 +222,43 @@ In-flight polling transactions are disturbed by the ISR operation to accommodate
To have better control of the calling sequence of functions, send mixed transactions to the same Device only within a single task.
.. only:: esp32
GPIO Matrix and IO_MUX
----------------------
GPIO Matrix and IO_MUX
----------------------
Most of ESP32's peripheral signals have direct connection to their dedicated IO_MUX pins. However, the signals can also be routed to any other available pins using the less direct GPIO matrix. If at least one signal is routed through the GPIO matrix, then all signals will be routed through it.
Most of ESP32's peripheral signals have direct connection to their dedicated IO_MUX pins. However, the signals can also be routed to any other available pins using the less direct GPIO matrix. If at least one signal is routed through the GPIO matrix, then all signals will be routed through it.
The GPIO matrix introduces flexibility of routing but also brings the following disadvantages:
The GPIO matrix introduces flexibility of routing but also brings the following disadvantages:
- Increases the input delay of the MISO signal, which makes MISO setup time violations more likely. If SPI needs to operate at high speeds, use dedicated IO_MUX pins.
- Allows signals with clock frequencies only up to 40 MHz, as opposed to 80 MHz if IO_MUX pins are used.
- Increases the input delay of the MISO signal, which makes MISO setup time violations more likely. If SPI needs to operate at high speeds, use dedicated IO_MUX pins.
- Allows signals with clock frequencies only up to 40 MHz, as opposed to 80 MHz if IO_MUX pins are used.
.. note::
.. note::
For more details about the influence of the MISO input delay on the maximum clock frequency, see :ref:`timing_considerations`.
For more details about the influence of the MISO input delay on the maximum clock frequency, see :ref:`timing_considerations`.
The IO_MUX pins for SPI buses are given below.
The IO_MUX pins for SPI buses are given below.
+----------+------+------+
| Pin Name | SPI2 | SPI3 |
+ +------+------+
| | GPIO Number |
+==========+======+======+
| CS0* | 15 | 5 |
+----------+------+------+
| SCLK | 14 | 18 |
+----------+------+------+
| MISO | 12 | 19 |
+----------+------+------+
| MOSI | 13 | 23 |
+----------+------+------+
| QUADWP | 2 | 22 |
+----------+------+------+
| QUADHD | 4 | 21 |
+----------+------+------+
+----------+------+------+
| Pin Name | SPI2 | SPI3 |
+ +------+------+
| | GPIO Number |
+==========+======+======+
| CS0* | 15 | 5 |
+----------+------+------+
| SCLK | 14 | 18 |
+----------+------+------+
| MISO | 12 | 19 |
+----------+------+------+
| MOSI | 13 | 23 |
+----------+------+------+
| QUADWP | 2 | 22 |
+----------+------+------+
| QUADHD | 4 | 21 |
+----------+------+------+
* Only the first Device attached to the bus can use the CS0 pin.
* Only the first Device attached to the bus can use the CS0 pin.
.. _speed_considerations:
@ -429,21 +430,23 @@ Corresponding frequency limits for different Devices with different *input delay
Known Issues
------------
1. Half-duplex transactions are not compatible with DMA when both writing and reading phases are used.
.. only:: esp32
If such transactions are required, you have to use one of the alternative solutions:
1. Half-duplex transactions are not compatible with DMA when both writing and reading phases are used.
1. Use full-duplex transactions instead.
2. Disable DMA by setting the bus initialization function's last parameter to 0 as follows:
``ret=spi_bus_initialize(VSPI_HOST, &buscfg, 0);``
If such transactions are required, you have to use one of the alternative solutions:
This can prohibit you from transmitting and receiving data longer than 64 bytes.
3. Try using the command and address fields to replace the write phase.
1. Use full-duplex transactions instead.
2. Disable DMA by setting the bus initialization function's last parameter to 0 as follows:
``ret=spi_bus_initialize(VSPI_HOST, &buscfg, 0);``
2. Full-duplex transactions are not compatible with the *dummy bit workaround*, hence the frequency is limited. See :ref:`dummy
bit speed-up workaround <dummy_bit_workaround>`.
This can prohibit you from transmitting and receiving data longer than 64 bytes.
3. Try using the command and address fields to replace the write phase.
3. ``cs_ena_pretrans`` is not compatible with the command and address phases of full-duplex transactions.
2. Full-duplex transactions are not compatible with the *dummy bit workaround*, hence the frequency is limited. See :ref:`dummy
bit speed-up workaround <dummy_bit_workaround>`.
3. ``cs_ena_pretrans`` is not compatible with the command and address phases of full-duplex transactions.
Application Example

87
docs/en/api-reference/peripherals/spi_slave.rst
View file

@ -1,13 +1,13 @@
SPI Slave Driver
================
SPI Slave driver is a program that controls ESP32's SPI peripherals while they function as slaves.
SPI Slave driver is a program that controls {IDF_TARGET_NAME}'s SPI peripherals while they function as slaves.
Overview of ESP32's SPI peripherals
-----------------------------------
Overview of {IDF_TARGET_NAME}'s SPI peripherals
-----------------------------------------------
ESP32 integrates two general purpose SPI controllers which can be used as slave nodes driven by an off-chip SPI master
{IDF_TARGET_NAME} integrates two general purpose SPI controllers which can be used as slave nodes driven by an off-chip SPI master
- SPI2, sometimes referred to as HSPI
- SPI3, sometimes referred to as VSPI
@ -23,7 +23,7 @@ The terms used in relation to the SPI slave driver are given in the table below.
================= =========================================================================================
Term Definition
================= =========================================================================================
**Host** The SPI controller peripheral external to ESP32 that initiates SPI transmissions over the bus, and acts as an SPI Master.
**Host** The SPI controller peripheral external to {IDF_TARGET_NAME} that initiates SPI transmissions over the bus, and acts as an SPI Master.
**Device** SPI slave device, in this case the SPI2 and SPI3 controllers. Each Device shares the MOSI, MISO and SCLK signals but is only active on the bus when the Host asserts the Device's individual CS line.
**Bus** A signal bus, common to all Devices connected to one Host. In general, a bus includes the following lines: MISO, MOSI, SCLK, one or more CS lines, and, optionally, QUADWP and QUADHD. So Devices are connected to the same lines, with the exception that each Device has its own CS line. Several Devices can also share one CS line if connected in the daisy-chain manner.
- **MISO** Master In, Slave Out, a.k.a. Q. Data transmission from a Device to Host.
@ -63,7 +63,15 @@ As not every transaction requires both writing and reading data, you have a choi
Driver Usage
------------
- Initialize an SPI peripheral as a Device by calling the function cpp:func:`spi_slave_initialize`. Make sure to set the correct I/O pins in the struct :cpp:type:`bus_config`. Set the unused signals to ``-1``. If transactions will be longer than 32 bytes, allow a DMA channel 1 or 2 by setting the parameter ``dma_chan`` to ``1`` or ``2`` respectively. Otherwise, set ``dma_chan`` to ``0``.
- Initialize an SPI peripheral as a Device by calling the function cpp:func:`spi_slave_initialize`. Make sure to set the correct I/O pins in the struct :cpp:type:`bus_config`. Set the unused signals to ``-1``.
.. only:: esp32
If transactions will be longer than 32 bytes, allow a DMA channel 1 or 2 by setting the parameter ``dma_chan`` to ``1`` or ``2`` respectively. Otherwise, set ``dma_chan`` to ``0``.
.. only:: esp32s2
If transactions will be longer than 32 bytes, allow a DMA channel by setting the parameter ``dma_chan`` to the host device. Otherwise, set ``dma_chan`` to ``0``.
- Before initiating transactions, fill one or more :cpp:type:`spi_slave_transaction_t` structs with the transaction parameters required. Either queue all transactions by calling the function :cpp:func:`spi_slave_queue_trans` and, at a later time, query the result by using the function :cpp:func:`spi_slave_get_trans_result`, or handle all requests individually by feeding them into :cpp:func:`spi_slave_transmit`. The latter two functions will be blocked until the Host has initiated and finished a transaction, causing the queued data to be sent and received.
@ -79,47 +87,54 @@ The amount of data that the driver can read or write to the buffers is limited b
If the length of the transmission is greater than the buffer length, only the initial number of bits specified in the :cpp:member:`length` member will be sent and received. In this case, :cpp:member:`trans_len` is set to :cpp:member:`length` instead of the actual transaction length. To meet the actual transaction length requirements, set :cpp:member:`length` to a value greater than the maximum :cpp:member:`trans_len` expected. If the transmission length is shorter than the buffer length, only the data equal to the length of the buffer will be transmitted.
.. Warning::
.. only:: esp32
The ESP32 DMA hardware has a limit to the number of bytes sent by a Host and received by a Device. The transaction length must be longer than 8 bytes and a multiple of 4 bytes; otherwise, the SPI hardware might fail to receive the last 1 to 7 bytes.
.. Warning::
The ESP32 DMA hardware has a limit to the number of bytes sent by a Host and received by a Device. The transaction length must be longer than 8 bytes and a multiple of 4 bytes; otherwise, the SPI hardware might fail to receive the last 1 to 7 bytes.
GPIO Matrix and IO_MUX
----------------------
.. only:: esp32
Most of ESP32's peripheral signals have direct connection to their dedicated IO_MUX pins. However, the signals can also be routed to any other available pins using the less direct GPIO matrix.
GPIO Matrix and IO_MUX
----------------------
If at least one signal is routed through the GPIO matrix, then all signals will be routed through it. The GPIO matrix samples all signals at 80 MHz and transmits them between the GPIO and the peripheral.
Most of {IDF_TARGET_NAME}'s peripheral signals have direct connection to their dedicated IO_MUX pins. However, the signals can also be routed to any other available pins using the less direct GPIO matrix.
If the driver is configured so that all SPI signals are either routed to their dedicated IO_MUX pins or are not connected at all, the GPIO matrix will be bypassed.
If at least one signal is routed through the GPIO matrix, then all signals will be routed through it. The GPIO matrix samples all signals at 80 MHz and transmits them between the GPIO and the peripheral.
The GPIO matrix introduces flexibility of routing but also increases the input delay of the MISO signal, which makes MISO setup time violations more likely. If SPI needs to operate at high speeds, use dedicated IO_MUX pins.
If the driver is configured so that all SPI signals are either routed to their dedicated IO_MUX pins or are not connected at all, the GPIO matrix will be bypassed.
.. note::
The GPIO matrix introduces flexibility of routing but also increases the input delay of the MISO signal, which makes MISO setup time violations more likely. If SPI needs to operate at high speeds, use dedicated IO_MUX pins.
For more details about the influence of the MISO input delay on the maximum clock frequency, see :ref:`timing_considerations`.
.. note::
The IO_MUX pins for SPI buses are given below.
For more details about the influence of the MISO input delay on the maximum clock frequency, see :ref:`timing_considerations`.
+----------+------+------+
| Pin Name | SPI2 | SPI3 |
+ +------+------+
| | GPIO Number |
+==========+======+======+
| CS0* | 15 | 5 |
+----------+------+------+
| SCLK | 14 | 18 |
+----------+------+------+
| MISO | 12 | 19 |
+----------+------+------+
| MOSI | 13 | 23 |
+----------+------+------+
| QUADWP | 2 | 22 |
+----------+------+------+
| QUADHD | 4 | 21 |
+----------+------+------+
The IO_MUX pins for SPI buses are given below.
* Only the first Device attached to the bus can use the CS0 pin.
.. only:: esp32
+----------+------+------+
| Pin Name | SPI2 | SPI3 |
+ +------+------+
| | GPIO Number |
+==========+======+======+
| CS0* | 15 | 5 |
+----------+------+------+
| SCLK | 14 | 18 |
+----------+------+------+
| MISO | 12 | 19 |
+----------+------+------+
| MOSI | 13 | 23 |
+----------+------+------+
| QUADWP | 2 | 22 |
+----------+------+------+
| QUADHD | 4 | 21 |
+----------+------+------+
* Only the first Device attached to the bus can use the CS0 pin.
Speed and Timing Considerations
@ -130,7 +145,7 @@ Speed and Timing Considerations
Transaction Interval
^^^^^^^^^^^^^^^^^^^^
The ESP32 SPI slave peripherals are designed as general purpose Devices controlled by a CPU. As opposed to dedicated slaves, CPU-based SPI Devices have a limited number of pre-defined registers. All transactions must be handled by the CPU, which means that the transfers and responses are not real-time, and there might be noticeable latency.
The {IDF_TARGET_NAME} SPI slave peripherals are designed as general purpose Devices controlled by a CPU. As opposed to dedicated slaves, CPU-based SPI Devices have a limited number of pre-defined registers. All transactions must be handled by the CPU, which means that the transfers and responses are not real-time, and there might be noticeable latency.
As a solution, a Device's response rate can be doubled by using the functions :cpp:func:`spi_slave_queue_trans` and then :cpp:func:`spi_slave_get_trans_result` instead of using :cpp:func:`spi_slave_transmit`.

38
docs/en/api-reference/peripherals/temp_sensor.rst
View file

@ -4,22 +4,30 @@ ESP32-S2 Temperature Sensor
Overview
--------
The ESP32-S2 has a built-in temperature sensor. The temperature sensor module contains an 8-bit Sigma-Delta ADC and a temperature offset DAC.
The conversion relationship is the first columns of the table below. Among them, offset = 0 is the main measurement option, and other values are extended measurement options.
.. only:: esp32
+--------+------------------------+------------------------+
| offset | measure range(Celsius) | measure error(Celsius) |
+========+========================+========================+
| -2 | 50 ~ 125 | < 3 |
+--------+------------------------+------------------------+
| -1 | 20 ~ 100 | < 2 |
+--------+------------------------+------------------------+
| 0 | -10 ~ 80 | < 1 |
+--------+------------------------+------------------------+
| 1 | -30 ~ 50 | < 2 |
+--------+------------------------+------------------------+
| 2 | -40 ~ 20 | < 3 |
+--------+------------------------+------------------------+
.. note::
ESP32 does not have a built-in temperature sensor.
.. only:: esp32s2
The ESP32-S2 has a built-in temperature sensor. The temperature sensor module contains an 8-bit Sigma-Delta ADC and a temperature offset DAC.
The conversion relationship is the first columns of the table below. Among them, offset = 0 is the main measurement option, and other values are extended measurement options.
+--------+------------------------+------------------------+
| offset | measure range(Celsius) | measure error(Celsius) |
+========+========================+========================+
| -2 | 50 ~ 125 | < 3 |
+--------+------------------------+------------------------+
| -1 | 20 ~ 100 | < 2 |
+--------+------------------------+------------------------+
| 0 | -10 ~ 80 | < 1 |
+--------+------------------------+------------------------+
| 1 | -30 ~ 50 | < 2 |
+--------+------------------------+------------------------+
| 2 | -40 ~ 20 | < 3 |
+--------+------------------------+------------------------+
Application Example
-------------------

11
docs/en/api-reference/peripherals/timer.rst
View file

@ -2,11 +2,12 @@ Timer
=====
:link_to_translation:`zh_CN:[中文]`
{IDF_TARGET_INT_CLR_REG: default="int_clr", esp32="int_clr_timers"}
Introduction
------------
The ESP32 chip contains two hardware timer groups. Each group has two general-purpose hardware timers. They are all 64-bit generic timers based on 16-bit prescalers and 64-bit up / down counters which are capable of being auto-reloaded.
The {IDF_TARGET_NAME} chip contains two hardware timer groups. Each group has two general-purpose hardware timers. They are all 64-bit generic timers based on 16-bit prescalers and 64-bit up / down counters which are capable of being auto-reloaded.
Functional Overview
@ -25,7 +26,7 @@ The following sections of this document cover the typical steps to configure and
Timer Initialization
^^^^^^^^^^^^^^^^^^^^
The two ESP32 timer groups, with two timers in each, provide the total of four individual timers for use. An ESP32 timer group should be identified using :cpp:type:`timer_group_t`. An individual timer in a group should be identified with :cpp:type:`timer_idx_t`.
The two {IDF_TARGET_NAME} timer groups, with two timers in each, provide the total of four individual timers for use. An {IDF_TARGET_NAME} timer group should be identified using :cpp:type:`timer_group_t`. An individual timer in a group should be identified with :cpp:type:`timer_idx_t`.
First of all, the timer should be initialized by calling the function :cpp:func:`timer_init` and passing a structure :cpp:type:`timer_config_t` to it to define how the timer should operate. In particular, the following timer parameters can be set:
@ -85,14 +86,14 @@ To check the specified alarm value, call :cpp:func:`timer_get_alarm_value`.
Interrupts
^^^^^^^^^^
Registration of the interrupt handler for a specific timer or a timer group can be done by calling :cpp:func:`timer_isr_register`.
Registration of the interrupt handler for a specific timer or a timer group can be done by calling :cpp:func:`timer_isr_register`.
To enable interrupts for a timer group, call :cpp:func:`timer_group_intr_enable`, for a specific timer call :cpp:func:`timer_enable_intr`.
To disable interrupts for a timer group, call :cpp:func:`timer_group_intr_disable`, for a specified timer, call :cpp:func:`timer_disable_intr`.
When handling an interrupt within an interrupt serivce routine (ISR), the interrupt status bit needs to be explicitly cleared. To do that, set the ``TIMERGN.int_clr_timers.tM`` structure, defined in :component_file:`soc/esp32/include/soc/timer_group_struct.h`. In this structure, ``N`` is the timer group number [0, 1], ``M`` is the timer number [0, 1]. For example, to clear an interrupt status bit for the timer 1 in the timer group 0, call the following::
When handling an interrupt within an interrupt serivce routine (ISR), the interrupt status bit needs to be explicitly cleared. To do that, set the ``TIMERGN.{IDF_TARGET_INT_CLR_REG}.tM`` structure, defined in :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/timer_group_struct.h`. In this structure, ``N`` is the timer group number [0, 1], ``M`` is the timer number [0, 1]. For example, to clear an interrupt status bit for the timer 1 in the timer group 0, call the following::
TIMERG0.int_clr_timers.t1 = 1
TIMERG0.{IDF_TARGET_INT_CLR_REG}.t1 = 1
For more information on how to use interrupts, please see the application example below.

109
docs/en/api-reference/peripherals/touch_pad.rst
View file

@ -8,11 +8,23 @@ Introduction
A touch sensor system is built on a substrate which carries electrodes and relevant connections under a protective flat surface. When a user touches the surface, the capacitance variation is used to evaluate if the touch was valid.
ESP32 can handle up to 10 capacitive touch pads / GPIOs. The sensing pads can be arranged in different combinations (e.g., matrix, slider), so that a larger area or more points can be detected. The touch pad sensing process is under the control of a hardware-implemented finite-state machine (FSM) which is initiated by software or a dedicated hardware timer.
.. only:: esp32
Design, operation, and control registers of a touch sensor are discussed in `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ (PDF). Please refer to this manual for additional details on how this subsystem works.
ESP32 can handle up to 10 capacitive touch pads / GPIOs.
In-depth design details of touch sensors and firmware development guidelines for ESP32 are available in `Touch Sensor Application Note <https://github.com/espressif/esp-iot-solution/blob/master/documents/touch_pad_solution/touch_sensor_design_en.md>`_. If you want to test touch sensors in various configurations without building them on your own, check the `Guide for ESP32-Sense Development Kit <https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/esp32_sense_kit_guide_en.md>`_.
.. only:: esp32s2
{IDF_TARGET_NAME} can handle up to 14 capacitive touch pads / GPIOs.
The sensing pads can be arranged in different combinations (e.g., matrix, slider), so that a larger area or more points can be detected. The touch pad sensing process is under the control of a hardware-implemented finite-state machine (FSM) which is initiated by software or a dedicated hardware timer.
Design, operation, and control registers of a touch sensor are discussed in `{IDF_TARGET_NAME} Technical Reference Manual <IDF_TARGET_TRM_URL>`_ (PDF). Please refer to this manual for additional details on how this subsystem works.
In-depth design details of touch sensors and firmware development guidelines for {IDF_TARGET_NAME} are available in `Touch Sensor Application Note <https://github.com/espressif/esp-iot-solution/blob/master/documents/touch_pad_solution/touch_sensor_design_en.md>`_.
.. only:: esp32
If you want to test touch sensors in various configurations without building them on your own, check the `Guide for ESP32-Sense Development Kit <https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/esp32_sense_kit_guide_en.md>`_.
Functionality Overview
@ -29,13 +41,13 @@ Description of API is broken down into groups of functions to provide a quick ov
- Setting up interrupts to report touch detection
- Waking up from Sleep mode on interrupt
For detailed description of a particular function, please go to Section :ref:`touch_pad-api-reference`. Practical implementation of this API is covered in Section :ref:`touch_pad-api-examples`.
For detailed description of a particular function, please go to Section :ref:`touch_pad-api-reference`. Practical implementation of this API is covered in Section :ref:`Application Examples <touch_pad-api-examples>`.
Initialization
^^^^^^^^^^^^^^
Before using a touch pad, you need to initialize the touch pad driver by calling the function :cpp:func:`touch_pad_init`. This function sets several ``.._DEFAULT`` driver parameters listed in :ref:`touch_pad-api-reference` under *Macros*. It also removes the information about which pads have been touched before, if any, and disables interrupts.
Before using a touch pad, you need to initialize the touch pad driver by calling the function :cpp:func:`touch_pad_init`. This function sets several ``.._DEFAULT`` driver parameters listed in :ref:`touch_pad-api-reference` under *Macros*. It also removes the information about which pads have been touched before, if any, and disables interrupts.
If the driver is not required anymore, deinitialize it by calling :cpp:func:`touch_pad_deinit`.
@ -43,7 +55,7 @@ If the driver is not required anymore, deinitialize it by calling :cpp:func:`tou
Configuration
^^^^^^^^^^^^^
Enabling the touch sensor functionality for a particular GPIO is done with :cpp:func:`touch_pad_config`.
Enabling the touch sensor functionality for a particular GPIO is done with :cpp:func:`touch_pad_config`.
Use the function :cpp:func:`touch_pad_set_fsm_mode` to select if touch pad measurement (operated by FSM) should be started automatically by a hardware timer, or by software. If software mode is selected, use :cpp:func:`touch_pad_sw_start` to start the FSM.
@ -51,18 +63,28 @@ Use the function :cpp:func:`touch_pad_set_fsm_mode` to select if touch pad measu
Touch State Measurements
^^^^^^^^^^^^^^^^^^^^^^^^
The following two functions come in handy to read raw or filtered measurements from the sensor:
.. only:: esp32
* :cpp:func:`touch_pad_read`
* :cpp:func:`touch_pad_read_filtered`
The following two functions come in handy to read raw or filtered measurements from the sensor:
They can also be used, for example, to evaluate a particular touch pad design by checking the range of sensor readings when a pad is touched or released. This information can be then used to establish a touch threshold.
* :cpp:func:`touch_pad_read_raw_data`
* :cpp:func:`touch_pad_read_filtered`
.. note::
They can also be used, for example, to evaluate a particular touch pad design by checking the range of sensor readings when a pad is touched or released. This information can be then used to establish a touch threshold.
Before using :cpp:func:`touch_pad_read_filtered`, you need to initialize and configure the filter by calling specific filter functions described in Section `Filtering of Measurements`_.
.. note::
For the demonstration of how to use both read functions, check the application example :example:`peripherals/touch_pad_read`.
Before using :cpp:func:`touch_pad_read_filtered`, you need to initialize and configure the filter by calling specific filter functions described in Section `Filtering of Measurements`_.
.. only:: esp32s2
The following function come in handy to read raw measurements from the sensor:
* :cpp:func:`touch_pad_read_raw_data`
It can also be used, for example, to evaluate a particular touch pad design by checking the range of sensor readings when a pad is touched or released. This information can be then used to establish a touch threshold.
For the demonstration of how to read the touch pad data, check the application example :example:`peripherals/touch_pad_read`.
Optimization of Measurements
@ -81,14 +103,14 @@ The following list summarizes available measurement parameters and corresponding
* Measurement time: :cpp:func:`touch_pad_set_meas_time`
Relationship between the voltage range (high / low reference voltages), speed (slope), and measurement time is shown in the figure below.
Relationship between the voltage range (high / low reference voltages), speed (slope), and measurement time is shown in the figure below.
.. figure:: ../../../_static/touch_pad-measurement-parameters.jpg
:align: center
:alt: Touch Pad - relationship between measurement parameters
:alt: Touch Pad - relationship between measurement parameters
:figclass: align-center
Touch pad - relationship between measurement parameters
Touch pad - relationship between measurement parameters
The last chart *Output* represents the touch sensor reading, i.e., the count of pulses collected within the measurement time.
@ -98,18 +120,28 @@ All functions are provided in pairs to *set* a specific parameter and to *get* t
Filtering of Measurements
^^^^^^^^^^^^^^^^^^^^^^^^^
.. only:: esp32
If measurements are noisy, you can filter them with provided API functions. Before using the filter, please start it by calling :cpp:func:`touch_pad_filter_start`.
If measurements are noisy, you can filter them with provided API functions. Before using the filter, please start it by calling :cpp:func:`touch_pad_filter_start`.
The filter type is IIR (infinite impulse response), and it has a configurable period that can be set with the function :cpp:func:`touch_pad_set_filter_period`.
The filter type is IIR (infinite impulse response), and it has a configurable period that can be set with the function :cpp:func:`touch_pad_set_filter_period`.
You can stop the filter with :cpp:func:`touch_pad_filter_stop`. If not required anymore, the filter can be deleted by invoking :cpp:func:`touch_pad_filter_delete`.
You can stop the filter with :cpp:func:`touch_pad_filter_stop`. If not required anymore, the filter can be deleted by invoking :cpp:func:`touch_pad_filter_delete`.
.. only:: esp32s2
If measurements are noisy, you can filter them with provided API functions. The {IDF_TARGET_NAME}'s touch functionality provide two sets of APIs for doing this.
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`
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`
Touch Detection
^^^^^^^^^^^^^^^
Touch detection is implemented in ESP32's hardware based on the user-configured threshold and raw measurements executed by FSM. Use the functions :cpp:func:`touch_pad_get_status` to check which pads have been touched and :cpp:func:`touch_pad_clear_status` to clear the touch status information.
Touch detection is implemented in ESP32's hardware based on the user-configured threshold and raw measurements executed by FSM. Use the functions :cpp:func:`touch_pad_get_status` to check which pads have been touched and :cpp:func:`touch_pad_clear_status` to clear the touch status information.
Hardware touch detection can also be wired to interrupts. This is described in the next section.
@ -123,7 +155,9 @@ Before enabling an interrupt on a touch detection, you should establish a touch
Once a detection threshold is established, it can be set during initialization with :cpp:func:`touch_pad_config` or at the runtime with :cpp:func:`touch_pad_set_thresh`.
In the next step, configure how interrupts are triggered. They can be triggered below or above the threshold, which is set with the function :cpp:func:`touch_pad_set_trigger_mode`.
.. only:: esp32
In the next step, configure how interrupts are triggered. They can be triggered below or above the threshold, which is set with the function :cpp:func:`touch_pad_set_trigger_mode`.
Finally, configure and manage interrupt calls using the following functions:
@ -132,26 +166,30 @@ Finally, configure and manage interrupt calls using the following functions:
When interrupts are operational, you can obtain the information from which particular pad an interrupt came by invoking :cpp:func:`touch_pad_get_status` and clear the pad status with :cpp:func:`touch_pad_clear_status`.
.. note::
.. only:: esp32
Interrupts on touch detection operate on raw / unfiltered measurements checked against user established threshold and are implemented in hardware. Enabling the software filtering API (see :ref:`touch_pad-api-filtering-of-measurements`) does not affect this process.
.. note::
Interrupts on touch detection operate on raw / unfiltered measurements checked against user established threshold and are implemented in hardware. Enabling the software filtering API (see :ref:`touch_pad-api-filtering-of-measurements`) does not affect this process.
.. only:: esp32
Wakeup from Sleep Mode
^^^^^^^^^^^^^^^^^^^^^^
If touch pad interrupts are used to wake up the chip from a sleep mode, you can select a certain configuration of pads (SET1 or both SET1 and SET2) that should be touched to trigger the interrupt and cause the subsequent wakeup. To do so, use the function :cpp:func:`touch_pad_set_trigger_source`.
Configuration of required bit patterns of pads may be managed for each 'SET' with:
* :cpp:func:`touch_pad_set_group_mask` / :cpp:func:`touch_pad_get_group_mask`
* :cpp:func:`touch_pad_clear_group_mask`
Wakeup from Sleep Mode
^^^^^^^^^^^^^^^^^^^^^^
If touch pad interrupts are used to wake up the chip from a sleep mode, you can select a certain configuration of pads (SET1 or both SET1 and SET2) that should be touched to trigger the interrupt and cause the subsequent wakeup. To do so, use the function :cpp:func:`touch_pad_set_trigger_source`.
Configuration of required bit patterns of pads may be managed for each 'SET' with:
* :cpp:func:`touch_pad_set_group_mask` / :cpp:func:`touch_pad_get_group_mask`
* :cpp:func:`touch_pad_clear_group_mask`
.. _touch_pad-api-examples:
Application Examples
--------------------
.. _touch_pad-api-examples:
- Touch sensor read example: :example:`peripherals/touch_pad_read`.
- Touch sensor interrupt example: :example:`peripherals/touch_pad_interrupt`.
@ -162,7 +200,8 @@ Application Examples
API Reference
-------------
.. include-build-file:: inc/touch_pad.inc
.. include-build-file:: inc/touch_sensor.inc
.. include-build-file:: inc/touch_sensor_common.inc
GPIO Lookup Macros
^^^^^^^^^^^^^^^^^^

59
docs/en/api-reference/peripherals/uart.rst
View file

@ -1,29 +1,38 @@
UART
====
{IDF_TARGET_UART_NUM:default = "UART1", esp32 = "UART2", esp32s2 = "UART1"}
Overview
--------
A Universal Asynchronous Receiver/Transmitter (UART) is a hardware feature that handles communication (i.e., timing requirements and data framing) using widely-adapted asynchronous serial communication interfaces, such as RS232, RS422, RS485. A UART provides a widely adopted and cheap method to realize full-duplex or half-duplex data exchange among different devices.
The ESP32 chip has three UART controllers (UART0, UART1, and UART2) that feature an identical set of registers for ease of programming and flexibility. Each UART controller is independently configurable with parameters such as baud rate, data bit length, bit ordering, number of stop bits, parity bit etc. All the controllers are compatible with UART-enabled devices from various manufacturers and can also support Infrared Data Association protocols (IrDA).
.. only:: esp32
The ESP32 chip has three UART controllers (UART0, UART1, and UART2) that feature an identical set of registers for ease of programming and flexibility.
.. only:: esp32s2
The ESP32-S2 chip has two UART controllers (UART0 and UART1) that feature an identical set of registers for ease of programming and flexibility.
Each UART controller is independently configurable with parameters such as baud rate, data bit length, bit ordering, number of stop bits, parity bit etc. All the controllers are compatible with UART-enabled devices from various manufacturers and can also support Infrared Data Association protocols (IrDA).
Functional Overview
-------------------
The following overview describes how to establish communication between an ESP32 and other UART devices using the functions and data types of the UART driver. The overview reflects a typical programming workflow and is broken down into the sections provided below:
The following overview describes how to establish communication between an {IDF_TARGET_NAME} and other UART devices using the functions and data types of the UART driver. The overview reflects a typical programming workflow and is broken down into the sections provided below:
1. :ref:`uart-api-setting-communication-parameters` - Setting baud rate, data bits, stop bits, etc.
2. :ref:`uart-api-setting-communication-pins` - Assigning pins for connection to a device.
3. :ref:`uart-api-driver-installation` - Allocating ESP32's resources for the UART driver.
3. :ref:`uart-api-driver-installation` - Allocating {IDF_TARGET_NAME}'s resources for the UART driver.
4. :ref:`uart-api-running-uart-communication` - Sending / receiving data
5. :ref:`uart-api-using-interrupts` - Triggering interrupts on specific communication events
6. :ref:`uart-api-deleting-driver` - Freeing allocated resources if a UART communication is no longer required
Steps 1 to 3 comprise the configuration stage. Step 4 is where the UART starts operating. Steps 5 and 6 are optional.
The UART driver's functions identify each of the three UART controllers using :cpp:type:`uart_port_t`. This identification is needed for all the following function calls.
The UART driver's functions identify each of the UART controllers using :cpp:type:`uart_port_t`. This identification is needed for all the following function calls.
.. _uart-api-setting-communication-parameters:
@ -41,7 +50,7 @@ Call the function :cpp:func:`uart_param_config` and pass to it a :cpp:type:`uart
.. code-block:: c
const int uart_num = UART_NUM_2;
const int uart_num = {IDF_TARGET_UART_NUM};
uart_config_t uart_config = {
.baud_rate = 115200,
.data_bits = UART_DATA_8_BITS,
@ -92,8 +101,19 @@ The same macro should be specified for pins that will not be used.
.. code-block:: c
// Set UART pins(TX: IO16 (UART2 default), RX: IO17 (UART2 default), RTS: IO18, CTS: IO19)
ESP_ERROR_CHECK(uart_set_pin(UART_NUM_2, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, 18, 19));
.. only:: esp32
::
// Set UART pins(TX: IO16 (UART2 default), RX: IO17 (UART2 default), RTS: IO18, CTS: IO19)
ESP_ERROR_CHECK(uart_set_pin(UART_NUM_2, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, 18, 19));
.. only:: esp32s2
::
// Set UART pins(TX: IO17 (UART1 default), RX: IO18 (UART1 default), RTS: IO19, CTS: IO20)
ESP_ERROR_CHECK(uart_set_pin(UART_NUM_1, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, 19, 20));
.. _uart-api-driver-installation:
@ -108,7 +128,7 @@ Once the communication pins are set, install the driver by calling :cpp:func:`ua
- Event queue handle and size
- Flags to allocate an interrupt
The function will allocate the required ESP32 resources for the UART driver.
The function will allocate the required internal resources for the UART driver.
.. code-block:: c
@ -116,7 +136,7 @@ The function will allocate the required ESP32 resources for the UART driver.
const int uart_buffer_size = (1024 * 2);
QueueHandle_t uart_queue;
// Install UART driver using an event queue here
ESP_ERROR_CHECK(uart_driver_install(UART_NUM_2, uart_buffer_size, \
ESP_ERROR_CHECK(uart_driver_install({IDF_TARGET_UART_NUM}, uart_buffer_size, \
uart_buffer_size, 10, &uart_queue, 0));
Once this step is complete, you can connect the external UART device and check the communication.
@ -181,7 +201,7 @@ Once the data is received by the UART and saved in the Rx FIFO buffer, it needs
.. code-block:: c
// Read data from UART.
const int uart_num = UART_NUM_2;
const int uart_num = {IDF_TARGET_UART_NUM};
uint8_t data[128];
int length = 0;
ESP_ERROR_CHECK(uart_get_buffered_data_len(uart_num, (size_t*)&length));
@ -212,7 +232,7 @@ The UART controller supports a number of communication modes. A mode can be sele
Using Interrupts
^^^^^^^^^^^^^^^^
There are many interrupts that can be generated following specific UART states or detected errors. The full list of available interrupts is provided in `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#page=342>`_ (PDF). You can enable or disable specific interrupts by calling :cpp:func:`uart_enable_intr_mask` or :cpp:func:`uart_disable_intr_mask` respectively. The mask of all interrupts is available as :c:macro:`UART_INTR_MASK`.
There are many interrupts that can be generated following specific UART states or detected errors. The full list of available interrupts is provided in the SoC Technical Reference Manual. You can enable or disable specific interrupts by calling :cpp:func:`uart_enable_intr_mask` or :cpp:func:`uart_disable_intr_mask` respectively. The mask of all interrupts is available as :c:macro:`UART_INTR_MASK`.
By default, the :cpp:func:`uart_driver_install` function installs the driver's internal interrupt handler to manage the Tx and Rx ring buffers and provides high-level API functions like events (see below). It is also possible to register a lower level interrupt handler instead using :cpp:func:`uart_isr_register`, and to free it again using :cpp:func:`uart_isr_free`. Some UART driver functions which use the Tx and Rx ring buffers, events, etc. will not automatically work in this case - it is necessary to handle the interrupts directly in the ISR. Inside the custom handler implementation, clear the interrupt status bits using :cpp:func:`uart_clear_intr_status`.
@ -251,19 +271,19 @@ Overview of RS485 specific communication options
.. note::
The following section will use ``[UART_REGISTER_NAME].[UART_FIELD_BIT]`` to refer to UART register fields/bits. To find more information on a specific option bit, open `Register Summary in the ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#page=344>`_ (PDF), use the register name to navigate to the register description and then find the field/bit.
The following section will use ``[UART_REGISTER_NAME].[UART_FIELD_BIT]`` to refer to UART register fields/bits. To find more information on a specific option bit, open the Register Summary section of the SoC Technical Reference Manual. Use the register name to navigate to the register description and then find the field/bit.
- ``UART_RS485_CONF_REG.UART_RS485_EN``: setting this bit enables RS485 communication mode support.
- ``UART_RS485_CONF_REG.UART_RS485TX_RX_EN``: if this bit is set, the transmitter's output signal loops back to the receiver's input signal.
- ``UART_RS485_CONF_REG.UART_RS485RXBY_TX_EN``: if this bit is set, the transmitter will still be sending data if the receiver is busy (remove collisions automatically by hardware).
The ESP32's RS485 UART hardware can detect signal collisions during transmission of a datagram and generate the interrupt ``UART_RS485_CLASH_INT`` if this interrupt is enabled. The term collision means that a transmitted datagram is not equal to the one received on the other end. Data collisions are usually associated with the presence of other active devices on the bus or might occur due to bus errors.
The {IDF_TARGET_NAME}'s RS485 UART hardware can detect signal collisions during transmission of a datagram and generate the interrupt ``UART_RS485_CLASH_INT`` if this interrupt is enabled. The term collision means that a transmitted datagram is not equal to the one received on the other end. Data collisions are usually associated with the presence of other active devices on the bus or might occur due to bus errors.
The collision detection feature allows handling collisions when their interrupts are activated and triggered. The interrupts ``UART_RS485_FRM_ERR_INT`` and ``UART_RS485_PARITY_ERR_INT`` can be used with the collision detection feature to control frame errors and parity bit errors accordingly in RS485 mode. This functionality is supported in the UART driver and can be used by selecting the :cpp:enumerator:`UART_MODE_RS485_APP_CTRL` mode (see the function :cpp:func:`uart_set_mode`).
The collision detection feature can work with circuit A and circuit C (see Section `Interface Connection Options`_). In the case of using circuit A or B, the RTS pin connected to the DE pin of the bus driver should be controlled by the user application. Use the function :cpp:func:`uart_get_collision_flag` to check if the collision detection flag has been raised.
The ESP32's UART controllers themselves do not support half-duplex communication as they cannot provide automatic control of the RTS pin connected to the ~RE/DE input of RS485 bus driver. However, half-duplex communication can be achieved via software control of the RTS pin by the UART driver. This can be enabled by selecting the :cpp:enumerator:`UART_MODE_RS485_HALF_DUPLEX` mode when calling :cpp:func:`uart_set_mode`.
The {IDF_TARGET_NAME} UART controllers themselves do not support half-duplex communication as they cannot provide automatic control of the RTS pin connected to the ~RE/DE input of RS485 bus driver. However, half-duplex communication can be achieved via software control of the RTS pin by the UART driver. This can be enabled by selecting the :cpp:enumerator:`UART_MODE_RS485_HALF_DUPLEX` mode when calling :cpp:func:`uart_set_mode`.
Once the host starts writing data to the Tx FIFO buffer, the UART driver automatically asserts the RTS pin (logic 1); once the last bit of the data has been transmitted, the driver de-asserts the RTS pin (logic 0). To use this mode, the software would have to disable the hardware flow control function. This mode works with all the used circuits shown below.
@ -271,7 +291,7 @@ Once the host starts writing data to the Tx FIFO buffer, the UART driver automat
Interface Connection Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This section provides example schematics to demonstrate the basic aspects of ESP32's RS485 interface connection.
This section provides example schematics to demonstrate the basic aspects of {IDF_TARGET_NAME}'s RS485 interface connection.
.. note::
@ -291,7 +311,7 @@ Circuit A: Collision Detection Circuit
RXD <------| R |
| B|----------<> B
TXD ------>| D ADM483 |
ESP32 | | RS485 bus side
ESP | | RS485 bus side
RTS ------>| DE |
| A|----------<> A
+----| /RE |
@ -299,12 +319,13 @@ Circuit A: Collision Detection Circuit
| |
GND GND
This circuit is preferable because it allows for collision detection and is quite simple at the same time. The receiver in the line driver is constantly enabled, which allows the UART to monitor the RS485 bus. Echo suppression is performed by the ESP32 hardware when the bit ``UART_RS485_CONF_REG.UART_RS485TX_RX_EN`` is enabled.
This circuit is preferable because it allows for collision detection and is quite simple at the same time. The receiver in the line driver is constantly enabled, which allows the UART to monitor the RS485 bus. Echo suppression is performed by the UART peripheral when the bit ``UART_RS485_CONF_REG.UART_RS485TX_RX_EN`` is enabled.
Circuit B: Manual Switching Transmitter/Receiver Without Collision Detection
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.. code-block:: none
VCC ---------------+
@ -313,7 +334,7 @@ Circuit B: Manual Switching Transmitter/Receiver Without Collision Detection
RXD <------| R |
| B|-----------<> B
TXD ------>| D ADM483 |
ESP32 | | RS485 bus side
ESP | | RS485 bus side
RTS --+--->| DE |
| | A|-----------<> A
+----| /RE |
@ -371,7 +392,7 @@ The table below describes the code examples available in the directory :example:
* - :example:`peripherals/uart/uart_select`
- Using synchronous I/O multiplexing for UART file descriptors.
* - :example:`peripherals/uart/uart_echo_rs485`
- Setting up UART driver to communicate over RS485 interface in half-duplex mode. This example is similar to :example:`peripherals/uart/uart_echo` but allows communication through an RS485 interface chip connected to ESP32 pins.
- Setting up UART driver to communicate over RS485 interface in half-duplex mode. This example is similar to :example:`peripherals/uart/uart_echo` but allows communication through an RS485 interface chip connected to {IDF_TARGET_NAME} pins.
* - :example:`peripherals/uart/nmea0183_parser`
- Obtaining GPS information by parsing NMEA0183 statements received from GPS via the UART peripheral.

6
docs/en/contribute/add-ons-reference.rst
View file

@ -150,7 +150,11 @@ Other Extensions
An extension for replacing generic target related names with the idf_target passed to the Sphinx command line.
This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` will, if the backspaces are removed, render as This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`.
This cannot be used inside tables.
Also supports markup for defining local (single .rst-file) substitions with the following syntax: {\IDF_TARGET_TX_PIN:default="IO3",esp32="IO4",esp32s2="IO5"}
This will define a replacement of the tag {\IDF_TARGET_TX_PIN} in the current rst-file.
These replacements cannot be used inside markup that rely on allignment of characters, e.g. tables.
Related Documents
-----------------