alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-11-26 20:53:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Resolve doxygen & Sphinx warnings

Browse Source
This commit is contained in:
Angus Gratton
2020-01-29 09:31:14 +11:00
committed by Angus Gratton
parent 268816649c
commit 11fac8637a
38 changed files with 312 additions and 273 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/en/api-reference/peripherals/adc.rst
View File

@@ -85,7 +85,7 @@ Reading voltage on ADC2 channel 7 ({IDF_TARGET_ADC2_CH7})::
The reading may fail due to collision with Wi-Fi, should check it.
An example using the ADC2 driver to read the output of DAC is available in esp-idf: :example:`peripherals/adc2`
.. only: esp32
.. only:: esp32
Reading the internal hall effect sensor::

6
docs/en/api-reference/peripherals/esp_slave_protocol.rst
View File

@@ -6,12 +6,6 @@ Communication with ESP SDIO Slave
ESP SDIO slave initialization
------------------------------
.. only:: esp32s2
.. note::
{IDF_TARGET_NAME} does not have a SDIO peripheral.
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

10
docs/en/api-reference/peripherals/index.rst
View File

@@ -14,17 +14,17 @@ Peripherals API
I2C <i2c>
I2S <i2s>
LED Control <ledc>
MCPWM <mcpwm>
:esp32: MCPWM <mcpwm>
Pulse Counter <pcnt>
Remote Control <rmt>
SD Pull-up Requirements <sd_pullup_requirements>
SDMMC Host <sdmmc_host>
:esp32: SD Pull-up Requirements <sd_pullup_requirements>
:esp32: SDMMC Host <sdmmc_host>
SD SPI Host <sdspi_host>
SDIO Slave <sdio_slave>
:esp32: SDIO Slave <sdio_slave>
Sigma-delta Modulation <sigmadelta>
SPI Master <spi_master>
SPI Slave <spi_slave>
Temp sensor <temp_sensor>
:esp32s2: Temp sensor <temp_sensor>
Timer <timer>
Touch Sensor <touch_pad>
UART <uart>

8
docs/en/api-reference/peripherals/sdio_slave.rst
View File

@@ -4,14 +4,6 @@ SDIO Card Slave Driver
Overview
--------
.. only:: esp32s2
.. note::
{IDF_TARGET_NAME} does not have a SDIO peripheral.
.. only:: esp32
The ESP32 SDIO Card peripherals (Host, Slave) shares two sets of pins as below table.
The first set is usually occupied by SPI0 bus which is responsible for the SPI flash holding the code to run.
This means SDIO slave driver can only runs on the second set of pins while SDIO host is not using it.

75
docs/en/api-reference/peripherals/sdmmc_host.rst
View File

