Getting started guides

docs/api-reference/bluetooth/bt_common.rst

@@ -0,0 +1,9 @@
+BT COMMON
+=========
+
+.. toctree::
+   :caption: Bluetooth Common Defines and APIs
+
+   Bluetooth DEFINE <esp_bt_defs>
+   Bluetooth MAIN <esp_bt_main>
+   Bluetooth DEVICE <esp_bt_device>

docs/api-reference/bluetooth/bt_le.rst

@@ -0,0 +1,11 @@
+BT LE
+=========
+
+.. toctree::
+   :caption: Bluetooth LE
+
+   BLE GAP <esp_gap_ble>
+   BLE GATT DEFINE <esp_gatt_defs>
+   BLE GATT SERVER <esp_gatts>
+   BLE GATT CLIENT <esp_gattc>
+   BLE BLUFI <esp_blufi>

docs/api-reference/bluetooth/classic_bt.rst

@@ -0,0 +1,9 @@
+CLASSIC BT
+==========
+
+.. toctree::
+   :caption: Classic BT
+
+   BT GAP <esp_gap_bt>
+   BT A2DP <esp_a2dp>
+   BT AVRC <esp_avrc>

docs/api-reference/bluetooth/controller_vhci.rst

@@ -0,0 +1,59 @@
+Controller && VHCI
+==================
+
+Overview
+--------
+
+`Instructions`_
+
+.. _Instructions: ../template.html
+
+Application Example
+-------------------
+
+Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following example:
+
+: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.
+
+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
+

docs/api-reference/bluetooth/esp_a2dp.rst

@@ -0,0 +1,82 @@
+Bluetooth A2DP API
+==================
+
+Overview
+--------
+
+`Instructions`_
+
+.. _Instructions: ../template.html
+
+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.
+
+
+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
+

docs/api-reference/bluetooth/esp_avrc.rst

@@ -0,0 +1,65 @@
+BT AVRCP APIs
+=============
+
+Overview
+--------
+
+Bluetooth AVRCP reference APIs.
+
+`Instructions`_
+
+Application Example
+-------------------
+
+`Instructions`_
+
+.. _Instructions: ../template.html
+
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :component_file:`bt/bluedroid/api/include/esp_avrc_api.h`
+
+
+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
+

docs/api-reference/bluetooth/esp_blufi.rst

@@ -0,0 +1,128 @@
+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: 
+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.
+
+
+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
+

docs/api-reference/bluetooth/esp_bt_defs.rst

@@ -0,0 +1,65 @@
+BT GENERIC DEFINES
+==================
+
+Overview
+--------
+
+`Instructions`_
+
+Application Example
+-------------------
+
+`Instructions`_
+
+.. _Instructions: ../template.html
+
+
+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
+^^^^^^^^^
+
+

docs/api-reference/bluetooth/esp_bt_device.rst

@@ -0,0 +1,49 @@
+BT DEVICE APIs
+===============
+
+Overview
+--------
+
+Bluetooth device reference APIs.
+
+`Instructions`_
+
+Application Example
+-------------------
+
+`Instructions`_
+
+.. _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
+

docs/api-reference/bluetooth/esp_bt_main.rst

@@ -0,0 +1,52 @@
+BT MAIN API
+===========
+
+Overview
+--------
+
+`Instructions`_
+
+Application Example
+-------------------
+
+`Instructions`_
+
+.. _Instructions: ../template.html
+
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :component_file:`bt/bluedroid/api/include/esp_bt_main.h`
+
+
+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
+

docs/api-reference/bluetooth/esp_gap_ble.rst

@@ -0,0 +1,188 @@
+GAP API
+=======
+
+Overview
+--------
+
+`Instructions`_
+
+.. _Instructions: ../template.html
+
+Application Example
+-------------------
+
+Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following examples:
+
+:example:`bluetooth/gatt_server`, :example:`bluetooth/gatt_client` 
+
+  The two demos use different GAP APIs, such like advertising, scan, set device name and others.
+
+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
+

docs/api-reference/bluetooth/esp_gap_bt.rst

@@ -0,0 +1,47 @@
+CLASSIC BLUETOOTH GAP API
+=========================
+
+Overview
+--------
+
+`Instructions`_
+
+Application Example
+-------------------
+
+`Instructions`_
+
+.. _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
+

docs/api-reference/bluetooth/esp_gatt_defs.rst

@@ -0,0 +1,167 @@
+GATT DEFINES
+============
+
+Overview
+--------
+
+`Instructions`_
+
+Application Example
+-------------------
+
+`Instructions`_
+
+.. _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
+^^^^^^^^^
+
+

docs/api-reference/bluetooth/esp_gattc.rst

@@ -0,0 +1,124 @@
+GATT CLIENT API
+===============
+
+Overview
+--------
+
+`Instructions`_
+
+.. _Instructions: ../template.html
+
+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.
+
+
+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_execute_write
+.. doxygenfunction:: esp_ble_gattc_register_for_notify
+.. doxygenfunction:: esp_ble_gattc_unregister_for_notify
+

docs/api-reference/bluetooth/esp_gatts.rst

@@ -0,0 +1,128 @@
+GATT SERVER API
+===============
+
+Overview
+--------
+
+`Instructions`_
+
+.. _Instructions: ../template.html
+
+Application Example
+-------------------
+
+Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following example:
+
+: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.
+
+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
+

docs/api-reference/bluetooth/index.rst

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

docs/api-reference/ethernet/esp_eth.rst

@@ -0,0 +1,74 @@
+ETHERNET
+========
+
+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
+
+
+PHY Configuration Constants
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. doxygenvariable:: phy_tlk110_default_ethernet_config
+.. doxygenvariable:: phy_lan8720_default_ethernet_config

docs/api-reference/ethernet/index.rst

@@ -0,0 +1,10 @@
+Ethernet API
+************
+
+.. toctree::
+   :maxdepth: 1
+
+   Ethernet <esp_eth>
+
+
+Example code for this API section is provided in :example:`ethernet` directory of ESP-IDF examples.

docs/api-reference/index.rst

@@ -0,0 +1,14 @@
+*************
+API Reference
+*************
+
+.. toctree::
+   :maxdepth: 2
+
+   Wi-Fi <wifi/index>
+   Bluetooth <bluetooth/index>
+   Ethernet <ethernet/index>
+   Peripherals <peripherals/index>
+   System <system/index>
+   Storage <storage/index>
+   Protocols <protocols/index>

docs/api-reference/peripherals/adc.rst

@@ -0,0 +1,62 @@
+Analog to Digital Converter
+===========================
+
+Overview
+--------
+
+ESP32 integrates two 12-bit SAR ("Successive Approximation Register") ADCs (Analog to Digital Converters) and supports measurements on 18 channels (analog enabled pins). Some of these pins can be used to build a programmable gain amplifier which is used for the measurement of small
+analog signals.
+
+The ADC driver API currently only supports ADC1 (9 channels, attached to GPIOs 32-39).
+
+Taking an ADC reading involves configuring the ADC with the desired precision and attentuation settings, and then calling adc1_get_voltage() to read the channel.
+
+It is also possible to read the internal hall effect sensor via ADC1.
+
+Application Example
+-------------------
+
+Reading voltage on ADC1 channel 0 (GPIO 36)::
+
+    #include <driver/adc.h>
+
+    ...
+
+        adc1_config_width(ADC_WIDTH_12Bit);
+        adc1_config_channel_atten(ADC1_CHANNEL_0,ADC_ATTEN_0db);
+        int val = adc1_get_voltage(ADC1_CHANNEL_0);
+
+Reading the internal hall effect sensor::
+
+    #include <driver/adc.h>
+
+    ...
+
+        adc1_config_width(ADC_WIDTH_12Bit);
+        int val = hall_sensor_read();
+
+The value read in both these examples is 12 bits wide (range 0-4095).
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * `components/driver/include/driver/adc.h`
+
+Enumerations
+^^^^^^^^^^^^
+
+  .. doxygenenum:: adc1_channel_t
+  .. doxygenenum:: adc_atten_t
+  .. doxygenenum:: adc_bits_width_t
+
+Functions
+^^^^^^^^^
+
+  .. doxygenfunction:: adc1_config_width
+  .. doxygenfunction:: adc1_config_channel_atten
+  .. doxygenfunction:: adc1_get_voltage
+  .. doxygenfunction:: hall_sensor_read
+

docs/api-reference/peripherals/dac.rst

@@ -0,0 +1,45 @@
+Digital To Analog Converter
+===========================
+
+Overview
+--------
+
+ESP32 has two 8-bit DAC (digital to analog converter) channels, connected to GPIO25 (Channel 1) and GPIO26 (Channel 2).
+
+The DAC driver allows these channels to be set to arbitrary voltages.
+
+The DAC channels can also be driven with DMA-style written sample data, via the :doc:`I2S driver <i2s>` when using the "built-in DAC mode".
+
+For other analog output options, see the :doc:`Sigma-delta Modulation module <sigmadelta>` and the :doc:`LED Control module <ledc>`. Both these modules produce high frequency PWM output, which can be hardware low-pass filtered in order to generate a lower frequency analog output.
+
+
+Application Example
+-------------------
+
+Setting DAC channel 1 (GPIO 25) voltage to approx 0.78 of VDD_A voltage (VDD * 200 / 255). For VDD_A 3.3V, this is 2.59V::
+
+  #include <driver/dac.h>
+
+  ...
+
+      dac_out_voltage(DAC_CHANNEL_1, 200);
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * `components/driver/include/driver/dac.h`
+
+Enumerations
+^^^^^^^^^^^^
+
+  .. doxygenenum:: dac_channel_t
+
+Functions
+^^^^^^^^^
+
+  .. doxygenfunction:: dac_out_voltage
+
+

