diff --git a/.gitignore b/.gitignore index 5490ebb93..e571eeb68 100644 --- a/.gitignore +++ b/.gitignore @@ -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/ diff --git a/components/driver/include/driver/dac.h b/components/driver/include/driver/dac.h index 07e1ff80d..842894d0e 100644 --- a/components/driver/include/driver/dac.h +++ b/components/driver/include/driver/dac.h @@ -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. diff --git a/components/driver/include/driver/gpio.h b/components/driver/include/driver/gpio.h index 33f87bdfa..53f2021a1 100644 --- a/components/driver/include/driver/gpio.h +++ b/components/driver/include/driver/gpio.h @@ -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 { diff --git a/components/driver/include/driver/spi_common.h b/components/driver/include/driver/spi_common.h index 5d4270fd1..53cde6ffa 100644 --- a/components/driver/include/driver/spi_common.h +++ b/components/driver/include/driver/spi_common.h @@ -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 \ No newline at end of file +#endif diff --git a/components/ethernet/include/eth_phy/phy.h b/components/ethernet/include/eth_phy/phy.h index 44edd7491..18b8f3f6c 100644 --- a/components/ethernet/include/eth_phy/phy.h +++ b/components/ethernet/include/eth_phy/phy.h @@ -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); diff --git a/components/ethernet/include/eth_phy/phy_lan8720.h b/components/ethernet/include/eth_phy/phy_lan8720.h index 7bde42eca..8c579ef5e 100644 --- a/components/ethernet/include/eth_phy/phy_lan8720.h +++ b/components/ethernet/include/eth_phy/phy_lan8720.h @@ -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. diff --git a/components/ethernet/include/eth_phy/phy_tlk110.h b/components/ethernet/include/eth_phy/phy_tlk110.h index 1019044e9..ff61c322c 100644 --- a/components/ethernet/include/eth_phy/phy_tlk110.h +++ b/components/ethernet/include/eth_phy/phy_tlk110.h @@ -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. diff --git a/components/vfs/README.rst b/components/vfs/README.rst index 26d857fc8..318004c25 100644 --- a/components/vfs/README.rst +++ b/components/vfs/README.rst @@ -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: diff --git a/docs/Doxyfile b/docs/Doxyfile old mode 100755 new mode 100644 index 9b7d602b9..b5ca4b7f8 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -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" + diff --git a/docs/Makefile b/docs/Makefile index 8076416b7..cc32abbd5 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -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"; \ diff --git a/docs/_static/about-doc.png b/docs/_static/about-doc.png index 4af663dbf..f52f1658a 100644 Binary files a/docs/_static/about-doc.png and b/docs/_static/about-doc.png differ diff --git a/docs/api-guides/build-system.rst b/docs/api-guides/build-system.rst index aa4a67032..51aacb7bb 100644 --- a/docs/api-guides/build-system.rst +++ b/docs/api-guides/build-system.rst @@ -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 diff --git a/docs/api-reference/bluetooth/controller_vhci.rst b/docs/api-reference/bluetooth/controller_vhci.rst index 6241adfbd..17680a587 100644 --- a/docs/api-reference/bluetooth/controller_vhci.rst +++ b/docs/api-reference/bluetooth/controller_vhci.rst @@ -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 diff --git a/docs/api-reference/bluetooth/esp_a2dp.rst b/docs/api-reference/bluetooth/esp_a2dp.rst index 24fe4c953..ee30b6deb 100644 --- a/docs/api-reference/bluetooth/esp_a2dp.rst +++ b/docs/api-reference/bluetooth/esp_a2dp.rst @@ -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 diff --git a/docs/api-reference/bluetooth/esp_avrc.rst b/docs/api-reference/bluetooth/esp_avrc.rst index 8e6be3719..ca4993de1 100644 --- a/docs/api-reference/bluetooth/esp_avrc.rst +++ b/docs/api-reference/bluetooth/esp_avrc.rst @@ -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 - diff --git a/docs/api-reference/bluetooth/esp_blufi.rst b/docs/api-reference/bluetooth/esp_blufi.rst index bc95abf9f..a9c5c5e0e 100644 --- a/docs/api-reference/bluetooth/esp_blufi.rst +++ b/docs/api-reference/bluetooth/esp_blufi.rst @@ -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 diff --git a/docs/api-reference/bluetooth/esp_bt_defs.rst b/docs/api-reference/bluetooth/esp_bt_defs.rst index 0c13378fa..58b2ad03e 100644 --- a/docs/api-reference/bluetooth/esp_bt_defs.rst +++ b/docs/api-reference/bluetooth/esp_bt_defs.rst @@ -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 diff --git a/docs/api-reference/bluetooth/esp_bt_device.rst b/docs/api-reference/bluetooth/esp_bt_device.rst index 8f5a8a4c7..936b5a318 100644 --- a/docs/api-reference/bluetooth/esp_bt_device.rst +++ b/docs/api-reference/bluetooth/esp_bt_device.rst @@ -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 diff --git a/docs/api-reference/bluetooth/esp_bt_main.rst b/docs/api-reference/bluetooth/esp_bt_main.rst index 1c085a134..06055ffad 100644 --- a/docs/api-reference/bluetooth/esp_bt_main.rst +++ b/docs/api-reference/bluetooth/esp_bt_main.rst @@ -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 - diff --git a/docs/api-reference/bluetooth/esp_gap_ble.rst b/docs/api-reference/bluetooth/esp_gap_ble.rst index 02a12833a..9d0b50322 100644 --- a/docs/api-reference/bluetooth/esp_gap_ble.rst +++ b/docs/api-reference/bluetooth/esp_gap_ble.rst @@ -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 diff --git a/docs/api-reference/bluetooth/esp_gap_bt.rst b/docs/api-reference/bluetooth/esp_gap_bt.rst index 8f5314e10..38b005b31 100644 --- a/docs/api-reference/bluetooth/esp_gap_bt.rst +++ b/docs/api-reference/bluetooth/esp_gap_bt.rst @@ -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 diff --git a/docs/api-reference/bluetooth/esp_gatt_defs.rst b/docs/api-reference/bluetooth/esp_gatt_defs.rst index 11cb64027..fd383ab72 100644 --- a/docs/api-reference/bluetooth/esp_gatt_defs.rst +++ b/docs/api-reference/bluetooth/esp_gatt_defs.rst @@ -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 diff --git a/docs/api-reference/bluetooth/esp_gattc.rst b/docs/api-reference/bluetooth/esp_gattc.rst index 755e7dc71..6efbc7aff 100644 --- a/docs/api-reference/bluetooth/esp_gattc.rst +++ b/docs/api-reference/bluetooth/esp_gattc.rst @@ -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 diff --git a/docs/api-reference/bluetooth/esp_gatts.rst b/docs/api-reference/bluetooth/esp_gatts.rst index 8f0414d67..3b0fb4532 100644 --- a/docs/api-reference/bluetooth/esp_gatts.rst +++ b/docs/api-reference/bluetooth/esp_gatts.rst @@ -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 diff --git a/docs/api-reference/bluetooth/index.rst b/docs/api-reference/bluetooth/index.rst index db92ee8c2..e24c1fab1 100644 --- a/docs/api-reference/bluetooth/index.rst +++ b/docs/api-reference/bluetooth/index.rst @@ -7,7 +7,7 @@ Bluetooth API Bluetooth Controller && VHCI Bluetooth Common Bluetooth LE - Bluetooth Classic BT + Bluetooth Classic Example code for this API section is provided in :example:`bluetooth` directory of ESP-IDF examples. diff --git a/docs/api-reference/ethernet/esp_eth.rst b/docs/api-reference/ethernet/esp_eth.rst index 223c7b226..4025ed231 100644 --- a/docs/api-reference/ethernet/esp_eth.rst +++ b/docs/api-reference/ethernet/esp_eth.rst @@ -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 + + diff --git a/docs/api-reference/index.rst b/docs/api-reference/index.rst index 28bb8b250..104df9231 100644 --- a/docs/api-reference/index.rst +++ b/docs/api-reference/index.rst @@ -9,6 +9,7 @@ API Reference Bluetooth Ethernet Peripherals - System - Storage Protocols + Storage + System + diff --git a/docs/api-reference/peripherals/adc.rst b/docs/api-reference/peripherals/adc.rst index 8d598f327..122848f45 100644 --- a/docs/api-reference/peripherals/adc.rst +++ b/docs/api-reference/peripherals/adc.rst @@ -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 diff --git a/docs/api-reference/peripherals/dac.rst b/docs/api-reference/peripherals/dac.rst index 905b9b21e..7d860f3bf 100644 --- a/docs/api-reference/peripherals/dac.rst +++ b/docs/api-reference/peripherals/dac.rst @@ -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 - \ No newline at end of file diff --git a/docs/api-reference/peripherals/gpio.rst b/docs/api-reference/peripherals/gpio.rst index 16d012084..9cb78f6f1 100644 --- a/docs/api-reference/peripherals/gpio.rst +++ b/docs/api-reference/peripherals/gpio.rst @@ -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 diff --git a/docs/api-reference/peripherals/i2c.rst b/docs/api-reference/peripherals/i2c.rst index bd30a345d..130119fd3 100644 --- a/docs/api-reference/peripherals/i2c.rst +++ b/docs/api-reference/peripherals/i2c.rst @@ -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 diff --git a/docs/api-reference/peripherals/i2s.rst b/docs/api-reference/peripherals/i2s.rst index 3d05f129b..f3d372978 100644 --- a/docs/api-reference/peripherals/i2s.rst +++ b/docs/api-reference/peripherals/i2s.rst @@ -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 diff --git a/docs/api-reference/peripherals/index.rst b/docs/api-reference/peripherals/index.rst index c0cb3008d..491d98033 100644 --- a/docs/api-reference/peripherals/index.rst +++ b/docs/api-reference/peripherals/index.rst @@ -10,12 +10,13 @@ Peripherals API I2C I2S LED Control + MCPWM Pulse Counter + Remote Control SD/MMC Card Host <../storage/sdmmc> Sigma-delta Modulation SPI Master SPI Slave - Remote Control Timer UART diff --git a/docs/api-reference/peripherals/ledc.rst b/docs/api-reference/peripherals/ledc.rst index a1a96543d..c30aa2dac 100644 --- a/docs/api-reference/peripherals/ledc.rst +++ b/docs/api-reference/peripherals/ledc.rst @@ -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 diff --git a/docs/api/peripherals/mcpwm.rst b/docs/api-reference/peripherals/mcpwm.rst similarity index 56% rename from docs/api/peripherals/mcpwm.rst rename to docs/api-reference/peripherals/mcpwm.rst index a6533e6a8..6e208436a 100644 --- a/docs/api/peripherals/mcpwm.rst +++ b/docs/api-reference/peripherals/mcpwm.rst @@ -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 - diff --git a/docs/api-reference/peripherals/pcnt.rst b/docs/api-reference/peripherals/pcnt.rst index 63e6ad644..23123bd85 100644 --- a/docs/api-reference/peripherals/pcnt.rst +++ b/docs/api-reference/peripherals/pcnt.rst @@ -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 diff --git a/docs/api-reference/peripherals/rmt.rst b/docs/api-reference/peripherals/rmt.rst index 276ed939e..5097a5f0e 100644 --- a/docs/api-reference/peripherals/rmt.rst +++ b/docs/api-reference/peripherals/rmt.rst @@ -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 diff --git a/docs/api-reference/peripherals/sigmadelta.rst b/docs/api-reference/peripherals/sigmadelta.rst index d2e423deb..a70decea6 100644 --- a/docs/api-reference/peripherals/sigmadelta.rst +++ b/docs/api-reference/peripherals/sigmadelta.rst @@ -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 diff --git a/docs/api-reference/peripherals/spi_master.rst b/docs/api-reference/peripherals/spi_master.rst index 31fca3996..bc7a0b4e7 100644 --- a/docs/api-reference/peripherals/spi_master.rst +++ b/docs/api-reference/peripherals/spi_master.rst @@ -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 diff --git a/docs/api-reference/peripherals/spi_slave.rst b/docs/api-reference/peripherals/spi_slave.rst index fc0e212cd..76f44c494 100644 --- a/docs/api-reference/peripherals/spi_slave.rst +++ b/docs/api-reference/peripherals/spi_slave.rst @@ -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 diff --git a/docs/api-reference/peripherals/timer.rst b/docs/api-reference/peripherals/timer.rst index 7b5253fde..5c833ebc0 100644 --- a/docs/api-reference/peripherals/timer.rst +++ b/docs/api-reference/peripherals/timer.rst @@ -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 diff --git a/docs/api-reference/peripherals/uart.rst b/docs/api-reference/peripherals/uart.rst index 1392361d9..921b5eb63 100644 --- a/docs/api-reference/peripherals/uart.rst +++ b/docs/api-reference/peripherals/uart.rst @@ -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 diff --git a/docs/api-reference/protocols/mdns.rst b/docs/api-reference/protocols/mdns.rst index 1355642de..751fb0776 100644 --- a/docs/api-reference/protocols/mdns.rst +++ b/docs/api-reference/protocols/mdns.rst @@ -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 - diff --git a/docs/api-reference/storage/fatfs.rst b/docs/api-reference/storage/fatfs.rst index b6735b7c0..9ea2c0685 100644 --- a/docs/api-reference/storage/fatfs.rst +++ b/docs/api-reference/storage/fatfs.rst @@ -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 diff --git a/docs/api-reference/storage/index.rst b/docs/api-reference/storage/index.rst index a1d3f553d..9c4394bd5 100644 --- a/docs/api-reference/storage/index.rst +++ b/docs/api-reference/storage/index.rst @@ -5,7 +5,7 @@ Storage API :maxdepth: 1 SPI Flash and Partition APIs - SD/MMC + SD/MMC Card Host Non-Volatile Storage Virtual Filesystem FAT Filesystem diff --git a/docs/api-reference/storage/nvs_flash.rst b/docs/api-reference/storage/nvs_flash.rst index b6cf6f221..005b9b04f 100644 --- a/docs/api-reference/storage/nvs_flash.rst +++ b/docs/api-reference/storage/nvs_flash.rst @@ -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 diff --git a/docs/api-reference/storage/spi_flash.rst b/docs/api-reference/storage/spi_flash.rst index c43af4d8c..e95d93883 100644 --- a/docs/api-reference/storage/spi_flash.rst +++ b/docs/api-reference/storage/spi_flash.rst @@ -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 ` 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 + + diff --git a/docs/api-reference/storage/vfs.rst b/docs/api-reference/storage/vfs.rst index 0035229d8..c59177cde 100644 --- a/docs/api-reference/storage/vfs.rst +++ b/docs/api-reference/storage/vfs.rst @@ -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 diff --git a/docs/api-reference/storage/wear-levelling.rst b/docs/api-reference/storage/wear-levelling.rst index 0766087df..63dc44058 100644 --- a/docs/api-reference/storage/wear-levelling.rst +++ b/docs/api-reference/storage/wear-levelling.rst @@ -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 diff --git a/docs/api-reference/system/base_mac_address.rst b/docs/api-reference/system/base_mac_address.rst index 37cf2bcbb..abb4781d8 100644 --- a/docs/api-reference/system/base_mac_address.rst +++ b/docs/api-reference/system/base_mac_address.rst @@ -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`. +A `definition of local vs universal MAC address can be found on Wikipedia `_. 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 \ No newline at end of file +.. doxygenfunction:: esp_efuse_mac_get_custom diff --git a/docs/api-reference/system/intr_alloc.rst b/docs/api-reference/system/intr_alloc.rst index 8abe47e0f..7411c4936 100644 --- a/docs/api-reference/system/intr_alloc.rst +++ b/docs/api-reference/system/intr_alloc.rst @@ -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 ` 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 diff --git a/docs/api-reference/system/log.rst b/docs/api-reference/system/log.rst index 8aadeac09..c9883693c 100644 --- a/docs/api-reference/system/log.rst +++ b/docs/api-reference/system/log.rst @@ -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 diff --git a/docs/api-reference/system/mem_alloc.rst b/docs/api-reference/system/mem_alloc.rst index 35868f755..cba326ad1 100644 --- a/docs/api-reference/system/mem_alloc.rst +++ b/docs/api-reference/system/mem_alloc.rst @@ -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 diff --git a/docs/api-reference/system/ota.rst b/docs/api-reference/system/ota.rst index 0ecb01d4e..d7dbb5978 100644 --- a/docs/api-reference/system/ota.rst +++ b/docs/api-reference/system/ota.rst @@ -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 diff --git a/docs/api-reference/template.rst b/docs/api-reference/template.rst index 931ead75e..ccfadb4b1 100644 --- a/docs/api-reference/template.rst +++ b/docs/api-reference/template.rst @@ -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 `_: + 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 `_: - * ``#`` 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 `_ 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 `_ 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 `_ for additional information. -:: + To provide a link to header file, use the :ref:`link custom role ` 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. diff --git a/docs/api-reference/wifi/esp_smartconfig.rst b/docs/api-reference/wifi/esp_smartconfig.rst index 31295a5d4..7ad26f5fb 100644 --- a/docs/api-reference/wifi/esp_smartconfig.rst +++ b/docs/api-reference/wifi/esp_smartconfig.rst @@ -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 diff --git a/docs/api-reference/wifi/esp_wifi.rst b/docs/api-reference/wifi/esp_wifi.rst index 042e810e3..976893e5e 100644 --- a/docs/api-reference/wifi/esp_wifi.rst +++ b/docs/api-reference/wifi/esp_wifi.rst @@ -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 `_. + +* 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 `_. 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 diff --git a/docs/conf.py b/docs/conf.py index 380a64386..120de169a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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 + diff --git a/docs/contribute/documenting-code.rst b/docs/contribute/documenting-code.rst index 8df56e643..459f9c5bc 100644 --- a/docs/contribute/documenting-code.rst +++ b/docs/contribute/documenting-code.rst @@ -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/ + diff --git a/docs/doxygen_xml_to_rst.xslt b/docs/doxygen_xml_to_rst.xslt deleted file mode 100644 index 0212457e5..000000000 --- a/docs/doxygen_xml_to_rst.xslt +++ /dev/null @@ -1,58 +0,0 @@ - - - - - - - - - Macros - ^^^^^^ - - .. doxygendefine:: - - - - - - Type Definitions - ^^^^^^^^^^^^^^^^ - - .. doxygentypedef:: - - - - - - Enumerations - ^^^^^^^^^^^^ - - .. doxygenenum:: - - - - - - - Structures - ^^^^^^^^^^ - - .. doxygenstruct:: - - - :members: - - - - - Functions - ^^^^^^^^^ - - .. doxygenfunction:: - - - - - - - diff --git a/docs/gen-dxd.py b/docs/gen-dxd.py new file mode 100644 index 000000000..4be75915b --- /dev/null +++ b/docs/gen-dxd.py @@ -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() diff --git a/docs/hw-reference/index.rst b/docs/hw-reference/index.rst index 58edfa114..dcd736949 100644 --- a/docs/hw-reference/index.rst +++ b/docs/hw-reference/index.rst @@ -7,6 +7,7 @@ Hardware Reference Technical Reference Manual (PDF) Pin List and Functions (PDF) Chip Pinout (PDF) + ESP32 Hardware Design Guidelines (PDF) Silicon Errata (PDF) Modules and Boards - +