@@ -3,54 +3,47 @@ SDMMC Host Driver
Overview
--------
.. only:: esp32s2
.. note::
ESP32's SDMMC host peripheral has two slots:
{IDF_TARGET_NAME} does not have a SDMMC host peripheral.
- Slot 0 (:c:macro:`SDMMC_HOST_SLOT_0`) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX.
- Slot 1 (:c:macro:`SDMMC_HOST_SLOT_1`) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX.
.. only:: esp32
Pin mappings of these slots are given in the table below.
ESP32's SDMMC host peripheral has two slots:
+--------+-------------+-------------+
| Signal | Slot 0 | Slot 1 |
+========+=============+=============+
| CMD | GPIO11 | GPIO15 |
+--------+-------------+-------------+
| CLK | GPIO6 | GPIO14 |
+--------+-------------+-------------+
| D0 | GPIO7 | GPIO2 |
+--------+-------------+-------------+
| D1 | GPIO8 | GPIO4 |
+--------+-------------+-------------+
| D2 | GPIO9 | GPIO12 |
+--------+-------------+-------------+
| D3 | GPIO10 | GPIO13 |
+--------+-------------+-------------+
| D4 | GPIO16 | |
+--------+-------------+-------------+
| D5 | GPIO17 | |
+--------+-------------+-------------+
| D6 | GPIO5 | |
+--------+-------------+-------------+
| D7 | GPIO18 | |
+--------+-------------+-------------+
| CD | any input via GPIO matrix |
+--------+---------------------------+
| WP | any input via GPIO matrix |
+--------+---------------------------+
- Slot 0 (:c:macro:`SDMMC_HOST_SLOT_0`) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX.
- Slot 1 (:c:macro:`SDMMC_HOST_SLOT_1`) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX.
The Card Detect and Write Protect signals can be routed to arbitrary pins using the GPIO matrix. To reserve the pins, set the ``gpio_cd`` and ``gpio_wp`` members of the :cpp:class:`sdmmc_slot_config_t` structure before calling :cpp:func:`sdmmc_host_init_slot`. Please note that it is not advised to specify a Card Detect pin when working with SDIO cards, because the card detect signal in ESP32 can also trigger SDIO slave interrupt.
Pin mappings of these slots are given in the table below.
.. warning::
+--------+-------------+-------------+
| Signal | Slot 0 | Slot 1 |
+========+=============+=============+
| CMD | GPIO11 | GPIO15 |
+--------+-------------+-------------+
| CLK | GPIO6 | GPIO14 |
+--------+-------------+-------------+
| D0 | GPIO7 | GPIO2 |
+--------+-------------+-------------+
| D1 | GPIO8 | GPIO4 |
+--------+-------------+-------------+
| D2 | GPIO9 | GPIO12 |
+--------+-------------+-------------+
| D3 | GPIO10 | GPIO13 |
+--------+-------------+-------------+
| D4 | GPIO16 | |
+--------+-------------+-------------+
| D5 | GPIO17 | |
+--------+-------------+-------------+
| D6 | GPIO5 | |
+--------+-------------+-------------+
| D7 | GPIO18 | |
+--------+-------------+-------------+
| CD | any input via GPIO matrix |
+--------+---------------------------+
| WP | any input via GPIO matrix |
+--------+---------------------------+
The Card Detect and Write Protect signals can be routed to arbitrary pins using the GPIO matrix. To reserve the pins, set the ``gpio_cd`` and ``gpio_wp`` members of the :cpp:class:`sdmmc_slot_config_t` structure before calling :cpp:func:`sdmmc_host_init_slot`. Please note that it is not advised to specify a Card Detect pin when working with SDIO cards, because the card detect signal in ESP32 can also trigger SDIO slave interrupt.
.. warning::
Pins used by Slot 0 (``HS1_*``) are also used to connect the SPI flash chip in ESP32-WROOM and ESP32-WROVER modules. These pins cannot be shared between an SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set eFuses accordingly.
Pins used by Slot 0 (``HS1_*``) are also used to connect the SPI flash chip in ESP32-WROOM and ESP32-WROVER modules. These pins cannot be shared between an SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set eFuses accordingly.
Supported Speed Modes

6
docs/en/api-reference/peripherals/sdspi_host.rst
View File

@@ -4,7 +4,11 @@ SD SPI Host Driver
Overview
--------
The SD SPI host driver allows using the SPI2 (HSPI) or SPI3 (VSPI) controller for communication with SD cards. This driver's naming pattern was adopted from the :doc:`SDMMC Host <sdmmc_host>` driver due to their similarity. Likewise, the APIs of both drivers are also very similar.
The SD SPI host driver allows using the SPI2 (HSPI) or SPI3 (VSPI) controller for communication with SD cards.
.. only:: esp32
This driver's naming pattern was adopted from the :doc:`SDMMC Host <sdmmc_host>` driver due to their similarity. Likewise, the APIs of both drivers are also very similar.
The SD SPI host driver has the following modes:

37
docs/en/api-reference/peripherals/temp_sensor.rst
View File

