alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

docs: Add missing peripheral driver docs (ADC, DAC, RTC I/O, I2S)

Browse Source
This commit is contained in:
Angus Gratton 2017-02-16 13:59:50 +11:00
parent 21964a42fb
commit bfdfcbfaef
11 changed files with 464 additions and 185 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
components/driver/include/driver/adc.h
View File

@ -49,11 +49,11 @@ typedef enum {
} adc1_channel_t; } adc1_channel_t;
/** /**
* @brief Configuration ADC1 capture width. * @brief Configure ADC1 capture width.
* *
* The configuration is in effect for all channels of ADC1 * The configuration is for all channels of ADC1
* *
* @param width_bit ADC1 * @param width_bit Bit capture width for ADC1
* *
* @return * @return
* - ESP_OK success * - ESP_OK success
@ -62,10 +62,29 @@ typedef enum {
esp_err_t adc1_config_width(adc_bits_width_t width_bit); esp_err_t adc1_config_width(adc_bits_width_t width_bit);
/** /**
* @brief Configuration ADC1 capture attenuation of channels. * @brief Configure the ADC1 channel, including setting attenuation.
* *
* @param channel the ADC1 channel * @note This function also configures the input GPIO pin mux to
* @param atten attenuation * connect it to the ADC1 channel. It must be called before calling
* adc1_get_voltage() for this channel.
*
* The default ADC full-scale voltage is 1.1V. To read higher voltages (up to the pin maximum voltage,
* usually 3.3V) requires setting >0dB signal attenuation for that ADC channel.
*
* When VDD_A is 3.3V:
*
* - 0dB attenuaton (ADC_ATTEN_0db) gives full-scale voltage 1.1V
* - 2.5dB attenuation (ADC_ATTEN_2_5db) gives full-scale voltage 1.5V
* - 6dB attenuation (ADC_ATTEN_6db) gives full-scale voltage 2.2V
* - 11dB attenuation (ADC_ATTEN_11db) gives full-scale voltage 3.9V (see note below)
*
* @note The full-scale voltage is the voltage corresponding to a maximum reading (depending on ADC1 configured
* bit width, this value is: 4095 for 12-bits, 2047 for 11-bits, 1023 for 10-bits, 511 for 9 bits.)
*
* @note At 11dB attenuation the maximum voltage is limited by VDD_A, not the full scale voltage.
*
* @param channel ADC1 channel to configure
* @param atten Attenuation level
* *
* @return * @return
* - ESP_OK success * - ESP_OK success
@ -74,46 +93,38 @@ esp_err_t adc1_config_width(adc_bits_width_t width_bit);
esp_err_t adc1_config_channel_atten(adc1_channel_t channel, adc_atten_t atten); esp_err_t adc1_config_channel_atten(adc1_channel_t channel, adc_atten_t atten);
/** /**
* @brief ADC1 get the value of the voltage. * @brief Take an ADC1 reading on a single channel
* *
* @param channel the ADC1 channel * @note Call adc1_config_width() before the first time this
* function is called.
*
* @note For a given channel, adc1_config_channel_atten(channel)
* must be called before the first time this function is called.
*
* @param channel ADC1 channel to read
* *
* @return * @return
* - -1 Parameter error * - -1: Parameter error
* - Other the value of ADC1 channel * - Other: ADC1 channel reading.
*/ */
int adc1_get_voltage(adc1_channel_t channel); int adc1_get_voltage(adc1_channel_t channel);
/** /**
* @brief Hall Sensor output value. * @brief Read Hall Sensor
* @note
* The Hall Sensor uses Channel_0 and Channel_3 of ADC1.
* So, firstly: please configure ADC1 module by calling adc1_config_width before calling hall_sensor_read.
We recommend that the WIDTH ADC1 be configured as 12Bit, because the values of hall_sensor_read are small and almost the same if WIDTH ADC1 is configured as 9Bit, 10Bit or 11Bit.
* secondly: when you use the hall sensor, please do not use Channel_0 and Channel_3 of ADC1 as
* ADC channels.
* *
* @return the value of hall sensor * @note The Hall Sensor uses channels 0 and 3 of ADC1. Do not configure
* these channels for use as ADC channels.
*
* @note The ADC1 module must be enabled by calling
* adc1_config_width() before calling hall_sensor_read(). ADC1
* should be configured for 12 bit readings, as the hall sensor
* readings are low values and do not cover the full range of the
* ADC.
*
* @return The hall sensor reading.
*/ */
int hall_sensor_read(); int hall_sensor_read();
/**
*----------EXAMPLE TO USE ADC1------------ *
* @code{c}
* adc1_config_width(ADC_WIDTH_12Bit);//config adc1 width
* adc1_config_channel_atten(ADC1_CHANNEL_0,ADC_ATTEN_0db);//config channel0 attenuation
* int val=adc1_get_voltage(ADC1_CHANNEL_0);//get the val of channel0
* @endcode
**/
/**
*----------EXAMPLE TO USE HALL SENSOR------------ *
* @code{c}
* adc1_config_width(ADC_WIDTH_12Bit);//config adc1 width
* int val=hall_sensor_read();
* @endcode
**/
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif

