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

2017-02-16 13:59:50 +11:00
parent 21964a42fb
commit bfdfcbfaef
11 changed files with 464 additions and 185 deletions
--- a/docs/api/peripherals/i2s.rst
+++ b/docs/api/peripherals/i2s.rst
@@ -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
+
+