docs/api-reference/peripherals/gpio.rst

@@ -0,0 +1,191 @@
+GPIO & RTC GPIO
+===============
+
+Overview
+--------
+
+The ESP32 chip features 40 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal.
+
+- Note that GPIO6-11 are usually used for SPI flash.
+- GPIO34-39 can only be set as input mode and do not have software pullup or pulldown functions.
+
+There is also separate "RTC GPIO" support, which functions when GPIOs are routed to the "RTC" low-power and analog subsystem. These pin functions can be used when in deep sleep, when the :doc:`Ultra Low Power co-processor <../../api-guides/ulp>` is running, or when analog functions such as ADC/DAC/etc are in use.
+
+Application Example
+-------------------
+
+GPIO output and input interrupt example: :example:`peripherals/gpio`.
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :component_file:`driver/include/driver/gpio.h`
+  * :component_file:`driver/include/driver/rtc_io.h`
+
+Macros
+^^^^^^
+
+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

docs/api-reference/peripherals/i2c.rst

@@ -0,0 +1,82 @@
+I2C
+===========
+
+Overview
+--------
+
+ESP32 has two I2C controllers which can be set as master mode or slave mode.
+
+Application Example
+-------------------
+
+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
+

docs/api-reference/peripherals/i2s.rst

@@ -0,0 +1,131 @@
+I2S
+===
+
+Overview
+--------
+
+ESP32 contains two I2S peripherals. These peripherals can be configured to input and output sample data via the I2S driver.
+
+The I2S peripheral supports DMA meaning it can stream sample data without requiring each sample to be read or written by the CPU.
+
+I2S output can also be routed directly to the Digital/Analog Converter output channels (GPIO 25 & GPIO 26) to produce analog output directly, rather than via an external I2S codec.
+
+Application Example
+-------------------
+
+A full I2S example is available in esp-idf: :example:`peripherals/i2s`.
+
+Short example of I2S configuration::
+
+    #include "driver/i2s.h"
+    #include "freertos/queue.h"
+
+    static const int i2s_num = 0; // i2s port number
+
+    static const i2s_config_t i2s_config = {
+         .mode = I2S_MODE_MASTER | I2S_MODE_TX,
+         .sample_rate = 44100,
+         .bits_per_sample = 16,
+         .channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
+         .communication_format = I2S_COMM_FORMAT_I2S | I2S_COMM_FORMAT_I2S_MSB,
+         .intr_alloc_flags = ESP_INTR_FLAG_LEVEL1, // high interrupt priority
+         .dma_buf_count = 8,
+         .dma_buf_len = 64
+    };
+
+    static const i2s_pin_config_t pin_config = {
+        .bck_io_num = 26,
+        .ws_io_num = 25,
+        .data_out_num = 22,
+        .data_in_num = I2S_PIN_NO_CHANGE
+    };
+
+    ...
+
+        i2s_driver_install(i2s_num, &i2s_config, 0, NULL);   //install and start i2s driver
+
+        i2s_set_pin(i2s_num, &pin_config);
+
+        i2s_set_sample_rates(i2s_num, 22050); //set sample rates
+
+        i2s_driver_uninstall(i2s_num); //stop & destroy i2s driver
+
+Short example configuring I2S to use internal DAC for analog output::
+
+    #include "driver/i2s.h"
+    #include "freertos/queue.h"
+
+    static const int i2s_num = 0; // i2s port number
+
+    static const i2s_config_t i2s_config = {
+         .mode = I2S_MODE_MASTER | I2S_MODE_TX | I2S_MODE_DAC_BUILT_IN,
+         .sample_rate = 44100,
+         .bits_per_sample = 8, /* must be 8 for built-in DAC */
+         .channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
+         .communication_format = I2S_COMM_FORMAT_I2S_MSB,
+         .intr_alloc_flags = ESP_INTR_FLAG_LEVEL1, // high interrupt priority
+         .dma_buf_count = 8,
+         .dma_buf_len = 64
+    };
+
+    ...
+
+        i2s_driver_install(i2s_num, &i2s_config, 0, NULL);   //install and start i2s driver
+
+        i2s_set_pin(i2s_num, NULL); //for internal DAC
+
+        i2s_set_sample_rates(i2s_num, 22050); //set sample rates
+
+        i2s_driver_uninstall(i2s_num); //stop & destroy i2s driver
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * `components/driver/include/driver/i2s.h`
+
+Data Structures
+^^^^^^^^^^^^^^^
+
+  .. doxygenstruct:: i2s_config_t
+     :members:
+  .. doxygenstruct:: i2s_event_t
+     :members:
+  .. doxygenstruct:: i2s_pin_config_t
+     :members:
+
+Macros
+^^^^^^
+
+  .. doxygendefine:: I2S_PIN_NO_CHANGE
+
+Enumerations
+^^^^^^^^^^^^
+
+  .. doxygenenum:: i2s_bits_per_sample_t
+  .. doxygenenum:: i2s_comm_format_t
+  .. doxygenenum:: i2s_channel_fmt_t
+  .. doxygenenum:: pdm_sample_rate_ratio_t
+  .. doxygenenum:: pdm_pcm_conv_t
+  .. doxygenenum:: i2s_port_t
+  .. doxygenenum:: i2s_mode_t
+  .. doxygenenum:: i2s_event_type_t
+
+Functions
+^^^^^^^^^
+
+  .. doxygenfunction:: i2s_set_pin
+  .. doxygenfunction:: i2s_driver_install
+  .. doxygenfunction:: i2s_driver_uninstall
+  .. doxygenfunction:: i2s_write_bytes
+  .. doxygenfunction:: i2s_read_bytes
+  .. doxygenfunction:: i2s_push_sample
+  .. doxygenfunction:: i2s_pop_sample
+  .. doxygenfunction:: i2s_set_sample_rates
+  .. doxygenfunction:: i2s_start
+  .. doxygenfunction:: i2s_stop
+  .. doxygenfunction:: i2s_zero_dma_buffer
+
+

docs/api-reference/peripherals/index.rst

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

docs/api-reference/peripherals/ledc.rst

@@ -0,0 +1,80 @@
+LED Control
+===========
+
+Overview
+--------
+
+The LED control module is primarily designed to control the intensity of LEDs, although it can be used to generate PWM signals for other purposes as well. 
+It has 16 channels which can generate independent waveforms that can be used to drive e.g. RGB LED devices. For maximum flexibility, the high-speed as well 
+as the low-speed channels can be driven from one of four high-speed/low-speed timers. The PWM controller also has the ability to automatically increase or 
+decrease the duty cycle gradually, allowing for fades without any processor interference.
+
+Application Example
+-------------------
+
+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
+

docs/api-reference/peripherals/pcnt.rst

@@ -0,0 +1,66 @@
+Pulse Counter
+=============
+
+Overview
+--------
+
+The PCNT (Pulse Counter) module is designed to count the number of rising and/or falling edges of an input signal. Each pulse counter unit has a 16-bit signed counter register and two channels that can be configured to either increment or decrement the counter. Each channel has a signal input that accepts signal edges to be detected, as well as a control input that can be used to enable or disable the signal input. The inputs have optional filters that can be used to discard unwanted glitches in the signal.
+
+Application Example
+-------------------
+
+Pulse counter with control signal and event interrupt example: :example:`peripherals/pcnt`.
+
+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
+

docs/api-reference/peripherals/rmt.rst

@@ -0,0 +1,93 @@
+RMT
+========
+
+Overview
+--------
+
+The RMT (Remote Control) module driver can be used to send and receive infrared remote control signals. Due to flexibility of RMT module, the driver can also be used to generate many other types of signals.
+
+Application Example
+-------------------
+
+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
+

docs/api-reference/peripherals/sigmadelta.rst

@@ -0,0 +1,51 @@
+Sigma-delta Modulation
+======================
+
+Overview
+--------
+
+ESP32 has a second-order sigma-delta modulation module.
+This driver configures the channels of the sigma-delta module.
+
+Application Example
+-------------------
+
+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
+

docs/api-reference/peripherals/spi_master.rst