@@ -4,30 +4,23 @@ ESP32-S2 Temperature Sensor
Overview
--------
.. only:: esp32
The ESP32-S2 has a built-in temperature sensor. The temperature sensor module contains an 8-bit Sigma-Delta ADC and a temperature offset DAC.
.. note::
The conversion relationship is the first columns of the table below. Among them, offset = 0 is the main measurement option, and other values are extended measurement options.
ESP32 does not have a built-in temperature sensor.
.. only:: esp32s2
The ESP32-S2 has a built-in temperature sensor. The temperature sensor module contains an 8-bit Sigma-Delta ADC and a temperature offset DAC.
The conversion relationship is the first columns of the table below. Among them, offset = 0 is the main measurement option, and other values are extended measurement options.
+--------+------------------------+------------------------+
| offset | measure range(Celsius) | measure error(Celsius) |
+========+========================+========================+
| -2 | 50 ~ 125 | < 3 |
+--------+------------------------+------------------------+
| -1 | 20 ~ 100 | < 2 |
+--------+------------------------+------------------------+
| 0 | -10 ~ 80 | < 1 |
+--------+------------------------+------------------------+
| 1 | -30 ~ 50 | < 2 |
+--------+------------------------+------------------------+
| 2 | -40 ~ 20 | < 3 |
+--------+------------------------+------------------------+
+--------+------------------------+------------------------+
| offset | measure range(Celsius) | measure error(Celsius) |
+========+========================+========================+
| -2 | 50 ~ 125 | < 3 |
+--------+------------------------+------------------------+
| -1 | 20 ~ 100 | < 2 |
+--------+------------------------+------------------------+
| 0 | -10 ~ 80 | < 1 |
+--------+------------------------+------------------------+
| 1 | -30 ~ 50 | < 2 |
+--------+------------------------+------------------------+
| 2 | -40 ~ 20 | < 3 |
+--------+------------------------+------------------------+
Application Example
-------------------

85
docs/en/api-reference/storage/sdmmc.rst
View File

