mirror of
https://github.com/espressif/esp-idf.git
synced 2025-08-31 14:22:14 +00:00
docs: Add missing peripheral driver docs (ADC, DAC, RTC I/O, I2S)
This commit is contained in:
Angus Gratton
62
docs/api/peripherals/adc.rst
Normal file
62
docs/api/peripherals/adc.rst
Normal file
@@ -0,0 +1,62 @@
|
||||
Analog to Digital Converter
|
||||
===========================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
ESP32 integrates two 12-bit SAR ("Successive Approximation Register") ADCs (Analog to Digital Converters) and supports measurements on 18 channels (analog enabled pins). Some of these pins can be used to build a programmable gain amplifier which is used for the measurement of small
|
||||
analog signals.
|
||||
|
||||
The ADC driver API currently only supports ADC1 (9 channels, attached to GPIOs 32-39).
|
||||
|
||||
Taking an ADC reading involves configuring the ADC with the desired precision and attentuation settings, and then calling adc1_get_voltage() to read the channel.
|
||||
|
||||
It is also possible to read the internal hall effect sensor via ADC1.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
Reading voltage on ADC1 channel 0 (GPIO 36)::
|
||||
|
||||
#include <driver/adc.h>
|
||||
|
||||
...
|
||||
|
||||
adc1_config_width(ADC_WIDTH_12Bit);
|
||||
adc1_config_channel_atten(ADC1_CHANNEL_0,ADC_ATTEN_0db);
|
||||
int val = adc1_get_voltage(ADC1_CHANNEL_0);
|
||||
|
||||
Reading the internal hall effect sensor::
|
||||
|
||||
#include <driver/adc.h>
|
||||
|
||||
...
|
||||
|
||||
adc1_config_width(ADC_WIDTH_12Bit);
|
||||
int val = hall_sensor_read();
|
||||
|
||||
The value read in both these examples is 12 bits wide (range 0-4095).
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
Header Files
|
||||
^^^^^^^^^^^^
|
||||
|
||||
* `components/driver/include/driver/adc.h`
|
||||
|
||||
Enumerations
|
||||
^^^^^^^^^^^^
|
||||
|
||||
.. doxygenenum:: adc1_channel_t
|
||||
.. doxygenenum:: adc_atten_t
|
||||
.. doxygenenum:: adc_bits_width_t
|
||||
|
||||
Functions
|
||||
^^^^^^^^^
|
||||
|
||||
.. doxygenfunction:: adc1_config_width
|
||||
.. doxygenfunction:: adc1_config_channel_atten
|
||||
.. doxygenfunction:: adc1_get_voltage
|
||||
.. doxygenfunction:: hall_sensor_read
|
||||
|
||||
45
docs/api/peripherals/dac.rst
Normal file
45
docs/api/peripherals/dac.rst
Normal file
@@ -0,0 +1,45 @@
|
||||
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).
|
||||
|
||||
The DAC driver allows these channels to be set to arbitrary voltages.
|
||||
|
||||
The DAC channels can also be driven with DMA-style written sample data, via the :doc:`I2S driver <i2s>` when using the "built-in DAC mode".
|
||||
|
||||
For other analog output options, see the :doc:`Sigma-delta Modulation module <sigmadelta>` and the :doc:`LED Control module <ledc>`. Both these modules produce high frequency PWM output, which can be hardware low-pass filtered in order to generate a lower frequency analog output.
|
||||
|
||||
|
||||
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::
|
||||
|
||||
#include <driver/dac.h>
|
||||
|
||||
...
|
||||
|
||||
dac_out_voltage(DAC_CHANNEL_1, 200);
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
Header Files
|
||||
^^^^^^^^^^^^
|
||||
|
||||
* `components/driver/include/driver/dac.h`
|
||||
|
||||
Enumerations
|
||||
^^^^^^^^^^^^
|
||||
|
||||
.. doxygenenum:: dac_channel_t
|
||||
|
||||
Functions
|
||||
^^^^^^^^^
|
||||
|
||||
.. doxygenfunction:: dac_out_voltage
|
||||
|
||||
|
||||
@@ -1,11 +1,15 @@
|
||||
GPIO
|
||||
====
|
||||
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.
|
||||
Note that GPIO6-11 are usually used for SPI flash. GPIO34-39 can only be set as input mode.
|
||||
|
||||
- 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 </ulp>` is running, or when analog functions such as ADC/DAC/etc are in use.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
@@ -19,10 +23,14 @@ Header Files
|
||||
^^^^^^^^^^^^
|
||||
|
||||
* :component_file:`driver/include/driver/gpio.h`
|
||||
* :component_file:`driver/include/driver/rtc_io.h`
|
||||
|
||||
Macros
|
||||
^^^^^^
|
||||
|
||||
Normal GPIO
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. doxygendefine:: GPIO_SEL_0
|
||||
.. doxygendefine:: GPIO_SEL_1
|
||||
.. doxygendefine:: GPIO_SEL_2
|
||||
@@ -107,12 +115,18 @@ Macros
|
||||
Type Definitions
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Normal GPIO
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. doxygentypedef:: gpio_isr_t
|
||||
.. doxygentypedef:: gpio_isr_handle_t
|
||||
|
||||
Enumerations
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Normal GPIO
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. doxygenenum:: gpio_num_t
|
||||
.. doxygenenum:: gpio_int_type_t
|
||||
.. doxygenenum:: gpio_mode_t
|
||||
@@ -120,16 +134,26 @@ Enumerations
|
||||
.. doxygenenum:: gpio_pulldown_t
|
||||
.. doxygenenum:: gpio_pull_mode_t
|
||||
|
||||
RTC GPIO
|
||||
~~~~~~~~
|
||||
|
||||
.. doxygenenum:: rtc_gpio_mode_t
|
||||
|
||||
Structures
|
||||
^^^^^^^^^^
|
||||
|
||||
Normal GPIO
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. doxygenstruct:: gpio_config_t
|
||||
:members:
|
||||
|
||||
|
||||
Functions
|
||||
^^^^^^^^^
|
||||
|
||||
Normal GPIO
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. doxygenfunction:: gpio_config
|
||||
.. doxygenfunction:: gpio_set_intr_type
|
||||
.. doxygenfunction:: gpio_intr_enable
|
||||
@@ -150,3 +174,18 @@ Functions
|
||||
.. doxygenfunction:: gpio_isr_handler_add
|
||||
.. doxygenfunction:: gpio_isr_handler_remove
|
||||
|
||||
|
||||
RTC GPIO
|
||||
~~~~~~~~
|
||||
|
||||
.. doxygenfunction:: rtc_gpio_is_valid_gpio
|
||||
.. doxygenfunction:: rtc_gpio_init
|
||||
.. doxygenfunction:: rtc_gpio_deinit
|
||||
.. doxygenfunction:: rtc_gpio_get_level
|
||||
.. doxygenfunction:: rtc_gpio_set_level
|
||||
.. doxygenfunction:: rtc_gpio_set_direction
|
||||
.. doxygenfunction:: rtc_gpio_pullup_en
|
||||
.. doxygenfunction:: rtc_gpio_pulldown_en
|
||||
.. doxygenfunction:: rtc_gpio_pullup_dis
|
||||
.. doxygenfunction:: rtc_gpio_pulldown_dis
|
||||
.. doxygenfunction:: rtc_gpio_unhold_all
|
||||
|
||||
131
docs/api/peripherals/i2s.rst
Normal file
131
docs/api/peripherals/i2s.rst
Normal file
@@ -0,0 +1,131 @@
|
||||
I2S
|
||||
===
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
ESP32 contains two I2S peripherals. These peripherals can be configured to input and output sample data via the I2S driver.
|
||||
|
||||
The I2S peripheral supports DMA meaning it can stream sample data without requiring each sample to be read or written by the CPU.
|
||||
|
||||
I2S output can also be routed directly to the Digital/Analog Converter output channels (GPIO 25 & GPIO 26) to produce analog output directly, rather than via an external I2S codec.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
A full I2S example is available in esp-idf: :example:`peripherals/i2s`.
|
||||
|
||||
Short example of I2S configuration::
|
||||
|
||||
#include "driver/i2s.h"
|
||||
#include "freertos/queue.h"
|
||||
|
||||
static const int i2s_num = 0; // i2s port number
|
||||
|
||||
static const i2s_config_t i2s_config = {
|
||||
.mode = I2S_MODE_MASTER | I2S_MODE_TX,
|
||||
.sample_rate = 44100,
|
||||
.bits_per_sample = 16,
|
||||
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
|
||||
.communication_format = I2S_COMM_FORMAT_I2S | I2S_COMM_FORMAT_I2S_MSB,
|
||||
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1, // high interrupt priority
|
||||
.dma_buf_count = 8,
|
||||
.dma_buf_len = 64
|
||||
};
|
||||
|
||||
static const i2s_pin_config_t pin_config = {
|
||||
.bck_io_num = 26,
|
||||
.ws_io_num = 25,
|
||||
.data_out_num = 22,
|
||||
.data_in_num = I2S_PIN_NO_CHANGE
|
||||
};
|
||||
|
||||
...
|
||||
|
||||
i2s_driver_install(i2s_num, &i2s_config, 0, NULL); //install and start i2s driver
|
||||
|
||||
i2s_set_pin(i2s_num, &pin_config);
|
||||
|
||||
i2s_set_sample_rates(i2s_num, 22050); //set sample rates
|
||||
|
||||
i2s_driver_uninstall(i2s_num); //stop & destroy i2s driver
|
||||
|
||||
Short example configuring I2S to use internal DAC for analog output::
|
||||
|
||||
#include "driver/i2s.h"
|
||||
#include "freertos/queue.h"
|
||||
|
||||
static const int i2s_num = 0; // i2s port number
|
||||
|
||||
static const i2s_config_t i2s_config = {
|
||||
.mode = I2S_MODE_MASTER | I2S_MODE_TX | I2S_MODE_DAC_BUILT_IN,
|
||||
.sample_rate = 44100,
|
||||
.bits_per_sample = 8, /* must be 8 for built-in DAC */
|
||||
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
|
||||
.communication_format = I2S_COMM_FORMAT_I2S_MSB,
|
||||
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1, // high interrupt priority
|
||||
.dma_buf_count = 8,
|
||||
.dma_buf_len = 64
|
||||
};
|
||||
|
||||
...
|
||||
|
||||
i2s_driver_install(i2s_num, &i2s_config, 0, NULL); //install and start i2s driver
|
||||
|
||||
i2s_set_pin(i2s_num, NULL); //for internal DAC
|
||||
|
||||
i2s_set_sample_rates(i2s_num, 22050); //set sample rates
|
||||
|
||||
i2s_driver_uninstall(i2s_num); //stop & destroy i2s driver
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
Header Files
|
||||
^^^^^^^^^^^^
|
||||
|
||||
* `components/driver/include/driver/i2s.h`
|
||||
|
||||
Data Structures
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. doxygenstruct:: i2s_config_t
|
||||
:members:
|
||||
.. doxygenstruct:: i2s_event_t
|
||||
:members:
|
||||
.. doxygenstruct:: i2s_pin_config_t
|
||||
:members:
|
||||
|
||||
Macros
|
||||
^^^^^^
|
||||
|
||||
.. doxygendefine:: I2S_PIN_NO_CHANGE
|
||||
|
||||
Enumerations
|
||||
^^^^^^^^^^^^
|
||||
|
||||
.. doxygenenum:: i2s_bits_per_sample_t
|
||||
.. doxygenenum:: i2s_comm_format_t
|
||||
.. doxygenenum:: i2s_channel_fmt_t
|
||||
.. doxygenenum:: pdm_sample_rate_ratio_t
|
||||
.. doxygenenum:: pdm_pcm_conv_t
|
||||
.. doxygenenum:: i2s_port_t
|
||||
.. doxygenenum:: i2s_mode_t
|
||||
.. doxygenenum:: i2s_event_type_t
|
||||
|
||||
Functions
|
||||
^^^^^^^^^
|
||||
|
||||
.. doxygenfunction:: i2s_set_pin
|
||||
.. doxygenfunction:: i2s_driver_install
|
||||
.. doxygenfunction:: i2s_driver_uninstall
|
||||
.. doxygenfunction:: i2s_write_bytes
|
||||
.. doxygenfunction:: i2s_read_bytes
|
||||
.. doxygenfunction:: i2s_push_sample
|
||||
.. doxygenfunction:: i2s_pop_sample
|
||||
.. doxygenfunction:: i2s_set_sample_rates
|
||||
.. doxygenfunction:: i2s_start
|
||||
.. doxygenfunction:: i2s_stop
|
||||
.. doxygenfunction:: i2s_zero_dma_buffer
|
||||
|
||||
|
||||
@@ -4,15 +4,18 @@ Peripherals API
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
GPIO <gpio>
|
||||
UART <uart>
|
||||
ADC <adc>
|
||||
DAC <dac>
|
||||
GPIO (including RTC low power I/O) <gpio>
|
||||
I2C <i2c>
|
||||
SPI Master <spi_master>
|
||||
Timer <timer>
|
||||
Pulse Counter <pcnt>
|
||||
Sigma-delta Modulation <sigmadelta>
|
||||
I2S <i2s>
|
||||
LED Control <ledc>
|
||||
Pulse Counter <pcnt>
|
||||
SD/MMC Card Host <../storage/sdmmc>
|
||||
Sigma-delta Modulation <sigmadelta>
|
||||
SPI Master <spi_master>
|
||||
Remote Control <rmt>
|
||||
|
||||
Timer <timer>
|
||||
UART <uart>
|
||||
|
||||
Example code for this API section is provided in :example:`peripherals` directory of ESP-IDF examples.
|
||||
|
||||
@@ -4,7 +4,7 @@ Sigma-delta Modulation
|
||||
Overview
|
||||
--------
|
||||
|
||||
ESP32 has a second-order sigma-delta modulation module.
|
||||
ESP32 has a second-order sigma-delta modulation module.
|
||||
This driver configures the channels of the sigma-delta module.
|
||||
|
||||
Application Example
|
||||
|
||||
Reference in New Issue
Block a user