18
components/driver/include/driver/dac.h
View File

@ -29,12 +29,15 @@ typedef enum {
} dac_channel_t; } dac_channel_t;
/** /**
* @brief Set Dac output voltage. * @brief Set DAC output voltage.
* *
* Dac width is 8bit ,and the voltage max is vdd * DAC output is 8-bit. Maximum (255) corresponds to VDD.
* *
* @param channel dac channel * @note When this function is called, function for the DAC
* @param dac_value dac output value * channel's GPIO pin is reconfigured for RTC DAC function.
*
* @param channel DAC channel
* @param dac_value DAC output value
* *
* @return * @return
* - ESP_OK success * - ESP_OK success
@ -42,13 +45,6 @@ typedef enum {
*/ */
esp_err_t dac_out_voltage(dac_channel_t channel, uint8_t dac_value); esp_err_t dac_out_voltage(dac_channel_t channel, uint8_t dac_value);
/**
*----------EXAMPLE TO USE DAC------------ *
* @code{c}
* dac_out_voltage(DAC_CHANNEL_1,200);//the dac out voltage ≈ 200*vdd/255
* @endcode
**/
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif

45
components/driver/include/driver/gpio.h
View File

@ -302,9 +302,9 @@ int gpio_get_level(gpio_num_t gpio_num);
esp_err_t gpio_set_direction(gpio_num_t gpio_num, gpio_mode_t mode); esp_err_t gpio_set_direction(gpio_num_t gpio_num, gpio_mode_t mode);
/** /**
* @brief GPIO set pull * @brief Configure GPIO pull-up/pull-down resistors
* *
* User this Function,configure GPIO pull mode,such as pull-up,pull-down * Only pins that support both input & output have integrated pull-up and pull-down resistors. Input-only GPIOs 34-39 do not.
* *
* @param gpio_num GPIO number. If you want to set pull up or down mode for e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); * @param gpio_num GPIO number. If you want to set pull up or down mode for e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);
* @param pull GPIO pull up/down mode. * @param pull GPIO pull up/down mode.
@ -317,7 +317,7 @@ esp_err_t gpio_set_direction(gpio_num_t gpio_num, gpio_mode_t mode);
esp_err_t gpio_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull); esp_err_t gpio_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull);
/** /**
* @brief enable GPIO wake-up function. * @brief Enable GPIO wake-up function.
* *
* @param gpio_num GPIO number. * @param gpio_num GPIO number.
* *
@ -341,15 +341,23 @@ esp_err_t gpio_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type);
esp_err_t gpio_wakeup_disable(gpio_num_t gpio_num); esp_err_t gpio_wakeup_disable(gpio_num_t gpio_num);
/** /**
* @brief register GPIO interrupt handler, the handler is an ISR. * @brief Register GPIO interrupt handler, the handler is an ISR.
* The handler will be attached to the same CPU core that this function is running on. * The handler will be attached to the same CPU core that this function is running on.
* *
* This ISR function is called whenever any GPIO interrupt occurs. See
* the alternative gpio_install_isr_service() and
* gpio_isr_handler_add() API in order to have the driver support
* per-GPIO ISRs.
*
* @param fn Interrupt handler function. * @param fn Interrupt handler function.
* @param intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred) * @param intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred)
* ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. * ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.
* @param arg Parameter for handler function * @param arg Parameter for handler function
* @param handle Pointer to return handle. If non-NULL, a handle for the interrupt will * @param handle Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.
* be returned here. *
* \verbatim embed:rst:leading-asterisk
* To disable or remove the ISR, pass the returned handle to the :doc:`interrupt allocation functions </api/system/intr_alloc>`.
* \endverbatim
* *
* @return * @return
* - ESP_OK Success ; * - ESP_OK Success ;
@ -402,7 +410,9 @@ esp_err_t gpio_pulldown_en(gpio_num_t gpio_num);
esp_err_t gpio_pulldown_dis(gpio_num_t gpio_num); esp_err_t gpio_pulldown_dis(gpio_num_t gpio_num);
/** /**
* @brief Install a GPIO ISR service, so we can assign different ISR handler for different pins * @brief Install the driver's GPIO ISR handler service, which allows per-pin GPIO interrupt handlers.
*
* This function is incompatible with gpio_isr_register() - if that function is used, a single global ISR is registered for all GPIO interrupts. If this function is used, the ISR service provides a global GPIO ISR and individual pin handlers are registered via the gpio_isr_register() function.
* *
* @param intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred) * @param intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred)
* ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. * ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.
@ -415,17 +425,24 @@ esp_err_t gpio_pulldown_dis(gpio_num_t gpio_num);
esp_err_t gpio_install_isr_service(int intr_alloc_flags); esp_err_t gpio_install_isr_service(int intr_alloc_flags);
/** /**
* @brief Un-install GPIO ISR service, free the resources. * @brief Uninstall the driver's GPIO ISR service, freeing related resources.
*/ */
void gpio_uninstall_isr_service(); void gpio_uninstall_isr_service();
/** /**
* @brief Add ISR handler for the corresponding GPIO. * @brief Add ISR handler for the corresponding GPIO pin.
* *
* Interrupt handlers no longer need to be declared with IRAM_ATTR, unless you pass the ESP_INTR_FLAG_IRAM flag * Call this function after using gpio_install_isr_service() to
* when allocating the ISR in gpio_install_isr_service(). * install the driver's GPIO ISR handler service.
* This ISR handler will be called from an ISR. So there probably is some stack size limit, and this limit *
* is smaller compared to a "raw" interrupt handler due to another level of indirection. * The pin ISR handlers no longer need to be declared with IRAM_ATTR,
* unless you pass the ESP_INTR_FLAG_IRAM flag when allocating the
* ISR in gpio_install_isr_service().
*
* This ISR handler will be called from an ISR. So there is a stack
* size limit (configurable as "ISR stack size" in menuconfig). This
* limit is smaller compared to a global GPIO interrupt handler due
* to the additional level of indirection.
* *
* @param gpio_num GPIO number * @param gpio_num GPIO number
* @param isr_handler ISR handler function for the corresponding GPIO number. * @param isr_handler ISR handler function for the corresponding GPIO number.
@ -439,7 +456,7 @@ void gpio_uninstall_isr_service();
esp_err_t gpio_isr_handler_add(gpio_num_t gpio_num, gpio_isr_t isr_handler, void* args); esp_err_t gpio_isr_handler_add(gpio_num_t gpio_num, gpio_isr_t isr_handler, void* args);
/** /**
* @brief Remove ISR handler for the corresponding GPIO. * @brief Remove ISR handler for the corresponding GPIO pin.
* *
* @param gpio_num GPIO number * @param gpio_num GPIO number
* *

175
components/driver/include/driver/i2s.h
View File

@ -32,9 +32,6 @@
extern "C" { extern "C" {
#endif #endif
#define I2S_PIN_NO_CHANGE (-1)
/** /**
* @brief I2S bit width per sample. * @brief I2S bit width per sample.
* *
@ -147,6 +144,8 @@ typedef struct {
size_t size; /*!< I2S data size for I2S_DATA event*/ size_t size; /*!< I2S data size for I2S_DATA event*/
} i2s_event_t; } i2s_event_t;
#define I2S_PIN_NO_CHANGE (-1) /*!< Use in i2s_pin_config_t for pins which should not be changed */
/** /**
* @brief I2S pin number for i2s_set_pin * @brief I2S pin number for i2s_set_pin
* *
@ -163,12 +162,15 @@ typedef intr_handle_t i2s_isr_handle_t;
* @brief Set I2S pin number * @brief Set I2S pin number
* *
* @note * @note
* Internal signal can be output to multiple GPIO pads * The I2S peripheral output signals can be connected to multiple GPIO pads.
* Only one GPIO pad can connect with input signal * However, the I2S peripheral input signal can only be connected to one GPIO pad.
* *
* @param i2s_num I2S_NUM_0 or I2S_NUM_1 * @param i2s_num I2S_NUM_0 or I2S_NUM_1
* *
* @param pin I2S Pin struct, or NULL for 2-channels, 8-bits DAC pin configuration (GPIO25 & GPIO26) * @param pin I2S Pin structure, or NULL to set 2-channel 8-bit internal DAC pin configuration (GPIO25 & GPIO26)
*
* Inside the pin configuration structure, set I2S_PIN_NO_CHANGE for any pin where
* the current configuration should not be changed.
* *
* @return * @return
* - ESP_OK Success * - ESP_OK Success
@ -177,7 +179,7 @@ typedef intr_handle_t i2s_isr_handle_t;
esp_err_t i2s_set_pin(i2s_port_t i2s_num, const i2s_pin_config_t *pin); esp_err_t i2s_set_pin(i2s_port_t i2s_num, const i2s_pin_config_t *pin);
/** /**
* @brief i2s install and start driver * @brief Install and start I2S driver.
* *
* @param i2s_num I2S_NUM_0, I2S_NUM_1 * @param i2s_num I2S_NUM_0, I2S_NUM_1
* *
@ -187,6 +189,8 @@ esp_err_t i2s_set_pin(i2s_port_t i2s_num, const i2s_pin_config_t *pin);
* *
* @param i2s_queue I2S event queue handle, if set NULL, driver will not use an event queue. * @param i2s_queue I2S event queue handle, if set NULL, driver will not use an event queue.
* *
* This function must be called before any I2S driver read/write operations.
*
* @return * @return
* - ESP_OK Success * - ESP_OK Success
* - ESP_FAIL Parameter error * - ESP_FAIL Parameter error
@ -205,68 +209,88 @@ esp_err_t i2s_driver_install(i2s_port_t i2s_num, const i2s_config_t *i2s_config,
esp_err_t i2s_driver_uninstall(i2s_port_t i2s_num); esp_err_t i2s_driver_uninstall(i2s_port_t i2s_num);
/** /**
* @brief i2s read data buffer to i2s dma buffer * @brief Write data to I2S DMA transmit buffer.
* *
* @param i2s_num I2S_NUM_0, I2S_NUM_1 * @param i2s_num I2S_NUM_0, I2S_NUM_1
* *
* @param src source address to write * @param src Source address to write from
* *
* @param size size of data (size in bytes) * @param size Size of data in bytes
* *
* @param ticks_to_wait Write timeout * @param ticks_to_wait TX buffer wait timeout in RTOS ticks. If this
* many ticks pass without space becoming available in the DMA
* transmit buffer, then the function will return (note that if the
* data is written to the DMA buffer in pieces, the overall operation
* may still take longer than this timeout.) Pass portMAX_DELAY for no
* timeout.
* *
* @return number of written bytes * Format of the data in source buffer is determined by the I2S
* configuration (see i2s_config_t).
*
* @return Number of bytes written, or ESP_FAIL (-1) for parameter error. If a timeout occurred, bytes written will be less than total size.
*/ */
int i2s_write_bytes(i2s_port_t i2s_num, const char *src, size_t size, TickType_t ticks_to_wait); int i2s_write_bytes(i2s_port_t i2s_num, const char *src, size_t size, TickType_t ticks_to_wait);
/** /**
* @brief i2s write data buffer to i2s dma buffer * @brief Read data from I2S DMA receive buffer
* *
* @param i2s_num I2S_NUM_0, I2S_NUM_1 * @param i2s_num I2S_NUM_0, I2S_NUM_1
* *
* @param dest destination address to read * @param dest Destination address to read into
* *
* @param size size of data (size in bytes) * @param size Size of data in bytes
* *
* @param ticks_to_wait Read timeout * @param ticks_to_wait RX buffer wait timeout in RTOS ticks. If this many ticks pass without bytes becoming available in the DMA receive buffer, then the function will return (note that if data is read from the DMA buffer in pieces, the overall operation may still take longer than this timeout.) Pass portMAX_DELAY for no timeout.
* *
* @return number of read bytes * Format of the data in source buffer is determined by the I2S
* configuration (see i2s_config_t).
*
* @return Number of bytes read, or ESP_FAIL (-1) for parameter error. If a timeout occurred, bytes read will be less than total size.
*/ */
int i2s_read_bytes(i2s_port_t i2s_num, char* dest, size_t size, TickType_t ticks_to_wait); int i2s_read_bytes(i2s_port_t i2s_num, char* dest, size_t size, TickType_t ticks_to_wait);
/** /**
* @brief i2s push 1 sample to i2s dma buffer, with the size parameter equal to one sample's size in bytes = bits_per_sample/8. * @brief Push (write) a single sample to the I2S DMA TX buffer.
*
* Size of the sample is determined by the channel_format (mono or stereo)) & bits_per_sample configuration (see i2s_config_t).
* *
* @param i2s_num I2S_NUM_0, I2S_NUM_1 * @param i2s_num I2S_NUM_0, I2S_NUM_1
* *
* @param sample destination address to write (depend on bits_per_sample, size of sample (in bytes) = 2*bits_per_sample/8) * @param sample Pointer to buffer containing sample to write. Size of buffer (in bytes) = (number of channels) * bits_per_sample / 8.
* *
* @param ticks_to_wait Push timeout * @param ticks_to_wait Push timeout in RTOS ticks. If space is not available in the DMA TX buffer within this period, no data is written and function returns 0.
* *
* @return number of push bytes * @return Number of bytes successfully pushed to DMA buffer, or ESP_FAIL (-1) for parameter error. Will be either zero or the size of configured sample buffer.
*/ */
int i2s_push_sample(i2s_port_t i2s_num, const char *sample, TickType_t ticks_to_wait); int i2s_push_sample(i2s_port_t i2s_num, const char *sample, TickType_t ticks_to_wait);
/** /**
* @brief Pop 1 sample to i2s dma buffer, with the size parameter equal to one sample's size in bytes = bits_per_sample/8. * @brief Pop (read) a single sample from the I2S DMA RX buffer.
*
* Size of the sample is determined by the channel_format (mono or stereo)) & bits_per_sample configuration (see i2s_config_t).
* *
* @param i2s_num I2S_NUM_0, I2S_NUM_1 * @param i2s_num I2S_NUM_0, I2S_NUM_1
* *
* @param sample destination address to write (depend on bits_per_sample, size of sample (in bytes) = 2*bits_per_sample/8) * @param sample Buffer sample data will be read into. Size of buffer (in bytes) = (number of channels) * bits_per_sample / 8.
* *
* @param ticks_to_wait Pop timeout * @param ticks_to_wait Pop timeout in RTOS ticks. If a sample is not available in the DMA buffer within this period, no data is read and function returns zero.
* *
* @return number of pop bytes * @return Number of bytes successfully read from DMA buffer, or ESP_FAIL (-1) for parameter error. Byte count will be either zero or the size of the configured sample buffer.
*/ */
int i2s_pop_sample(i2s_port_t i2s_num, char *sample, TickType_t ticks_to_wait); int i2s_pop_sample(i2s_port_t i2s_num, char *sample, TickType_t ticks_to_wait);
/** /**
* @brief Set clock rate used for I2S RX and TX * @brief Set sample rate used for I2S RX and TX.
*
* The bit clock rate is determined by the sample rate and i2s_config_t configuration parameters (number of channels, bits_per_sample).
*
* `bit_clock = rate * (number of channels) * bits_per_sample`
* *
* @param i2s_num I2S_NUM_0, I2S_NUM_1 * @param i2s_num I2S_NUM_0, I2S_NUM_1
* *
* @param rate I2S clock (ex: 8000, 44100...) * @param rate I2S sample rate (ex: 8000, 44100...)
* *
* @return * @return
* - ESP_OK Success * - ESP_OK Success
@ -275,18 +299,9 @@ int i2s_pop_sample(i2s_port_t i2s_num, char *sample, TickType_t ticks_to_wait);
esp_err_t i2s_set_sample_rates(i2s_port_t i2s_num, uint32_t rate); esp_err_t i2s_set_sample_rates(i2s_port_t i2s_num, uint32_t rate);
/** /**
* @brief Start driver * @brief Stop I2S driver
* *
* @param i2s_num I2S_NUM_0, I2S_NUM_1 * Disables I2S TX/RX, until i2s_start() is called.
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t i2s_start(i2s_port_t i2s_num);
/**
* @brief Stop driver
* *
* @param i2s_num I2S_NUM_0, I2S_NUM_1 * @param i2s_num I2S_NUM_0, I2S_NUM_1
* *
@ -297,7 +312,23 @@ esp_err_t i2s_start(i2s_port_t i2s_num);
esp_err_t i2s_stop(i2s_port_t i2s_num); esp_err_t i2s_stop(i2s_port_t i2s_num);
/** /**
* @brief Set the TX DMA buffer contents to all zeroes * @brief Start I2S driver
*
* It is not necessary to call this function after i2s_driver_install() (it is started automatically), however it is necessary to call it after i2s_stop().
*
*
* @param i2s_num I2S_NUM_0, I2S_NUM_1
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t i2s_start(i2s_port_t i2s_num);
/**
* @brief Zero the contents of the TX DMA buffer.
*
* Pushes zero-byte samples into the TX DMA buffer, until it is full.
* *
* @param i2s_num I2S_NUM_0, I2S_NUM_1 * @param i2s_num I2S_NUM_0, I2S_NUM_1
* *
@ -307,72 +338,6 @@ esp_err_t i2s_stop(i2s_port_t i2s_num);
*/ */
esp_err_t i2s_zero_dma_buffer(i2s_port_t i2s_num); esp_err_t i2s_zero_dma_buffer(i2s_port_t i2s_num);
/***************************EXAMPLE**********************************
*
*
* ----------------EXAMPLE OF I2S SETTING ---------------------
* @code{c}
*
* #include "freertos/queue.h"
* #define I2S_INTR_NUM 17 //choose one interrupt number from soc.h
* int i2s_num = 0; //i2s port number
* i2s_config_t i2s_config = {
* .mode = I2S_MODE_MASTER | I2S_MODE_TX,
* .sample_rate = 44100,
* .bits_per_sample = 16, //16, 32
* .channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT, //format LEFT_RIGHT
* .communication_format = I2S_COMM_FORMAT_I2S | I2S_COMM_FORMAT_I2S_MSB,
* .intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
* .dma_buf_count = 8,
* .dma_buf_len = 64
* };
*
* 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
*@endcode
*
* ----------------EXAMPLE USING I2S WITH DAC ---------------------
* @code{c}
*
* #include "freertos/queue.h"
* #define I2S_INTR_NUM 17 //choose one interrupt number from soc.h
* int i2s_num = 0; //i2s port number
* i2s_config_t i2s_config = {
* .mode = I2S_MODE_MASTER | I2S_MODE_TX | I2S_MODE_DAC_BUILT_IN,
* .sample_rate = 44100,
* .bits_per_sample = 8, // Only 8-bit DAC support
* .channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT, //
* .communication_format = I2S_COMM_FORMAT_I2S_MSB,
* .intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
* .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
*@endcode
*-----------------------------------------------------------------------------*
***************************END OF EXAMPLE**********************************/
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif

14
components/driver/include/driver/rtc_io.h
View File

@ -24,7 +24,10 @@ extern "C" {
#endif #endif
/** /**
* @brief Pullup/pulldown information for a single GPIO pad * @brief Pin function information for a single GPIO pad's RTC functions.
*
* This is an internal function of the driver, and is not usually useful
* for external use.
*/ */
typedef struct { typedef struct {
uint32_t reg; /*!< Register of RTC pad, or 0 if not an RTC GPIO */ uint32_t reg; /*!< Register of RTC pad, or 0 if not an RTC GPIO */
@ -46,6 +49,13 @@ typedef enum {
RTC_GPIO_MODE_DISABLED, /*!< Pad (output + input) disable */ RTC_GPIO_MODE_DISABLED, /*!< Pad (output + input) disable */
} rtc_gpio_mode_t; } rtc_gpio_mode_t;
/**
* @brief Provides access to a constant table of RTC I/O pin
* function information.
*
* This is an internal function of the driver, and is not usually useful
* for external use.
*/
extern const rtc_gpio_desc_t rtc_gpio_desc[GPIO_PIN_COUNT]; extern const rtc_gpio_desc_t rtc_gpio_desc[GPIO_PIN_COUNT];
/** /**
@ -60,7 +70,7 @@ inline static bool rtc_gpio_is_valid_gpio(gpio_num_t gpio_num)
&& rtc_gpio_desc[gpio_num].reg != 0; && rtc_gpio_desc[gpio_num].reg != 0;
} }
#define RTC_GPIO_IS_VALID_GPIO(gpio_num) rtc_gpio_is_valid(gpio_num) // Deprecated, use rtc_gpio_is_valid_gpio() #define RTC_GPIO_IS_VALID_GPIO(gpio_num) rtc_gpio_is_valid_gpio(gpio_num) // Deprecated, use rtc_gpio_is_valid_gpio()
/** /**
* @brief Init a GPIO as RTC GPIO * @brief Init a GPIO as RTC GPIO

62
docs/api/peripherals/adc.rst Normal file
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

45
docs/api/peripherals/dac.rst Normal file
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

47
docs/api/peripherals/gpio.rst
View File

@ -1,11 +1,15 @@
GPIO GPIO & RTC GPIO
==== ===============
Overview 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. 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 Application Example
------------------- -------------------
@ -19,10 +23,14 @@ Header Files
^^^^^^^^^^^^ ^^^^^^^^^^^^
* :component_file:`driver/include/driver/gpio.h` * :component_file:`driver/include/driver/gpio.h`
* :component_file:`driver/include/driver/rtc_io.h`
Macros Macros
^^^^^^ ^^^^^^
Normal GPIO
~~~~~~~~~~~
.. doxygendefine:: GPIO_SEL_0 .. doxygendefine:: GPIO_SEL_0
.. doxygendefine:: GPIO_SEL_1 .. doxygendefine:: GPIO_SEL_1
.. doxygendefine:: GPIO_SEL_2 .. doxygendefine:: GPIO_SEL_2
@ -107,12 +115,18 @@ Macros
Type Definitions Type Definitions
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
Normal GPIO
~~~~~~~~~~~
.. doxygentypedef:: gpio_isr_t .. doxygentypedef:: gpio_isr_t
.. doxygentypedef:: gpio_isr_handle_t .. doxygentypedef:: gpio_isr_handle_t
Enumerations Enumerations
^^^^^^^^^^^^ ^^^^^^^^^^^^
Normal GPIO
~~~~~~~~~~~
.. doxygenenum:: gpio_num_t .. doxygenenum:: gpio_num_t
.. doxygenenum:: gpio_int_type_t .. doxygenenum:: gpio_int_type_t
.. doxygenenum:: gpio_mode_t .. doxygenenum:: gpio_mode_t
@ -120,16 +134,26 @@ Enumerations
.. doxygenenum:: gpio_pulldown_t .. doxygenenum:: gpio_pulldown_t
.. doxygenenum:: gpio_pull_mode_t .. doxygenenum:: gpio_pull_mode_t
RTC GPIO
~~~~~~~~
.. doxygenenum:: rtc_gpio_mode_t
Structures Structures
^^^^^^^^^^ ^^^^^^^^^^
Normal GPIO
~~~~~~~~~~~
.. doxygenstruct:: gpio_config_t .. doxygenstruct:: gpio_config_t
:members: :members:
Functions Functions
^^^^^^^^^ ^^^^^^^^^
Normal GPIO
~~~~~~~~~~~
.. doxygenfunction:: gpio_config .. doxygenfunction:: gpio_config
.. doxygenfunction:: gpio_set_intr_type .. doxygenfunction:: gpio_set_intr_type
.. doxygenfunction:: gpio_intr_enable .. doxygenfunction:: gpio_intr_enable
@ -150,3 +174,18 @@ Functions
.. doxygenfunction:: gpio_isr_handler_add .. doxygenfunction:: gpio_isr_handler_add
.. doxygenfunction:: gpio_isr_handler_remove .. 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
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

17
docs/api/peripherals/index.rst
View File

@ -4,15 +4,18 @@ Peripherals API
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
GPIO <gpio> ADC <adc>
UART <uart> DAC <dac>
GPIO (including RTC low power I/O) <gpio>
I2C <i2c> I2C <i2c>
SPI Master <spi_master> I2S <i2s>
Timer <timer>
Pulse Counter <pcnt>
Sigma-delta Modulation <sigmadelta>
LED Control <ledc> LED Control <ledc>
Pulse Counter <pcnt>
SD/MMC Card Host <../storage/sdmmc>
Sigma-delta Modulation <sigmadelta>
SPI Master <spi_master>
Remote Control <rmt> Remote Control <rmt>
Timer <timer>
UART <uart>
Example code for this API section is provided in :example:`peripherals` directory of ESP-IDF examples. Example code for this API section is provided in :example:`peripherals` directory of ESP-IDF examples.