@@ -16,74 +16,79 @@ SDMMC and SD SPI host drivers (:component:`driver/include/driver/sdmmc_host.h`)
For functions used to initialize and configure:
- SDMMC host, see :doc:`SDMMC Host API <../peripherals/sdmmc_host>`
- SD SPI host, see :doc:`SD SPI Host API <../peripherals/sdspi_host>`
.. only:: esp32
- SDMMC host, see :doc:`SDMMC Host API <../peripherals/sdmmc_host>`
- SD SPI host, see :doc:`SD SPI Host API <../peripherals/sdspi_host>`
The SDMMC protocol layer described in this document handles the specifics of the SD protocol, such as the card initialization and data transfer commands.
The SDMMC protocol layer described in this document handles the specifics of the SD protocol, such as the card initialization and data transfer commands.
The protocol layer works with the host via the :cpp:class:`sdmmc_host_t` structure. This structure contains pointers to various functions of the host.
The protocol layer works with the host via the :cpp:class:`sdmmc_host_t` structure. This structure contains pointers to various functions of the host.
Application Example
-------------------
Application Example
-------------------
An example which combines the SDMMC driver with the FATFS library is provided in the :example:`storage/sd_card` directory of ESP-IDF examples. This example initializes the card, then writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
An example which combines the SDMMC driver with the FATFS library is provided in the :example:`storage/sd_card` directory of ESP-IDF examples. This example initializes the card, then writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
Protocol layer API
------------------
Protocol layer API
------------------
The protocol layer is given the :cpp:class:`sdmmc_host_t` structure. This structure describes the SD/MMC host driver, lists its capabilities, and provides pointers to functions of the driver. The protocol layer stores card-specific information in the :cpp:class:`sdmmc_card_t` structure. When sending commands to the SD/MMC host driver, the protocol layer uses the :cpp:class:`sdmmc_command_t` structure to describe the command, arguments, expected return values, and data to transfer if there is any.
The protocol layer is given the :cpp:class:`sdmmc_host_t` structure. This structure describes the SD/MMC host driver, lists its capabilities, and provides pointers to functions of the driver. The protocol layer stores card-specific information in the :cpp:class:`sdmmc_card_t` structure. When sending commands to the SD/MMC host driver, the protocol layer uses the :cpp:class:`sdmmc_command_t` structure to describe the command, arguments, expected return values, and data to transfer if there is any.
Using API with SD memory cards
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Using API with SD memory cards
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. To initialize the host, call the host driver functions, e.g., :cpp:func:`sdmmc_host_init`, :cpp:func:`sdmmc_host_init_slot`.
2. To initialize the card, call :cpp:func:`sdmmc_card_init` and pass to it the parameters ``host`` - the host driver information, and ``card`` - a pointer to the structure :cpp:class:`sdmmc_card_t` which will be filled with information about the card when the function completes.
3. To read and write sectors of the card, use :cpp:func:`sdmmc_read_sectors` and :cpp:func:`sdmmc_write_sectors` respectively and pass to it the parameter ``card`` - a pointer to the card information structure.
4. If the card is not used anymore, call the host driver function - e.g., :cpp:func:`sdmmc_host_deinit` - to disable the host peripheral and free the resources allocated by the driver.
1. To initialize the host, call the host driver functions, e.g., :cpp:func:`sdmmc_host_init`, :cpp:func:`sdmmc_host_init_slot`.
2. To initialize the card, call :cpp:func:`sdmmc_card_init` and pass to it the parameters ``host`` - the host driver information, and ``card`` - a pointer to the structure :cpp:class:`sdmmc_card_t` which will be filled with information about the card when the function completes.
3. To read and write sectors of the card, use :cpp:func:`sdmmc_read_sectors` and :cpp:func:`sdmmc_write_sectors` respectively and pass to it the parameter ``card`` - a pointer to the card information structure.
4. If the card is not used anymore, call the host driver function - e.g., :cpp:func:`sdmmc_host_deinit` - to disable the host peripheral and free the resources allocated by the driver.
Using API with eMMC chips
^^^^^^^^^^^^^^^^^^^^^^^^^
Using API with eMMC chips
^^^^^^^^^^^^^^^^^^^^^^^^^
From the protocol layer's perspective, eMMC memory chips behave exactly like SD memory cards. Even though eMMCs are chips and do not have a card form factor, the terminology for SD cards can still be applied to eMMC due to the similarity of the protocol (`sdmmc_card_t`, `sdmmc_card_init`). Note that eMMC chips cannot be used over SPI, which makes them incompatible with the SD SPI host driver.
From the protocol layer's perspective, eMMC memory chips behave exactly like SD memory cards. Even though eMMCs are chips and do not have a card form factor, the terminology for SD cards can still be applied to eMMC due to the similarity of the protocol (`sdmmc_card_t`, `sdmmc_card_init`). Note that eMMC chips cannot be used over SPI, which makes them incompatible with the SD SPI host driver.
To initialize eMMC memory and perform read/write operations, follow the steps listed for SD cards in the previous section.
To initialize eMMC memory and perform read/write operations, follow the steps listed for SD cards in the previous section.
Using API with SDIO cards
^^^^^^^^^^^^^^^^^^^^^^^^^
Using API with SDIO cards
^^^^^^^^^^^^^^^^^^^^^^^^^
Initialization and the probing process is the same as with SD memory cards. The only difference is in data transfer commands in SDIO mode.
Initialization and the probing process is the same as with SD memory cards. The only difference is in data transfer commands in SDIO mode.
During the card initialization and probing, performed with :cpp:func:`sdmmc_card_init`, the driver only configures the following registers of the IO card:
During the card initialization and probing, performed with :cpp:func:`sdmmc_card_init`, the driver only configures the following registers of the IO card:
1. The IO portion of the card is reset by setting RES bit in the I/O Abort (0x06) register.
2. If 4-line mode is enabled in host and slot configuration, the driver attempts to set the Bus width field in the Bus Interface Control (0x07) register. If setting the filed is successful, which means that the slave supports 4-line mode, the host is also switched to 4-line mode.
3. If high-speed mode is enabled in the host configuration, the SHS bit is set in the High Speed (0x13) register.
1. The IO portion of the card is reset by setting RES bit in the I/O Abort (0x06) register.
2. If 4-line mode is enabled in host and slot configuration, the driver attempts to set the Bus width field in the Bus Interface Control (0x07) register. If setting the filed is successful, which means that the slave supports 4-line mode, the host is also switched to 4-line mode.
3. If high-speed mode is enabled in the host configuration, the SHS bit is set in the High Speed (0x13) register.
In particular, the driver does not set any bits in (1) I/O Enable and Int Enable registers, (2) I/O block sizes, etc. Applications can set them by calling :cpp:func:`sdmmc_io_write_byte`.
In particular, the driver does not set any bits in (1) I/O Enable and Int Enable registers, (2) I/O block sizes, etc. Applications can set them by calling :cpp:func:`sdmmc_io_write_byte`.
For card configuration and data transfer, choose the pair of functions relevant to your case from the table below.
For card configuration and data transfer, choose the pair of functions relevant to your case from the table below.
========================================================================= ================================= =================================
Action Read Function Write Function
========================================================================= ================================= =================================
Read and write a single byte using IO_RW_DIRECT (CMD52) :cpp:func:`sdmmc_io_read_byte` :cpp:func:`sdmmc_io_write_byte`
Read and write multiple bytes using IO_RW_EXTENDED (CMD53) in byte mode :cpp:func:`sdmmc_io_read_bytes` :cpp:func:`sdmmc_io_write_bytes`
Read and write blocks of data using IO_RW_EXTENDED (CMD53) in block mode :cpp:func:`sdmmc_io_read_blocks` :cpp:func:`sdmmc_io_write_blocks`
========================================================================= ================================= =================================
========================================================================= ================================= =================================
Action Read Function Write Function
========================================================================= ================================= =================================
Read and write a single byte using IO_RW_DIRECT (CMD52) :cpp:func:`sdmmc_io_read_byte` :cpp:func:`sdmmc_io_write_byte`
Read and write multiple bytes using IO_RW_EXTENDED (CMD53) in byte mode :cpp:func:`sdmmc_io_read_bytes` :cpp:func:`sdmmc_io_write_bytes`
Read and write blocks of data using IO_RW_EXTENDED (CMD53) in block mode :cpp:func:`sdmmc_io_read_blocks` :cpp:func:`sdmmc_io_write_blocks`
========================================================================= ================================= =================================
SDIO interrupts can be enabled by the application using the function :cpp:func:`sdmmc_io_enable_int`. When using SDIO in 1-line mode, the D1 line also needs to be connected to use SDIO interrupts.
SDIO interrupts can be enabled by the application using the function :cpp:func:`sdmmc_io_enable_int`. When using SDIO in 1-line mode, the D1 line also needs to be connected to use SDIO interrupts.
If you want the application to wait until the SDIO interrupt occurs, use :cpp:func:`sdmmc_io_wait_int`.
If you want the application to wait until the SDIO interrupt occurs, use :cpp:func:`sdmmc_io_wait_int`.
There is a component ESSL (ESP Serial Slave Link) to use if you are communicating with an ESP32
SDIO slave. See :doc:`/api-reference/protocols/esp_serial_slave_link` and example :example:`peripherals/sdio/host`.
.. only:: esp32
There is a component ESSL (ESP Serial Slave Link) to use if you are communicating with an ESP32
SDIO slave. See :doc:`/api-reference/protocols/esp_serial_slave_link` and example :example:`peripherals/sdio/host`.
Combo (memory + IO) cards
^^^^^^^^^^^^^^^^^^^^^^^^^