@@ -0,0 +1,171 @@
+SPI Master driver
+=================
+
+Overview
+--------
+
+The ESP32 has four SPI peripheral devices, called SPI0, SPI1, HSPI and VSPI. SPI0 is entirely dedicated to
+the flash cache the ESP32 uses to map the SPI flash device it is connected to into memory. SPI1 is
+connected to the same hardware lines as SPI0 and is used to write to the flash chip. HSPI and VSPI
+are free to use. SPI1, HSPI and VSPI all have three chip select lines, allowing them to drive up to
+three SPI devices each as a master.
+
+The spi_master driver
+^^^^^^^^^^^^^^^^^^^^^
+
+The spi_master driver allows easy communicating with SPI slave devices, even in a multithreaded environment.
+It fully transparently handles DMA transfers to read and write data and automatically takes care of 
+multiplexing between different SPI slaves on the same master
+
+Terminology
+^^^^^^^^^^^
+
+The spi_master driver uses the following terms:
+
+* Host: The SPI peripheral inside the ESP32 initiating the SPI transmissions. One of SPI, HSPI or VSPI. (For 
+  now, only HSPI or VSPI are actually supported in the driver; it will support all 3 peripherals 
+  somewhere in the future.)
+* Bus: The SPI bus, common to all SPI devices connected to one host. In general the bus consists of the
+  miso, mosi, sclk and optionally quadwp and quadhd signals. The SPI slaves are connected to these 
+  signals in parallel.
+
+  - miso - Also known as q, this is the input of the serial stream into the ESP32
+
+  - mosi - Also known as d, this is the output of the serial stream from the ESP32
+
+  - sclk - Clock signal. Each data bit is clocked out or in on the positive or negative edge of this signal
+
+  - quadwp - Write Protect signal. Only used for 4-bit (qio/qout) transactions.
+
+  - quadhd - Hold signal. Only used for 4-bit (qio/qout) transactions.
+
+* Device: A SPI slave. Each SPI slave has its own chip select (CS) line, which is made active when
+  a transmission to/from the SPI slave occurs.
+* Transaction: One instance of CS going active, data transfer from and/or to a device happening, and
+  CS going inactive again. Transactions are atomic, as in they will never be interrupted by another
+  transaction.
+
+
+SPI transactions
+^^^^^^^^^^^^^^^^
+
+A transaction on the SPI bus consists of five phases, any of which may be skipped:
+
+* The command phase. In this phase, a command (0-16 bit) is clocked out.
+* The address phase. In this phase, an address (0-64 bit) is clocked out.
+* The read phase. The slave sends data to the master.
+* The write phase. The master sends data to the slave.
+
+In full duplex, the read and write phases are combined, causing the SPI host to read and
+write data simultaneously.
+
+The command and address phase are optional in that not every SPI device will need to be sent a command
+and/or address. Tis is reflected in the device configuration: when the ``command_bits`` or ``data_bits``
+fields are set to zero, no command or address phase is done.
+
+Something similar is true for the read and write phase: not every transaction needs both data to be written
+as well as data to be read. When ``rx_buffer`` is NULL (and SPI_USE_RXDATA) is not set) the read phase 
+is skipped. When ``tx_buffer`` is NULL (and SPI_USE_TXDATA) is not set) the write phase is skipped.
+
+Using the spi_master driver
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Initialize a SPI bus by calling ``spi_bus_initialize``. Make sure to set the correct IO pins in
+  the ``bus_config`` struct. Take care to set signals that are not needed to -1.
+
+- Tell the driver about a SPI slave device connected to the bus by calling spi_bus_add_device. 
+  Make sure to configure any timing requirements the device has in the ``dev_config`` structure.
+  You should now have a handle for the device, to be used when sending it a transaction.
+
+- To interact with the device, fill one or more spi_transaction_t structure with any transaction 
+  parameters you need. Either queue all transactions by calling ``spi_device_queue_trans``, later
+  quering the result using ``spi_device_get_trans_result``, or handle all requests synchroneously
+  by feeding them into ``spi_device_transmit``.
+
+- Optional: to unload the driver for a device, call ``spi_bus_remove_device`` with the device
+  handle as an argument
+
+- Optional: to remove the driver for a bus, make sure no more drivers are attached and call 
+  ``spi_bus_free``.
+
+
+Transaction data
+^^^^^^^^^^^^^^^^
+
+Normally, data to be transferred to or from a device will be read from or written to a chunk of memory
+indicated by the ``rx_buffer`` and ``tx_buffer`` members of the transaction structure. The SPI driver
+may decide to use DMA for transfers, so these buffers should be allocated in DMA-capable memory using 
+``pvPortMallocCaps(size, MALLOC_CAP_DMA)``.
+
+Sometimes, the amount of data is very small making it less than optimal allocating a separate buffer
+for it. If the data to be transferred is 32 bits or less, it can be stored in the transaction struct
+itself. For transmitted data, use the ``tx_data`` member for this and set the ``SPI_USE_TXDATA`` flag
+on the transmission. For received data, use ``rx_data`` and set ``SPI_USE_RXDATA``. In both cases, do
+not touch the ``tx_buffer`` or ``rx_buffer`` members, because they use the same memory locations
+as ``tx_data`` and ``rx_data``.
+
+Application Example
+-------------------
+ 
+Display graphics on the ILI9341-based 320x240 LCD: :example:`peripherals/spi_master`.
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :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:
+
+
+
+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
+

docs/api-reference/peripherals/spi_slave.rst

@@ -0,0 +1,142 @@
+SPI Slave driver
+=================
+
+Overview
+--------
+
+The ESP32 has four SPI peripheral devices, called SPI0, SPI1, HSPI and VSPI. SPI0 is entirely dedicated to
+the flash cache the ESP32 uses to map the SPI flash device it is connected to into memory. SPI1 is
+connected to the same hardware lines as SPI0 and is used to write to the flash chip. HSPI and VSPI
+are free to use, and with the spi_slave driver, these can be used as a SPI slave, driven from a 
+connected SPI master.
+
+The spi_slave driver
+^^^^^^^^^^^^^^^^^^^^^
+
+The spi_slave driver allows using the HSPI and/or VSPI peripheral as a full-duplex SPI slave. It can make
+use of DMA to send/receive transactions of arbitrary length.
+
+Terminology
+^^^^^^^^^^^
+
+The spi_slave driver uses the following terms:
+
+* Host: The SPI peripheral inside the ESP32 initiating the SPI transmissions. One of HSPI or VSPI. 
+* Bus: The SPI bus, common to all SPI devices connected to a master. In general the bus consists of the
+  miso, mosi, sclk and optionally quadwp and quadhd signals. The SPI slaves are connected to these 
+  signals in parallel. Each  SPI slave is also connected to one CS signal.
+
+  - miso - Also known as q, this is the output of the serial stream from the ESP32 to the SPI master
+
+  - mosi - Also known as d, this is the output of the serial stream from the SPI master to the ESP32
+
+  - sclk - Clock signal. Each data bit is clocked out or in on the positive or negative edge of this signal
+
+  - cs - Chip Select. An active Chip Select delineates a single transaction to/from a slave.
+
+* Transaction: One instance of CS going active, data transfer from and to a master happening, and
+  CS going inactive again. Transactions are atomic, as in they will never be interrupted by another
+  transaction.
+
+
+SPI transactions
+^^^^^^^^^^^^^^^^
+
+A full-duplex SPI transaction starts with the master pulling CS low. After this happens, the master
+starts sending out clock pulses on the CLK line: every clock pulse causes a data bit to be shifted from
+the master to the slave on the MOSI line and vice versa on the MISO line. At the end of the transaction,
+the master makes CS high again.
+
+Using the spi_slave driver
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Initialize a SPI peripheral as a slave by calling ``spi_slave_initialize``. Make sure to set the 
+  correct IO pins in the ``bus_config`` struct. Take care to set signals that are not needed to -1.
+  A DMA channel (either 1 or 2) must be given if transactions will be larger than 32 bytes, if not
+  the dma_chan parameter may be 0.
+
+- To set up a transaction, fill one or more spi_transaction_t structure with any transaction 
+  parameters you need. Either queue all transactions by calling ``spi_slave_queue_trans``, later
+  quering the result using ``spi_slave_get_trans_result``, or handle all requests synchroneously
+  by feeding them into ``spi_slave_transmit``. The latter two  functions will block until the 
+  master has initiated and finished a transaction, causing the queued data to be sent and received.
+
+- Optional: to unload the SPI slave driver, call ``spi_slave_free``.
+
+
+Transaction data and master/slave length mismatches
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Normally, data to be transferred to or from a device will be read from or written to a chunk of memory
+indicated by the ``rx_buffer`` and ``tx_buffer`` members of the transaction structure. The SPI driver
+may decide to use DMA for transfers, so these buffers should be allocated in DMA-capable memory using 
+``pvPortMallocCaps(size, MALLOC_CAP_DMA)``.
+
+The amount of data written to the buffers is limited by the ``length`` member of the transaction structure:
+the driver will never read/write more data than indicated there. The ``length`` cannot define the actual
+length of the SPI transaction; this is determined by the master as it drives the clock and CS lines. In
+case the length of the transmission is larger than the buffer length, only the start of the transmission
+will be sent and received. In case the transmission length is shorter than the buffer length, only data up 
+to the length of the buffer will be exchanged.
+
+Warning: Due to a design peculiarity in the ESP32, if the amount of bytes sent by the master or the length 
+of the transmission queues in the slave driver, in bytes, is not both larger than eight and dividable by 
+four, the SPI hardware can fail to write the last one to seven bytes to the receive buffer.
+
+
+Application Example
+-------------------
+
+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
+

docs/api-reference/peripherals/timer.rst

@@ -0,0 +1,73 @@
+TIMER
+========
+
+Overview
+--------
+
+ESP32 chip contains two hardware timer groups, each containing two general-purpose hardware timers. 
+
+They are all 64-bit generic timers based on 16-bit prescalers and 64-bit auto-reload-capable up/down counters.
+
+
+Application Example
+-------------------
+
+64-bit hardware timer example: :example:`peripherals/timer_group`.
+
+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
+

docs/api-reference/peripherals/uart.rst

@@ -0,0 +1,98 @@
+UART
+====
+
+Overview
+--------
+
+`Instructions`_
+
+.. _Instructions: ../template.html
+
+Application Example
+-------------------
+
+Configure uart settings and install uart driver to read/write using UART0 and UART1 interfaces: :example:`peripherals/uart`.
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :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
+

docs/api-reference/protocols/index.rst

