pioduino/esp-idf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Getting started guides

Browse Source
This commit is contained in:
krzychb
2017-03-27 00:01:52 +02:00
parent 6f0a9f76cd
commit 1a19747678
130 changed files with 1371 additions and 608 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api-reference/peripherals/adc.rst
+62
View 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
docs/api-reference/peripherals/dac.rst
+45
View 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
docs/api-reference/peripherals/gpio.rst
+191
View File
@@ -0,0 +1,191 @@
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 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.
Application Example
-------------------
GPIO output and input interrupt example: :example:`peripherals/gpio`.
API Reference
-------------
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
.. doxygendefine:: GPIO_SEL_3
.. doxygendefine:: GPIO_SEL_4
.. doxygendefine:: GPIO_SEL_5
.. doxygendefine:: GPIO_SEL_6
.. doxygendefine:: GPIO_SEL_7
.. doxygendefine:: GPIO_SEL_8
.. doxygendefine:: GPIO_SEL_9
.. doxygendefine:: GPIO_SEL_10
.. doxygendefine:: GPIO_SEL_11
.. doxygendefine:: GPIO_SEL_12
.. doxygendefine:: GPIO_SEL_13
.. doxygendefine:: GPIO_SEL_14
.. doxygendefine:: GPIO_SEL_15
.. doxygendefine:: GPIO_SEL_16
.. doxygendefine:: GPIO_SEL_17
.. doxygendefine:: GPIO_SEL_18
.. doxygendefine:: GPIO_SEL_19
.. doxygendefine:: GPIO_SEL_21
.. doxygendefine:: GPIO_SEL_22
.. doxygendefine:: GPIO_SEL_23
.. doxygendefine:: GPIO_SEL_25
.. doxygendefine:: GPIO_SEL_26
.. doxygendefine:: GPIO_SEL_27
.. doxygendefine:: GPIO_SEL_32
.. doxygendefine:: GPIO_SEL_33
.. doxygendefine:: GPIO_SEL_34
.. doxygendefine:: GPIO_SEL_35
.. doxygendefine:: GPIO_SEL_36
.. doxygendefine:: GPIO_SEL_37
.. doxygendefine:: GPIO_SEL_38
.. doxygendefine:: GPIO_SEL_39
.. doxygendefine:: GPIO_PIN_REG_0
.. doxygendefine:: GPIO_PIN_REG_1
.. doxygendefine:: GPIO_PIN_REG_2
.. doxygendefine:: GPIO_PIN_REG_3
.. doxygendefine:: GPIO_PIN_REG_4
.. doxygendefine:: GPIO_PIN_REG_5
.. doxygendefine:: GPIO_PIN_REG_6
.. doxygendefine:: GPIO_PIN_REG_7
.. doxygendefine:: GPIO_PIN_REG_8
.. doxygendefine:: GPIO_PIN_REG_9
.. doxygendefine:: GPIO_PIN_REG_10
.. doxygendefine:: GPIO_PIN_REG_11
.. doxygendefine:: GPIO_PIN_REG_12
.. doxygendefine:: GPIO_PIN_REG_13
.. doxygendefine:: GPIO_PIN_REG_14
.. doxygendefine:: GPIO_PIN_REG_15
.. doxygendefine:: GPIO_PIN_REG_16
.. doxygendefine:: GPIO_PIN_REG_17
.. doxygendefine:: GPIO_PIN_REG_18
.. doxygendefine:: GPIO_PIN_REG_19
.. doxygendefine:: GPIO_PIN_REG_20
.. doxygendefine:: GPIO_PIN_REG_21
.. doxygendefine:: GPIO_PIN_REG_22
.. doxygendefine:: GPIO_PIN_REG_23
.. doxygendefine:: GPIO_PIN_REG_25
.. doxygendefine:: GPIO_PIN_REG_26
.. doxygendefine:: GPIO_PIN_REG_27
.. doxygendefine:: GPIO_PIN_REG_32
.. doxygendefine:: GPIO_PIN_REG_33
.. doxygendefine:: GPIO_PIN_REG_34
.. doxygendefine:: GPIO_PIN_REG_35
.. doxygendefine:: GPIO_PIN_REG_36
.. doxygendefine:: GPIO_PIN_REG_37
.. doxygendefine:: GPIO_PIN_REG_38
.. doxygendefine:: GPIO_PIN_REG_39
.. doxygendefine:: GPIO_APP_CPU_INTR_ENA
.. doxygendefine:: GPIO_APP_CPU_NMI_INTR_ENA
.. doxygendefine:: GPIO_PRO_CPU_INTR_ENA
.. doxygendefine:: GPIO_PRO_CPU_NMI_INTR_ENA
.. doxygendefine:: GPIO_SDIO_EXT_INTR_ENA
.. doxygendefine:: GPIO_MODE_DEF_INPUT
.. doxygendefine:: GPIO_MODE_DEF_OUTPUT
.. doxygendefine:: GPIO_MODE_DEF_OD
.. doxygendefine:: GPIO_PIN_COUNT
.. doxygendefine:: GPIO_IS_VALID_GPIO
.. doxygendefine:: GPIO_IS_VALID_OUTPUT_GPIO
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
.. doxygenenum:: gpio_pullup_t
.. 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
.. doxygenfunction:: gpio_intr_disable
.. doxygenfunction:: gpio_set_level
.. doxygenfunction:: gpio_get_level
.. doxygenfunction:: gpio_set_direction
.. doxygenfunction:: gpio_set_pull_mode
.. doxygenfunction:: gpio_wakeup_enable
.. doxygenfunction:: gpio_wakeup_disable
.. doxygenfunction:: gpio_isr_register
.. doxygenfunction:: gpio_pullup_en
.. doxygenfunction:: gpio_pullup_dis
.. doxygenfunction:: gpio_pulldown_en
.. doxygenfunction:: gpio_pulldown_dis
.. doxygenfunction:: gpio_install_isr_service
.. doxygenfunction:: gpio_uninstall_isr_service
.. 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
docs/api-reference/peripherals/i2c.rst
+82
View File
@@ -0,0 +1,82 @@
I2C
===========
Overview
--------
ESP32 has two I2C controllers which can be set as master mode or slave mode.
Application Example
-------------------
I2C master and slave example: :example:`peripherals/i2c`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`driver/include/driver/i2c.h`
Macros
^^^^^^
.. doxygendefine:: I2C_APB_CLK_FREQ
.. doxygendefine:: I2C_FIFO_LEN
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: i2c_cmd_handle_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: i2c_mode_t
.. doxygenenum:: i2c_rw_t
.. doxygenenum:: i2c_trans_mode_t
.. doxygenenum:: i2c_opmode_t
.. doxygenenum:: i2c_port_t
.. doxygenenum:: i2c_addr_mode_t
Structures
^^^^^^^^^^
.. doxygenstruct:: i2c_config_t
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: i2c_driver_install
.. doxygenfunction:: i2c_driver_delete
.. doxygenfunction:: i2c_param_config
.. doxygenfunction:: i2c_reset_tx_fifo
.. doxygenfunction:: i2c_reset_rx_fifo
.. doxygenfunction:: i2c_isr_register
.. doxygenfunction:: i2c_isr_free
.. doxygenfunction:: i2c_set_pin
.. doxygenfunction:: i2c_master_start
.. doxygenfunction:: i2c_master_write_byte
.. doxygenfunction:: i2c_master_write
.. doxygenfunction:: i2c_master_read_byte
.. doxygenfunction:: i2c_master_read
.. doxygenfunction:: i2c_master_stop
.. doxygenfunction:: i2c_master_cmd_begin
.. doxygenfunction:: i2c_slave_write_buffer
.. doxygenfunction:: i2c_slave_read
.. doxygenfunction:: i2c_set_period
.. doxygenfunction:: i2c_get_period
.. doxygenfunction:: i2c_set_start_timing
.. doxygenfunction:: i2c_get_start_timing
.. doxygenfunction:: i2c_set_stop_timing
.. doxygenfunction:: i2c_get_stop_timing
.. doxygenfunction:: i2c_set_data_timing
.. doxygenfunction:: i2c_get_data_timing
.. doxygenfunction:: i2c_set_data_mode
.. doxygenfunction:: i2c_get_data_mode
.. doxygenfunction:: i2c_cmd_link_create
.. doxygenfunction:: i2c_cmd_link_delete
docs/api-reference/peripherals/i2s.rst
+131
View 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
docs/api-reference/peripherals/index.rst
+22
View File
@@ -0,0 +1,22 @@
Peripherals API
***************
.. toctree::
:maxdepth: 1
ADC <adc>
DAC <dac>
GPIO (including RTC low power I/O) <gpio>
I2C <i2c>
I2S <i2s>
LED Control <ledc>
Pulse Counter <pcnt>
SD/MMC Card Host <../storage/sdmmc>
Sigma-delta Modulation <sigmadelta>
SPI Master <spi_master>
SPI Slave <spi_slave>
Remote Control <rmt>
Timer <timer>
UART <uart>
Example code for this API section is provided in :example:`peripherals` directory of ESP-IDF examples.
docs/api-reference/peripherals/ledc.rst
+80
View File
@@ -0,0 +1,80 @@
LED Control
===========
Overview
--------
The LED control module is primarily designed to control the intensity of LEDs, although it can be used to generate PWM signals for other purposes as well.
It has 16 channels which can generate independent waveforms that can be used to drive e.g. RGB LED devices. For maximum flexibility, the high-speed as well
as the low-speed channels can be driven from one of four high-speed/low-speed timers. The PWM controller also has the ability to automatically increase or
decrease the duty cycle gradually, allowing for fades without any processor interference.
Application Example
-------------------
LEDC change duty cycle and fading control example: :example:`peripherals/ledc`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`driver/include/driver/ledc.h`
Macros
^^^^^^
.. doxygendefine:: LEDC_APB_CLK_HZ
.. doxygendefine:: LEDC_REF_CLK_HZ
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: ledc_isr_handle_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: ledc_mode_t
.. doxygenenum:: ledc_intr_type_t
.. doxygenenum:: ledc_duty_direction_t
.. doxygenenum:: ledc_clk_src_t
.. doxygenenum:: ledc_timer_t
.. doxygenenum:: ledc_channel_t
.. doxygenenum:: ledc_timer_bit_t
Structures
^^^^^^^^^^
.. doxygenstruct:: ledc_channel_config_t
:members:
.. doxygenstruct:: ledc_timer_config_t
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: ledc_channel_config
.. doxygenfunction:: ledc_timer_config
.. doxygenfunction:: ledc_update_duty
.. doxygenfunction:: ledc_stop
.. doxygenfunction:: ledc_set_freq
.. doxygenfunction:: ledc_get_freq
.. doxygenfunction:: ledc_set_duty
.. doxygenfunction:: ledc_get_duty
.. doxygenfunction:: ledc_set_fade
.. doxygenfunction:: ledc_isr_register
.. doxygenfunction:: ledc_timer_set
.. doxygenfunction:: ledc_timer_rst
.. doxygenfunction:: ledc_timer_pause
.. doxygenfunction:: ledc_timer_resume
.. doxygenfunction:: ledc_bind_channel_timer
.. doxygenfunction:: ledc_set_fade_with_step
.. doxygenfunction:: ledc_set_fade_with_time
.. doxygenfunction:: ledc_fade_func_install
.. doxygenfunction:: ledc_fade_func_uninstall
.. doxygenfunction:: ledc_fade_start
docs/api-reference/peripherals/pcnt.rst
+66
View File
@@ -0,0 +1,66 @@
Pulse Counter
=============
Overview
--------
The PCNT (Pulse Counter) module is designed to count the number of rising and/or falling edges of an input signal. Each pulse counter unit has a 16-bit signed counter register and two channels that can be configured to either increment or decrement the counter. Each channel has a signal input that accepts signal edges to be detected, as well as a control input that can be used to enable or disable the signal input. The inputs have optional filters that can be used to discard unwanted glitches in the signal.
Application Example
-------------------
Pulse counter with control signal and event interrupt example: :example:`peripherals/pcnt`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`driver/include/driver/pcnt.h`
Macros
^^^^^^
Type Definitions
^^^^^^^^^^^^^^^^
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: pcnt_ctrl_mode_t
.. doxygenenum:: pcnt_count_mode_t
.. doxygenenum:: pcnt_unit_t
.. doxygenenum:: pcnt_channel_t
.. doxygenenum:: pcnt_evt_type_t
Structures
^^^^^^^^^^
.. doxygenstruct:: pcnt_config_t
Functions
^^^^^^^^^
.. doxygenfunction:: pcnt_unit_config
.. doxygenfunction:: pcnt_get_counter_value
.. doxygenfunction:: pcnt_counter_pause
.. doxygenfunction:: pcnt_counter_resume
.. doxygenfunction:: pcnt_counter_clear
.. doxygenfunction:: pcnt_intr_enable
.. doxygenfunction:: pcnt_intr_disable
.. doxygenfunction:: pcnt_event_enable
.. doxygenfunction:: pcnt_event_disable
.. doxygenfunction:: pcnt_set_event_value
.. doxygenfunction:: pcnt_get_event_value
.. doxygenfunction:: pcnt_isr_register
.. doxygenfunction:: pcnt_set_pin
.. doxygenfunction:: pcnt_filter_enable
.. doxygenfunction:: pcnt_filter_disable
.. doxygenfunction:: pcnt_set_filter_value
.. doxygenfunction:: pcnt_get_filter_value
.. doxygenfunction:: pcnt_set_mode
docs/api-reference/peripherals/rmt.rst
+93
View File
@@ -0,0 +1,93 @@
RMT
========
Overview
--------
The RMT (Remote Control) module driver can be used to send and receive infrared remote control signals. Due to flexibility of RMT module, the driver can also be used to generate many other types of signals.
Application Example
-------------------
NEC remote control TX and RX example: :example:`peripherals/rmt_nec_tx_rx`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`driver/include/driver/rmt.h`
Macros
^^^^^^
.. doxygendefine:: RMT_MEM_BLOCK_BYTE_NUM
.. doxygendefine:: RMT_MEM_ITEM_NUM
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: rmt_channel_t
.. doxygenenum:: rmt_mem_owner_t
.. doxygenenum:: rmt_source_clk_t
.. doxygenenum:: rmt_data_mode_t
.. doxygenenum:: rmt_mode_t
.. doxygenenum:: rmt_idle_level_t
.. doxygenenum:: rmt_carrier_level_t
Structures
^^^^^^^^^^
.. doxygenstruct:: rmt_tx_config_t
:members:
.. doxygenstruct:: rmt_rx_config_t
:members:
.. doxygenstruct:: rmt_config_t
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: rmt_set_clk_div
.. doxygenfunction:: rmt_get_clk_div
.. doxygenfunction:: rmt_set_rx_idle_thresh
.. doxygenfunction:: rmt_get_rx_idle_thresh
.. doxygenfunction:: rmt_set_mem_block_num
.. doxygenfunction:: rmt_get_mem_block_num
.. doxygenfunction:: rmt_set_tx_carrier
.. doxygenfunction:: rmt_set_mem_pd
.. doxygenfunction:: rmt_get_mem_pd
.. doxygenfunction:: rmt_tx_start
.. doxygenfunction:: rmt_tx_stop
.. doxygenfunction:: rmt_rx_start
.. doxygenfunction:: rmt_rx_stop
.. doxygenfunction:: rmt_memory_rw_rst
.. doxygenfunction:: rmt_set_memory_owner
.. doxygenfunction:: rmt_get_memory_owner
.. doxygenfunction:: rmt_set_tx_loop_mode
.. doxygenfunction:: rmt_get_tx_loop_mode
.. doxygenfunction:: rmt_set_rx_filter
.. doxygenfunction:: rmt_set_source_clk
.. doxygenfunction:: rmt_get_source_clk
.. doxygenfunction:: rmt_set_idle_level
.. doxygenfunction:: rmt_get_status
.. doxygenfunction:: rmt_set_intr_enable_mask
.. doxygenfunction:: rmt_clr_intr_enable_mask
.. doxygenfunction:: rmt_set_rx_intr_en
.. doxygenfunction:: rmt_set_err_intr_en
.. doxygenfunction:: rmt_set_tx_intr_en
.. doxygenfunction:: rmt_set_evt_intr_en
.. doxygenfunction:: rmt_set_pin
.. doxygenfunction:: rmt_config
.. doxygenfunction:: rmt_isr_register
.. doxygenfunction:: rmt_fill_tx_items
.. doxygenfunction:: rmt_driver_install
.. doxygenfunction:: rmt_driver_uninstall
.. doxygenfunction:: rmt_write_items
.. doxygenfunction:: rmt_wait_tx_done
.. doxygenfunction:: rmt_get_ringbuf_handler
docs/api-reference/peripherals/sigmadelta.rst
+51
View File
@@ -0,0 +1,51 @@
Sigma-delta Modulation
======================
Overview
--------
ESP32 has a second-order sigma-delta modulation module.
This driver configures the channels of the sigma-delta module.
Application Example
-------------------
Sigma-delta Modulation example: :example:`peripherals/sigmadelta`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`driver/include/driver/sigmadelta.h`
Macros
^^^^^^
Type Definitions
^^^^^^^^^^^^^^^^
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: sigmadelta_channel_t
Structures
^^^^^^^^^^
.. doxygenstruct:: sigmadelta_config_t
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: sigmadelta_config
.. doxygenfunction:: sigmadelta_set_duty
.. doxygenfunction:: sigmadelta_set_prescale
.. doxygenfunction:: sigmadelta_set_pin
docs/api-reference/peripherals/spi_master.rst
+171
View File
@@ -0,0 +1,171 @@
SPI Master driver
=================
Overview
--------
The ESP32 has four SPI peripheral devices, called SPI0, SPI1, HSPI and VSPI. SPI0 is entirely dedicated to
the flash cache the ESP32 uses to map the SPI flash device it is connected to into memory. SPI1 is
connected to the same hardware lines as SPI0 and is used to write to the flash chip. HSPI and VSPI
are free to use. SPI1, HSPI and VSPI all have three chip select lines, allowing them to drive up to
three SPI devices each as a master.
The spi_master driver
^^^^^^^^^^^^^^^^^^^^^
The spi_master driver allows easy communicating with SPI slave devices, even in a multithreaded environment.
It fully transparently handles DMA transfers to read and write data and automatically takes care of
multiplexing between different SPI slaves on the same master
Terminology
^^^^^^^^^^^
The spi_master driver uses the following terms:
* Host: The SPI peripheral inside the ESP32 initiating the SPI transmissions. One of SPI, HSPI or VSPI. (For
now, only HSPI or VSPI are actually supported in the driver; it will support all 3 peripherals
somewhere in the future.)
* Bus: The SPI bus, common to all SPI devices connected to one host. In general the bus consists of the
miso, mosi, sclk and optionally quadwp and quadhd signals. The SPI slaves are connected to these
signals in parallel.
- miso - Also known as q, this is the input of the serial stream into the ESP32
- mosi - Also known as d, this is the output of the serial stream from the ESP32
- sclk - Clock signal. Each data bit is clocked out or in on the positive or negative edge of this signal
- quadwp - Write Protect signal. Only used for 4-bit (qio/qout) transactions.
- quadhd - Hold signal. Only used for 4-bit (qio/qout) transactions.
* Device: A SPI slave. Each SPI slave has its own chip select (CS) line, which is made active when
a transmission to/from the SPI slave occurs.
* Transaction: One instance of CS going active, data transfer from and/or to a device happening, and
CS going inactive again. Transactions are atomic, as in they will never be interrupted by another
transaction.
SPI transactions
^^^^^^^^^^^^^^^^
A transaction on the SPI bus consists of five phases, any of which may be skipped:
* The command phase. In this phase, a command (0-16 bit) is clocked out.
* The address phase. In this phase, an address (0-64 bit) is clocked out.
* The read phase. The slave sends data to the master.
* The write phase. The master sends data to the slave.
In full duplex, the read and write phases are combined, causing the SPI host to read and
write data simultaneously.
The command and address phase are optional in that not every SPI device will need to be sent a command
and/or address. Tis is reflected in the device configuration: when the ``command_bits`` or ``data_bits``
fields are set to zero, no command or address phase is done.
Something similar is true for the read and write phase: not every transaction needs both data to be written
as well as data to be read. When ``rx_buffer`` is NULL (and SPI_USE_RXDATA) is not set) the read phase
is skipped. When ``tx_buffer`` is NULL (and SPI_USE_TXDATA) is not set) the write phase is skipped.
Using the spi_master driver
^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Initialize a SPI bus by calling ``spi_bus_initialize``. Make sure to set the correct IO pins in
the ``bus_config`` struct. Take care to set signals that are not needed to -1.
- Tell the driver about a SPI slave device connected to the bus by calling spi_bus_add_device.
Make sure to configure any timing requirements the device has in the ``dev_config`` structure.
You should now have a handle for the device, to be used when sending it a transaction.
- To interact with the device, fill one or more spi_transaction_t structure with any transaction
parameters you need. Either queue all transactions by calling ``spi_device_queue_trans``, later
quering the result using ``spi_device_get_trans_result``, or handle all requests synchroneously
by feeding them into ``spi_device_transmit``.
- Optional: to unload the driver for a device, call ``spi_bus_remove_device`` with the device
handle as an argument
- Optional: to remove the driver for a bus, make sure no more drivers are attached and call
``spi_bus_free``.
Transaction data
^^^^^^^^^^^^^^^^
Normally, data to be transferred to or from a device will be read from or written to a chunk of memory
indicated by the ``rx_buffer`` and ``tx_buffer`` members of the transaction structure. The SPI driver
may decide to use DMA for transfers, so these buffers should be allocated in DMA-capable memory using
``pvPortMallocCaps(size, MALLOC_CAP_DMA)``.
Sometimes, the amount of data is very small making it less than optimal allocating a separate buffer
for it. If the data to be transferred is 32 bits or less, it can be stored in the transaction struct
itself. For transmitted data, use the ``tx_data`` member for this and set the ``SPI_USE_TXDATA`` flag
on the transmission. For received data, use ``rx_data`` and set ``SPI_USE_RXDATA``. In both cases, do
not touch the ``tx_buffer`` or ``rx_buffer`` members, because they use the same memory locations
as ``tx_data`` and ``rx_data``.
Application Example
-------------------
Display graphics on the ILI9341-based 320x240 LCD: :example:`peripherals/spi_master`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`driver/include/driver/spi_master.h`
Macros
^^^^^^
.. doxygendefine:: SPI_DEVICE_TXBIT_LSBFIRST
.. doxygendefine:: SPI_DEVICE_RXBIT_LSBFIRST
.. doxygendefine:: SPI_DEVICE_BIT_LSBFIRST
.. doxygendefine:: SPI_DEVICE_3WIRE
.. doxygendefine:: SPI_DEVICE_POSITIVE_CS
.. doxygendefine:: SPI_DEVICE_HALFDUPLEX
.. doxygendefine:: SPI_DEVICE_CLK_AS_CS
.. doxygendefine:: SPI_TRANS_MODE_DIO
.. doxygendefine:: SPI_TRANS_MODE_QIO
.. doxygendefine:: SPI_TRANS_MODE_DIOQIO_ADDR
.. doxygendefine:: SPI_TRANS_USE_RXDATA
.. doxygendefine:: SPI_TRANS_USE_TXDATA
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: spi_device_handle_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: spi_host_device_t
Structures
^^^^^^^^^^
.. doxygenstruct:: spi_transaction_t
:members:
.. doxygenstruct:: spi_bus_config_t
:members:
.. doxygenstruct:: spi_device_interface_config_t
:members:
Functions
---------
.. doxygenfunction:: spi_bus_initialize
.. doxygenfunction:: spi_bus_free
.. doxygenfunction:: spi_bus_add_device
.. doxygenfunction:: spi_bus_remove_device
.. doxygenfunction:: spi_device_queue_trans
.. doxygenfunction:: spi_device_get_trans_result
.. doxygenfunction:: spi_device_transmit
docs/api-reference/peripherals/spi_slave.rst
+142
View File
@@ -0,0 +1,142 @@
SPI Slave driver
=================
Overview
--------
The ESP32 has four SPI peripheral devices, called SPI0, SPI1, HSPI and VSPI. SPI0 is entirely dedicated to
the flash cache the ESP32 uses to map the SPI flash device it is connected to into memory. SPI1 is
connected to the same hardware lines as SPI0 and is used to write to the flash chip. HSPI and VSPI
are free to use, and with the spi_slave driver, these can be used as a SPI slave, driven from a
connected SPI master.
The spi_slave driver
^^^^^^^^^^^^^^^^^^^^^
The spi_slave driver allows using the HSPI and/or VSPI peripheral as a full-duplex SPI slave. It can make
use of DMA to send/receive transactions of arbitrary length.
Terminology
^^^^^^^^^^^
The spi_slave driver uses the following terms:
* Host: The SPI peripheral inside the ESP32 initiating the SPI transmissions. One of HSPI or VSPI.
* Bus: The SPI bus, common to all SPI devices connected to a master. In general the bus consists of the
miso, mosi, sclk and optionally quadwp and quadhd signals. The SPI slaves are connected to these
signals in parallel. Each SPI slave is also connected to one CS signal.
- miso - Also known as q, this is the output of the serial stream from the ESP32 to the SPI master
- mosi - Also known as d, this is the output of the serial stream from the SPI master to the ESP32
- sclk - Clock signal. Each data bit is clocked out or in on the positive or negative edge of this signal
- cs - Chip Select. An active Chip Select delineates a single transaction to/from a slave.
* Transaction: One instance of CS going active, data transfer from and to a master happening, and
CS going inactive again. Transactions are atomic, as in they will never be interrupted by another
transaction.
SPI transactions
^^^^^^^^^^^^^^^^
A full-duplex SPI transaction starts with the master pulling CS low. After this happens, the master
starts sending out clock pulses on the CLK line: every clock pulse causes a data bit to be shifted from
the master to the slave on the MOSI line and vice versa on the MISO line. At the end of the transaction,
the master makes CS high again.
Using the spi_slave driver
^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Initialize a SPI peripheral as a slave by calling ``spi_slave_initialize``. Make sure to set the
correct IO pins in the ``bus_config`` struct. Take care to set signals that are not needed to -1.
A DMA channel (either 1 or 2) must be given if transactions will be larger than 32 bytes, if not
the dma_chan parameter may be 0.
- To set up a transaction, fill one or more spi_transaction_t structure with any transaction
parameters you need. Either queue all transactions by calling ``spi_slave_queue_trans``, later
quering the result using ``spi_slave_get_trans_result``, or handle all requests synchroneously
by feeding them into ``spi_slave_transmit``. The latter two functions will block until the
master has initiated and finished a transaction, causing the queued data to be sent and received.
- Optional: to unload the SPI slave driver, call ``spi_slave_free``.
Transaction data and master/slave length mismatches
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Normally, data to be transferred to or from a device will be read from or written to a chunk of memory
indicated by the ``rx_buffer`` and ``tx_buffer`` members of the transaction structure. The SPI driver
may decide to use DMA for transfers, so these buffers should be allocated in DMA-capable memory using
``pvPortMallocCaps(size, MALLOC_CAP_DMA)``.
The amount of data written to the buffers is limited by the ``length`` member of the transaction structure:
the driver will never read/write more data than indicated there. The ``length`` cannot define the actual
length of the SPI transaction; this is determined by the master as it drives the clock and CS lines. In
case the length of the transmission is larger than the buffer length, only the start of the transmission
will be sent and received. In case the transmission length is shorter than the buffer length, only data up
to the length of the buffer will be exchanged.
Warning: Due to a design peculiarity in the ESP32, if the amount of bytes sent by the master or the length
of the transmission queues in the slave driver, in bytes, is not both larger than eight and dividable by
four, the SPI hardware can fail to write the last one to seven bytes to the receive buffer.
Application Example
-------------------
Slave/master communication: :example:`peripherals/spi_slave`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`driver/include/driver/spi_slave.h`
Macros
^^^^^^
.. doxygendefine:: SPI_SLAVE_TXBIT_LSBFIRST
.. doxygendefine:: SPI_SLAVE_RXBIT_LSBFIRST
.. doxygendefine:: SPI_SLAVE_BIT_LSBFIRST
.. doxygendefine:: SPI_SLAVE_POSITIVE_CS
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: spi_host_device_t
Type Definitions
^^^^^^^^^^^^^^^^
Structures
^^^^^^^^^^
.. doxygenstruct:: spi_slave_transaction_t
:members:
.. doxygenstruct:: spi_slave_interface_config_t
:members:
.. doxygenstruct:: spi_bus_config_t
:members:
Be advised that the slave driver does not use the quadwp/quadhd lines and fields in ``spi_bus_config_t`` refering to these lines
will be ignored and can thus safely be left uninitialized.
Functions
---------
.. doxygenfunction:: spi_slave_initialize
.. doxygenfunction:: spi_slave_free
.. doxygenfunction:: spi_slave_queue_trans
.. doxygenfunction:: spi_slave_get_trans_result
.. doxygenfunction:: spi_slave_transmit
docs/api-reference/peripherals/timer.rst
+73
View File
@@ -0,0 +1,73 @@
TIMER
========
Overview
--------
ESP32 chip contains two hardware timer groups, each containing two general-purpose hardware timers.
They are all 64-bit generic timers based on 16-bit prescalers and 64-bit auto-reload-capable up/down counters.
Application Example
-------------------
64-bit hardware timer example: :example:`peripherals/timer_group`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`driver/include/driver/timer.h`
Macros
^^^^^^
.. doxygendefine:: TIMER_BASE_CLK
Type Definitions
^^^^^^^^^^^^^^^^
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: timer_group_t
.. doxygenenum:: timer_idx_t
.. doxygenenum:: timer_count_dir_t
.. doxygenenum:: timer_start_t
.. doxygenenum:: timer_alarm_t
.. doxygenenum:: timer_intr_mode_t
.. doxygenenum:: timer_autoreload_t
Structures
^^^^^^^^^^
.. doxygenstruct:: timer_config_t
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: timer_get_counter_value
.. doxygenfunction:: timer_get_counter_time_sec
.. doxygenfunction:: timer_set_counter_value
.. doxygenfunction:: timer_start
.. doxygenfunction:: timer_pause
.. doxygenfunction:: timer_set_counter_mode
.. doxygenfunction:: timer_set_auto_reload
.. doxygenfunction:: timer_set_divider
.. doxygenfunction:: timer_set_alarm_value
.. doxygenfunction:: timer_get_alarm_value
.. doxygenfunction:: timer_set_alarm
.. doxygenfunction:: timer_isr_register
.. doxygenfunction:: timer_init
.. doxygenfunction:: timer_get_config
.. doxygenfunction:: timer_group_intr_enable
.. doxygenfunction:: timer_group_intr_disable
.. doxygenfunction:: timer_enable_intr
.. doxygenfunction:: timer_disable_intr
docs/api-reference/peripherals/uart.rst
+98
View File
@@ -0,0 +1,98 @@
UART
====
Overview
--------
`Instructions`_
.. _Instructions: ../template.html
Application Example
-------------------
Configure uart settings and install uart driver to read/write using UART0 and UART1 interfaces: :example:`peripherals/uart`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`driver/include/driver/uart.h`
Data Structures
^^^^^^^^^^^^^^^
.. doxygenstruct:: uart_config_t
:members:
.. doxygenstruct:: uart_intr_config_t
:members:
.. doxygenstruct:: uart_event_t
:members:
Macros
^^^^^^
.. doxygendefine:: UART_FIFO_LEN
.. doxygendefine:: UART_INTR_MASK
.. doxygendefine:: UART_LINE_INV_MASK
.. doxygendefine:: UART_BITRATE_MAX
.. doxygendefine:: UART_PIN_NO_CHANGE
.. doxygendefine:: UART_INVERSE_DISABLE
.. doxygendefine:: UART_INVERSE_RXD
.. doxygendefine:: UART_INVERSE_CTS
.. doxygendefine:: UART_INVERSE_TXD
.. doxygendefine:: UART_INVERSE_RTS
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: uart_word_length_t
.. doxygenenum:: uart_stop_bits_t
.. doxygenenum:: uart_port_t
.. doxygenenum:: uart_parity_t
.. doxygenenum:: uart_hw_flowcontrol_t
.. doxygenenum:: uart_event_type_t
Functions
^^^^^^^^^
.. doxygenfunction:: uart_set_word_length
.. doxygenfunction:: uart_get_word_length
.. doxygenfunction:: uart_set_stop_bits
.. doxygenfunction:: uart_get_stop_bits
.. doxygenfunction:: uart_set_parity
.. doxygenfunction:: uart_get_parity
.. doxygenfunction:: uart_set_baudrate
.. doxygenfunction:: uart_get_baudrate
.. doxygenfunction:: uart_set_line_inverse
.. doxygenfunction:: uart_set_hw_flow_ctrl
.. doxygenfunction:: uart_get_hw_flow_ctrl
.. doxygenfunction:: uart_clear_intr_status
.. doxygenfunction:: uart_enable_intr_mask
.. doxygenfunction:: uart_disable_intr_mask
.. doxygenfunction:: uart_enable_rx_intr
.. doxygenfunction:: uart_disable_rx_intr
.. doxygenfunction:: uart_disable_tx_intr
.. doxygenfunction:: uart_enable_tx_intr
.. doxygenfunction:: uart_isr_register
.. doxygenfunction:: uart_set_pin
.. doxygenfunction:: uart_set_rts
.. doxygenfunction:: uart_set_dtr
.. doxygenfunction:: uart_param_config
.. doxygenfunction:: uart_intr_config
.. doxygenfunction:: uart_driver_install
.. doxygenfunction:: uart_driver_delete
.. doxygenfunction:: uart_wait_tx_done
.. doxygenfunction:: uart_tx_chars
.. doxygenfunction:: uart_write_bytes
.. doxygenfunction:: uart_write_bytes_with_break
.. doxygenfunction:: uart_read_bytes
.. doxygenfunction:: uart_flush
.. doxygenfunction:: uart_get_buffered_data_len
.. doxygenfunction:: uart_disable_pattern_det_intr
.. doxygenfunction:: uart_enable_pattern_det_intr