6
docs/en/api-reference/system/system_time.rst
View File

@@ -19,7 +19,7 @@ The settings for the system time source are as follows:
- High-resolution timer
- None
It is recommended to stick to the default setting which provides maximum accuracy. If you want to choose a different timer, configure :ref:`CONFIG_ESP32_TIME_SYSCALL` in project configuration.
It is recommended to stick to the default setting which provides maximum accuracy. If you want to choose a different timer, configure :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_TIME_SYSCALL` in project configuration.
RTC Clock Source
@@ -35,7 +35,7 @@ The RTC timer has the following clock sources:
- ``Internal 8.5MHz oscillator, divided by 256 (~33kHz)``. Provides better frequency stability than the ``internal 150kHz RC oscillator`` at the expense of higher (by 5 uA) deep sleep current consumption. It also does not require external components.
The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set :ref:`CONFIG_ESP32_RTC_CLK_SRC` in project configuration.
The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_RTC_CLK_SRC` in project configuration.
More details on wiring requirements for the ``External 32kHz crystal`` and ``External 32kHz oscillator at 32K_XP pin`` sources can be found in Section 2.1.4 *Crystal Oscillator* of `Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf#page=10>`_.
@@ -130,4 +130,4 @@ Once these steps are completed, call the standard C library function ``localtime
API Reference
-------------
.. include:: /_build/inc/sntp.inc
.. include-build-file:: inc/sntp.inc