@@ -0,0 +1,10 @@
+Protocols API
+*************
+
+.. toctree::
+   :maxdepth: 1
+
+   mDNS <mdns>
+
+
+Example code for this API section is provided in :example:`protocols` directory of ESP-IDF examples.

docs/api-reference/protocols/mdns.rst

@@ -0,0 +1,215 @@
+mDNS Service
+============
+
+Overview
+--------
+
+mDNS is a multicast UDP service that is used to provide local network service and host discovery.
+
+mDNS is installed by default on most operating systems or is available as separate package. On ``Mac OS`` it is installed by default and is called ``Bonjour``. Apple releases an installer for ``Windows`` that can be found `on Apple's support page <https://support.apple.com/downloads/bonjour%2520for%2520windows>`_. On ``Linux``, mDNS is provided by `avahi <https://github.com/lathiat/avahi>`_ and is usually installed by default.
+
+mDNS Properties
+^^^^^^^^^^^^^^^
+
+    * ``hostname``: the hostname that the device will respond to. If not set, the ``hostname`` will be read from the interface. Example: ``my-esp32`` will resolve to ``my-esp32.local``
+    * ``default_instance``: friendly name for your device, like ``Jhon's ESP32 Thing``. If not set, ``hostname`` will be used.
+
+Example method to start mDNS for the STA interface and set ``hostname`` and ``default_instance``:
+
+  ::
+
+    mdns_server_t * mdns = NULL;
+    
+    void start_mdns_service()
+    {
+        //initialize mDNS service on STA interface
+        esp_err_t err = mdns_init(TCPIP_ADAPTER_IF_STA, &mdns);
+        if (err) {
+            printf("MDNS Init failed: %d\n", err);
+            return;
+        }
+    
+        //set hostname
+        mdns_set_hostname(mdns, "my-esp32");
+        //set default instance
+        mdns_set_instance(mdns, "Jhon's ESP32 Thing");
+    }
+
+mDNS Services
+^^^^^^^^^^^^^
+
+mDNS can advertise information about network services that your device offers. Each service is defined by a few properties.
+
+    * ``service``: (required) service type, prepended with underscore. Some common types can be found `here <http://www.dns-sd.org/serviceTypes.html>`_.
+    * ``proto``: (required) protocol that the service runs on, prepended with underscore. Example: ``_tcp`` or ``_udp`` 
+    * ``port``: (required) network port that the service runs on
+    * ``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:
+
+  ::
+
+    void add_mdns_services()
+    {
+        //add our services
+        mdns_service_add(mdns, "_http", "_tcp", 80);
+        mdns_service_add(mdns, "_arduino", "_tcp", 3232);
+        mdns_service_add(mdns, "_myservice", "_udp", 1234);
+        
+        //NOTE: services must be added before their properties can be set
+        //use custom instance for the web server
+        mdns_service_instance_set(mdns, "_http", "_tcp", "Jhon's ESP32 Web Server");
+
+        const char * arduTxtData[4] = {
+                "board=esp32",
+                "tcp_check=no",
+                "ssh_upload=no",
+                "auth_upload=no"
+        };
+        //set txt data for service (will free and replace current data)
+        mdns_service_txt_set(mdns, "_arduino", "_tcp", 4, arduTxtData);
+        
+        //change service port
+        mdns_service_port_set(mdns, "_myservice", "_udp", 4321);
+    }
+
+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:
+
+  ::
+
+    void resolve_mdns_host(const char * hostname)
+    {
+        printf("mDNS Host Lookup: %s.local\n", hostname);
+        //run search for 1000 ms
+        if (mdns_query(mdns, hostname, NULL, 1000)) {
+            //results were found
+            const mdns_result_t * results = mdns_result_get(mdns, 0);
+            //itterate through all results
+            size_t i = 1;
+            while(results) {
+                //print result information
+                printf("  %u: IP:" IPSTR ", IPv6:" IPV6STR "\n", i++
+                    IP2STR(&results->addr), IPV62STR(results->addrv6));
+                //load next result. Will be NULL if this was the last one
+                results = results->next;
+            }
+            //free the results from memory
+            mdns_result_free(mdns);
+        } else {
+            //host was not found
+            printf("  Host Not Found\n");
+        }
+    }
+
+Example method to resolve local services:
+
+  ::
+
+    void find_mdns_service(const char * service, const char * proto)
+    {
+        printf("mDNS Service Lookup: %s.%s\n", service, proto);
+        //run search for 1000 ms
+        if (mdns_query(mdns, service, proto, 1000)) {
+            //results were found
+            const mdns_result_t * results = mdns_result_get(mdns, 0);
+            //itterate through all results
+            size_t i = 1;
+            while(results) {
+                //print result information
+                printf("  %u: hostname:%s, instance:\"%s\", IP:" IPSTR ", IPv6:" IPV6STR ", port:%u, txt:%s\n", i++,
+                    (results->host)?results->host:"NULL", (results->instance)?results->instance:"NULL",
+                    IP2STR(&results->addr), IPV62STR(results->addrv6),
+                    results->port, (results->txt)?results->txt:"\r");
+                //load next result. Will be NULL if this was the last one
+                results = results->next;
+            }
+            //free the results from memory
+            mdns_result_free(mdns);
+        } else {
+            //service was not found
+            printf("  Service Not Found\n");
+        }
+    }
+
+Example of using the methods above:
+
+  ::
+
+    void my_app_some_method(){
+        //search for esp32-mdns.local
+        resolve_mdns_host("esp32-mdns");
+        
+        //search for HTTP servers
+        find_mdns_service("_http", "_tcp");
+        //or file servers
+        find_mdns_service("_smb", "_tcp"); //windows sharing
+        find_mdns_service("_afpovertcp", "_tcp"); //apple sharing
+        find_mdns_service("_nfs", "_tcp"); //NFS server
+        find_mdns_service("_ftp", "_tcp"); //FTP server
+        //or networked printer
+        find_mdns_service("_printer", "_tcp");
+        find_mdns_service("_ipp", "_tcp");
+    }
+
+Application Example
+-------------------
+
+mDNS server/scanner example: :example:`protocols/mdns`.
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :component_file:`mdns/include/mdns.h`
+
+Macros
+^^^^^^
+
+
+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
+

docs/api-reference/storage/fatfs.rst

@@ -0,0 +1,64 @@
+FAT Filesystem Support
+======================
+
+ESP-IDF uses `FatFs <http://elm-chan.org/fsw/ff/00index_e.html>`_ library to work with FAT filesystems. FatFs library resides in ``fatfs`` component. Although it can be used directly, many of its features can be accessed via VFS using C standard library and POSIX APIs.
+
+Additionally, FatFs has been modified to support run-time pluggable disk IO layer. This allows mapping of FatFs drives to physical disks at run-time.
+
+Using FatFs with VFS
+--------------------
+
+``esp_vfs_fat.h`` header file defines functions to connect FatFs with VFS. ``esp_vfs_fat_register`` function allocates a ``FATFS`` structure, and registers a given path prefix in VFS. Subsequent operations on files starting with this prefix are forwarded to FatFs APIs. ``esp_vfs_fat_unregister_path`` function deletes the registration with VFS, and frees the ``FATFS`` structure.
+
+Most applications will use the following flow when working with ``esp_vfs_fat_`` functions:
+
+1. Call ``esp_vfs_fat_register``, specifying path prefix where the filesystem has to be mounted (e.g. ``"/sdcard"``, ``"/spiflash"``), FatFs drive number, and a variable which will receive a pointer to ``FATFS`` structure.
+
+2. Call ``ff_diskio_register`` function to register disk IO driver for the drive number used in step 1.
+
+3. Call ``f_mount`` function (and optionally ``f_fdisk``, ``f_mkfs``) to mount the filesystem using the same drive number which was passed to ``esp_vfs_fat_register``. See FatFs documentation for more details.
+
+4. Call POSIX and C standard library functions to open, read, write, erase, copy files, etc. Use paths starting with the prefix passed to ``esp_vfs_register`` (such as ``"/sdcard/hello.txt"``).
+
+5. Optionally, call FatFs library functions directly. Use paths without a VFS prefix in this case (``"/hello.txt"``).
+
+6. Close all open files.
+
+7. Call ``f_mount`` function for the same drive number, with NULL ``FATFS*`` argument, to unmount the filesystem.
+
+8. Call ``ff_diskio_register`` with NULL ``ff_diskio_impl_t*`` argument and the same drive number.
+
+9. Call ``esp_vfs_fat_unregister_path`` with the path where the file system is mounted to remove FatFs from VFS, and free the ``FATFS`` structure allocated on step 1.
+
+Convenience functions, ``esp_vfs_fat_sdmmc_mount`` and ``esp_vfs_fat_sdmmc_unmount``, which wrap these steps and also handle SD card initialization, are described in the next section. 
+
+.. doxygenfunction:: esp_vfs_fat_register
+.. doxygenfunction:: esp_vfs_fat_unregister_path
+
+
+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
+-------------------
+
+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
+

docs/api-reference/storage/index.rst

@@ -0,0 +1,15 @@
+Storage API
+***********
+
+.. toctree::
+   :maxdepth: 1
+
+   SPI Flash and Partition APIs <spi_flash>
+   SD/MMC <sdmmc>
+   Non-Volatile Storage <nvs_flash>
+   Virtual Filesystem <vfs>
+   FAT Filesystem <fatfs>
+   Wear Levelling <wear-levelling>
+
+
+Example code for this API section is provided in :example:`storage` directory of ESP-IDF examples.

