doc: Update English pages with generic target name
This commit is contained in:
Marius Vikhammer
committed by
Angus Gratton
Angus Gratton
parent
c848aa74ac
commit
9352899d69
@@ -4,24 +4,27 @@ Analog to Digital Converter
|
||||
Overview
|
||||
--------
|
||||
|
||||
The ESP32 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 {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.
|
||||
2. Some of the ADC2 pins are used as strapping pins (GPIO 0, 2, 15) thus cannot be used freely. Such is the case in the following official Development Kits:
|
||||
..only:: esp32
|
||||
|
||||
- :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.
|
||||
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.
|
||||
2. Some of the ADC2 pins are used as strapping pins (GPIO 0, 2, 15) thus cannot be used freely. Such is the case in the following official Development Kits:
|
||||
|
||||
- :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.
|
||||
|
||||
Configuration and Reading ADC
|
||||
-----------------------------
|
||||
|
||||
The ADC should be configured before reading is taken.
|
||||
|
||||
- For ADC1, configure desired precision and attenuation by calling functions :cpp:func:`adc1_config_width` and :cpp:func:`adc1_config_channel_atten`.
|
||||
- For ADC1, configure desired precision and attenuation by calling functions :cpp:func:`adc1_config_width` and :cpp:func:`adc1_config_channel_atten`.
|
||||
- For ADC2, configure the attenuation by :cpp:func:`adc2_config_channel_atten`. The reading width of ADC2 is configured every time you take the reading.
|
||||
|
||||
|
||||
Attenuation configuration is done per channel, see :cpp:type:`adc1_channel_t` and :cpp:type:`adc2_channel_t`, set as a parameter of above functions.
|
||||
|
||||
Then it is possible to read ADC conversion result with :cpp:func:`adc1_get_raw` and :cpp:func:`adc2_get_raw`. Reading width of ADC2 should be set as a parameter of :cpp:func:`adc2_get_raw` instead of in the configuration functions.
|
||||
@@ -55,7 +58,7 @@ Reading voltage on ADC2 channel 7 (GPIO 27)::
|
||||
#include <driver/adc.h>
|
||||
|
||||
...
|
||||
|
||||
|
||||
int read_raw;
|
||||
adc2_config_channel_atten( ADC2_CHANNEL_7, ADC_ATTEN_0db );
|
||||
|
||||
@@ -87,23 +90,23 @@ The value read in both these examples is 12 bits wide (range 0-4095).
|
||||
Minimizing Noise
|
||||
----------------
|
||||
|
||||
The ESP32 ADC can be sensitive to noise leading to large discrepancies in ADC readings. To minimize noise, users may connect a 0.1uF capacitor to the ADC input pad in use. Multisampling may also be used to further mitigate the effects of noise.
|
||||
The {IDF_TARGET_NAME} ADC can be sensitive to noise leading to large discrepancies in ADC readings. To minimize noise, users may connect a 0.1uF capacitor to the ADC input pad in use. Multisampling may also be used to further mitigate the effects of noise.
|
||||
|
||||
.. figure:: ../../../_static/adc-noise-graph.jpg
|
||||
:align: center
|
||||
:alt: ADC noise mitigation
|
||||
|
||||
|
||||
Graph illustrating noise mitigation using capacitor and multisampling of 64 samples.
|
||||
|
||||
ADC Calibration
|
||||
---------------
|
||||
|
||||
The :component_file:`esp_adc_cal/include/esp_adc_cal.h` API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100mV, however the true reference voltage can range from 1000mV to 1200mV amongst different ESP32s.
|
||||
The :component_file:`esp_adc_cal/include/esp_adc_cal.h` API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100mV, however the true reference voltage can range from 1000mV to 1200mV amongst different {IDF_TARGET_NAME}s.
|
||||
|
||||
.. figure:: ../../../_static/adc-vref-graph.jpg
|
||||
:align: center
|
||||
:alt: ADC reference voltage comparison
|
||||
|
||||
|
||||
Graph illustrating effect of differing reference voltages on the ADC voltage curve.
|
||||
|
||||
Correcting ADC readings using this API involves characterizing one of the ADCs at a given attenuation to obtain a characteristics curve (ADC-Voltage curve) that takes into account the difference in ADC reference voltage. The characteristics curve is in the form of ``y = coeff_a * x + coeff_b`` and is used to convert ADC readings to voltages in mV. Calculation of the characteristics curve is based on calibration values which can be stored in eFuse or provided by the user.
|
||||
@@ -111,21 +114,23 @@ Correcting ADC readings using this API involves characterizing one of the ADCs a
|
||||
Calibration Values
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Calibration values are used to generate characteristic curves that account for the unique ADC reference voltage of a particular ESP32. There are currently three sources of calibration values. The availability of these calibration values will depend on the type and production date of the ESP32 chip/module.
|
||||
Calibration values are used to generate characteristic curves that account for the unique ADC reference voltage of a particular {IDF_TARGET_NAME}. There are currently three sources of calibration values. The availability of these calibration values will depend on the type and production date of the {IDF_TARGET_NAME} chip/module.
|
||||
|
||||
* **Two Point** values represent each of the ADCs’ readings at 150mV and 850mV. To obtain more accurate calibration results these values should be measured by user and burned into eFuse ``BLOCK3``.
|
||||
|
||||
* **eFuse Vref** represents the true ADC reference voltage. This value is measured and burned into eFuse ``BLOCK0`` during factory calibration.
|
||||
* **eFuse Vref** represents the true ADC reference voltage. This value is measured and burned into eFuse ``BLOCK0`` during factory calibration.
|
||||
|
||||
* **Default Vref** is an estimate of the ADC reference voltage provided by the user as a parameter during characterization. If Two Point or eFuse Vref values are unavailable, **Default Vref** will be used.
|
||||
|
||||
Individual measurement and burning of the **eFuse Vref** has been applied to ESP32-D0WD and ESP32-D0WDQ6 chips produced on/after the 1st week of 2018. Such chips may be recognized by date codes on/later than 012018 (see Line 4 on figure below).
|
||||
.. only:: esp32
|
||||
|
||||
.. figure:: ../../../_static/chip_surface_marking.png
|
||||
:align: center
|
||||
:alt: ESP32 Chip Surface Marking
|
||||
|
||||
ESP32 Chip Surface Marking
|
||||
Individual measurement and burning of the **eFuse Vref** has been applied to ESP32-D0WD and ESP32-D0WDQ6 chips produced on/after the 1st week of 2018. Such chips may be recognized by date codes on/later than 012018 (see Line 4 on figure below).
|
||||
|
||||
.. figure:: ../../../_static/chip_surface_marking.png
|
||||
:align: center
|
||||
:alt: ESP32 Chip Surface Marking
|
||||
|
||||
ESP32 Chip Surface Marking
|
||||
|
||||
If you would like to purchase chips or modules with calibration, double check with distributor or Espressif directly.
|
||||
|
||||
@@ -135,7 +140,7 @@ If you are unable to check the date code (i.e. the chip may be enclosed inside a
|
||||
|
||||
$IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 adc_info
|
||||
|
||||
Replace ``/dev/ttyUSB0`` with ESP32 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::
|
||||
|
||||
@@ -163,9 +168,9 @@ Characterizing an ADC at a particular attenuation::
|
||||
|
||||
#include "driver/adc.h"
|
||||
#include "esp_adc_cal.h"
|
||||
|
||||
|
||||
...
|
||||
|
||||
|
||||
//Characterize ADC at particular atten
|
||||
esp_adc_cal_characteristics_t *adc_chars = calloc(1, sizeof(esp_adc_cal_characteristics_t));
|
||||
esp_adc_cal_value_t val_type = esp_adc_cal_characterize(unit, atten, ADC_WIDTH_BIT_12, DEFAULT_VREF, adc_chars);
|
||||
@@ -182,15 +187,15 @@ Reading an ADC then converting the reading to a voltage::
|
||||
|
||||
#include "driver/adc.h"
|
||||
#include "esp_adc_cal.h"
|
||||
|
||||
|
||||
...
|
||||
uint32_t reading = adc1_get_raw(ADC1_CHANNEL_5);
|
||||
uint32_t voltage = esp_adc_cal_raw_to_voltage(reading, adc_chars);
|
||||
|
||||
|
||||
Routing ADC reference voltage to GPIO, so it can be manually measured (for **Default Vref**)::
|
||||
|
||||
#include "driver/adc.h"
|
||||
|
||||
|
||||
...
|
||||
|
||||
esp_err_t status = adc2_vref_to_gpio(GPIO_NUM_25);
|
||||
|
||||
@@ -6,10 +6,10 @@ Controller Area Network (CAN)
|
||||
Overview
|
||||
--------
|
||||
|
||||
The ESP32'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.
|
||||
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.
|
||||
|
||||
.. warning::
|
||||
The ESP32 CAN controller is not compatible with CAN FD frames and will interpret such frames as errors.
|
||||
The {IDF_TARGET_NAME} CAN controller is not compatible with CAN FD frames and will interpret such frames as errors.
|
||||
|
||||
This programming guide is split into the following sections:
|
||||
|
||||
@@ -199,9 +199,11 @@ Bit timing **macro initializers** are also available for commonly used CAN bus b
|
||||
- ``CAN_TIMING_CONFIG_800KBITS()``
|
||||
- ``CAN_TIMING_CONFIG_1MBITS()``
|
||||
|
||||
.. note::
|
||||
The macro initializers for 12.5K, 16K, and 20K bit rates are only available
|
||||
for ESP32 revision 2 or later.
|
||||
.. only::esp32
|
||||
|
||||
.. note::
|
||||
The macro initializers for 12.5K, 16K, and 20K bit rates are only available
|
||||
for ESP32 revision 2 or later.
|
||||
|
||||
Acceptance Filter
|
||||
^^^^^^^^^^^^^^^^^
|
||||
@@ -477,7 +479,7 @@ The following example shows how the calculate the acceptance mask given multiple
|
||||
Application Examples
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
**Network Example:** The CAN Network example demonstrates communication between two ESP32s using the CAN driver API. One CAN node acts as a network master initiate and ceasing the transfer of a data from another CAN node acting as a network slave. The example can be found via :example:`peripherals/can/can_network`.
|
||||
**Network Example:** The CAN Network example demonstrates communication between two {IDF_TARGET_NAME}s using the CAN driver API. One CAN node acts as a network master initiate and ceasing the transfer of a data from another CAN node acting as a network slave. The example can be found via :example:`peripherals/can/can_network`.
|
||||
|
||||
**Alert and Recovery Example:** This example demonstrates how to use the CAN driver's alert and bus recovery API. The example purposely introduces errors on the CAN bus to put the CAN controller into the Bus-Off state. An alert is used to detect the Bus-Off state and trigger the bus recovery process. The example can be found via :example:`peripherals/can/can_alert_and_recovery`.
|
||||
|
||||
|
||||
@@ -4,7 +4,13 @@ Digital To Analog Converter
|
||||
Overview
|
||||
--------
|
||||
|
||||
ESP32 has two 8-bit DAC (digital to analog converter) channels, connected to GPIO25 (Channel 1) and GPIO26 (Channel 2).
|
||||
.. only:: esp32
|
||||
|
||||
{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.
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ Communication with ESP SDIO Slave
|
||||
ESP SDIO slave initialization
|
||||
------------------------------
|
||||
|
||||
The host should initialize the ESP32 SDIO slave according to the standard
|
||||
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
|
||||
and below, the SDIO slave is also called an (SD)IO card. All the
|
||||
|
||||
@@ -4,10 +4,18 @@ GPIO & RTC GPIO
|
||||
Overview
|
||||
--------
|
||||
|
||||
The ESP32 chip features 40 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.
|
||||
.. only:: esp32
|
||||
|
||||
The {IDF_TARGET_NAME} chip features 40 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 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
|
||||
|
||||
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 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.
|
||||
|
||||
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,7 +8,7 @@ I2C is a serial, synchronous, half-duplex communication protocol that allows co-
|
||||
|
||||
With such advantages as simplicity and low manufacturing cost, I2C is mostly used for communication of low-speed peripheral devices over short distances (within one foot).
|
||||
|
||||
ESP32 has two I2C controllers (also referred to as ports) which are responsible for handling communications on two I2C buses. Each I2C controller can operate as master or slave. As an example, one controller can act as a master and the other as a slave at the same time.
|
||||
{IDF_TARGET_NAME} has two I2C controllers (also referred to as ports) which are responsible for handling communications on two I2C buses. Each I2C controller can operate as master or slave. As an example, one controller can act as a master and the other as a slave at the same time.
|
||||
|
||||
|
||||
Driver Features
|
||||
@@ -50,7 +50,7 @@ To establish I2C communication, start by configuring the driver. This is done by
|
||||
- Configure **communication pins**
|
||||
|
||||
- Assign GPIO pins for SDA and SCL signals
|
||||
- Set whether to enable ESP32's internal pull-ups
|
||||
- Set whether to enable {IDF_TARGET_NAME}'s internal pull-ups
|
||||
|
||||
- (Master only) Set I2C **clock speed**
|
||||
- (Slave only) Configure the following
|
||||
@@ -81,9 +81,9 @@ After the I2C driver is configured, install it by calling the function :cpp:func
|
||||
Communication as Master
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
After installing the I2C driver, ESP32 is ready to communicate with other I2C devices.
|
||||
After installing the I2C driver, {IDF_TARGET_NAME} is ready to communicate with other I2C devices.
|
||||
|
||||
ESP32's I2C controller operating as master is responsible for establishing communication with I2C slave devices and sending commands to trigger a slave to action, for example, to take a measurement and send the readings back to the master.
|
||||
{IDF_TARGET_NAME}'s I2C controller operating as master is responsible for establishing communication with I2C slave devices and sending commands to trigger a slave to action, for example, to take a measurement and send the readings back to the master.
|
||||
|
||||
For better process organization, the driver provides a container, called a "command link", that should be populated with a sequence of commands and then passed to the I2C controller for execution.
|
||||
|
||||
@@ -155,7 +155,7 @@ Likewise, the command link to read from the slave looks as follows:
|
||||
Communication as Slave
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
After installing the I2C driver, ESP32 is ready to communicate with other I2C devices.
|
||||
After installing the I2C driver, {IDF_TARGET_NAME} is ready to communicate with other I2C devices.
|
||||
|
||||
The API provides the following functions for slaves
|
||||
|
||||
@@ -179,7 +179,6 @@ During driver installation, an interrupt handler is installed by default. Howeve
|
||||
|
||||
To delete an interrupt handler, call :cpp:func:`i2c_isr_free`.
|
||||
|
||||
|
||||
.. _i2c-api-customized-configuration:
|
||||
|
||||
Customized Configuration
|
||||
@@ -217,7 +216,7 @@ You can also select different pins for SDA and SCL signals and alter the configu
|
||||
|
||||
.. note::
|
||||
|
||||
ESP32's internal pull-ups are in the range of tens of kOhm, which is, in most cases, insufficient for use as I2C pull-ups. Users are advised to use external pull-ups with values described in the `I2C specification <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_.
|
||||
{IDF_TARGET_NAME}'s internal pull-ups are in the range of tens of kOhm, which is, in most cases, insufficient for use as I2C pull-ups. Users are advised to use external pull-ups with values described in the `I2C specification <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_.
|
||||
|
||||
|
||||
.. _i2c-api-error-handling:
|
||||
|
||||
@@ -6,7 +6,7 @@ Overview
|
||||
|
||||
I2S (Inter-IC Sound) is a serial, synchronous communication protocol that is usually used for transmitting audio data between two digital audio devices.
|
||||
|
||||
ESP32 integrates two I2S controllers, referred to as I2S0 and I2S1, both of which can be used for streaming audio and video digital data.
|
||||
{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.
|
||||
|
||||
An I2S bus consists of the following lines:
|
||||
|
||||
@@ -30,7 +30,9 @@ The I2S peripherals also support LCD mode for communicating data over a parallel
|
||||
- Camera slave receiving mode
|
||||
- ADC/DAC mode
|
||||
|
||||
For more information, see the `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#page=306>`_.
|
||||
.. only:: esp32
|
||||
|
||||
For more information, see the `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#page=306>`_.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -198,7 +200,7 @@ Configuring I2S to use internal DAC for analog output
|
||||
i2s_set_pin(i2s_num, NULL); //for internal DAC, this will enable both of the internal channels
|
||||
|
||||
//You can call i2s_set_dac_mode to set built-in DAC output mode.
|
||||
//i2s_set_dac_mode(I2S_DAC_CHANNEL_BOTH_EN);
|
||||
//i2s_set_dac_mode(I2S_DAC_CHANNEL_BOTH_EN);
|
||||
|
||||
i2s_set_sample_rates(i2s_num, 22050); //set sample rates
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ 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.
|
||||
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.
|
||||
|
||||
@@ -121,7 +121,7 @@ The first two functions are called "behind the scenes" by :cpp:func:`ledc_channe
|
||||
Use Interrupts
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
When configuring an LEDC channel, one of the parameters selected within :cpp:type:`ledc_channel_config_t` is :cpp:type:`ledc_intr_type_t` which triggers an interrupt on fade completion.
|
||||
When configuring an LEDC channel, one of the parameters selected within :cpp:type:`ledc_channel_config_t` is :cpp:type:`ledc_intr_type_t` which triggers an interrupt on fade completion.
|
||||
|
||||
For registration of a handler to address this interrupt, call :cpp:func:`ledc_isr_register`.
|
||||
|
||||
@@ -135,8 +135,13 @@ Of the total 8 timers and 16 channels available in the LED PWM Controller, half
|
||||
|
||||
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.
|
||||
|
||||
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:: esp32
|
||||
|
||||
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 `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.
|
||||
|
||||
.. _ledc-api-supported-range-frequency-duty-resolution:
|
||||
|
||||
@@ -163,7 +168,7 @@ The LEDC driver will also capture and report attempts to configure frequency / d
|
||||
|
||||
E (196) ledc: requested frequency and duty resolution cannot be achieved, try increasing freq_hz or duty_resolution. div_param=128000000
|
||||
|
||||
The duty resolution is normally set using :cpp:type:`ledc_timer_bit_t`. This enumeration covers the range from 10 to 15 bits. If a smaller duty resolution is required (from 10 down to 1), enter the equivalent numeric values directly.
|
||||
The duty resolution is normally set using :cpp:type:`ledc_timer_bit_t`. This enumeration covers the range from 10 to 15 bits. If a smaller duty resolution is required (from 10 down to 1), enter the equivalent numeric values directly.
|
||||
|
||||
|
||||
Application Example
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
MCPWM
|
||||
=====
|
||||
|
||||
ESP32 has two MCPWM units which can be used to control different types of motors. Each unit has three pairs of PWM outputs.
|
||||
{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.
|
||||
|
||||
.. figure:: ../../../_static/mcpwm-overview.png
|
||||
:align: center
|
||||
@@ -53,7 +53,7 @@ In this case we will describe a simple configuration to control a brushed DC mot
|
||||
|
||||
Configuration covers the following steps:
|
||||
|
||||
1. Selection of a MPWn unit that will be used to drive the motor. There are two units available on-board of ESP32 and enumerated in :cpp:type:`mcpwm_unit_t`.
|
||||
1. Selection of a MPWn unit that will be used to drive the motor. There are two units available on-board of {IDF_TARGET_NAME} and enumerated in :cpp:type:`mcpwm_unit_t`.
|
||||
2. Initialization of two GPIOs as output signals within selected unit by calling :cpp:func:`mcpwm_gpio_init`. The two output signals are typically used to command the motor to rotate right or left. All available signal options are listed in :cpp:type:`mcpwm_io_signals_t`. To set more than a single pin at a time, use function :cpp:func:`mcpwm_set_pin` together with :cpp:type:`mcpwm_pin_config_t`.
|
||||
3. Selection of a timer. There are three timers available within the unit. The timers are listed in :cpp:type:`mcpwm_timer_t`.
|
||||
4. Setting of the timer frequency and initial duty within :cpp:type:`mcpwm_config_t` structure.
|
||||
@@ -89,8 +89,13 @@ 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`.
|
||||
|
||||
* 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:: 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`_.
|
||||
|
||||
Capture
|
||||
-------
|
||||
@@ -171,6 +176,8 @@ Examples of using MCPWM for motor control: :example:`peripherals/mcpwm`:
|
||||
|
||||
.. _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
|
||||
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
@@ -105,7 +105,7 @@ Common Parameters
|
||||
|
||||
* The **channel** to be configured, select one from the :cpp:type:`rmt_channel_t` enumerator.
|
||||
* The RMT **operation mode** - whether this channel is used to transmit or receive data, selected by setting a **rmt_mode** members to one of the values from :cpp:type:`rmt_mode_t`.
|
||||
* What is the **pin number** to transmit or receive RMT signals, selected by setting **gpio_num**.
|
||||
* What is the **pin number** to transmit or receive RMT signals, selected by setting **gpio_num**.
|
||||
* How many **memory blocks** will be used by the channel, set with **mem_block_num**.
|
||||
* A **clock divider**, that will determine the range of pulse length generated by the RMT transmitter or discriminated by the receiver. Selected by setting **clk_div** to a value within [1 .. 255] range. The RMT source clock is typically APB CLK, 80Mhz by default.
|
||||
|
||||
@@ -123,7 +123,7 @@ When configuring channel in transmit mode, set **tx_config** and the following m
|
||||
|
||||
* Transmit the currently configured data items in a loop - **loop_en**
|
||||
* Enable the RMT carrier signal - **carrier_en**
|
||||
* Frequency of the carrier in Hz - **carrier_freq_hz**
|
||||
* Frequency of the carrier in Hz - **carrier_freq_hz**
|
||||
* Duty cycle of the carrier signal in percent (%) - **carrier_duty_percent**
|
||||
* Level of the RMT output, when the carrier is applied - **carrier_level**
|
||||
* Enable the RMT output if idle - **idle_output_en**
|
||||
@@ -153,14 +153,14 @@ 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/esp32/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_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.
|
||||
|
||||
.. packetdiag::
|
||||
:caption: Structure of RMT items (L - signal level)
|
||||
:align: center
|
||||
|
||||
packetdiag rmt_items {
|
||||
colwidth = 32
|
||||
colwidth = 32
|
||||
node_width = 10
|
||||
node_height = 24
|
||||
default_fontsize = 12
|
||||
@@ -180,7 +180,7 @@ For a simple example how to define a block of items see :example:`peripherals/rm
|
||||
|
||||
The items are provided to the RMT controller by calling function :cpp:func:`rmt_write_items`. This function also automatically triggers start of transmission. It may be called to wait for transmission completion or exit just after transmission start. In such case you can wait for the transmission end by calling :cpp:func:`rmt_wait_tx_done`. This function does not limit the number of data items to transmit. It is using an interrupt to successively copy the new data chunks to RMT's internal memory as previously provided data are sent out.
|
||||
|
||||
Another way to provide data for transmission is by calling :cpp:func:`rmt_fill_tx_items`. In this case transmission is not started automatically. To control the transmission process use :cpp:func:`rmt_tx_start` and :cpp:func:`rmt_tx_stop`. The number of items to sent is restricted by the size of memory blocks allocated in the RMT controller's internal memory, see :cpp:func:`rmt_set_mem_block_num`.
|
||||
Another way to provide data for transmission is by calling :cpp:func:`rmt_fill_tx_items`. In this case transmission is not started automatically. To control the transmission process use :cpp:func:`rmt_tx_start` and :cpp:func:`rmt_tx_stop`. The number of items to sent is restricted by the size of memory blocks allocated in the RMT controller's internal memory, see :cpp:func:`rmt_set_mem_block_num`.
|
||||
|
||||
|
||||
Receive Data
|
||||
@@ -227,11 +227,11 @@ Receive Mode Parameters
|
||||
Use Interrupts
|
||||
--------------
|
||||
|
||||
Registering of an interrupt handler for the RMT controller is done be calling :cpp:func:`rmt_isr_register`.
|
||||
Registering of an interrupt handler for the RMT controller is done be calling :cpp:func:`rmt_isr_register`.
|
||||
|
||||
.. note::
|
||||
|
||||
When calling :cpp:func:`rmt_driver_install` to use the system RMT driver, a default ISR is being installed. In such a case you cannot register a generic ISR handler with :cpp:func:`rmt_isr_register`.
|
||||
When calling :cpp:func:`rmt_driver_install` to use the system RMT driver, a default ISR is being installed. In such a case you cannot register a generic ISR handler with :cpp:func:`rmt_isr_register`.
|
||||
|
||||
The RMT controller triggers interrupts on four specific events describes below. To enable interrupts on these events, the following functions are provided:
|
||||
|
||||
@@ -242,7 +242,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/esp32/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/{IDT_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.
|
||||
|
||||
If you do not need an ISR anymore, you can deregister it by calling a function :cpp:func:`rmt_isr_deregister`.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user