Crash_Override
/
OVMS3-idf
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: Generate Doxygen directives for API documentation 

This is to resolve issue reported in https://github.com/espressif/esp-idf/issues/130.
This commit is contained in:
krzychb 2017-05-02 10:36:01 +02:00
parent a38cecefa7
commit 30edcca1fb
62 changed files with 771 additions and 2540 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -26,6 +26,7 @@ examples/**/build
#Doc build artifacts
docs/_build/
docs/doxygen-warning-log.txt
docs/sphinx-warning-log.txt
docs/xml/
docs/man/

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

@ -28,7 +28,7 @@ typedef enum {
DAC_CHANNEL_MAX,
} dac_channel_t;
/** @cond */
/**
* @brief Set DAC output voltage.
*
@ -45,6 +45,7 @@ typedef enum {
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t dac_out_voltage(dac_channel_t channel, uint8_t dac_value) __attribute__ ((deprecated));
/** @endcond */
/**
* @brief Set DAC output voltage.

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

@ -31,7 +31,13 @@ extern "C" {
#define GPIO_SEL_0 (BIT(0)) /*!< Pin 0 selected */
#define GPIO_SEL_1 (BIT(1)) /*!< Pin 1 selected */
#define GPIO_SEL_2 (BIT(2)) /*!< Pin 2 selected */
#define GPIO_SEL_2 (BIT(2)) /*!< Pin 2 selected
@note There are more macros
like that up to pin 39,
excluding pins 20, 24 and 28..31.
They are not shown here
to reduce redundant information. */
/** @cond */
#define GPIO_SEL_3 (BIT(3)) /*!< Pin 3 selected */
#define GPIO_SEL_4 (BIT(4)) /*!< Pin 4 selected */
#define GPIO_SEL_5 (BIT(5)) /*!< Pin 5 selected */
@ -114,14 +120,21 @@ extern "C" {
#define GPIO_MODE_DEF_OD (BIT2)
#define GPIO_PIN_COUNT 40
/** @endcond */
extern const uint32_t GPIO_PIN_MUX_REG[GPIO_PIN_COUNT];
#define GPIO_IS_VALID_GPIO(gpio_num) ((gpio_num < GPIO_PIN_COUNT && GPIO_PIN_MUX_REG[gpio_num] != 0)) //to decide whether it is a valid GPIO number
#define GPIO_IS_VALID_OUTPUT_GPIO(gpio_num) ((GPIO_IS_VALID_GPIO(gpio_num)) && (gpio_num < 34)) //to decide whether it can be a valid GPIO number of output mode
#define GPIO_IS_VALID_GPIO(gpio_num) ((gpio_num < GPIO_PIN_COUNT && GPIO_PIN_MUX_REG[gpio_num] != 0)) /*!< Check whether it is a valid GPIO number */
#define GPIO_IS_VALID_OUTPUT_GPIO(gpio_num) ((GPIO_IS_VALID_GPIO(gpio_num)) && (gpio_num < 34)) /*!< Check whether it can be a valid GPIO number of output mode */
typedef enum {
GPIO_NUM_0 = 0, /*!< GPIO0, input and output */
GPIO_NUM_1 = 1, /*!< GPIO1, input and output */
GPIO_NUM_2 = 2, /*!< GPIO2, input and output */
GPIO_NUM_2 = 2, /*!< GPIO2, input and output
@note There are more enumerations like that
up to GPIO39, excluding GPIO20, GPIO24 and GPIO28..31.
They are not shown here to reduce redundant information.
@note GPIO34..29 are input mode only. */
/** @cond */
GPIO_NUM_3 = 3, /*!< GPIO3, input and output */
GPIO_NUM_4 = 4, /*!< GPIO4, input and output */
GPIO_NUM_5 = 5, /*!< GPIO5, input and output */
@ -157,6 +170,7 @@ typedef enum {
GPIO_NUM_38 = 38, /*!< GPIO38, input mode only */
GPIO_NUM_39 = 39, /*!< GPIO39, input mode only */
GPIO_NUM_MAX = 40,
/** @endcond */
} gpio_num_t;
typedef enum {

4
components/driver/include/driver/spi_common.h
View File

@ -48,6 +48,8 @@ typedef enum {
* You can use this structure to specify the GPIO pins of the bus. Normally, the driver will use the
* GPIO matrix to route the signals. An exception is made when all signals either can be routed through
* the IO_MUX or are -1. In that case, the IO_MUX is used, allowing for >40MHz speeds.
*
* @note 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.
*/
typedef struct {
int mosi_io_num; ///< GPIO pin for Master Out Slave In (=spi_d) signal, or -1 if not used.
@ -230,4 +232,4 @@ void spicommon_dmaworkaround_transfer_active(int dmachan);
}
#endif
#endif
#endif

8
components/ethernet/include/eth_phy/phy.h
View File

@ -20,13 +20,13 @@ extern "C" {
#include "esp_eth.h"
/* Common PHY-management functions.
/** Common PHY-management functions.
These are not enough to drive any particular Ethernet PHY, but they provide a common configuration structure and
management functions.
*/
/* Configure fixed pins for RMII data interface.
/** Configure fixed pins for RMII data interface.
This configures GPIOs 0, 19, 22, 25, 26, 27 for use with RMII
data interface. These pins cannot be changed, and must be wired to
@ -38,7 +38,7 @@ extern "C" {
*/
void phy_rmii_configure_data_interface_pins(void);
/* Configure variable pins for SMI (MDIO) ethernet functions.
/** Configure variable pins for SMI (MDIO) ethernet functions.
Calling this function along with mii_configure_default_pins() will
fully configure the GPIOs for the ethernet PHY.
@ -46,7 +46,7 @@ void phy_rmii_configure_data_interface_pins(void);
void phy_rmii_smi_configure_pins(uint8_t mdc_gpio, uint8_t mdio_gpio);
/* Enable flow control in standard PHY MII register.
/** Enable flow control in standard PHY MII register.
*/
void phy_mii_enable_flow_ctrl(void);

14
components/ethernet/include/eth_phy/phy_lan8720.h
View File

@ -21,26 +21,26 @@ extern "C" {
#include "phy.h"
/* @brief Dump all LAN8720 PHY SMI configuration registers
/** @brief Dump all LAN8720 PHY SMI configuration registers
*
* @note These registers are dumped at 'debug' level, so output
* may not be visible depending on default log levels.
*/
void phy_lan8720_dump_registers();
/* @brief Default LAN8720 phy_check_init function.
/** @brief Default LAN8720 phy_check_init function.
*/
void phy_lan8720_check_phy_init(void);
/* @brief Default LAN8720 phy_get_speed_mode function.
/** @brief Default LAN8720 phy_get_speed_mode function.
*/
eth_speed_mode_t phy_lan8720_get_speed_mode(void);
/* @brief Default LAN8720 phy_get_duplex_mode function.
/** @brief Default LAN8720 phy_get_duplex_mode function.
*/
eth_duplex_mode_t phy_lan8720_get_duplex_mode(void);
/* @brief Default LAN8720 phy_power_enable function.
/** @brief Default LAN8720 phy_power_enable function.
*
* @note This function may need to be replaced with a custom function
* if the PHY has a GPIO to enable power or start a clock.
@ -49,11 +49,11 @@ eth_duplex_mode_t phy_lan8720_get_duplex_mode(void);
*/
void phy_lan8720_power_enable(bool);
/* @brief Default LAN8720 phy_init function.
/** @brief Default LAN8720 phy_init function.
*/
void phy_lan8720_init(void);
/* @brief Default LAN8720 PHY configuration
/** @brief Default LAN8720 PHY configuration
*
* This configuration is not suitable for use as-is, it will need
* to be modified for your particular PHY hardware setup.

14
components/ethernet/include/eth_phy/phy_tlk110.h
View File

@ -20,26 +20,26 @@ extern "C" {
#include "phy.h"
/* @brief Dump all TLK110 PHY SMI configuration registers
/** @brief Dump all TLK110 PHY SMI configuration registers
*
* @note These registers are dumped at 'debug' level, so output
* may not be visible depending on default log levels.
*/
void phy_tlk110_dump_registers();
/* @brief Default TLK110 phy_check_init function.
/** @brief Default TLK110 phy_check_init function.
*/
void phy_tlk110_check_phy_init(void);
/* @brief Default TLK110 phy_get_speed_mode function.
/** @brief Default TLK110 phy_get_speed_mode function.
*/
eth_speed_mode_t phy_tlk110_get_speed_mode(void);
/* @brief Default TLK110 phy_get_duplex_mode function.
/** @brief Default TLK110 phy_get_duplex_mode function.
*/
eth_duplex_mode_t phy_tlk110_get_duplex_mode(void);
/* @brief Default TLK110 phy_power_enable function.
/** @brief Default TLK110 phy_power_enable function.
*
* @note This function may need to be replaced with a custom function
* if the PHY has a GPIO to enable power or start a clock.
@ -48,11 +48,11 @@ eth_duplex_mode_t phy_tlk110_get_duplex_mode(void);
*/
void phy_tlk110_power_enable(bool);
/* @brief Default TLK110 phy_init function.
/** @brief Default TLK110 phy_init function.
*/
void phy_tlk110_init(void);
/* @brief Default TLK110 PHY configuration
/** @brief Default TLK110 PHY configuration
*
* This configuration is not suitable for use as-is, it will need
* to be modified for your particular PHY hardware setup.

20
components/vfs/README.rst
View File

@ -13,7 +13,13 @@ For example, one can register a FAT filesystem driver with ``/fat`` prefix, and
FS registration
---------------
To register an FS driver, application needs to define in instance of esp_vfs_t structure and populate it with function pointers to FS APIs::
To register an FS driver, application needs to define in instance of esp_vfs_t structure and populate it with function pointers to FS APIs:
.. highlight:: c
::
esp_vfs_t myfs = {
.fd_offset = 0,
@ -97,6 +103,8 @@ Lower ``CONFIG_MAX_FD_BITS`` bits are used to store zero-based file descriptor.
When VFS component receives a call from newlib which has a file descriptor, this file descriptor is translated back to the FS-specific file descriptor. First, higher bits of FD are used to identify the FS. Then ``fd_offset`` field of the FS is added to the lower ``CONFIG_MAX_FD_BITS`` bits of the fd, and resulting FD is passed to the FS driver.
.. highlight:: none
::
FD as seen by newlib FD as seen by FS driver
@ -132,15 +140,19 @@ Note that while writing to ``stdout`` or ``stderr`` will block until all charact
Standard streams and FreeRTOS tasks
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``FILE`` objects for ``stdin``, ``stdout``, and ``stderr`` are shared between all FreeRTOS tasks, but the pointers to these objects are are stored in per-task ``struct _reent``. The following code::
``FILE`` objects for ``stdin``, ``stdout``, and ``stderr`` are shared between all FreeRTOS tasks, but the pointers to these objects are are stored in per-task ``struct _reent``. The following code:
.. highlight:: c
::
fprintf(stderr, "42\n");
actually is translated to to this (by the preprocessor):
actually is translated to to this (by the preprocessor)::
fprintf(__getreent()->_stderr, "42\n");
where the ``__getreent()`` function returns a per-task pointer to ``struct _reent`` (:component_file:`newlib/include/sys/reent.h#L370-L417>`). This structure is allocated on the TCB of each task. When a task is initialized, ``_stdin``, ``_stdout`` and ``_stderr`` members of ``struct _reent`` are set to the values of ``_stdin``, ``_stdout`` and ``_stderr`` of ``_GLOBAL_REENT`` (i.e. the structure which is used before FreeRTOS is started).
where the ``__getreent()`` function returns a per-task pointer to ``struct _reent`` (:component_file:`newlib/include/sys/reent.h#L370-L417`). This structure is allocated on the TCB of each task. When a task is initialized, ``_stdin``, ``_stdout`` and ``_stderr`` members of ``struct _reent`` are set to the values of ``_stdin``, ``_stdout`` and ``_stderr`` of ``_GLOBAL_REENT`` (i.e. the structure which is used before FreeRTOS is started).
Such a design has the following consequences:

159
docs/Doxyfile Executable file → Normal file
View File

@ -15,51 +15,145 @@
PROJECT_NAME = "ESP32 Programming Guide"
INPUT = ../components/esp32/include/esp_wifi.h \
../components/driver/include/driver \
../components/bt/include \
../components/bt/bluedroid/api/include \
../components/nvs_flash/include \
../components/log/include \
../components/vfs/include \
../components/spi_flash/include \
../components/esp32/include/esp_int_wdt.h \
../components/esp32/include/esp_task_wdt.h \
../components/app_update/include/esp_ota_ops.h \
../components/ethernet/include/esp_eth.h \
../components/ulp/include/esp32/ulp.h \
../components/esp32/include/esp_intr_alloc.h \
../components/esp32/include/esp_heap_alloc_caps.h \
../components/freertos/include/freertos/heap_regions.h \
../components/esp32/include/esp_smartconfig.h \
../components/esp32/include/esp_deep_sleep.h \
../components/sdmmc/include/sdmmc_cmd.h \
../components/fatfs/src/esp_vfs_fat.h \
../components/fatfs/src/diskio.h \
../components/esp32/include/esp_core_dump.h \
../components/mdns/include/mdns.h \
../components/bootloader_support/include/esp_flash_encrypt.h \
../components/wear_levelling/include/wear_levelling.h
## The 'INPUT' statement below is used as input by script 'gen-df-input.py'
## to automatically generate API reference list files heder_file.inc
## These files are placed in '_inc' directory
## and used to include in API reference documentation
INPUT = \
##
## Wi-Fi - API Reference
##
../components/esp32/include/esp_wifi.h \
../components/esp32/include/esp_smartconfig.h \
## Bluetooth - API Reference
## Controller && VHCI
../components/bt/include/bt.h \
## Bluetooth COMMON
## Issue with __attribute__
../components/bt/bluedroid/api/include/esp_bt_defs.h \
../components/bt/bluedroid/api/include/esp_bt_main.h \
../components/bt/bluedroid/api/include/esp_bt_device.h \
## Bluetooth LE
../components/bt/bluedroid/api/include/esp_gap_ble_api.h \
## Issue with __attribute__
../components/bt/bluedroid/api/include/esp_gatt_defs.h \
../components/bt/bluedroid/api/include/esp_gatts_api.h \
../components/bt/bluedroid/api/include/esp_gattc_api.h \
../components/bt/bluedroid/api/include/esp_blufi_api.h \
## Bluetooth Classic
../components/bt/bluedroid/api/include/esp_gap_bt_api.h \
## Issue with __attribute__
../components/bt/bluedroid/api/include/esp_a2dp_api.h \
../components/bt/bluedroid/api/include/esp_avrc_api.h \
##
## Ethernet - API Reference
##
../components/ethernet/include/esp_eth.h \
../components/ethernet/include/eth_phy/phy.h \
../components/ethernet/include/eth_phy/phy_tlk110.h \
../components/ethernet/include/eth_phy/phy_lan8720.h \
##
## Peripherals - API Reference
##
../components/driver/include/driver/adc.h \
../components/driver/include/driver/dac.h \
../components/driver/include/driver/gpio.h \
../components/driver/include/driver/rtc_io.h \
../components/driver/include/driver/i2c.h \
../components/driver/include/driver/i2s.h \
../components/driver/include/driver/ledc.h \
../components/driver/include/driver/mcpwm.h \
../components/driver/include/driver/pcnt.h \
../components/driver/include/driver/rmt.h \
../components/driver/include/driver/sigmadelta.h \
../components/driver/include/driver/spi_common.h \
../components/driver/include/driver/spi_master.h \
../components/driver/include/driver/spi_slave.h \
../components/driver/include/driver/timer.h \
../components/driver/include/driver/uart.h \
##
## Protocols - API Reference
##
../components/mdns/include/mdns.h \
##
## Storage - API Reference
##
## SPI Flash and Partition APIs
../components/spi_flash/include/esp_spi_flash.h \
../components/spi_flash/include/esp_partition.h \
../components/bootloader_support/include/esp_flash_encrypt.h \
## SD/MMC Card Host
## NOTE: for three lines below header_file.inc is not used
../components/sdmmc/include/sdmmc_cmd.h \
../components/driver/include/driver/sdmmc_host.h \
../components/driver/include/driver/sdmmc_types.h \
## Non-Volatile Storage
../components/nvs_flash/include/nvs.h \
../components/nvs_flash/include/nvs_flash.h \
## Virtual Filesystem
../components/vfs/include/esp_vfs.h \
../components/vfs/include/esp_vfs_dev.h \
## FAT Filesystem
## NOTE: for two lines below header_file.inc is not used
../components/fatfs/src/esp_vfs_fat.h \
../components/fatfs/src/diskio.h \
## Wear Levelling
../components/wear_levelling/include/wear_levelling.h \
##
## System - API Reference
##
## Memory Allocation #
../components/esp32/include/esp_heap_alloc_caps.h \
../components/freertos/include/freertos/heap_regions.h \
## Interrupt Allocation
../components/esp32/include/esp_intr_alloc.h \
## Watchdogs
## NOTE: for two lines below header_file.inc is not used
../components/esp32/include/esp_int_wdt.h \
../components/esp32/include/esp_task_wdt.h \
## Over The Air Updates (OTA)
../components/app_update/include/esp_ota_ops.h \
## Deep Sleep
## NOTE: for line below header_file.inc is not used
../components/esp32/include/esp_deep_sleep.h \
## Logging
../components/log/include/esp_log.h \
## Base MAC address
## NOTE: for line below header_file.inc is not used
../components/esp32/include/esp_system.h \
##
## ULP Coprocessor - API Guides
##
## NOTE: for line below header_file.inc is not used
../components/ulp/include/esp32/ulp.h
## Get warnings for functions that have no documentation for their parameters or return value
##
WARN_NO_PARAMDOC = YES
## Enable preprocessing and remove __attribute__(...) expressions from the INPUT files
##
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = __attribute__(x)=
## Do not complain about not having dot
##
HAVE_DOT = NO
## Generate XML that is required for Breathe
##
GENERATE_XML = YES
XML_OUTPUT = xml
GENERATE_XML = YES
XML_OUTPUT = xml
GENERATE_HTML = NO
HAVE_DOT = NO
GENERATE_LATEX = NO
GENERATE_MAN = YES
GENERATE_RTF = NO
GENERATE_HTML = NO
HAVE_DOT = NO
GENERATE_LATEX = NO
GENERATE_MAN = YES
GENERATE_RTF = NO
## Skip distracting progress messages
##
@ -67,3 +161,4 @@ QUIET = YES
## Log warnings in a file for further review
##
WARN_LOGFILE = "doxygen-warning-log.txt"

8
docs/Makefile
View File

@ -15,7 +15,7 @@ endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -w sphinx-warning-log.txt .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
@ -170,14 +170,14 @@ gh-linkcheck:
echo "WARNINIG: Some .rst files contain hardcoded Github links."; \
echo "Please check above output and replace links with one of the following:"; \
echo "- :idf:\`dir\` - points to directory inside ESP-IDF"; \
echo "- :idf_blob:\`file\` - points to file inside ESP-IDF"; \
echo "- :idf_file:\`file\` - points to file inside ESP-IDF"; \
echo "- :idf_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \
echo "- :component:\`dir\` - points to directory inside ESP-IDF components dir"; \
echo "- :component_blob:\`file\` - points to file inside ESP-IDF components dir"; \
echo "- :component_file:\`file\` - points to file inside ESP-IDF components dir"; \
echo "- :component_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \
echo " components dir"; \
echo "- :example:\`dir\` - points to directory inside ESP-IDF examples dir"; \
echo "- :example_blob:\`file\` - points to file inside ESP-IDF examples dir"; \
echo "- :example_file:\`file\` - points to file inside ESP-IDF examples dir"; \
echo "- :example_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \
echo " examples dir"; \
echo "These link types will point to the correct GitHub version automatically"; \

BIN
docs/_static/about-doc.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 67 KiB

After

Width:  |  Height:  |  Size: 106 KiB

14
docs/api-guides/build-system.rst
View File

@ -508,20 +508,20 @@ To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment va
Save flash arguments
-------------------------
--------------------
There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. For flash arguments, we can add the following code to application project makefile::
There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. For flash arguments, we can add the following code to application project makefile:
::
print_flash_cmd:
echo $(ESPTOOL_WRITE_FLASH_OPTIONS) $(ESPTOOL_ALL_FLASH_ARGS) | sed -e 's:'$(PWD)/build/'::g'
the original ESPTOOL_ALL_FLASH_ARGS are absolute file name. Usually we want to save relative file name so we can move the bin folder to somewhere else. For this case we can use ``sed`` to convert to relative file name, like what we did in the example above.
When running ``make print_flash_cmd``, it will print the flash arguments:
::
When running ``make print_flash_cmd``, it will print the flash arguments::
--flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
Then use flash arguments as the arguemnts for esptool write_flash arguments:
::
Then use flash arguments as the arguemnts for esptool write_flash arguments::
python esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin

44
docs/api-reference/bluetooth/controller_vhci.rst
View File

@ -11,49 +11,11 @@ Overview
Application Example
-------------------
Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following example:
Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following application:
:example:`bluetooth/ble_adv`
This is a BLE advertising demo with virtual HCI interface. Send Reset/ADV_PARAM/ADV_DATA/ADV_ENABLE HCI command for BLE advertising.
* This is a BLE advertising demo with virtual HCI interface. Send Reset/ADV_PARAM/ADV_DATA/ADV_ENABLE HCI command for BLE advertising - :example:`bluetooth/ble_adv`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/include/bt.h`
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: esp_vhci_host_callback_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_bt_mode_t
Structures
^^^^^^^^^^
.. doxygenstruct:: esp_bt_controller_config_t
:members:
.. doxygenstruct:: esp_vhci_host_callback
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: esp_bt_controller_init
.. doxygenfunction:: esp_bt_controller_deinit
.. doxygenfunction:: esp_bt_controller_enable
.. doxygenfunction:: esp_bt_controller_disable
.. doxygenfunction:: esp_bt_controller_get_status
.. doxygenfunction:: esp_vhci_host_check_send_available
.. doxygenfunction:: esp_vhci_host_send_packet
.. doxygenfunction:: esp_vhci_host_register_callback
.. include:: /_build/inc/bt.inc

66
docs/api-reference/bluetooth/esp_a2dp.rst
View File

@ -11,72 +11,12 @@ Overview
Application Example
-------------------
Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following examples:
:example:`bluetooth/a2dp_sink`
This is a A2DP sink client demo. This demo can be discovered and connected by A2DP source device and receive the audio stream from remote device.
Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following application:
* This is a A2DP sink client demo. This demo can be discovered and connected by A2DP source device and receive the audio stream from remote device - :example:`bluetooth/a2dp_sink`
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/bluedroid/api/include/esp_a2dp_api.h`
Macros
^^^^^^
.. doxygendefine:: ESP_A2D_MCT_SBC
.. doxygendefine:: ESP_A2D_MCT_M12
.. doxygendefine:: ESP_A2D_MCT_M24
.. doxygendefine:: ESP_A2D_MCT_ATRAC
.. doxygendefine:: ESP_A2D_MCT_NON_A2DP
.. doxygendefine:: ESP_A2D_CIE_LEN_SBC
.. doxygendefine:: ESP_A2D_CIE_LEN_M12
.. doxygendefine:: ESP_A2D_CIE_LEN_M24
.. doxygendefine:: ESP_A2D_CIE_LEN_ATRAC
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: esp_a2d_mct_t
.. doxygentypedef:: esp_a2d_cb_t
.. doxygentypedef:: esp_a2d_data_cb_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_a2d_connection_state_t
.. doxygenenum:: esp_a2d_disc_rsn_t
.. doxygenenum:: esp_a2d_audio_state_t
.. doxygenenum:: esp_a2d_cb_event_t
Structures
^^^^^^^^^^
.. doxygenstruct:: esp_a2d_cb_param_t
:members:
.. doxygenstruct:: esp_a2d_cb_param_t::a2d_conn_stat_param
:members:
.. doxygenstruct:: esp_a2d_cb_param_t::a2d_audio_stat_param
:members:
.. doxygenstruct:: esp_a2d_cb_param_t::a2d_audio_cfg_param
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: esp_a2d_register_callback
.. doxygenfunction:: esp_a2d_register_data_callback
.. doxygenfunction:: esp_a2d_sink_init
.. doxygenfunction:: esp_a2d_sink_deinit
.. doxygenfunction:: esp_a2d_sink_connect
.. doxygenfunction:: esp_a2d_sink_disconnect
.. include:: /_build/inc/esp_a2dp_api.inc

44
docs/api-reference/bluetooth/esp_avrc.rst
View File

@ -15,51 +15,9 @@ Application Example
.. _Instructions: ../template.html
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/bluedroid/api/include/esp_avrc_api.h`
.. include:: /_build/inc/esp_avrc_api.inc
Macros
^^^^^^
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: esp_avrc_ct_cb_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_avrc_features_t
.. doxygenenum:: esp_avrc_pt_cmd_t
.. doxygenenum:: esp_avrc_pt_cmd_state_t
.. doxygenenum:: esp_avrc_ct_cb_event_t
Structures
^^^^^^^^^^
.. doxygenstruct:: esp_avrc_ct_cb_param_t
:members:
.. doxygenstruct:: esp_avrc_ct_cb_param_t::avrc_ct_conn_stat_param
:members:
.. doxygenstruct:: esp_avrc_ct_cb_param_t::avrc_ct_psth_rsp_param
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: esp_avrc_ct_register_callback
.. doxygenfunction:: esp_avrc_ct_init
.. doxygenfunction:: esp_avrc_ct_deinit
.. doxygenfunction:: esp_avrc_ct_send_passthrough_cmd

116
docs/api-reference/bluetooth/esp_blufi.rst
View File

@ -4,126 +4,20 @@ BLUFI API
Overview
--------
BLUFI is a profile based GATT to config ESP32 WIFI to connect/disconnect AP or setup a softap and etc.
Use should concern these things:
Use should concern these things:
1. The event sent from profile. Then you need to do something as the event indicate.
2. Security reference. You can write your own Security functions such as symmetrical encryption/decryption and checksum functions. Even you can define the "Key Exchange/Negotiation" procedure.
Application Example
-------------------
Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following example:
:example:`bluetooth/blufi`
This is a BLUFI demo. This demo can set ESP32's wifi to softap/station/softap&station mode and config wifi connections.
Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following application:
* This is a BLUFI demo. This demo can set ESP32's wifi to softap/station/softap&station mode and config wifi connections - :example:`bluetooth/blufi`
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/bluedroid/api/include/esp_blufi_api.h`
Macros
^^^^^^
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: esp_blufi_event_cb_t
.. doxygentypedef:: esp_blufi_negotiate_data_handler_t
.. doxygentypedef:: esp_blufi_encrypt_func_t
.. doxygentypedef:: esp_blufi_decrypt_func_t
.. doxygentypedef:: esp_blufi_checksum_func_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_blufi_cb_event_t
.. doxygenenum:: esp_blufi_sta_conn_state_t
.. doxygenenum:: esp_blufi_init_state_t
.. doxygenenum:: esp_blufi_deinit_state_t
Structures
^^^^^^^^^^
.. doxygenstruct:: esp_blufi_extra_info_t
:members:
.. doxygenstruct:: esp_blufi_cb_param_t
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_init_finish_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_deinit_finish_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_set_wifi_mode_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_connect_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_disconnect_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_sta_bssid_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_sta_ssid_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_sta_passwd_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_softap_ssid_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_softap_passwd_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_softap_max_conn_num_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_softap_auth_mode_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_softap_channel_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_username_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_ca_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_client_cert_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_server_cert_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_client_pkey_evt_param
:members:
.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_server_pkey_evt_param
:members:
.. doxygenstruct:: esp_blufi_callbacks_t
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: esp_blufi_register_callbacks
.. doxygenfunction:: esp_blufi_profile_init
.. doxygenfunction:: esp_blufi_profile_deinit
.. doxygenfunction:: esp_blufi_send_wifi_conn_report
.. doxygenfunction:: esp_blufi_get_version
.. doxygenfunction:: esp_blufi_close
.. include:: /_build/inc/esp_blufi_api.inc

46
docs/api-reference/bluetooth/esp_bt_defs.rst
View File

@ -17,49 +17,5 @@ Application Example
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/bluedroid/api/include/esp_bt_defs.h`
Macros
^^^^^^
.. doxygendefine:: ESP_BT_OCTET16_LEN
.. doxygendefine:: ESP_BT_OCTET8_LEN
.. doxygendefine:: ESP_DEFAULT_GATT_IF
.. doxygendefine:: ESP_BLE_CONN_PARAM_UNDEF
.. doxygendefine:: ESP_BLE_IS_VALID_PARAM
.. doxygendefine:: ESP_UUID_LEN_16
.. doxygendefine:: ESP_UUID_LEN_32
.. doxygendefine:: ESP_UUID_LEN_128
.. doxygendefine:: ESP_BD_ADDR_LEN
.. doxygendefine:: ESP_APP_ID_MIN
.. doxygendefine:: ESP_APP_ID_MAX
.. doxygendefine:: ESP_BD_ADDR_STR
.. doxygendefine:: ESP_BD_ADDR_HEX
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: esp_bt_octet16_t
.. doxygentypedef:: esp_bt_octet8_t
.. doxygentypedef:: esp_bd_addr_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_bt_status_t
.. doxygenenum:: esp_bt_dev_type_t
.. doxygenenum:: esp_bd_addr_type_t
.. doxygenenum:: esp_ble_addr_type_t
Structures
^^^^^^^^^^
Functions
^^^^^^^^^
.. include:: /_build/inc/esp_bt_defs.inc

30
docs/api-reference/bluetooth/esp_bt_device.rst
View File

@ -15,35 +15,7 @@ Application Example
.. _Instructions: ../template.html
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/bluedroid/api/include/esp_bt_device.h`
Macros
^^^^^^
Type Definitions
^^^^^^^^^^^^^^^^
Enumerations
^^^^^^^^^^^^
Structures
^^^^^^^^^^
Functions
^^^^^^^^^
.. doxygenfunction:: esp_bt_dev_get_address
.. doxygenfunction:: esp_bt_dev_set_device_name
.. include:: /_build/inc/esp_bt_device.inc

32
docs/api-reference/bluetooth/esp_bt_main.rst
View File

@ -17,36 +17,6 @@ Application Example
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/bluedroid/api/include/esp_bt_main.h`
.. include:: /_build/inc/esp_bt_main.inc
Macros
^^^^^^
Type Definitions
^^^^^^^^^^^^^^^^
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_bluedroid_status_t
Structures
^^^^^^^^^^
Functions
^^^^^^^^^
.. doxygenfunction:: esp_bluedroid_get_status
.. doxygenfunction:: esp_bluedroid_enable
.. doxygenfunction:: esp_bluedroid_disable
.. doxygenfunction:: esp_bluedroid_init
.. doxygenfunction:: esp_bluedroid_deinit

172
docs/api-reference/bluetooth/esp_gap_ble.rst
View File

@ -11,178 +11,12 @@ Overview
Application Example
-------------------
Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following examples:
Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following applications:
:example:`bluetooth/gatt_server`, :example:`bluetooth/gatt_client`
The two demos use different GAP APIs, such like advertising, scan, set device name and others.
* The two demos use different GAP APIs, such like advertising, scan, set device name and others - :example:`bluetooth/gatt_server`, :example:`bluetooth/gatt_client`
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/bluedroid/api/include/esp_gap_ble_api.h`
Macros
^^^^^^
.. doxygendefine:: ESP_BLE_ADV_FLAG_LIMIT_DISC
.. doxygendefine:: ESP_BLE_ADV_FLAG_GEN_DISC
.. doxygendefine:: ESP_BLE_ADV_FLAG_BREDR_NOT_SPT
.. doxygendefine:: ESP_BLE_ADV_FLAG_DMT_CONTROLLER_SPT
.. doxygendefine:: ESP_BLE_ADV_FLAG_DMT_HOST_SPT
.. doxygendefine:: ESP_BLE_ADV_FLAG_NON_LIMIT_DISC
.. doxygendefine:: ESP_LE_KEY_NONE
.. doxygendefine:: ESP_LE_KEY_PENC
.. doxygendefine:: ESP_LE_KEY_PID
.. doxygendefine:: ESP_LE_KEY_PCSRK
.. doxygendefine:: ESP_LE_KEY_PLK
.. doxygendefine:: ESP_LE_KEY_LLK
.. doxygendefine:: ESP_LE_KEY_LENC
.. doxygendefine:: ESP_LE_KEY_LID
.. doxygendefine:: ESP_LE_KEY_LCSRK
.. doxygendefine:: ESP_LE_AUTH_NO_BOND
.. doxygendefine:: ESP_LE_AUTH_BOND
.. doxygendefine:: ESP_LE_AUTH_REQ_MITM
.. doxygendefine:: ESP_LE_AUTH_REQ_SC_ONLY
.. doxygendefine:: ESP_LE_AUTH_REQ_SC_BOND
.. doxygendefine:: ESP_LE_AUTH_REQ_SC_MITM
.. doxygendefine:: ESP_LE_AUTH_REQ_SC_MITM_BOND
.. doxygendefine:: ESP_IO_CAP_OUT
.. doxygendefine:: ESP_IO_CAP_IO
.. doxygendefine:: ESP_IO_CAP_IN
.. doxygendefine:: ESP_IO_CAP_NONE
.. doxygendefine:: ESP_IO_CAP_KBDISP
.. doxygendefine:: ESP_BLE_ADV_DATA_LEN_MAX
.. doxygendefine:: ESP_BLE_SCAN_RSP_DATA_LEN_MAX
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: esp_ble_key_type_t
.. doxygentypedef:: esp_ble_auth_req_t
.. doxygentypedef:: esp_ble_io_cap_t
.. doxygentypedef:: esp_gap_ble_cb_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_gap_ble_cb_event_t
.. doxygenenum:: esp_ble_adv_data_type
.. doxygenenum:: esp_ble_adv_type_t
.. doxygenenum:: esp_ble_adv_channel_t
.. doxygenenum:: esp_ble_adv_filter_t
.. doxygenenum:: esp_ble_sec_act_t
.. doxygenenum:: esp_ble_sm_param_t
.. doxygenenum:: esp_ble_own_addr_src_t
.. doxygenenum:: esp_ble_scan_type_t
.. doxygenenum:: esp_ble_scan_filter_t
.. doxygenenum:: esp_gap_search_evt_t
.. doxygenenum:: esp_ble_evt_type_t
Structures
^^^^^^^^^^
.. doxygenstruct:: esp_ble_adv_params_t
:members:
.. doxygenstruct:: esp_ble_adv_data_t
:members:
.. doxygenstruct:: esp_ble_scan_params_t
:members:
.. doxygenstruct:: esp_ble_conn_update_params_t
:members:
.. doxygenstruct:: esp_ble_penc_keys_t
:members:
.. doxygenstruct:: esp_ble_pcsrk_keys_t
:members:
.. doxygenstruct:: esp_ble_pid_keys_t
:members:
.. doxygenstruct:: esp_ble_lenc_keys_t
:members:
.. doxygenstruct:: esp_ble_lcsrk_keys
:members:
.. doxygenstruct:: esp_ble_sec_key_notif_t
:members:
.. doxygenstruct:: esp_ble_sec_req_t
:members:
.. doxygenstruct:: esp_ble_key_value_t
:members:
.. doxygenstruct:: esp_ble_key_t
:members:
.. doxygenstruct:: esp_ble_local_id_keys_t
:members:
.. doxygenstruct:: esp_ble_auth_cmpl_t
:members:
.. doxygenstruct:: esp_ble_sec_t
:members:
.. doxygenstruct:: esp_ble_gap_cb_param_t
:members:
.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_adv_data_cmpl_evt_param
:members:
.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_scan_rsp_data_cmpl_evt_param
:members:
.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_scan_param_cmpl_evt_param
:members:
.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_scan_result_evt_param
:members:
.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_adv_data_raw_cmpl_evt_param
:members:
.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_scan_rsp_data_raw_cmpl_evt_param
:members:
.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_adv_start_cmpl_evt_param
:members:
.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_scan_start_cmpl_evt_param
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: esp_ble_gap_register_callback
.. doxygenfunction:: esp_ble_gap_config_adv_data
.. doxygenfunction:: esp_ble_gap_set_scan_params
.. doxygenfunction:: esp_ble_gap_start_scanning
.. doxygenfunction:: esp_ble_gap_stop_scanning
.. doxygenfunction:: esp_ble_gap_start_advertising
.. doxygenfunction:: esp_ble_gap_stop_advertising
.. doxygenfunction:: esp_ble_gap_update_conn_params
.. doxygenfunction:: esp_ble_gap_set_pkt_data_len
.. doxygenfunction:: esp_ble_gap_set_rand_addr
.. doxygenfunction:: esp_ble_gap_config_local_privacy
.. doxygenfunction:: esp_ble_gap_set_device_name
.. doxygenfunction:: esp_ble_resolve_adv_data
.. doxygenfunction:: esp_ble_gap_config_adv_data_raw
.. doxygenfunction:: esp_ble_gap_config_scan_rsp_data_raw
.. doxygenfunction:: esp_ble_gap_set_security_param
.. doxygenfunction:: esp_ble_gap_security_rsp
.. doxygenfunction:: esp_ble_set_encryption
.. doxygenfunction:: esp_ble_passkey_reply
.. doxygenfunction:: esp_ble_confirm_reply
.. include:: /_build/inc/esp_gap_ble_api.inc

29
docs/api-reference/bluetooth/esp_gap_bt.rst
View File

@ -13,35 +13,8 @@ Application Example
.. _Instructions: ../template.html
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/bluedroid/api/include/esp_gap_bt_api.h`
Macros
^^^^^^
Type Definitions
^^^^^^^^^^^^^^^^
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_bt_scan_mode_t
Structures
^^^^^^^^^^
Functions
^^^^^^^^^
.. doxygenfunction:: esp_bt_gap_set_scan_mode
.. include:: /_build/inc/esp_gap_bt_api.inc

148
docs/api-reference/bluetooth/esp_gatt_defs.rst
View File

@ -13,155 +13,9 @@ Application Example
.. _Instructions: ../template.html
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/bluedroid/api/include/esp_gatt_defs.h`
Macros
^^^^^^
.. doxygendefine:: ESP_GATT_UUID_IMMEDIATE_ALERT_SVC
.. doxygendefine:: ESP_GATT_UUID_LINK_LOSS_SVC
.. doxygendefine:: ESP_GATT_UUID_TX_POWER_SVC
.. doxygendefine:: ESP_GATT_UUID_CURRENT_TIME_SVC
.. doxygendefine:: ESP_GATT_UUID_REF_TIME_UPDATE_SVC
.. doxygendefine:: ESP_GATT_UUID_NEXT_DST_CHANGE_SVC
.. doxygendefine:: ESP_GATT_UUID_GLUCOSE_SVC
.. doxygendefine:: ESP_GATT_UUID_HEALTH_THERMOM_SVC
.. doxygendefine:: ESP_GATT_UUID_DEVICE_INFO_SVC
.. doxygendefine:: ESP_GATT_UUID_HEART_RATE_SVC
.. doxygendefine:: ESP_GATT_UUID_PHONE_ALERT_STATUS_SVC
.. doxygendefine:: ESP_GATT_UUID_BATTERY_SERVICE_SVC
.. doxygendefine:: ESP_GATT_UUID_BLOOD_PRESSURE_SVC
.. doxygendefine:: ESP_GATT_UUID_ALERT_NTF_SVC
.. doxygendefine:: ESP_GATT_UUID_HID_SVC
.. doxygendefine:: ESP_GATT_UUID_SCAN_PARAMETERS_SVC
.. doxygendefine:: ESP_GATT_UUID_RUNNING_SPEED_CADENCE_SVC
.. doxygendefine:: ESP_GATT_UUID_CYCLING_SPEED_CADENCE_SVC
.. doxygendefine:: ESP_GATT_UUID_CYCLING_POWER_SVC
.. doxygendefine:: ESP_GATT_UUID_LOCATION_AND_NAVIGATION_SVC
.. doxygendefine:: ESP_GATT_UUID_USER_DATA_SVC
.. doxygendefine:: ESP_GATT_UUID_WEIGHT_SCALE_SVC
.. doxygendefine:: ESP_GATT_UUID_PRI_SERVICE
.. doxygendefine:: ESP_GATT_UUID_SEC_SERVICE
.. doxygendefine:: ESP_GATT_UUID_INCLUDE_SERVICE
.. doxygendefine:: ESP_GATT_UUID_CHAR_DECLARE
.. doxygendefine:: ESP_GATT_UUID_CHAR_EXT_PROP
.. doxygendefine:: ESP_GATT_UUID_CHAR_DESCRIPTION
.. doxygendefine:: ESP_GATT_UUID_CHAR_CLIENT_CONFIG
.. doxygendefine:: ESP_GATT_UUID_CHAR_SRVR_CONFIG
.. doxygendefine:: ESP_GATT_UUID_CHAR_PRESENT_FORMAT
.. doxygendefine:: ESP_GATT_UUID_CHAR_AGG_FORMAT
.. doxygendefine:: ESP_GATT_UUID_CHAR_VALID_RANGE
.. doxygendefine:: ESP_GATT_UUID_EXT_RPT_REF_DESCR
.. doxygendefine:: ESP_GATT_UUID_RPT_REF_DESCR
.. doxygendefine:: ESP_GATT_UUID_GAP_DEVICE_NAME
.. doxygendefine:: ESP_GATT_UUID_GAP_ICON
.. doxygendefine:: ESP_GATT_UUID_GAP_PREF_CONN_PARAM
.. doxygendefine:: ESP_GATT_UUID_GAP_CENTRAL_ADDR_RESOL
.. doxygendefine:: ESP_GATT_UUID_GATT_SRV_CHGD
.. doxygendefine:: ESP_GATT_UUID_ALERT_LEVEL
.. doxygendefine:: ESP_GATT_UUID_TX_POWER_LEVEL
.. doxygendefine:: ESP_GATT_UUID_CURRENT_TIME
.. doxygendefine:: ESP_GATT_UUID_LOCAL_TIME_INFO
.. doxygendefine:: ESP_GATT_UUID_REF_TIME_INFO
.. doxygendefine:: ESP_GATT_UUID_NW_STATUS
.. doxygendefine:: ESP_GATT_UUID_NW_TRIGGER
.. doxygendefine:: ESP_GATT_UUID_ALERT_STATUS
.. doxygendefine:: ESP_GATT_UUID_RINGER_CP
.. doxygendefine:: ESP_GATT_UUID_RINGER_SETTING
.. doxygendefine:: ESP_GATT_UUID_GM_MEASUREMENT
.. doxygendefine:: ESP_GATT_UUID_GM_CONTEXT
.. doxygendefine:: ESP_GATT_UUID_GM_CONTROL_POINT
.. doxygendefine:: ESP_GATT_UUID_GM_FEATURE
.. doxygendefine:: ESP_GATT_UUID_SYSTEM_ID
.. doxygendefine:: ESP_GATT_UUID_MODEL_NUMBER_STR
.. doxygendefine:: ESP_GATT_UUID_SERIAL_NUMBER_STR
.. doxygendefine:: ESP_GATT_UUID_FW_VERSION_STR
.. doxygendefine:: ESP_GATT_UUID_HW_VERSION_STR
.. doxygendefine:: ESP_GATT_UUID_SW_VERSION_STR
.. doxygendefine:: ESP_GATT_UUID_MANU_NAME
.. doxygendefine:: ESP_GATT_UUID_IEEE_DATA
.. doxygendefine:: ESP_GATT_UUID_PNP_ID
.. doxygendefine:: ESP_GATT_UUID_HID_INFORMATION
.. doxygendefine:: ESP_GATT_UUID_HID_REPORT_MAP
.. doxygendefine:: ESP_GATT_UUID_HID_CONTROL_POINT
.. doxygendefine:: ESP_GATT_UUID_HID_REPORT
.. doxygendefine:: ESP_GATT_UUID_HID_PROTO_MODE
.. doxygendefine:: ESP_GATT_UUID_HID_BT_KB_INPUT
.. doxygendefine:: ESP_GATT_UUID_HID_BT_KB_OUTPUT
.. doxygendefine:: ESP_GATT_UUID_HID_BT_MOUSE_INPUT
.. doxygendefine:: ESP_GATT_HEART_RATE_MEAS
.. doxygendefine:: ESP_GATT_BODY_SENSOR_LOCATION
.. doxygendefine:: ESP_GATT_HEART_RATE_CNTL_POINT
.. doxygendefine:: ESP_GATT_UUID_BATTERY_LEVEL
.. doxygendefine:: ESP_GATT_UUID_SC_CONTROL_POINT
.. doxygendefine:: ESP_GATT_UUID_SENSOR_LOCATION
.. doxygendefine:: ESP_GATT_UUID_RSC_MEASUREMENT
.. doxygendefine:: ESP_GATT_UUID_RSC_FEATURE
.. doxygendefine:: ESP_GATT_UUID_CSC_MEASUREMENT
.. doxygendefine:: ESP_GATT_UUID_CSC_FEATURE
.. doxygendefine:: ESP_GATT_UUID_SCAN_INT_WINDOW
.. doxygendefine:: ESP_GATT_UUID_SCAN_REFRESH
.. doxygendefine:: ESP_GATT_ILLEGAL_UUID
.. doxygendefine:: ESP_GATT_ILLEGAL_HANDLE
.. doxygendefine:: ESP_GATT_ATTR_HANDLE_MAX
.. doxygendefine:: ESP_GATT_MAX_ATTR_LEN
.. doxygendefine:: ESP_GATT_RSP_BY_APP
.. doxygendefine:: ESP_GATT_AUTO_RSP
.. doxygendefine:: ESP_GATT_IF_NONE
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: esp_gatt_if_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_gatt_prep_write_type
.. doxygenenum:: esp_gatt_status_t
.. doxygenenum:: esp_gatt_conn_reason_t
.. doxygenenum:: esp_gatt_auth_req_t
.. doxygenenum:: esp_gatt_perm_t
.. doxygenenum:: esp_gatt_char_prop_t
.. doxygenenum:: esp_gatt_write_type_t
Structures
^^^^^^^^^^
.. doxygenstruct:: esp_attr_desc_t
:members:
.. doxygenstruct:: esp_attr_control_t
:members:
.. doxygenstruct:: esp_gatts_attr_db_t
:members:
.. doxygenstruct:: esp_attr_value_t
:members:
.. doxygenstruct:: esp_gatts_incl_svc_desc_t
:members:
.. doxygenstruct:: esp_gatts_incl128_svc_desc_t
:members:
.. doxygenstruct:: esp_gatt_value_t
:members:
.. doxygenstruct:: esp_gatt_rsp_t
:members:
Functions
^^^^^^^^^
.. include:: /_build/inc/esp_gatt_defs.inc

109
docs/api-reference/bluetooth/esp_gattc.rst
View File

@ -11,115 +11,12 @@ Overview
Application Example
-------------------
Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following examples:
:example:`bluetooth/gatt_client`
This is a GATT client demo. This demo can scan devices, connect to the GATT server and discover the service.
Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following application:
* This is a GATT client demo. This demo can scan devices, connect to the GATT server and discover the service :example:`bluetooth/gatt_client`
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/bluedroid/api/include/esp_gattc_api.h`
Macros
^^^^^^
.. doxygendefine:: ESP_GATT_DEF_BLE_MTU_SIZE
.. doxygendefine:: ESP_GATT_MAX_MTU_SIZE
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: esp_gattc_cb_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_gattc_cb_event_t
Structures
^^^^^^^^^^
.. doxygenstruct:: esp_ble_gattc_cb_param_t
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_reg_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_open_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_close_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_cfg_mtu_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_search_cmpl_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_search_res_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_read_char_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_write_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_exec_cmpl_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_notify_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_srvc_chg_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_congest_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_get_char_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_get_descr_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_get_incl_srvc_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_reg_for_notify_evt_param
:members:
.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_unreg_for_notify_evt_param
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: esp_ble_gattc_register_callback
.. doxygenfunction:: esp_ble_gattc_app_register
.. doxygenfunction:: esp_ble_gattc_app_unregister
.. doxygenfunction:: esp_ble_gattc_open
.. doxygenfunction:: esp_ble_gattc_close
.. doxygenfunction:: esp_ble_gattc_config_mtu
.. doxygenfunction:: esp_ble_gattc_search_service
.. doxygenfunction:: esp_ble_gattc_get_characteristic
.. doxygenfunction:: esp_ble_gattc_get_descriptor
.. doxygenfunction:: esp_ble_gattc_get_included_service
.. doxygenfunction:: esp_ble_gattc_read_char
.. doxygenfunction:: esp_ble_gattc_read_char_descr
.. doxygenfunction:: esp_ble_gattc_write_char
.. doxygenfunction:: esp_ble_gattc_write_char_descr
.. doxygenfunction:: esp_ble_gattc_prepare_write
.. doxygenfunction:: esp_ble_gattc_prepare_write_char_descr
.. doxygenfunction:: esp_ble_gattc_execute_write
.. doxygenfunction:: esp_ble_gattc_register_for_notify
.. doxygenfunction:: esp_ble_gattc_unregister_for_notify
.. include:: /_build/inc/esp_gattc_api.inc

112
docs/api-reference/bluetooth/esp_gatts.rst
View File

@ -11,118 +11,12 @@ Overview
Application Example
-------------------
Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following example:
Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following application:
:example:`bluetooth/gatt_server`
This is a GATT server demo. Use GATT API to create a GATT server with send advertising. This GATT server can be connected and the service can be discovery.
* This is a GATT server demo. Use GATT API to create a GATT server with send advertising. This GATT server can be connected and the service can be discovery - :example:`bluetooth/gatt_server`
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/bluedroid/api/include/esp_gatts_api.h`
Macros
^^^^^^
.. doxygendefine:: ESP_GATT_PREP_WRITE_CANCEL
.. doxygendefine:: ESP_GATT_PREP_WRITE_EXEC
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: esp_gatts_cb_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_gatts_cb_event_t
Structures
^^^^^^^^^^
.. doxygenstruct:: esp_ble_gatts_cb_param_t
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_reg_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_read_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_write_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_exec_write_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_mtu_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_conf_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_create_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_add_incl_srvc_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_add_char_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_add_char_descr_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_delete_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_start_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_stop_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_connect_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_disconnect_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_congest_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_rsp_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_param
:members:
.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_set_attr_val_evt_param
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: esp_ble_gatts_register_callback
.. doxygenfunction:: esp_ble_gatts_app_register
.. doxygenfunction:: esp_ble_gatts_app_unregister
.. doxygenfunction:: esp_ble_gatts_create_service
.. doxygenfunction:: esp_ble_gatts_create_attr_tab
.. doxygenfunction:: esp_ble_gatts_add_included_service
.. doxygenfunction:: esp_ble_gatts_add_char
.. doxygenfunction:: esp_ble_gatts_add_char_descr
.. doxygenfunction:: esp_ble_gatts_delete_service
.. doxygenfunction:: esp_ble_gatts_start_service
.. doxygenfunction:: esp_ble_gatts_stop_service
.. doxygenfunction:: esp_ble_gatts_send_indicate
.. doxygenfunction:: esp_ble_gatts_send_response
.. doxygenfunction:: esp_ble_gatts_set_attr_value
.. doxygenfunction:: esp_ble_gatts_get_attr_value
.. doxygenfunction:: esp_ble_gatts_open
.. doxygenfunction:: esp_ble_gatts_close
.. include:: /_build/inc/esp_gatts_api.inc

2
docs/api-reference/bluetooth/index.rst
View File

@ -7,7 +7,7 @@ Bluetooth API
Bluetooth Controller && VHCI <controller_vhci>
Bluetooth Common <bt_common>
Bluetooth LE <bt_le>
Bluetooth Classic BT <classic_bt>
Bluetooth Classic <classic_bt>
Example code for this API section is provided in :example:`bluetooth` directory of ESP-IDF examples.

81
docs/api-reference/ethernet/esp_eth.rst
View File

@ -6,69 +6,42 @@ Application Example
Ethernet example: :example:`ethernet/ethernet`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`ethernet/include/esp_eth.h`
* :component_file:`ethernet/include/phy/phy.h`
PHY Interfaces
^^^^^^^^^^^^^^
--------------
The configured PHY model(s) are set in software by configuring the eth_config_t structure for the given PHY.
Headers include a default configuration structure. These default configurations will need some members overriden or re-set before they can be used for a particular PHY hardware configuration. Consult the Ethernet example to see how this is done.
* :component_file:`ethernet/include/phy/phy_tlk110.h`
* :component_file:`ethernet/include/phy/phy_lan8720.h`
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: eth_phy_check_link_func
.. doxygentypedef:: eth_phy_check_init_func
.. doxygentypedef:: eth_phy_get_speed_mode_func
.. doxygentypedef:: eth_phy_get_duplex_mode_func
.. doxygentypedef:: eth_phy_func
.. doxygentypedef:: eth_tcpip_input_func
.. doxygentypedef:: eth_gpio_config_func
.. doxygentypedef:: eth_phy_get_partner_pause_enable_func
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: eth_mode_t
.. doxygenenum:: eth_speed_mode_t
.. doxygenenum:: eth_duplex_mode_t
.. doxygenenum:: eth_phy_base_t
Structures
^^^^^^^^^^
.. doxygenstruct:: eth_config_t
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: esp_eth_init
.. doxygenfunction:: esp_eth_tx
.. doxygenfunction:: esp_eth_enable
.. doxygenfunction:: esp_eth_disable
.. doxygenfunction:: esp_eth_get_mac
.. doxygenfunction:: esp_eth_smi_write
.. doxygenfunction:: esp_eth_smi_read
.. doxygenfunction:: esp_eth_smi_wait_value
.. doxygenfunction:: esp_eth_smi_wait_set
.. doxygenfunction:: esp_eth_free_rx_buf
* :component_file:`ethernet/include/eth_phy/phy.h` (common)
* :component_file:`ethernet/include/eth_phy/phy_tlk110.h`
* :component_file:`ethernet/include/eth_phy/phy_lan8720.h`
PHY Configuration Constants
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenvariable:: phy_tlk110_default_ethernet_config
.. doxygenvariable:: phy_lan8720_default_ethernet_config
API Reference - Ethernet
------------------------
.. include:: /_build/inc/esp_eth.inc
API Reference - PHY Common
--------------------------
.. include:: /_build/inc/phy.inc
API Reference - PHY TLK110
--------------------------
.. include:: /_build/inc/phy_tlk110.inc
API Reference - PHY LAN8720
---------------------------
.. include:: /_build/inc/phy_lan8720.inc

5
docs/api-reference/index.rst
View File

@ -9,6 +9,7 @@ API Reference
Bluetooth <bluetooth/index>
Ethernet <ethernet/index>
Peripherals <peripherals/index>
System <system/index>
Storage <storage/index>
Protocols <protocols/index>
Storage <storage/index>
System <system/index>

19
docs/api-reference/peripherals/adc.rst
View File

@ -40,23 +40,6 @@ The value read in both these examples is 12 bits wide (range 0-4095).
API Reference
-------------
Header Files
^^^^^^^^^^^^
.. include:: /_build/inc/adc.inc
* `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

19
docs/api-reference/peripherals/dac.rst
View File

@ -28,22 +28,5 @@ Setting DAC channel 1 (GPIO 25) voltage to approx 0.78 of VDD_A voltage (VDD * 2
API Reference
-------------
Header Files
^^^^^^^^^^^^
.. include:: /_build/inc/dac.inc
* `components/driver/include/driver/dac.h`
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: dac_channel_t
Functions
^^^^^^^^^
.. doxygenfunction:: dac_output_voltage
.. doxygenfunction:: dac_output_enable
.. doxygenfunction:: dac_output_disable
.. doxygenfunction:: dac_i2s_enable
.. doxygenfunction:: dac_i2s_disable

175
docs/api-reference/peripherals/gpio.rst
View File

@ -16,176 +16,13 @@ Application Example
GPIO output and input interrupt example: :example:`peripherals/gpio`.
API Reference
-------------
API Reference - Normal GPIO
---------------------------
Header Files
^^^^^^^^^^^^
.. include:: /_build/inc/gpio.inc
* :component_file:`driver/include/driver/gpio.h`
* :component_file:`driver/include/driver/rtc_io.h`
API Reference - RTC GPIO
------------------------
Macros
^^^^^^
.. include:: /_build/inc/rtc_io.inc
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

68
docs/api-reference/peripherals/i2c.rst
View File

@ -1,5 +1,5 @@
I2C
===========
===
Overview
--------
@ -14,69 +14,5 @@ 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
.. include:: /_build/inc/i2c.inc

56
docs/api-reference/peripherals/i2s.rst
View File

@ -15,7 +15,11 @@ Application Example
A full I2S example is available in esp-idf: :example:`peripherals/i2s`.
Short example of I2S configuration::
Short example of I2S configuration:
.. highlight:: c
::
#include "driver/i2s.h"
#include "freertos/queue.h"
@ -84,53 +88,5 @@ Short example configuring I2S to use internal DAC for analog output::
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
.. doxygenenum:: i2s_dac_mode_t
Functions
^^^^^^^^^
.. doxygenfunction:: i2s_set_pin
.. doxygenfunction:: i2s_set_dac_mode
.. 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
.. include:: /_build/inc/i2s.inc

3
docs/api-reference/peripherals/index.rst
View File

@ -10,12 +10,13 @@ Peripherals API
I2C <i2c>
I2S <i2s>
LED Control <ledc>
MCPWM <mcpwm>
Pulse Counter <pcnt>
Remote Control <rmt>
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>

61
docs/api-reference/peripherals/ledc.rst
View File

@ -17,64 +17,5 @@ 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
.. include:: /_build/inc/ledc.inc

77
docs/api/peripherals/mcpwm.rst → docs/api-reference/peripherals/mcpwm.rst
View File

@ -50,84 +50,11 @@ The block diagram of MCPWM unit is as shown.
Application Example
-------------------
MCPWM different motor example: :example:`peripherals/mcpwm`.
Examples of using MCPWM for motor control: :example:`peripherals/mcpwm`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`driver/include/driver/mcpwm.h`
Type Definitions
^^^^^^^^^^^^^^^^
.. include:: /_build/inc/mcpwm.inc
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: mcpwm_io_signals_t
.. doxygenenum:: mcpwm_unit_t
.. doxygenenum:: mcpwm_timer_t
.. doxygenenum:: mcpwm_operator_t
.. doxygenenum:: mcpwm_counter_type_t
.. doxygenenum:: mcpwm_duty_type_t
.. doxygenenum:: mcpwm_carrier_os_t
.. doxygenenum:: mcpwm_carrier_out_ivt_t
.. doxygenenum:: mcpwm_sync_signal_t
.. doxygenenum:: mcpwm_fault_signal_t
.. doxygenenum:: mcpwm_fault_input_level_t
.. doxygenenum:: mcpwm_action_on_pwmxa_t
.. doxygenenum:: mcpwm_action_on_pwmxb_t
.. doxygenenum:: mcpwm_capture_signal_t
.. doxygenenum:: mcpwm_capture_on_edge_t
.. doxygenenum:: mcpwm_deadtime_type_t
Structures
^^^^^^^^^^
.. doxygenstruct:: mcpwm_config_t
:members:
.. doxygenstruct:: mcpwm_carrier_config_t
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: mcpwm_gpio_init
.. doxygenfunction:: mcpwm_init
.. doxygenfunction:: mcpwm_set_frequency
.. doxygenfunction:: mcpwm_set_duty
.. doxygenfunction:: mcpwm_set_duty_in_us
.. doxygenfunction:: mcpwm_set_duty_type
.. doxygenfunction:: mcpwm_get_frequency
.. doxygenfunction:: mcpwm_get_duty
.. doxygenfunction:: mcpwm_set_signal_high
.. doxygenfunction:: mcpwm_set_signal_low
.. doxygenfunction:: mcpwm_start
.. doxygenfunction:: mcpwm_stop
.. doxygenfunction:: mcpwm_carrier_init
.. doxygenfunction:: mcpwm_carrier_enable
.. doxygenfunction:: mcpwm_carrier_disable
.. doxygenfunction:: mcpwm_carrier_set_period
.. doxygenfunction:: mcpwm_carrier_set_duty_cycle
.. doxygenfunction:: mcpwm_carrier_oneshot_mode_enable
.. doxygenfunction:: mcpwm_carrier_oneshot_mode_disable
.. doxygenfunction:: mcpwm_carrier_output_invert
.. doxygenfunction:: mcpwm_deadtime_enable
.. doxygenfunction:: mcpwm_deadtime_disable
.. doxygenfunction:: mcpwm_fault_init
.. doxygenfunction:: mcpwm_fault_set_oneshot_mode
.. doxygenfunction:: mcpwm_fault_set_cyc_mode
.. doxygenfunction:: mcpwm_fault_deinit
.. doxygenfunction:: mcpwm_capture_enable
.. doxygenfunction:: mcpwm_capture_disable
.. doxygenfunction:: mcpwm_capture_signal_get_value
.. doxygenfunction:: mcpwm_capture_signal_get_edge
.. doxygenfunction:: mcpwm_sync_enable
.. doxygenfunction:: mcpwm_sync_disable
.. doxygenfunction:: mcpwm_isr_register

50
docs/api-reference/peripherals/pcnt.rst
View File

@ -14,53 +14,5 @@ Pulse counter with control signal and event interrupt example: :example:`periphe
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
.. include:: /_build/inc/pcnt.inc

77
docs/api-reference/peripherals/rmt.rst
View File

@ -14,80 +14,5 @@ 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
.. include:: /_build/inc/rmt.inc

34
docs/api-reference/peripherals/sigmadelta.rst
View File

@ -15,37 +15,5 @@ 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
.. include:: /_build/inc/sigmadelta.inc

60
docs/api-reference/peripherals/spi_master.rst
View File

@ -109,63 +109,15 @@ Application Example
Display graphics on the ILI9341-based 320x240 LCD: :example:`peripherals/spi_master`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
API Reference - SPI Common
--------------------------
* :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:
.. include:: /_build/inc/spi_common.inc
API Reference - SPI Master
--------------------------
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
.. include:: /_build/inc/spi_master.inc

48
docs/api-reference/peripherals/spi_slave.rst
View File

@ -92,51 +92,5 @@ 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
.. include:: /_build/inc/spi_slave.inc

55
docs/api-reference/peripherals/timer.rst
View File

@ -8,7 +8,6 @@ ESP32 chip contains two hardware timer groups, each containing two general-purpo
They are all 64-bit generic timers based on 16-bit prescalers and 64-bit auto-reload-capable up/down counters.
Application Example
-------------------
@ -17,57 +16,5 @@ Application Example
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
.. include:: /_build/inc/timer.inc

79
docs/api-reference/peripherals/uart.rst
View File

@ -16,83 +16,6 @@ Configure uart settings and install uart driver to read/write using UART0 and UA
API Reference
-------------
Header Files
^^^^^^^^^^^^
.. include:: /_build/inc/uart.inc
* :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

67
docs/api-reference/protocols/mdns.rst
View File

@ -16,7 +16,9 @@ mDNS Properties
Example method to start mDNS for the STA interface and set ``hostname`` and ``default_instance``:
::
.. highlight:: c
::
mdns_server_t * mdns = NULL;
@ -46,9 +48,7 @@ mDNS can advertise information about network services that your device offers. E
* ``instance``: friendly name for your service, like ``Jhon's ESP32 Web Server``. If not defined, ``default_instance`` will be used.
* ``txt``: ``var=val`` array of strings, used to define properties for your service
Example method to add a few services and different properties:
::
Example method to add a few services and different properties::
void add_mdns_services()
{
@ -78,13 +78,10 @@ mDNS Query
^^^^^^^^^^
mDNS provides methods for browsing for services and resolving host's IP/IPv6 addresses.
Results are returned as a linked list of ``mdns_result_t`` objects. If the result is from host query,
it will contain only ``addr`` and ``addrv6`` if found. Service queries will populate all fields
in a result that were found.
Example method to resolve host IPs:
Results are returned as a linked list of ``mdns_result_t`` objects. If the result is from host query, it will contain only ``addr`` and ``addrv6`` if found. Service queries will populate all fields in a result that were found.
::
Example method to resolve host IPs::
void resolve_mdns_host(const char * hostname)
{
@ -110,9 +107,7 @@ Example method to resolve host IPs:
}
}
Example method to resolve local services:
::
Example method to resolve local services::
void find_mdns_service(const char * service, const char * proto)
{
@ -140,9 +135,7 @@ Example method to resolve local services:
}
}
Example of using the methods above:
::
Example of using the methods above::
void my_app_some_method(){
//search for esp32-mdns.local
@ -168,48 +161,6 @@ mDNS server/scanner example: :example:`protocols/mdns`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`mdns/include/mdns.h`
Macros
^^^^^^
.. include:: /_build/inc/mdns.inc
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: mdns_server_t
.. doxygentypedef:: mdns_result_t
Enumerations
^^^^^^^^^^^^
Structures
^^^^^^^^^^
.. doxygenstruct:: mdns_result_s
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: mdns_init
.. doxygenfunction:: mdns_free
.. doxygenfunction:: mdns_set_hostname
.. doxygenfunction:: mdns_set_instance
.. doxygenfunction:: mdns_service_add
.. doxygenfunction:: mdns_service_remove
.. doxygenfunction:: mdns_service_instance_set
.. doxygenfunction:: mdns_service_txt_set
.. doxygenfunction:: mdns_service_port_set
.. doxygenfunction:: mdns_service_remove_all
.. doxygenfunction:: mdns_query
.. doxygenfunction:: mdns_query_end
.. doxygenfunction:: mdns_result_get_count
.. doxygenfunction:: mdns_result_get
.. doxygenfunction:: mdns_result_free

4
docs/api-reference/storage/fatfs.rst
View File

@ -42,10 +42,8 @@ Using FatFs with VFS and SD cards
``esp_vfs_fat.h`` header file also provides a convenience function to perform steps 1–3 and 7–9, and also handle SD card initialization: ``esp_vfs_fat_sdmmc_mount``. This function does only limited error handling. Developers are encouraged to look at its source code and incorporate more advanced versions into production applications. ``esp_vfs_fat_sdmmc_unmount`` function unmounts the filesystem and releases resources acquired by ``esp_vfs_fat_sdmmc_mount``.
.. doxygenfunction:: esp_vfs_fat_sdmmc_mount
.. doxygenstruct:: esp_vfs_fat_mount_config_t
:members:
.. doxygenfunction:: esp_vfs_fat_sdmmc_unmount
FatFS disk IO layer
@ -56,9 +54,7 @@ FatFs has been extended with an API to register disk IO driver at runtime.
Implementation of disk IO functions for SD/MMC cards is provided. It can be registered for the given FatFs drive number using ``ff_diskio_register_sdmmc`` function.
.. doxygenfunction:: ff_diskio_register
.. doxygenstruct:: ff_diskio_impl_t
:members:
.. doxygenfunction:: ff_diskio_register_sdmmc

2
docs/api-reference/storage/index.rst
View File

@ -5,7 +5,7 @@ Storage API
:maxdepth: 1
SPI Flash and Partition APIs <spi_flash>
SD/MMC <sdmmc>
SD/MMC Card Host <sdmmc>
Non-Volatile Storage <nvs_flash>
Virtual Filesystem <vfs>
FAT Filesystem <fatfs>

63
docs/api-reference/storage/nvs_flash.rst
View File

@ -26,67 +26,8 @@ Two examples are provided in :example:`storage` directory of ESP-IDF examples:
API Reference
-------------
Header Files
^^^^^^^^^^^^
.. include:: /_build/inc/nvs_flash.inc
* :component_file:`nvs_flash/include/nvs_flash.h`
* :component_file:`nvs_flash/include/nvs.h`
Macros
^^^^^^
.. doxygendefine:: ESP_ERR_NVS_BASE
.. doxygendefine:: ESP_ERR_NVS_NOT_INITIALIZED
.. doxygendefine:: ESP_ERR_NVS_NOT_FOUND
.. doxygendefine:: ESP_ERR_NVS_TYPE_MISMATCH
.. doxygendefine:: ESP_ERR_NVS_READ_ONLY
.. doxygendefine:: ESP_ERR_NVS_NOT_ENOUGH_SPACE
.. doxygendefine:: ESP_ERR_NVS_INVALID_NAME
.. doxygendefine:: ESP_ERR_NVS_INVALID_HANDLE
.. doxygendefine:: ESP_ERR_NVS_REMOVE_FAILED
.. doxygendefine:: ESP_ERR_NVS_KEY_TOO_LONG
.. doxygendefine:: ESP_ERR_NVS_PAGE_FULL
.. doxygendefine:: ESP_ERR_NVS_INVALID_STATE
.. doxygendefine:: ESP_ERR_NVS_INVALID_LENGTH
.. doxygendefine:: ESP_ERR_NVS_NO_FREE_PAGES
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: nvs_handle
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: nvs_open_mode
Functions
^^^^^^^^^
.. doxygenfunction:: nvs_flash_init
.. doxygenfunction:: nvs_open
.. doxygenfunction:: nvs_set_i8
.. doxygenfunction:: nvs_set_u8
.. doxygenfunction:: nvs_set_i16
.. doxygenfunction:: nvs_set_u16
.. doxygenfunction:: nvs_set_i32
.. doxygenfunction:: nvs_set_u32
.. doxygenfunction:: nvs_set_i64
.. doxygenfunction:: nvs_set_u64
.. doxygenfunction:: nvs_set_str
.. doxygenfunction:: nvs_set_blob
.. doxygenfunction:: nvs_get_i8
.. doxygenfunction:: nvs_get_u8
.. doxygenfunction:: nvs_get_i16
.. doxygenfunction:: nvs_get_u16
.. doxygenfunction:: nvs_get_i32
.. doxygenfunction:: nvs_get_u32
.. doxygenfunction:: nvs_get_i64
.. doxygenfunction:: nvs_get_u64
.. doxygenfunction:: nvs_get_str
.. doxygenfunction:: nvs_get_blob
.. doxygenfunction:: nvs_erase_key
.. doxygenfunction:: nvs_erase_all
.. doxygenfunction:: nvs_commit
.. doxygenfunction:: nvs_close
.. include:: /_build/inc/nvs.inc

83
docs/api-reference/storage/spi_flash.rst
View File

@ -7,72 +7,6 @@ See also
- :doc:`Over The Air Update (OTA) API <../system/ota>` provides high-level API for updating app firmware stored in flash.
- :doc:`Non-Volatile Storage (NVS) API <nvs_flash>` provides a structured API for storing small items of data in SPI flash.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`spi_flash/include/esp_spi_flash.h`
* :component_file:`spi_flash/include/esp_partition.h`
* :component_file:`bootloader_support/include/esp_flash_encrypt.h`
Macros
^^^^^^
.. doxygendefine:: ESP_ERR_FLASH_BASE
.. doxygendefine:: ESP_ERR_FLASH_OP_FAIL
.. doxygendefine:: ESP_ERR_FLASH_OP_TIMEOUT
.. doxygendefine:: SPI_FLASH_SEC_SIZE
.. doxygendefine:: SPI_FLASH_MMU_PAGE_SIZE
.. doxygendefine:: ESP_PARTITION_SUBTYPE_OTA
.. doxygendefine:: SPI_FLASH_CACHE2PHYS_FAIL
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: spi_flash_mmap_handle_t
.. doxygentypedef:: esp_partition_iterator_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: spi_flash_mmap_memory_t
.. doxygenenum:: esp_partition_type_t
.. doxygenenum:: esp_partition_subtype_t
Structures
^^^^^^^^^^
.. doxygenstruct:: esp_partition_t
Functions
^^^^^^^^^
.. doxygenfunction:: spi_flash_init
.. doxygenfunction:: spi_flash_get_chip_size
.. doxygenfunction:: spi_flash_erase_sector
.. doxygenfunction:: spi_flash_erase_range
.. doxygenfunction:: spi_flash_write
.. doxygenfunction:: spi_flash_write_encrypted
.. doxygenfunction:: spi_flash_read
.. doxygenfunction:: spi_flash_read_encrypted
.. doxygenfunction:: spi_flash_mmap
.. doxygenfunction:: spi_flash_munmap
.. doxygenfunction:: spi_flash_mmap_dump
.. doxygenfunction:: spi_flash_cache2phys
.. doxygenfunction:: spi_flash_phys2cache
.. doxygenfunction:: spi_flash_cache_enabled
.. doxygenfunction:: esp_partition_find
.. doxygenfunction:: esp_partition_find_first
.. doxygenfunction:: esp_partition_get
.. doxygenfunction:: esp_partition_next
.. doxygenfunction:: esp_partition_iterator_release
.. doxygenfunction:: esp_partition_read
.. doxygenfunction:: esp_partition_write
.. doxygenfunction:: esp_partition_erase_range
.. doxygenfunction:: esp_partition_mmap
.. doxygenfunction:: esp_flash_encryption_enabled
.. _spi-flash-implementation-details:
@ -108,3 +42,20 @@ Additionally, all API functions are protected with a mutex (s_flash_op_mutex).
In a single core environment (CONFIG_FREERTOS_UNICORE enabled), we simply
disable both caches, no inter-CPU communication takes place.
API Reference - SPI Flash
-------------------------
.. include:: /_build/inc/esp_spi_flash.inc
API Reference - Partition Table
-------------------------------
.. include:: /_build/inc/esp_partition.inc
API Reference - Flash Encrypt
-----------------------------
.. include:: /_build/inc/esp_flash_encrypt.inc

35
docs/api-reference/storage/vfs.rst
View File

@ -10,38 +10,7 @@ Application Example
API Reference
-------------
Header Files
^^^^^^^^^^^^
.. include:: /_build/inc/esp_vfs.inc
* :component_file:`vfs/include/esp_vfs.h`
* :component_file:`vfs/include/esp_vfs_dev.h`
.. include:: /_build/inc/esp_vfs_dev.inc
Macros
^^^^^^
.. doxygendefine:: ESP_VFS_PATH_MAX
.. doxygendefine:: ESP_VFS_FLAG_DEFAULT
.. doxygendefine:: ESP_VFS_FLAG_CONTEXT_PTR
Structures
^^^^^^^^^^
.. doxygenstruct:: esp_vfs_t
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: esp_vfs_register
.. doxygenfunction:: esp_vfs_unregister
.. doxygenfunction:: esp_vfs_write
.. doxygenfunction:: esp_vfs_lseek
.. doxygenfunction:: esp_vfs_read
.. doxygenfunction:: esp_vfs_open
.. doxygenfunction:: esp_vfs_close
.. doxygenfunction:: esp_vfs_fstat
.. doxygenfunction:: esp_vfs_stat
.. doxygenfunction:: esp_vfs_link
.. doxygenfunction:: esp_vfs_unlink
.. doxygenfunction:: esp_vfs_rename
.. doxygenfunction:: esp_vfs_dev_uart_register

22
docs/api-reference/storage/wear-levelling.rst
View File

@ -6,12 +6,10 @@ See also
- :doc:`FAT Filesystem <../../api-guides/partition-tables>`
- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
Application Example
-------------------
An example which combines wear levelling driver with FATFS library is provided in ``examples/storage/wear_levelling`` directory. This example initializes the
wear levelling driver, mounts FATFS partition, and 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 wear levelling driver with FATFS library is provided in ``examples/storage/wear_levelling`` directory. This example initializes the wear levelling driver, mounts FATFS partition, and writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
High level API Reference
------------------------
@ -19,7 +17,7 @@ High level API Reference
Header Files
^^^^^^^^^^^^
* :component_file:`fatfs/src/esp_vfs_fat.h`
* :component_file:`fatfs/src/esp_vfs_fat.h`
Functions
^^^^^^^^^
@ -32,19 +30,5 @@ Functions
Mid level API Reference
-----------------------
Header Files
^^^^^^^^^^^^
* :component_file:`wear_levelling/include/wear_levelling.h`
Functions
^^^^^^^^^
.. doxygenfunction:: wl_mount
.. doxygenfunction:: wl_unmount
.. doxygenfunction:: wl_erase_range
.. doxygenfunction:: wl_write
.. doxygenfunction:: wl_read
.. doxygenfunction:: wl_size
.. doxygenfunction:: wl_sector_size
.. include:: /_build/inc/wear_levelling.inc

41
docs/api-reference/system/base_mac_address.rst
View File

@ -4,7 +4,7 @@ Base MAC address
Overview
--------
Serveral universally administered(by IEEE) MAC addresses are uniquely assigned to the networking interfaces(WiFi/BT/Ethernet).
Serveral MAC addresses (universally administered by IEEE) are uniquely assigned to the networking interfaces (WiFi/BT/Ethernet).
The final octet of each universally administered MAC address increases by one. Only the first one which is called base MAC address
of them is stored in EFUSE or external storage, the others are generated from it. Here, 'generate' means adding 0, 1, 2 and 3
(respectively) to the final octet of the base MAC address.
@ -12,7 +12,7 @@ of them is stored in EFUSE or external storage, the others are generated from it
If the universally administered MAC addresses are not enough for all of the networking interfaces. Local administered MAC addresses
which are derived from universally administered MAC addresses are assigned to the reset of networking interfaces.
A `definition of local vs universal MAC address can be found on Wikipedia<https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local>`.
A `definition of local vs universal MAC address can be found on Wikipedia <https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local>`_.
The number of universally administered MAC address can be configured using ``make menuconfig``.
@ -21,30 +21,35 @@ Base MAC address
If using the default base MAC address factory programmed by Espressif in BLK0 of EFUSE, nothing needs to be done.
If using a custom base MAC address stored in BLK3 of EFUSE, call API esp_efuse_mac_get_custom() to get the base MAC address
which is stored in BLK3 of EFUSE. If correct MAC address is returned, then call esp_base_mac_addr_set() to set the base MAC
If using a custom base MAC address stored in BLK3 of EFUSE, call API ``esp_efuse_mac_get_custom()`` to get the base MAC address
which is stored in BLK3 of EFUSE. If correct MAC address is returned, then call ``esp_base_mac_addr_set()`` to set the base MAC
address for system to generate the MAC addresses used by the networking interfaces(WiFi/BT/Ethernet).
There are 192 bits storage spaces for custom to store base MAC address in BLK3 of EFUSE. They are EFUSE_BLK3_RDATA0,
EFUSE_BLK3_RDATA1, EFUSE_BLK3_RDATA2, EFUSE_BLK3_RDATA3, EFUSE_BLK3_RDATA4 and EFUSE_BLK3_RDATA5, each of them is 32 bits
register. The format of the 192 bits storage spaces is:
------------------------------------------------------
Field |Bits |Range |Description
------------------------------------------------------
version |8 |[191:184] |1: useful. 0: useless
------------------------------------------------------
reserve |112 |[183:72] |reserved
------------------------------------------------------
mac address |64 |[71:8] |base MAC address
------------------------------------------------------
mac crc |8 |[7:0] |crc of base MAC address
------------------------------------------------------
.. highlight:: none
::
------------------------------------------------------
Field |Bits |Range |Description
------------------------------------------------------
version |8 |[191:184] |1: useful. 0: useless
------------------------------------------------------
reserve |112 |[183:72] |reserved
------------------------------------------------------
mac address |64 |[71:8] |base MAC address
------------------------------------------------------
mac crc |8 |[7:0] |crc of base MAC address
------------------------------------------------------
If using base MAC address stored in external storage, firstly get the base MAC address stored in external storage, then call
API esp_base_mac_addr_set() to set the base MAC address for system to generate the MAC addresses used by the networking
API ``esp_base_mac_addr_set()`` to set the base MAC address for system to generate the MAC addresses used by the networking
interfaces(WiFi/BT/Ethernet).
All of the steps must be done before initializing the networking interfaces(WiFi/BT/Ethernet). It is recommended to do it in
app_main() which can be referenced in example `system/base_mac_address`.
``app_main()`` which can be referenced in :example:`system/base_mac_address`.
Number of universally administered MAC address
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -74,4 +79,4 @@ Functions
---------
.. doxygenfunction:: esp_base_mac_addr_set
.. doxygenfunction:: esp_efuse_mac_get_custom
.. doxygenfunction:: esp_efuse_mac_get_custom

39
docs/api-reference/system/intr_alloc.rst
View File

@ -83,46 +83,9 @@ It can also be useful to keep an interrupt handler in IRAM if it is called very
Refer to the :ref:`SPI flash API documentation <iram-safe-interrupt-handlers>` for more details.
Application Example
-------------------
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`esp32/include/esp_intr_alloc.h`
.. include:: /_build/inc/esp_intr_alloc.inc
Macros
^^^^^^
.. doxygendefine:: ESP_INTR_FLAG_LEVEL1
.. doxygendefine:: ESP_INTR_FLAG_LEVEL2
.. doxygendefine:: ESP_INTR_FLAG_LEVEL3
.. doxygendefine:: ESP_INTR_FLAG_LEVEL4
.. doxygendefine:: ESP_INTR_FLAG_LEVEL5
.. doxygendefine:: ESP_INTR_FLAG_LEVEL6
.. doxygendefine:: ESP_INTR_FLAG_NMI
.. doxygendefine:: ESP_INTR_FLAG_LOWMED
.. doxygendefine:: ESP_INTR_FLAG_HIGH
.. doxygendefine:: ESP_INTR_FLAG_SHARED
.. doxygendefine:: ESP_INTR_FLAG_EDGE
.. doxygendefine:: ESP_INTR_FLAG_IRAM
.. doxygendefine:: ESP_INTR_FLAG_INTRDISABLED
Functions
^^^^^^^^^
.. doxygenfunction:: esp_intr_mark_shared
.. doxygenfunction:: esp_intr_reserve
.. doxygenfunction:: esp_intr_alloc
.. doxygenfunction:: esp_intr_alloc_intrstatus
.. doxygenfunction:: esp_intr_free
.. doxygenfunction:: esp_intr_get_cpu
.. doxygenfunction:: esp_intr_get_intno
.. doxygenfunction:: esp_intr_disable
.. doxygenfunction:: esp_intr_enable
.. doxygenfunction:: esp_intr_noniram_disable
.. doxygenfunction:: esp_intr_noniram_enable

52
docs/api-reference/system/log.rst
View File

@ -12,57 +12,7 @@ Log library is commonly used by most of esp-idf components and examples. For dem
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`log/include/esp_log.h`
Macros
^^^^^^
.. doxygendefine:: LOG_COLOR_E
.. doxygendefine:: LOG_COLOR_W
.. doxygendefine:: LOG_COLOR_I
.. doxygendefine:: LOG_COLOR_D
.. doxygendefine:: LOG_COLOR_V
.. doxygendefine:: LOG_RESET_COLOR
.. doxygendefine:: LOG_FORMAT
.. doxygendefine:: LOG_LOCAL_LEVEL
.. doxygendefine:: ESP_EARLY_LOGE
.. doxygendefine:: ESP_EARLY_LOGW
.. doxygendefine:: ESP_EARLY_LOGI
.. doxygendefine:: ESP_EARLY_LOGD
.. doxygendefine:: ESP_EARLY_LOGV
.. doxygendefine:: ESP_LOGE
.. doxygendefine:: ESP_LOGW
.. doxygendefine:: ESP_LOGI
.. doxygendefine:: ESP_LOGD
.. doxygendefine:: ESP_LOGV
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: vprintf_like_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_log_level_t
Functions
^^^^^^^^^
.. doxygenfunction:: esp_log_level_set
.. doxygenfunction:: esp_log_set_vprintf
.. doxygenfunction:: esp_log_timestamp
.. doxygenfunction:: esp_log_write
.. include:: /_build/inc/esp_log.inc

49
docs/api-reference/system/mem_alloc.rst
View File

@ -1,5 +1,5 @@
Memory allocation
====================
=================
Overview
--------
@ -30,48 +30,13 @@ If a certain memory structure is only addressed in 32-bit units, for example an
useful to allocate it with the MALLOC_CAP_32BIT flag. This also allows the allocator to give out IRAM memory; something
which it can't do for a normal malloc() call. This can help to use all the available memory in the ESP32.
API Reference - Heap Allocation
-------------------------------
API Reference
-------------
.. include:: /_build/inc/esp_heap_alloc_caps.inc
Header Files
^^^^^^^^^^^^
API Reference - Heap Regions
----------------------------
* :component_file:`esp32/include/esp_heap_alloc_caps.h`
* :component_file:`freertos/include/freertos/heap_regions.h`
.. include:: /_build/inc/heap_regions.inc
Macros
^^^^^^
.. doxygendefine:: MALLOC_CAP_EXEC
.. doxygendefine:: MALLOC_CAP_32BIT
.. doxygendefine:: MALLOC_CAP_8BIT
.. doxygendefine:: MALLOC_CAP_DMA
.. doxygendefine:: MALLOC_CAP_PID2
.. doxygendefine:: MALLOC_CAP_PID3
.. doxygendefine:: MALLOC_CAP_PID4
.. doxygendefine:: MALLOC_CAP_PID5
.. doxygendefine:: MALLOC_CAP_PID6
.. doxygendefine:: MALLOC_CAP_PID7
.. doxygendefine:: MALLOC_CAP_SPISRAM
.. doxygendefine:: MALLOC_CAP_INVALID
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: HeapRegionTagged_t
Functions
^^^^^^^^^
.. doxygenfunction:: heap_alloc_caps_init
.. doxygenfunction:: pvPortMallocCaps
.. doxygenfunction:: xPortGetFreeHeapSizeCaps
.. doxygenfunction:: xPortGetMinimumEverFreeHeapSizeCaps
.. doxygenfunction:: vPortDefineHeapRegionsTagged
.. doxygenfunction:: pvPortMallocTagged
.. doxygenfunction:: vPortFreeTagged
.. doxygenfunction:: xPortGetMinimumEverFreeHeapSizeTagged
.. doxygenfunction:: xPortGetFreeHeapSizeTagged

31
docs/api-reference/system/ota.rst
View File

@ -2,7 +2,7 @@ Over The Air Updates (OTA)
==========================
OTA Process Overview
^^^^^^^^^^^^^^^^^^^^
--------------------
The OTA update mechanism allows a device to update itself based on data received while the normal firmware is running
(for example, over WiFi or Bluetooth.)
@ -17,7 +17,7 @@ next boot.
.. _ota_data_partition:
OTA Data Partition
^^^^^^^^^^^^^^^^^^
------------------
An OTA data partition (type ``data``, subtype ``ota``) must be included in the :doc:`Partition Table <../../api-guides/partition-tables>`
of any project which uses the OTA functions.
@ -46,32 +46,7 @@ End-to-end example of OTA firmware update workflow: :example:`system/ota`.
API Reference
-------------
Header Files
^^^^^^^^^^^^
.. include:: /_build/inc/esp_ota_ops.inc
* :component_file:`app_update/include/esp_ota_ops.h`
Macros
^^^^^^
.. doxygendefine:: ESP_ERR_OTA_BASE
.. doxygendefine:: ESP_ERR_OTA_PARTITION_CONFLICT
.. doxygendefine:: ESP_ERR_OTA_SELECT_INFO_INVALID
.. doxygendefine:: ESP_ERR_OTA_VALIDATE_FAILED
.. doxygendefine:: OTA_SIZE_UNKNOWN
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: esp_ota_handle_t
Functions
^^^^^^^^^
.. doxygenfunction:: esp_ota_begin
.. doxygenfunction:: esp_ota_write
.. doxygenfunction:: esp_ota_end
.. doxygenfunction:: esp_ota_get_running_partition
.. doxygenfunction:: esp_ota_set_boot_partition
.. doxygenfunction:: esp_ota_get_boot_partition
.. doxygenfunction:: esp_ota_get_next_update_partition

134
docs/api-reference/template.rst
View File

@ -3,113 +3,103 @@ API Documentation Template
.. note::
*INSTRUCTIONS*
*INSTRUCTIONS*
1. Use this file as a template to document API.
2. Change the file name to the name of the header file that represents documented API.
3. Include respective files with descriptions from the API folder using ``..include::``
* README.rst
* example.rst
4. Optionally provide description right in this file.
5. Once done, remove all instructions like this one and any superfluous headers.
1. Use this file (:idf_file:`docs/api-reference/template.rst`) as a template to document API.
2. Change the file name to the name of the header file that represents documented API.
3. Include respective files with descriptions from the API folder using ``..include::``
* README.rst
* example.rst
* ...
4. Optionally provide description right in this file.
5. Once done, remove all instructions like this one and any superfluous headers.
Overview
--------
.. note::
*INSTRUCTIONS*
*INSTRUCTIONS*
1. Provide overview where and how this API may be used.
2. Where applicable include code snippets to illustrate functionality of particular functions.
3. To distinguish between sections, use the following `heading levels <http://www.sphinx-doc.org/en/stable/rest.html#sections>`_:
1. Provide overview where and how this API may be used.
2. Where applicable include code snippets to illustrate functionality of particular functions.
3. To distinguish between sections, use the following `heading levels <http://www.sphinx-doc.org/en/stable/rest.html#sections>`_:
* ``#`` with overline, for parts
* ``*`` with overline, for chapters
* ``=``, for sections
* ``-``, for subsections
* ``^``, for subsubsections
* ``"``, for paragraphs
* ``#`` with overline, for parts
* ``*`` with overline, for chapters
* ``=``, for sections
* ``-``, for subsections
* ``^``, for subsubsections
* ``"``, for paragraphs
Application Example
-------------------
.. note::
*INSTRUCTIONS*
*INSTRUCTIONS*
1. Prepare one or more practical examples to demonstrate functionality of this API.
2. Each example should follow pattern of projects located in ``esp-idf/examples/`` folder.
3. Place example in this folder complete with ``README.md`` file.
4. Provide overview of demonstrated functionality in ``README.md``.
5. With good overview reader should be able to understand what example does without opening the source code.
6. Depending on complexity of example, break down description of code into parts and provide overview of functionality of each part.
7. Include flow diagram and screenshots of application output if applicable.
8. Finally add in this section synopsis of each example together with link to respective folder in ``esp-idf/examples/``.
1. Prepare one or more practical examples to demonstrate functionality of this API.
2. Each example should follow pattern of projects located in ``esp-idf/examples/`` folder.
3. Place example in this folder complete with ``README.md`` file.
4. Provide overview of demonstrated functionality in ``README.md``.
5. With good overview reader should be able to understand what example does without opening the source code.
6. Depending on complexity of example, break down description of code into parts and provide overview of functionality of each part.
7. Include flow diagram and screenshots of application output if applicable.
8. Finally add in this section synopsis of each example together with link to respective folder in ``esp-idf/examples/``.
API Reference
-------------
.. highlight:: none
.. note::
*INSTRUCTIONS*
1. Specify the names of header files used to generate this reference. Each name should be linked to the source on `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository.
2. Provide list of API members divided into sections.
3. Use corresponding ``.. doxygen..`` directives, so member documentation is auto updated.
*INSTRUCTIONS*
* Data Structures -``.. doxygenstruct::`` together with ``:members:``
* Macros - ``.. doxygendefine::``
* Type Definitions - ``.. doxygentypedef::``
* Enumerations - ``.. doxygenenum::``
* Functions - ``.. doxygenfunction::``
1. This repository provides for automatic update of API reference documentation using :doc:`code markup retrieved by Doxygen from header files <../contribute/documenting-code>`.
2. Update is done on each documentation build by invoking script :idf_file:`docs/gen-dxd.py` for all header files listed in the ``INPUT`` statement of :idf_file:`docs/Doxyfile`.
3. Each line of the ``INPUT`` statement (other than a comment that begins with ``##``) contains a path to header file ``*.h`` that will be used to generate corresponding ``*.inc`` files::
See `Breathe documentation <https://breathe.readthedocs.io/en/latest/directives.html>`_ for additional information.
##
## Wi-Fi - API Reference
##
../components/esp32/include/esp_wifi.h \
../components/esp32/include/esp_smartconfig.h \
4. Once done remove superfluous headers.
5. When changes are committed and documentation is build, check how this section rendered. :doc:`Correct annotations <../contribute/documenting-code>` in respective header files, if required.
4. The ``*.inc`` files contain formatted reference of API members generated automatically on each documentation build. All ``*.inc`` files are placed in Sphinx ``_build`` directory. To see directives generated for e.g. ``esp_wifi.h``, run ``python gen-dxd.py esp32/include/esp_wifi.h``.
Header Files
^^^^^^^^^^^^
5. To show contents of ``*.inc`` file in documentation, include it as follows::
* `path/header-file.h`
.. include:: /_build/inc/esp_wifi.inc
Data Structures
^^^^^^^^^^^^^^^
For example see :idf_file:`docs/api-reference/wifi/esp_wifi.rst`
6. Optionally, rather that using ``*.inc`` files, you may want to describe API in you own way. See :idf_file:`docs/api-reference/system/deep_sleep.rst` for example.
::
Below is the list of common ``.. doxygen...::`` directives:
.. doxygenstruct:: name_of_structure
:members:
* Functions - ``.. doxygenfunction:: name_of_function``
* Unions -``.. doxygenunion:: name_of_union``
* Structures -``.. doxygenstruct:: name_of_structure`` together with ``:members:``
* Macros - ``.. doxygendefine:: name_of_define``
* Type Definitions - ``.. doxygentypedef:: name_of_type``
* Enumerations - ``.. doxygenenum:: name_of_enumeration``
Macros
^^^^^^
See `Breathe documentation <https://breathe.readthedocs.io/en/latest/directives.html>`_ for additional information.
::
To provide a link to header file, use the :ref:`link custom role <link-custom-roles>` as follows::
.. doxygendefine:: name_of_macro
* :component_file:`path_to/header_file.h`
Type Definitions
^^^^^^^^^^^^^^^^
::
.. doxygentypedef:: name_of_type
Enumerations
^^^^^^^^^^^^
::
.. doxygenenum:: name_of_enumeration
Functions
^^^^^^^^^
::
.. doxygenfunction:: name_of_function
7. In any case, to generate API reference, the file :idf_file:`docs/Doxyfile` should be updated with paths to ``*.h`` headers that are being documented.
8. When changes are committed and documentation is build, check how this section has been rendered. :doc:`Correct annotations <../contribute/documenting-code>` in respective header files, if required.

20
docs/api-reference/wifi/esp_smartconfig.rst
View File

@ -4,22 +4,4 @@ Smart Config
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`esp32/include/esp_smartconfig.h`
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: sc_callback_t
Functions
^^^^^^^^^
.. doxygenfunction:: esp_smartconfig_get_version
.. doxygenfunction:: esp_smartconfig_start
.. doxygenfunction:: esp_smartconfig_stop
.. doxygenfunction:: esp_esptouch_set_timeout
.. doxygenfunction:: esp_smartconfig_set_type
.. doxygenfunction:: esp_smartconfig_fast_mode
.. include:: /_build/inc/esp_smartconfig.inc

71
docs/api-reference/wifi/esp_wifi.rst
View File

@ -8,71 +8,18 @@ Overview
.. _Instructions: ../template.html
Application Example
-------------------
Application Examples
--------------------
See :example:`wifi` directory of ESP-IDF examples that contains the following applications:
* Simple application showing how to connect ESP32 module to an Access Point - `esp-idf-template <https://github.com/espressif/esp-idf-template>`_.
* Using power save mode of Wi-Fi - :example:`wifi/power_save`.
Simple code showing how to connect ESP32 module to an Access Point: `esp-idf-template <https://github.com/espressif/esp-idf-template>`_.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`esp32/include/esp_wifi.h`
Macros
------
.. doxygendefine:: WIFI_INIT_CONFIG_DEFAULT
Type Definitions
----------------
.. doxygentypedef:: wifi_promiscuous_cb_t
.. doxygentypedef:: esp_vendor_ie_cb_t
Functions
---------
.. doxygenfunction:: esp_wifi_init
.. doxygenfunction:: esp_wifi_deinit
.. doxygenfunction:: esp_wifi_set_mode
.. doxygenfunction:: esp_wifi_get_mode
.. doxygenfunction:: esp_wifi_start
.. doxygenfunction:: esp_wifi_stop
.. doxygenfunction:: esp_wifi_connect
.. doxygenfunction:: esp_wifi_disconnect
.. doxygenfunction:: esp_wifi_clear_fast_connect
.. doxygenfunction:: esp_wifi_deauth_sta
.. doxygenfunction:: esp_wifi_scan_start
.. doxygenfunction:: esp_wifi_scan_stop
.. doxygenfunction:: esp_wifi_scan_get_ap_num
.. doxygenfunction:: esp_wifi_scan_get_ap_records
.. doxygenfunction:: esp_wifi_sta_get_ap_info
.. doxygenfunction:: esp_wifi_set_ps
.. doxygenfunction:: esp_wifi_get_ps
.. doxygenfunction:: esp_wifi_set_protocol
.. doxygenfunction:: esp_wifi_get_protocol
.. doxygenfunction:: esp_wifi_set_bandwidth
.. doxygenfunction:: esp_wifi_get_bandwidth
.. doxygenfunction:: esp_wifi_set_channel
.. doxygenfunction:: esp_wifi_get_channel
.. doxygenfunction:: esp_wifi_set_country
.. doxygenfunction:: esp_wifi_get_country
.. doxygenfunction:: esp_wifi_set_mac
.. doxygenfunction:: esp_wifi_get_mac
.. doxygenfunction:: esp_wifi_set_promiscuous_rx_cb
.. doxygenfunction:: esp_wifi_set_promiscuous
.. doxygenfunction:: esp_wifi_get_promiscuous
.. doxygenfunction:: esp_wifi_set_config
.. doxygenfunction:: esp_wifi_get_config
.. doxygenfunction:: esp_wifi_ap_get_sta_list
.. doxygenfunction:: esp_wifi_set_storage
.. doxygenfunction:: esp_wifi_set_auto_connect
.. doxygenfunction:: esp_wifi_get_auto_connect
.. doxygenfunction:: esp_wifi_set_vendor_ie
.. doxygenfunction:: esp_wifi_set_vendor_ie_cb
.. include:: /_build/inc/esp_wifi.inc

14
docs/conf.py
View File

@ -12,8 +12,7 @@
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
import sys, os
import re
from subprocess import call, Popen, PIPE
import shlex
@ -24,10 +23,16 @@ import shlex
sys.path.insert(0, os.path.abspath('.'))
from repo_util import run_cmd_get_output
# -- Run DoxyGen to prepare XML for Sphinx---------------------------------
# ref. https://github.com/rtfd/readthedocs.org/issues/388
# Call Doxygen to get XML files from the header files
print "Calling Doxygen to generate latest XML files"
call('doxygen')
# Generate 'api_name.inc' files using the XML files by Doxygen
os.system("python gen-dxd.py")
# http://stackoverflow.com/questions/12772927/specifying-an-online-image-in-sphinx-restructuredtext-format
#
suppress_warnings = ['image.nonlocal_uri']
# -- General configuration ------------------------------------------------
@ -290,3 +295,4 @@ if not on_rtd: # only import and set the theme if we're building docs locally
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# otherwise, readthedocs.org uses their theme by default, so no need to specify it

38
docs/contribute/documenting-code.rst
View File

@ -95,7 +95,7 @@ There is couple of tips, how you can make your documentation even better and mor
* @endcode
*
The code snippet should be enclosed in a comment block of the function that it illustrates.
The code snippet should be enclosed in a comment block of the function that it illustrates.
2. To highlight some important information use command ``@attention`` or ``@note``. ::
@ -105,9 +105,24 @@ There is couple of tips, how you can make your documentation even better and mor
* 2. If the ESP32 is connected to an AP, call esp_wifi_disconnect to disconnect.
*
Above example also shows how to use a numbered list.
Above example also shows how to use a numbered list.
3. Use markdown to make your documentation even more readable. You will add headers, links, tables and more. ::
3. To provide common description to a group of similar functions, enclose them using ``/**@{*/`` and ``/**@}*/`` markup commands::
/**@{*/
/**
* @brief common description of similar functions
*
*/
void first_similar_function (void);
void second_similar_function (void);
/**@}*/
For practical example see :component_file:`nvs_flash/include/nvs.h`.
4. You may want to go even further and skip some code like e.g. repetitive defines or enumerations. In such case enclose the code within ``/** @cond */`` and ``/** @endcond */`` commands. Example of such implementation is provided in :component_file:`driver/include/driver/gpio.h`.
5. Use markdown to make your documentation even more readable. You will add headers, links, tables and more. ::
*
* [ESP32 Technical Reference](http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf)
@ -117,8 +132,9 @@ There is couple of tips, how you can make your documentation even better and mor
Code snippets, notes, links, etc. will not make it to the documentation, if not enclosed in a comment block associated with one of documented objects.
4. Prepare one or more complete code examples together with description. Place description in a separate file ``README.md`` in specific folder of :idf:`examples` directory.
6. Prepare one or more complete code examples together with description. Place description in a separate file ``README.md`` in specific folder of :idf:`examples` directory.
.. _link-custom-roles:
Linking Examples
----------------
@ -128,13 +144,13 @@ When linking to examples on GitHub do not use absolute / hadcoded URLs. Instead,
The following roles are provided:
- ``:idf:`path``` - points to directory inside ESP-IDF
- ``:idf_blob:`path``` - points to file inside ESP-IDF
- ``:idf_file:`path``` - points to file inside ESP-IDF
- ``:idf_raw:`path``` - points to raw view of the file inside ESP-IDF
- ``:component:`path``` - points to directory inside ESP-IDF components dir
- ``:component_blob:`path``` - points to file inside ESP-IDF components dir
- ``:component_file:`path``` - points to file inside ESP-IDF components dir
- ``:component_raw:`path``` - points to raw view of the file inside ESP-IDF components dir
- ``:example:`path``` - points to directory inside ESP-IDF examples dir
- ``:example_blob:`path``` - points to file inside ESP-IDF examples dir
- ``:example_file:`path``` - points to file inside ESP-IDF examples dir
- ``:example_raw:`path``` - points to raw view of the file inside ESP-IDF examples dir
A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: ``cd docs`` and then ``make gh-linkcheck``.
@ -170,4 +186,12 @@ We love it even better, if it is well documented, so we can quickly make it run
Go ahead, contribute your code and documentation!
Related Documents
-----------------
* :doc:`../api-reference/template`
.. _espressif/esp-idf: https://github.com/espressif/esp-idf/

58
docs/doxygen_xml_to_rst.xslt
View File

@ -1,58 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- This XSL transform converts Doxygen XML output for a header file into Sphinx/Breathe compatible list of APIs -->
<!-- Usage: xsltproc doxygen_xml_to_rst.xslt xml/esp__xxxx_8h.xml -->
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="text" encoding="UTF-8"/>
<xsl:template match="/">
<xsl:text>Macros&#xA;</xsl:text>
<xsl:text>^^^^^^&#xA;&#xA;</xsl:text>
<xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='define']">
<xsl:text>.. doxygendefine:: </xsl:text>
<xsl:value-of select="name"/>
<xsl:text>&#xA;</xsl:text>
</xsl:for-each>
<xsl:text>&#xA;</xsl:text>
<xsl:text>Type Definitions&#xA;</xsl:text>
<xsl:text>^^^^^^^^^^^^^^^^&#xA;&#xA;</xsl:text>
<xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='typedef']">
<xsl:text>.. doxygentypedef:: </xsl:text>
<xsl:value-of select="name"/>
<xsl:text>&#xA;</xsl:text>
</xsl:for-each>
<xsl:text>&#xA;</xsl:text>
<xsl:text>Enumerations&#xA;</xsl:text>
<xsl:text>^^^^^^^^^^^^&#xA;&#xA;</xsl:text>
<xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='enum']">
<xsl:text>.. doxygenenum:: </xsl:text>
<xsl:value-of select="name"/>
<xsl:text>&#xA;</xsl:text>
</xsl:for-each>
<xsl:text>&#xA;</xsl:text>
<!-- TODO: figure out why structures are listed as innerclass instances -->
<xsl:text>Structures&#xA;</xsl:text>
<xsl:text>^^^^^^^^^^&#xA;&#xA;</xsl:text>
<xsl:for-each select="doxygen/compounddef/innerclass">
<xsl:text>.. doxygenstruct:: </xsl:text>
<xsl:value-of select="."/>
<xsl:text>&#xA;</xsl:text>
<xsl:text> :members:&#xA;</xsl:text>
<xsl:text>&#xA;</xsl:text>
</xsl:for-each>
<xsl:text>&#xA;</xsl:text>
<xsl:text>Functions&#xA;</xsl:text>
<xsl:text>^^^^^^^^^&#xA;&#xA;</xsl:text>
<xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='function']">
<xsl:text>.. doxygenfunction:: </xsl:text>
<xsl:value-of select="name"/>
<xsl:text>&#xA;</xsl:text>
</xsl:for-each>
<xsl:text>&#xA;</xsl:text>
</xsl:template>
</xsl:stylesheet>

301
docs/gen-dxd.py Normal file
View File

@ -0,0 +1,301 @@
# gen-dxd.py - Generate Doxygen Directives
#
# This code is in the Public Domain (or CC0 licensed, at your option.)
# Unless required by applicable law or agreed to in writing, this
# software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
# CONDITIONS OF ANY KIND, either express or implied.
#
import sys
import os
import re
# Script configuration
header_file_path_prefix = "../components/"
"""string: path prefix for header files.
"""
doxyfile_path = "Doxyfile"
"""string: path to a file containing header files to processs.
"""
xml_directory_path = "xml"
"""string: path to directory with XML files by Doxygen.
"""
inc_directory_path = "_build/inc"
"""string: path prefix for header files.
"""
all_kinds = [
("function", "Functions"),
("union", "Unions"),
("struct", "Structures"),
("define", "Macros"),
("typedef", "Type Definitions"),
("enum", "Enumerations")
]
"""list of items that will be generated for a single API file
"""
def get_doxyfile_input():
"""Get contents of Doxyfile's INPUT statement.
Returns:
Contents of Doxyfile's INPUT.
"""
if not os.path.isfile(doxyfile_path):
print "Doxyfile '%s' does not exist!" % doxyfile_path
sys.exit()
print "Getting Doxyfile's INPUT"
input_file = open(doxyfile_path, "r")
line = input_file.readline()
# read contents of Doxyfile until 'INPUT' statement
while line:
if line.find("INPUT") == 0:
break
line = input_file.readline()
doxyfile_INPUT = ""
line = input_file.readline()
# skip input_file contents until end of 'INPUT' statement
while line:
if line.isspace():
# we have reached the end of 'INPUT' statement
break
# process only lines that are not comments
if line.find("#") == -1:
# extract header file path inside components folder
m = re.search(header_file_path_prefix + "(.*\.h)", line)
header_file_path = m.group(1)
doxyfile_INPUT += header_file_path + "\n"
# proceed reading next line
line = input_file.readline()
input_file.close()
return doxyfile_INPUT
def get_api_name(header_file_path):
"""Get name of API from header file path.
Args:
header_file_path: path to the header file.
Returns:
The name of API.
"""
api_name = ""
regex = r".*/(.*)\.h"
m = re.search(regex, header_file_path)
if m:
api_name = m.group(1)
return api_name
def get_rst_header(header_name):
"""Get rst formatted code with a header.
Args:
header_name: name of header.
Returns:
Formatted rst code with the header.
"""
rst_output = ""
rst_output += header_name + "\n"
rst_output += "^" * len(header_name) + "\n"
rst_output += "\n"
return rst_output
def select_unions(innerclass_list):
"""Select unions from innerclass list.
Args:
innerclass_list: raw list with unions and structures
extracted from Dogygen's xml file.
Returns:
Doxygen directives with unions selected from the list.
"""
rst_output = ""
for line in innerclass_list.splitlines():
# union is denoted by "union" at the beginning of line
if line.find("union") == 0:
union_id, union_name = re.split(r"\t+", line)
rst_output += ".. doxygenunion:: "
rst_output += union_name
rst_output += "\n"
return rst_output
def select_structs(innerclass_list):
"""Select structures from innerclass list.
Args:
innerclass_list: raw list with unions and structures
extracted from Dogygen's xml file.
Returns:
Doxygen directives with structures selected from the list.
Note: some structures are excluded as described on code below.
"""
rst_output = ""
for line in innerclass_list.splitlines():
# structure is denoted by "struct" at the beginning of line
if line.find("struct") == 0:
# skip structures that are part of union
# they are documented by 'doxygenunion' directive
if line.find("::") > 0:
continue
struct_id, struct_name = re.split(r"\t+", line)
rst_output += ".. doxygenstruct:: "
rst_output += struct_name
rst_output += "\n"
rst_output += " :members:\n"
rst_output += "\n"
return rst_output
def get_directives(tree, kind):
"""Get directives for specific 'kind'.
Args:
tree: the ElementTree 'tree' of XML by Doxygen
kind: name of API "kind" to be generated
Returns:
Doxygen directives for selected 'kind'.
Note: the header with "kind" name is included.
"""
rst_output = ""
if kind in ["union", "struct"]:
innerclass_list = ""
for elem in tree.iterfind('compounddef/innerclass'):
innerclass_list += elem.attrib["refid"] + "\t" + elem.text + "\n"
if kind == "union":
rst_output += select_unions(innerclass_list)
else:
rst_output += select_structs(innerclass_list)
else:
for elem in tree.iterfind(
'compounddef/sectiondef/memberdef[@kind="%s"]' % kind):
name = elem.find('name')
rst_output += ".. doxygen%s:: " % kind
rst_output += name.text + "\n"
if rst_output:
all_kinds_dict = dict(all_kinds)
rst_output = get_rst_header(all_kinds_dict[kind]) + rst_output + "\n"
return rst_output
def generate_directives(header_file_path):
"""Generate API reference with Doxygen directives for a header file.
Args:
header_file_path: a path to the header file with API.
Returns:
Doxygen directives for the header file.
"""
api_name = get_api_name(header_file_path)
# in XLT file name each "_" in the api name is expanded by Doxygen to "__"
xlt_api_name = api_name.replace("_", "__")
xml_file_path = "%s/%s_8h.xml" % (xml_directory_path, xlt_api_name)
rst_output = ""
rst_output = ".. File automatically generated by 'gen-dxd.py'\n"
rst_output += "\n"
rst_output += get_rst_header("Header File")
rst_output += "* :component_file:`" + header_file_path + "`\n"
rst_output += "\n"
try:
import xml.etree.cElementTree as ET
except ImportError:
import xml.etree.ElementTree as ET
tree = ET.ElementTree(file=xml_file_path)
for i in range(len(all_kinds)):
kind = all_kinds[i][0]
rst_output += get_directives(tree, kind)
return rst_output
def generate_api_inc_files():
"""Generate header_file.inc files
with API reference made of doxygen directives
for each header file
specified in the 'INPUT' statement of Doxyfile.
"""
if not os.path.isdir(xml_directory_path):
print "Directory %s does not exist!" % xml_directory_path
sys.exit()
if not os.path.exists(inc_directory_path):
os.makedirs(inc_directory_path)
list_to_generate = get_doxyfile_input()
print "Generating 'api_name.inc' files with Doxygen directives"
for header_file_path in list_to_generate.splitlines():
api_name = get_api_name(header_file_path)
inc_file_path = inc_directory_path + "/" + api_name + ".inc"
rst_output = generate_directives(header_file_path)
inc_file = open(inc_file_path, "w")
inc_file.write(rst_output)
inc_file.close()
if __name__ == "__main__":
"""The main script that generates
Doxygen directives.
"""
# Process command line arguments, if any
if len(sys.argv) > 1:
if not os.path.isdir(xml_directory_path):
print "Directory %s does not exist!" % xml_directory_path
sys.exit()
header_file_path = sys.argv[1]
api_name = get_api_name(header_file_path)
if api_name:
rst_output = generate_directives(header_file_path)
print "Doxygen directives for '%s'" % header_file_path
print
print rst_output
else:
print "Options to execute 'gen-dxd.py' application:"
print "1: $ python gen-dxd.py"
print " Generate API 'header_file.inc' files for headers defined in '%s'" % doxyfile_path
print "2: $ python gen-dxd.py header_file_path"
print " Print out Doxygen directives for a single header file"
print " example: $ python gen-dxd.py mdns/include/mdns.h"
print " NOTE: Run Doxygen first to get XML files for the header file"
sys.exit()
# No command line arguments given
generate_api_inc_files()

3
docs/hw-reference/index.rst
View File

@ -7,6 +7,7 @@ Hardware Reference
Technical Reference Manual (PDF) <http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
Pin List and Functions (PDF) <http://espressif.com/sites/default/files/documentation/esp32_chip_pin_list_en.pdf>
Chip Pinout (PDF) <http://espressif.com/sites/default/files/documentation/esp32_pinout_v1_0.pdf>
ESP32 Hardware Design Guidelines (PDF) <http://espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf>
Silicon Errata (PDF) <http://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>
Modules and Boards <modules-and-boards>