docs/api-reference/storage/nvs_flash.rst

@@ -0,0 +1,92 @@
+.. include:: ../../../components/nvs_flash/README.rst
+
+Application Example
+-------------------
+
+Two examples are provided in :example:`storage` directory of ESP-IDF examples:
+
+:example:`storage/nvs_rw_value`
+
+  Demonstrates how to read and write a single integer value using NVS.
+
+  The value holds the number of ESP32 module restarts. Since it is written to NVS, the value is preserved between restarts.
+
+  Example also shows how to check if read / write operation was successful, or certain value is not initialized in NVS. Diagnostic is provided in plain text to help track program flow and capture any issues on the way.
+
+:example:`storage/nvs_rw_blob`
+
+  Demonstrates how to read and write a single integer value and a blob (binary large object) using NVS to preserve them between ESP32 module restarts.
+
+    * value - tracks number of ESP32 module soft and hard restarts.
+    * blob - contains a table with module run times. The table is read from NVS to dynamically allocated RAM. New run time is added to the table on each manually triggered soft restart and written back to NVS. Triggering is done by pulling down GPIO0.
+
+  Example also shows how to implement diagnostics if read / write operation was successful.
+
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :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
+
+

docs/api-reference/storage/sdmmc.rst

@@ -0,0 +1,96 @@
+SDMMC Host Peripheral
+=====================
+
+Overview
+--------
+
+SDMMC peripheral supports SD and MMC memory cards and SDIO cards. SDMMC software builds on top of SDMMC driver and consists of the following parts:
+
+1. SDMMC host driver (``driver/sdmmc_host.h``) — this driver provides APIs to send commands to the slave device(s), send and receive data, and handling error conditions on the bus.
+
+2. SDMMC protocol layer (``sdmmc_cmd.h``) — this component handles specifics of SD protocol such as card initialization and data transfer commands. Despite the name, only SD (SDSC/SDHC/SDXC) cards are supported at the moment. Support for MCC/eMMC cards can be added in the future.
+
+Protocol layer works with the host via ``sdmmc_host_t`` structure. This structure contains pointers to various functions of the host. This design makes it possible to implement an SD host using SPI interface later.
+
+Application Example
+-------------------
+
+An example which combines SDMMC driver with FATFS library is provided in ``examples/storage/sd_card`` directory. This example initializes the card, writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
+
+
+Protocol layer APIs
+-------------------
+
+Protocol layer is given ``sdmmc_host_t`` structure which describes the SD/MMC host driver, lists its capabilites, and provides pointers to functions of the driver. Protocol layer stores card-specific information in ``sdmmc_card_t`` structure. When sending commands to the SD/MMC host driver, protocol layer uses ``sdmmc_command_t`` structure to describe the command, argument, expected return value, and data to transfer, if any.
+
+Normal usage of the protocol layer is as follows:
+
+1. Call the host driver functions to initialize the host (e.g. ``sdmmc_host_init``, ``sdmmc_host_init_slot``). 
+2. Call ``sdmmc_card_init`` to initialize the card, passing it host driver information (``host``) and a pointer to ``sdmmc_card_t`` structure which will be filled in (``card``).
+3. To read and write sectors of the card, use ``sdmmc_read_sectors`` and ``sdmmc_write_sectors``, passing the pointer to card information structure (``card``).
+4. When card is not used anymore, call the host driver function to disable SDMMC host peripheral and free resources allocated by the driver (e.g. ``sdmmc_host_deinit``).
+
+Most applications need to use the protocol layer only in one task; therefore the protocol layer doesn't implement any kind of locking on the ``sdmmc_card_t`` structure, or when accessing SDMMC host driver. Such locking has to be implemented in the higher layer, if necessary (e.g. in the filesystem driver).
+
+.. doxygenstruct:: sdmmc_host_t
+    :members:
+
+.. doxygendefine:: SDMMC_HOST_FLAG_1BIT
+.. doxygendefine:: SDMMC_HOST_FLAG_4BIT
+.. doxygendefine:: SDMMC_HOST_FLAG_8BIT
+.. doxygendefine:: SDMMC_HOST_FLAG_SPI
+.. doxygendefine:: SDMMC_FREQ_DEFAULT
+.. doxygendefine:: SDMMC_FREQ_HIGHSPEED
+.. doxygendefine:: SDMMC_FREQ_PROBING
+
+.. doxygenstruct:: sdmmc_command_t
+    :members:
+
+.. doxygenstruct:: sdmmc_card_t
+    :members:
+
+.. doxygenstruct:: sdmmc_csd_t
+    :members:
+
+.. doxygenstruct:: sdmmc_cid_t
+    :members:
+
+.. doxygenstruct:: sdmmc_scr_t
+    :members:
+
+.. doxygenfunction:: sdmmc_card_init
+.. doxygenfunction:: sdmmc_write_sectors
+.. doxygenfunction:: sdmmc_read_sectors
+
+SDMMC host driver APIs
+----------------------
+
+On the ESP32, SDMMC host peripheral has two slots:
+
+- Slot 0 (``SDMMC_HOST_SLOT_0``) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX.
+- Slot 1 (``SDMMC_HOST_SLOT_1``) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX.
+
+Card Detect and Write Protect signals can be routed to arbitrary pins using GPIO matrix. To use these pins, set ``gpio_cd`` and ``gpio_wp`` members of ``sdmmc_slot_config_t`` structure when calling ``sdmmc_host_init_slot``.
+
+Of all the funtions listed below, only ``sdmmc_host_init``, ``sdmmc_host_init_slot``, and ``sdmmc_host_deinit`` will be used directly by most applications. Other functions, such as ``sdmmc_host_set_bus_width``, ``sdmmc_host_set_card_clk``, and ``sdmmc_host_do_transaction`` will be called by the SD/MMC protocol layer via function pointers in ``sdmmc_host_t`` structure.
+
+.. doxygenfunction:: sdmmc_host_init
+
+.. doxygendefine:: SDMMC_HOST_SLOT_0
+.. doxygendefine:: SDMMC_HOST_SLOT_1
+.. doxygendefine:: SDMMC_HOST_DEFAULT
+.. doxygendefine:: SDMMC_SLOT_WIDTH_DEFAULT
+
+.. doxygenfunction:: sdmmc_host_init_slot
+
+.. doxygenstruct:: sdmmc_slot_config_t
+    :members:
+
+.. doxygendefine:: SDMMC_SLOT_NO_CD
+.. doxygendefine:: SDMMC_SLOT_NO_WP
+.. doxygendefine:: SDMMC_SLOT_CONFIG_DEFAULT
+
+.. doxygenfunction:: sdmmc_host_set_bus_width
+.. doxygenfunction:: sdmmc_host_set_card_clk
+.. doxygenfunction:: sdmmc_host_do_transaction
+.. doxygenfunction:: sdmmc_host_deinit

docs/api-reference/storage/spi_flash.rst

@@ -0,0 +1,110 @@
+.. include:: ../../../components/spi_flash/README.rst
+
+See also
+--------
+
+- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
+- :doc:`Over The Air Update (OTA) API <../system/ota>` provides high-level API for updating app firmware stored in flash.
+- :doc:`Non-Volatile Storage (NVS) API <nvs_flash>` provides a structured API for storing small items of data in SPI flash.
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :component_file:`spi_flash/include/esp_spi_flash.h`
+  * :component_file:`spi_flash/include/esp_partition.h`
+  * :component_file:`bootloader_support/include/esp_flash_encrypt.h`
+
+Macros
+^^^^^^
+
+.. doxygendefine:: ESP_ERR_FLASH_BASE
+.. doxygendefine:: ESP_ERR_FLASH_OP_FAIL
+.. doxygendefine:: ESP_ERR_FLASH_OP_TIMEOUT
+.. doxygendefine:: SPI_FLASH_SEC_SIZE
+.. doxygendefine:: SPI_FLASH_MMU_PAGE_SIZE
+.. doxygendefine:: ESP_PARTITION_SUBTYPE_OTA
+.. doxygendefine:: SPI_FLASH_CACHE2PHYS_FAIL
+
+Type Definitions
+^^^^^^^^^^^^^^^^
+
+.. doxygentypedef:: spi_flash_mmap_handle_t
+.. doxygentypedef:: esp_partition_iterator_t
+
+Enumerations
+^^^^^^^^^^^^
+
+.. doxygenenum:: spi_flash_mmap_memory_t
+.. doxygenenum:: esp_partition_type_t
+.. doxygenenum:: esp_partition_subtype_t
+
+Structures
+^^^^^^^^^^
+
+.. doxygenstruct:: esp_partition_t
+
+Functions
+^^^^^^^^^
+
+.. doxygenfunction:: spi_flash_init
+.. doxygenfunction:: spi_flash_get_chip_size
+.. doxygenfunction:: spi_flash_erase_sector
+.. doxygenfunction:: spi_flash_erase_range
+.. doxygenfunction:: spi_flash_write
+.. doxygenfunction:: spi_flash_write_encrypted
+.. doxygenfunction:: spi_flash_read
+.. doxygenfunction:: spi_flash_read_encrypted
+.. doxygenfunction:: spi_flash_mmap
+.. doxygenfunction:: spi_flash_munmap
+.. doxygenfunction:: spi_flash_mmap_dump
+.. doxygenfunction:: spi_flash_cache2phys
+.. doxygenfunction:: spi_flash_phys2cache
+.. doxygenfunction:: spi_flash_cache_enabled
+.. doxygenfunction:: esp_partition_find
+.. doxygenfunction:: esp_partition_find_first
+.. doxygenfunction:: esp_partition_get
+.. doxygenfunction:: esp_partition_next
+.. doxygenfunction:: esp_partition_iterator_release
+.. doxygenfunction:: esp_partition_read
+.. doxygenfunction:: esp_partition_write
+.. doxygenfunction:: esp_partition_erase_range
+.. doxygenfunction:: esp_partition_mmap
+.. doxygenfunction:: esp_flash_encryption_enabled
+
+.. _spi-flash-implementation-details:
+
+Implementation details
+----------------------
+
+In order to perform some flash operations, we need to make sure both CPUs
+are not running any code from flash for the duration of the flash operation.
+In a single-core setup this is easy: we disable interrupts/scheduler and do
+the flash operation. In the dual-core setup this is slightly more complicated.
+We need to make sure that the other CPU doesn't run any code from flash.
+
+
+When SPI flash API is called on CPU A (can be PRO or APP), we start
+spi_flash_op_block_func function on CPU B using esp_ipc_call API. This API
+wakes up high priority task on CPU B and tells it to execute given function,
+in this case spi_flash_op_block_func. This function disables cache on CPU B and
+signals that cache is disabled by setting s_flash_op_can_start flag.
+Then the task on CPU A disables cache as well, and proceeds to execute flash
+operation.
+
+While flash operation is running, interrupts can still run on CPUs A and B.
+We assume that all interrupt code is placed into RAM. Once interrupt allocation
+API is added, we should add a flag to request interrupt to be disabled for
+the duration of flash operations.
+
+Once flash operation is complete, function on CPU A sets another flag,
+s_flash_op_complete, to let the task on CPU B know that it can re-enable
+cache and release the CPU. Then the function on CPU A re-enables the cache on
+CPU A as well and returns control to the calling code.
+
+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.

docs/api-reference/storage/vfs.rst

@@ -0,0 +1,47 @@
+.. include:: ../../../components/vfs/README.rst
+
+Application Example
+-------------------
+
+`Instructions`_
+
+.. _Instructions: ../template.html
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :component_file:`vfs/include/esp_vfs.h`
+  * :component_file:`vfs/include/esp_vfs_dev.h`
+
+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

docs/api-reference/storage/wear-levelling.rst

@@ -0,0 +1,50 @@
+.. include:: ../../../components/wear_levelling/README.rst
+
+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.
+
+High level API Reference
+------------------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :component_file:`fatfs/src/esp_vfs_fat.h`
+
+Functions
+^^^^^^^^^
+
+.. doxygenfunction:: esp_vfs_fat_spiflash_mount
+.. doxygenstruct:: esp_vfs_fat_mount_config_t
+    :members:
+.. doxygenfunction:: esp_vfs_fat_spiflash_unmount
+
+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
+

docs/api-reference/system/deep_sleep.rst

@@ -0,0 +1,123 @@
+Deep Sleep
+==========
+
+Overview
+--------
+
+ESP32 is capable of deep sleep power saving mode. In this mode CPUs, most of the RAM, and all the digital peripherals which are clocked from APB_CLK are powered off. The only parts of the chip which can still be powered on are: RTC controller, RTC peripherals (including ULP coprocessor), and RTC memories (slow and fast).
+
+Wakeup from deep sleep mode can be done using several sources. These sources can be combined, in this case the chip will wake up when any one of the sources is triggered. Wakeup sources can be enabled using ``esp_deep_sleep_enable_X_wakeup`` APIs. Next section describes these APIs in detail. Wakeup sources can be configured at any moment before entering deep sleep mode. 
+
+Additionally, the application can force specific powerdown modes for the RTC peripherals and RTC memories using ``esp_deep_sleep_pd_config`` API.
+
+Once wakeup sources are configured, application can start deep sleep using ``esp_deep_sleep_start`` API. At this point the hardware will be configured according to the requested wakeup sources, and RTC controller will power down the CPUs and digital peripherals.
+
+Wakeup sources
+--------------
+
+Timer
+^^^^^
+
+RTC controller has a built in timer which can be used to wake up the chip after a predefined amount of time. Time is specified at microsecond precision, but the actual resolution depends on the clock source selected for RTC SLOW_CLK. See chapter "Reset and Clock" of the ESP32 Technical Reference Manual for details about RTC clock options. 
+
+This wakeup mode doesn't require RTC peripherals or RTC memories to be powered on during deep sleep.
+
+The following function can be used to enable deep sleep wakeup using a timer.
+
+.. doxygenfunction:: esp_deep_sleep_enable_timer_wakeup
+
+Touch pad
+^^^^^^^^^
+
+RTC IO module contains logic to trigger wakeup when a touch sensor interrupt occurs. You need to configure the touch pad interrupt before the chip starts deep sleep.
+
+Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO).
+
+.. doxygenfunction:: esp_deep_sleep_enable_touchpad_wakeup
+
+
+External wakeup (ext0)
+^^^^^^^^^^^^^^^^^^^^^^
+
+RTC IO module contains logic to trigger wakeup when one of RTC GPIOs is set to a predefined logic level. RTC IO is part of RTC peripherals power domain, so RTC peripherals will be kept powered on during deep sleep if this wakeup source is requested. 
+
+Because RTC IO module is enabled in this mode, internal pullup or pulldown resistors can also be used. They need to be configured by the application using ``rtc_gpio_pullup_en`` and ``rtc_gpio_pulldown_en`` functions, before calling ``esp_deep_sleep_start``.
+
+In revisions 0 and 1 of the ESP32, this wakeup source is incompatible with ULP and touch wakeup sources.
+
+.. warning:: After wake up from deep sleep, IO pad used for wakeup will be configured as RTC IO. Before using this pad as digital GPIO, reconfigure it using ``rtc_gpio_deinit(gpio_num)`` function.
+
+.. doxygenfunction:: esp_deep_sleep_enable_ext0_wakeup
+
+External wakeup (ext1)
+^^^^^^^^^^^^^^^^^^^^^^
+
+RTC controller contains logic to trigger wakeup using multiple RTC GPIOs. One of the two logic functions can be used to trigger wakeup:
+
+    - wake up if any of the selected pins is high (``ESP_EXT1_WAKEUP_ANY_HIGH``)
+    - wake up if all the selected pins are low (``ESP_EXT1_WAKEUP_ALL_LOW``)
+
+This wakeup source is implemented by the RTC controller. As such, RTC peripherals and RTC memories can be powered off in this mode. However, if RTC peripherals are powered down, internal pullup and pulldown resistors will be disabled. To use internal pullup or pulldown resistors, request RTC peripherals power domain to be kept on during deep sleep, and configure pullup/pulldown resistors using ``rtc_gpio_`` functions, before entering deep sleep::
+
+    esp_deep_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON);
+    gpio_pullup_dis(gpio_num);
+    gpio_pulldown_en(gpio_num);
+
+.. warning:: After wake up from deep sleep, IO pad(s) used for wakeup will be configured as RTC IO. Before using these pads as digital GPIOs, reconfigure them using ``rtc_gpio_deinit(gpio_num)`` function.
+    
+The following function can be used to enable this wakeup mode:
+
+.. doxygenfunction:: esp_deep_sleep_enable_ext1_wakeup
+
+.. doxygenenum:: esp_ext1_wakeup_mode_t
+
+
+ULP coprocessor wakeup
+^^^^^^^^^^^^^^^^^^^^^^
+
+ULP coprocessor can run while the chip is in deep sleep, and may be used to poll sensors, monitor ADC or touch sensor values, and wake up the chip when a specific event is detected. ULP coprocessor is part of RTC peripherals power domain, and it runs the program stored in RTC slow memeory. RTC slow memory will be powered on during deep sleep if this wakeup mode is requested. RTC peripherals will be automatically powered on before ULP coprocessor starts running the program; once the program stops running, RTC peripherals are automatically powered down again.
+
+Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO).
+
+The following function can be used to enable this wakeup mode:
+
+.. doxygenfunction:: esp_deep_sleep_enable_ulp_wakeup
+
+Power-down of RTC peripherals and memories
+------------------------------------------
+
+By default, ``esp_deep_sleep_start`` function will power down all RTC power domains which are not needed by the enabled wakeup sources. To override this behaviour, the following function is provided:
+
+Note: in revision 0 of the ESP32, RTC fast memory will always be kept enabled in deep sleep, so that the deep sleep stub can run after reset. This can be overriden, if the application doesn't need clean reset behaviour after deep sleep.
+
+If some variables in the program are placed into RTC slow memory (for example, using ``RTC_DATA_ATTR`` attribute), RTC slow memory will be kept powered on by default. This can be overriden using ``esp_deep_sleep_pd_config`` function, if desired.
+
+.. doxygenfunction:: esp_deep_sleep_pd_config
+.. doxygenenum:: esp_deep_sleep_pd_domain_t
+.. doxygenenum:: esp_deep_sleep_pd_option_t
+
+
+Entering deep sleep
+-------------------
+
+The following function can be used to enter deep sleep once wakeup sources are configured. It is also possible to go into deep sleep with no wakeup sources configured, in this case the chip will be in deep sleep mode indefinetly, until external reset is applied.
+
+.. doxygenfunction:: esp_deep_sleep_start
+
+Checking deep sleep wakeup cause
+--------------------------------
+
+The following function can be used to check which wakeup source has triggered wakeup from deep sleep mode. For touch pad and ext1 wakeup sources, it is possible to identify pin or touch pad which has caused wakeup.
+
+.. doxygenfunction:: esp_deep_sleep_get_wakeup_cause
+.. doxygenenum:: esp_deep_sleep_wakeup_cause_t
+.. doxygenfunction:: esp_deep_sleep_get_touchpad_wakeup_status
+.. doxygenfunction:: esp_deep_sleep_get_ext1_wakeup_status
+
+
+Application Example
+-------------------
+ 
+Implementation of basic functionality of deep sleep is shown in :example:`protocols/sntp` example, where ESP module is periodically waken up to retrive time from NTP server.
+
+More extensive example in :example:`system/deep_sleep` illustrates usage of various deep sleep wakeup triggers and ULP coprocessor programming.

docs/api-reference/system/index.rst

@@ -0,0 +1,15 @@
+System API
+**********
+
+.. toctree::
+   :maxdepth: 1
+
+   Memory Allocation <mem_alloc>
+   Interrupt Allocation <intr_alloc>
+   Watchdogs <wdts>
+   Over The Air Updates (OTA) <ota>
+   Deep Sleep <deep_sleep>
+   Logging <log>
+
+
+Example code for this API section is provided in :example:`system` directory of ESP-IDF examples.

docs/api-reference/system/intr_alloc.rst

@@ -0,0 +1,128 @@
+Interrupt allocation
+====================
+
+Overview
+--------
+
+The ESP32 has two cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected
+to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in
+multiple drivers. The esp_intr_alloc abstraction exists to hide all these implementation details.
+
+A driver can allocate an interrupt for a certain peripheral by calling esp_intr_alloc (or esp_intr_alloc_sintrstatus). It can use
+the flags passed to this function to set the type of interrupt allocated, specifying a specific level or trigger method. The
+interrupt allocation code will then find an applicable interrupt, use the interrupt mux to hook it up to the peripheral, and
+install the given interrupt handler and ISR to it.
+
+This code has two different types of interrupts it handles differently: Shared interrupts and non-shared interrupts. The simplest
+of the two are non-shared interrupts: a separate interrupt is allocated per esp_intr_alloc call and this interrupt is solely used for
+the peripheral attached to it, with only one ISR that will get called. Non-shared interrupts can have multiple peripherals triggering 
+it, with multiple ISRs being called when one of the peripherals attached signals an interrupt. Thus, ISRs that are intended for shared
+interrupts should check the interrupt status of the peripheral they service in order to see if any action is required.
+
+Non-shared interrupts can be either level- or edge-triggered. Shared interrupts can
+only be level interrupts (because of the chance of missed interrupts when edge interrupts are
+used.)
+(The logic behind this: DevA and DevB share an int. DevB signals an int. Int line goes high. ISR handler
+calls code for DevA -> does nothing. ISR handler calls code for DevB, but while doing that,
+DevA signals an int. ISR DevB is done, clears int for DevB, exits interrupt code. Now an 
+interrupt for DevA is still pending, but because the int line never went low (DevA kept it high
+even when the int for DevB was cleared) the interrupt is never serviced.)
+
+
+Multicore issues
+----------------
+
+Peripherals that can generate interrupts can be divided in two types:
+
+  - External peripherals, within the ESP32 but outside the Xtensa cores themselves. Most ESP32 peripherals are of this type.
+  - Internal peripherals, part of the Xtensa CPU cores themselves.
+
+Interrupt handling differs slightly between these two types of peripherals.
+
+Internal peripheral interrupts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Each Xtensa CPU core has its own set of six internal peripherals:
+
+  - Three timer comparators
+  - A performance monitor
+  - Two software interrupts.
+
+Internal interrupt sources are defined in esp_intr_alloc.h as ``ETS_INTERNAL_*_INTR_SOURCE``.
+
+These peripherals can only be configured from the core they are associated with. When generating an interrupt,
+the interrupt they generate is hard-wired to their associated core; it's not possible to have e.g. an internal
+timer comparator of one core generate an interrupt on another core. That is why these sources can only be managed
+using a task running on that specific core. Internal interrupt sources are still allocatable using esp_intr_alloc
+as normal, but they cannot be shared and will always have a fixed interrupt level (namely, the one associated in
+hardware with the peripheral).
+
+External Peripheral Interrupts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The remaining interrupt sources are from external peripherals. These are defined in soc/soc.h as ``ETS_*_INTR_SOURCE``.
+
+Non-internal interrupt slots in both CPU cores are wired to an interrupt multiplexer, which can be used to
+route any external interrupt source to any of these interrupt slots.
+
+- Allocating an external interrupt will always allocate it on the core that does the allocation.
+- Freeing an external interrupt must always happen on the same core it was allocated on.
+- Disabling and enabling external interrupts from another core is allowed.
+- Multiple external interrupt sources can share an interrupt slot by passing ``ESP_INTR_FLAG_SHARED`` as a flag to esp_intr_alloc().
+
+Care should be taken when calling esp_intr_alloc() from a task which is not pinned to a core. During task switching, these tasks can migrate between cores. Therefore it is impossible to tell which CPU the interrupt is allocated on, which makes it difficult to free the interrupt handle and may also cause debugging difficulties. It is advised to use xTaskCreatePinnedToCore() with a specific CoreID argument to create tasks that will allocate interrupts. In the case of internal interrupt sources, this is required.
+
+IRAM-Safe Interrupt Handlers
+----------------------------
+
+The ``ESP_INTR_FLAG_IRAM`` flag registers an interrupt handler that always runs from IRAM (and reads all its data from DRAM), and therefore does not need to be disabled during flash erase and write operations.
+
+This is useful for interrupts which need a guaranteed minimum execution latency, as flash write and erase operations can be slow (erases can take tens or hundreds of milliseconds to complete).
+
+It can also be useful to keep an interrupt handler in IRAM if it is called very frequently, to avoid flash cache misses.
+
+Refer to the :ref:`SPI flash API documentation <iram-safe-interrupt-handlers>` for more details.
+
+Application Example
+-------------------
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :component_file:`esp32/include/esp_intr_alloc.h`
+
+
+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

docs/api-reference/system/log.rst

@@ -0,0 +1,68 @@
+.. include:: ../../../components/log/README.rst
+
+Application Example
+-------------------
+
+Log library is commonly used by most of esp-idf components and examples. For demonstration of log functionality check :idf:`examples` folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that among others, contains the following examples:
+ 
+* :example:`system/ota` 
+* :example:`storage/sd_card` 
+* :example:`protocols/https_request` 
+
+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
+
+
+
+
+
+
+
+
+
+

docs/api-reference/system/mem_alloc.rst

@@ -0,0 +1,77 @@
+Memory allocation
+====================
+
+Overview
+--------
+
+The ESP32 has multiple types of RAM. Internally, there's IRAM, DRAM as well as RAM that can be used as both. It's also
+possible to connect external SPI flash to the ESP32; it's memory can be integrated into the ESP32s memory map using
+the flash cache.
+
+In order to make use of all this memory, esp-idf has a capabilities-based memory allocator. Basically, if you want to have
+memory with certain properties (for example, DMA-capable, accessible by a certain PID, or capable of executing code), you
+can create an OR-mask of the required capabilities and pass that to pvPortMallocCaps. For instance, the normal malloc
+code internally allocates memory with ```pvPortMallocCaps(size, MALLOC_CAP_8BIT)``` in order to get data memory that is 
+byte-addressable.
+
+Because malloc uses this allocation system as well, memory allocated using pvPortMallocCaps can be freed by calling
+the standard ```free()``` function.
+
+Internally, this allocator is split in two pieces. The allocator in the FreeRTOS directory can allocate memory from
+tagged regions: a tag is an integer value and every region of free memory has one of these tags. The esp32-specific
+code initializes these regions with specific tags, and contains the logic to select applicable tags from the
+capabilities given by the user. While shown in the public API, tags are used in the communication between the two parts
+and should not be used directly.
+
+Special Uses
+------------
+
+If a certain memory structure is only addressed in 32-bit units, for example an array of ints or pointers, it can be
+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
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :component_file:`esp32/include/esp_heap_alloc_caps.h`
+  * :component_file:`freertos/include/freertos/heap_regions.h`
+
+
+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

docs/api-reference/system/ota.rst

@@ -0,0 +1,77 @@
+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.)
+
+OTA requires configuring the :doc:`Partition Table <../../api-guides/partition-tables>` of the device with at least two "OTA app slot"
+partitions (ie `ota_0` and `ota_1`) and an "OTA Data Partition".
+
+The OTA operation functions write a new app firmware image to whichever OTA app slot is not currently being used for
+booting. Once the image is verified, the OTA Data partition is updated to specify that this image should be used for the
+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.
+
+For factory boot settings, the OTA data partition should contain no data (all bytes erased to 0xFF). In this case the
+esp-idf software bootloader will boot the factory app if it is present in the the partition table. If no factory app is
+included in the partition table, the first available OTA slot (usually ``ota_0``) is booted.
+
+After the first OTA update, the OTA data partition is updated to specify which OTA app slot partition should be booted next.
+
+The OTA data partition is two flash sectors (0x2000 bytes) in size, to prevent problems if there is a power failure
+while it is being written. Sectors are independently erased and written with matching data, and if they disagree a
+counter field is used to determine which sector was written more recently.
+
+See also
+--------
+
+* :doc:`Partition Table documentation <../../api-guides/partition-tables>`
+* :doc:`Lower-Level SPI Flash/Partition API <../storage/spi_flash>`
+
+Application Example
+-------------------
+
+End-to-end example of OTA firmware update workflow: :example:`system/ota`.
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :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

docs/api-reference/system/wdts.rst

@@ -0,0 +1,72 @@
+Watchdogs
+=========
+
+Overview
+--------
+
+Esp-idf has support for two types of watchdogs: a task watchdog as well as an interrupt watchdog. Both can be
+enabled using ``make menuconfig`` and selecting the appropriate options.
+
+Interrupt watchdog
+^^^^^^^^^^^^^^^^^^
+
+The interrupt watchdog makes sure the FreeRTOS task switching interrupt isn't blocked for a long time. This
+is bad because no other tasks, including potentially important ones like the WiFi task and the idle task,
+can't get any CPU runtime. A blocked task switching interrupt can happen because a program runs into an 
+infinite loop with interrupts disabled or hangs in an interrupt.
+
+The default action of the interrupt watchdog is to invoke the panic handler. causing a register dump and an opportunity
+for the programmer to find out, using either OpenOCD or gdbstub, what bit of code is stuck with interrupts 
+disabled. Depending on the configuration of the panic handler, it can also blindly reset the CPU, which may be
+preferred in a production environment.
+
+The interrupt watchdog is built around the hardware watchdog in timer group 1. If this watchdog for some reason
+cannot execute the NMI handler that invokes the panic handler (e.g. because IRAM is overwritten by garbage),
+it will hard-reset the SOC.
+
+Task watchdog
+^^^^^^^^^^^^^
+
+Any tasks can elect to be watched by the task watchdog. If such a task does not feed the watchdog within the time
+specified by the task watchdog timeout (which is configurable using ``make menuconfig``), the watchdog will
+print out a warning with information about which processes are running on the ESP32 CPUs and which processes
+failed to feed the watchdog.
+
+By default, the task watchdog watches the idle tasks. The usual cause of idle tasks not feeding the watchdog 
+is a higher-priority process looping without yielding to the lower-priority processes, and can be an indicator
+of badly-written code that spinloops on a peripheral or a task that is stuck in an infinite loop.
+
+Other task can elect to be watched by the task watchdog by calling ``esp_task_wdt_feed()``. Calling this routine
+for the first time will register the task to the task watchdog; calling it subsequent times will feed
+the watchdog. If a task does not want to be watched anymore (e.g. because it is finished and will call 
+``vTaskDelete()`` on itself), it needs to call ``esp_task_wdt_delete()``.
+
+The task watchdog is built around the hardware watchdog in timer group 0. If this watchdog for some reason
+cannot execute the interrupt handler that prints the task data (e.g. because IRAM is overwritten by garbage
+or interrupts are disabled entirely) it will hard-reset the SOC.
+
+JTAG and watchdogs
+^^^^^^^^^^^^^^^^^^
+
+While debugging using OpenOCD, if the CPUs are halted the watchdogs will keep running, eventually resetting the
+CPU. This makes it very hard to debug code; that is why the OpenOCD config will disable both watchdogs on startup.
+This does mean that you will not get any warnings or panics from either the task or interrupt watchdog when the ESP32
+is connected to OpenOCD via JTAG.
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :component_file:`esp32/include/esp_int_wdt.h`
+  * :component_file:`esp32/include/esp_task_wdt.h`
+
+
+Functions
+---------
+
+.. doxygenfunction:: esp_int_wdt_init
+.. doxygenfunction:: esp_task_wdt_init
+.. doxygenfunction:: esp_task_wdt_feed
+.. doxygenfunction:: esp_task_wdt_delete

docs/api-reference/template.rst

@@ -0,0 +1,115 @@
+API Documentation Template 
+==========================
+
+.. note::
+
+   *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.
+
+Overview
+--------
+
+.. note::
+
+   *INSTRUCTIONS*
+
+   1. Provide overview where and how this API may be used. 
+   2. Where applicable include code snippets to illustrate functionality of particular functions.
+   3. To distinguish between sections, use the following `heading levels <http://www.sphinx-doc.org/en/stable/rest.html#sections>`_:
+
+     * ``#`` with overline, for parts
+     * ``*`` with overline, for chapters
+     * ``=``, for sections
+     * ``-``, for subsections
+     * ``^``, for subsubsections
+     * ``"``, for paragraphs
+
+Application Example
+-------------------
+
+.. note::
+
+   *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/``.
+  
+API Reference
+-------------
+
+.. note::
+
+   *INSTRUCTIONS*
+ 
+   1. Specify the names of header files used to generate this reference. Each name should be linked to the source on `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository.
+   2. Provide list of API members divided into sections. 
+   3. Use corresponding ``.. doxygen..`` directives, so member documentation is auto updated.
+
+     * Data Structures -``.. doxygenstruct::`` together with ``:members:``
+     * Macros - ``.. doxygendefine::``
+     * Type Definitions - ``.. doxygentypedef::``
+     * Enumerations - ``.. doxygenenum::``
+     * Functions - ``.. doxygenfunction::``
+
+     See `Breathe documentation <https://breathe.readthedocs.io/en/latest/directives.html>`_ for additional information. 
+
+   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.
+
+Header Files
+^^^^^^^^^^^^
+
+  * `path/header-file.h`
+
+Data Structures
+^^^^^^^^^^^^^^^
+
+::
+
+  .. doxygenstruct:: name_of_structure
+     :members:
+
+Macros
+^^^^^^
+
+::
+
+  .. doxygendefine:: name_of_macro
+
+Type Definitions
+^^^^^^^^^^^^^^^^
+
+::
+
+  .. doxygentypedef:: name_of_type
+
+Enumerations
+^^^^^^^^^^^^
+
+::
+
+  .. doxygenenum:: name_of_enumeration
+
+Functions
+^^^^^^^^^
+
+::
+
+  .. doxygenfunction:: name_of_function
+
+

docs/api-reference/wifi/esp_smartconfig.rst

@@ -0,0 +1,25 @@
+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

docs/api-reference/wifi/esp_wifi.rst

@@ -0,0 +1,78 @@
+Wi-Fi
+=====
+
+Overview
+--------
+
+`Instructions`_
+
+.. _Instructions: ../template.html
+
+Application Example
+-------------------
+
+Simple code showing how to connect ESP32 module to an Access Point: `esp-idf-template <https://github.com/espressif/esp-idf-template>`_.
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * :component_file:`esp32/include/esp_wifi.h`
+
+Macros
+------
+
+.. doxygendefine:: WIFI_INIT_CONFIG_DEFAULT
+
+
+Type Definitions
+----------------
+
+.. doxygentypedef:: wifi_promiscuous_cb_t
+.. doxygentypedef:: esp_vendor_ie_cb_t
+
+Functions
+---------
+
+.. doxygenfunction:: esp_wifi_init
+.. doxygenfunction:: esp_wifi_deinit
+.. doxygenfunction:: esp_wifi_set_mode
+.. doxygenfunction:: esp_wifi_get_mode
+.. doxygenfunction:: esp_wifi_start
+.. doxygenfunction:: esp_wifi_stop
+.. doxygenfunction:: esp_wifi_connect
+.. doxygenfunction:: esp_wifi_disconnect
+.. doxygenfunction:: esp_wifi_clear_fast_connect
+.. doxygenfunction:: esp_wifi_deauth_sta
+.. doxygenfunction:: esp_wifi_scan_start
+.. doxygenfunction:: esp_wifi_scan_stop
+.. doxygenfunction:: esp_wifi_scan_get_ap_num
+.. doxygenfunction:: esp_wifi_scan_get_ap_records
+.. doxygenfunction:: esp_wifi_sta_get_ap_info
+.. doxygenfunction:: esp_wifi_set_ps
+.. doxygenfunction:: esp_wifi_get_ps
+.. doxygenfunction:: esp_wifi_set_protocol
+.. doxygenfunction:: esp_wifi_get_protocol
+.. doxygenfunction:: esp_wifi_set_bandwidth
+.. doxygenfunction:: esp_wifi_get_bandwidth
+.. doxygenfunction:: esp_wifi_set_channel
+.. doxygenfunction:: esp_wifi_get_channel
+.. doxygenfunction:: esp_wifi_set_country
+.. doxygenfunction:: esp_wifi_get_country
+.. doxygenfunction:: esp_wifi_set_mac
+.. doxygenfunction:: esp_wifi_get_mac
+.. doxygenfunction:: esp_wifi_set_promiscuous_rx_cb
+.. doxygenfunction:: esp_wifi_set_promiscuous
+.. doxygenfunction:: esp_wifi_get_promiscuous
+.. doxygenfunction:: esp_wifi_set_config
+.. doxygenfunction:: esp_wifi_get_config
+.. doxygenfunction:: esp_wifi_ap_get_sta_list
+.. doxygenfunction:: esp_wifi_set_storage
+.. doxygenfunction:: esp_wifi_set_auto_connect
+.. doxygenfunction:: esp_wifi_get_auto_connect
+.. doxygenfunction:: esp_wifi_set_vendor_ie
+.. doxygenfunction:: esp_wifi_set_vendor_ie_cb
+
+

docs/api-reference/wifi/index.rst

@@ -0,0 +1,11 @@
+Wi-Fi API
+*********
+
+.. toctree::
+   :maxdepth: 1
+
+   Wi-Fi <esp_wifi>
+   Smart Config <esp_smartconfig>
+
+
+Example code for this API section is provided in :example:`wifi` directory of ESP-IDF examples.