forked from espressif/esp-idf
Merge branch 'doc/multi_target' into 'master'
docs: Multi target build support Closes IDF-523 See merge request espressif/esp-idf!6791
This commit is contained in:
Angus Gratton
@@ -6,7 +6,7 @@ stages:
|
||||
- target_test
|
||||
- post_check
|
||||
- deploy
|
||||
- post_check
|
||||
- post_deploy
|
||||
|
||||
variables:
|
||||
# System environment
|
||||
@@ -76,6 +76,9 @@ variables:
|
||||
rm -rf "$CUSTOM_TOOLCHAIN_PATH"
|
||||
|
||||
.setup_tools_unless_target_test: &setup_tools_unless_target_test |
|
||||
if [[ -n "$IDF_DONT_USE_MIRRORS" ]]; then
|
||||
export IDF_MIRROR_PREFIX_MAP=
|
||||
fi
|
||||
if [[ "$SETUP_TOOLS" == "1" || "$CI_JOB_STAGE" != "target_test" ]]; then
|
||||
tools/idf_tools.py --non-interactive install && eval "$(tools/idf_tools.py --non-interactive export)" || exit 1
|
||||
fi
|
||||
@@ -142,7 +145,7 @@ after_script:
|
||||
tags:
|
||||
- host_test
|
||||
dependencies: []
|
||||
extends: .before_script_lesser_nofilter
|
||||
extends: .before_script_lesser
|
||||
|
||||
.macos_build_template:
|
||||
stage: build
|
||||
@@ -163,3 +166,4 @@ include:
|
||||
- '/tools/ci/config/target-test.yml'
|
||||
- '/tools/ci/config/post_check.yml'
|
||||
- '/tools/ci/config/deploy.yml'
|
||||
- '/tools/ci/config/post_deploy.yml'
|
||||
|
||||
@@ -2,8 +2,6 @@
|
||||
|
||||
* [中文版](./README_CN.md)
|
||||
|
||||
[](https://docs.espressif.com/projects/esp-idf/en/latest/?badge=latest)
|
||||
|
||||
ESP-IDF is the official development framework for the [ESP32](https://espressif.com/en/products/hardware/esp32/overview) chip.
|
||||
|
||||
# Developing With ESP-IDF
|
||||
@@ -15,6 +13,8 @@ See setup guides for detailed instructions to set up the ESP-IDF:
|
||||
* [Getting Started Guide for the stable ESP-IDF version](https://docs.espressif.com/projects/esp-idf/en/stable/get-started/)
|
||||
* [Getting Started Guide for the latest (master branch) ESP-IDF version](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/)
|
||||
|
||||
*Note: ESP-IDF Programmers Guide is in the process of transitioning to a new documentation host. Master branch ("latest") docs will not be updated from 2020-02-05 for approximately two weeks. This note will be removed once the master branch docs are updating again. Other branch & release docs continue to update as normal.*
|
||||
|
||||
### Non-GitHub forks
|
||||
|
||||
ESP-IDF uses relative locations as its submodules URLs ([.gitmodules](.gitmodules)). So they link to GitHub.
|
||||
|
||||
@@ -439,11 +439,11 @@ typedef struct {
|
||||
struct esp_ble_mesh_model {
|
||||
/** Model ID */
|
||||
union {
|
||||
const uint16_t model_id;
|
||||
struct {
|
||||
uint16_t company_id;
|
||||
uint16_t model_id;
|
||||
} vnd;
|
||||
const uint16_t model_id; /*!< 16-bit model identifier */
|
||||
struct esp_ble_mesh_vnd_struct {
|
||||
uint16_t company_id; /*!< 16-bit company identifier */
|
||||
uint16_t model_id; /*!< 16-bit model identifier */
|
||||
} vnd; /*!< Structure encapsulating a model ID with a company ID */
|
||||
};
|
||||
|
||||
/** Internal information, mainly for persistent storage */
|
||||
|
||||
@@ -31,7 +31,8 @@ extern "C" {
|
||||
|
||||
typedef uint8_t esp_a2d_mct_t;
|
||||
|
||||
/// A2DP media codec capabilities union
|
||||
/** A2DP media codec capabilities union
|
||||
*/
|
||||
typedef struct {
|
||||
esp_a2d_mct_t type; /*!< A2DP media codec type */
|
||||
#define ESP_A2D_CIE_LEN_SBC (4)
|
||||
@@ -39,10 +40,10 @@ typedef struct {
|
||||
#define ESP_A2D_CIE_LEN_M24 (6)
|
||||
#define ESP_A2D_CIE_LEN_ATRAC (7)
|
||||
union {
|
||||
uint8_t sbc[ESP_A2D_CIE_LEN_SBC];
|
||||
uint8_t m12[ESP_A2D_CIE_LEN_M12];
|
||||
uint8_t m24[ESP_A2D_CIE_LEN_M24];
|
||||
uint8_t atrac[ESP_A2D_CIE_LEN_ATRAC];
|
||||
uint8_t sbc[ESP_A2D_CIE_LEN_SBC]; /*!< SBC codec capabilities */
|
||||
uint8_t m12[ESP_A2D_CIE_LEN_M12]; /*!< MPEG-1,2 audio codec capabilities */
|
||||
uint8_t m24[ESP_A2D_CIE_LEN_M24]; /*!< MPEG-2, 4 AAC audio codec capabilities */
|
||||
uint8_t atrac[ESP_A2D_CIE_LEN_ATRAC]; /*!< ATRAC family codec capabilities */
|
||||
} cie; /*!< A2DP codec information element */
|
||||
} __attribute__((packed)) esp_a2d_mcc_t;
|
||||
|
||||
|
||||
@@ -86,9 +86,9 @@ typedef struct {
|
||||
#define ESP_UUID_LEN_128 16
|
||||
uint16_t len; /*!< UUID length, 16bit, 32bit or 128bit */
|
||||
union {
|
||||
uint16_t uuid16;
|
||||
uint32_t uuid32;
|
||||
uint8_t uuid128[ESP_UUID_LEN_128];
|
||||
uint16_t uuid16; /*!< 16bit UUID */
|
||||
uint32_t uuid32; /*!< 32bit UUID */
|
||||
uint8_t uuid128[ESP_UUID_LEN_128]; /*!< 128bit UUID */
|
||||
} uuid; /*!< UUID */
|
||||
} __attribute__((packed)) esp_bt_uuid_t;
|
||||
|
||||
|
||||
@@ -51,22 +51,22 @@ esp_err_t touch_pad_sw_start(void);
|
||||
* sleep_cycle decide the interval between each measurement.
|
||||
* t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency).
|
||||
* The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function.
|
||||
* @param meas_timers The times of charge and discharge in each measure process of touch channels.
|
||||
* @param meas_time The time of charge and discharge in each measure process of touch channels.
|
||||
* The timer frequency is 8Mhz. Range: 0 ~ 0xffff.
|
||||
* Recommended typical value: Modify this value to make the measurement time around 1ms.
|
||||
* @return
|
||||
* - ESP_OK on success
|
||||
*/
|
||||
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times);
|
||||
esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_time);
|
||||
|
||||
/**
|
||||
* @brief Get touch sensor times of charge and discharge and sleep time
|
||||
* @param sleep_cycle Pointer to accept sleep cycle number
|
||||
* @param meas_times Pointer to accept measurement times count.
|
||||
* @param meas_time Pointer to accept measurement time count.
|
||||
* @return
|
||||
* - ESP_OK on success
|
||||
*/
|
||||
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times);
|
||||
esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_time);
|
||||
|
||||
/**
|
||||
* @brief Set connection type of touch channel in idle status.
|
||||
@@ -196,7 +196,7 @@ uint32_t touch_pad_read_intr_status_mask(void);
|
||||
|
||||
/**
|
||||
* @brief Enable touch sensor interrupt by bitmask.
|
||||
* @param type interrupt type
|
||||
* @param int_mask Pad mask to enable interrupts
|
||||
* @return
|
||||
* - ESP_OK on success
|
||||
*/
|
||||
@@ -204,7 +204,7 @@ esp_err_t touch_pad_intr_enable(touch_pad_intr_mask_t int_mask);
|
||||
|
||||
/**
|
||||
* @brief Disable touch sensor interrupt by bitmask.
|
||||
* @param type interrupt type
|
||||
* @param int_mask Pad mask to disable interrupts
|
||||
* @return
|
||||
* - ESP_OK on success
|
||||
*/
|
||||
@@ -215,12 +215,13 @@ esp_err_t touch_pad_intr_disable(touch_pad_intr_mask_t int_mask);
|
||||
* The handler will be attached to the same CPU core that this function is running on.
|
||||
* @param fn Pointer to ISR handler
|
||||
* @param arg Parameter for ISR
|
||||
* @param int_mask Initial pad mask to enable interrupt for
|
||||
* @return
|
||||
* - ESP_OK Success ;
|
||||
* - ESP_ERR_INVALID_ARG GPIO error
|
||||
* - ESP_ERR_NO_MEM No memory
|
||||
*/
|
||||
esp_err_t touch_pad_isr_register(intr_handler_t fn, void* arg, touch_pad_intr_mask_t intr_mask);
|
||||
esp_err_t touch_pad_isr_register(intr_handler_t fn, void* arg, touch_pad_intr_mask_t int_mask);
|
||||
|
||||
/**
|
||||
* @brief get raw data of touch sensor.
|
||||
@@ -239,7 +240,7 @@ esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint32_t *raw_data);
|
||||
* @brief get baseline of touch sensor.
|
||||
* @note After initialization, the baseline value is the maximum during the first measurement period.
|
||||
* @param touch_num touch pad index
|
||||
* @param touch_value pointer to accept touch sensor value
|
||||
* @param basedata pointer to accept touch sensor baseline value
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Touch channel 0 havent this parameter.
|
||||
@@ -331,7 +332,7 @@ esp_err_t touch_pad_denoise_disable(void);
|
||||
|
||||
/**
|
||||
* @brief Get denoise measure value (TOUCH_PAD_NUM0).
|
||||
* @param denoise value of denoise
|
||||
* @param data Pointer to receive denoise value
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
*/
|
||||
@@ -405,7 +406,7 @@ esp_err_t touch_pad_proximity_get_config(touch_pad_proximity_t *proximity);
|
||||
* @brief Get measure count of proximity channel.
|
||||
* The proximity sensor measurement is the accumulation of touch channel measurements.
|
||||
* @param touch_num touch pad index
|
||||
* @param proximity parameter of proximity
|
||||
* @param cnt Pointer to receive proximity channel measurement count
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG parameter is NULL
|
||||
|
||||
@@ -331,8 +331,6 @@ esp_err_t timer_disable_intr(timer_group_t group_num, timer_idx_t timer_num);
|
||||
* @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1
|
||||
* @param timer_num Timer index.
|
||||
*
|
||||
* @return
|
||||
* - None
|
||||
*/
|
||||
void timer_group_intr_clr_in_isr(timer_group_t group_num, timer_idx_t timer_num) __attribute__((deprecated));
|
||||
|
||||
@@ -341,8 +339,6 @@ void timer_group_intr_clr_in_isr(timer_group_t group_num, timer_idx_t timer_num)
|
||||
* @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1
|
||||
* @param timer_num Timer index.
|
||||
*
|
||||
* @return
|
||||
* - None
|
||||
*/
|
||||
void timer_group_clr_intr_status_in_isr(timer_group_t group_num, timer_idx_t timer_num);
|
||||
|
||||
@@ -351,8 +347,6 @@ void timer_group_clr_intr_status_in_isr(timer_group_t group_num, timer_idx_t tim
|
||||
* @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1
|
||||
* @param timer_num Timer index.
|
||||
*
|
||||
* @return
|
||||
* - None
|
||||
*/
|
||||
void timer_group_enable_alarm_in_isr(timer_group_t group_num, timer_idx_t timer_num);
|
||||
|
||||
@@ -372,8 +366,6 @@ uint64_t timer_group_get_counter_value_in_isr(timer_group_t group_num, timer_idx
|
||||
* @param timer_num Timer index.
|
||||
* @param alarm_val Alarm threshold.
|
||||
*
|
||||
* @return
|
||||
* - None
|
||||
*/
|
||||
void timer_group_set_alarm_value_in_isr(timer_group_t group_num, timer_idx_t timer_num, uint64_t alarm_val);
|
||||
|
||||
@@ -383,8 +375,6 @@ void timer_group_set_alarm_value_in_isr(timer_group_t group_num, timer_idx_t tim
|
||||
* @param timer_num Timer index.
|
||||
* @param counter_en Enable/disable.
|
||||
*
|
||||
* @return
|
||||
* - None
|
||||
*/
|
||||
void timer_group_set_counter_enable_in_isr(timer_group_t group_num, timer_idx_t timer_num, timer_start_t counter_en);
|
||||
|
||||
@@ -411,8 +401,6 @@ uint32_t timer_group_get_intr_status_in_isr(timer_group_t group_num);
|
||||
* @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1
|
||||
* @param intr_mask Masked interrupt.
|
||||
*
|
||||
* @return
|
||||
* - None
|
||||
*/
|
||||
void timer_group_clr_intr_sta_in_isr(timer_group_t group_num, timer_intr_t intr_mask) __attribute__((deprecated));
|
||||
|
||||
|
||||
@@ -56,7 +56,6 @@ extern "C" {
|
||||
#define ESP_INTR_FLAG_LEVELMASK (ESP_INTR_FLAG_LEVEL1|ESP_INTR_FLAG_LEVEL2|ESP_INTR_FLAG_LEVEL3| \
|
||||
ESP_INTR_FLAG_LEVEL4|ESP_INTR_FLAG_LEVEL5|ESP_INTR_FLAG_LEVEL6| \
|
||||
ESP_INTR_FLAG_NMI) ///< Mask for all level flags
|
||||
/**@}*/
|
||||
|
||||
|
||||
/** @addtogroup Intr_Alloc_Pseudo_Src
|
||||
@@ -78,16 +77,23 @@ extern "C" {
|
||||
|
||||
/**@}*/
|
||||
|
||||
// This is used to provide SystemView with positive IRQ IDs, otherwise sheduler events are not shown properly
|
||||
/** Provides SystemView with positive IRQ IDs, otherwise scheduler events are not shown properly
|
||||
*/
|
||||
#define ETS_INTERNAL_INTR_SOURCE_OFF (-ETS_INTERNAL_PROFILING_INTR_SOURCE)
|
||||
|
||||
/** Enable interrupt by interrupt number */
|
||||
#define ESP_INTR_ENABLE(inum) xt_ints_on((1<<inum))
|
||||
|
||||
/** Disable interrupt by interrupt number */
|
||||
#define ESP_INTR_DISABLE(inum) xt_ints_off((1<<inum))
|
||||
|
||||
/** Function prototype for interrupt handler function */
|
||||
typedef void (*intr_handler_t)(void *arg);
|
||||
|
||||
|
||||
/** Interrupt handler associated data structure */
|
||||
typedef struct intr_handle_data_t intr_handle_data_t;
|
||||
|
||||
/** Handle to an interrupt handler */
|
||||
typedef intr_handle_data_t* intr_handle_t ;
|
||||
|
||||
/**
|
||||
|
||||
@@ -56,7 +56,6 @@ extern "C" {
|
||||
#define ESP_INTR_FLAG_LEVELMASK (ESP_INTR_FLAG_LEVEL1|ESP_INTR_FLAG_LEVEL2|ESP_INTR_FLAG_LEVEL3| \
|
||||
ESP_INTR_FLAG_LEVEL4|ESP_INTR_FLAG_LEVEL5|ESP_INTR_FLAG_LEVEL6| \
|
||||
ESP_INTR_FLAG_NMI) ///< Mask for all level flags
|
||||
/**@}*/
|
||||
|
||||
|
||||
/** @addtogroup Intr_Alloc_Pseudo_Src
|
||||
@@ -78,16 +77,23 @@ extern "C" {
|
||||
|
||||
/**@}*/
|
||||
|
||||
// This is used to provide SystemView with positive IRQ IDs, otherwise sheduler events are not shown properly
|
||||
/** Provides SystemView with positive IRQ IDs, otherwise scheduler events are not shown properly
|
||||
*/
|
||||
#define ETS_INTERNAL_INTR_SOURCE_OFF (-ETS_INTERNAL_PROFILING_INTR_SOURCE)
|
||||
|
||||
/** Enable interrupt by interrupt number */
|
||||
#define ESP_INTR_ENABLE(inum) xt_ints_on((1<<inum))
|
||||
|
||||
/** Disable interrupt by interrupt number */
|
||||
#define ESP_INTR_DISABLE(inum) xt_ints_off((1<<inum))
|
||||
|
||||
/** Function prototype for interrupt handler function */
|
||||
typedef void (*intr_handler_t)(void *arg);
|
||||
|
||||
|
||||
/** Interrupt handler associated data structure */
|
||||
typedef struct intr_handle_data_t intr_handle_data_t;
|
||||
|
||||
/** Handle to an interrupt handler */
|
||||
typedef intr_handle_data_t* intr_handle_t ;
|
||||
|
||||
/**
|
||||
|
||||
@@ -302,6 +302,7 @@ esp_err_t esp_event_isr_post(esp_event_base_t event_base,
|
||||
/**
|
||||
* @brief Special variant of esp_event_post_to for posting events from interrupt handlers
|
||||
*
|
||||
* @param[in] event_loop the event loop to post to
|
||||
* @param[in] event_base the event base that identifies the event
|
||||
* @param[in] event_id the event id that identifies the event
|
||||
* @param[in] event_data the data, specific to the event occurence, that gets passed to the handler
|
||||
|
||||
@@ -308,7 +308,8 @@ endmenu # Wi-Fi
|
||||
menu "PHY"
|
||||
|
||||
config ESP32_PHY_CALIBRATION_AND_DATA_STORAGE
|
||||
# ToDo: remove once NVS and PHY partial calibration are supported
|
||||
# ToDo: remove target dependency once NVS and PHY partial calibration are supported
|
||||
# also re-enable the <RF_calibration> entry in docs/../api-guides/index.rst
|
||||
depends on IDF_TARGET_ESP32
|
||||
bool "Store phy calibration data in NVS"
|
||||
default y
|
||||
|
||||
@@ -114,7 +114,7 @@ typedef union {
|
||||
uart_port_t port; /*!< Modbus communication port (UART) number */
|
||||
uint32_t baudrate; /*!< Modbus baudrate */
|
||||
uart_parity_t parity; /*!< Modbus UART parity settings */
|
||||
uint16_t dummy_port;
|
||||
uint16_t dummy_port; /*!< Dummy field, unused */
|
||||
};
|
||||
// Tcp communication structure
|
||||
struct {
|
||||
|
||||
@@ -83,11 +83,11 @@ typedef struct{
|
||||
union {
|
||||
struct {
|
||||
uint32_t clk_speed; /*!< I2C clock frequency for master mode, (no higher than 1MHz for now) */
|
||||
} master;
|
||||
} master; /*!< I2C master config */
|
||||
struct {
|
||||
uint8_t addr_10bit_en; /*!< I2C 10bit address mode enable for slave mode */
|
||||
uint16_t slave_addr; /*!< I2C address for slave mode */
|
||||
} slave;
|
||||
} slave; /*!< I2C slave config */
|
||||
};
|
||||
} i2c_config_t;
|
||||
|
||||
|
||||
@@ -17,6 +17,7 @@
|
||||
#include "soc/touch_sensor_caps.h"
|
||||
#include "sdkconfig.h"
|
||||
|
||||
/** Touch pad channel */
|
||||
typedef enum {
|
||||
TOUCH_PAD_NUM0 = 0, /*!< Touch pad channel 0 is GPIO4(ESP32) */
|
||||
TOUCH_PAD_NUM1, /*!< Touch pad channel 1 is GPIO0(ESP32) / GPIO1(ESP32-S2) */
|
||||
@@ -38,6 +39,7 @@ typedef enum {
|
||||
TOUCH_PAD_MAX,
|
||||
} touch_pad_t;
|
||||
|
||||
/** Touch sensor high reference voltage */
|
||||
typedef enum {
|
||||
TOUCH_HVOLT_KEEP = -1, /*!<Touch sensor high reference voltage, no change */
|
||||
TOUCH_HVOLT_2V4 = 0, /*!<Touch sensor high reference voltage, 2.4V */
|
||||
@@ -47,6 +49,7 @@ typedef enum {
|
||||
TOUCH_HVOLT_MAX,
|
||||
} touch_high_volt_t;
|
||||
|
||||
/** Touch sensor low reference voltage */
|
||||
typedef enum {
|
||||
TOUCH_LVOLT_KEEP = -1, /*!<Touch sensor low reference voltage, no change */
|
||||
TOUCH_LVOLT_0V5 = 0, /*!<Touch sensor low reference voltage, 0.5V */
|
||||
@@ -56,6 +59,7 @@ typedef enum {
|
||||
TOUCH_LVOLT_MAX,
|
||||
} touch_low_volt_t;
|
||||
|
||||
/** Touch sensor high reference voltage attenuation */
|
||||
typedef enum {
|
||||
TOUCH_HVOLT_ATTEN_KEEP = -1, /*!<Touch sensor high reference voltage attenuation, no change */
|
||||
TOUCH_HVOLT_ATTEN_1V5 = 0, /*!<Touch sensor high reference voltage attenuation, 1.5V attenuation */
|
||||
@@ -65,6 +69,7 @@ typedef enum {
|
||||
TOUCH_HVOLT_ATTEN_MAX,
|
||||
} touch_volt_atten_t;
|
||||
|
||||
/** Touch sensor charge/discharge speed */
|
||||
typedef enum {
|
||||
TOUCH_PAD_SLOPE_0 = 0, /*!<Touch sensor charge / discharge speed, always zero */
|
||||
TOUCH_PAD_SLOPE_1 = 1, /*!<Touch sensor charge / discharge speed, slowest */
|
||||
@@ -77,12 +82,14 @@ typedef enum {
|
||||
TOUCH_PAD_SLOPE_MAX,
|
||||
} touch_cnt_slope_t;
|
||||
|
||||
/** Touch sensor initial charge level */
|
||||
typedef enum {
|
||||
TOUCH_PAD_TIE_OPT_LOW = 0, /*!<Initial level of charging voltage, low level */
|
||||
TOUCH_PAD_TIE_OPT_HIGH = 1, /*!<Initial level of charging voltage, high level */
|
||||
TOUCH_PAD_TIE_OPT_MAX,
|
||||
} touch_tie_opt_t;
|
||||
|
||||
/** Touch sensor FSM mode */
|
||||
typedef enum {
|
||||
TOUCH_FSM_MODE_TIMER = 0, /*!<To start touch FSM by timer */
|
||||
TOUCH_FSM_MODE_SW, /*!<To start touch FSM by software trigger */
|
||||
@@ -175,6 +182,7 @@ typedef enum {
|
||||
TOUCH_PAD_DENOISE_CAP_MAX
|
||||
} touch_pad_denoise_cap_t;
|
||||
|
||||
/** Touch sensor denoise configuration */
|
||||
typedef struct touch_pad_denoise {
|
||||
touch_pad_denoise_grade_t grade; /*!<Select denoise range of denoise channel.
|
||||
Determined by measuring the noise amplitude of the denoise channel. */
|
||||
@@ -195,6 +203,7 @@ typedef enum {
|
||||
TOUCH_PAD_SHIELD_DRV_MAX
|
||||
} touch_pad_shield_driver_t;
|
||||
|
||||
/** Touch sensor waterproof configuration */
|
||||
typedef struct touch_pad_waterproof {
|
||||
touch_pad_t guard_ring_pad; /*!<Waterproof. Select touch channel use for guard pad */
|
||||
touch_pad_shield_driver_t shield_driver;/*!<Waterproof. Select max equivalent capacitance for sheild pad
|
||||
@@ -202,6 +211,7 @@ typedef struct touch_pad_waterproof {
|
||||
reading to the Touch0 reading to estimate the equivalent capacitance.*/
|
||||
} touch_pad_waterproof_t;
|
||||
|
||||
/** Touch sensor proximity detection configuration */
|
||||
typedef struct touch_pad_proximity {
|
||||
touch_pad_t select_pad[SOC_TOUCH_PROXIMITY_CHANNEL_NUM]; /*!<Set touch channel number for proximity pad.
|
||||
If clear the proximity channel, point this pad to `TOUCH_PAD_NUM0` */
|
||||
@@ -209,9 +219,10 @@ typedef struct touch_pad_proximity {
|
||||
#define TOUCH_PROXIMITY_MEAS_NUM_MAX (0xFF)
|
||||
} touch_pad_proximity_t;
|
||||
|
||||
/** Touch channel idle state configuration */
|
||||
typedef enum {
|
||||
TOUCH_PAD_CONN_HIGHZ = 0, /*!<Idel status of touch channel is high resistance state */
|
||||
TOUCH_PAD_CONN_GND = 1, /*!<Idel status of touch channel is ground connection */
|
||||
TOUCH_PAD_CONN_HIGHZ = 0, /*!<Idle status of touch channel is high resistance state */
|
||||
TOUCH_PAD_CONN_GND = 1, /*!<Idle status of touch channel is ground connection */
|
||||
TOUCH_PAD_CONN_MAX
|
||||
} touch_pad_conn_type_t;
|
||||
|
||||
@@ -223,6 +234,7 @@ typedef enum {
|
||||
TOUCH_PAD_FILTER_MAX
|
||||
} touch_filter_mode_t;
|
||||
|
||||
/** Touch sensor filter configuration */
|
||||
typedef struct touch_filter_config {
|
||||
touch_filter_mode_t mode; /*!<Set filter mode. The input to the filter is raw data and the output is the baseline value.
|
||||
Larger filter coefficients increase the stability of the baseline. */
|
||||
@@ -253,6 +265,7 @@ typedef struct touch_filter_config {
|
||||
#define TOUCH_JITTER_STEP_MAX (15)
|
||||
} touch_filter_config_t;
|
||||
|
||||
/** Touch sensor channel sleep configuration */
|
||||
typedef struct {
|
||||
touch_pad_t touch_num; /*!<Set touch channel number for sleep pad.
|
||||
Only one touch sensor channel is supported in deep sleep mode. */
|
||||
|
||||
@@ -136,7 +136,7 @@ typedef struct {
|
||||
uint8_t rx_flow_ctrl_thresh; /*!< UART HW RTS threshold*/
|
||||
union {
|
||||
uart_sclk_t source_clk; /*!< UART source clock selection */
|
||||
bool use_ref_tick __attribute__((deprecated));
|
||||
bool use_ref_tick __attribute__((deprecated)); /*!< Deprecated method to select ref tick clock source, set source_clk field instead */
|
||||
};
|
||||
} uart_config_t;
|
||||
|
||||
|
||||
@@ -101,137 +101,137 @@ typedef struct
|
||||
{
|
||||
int flags; /*!< ESP_VFS_FLAG_CONTEXT_PTR or ESP_VFS_FLAG_DEFAULT */
|
||||
union {
|
||||
ssize_t (*write_p)(void* p, int fd, const void * data, size_t size);
|
||||
ssize_t (*write)(int fd, const void * data, size_t size);
|
||||
ssize_t (*write_p)(void* p, int fd, const void * data, size_t size); /*!< Write with context pointer */
|
||||
ssize_t (*write)(int fd, const void * data, size_t size); /*!< Write without context pointer */
|
||||
};
|
||||
union {
|
||||
off_t (*lseek_p)(void* p, int fd, off_t size, int mode);
|
||||
off_t (*lseek)(int fd, off_t size, int mode);
|
||||
off_t (*lseek_p)(void* p, int fd, off_t size, int mode); /*!< Seek with context pointer */
|
||||
off_t (*lseek)(int fd, off_t size, int mode); /*!< Seek without context pointer */
|
||||
};
|
||||
union {
|
||||
ssize_t (*read_p)(void* ctx, int fd, void * dst, size_t size);
|
||||
ssize_t (*read)(int fd, void * dst, size_t size);
|
||||
ssize_t (*read_p)(void* ctx, int fd, void * dst, size_t size); /*!< Read with context pointer */
|
||||
ssize_t (*read)(int fd, void * dst, size_t size); /*!< Read without context pointer */
|
||||
};
|
||||
union {
|
||||
ssize_t (*pread_p)(void *ctx, int fd, void * dst, size_t size, off_t offset);
|
||||
ssize_t (*pread)(int fd, void * dst, size_t size, off_t offset);
|
||||
ssize_t (*pread_p)(void *ctx, int fd, void * dst, size_t size, off_t offset); /*!< pread with context pointer */
|
||||
ssize_t (*pread)(int fd, void * dst, size_t size, off_t offset); /*!< pread without context pointer */
|
||||
};
|
||||
union {
|
||||
ssize_t (*pwrite_p)(void *ctx, int fd, const void *src, size_t size, off_t offset);
|
||||
ssize_t (*pwrite)(int fd, const void *src, size_t size, off_t offset);
|
||||
ssize_t (*pwrite_p)(void *ctx, int fd, const void *src, size_t size, off_t offset); /*!< pwrite with context pointer */
|
||||
ssize_t (*pwrite)(int fd, const void *src, size_t size, off_t offset); /*!< pwrite without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*open_p)(void* ctx, const char * path, int flags, int mode);
|
||||
int (*open)(const char * path, int flags, int mode);
|
||||
int (*open_p)(void* ctx, const char * path, int flags, int mode); /*!< open with context pointer */
|
||||
int (*open)(const char * path, int flags, int mode); /*!< open without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*close_p)(void* ctx, int fd);
|
||||
int (*close)(int fd);
|
||||
int (*close_p)(void* ctx, int fd); /*!< close with context pointer */
|
||||
int (*close)(int fd); /*!< close without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*fstat_p)(void* ctx, int fd, struct stat * st);
|
||||
int (*fstat)(int fd, struct stat * st);
|
||||
int (*fstat_p)(void* ctx, int fd, struct stat * st); /*!< fstat with context pointer */
|
||||
int (*fstat)(int fd, struct stat * st); /*!< fstat without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*stat_p)(void* ctx, const char * path, struct stat * st);
|
||||
int (*stat)(const char * path, struct stat * st);
|
||||
int (*stat_p)(void* ctx, const char * path, struct stat * st); /*!< stat with context pointer */
|
||||
int (*stat)(const char * path, struct stat * st); /*!< stat without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*link_p)(void* ctx, const char* n1, const char* n2);
|
||||
int (*link)(const char* n1, const char* n2);
|
||||
int (*link_p)(void* ctx, const char* n1, const char* n2); /*!< link with context pointer */
|
||||
int (*link)(const char* n1, const char* n2); /*!< link without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*unlink_p)(void* ctx, const char *path);
|
||||
int (*unlink)(const char *path);
|
||||
int (*unlink_p)(void* ctx, const char *path); /*!< unlink with context pointer */
|
||||
int (*unlink)(const char *path); /*!< unlink without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*rename_p)(void* ctx, const char *src, const char *dst);
|
||||
int (*rename)(const char *src, const char *dst);
|
||||
int (*rename_p)(void* ctx, const char *src, const char *dst); /*!< rename with context pointer */
|
||||
int (*rename)(const char *src, const char *dst); /*!< rename without context pointer */
|
||||
};
|
||||
union {
|
||||
DIR* (*opendir_p)(void* ctx, const char* name);
|
||||
DIR* (*opendir)(const char* name);
|
||||
DIR* (*opendir_p)(void* ctx, const char* name); /*!< opendir with context pointer */
|
||||
DIR* (*opendir)(const char* name); /*!< opendir without context pointer */
|
||||
};
|
||||
union {
|
||||
struct dirent* (*readdir_p)(void* ctx, DIR* pdir);
|
||||
struct dirent* (*readdir)(DIR* pdir);
|
||||
struct dirent* (*readdir_p)(void* ctx, DIR* pdir); /*!< readdir with context pointer */
|
||||
struct dirent* (*readdir)(DIR* pdir); /*!< readdir without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*readdir_r_p)(void* ctx, DIR* pdir, struct dirent* entry, struct dirent** out_dirent);
|
||||
int (*readdir_r)(DIR* pdir, struct dirent* entry, struct dirent** out_dirent);
|
||||
int (*readdir_r_p)(void* ctx, DIR* pdir, struct dirent* entry, struct dirent** out_dirent); /*!< readdir_r with context pointer */
|
||||
int (*readdir_r)(DIR* pdir, struct dirent* entry, struct dirent** out_dirent); /*!< readdir_r without context pointer */
|
||||
};
|
||||
union {
|
||||
long (*telldir_p)(void* ctx, DIR* pdir);
|
||||
long (*telldir)(DIR* pdir);
|
||||
long (*telldir_p)(void* ctx, DIR* pdir); /*!< telldir with context pointer */
|
||||
long (*telldir)(DIR* pdir); /*!< telldir without context pointer */
|
||||
};
|
||||
union {
|
||||
void (*seekdir_p)(void* ctx, DIR* pdir, long offset);
|
||||
void (*seekdir)(DIR* pdir, long offset);
|
||||
void (*seekdir_p)(void* ctx, DIR* pdir, long offset); /*!< seekdir with context pointer */
|
||||
void (*seekdir)(DIR* pdir, long offset); /*!< seekdir without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*closedir_p)(void* ctx, DIR* pdir);
|
||||
int (*closedir)(DIR* pdir);
|
||||
int (*closedir_p)(void* ctx, DIR* pdir); /*!< closedir with context pointer */
|
||||
int (*closedir)(DIR* pdir); /*!< closedir without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*mkdir_p)(void* ctx, const char* name, mode_t mode);
|
||||
int (*mkdir)(const char* name, mode_t mode);
|
||||
int (*mkdir_p)(void* ctx, const char* name, mode_t mode); /*!< mkdir with context pointer */
|
||||
int (*mkdir)(const char* name, mode_t mode); /*!< mkdir without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*rmdir_p)(void* ctx, const char* name);
|
||||
int (*rmdir)(const char* name);
|
||||
int (*rmdir_p)(void* ctx, const char* name); /*!< rmdir with context pointer */
|
||||
int (*rmdir)(const char* name); /*!< rmdir without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*fcntl_p)(void* ctx, int fd, int cmd, int arg);
|
||||
int (*fcntl)(int fd, int cmd, int arg);
|
||||
int (*fcntl_p)(void* ctx, int fd, int cmd, int arg); /*!< fcntl with context pointer */
|
||||
int (*fcntl)(int fd, int cmd, int arg); /*!< fcntl without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*ioctl_p)(void* ctx, int fd, int cmd, va_list args);
|
||||
int (*ioctl)(int fd, int cmd, va_list args);
|
||||
int (*ioctl_p)(void* ctx, int fd, int cmd, va_list args); /*!< ioctl with context pointer */
|
||||
int (*ioctl)(int fd, int cmd, va_list args); /*!< ioctl without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*fsync_p)(void* ctx, int fd);
|
||||
int (*fsync)(int fd);
|
||||
int (*fsync_p)(void* ctx, int fd); /*!< fsync with context pointer */
|
||||
int (*fsync)(int fd); /*!< fsync without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*access_p)(void* ctx, const char *path, int amode);
|
||||
int (*access)(const char *path, int amode);
|
||||
int (*access_p)(void* ctx, const char *path, int amode); /*!< access with context pointer */
|
||||
int (*access)(const char *path, int amode); /*!< access without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*truncate_p)(void* ctx, const char *path, off_t length);
|
||||
int (*truncate)(const char *path, off_t length);
|
||||
int (*truncate_p)(void* ctx, const char *path, off_t length); /*!< truncate with context pointer */
|
||||
int (*truncate)(const char *path, off_t length); /*!< truncate without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*utime_p)(void* ctx, const char *path, const struct utimbuf *times);
|
||||
int (*utime)(const char *path, const struct utimbuf *times);
|
||||
int (*utime_p)(void* ctx, const char *path, const struct utimbuf *times); /*!< utime with context pointer */
|
||||
int (*utime)(const char *path, const struct utimbuf *times); /*!< utime without context pointer */
|
||||
};
|
||||
#ifdef CONFIG_VFS_SUPPORT_TERMIOS
|
||||
union {
|
||||
int (*tcsetattr_p)(void *ctx, int fd, int optional_actions, const struct termios *p);
|
||||
int (*tcsetattr)(int fd, int optional_actions, const struct termios *p);
|
||||
int (*tcsetattr_p)(void *ctx, int fd, int optional_actions, const struct termios *p); /*!< tcsetattr with context pointer */
|
||||
int (*tcsetattr)(int fd, int optional_actions, const struct termios *p); /*!< tcsetattr without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*tcgetattr_p)(void *ctx, int fd, struct termios *p);
|
||||
int (*tcgetattr)(int fd, struct termios *p);
|
||||
int (*tcgetattr_p)(void *ctx, int fd, struct termios *p); /*!< tcgetattr with context pointer */
|
||||
int (*tcgetattr)(int fd, struct termios *p); /*!< tcgetattr without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*tcdrain_p)(void *ctx, int fd);
|
||||
int (*tcdrain)(int fd);
|
||||
int (*tcdrain_p)(void *ctx, int fd); /*!< tcdrain with context pointer */
|
||||
int (*tcdrain)(int fd); /*!< tcdrain without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*tcflush_p)(void *ctx, int fd, int select);
|
||||
int (*tcflush)(int fd, int select);
|
||||
int (*tcflush_p)(void *ctx, int fd, int select); /*!< tcflush with context pointer */
|
||||
int (*tcflush)(int fd, int select); /*!< tcflush without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*tcflow_p)(void *ctx, int fd, int action);
|
||||
int (*tcflow)(int fd, int action);
|
||||
int (*tcflow_p)(void *ctx, int fd, int action); /*!< tcflow with context pointer */
|
||||
int (*tcflow)(int fd, int action); /*!< tcflow without context pointer */
|
||||
};
|
||||
union {
|
||||
pid_t (*tcgetsid_p)(void *ctx, int fd);
|
||||
pid_t (*tcgetsid)(int fd);
|
||||
pid_t (*tcgetsid_p)(void *ctx, int fd); /*!< tcgetsid with context pointer */
|
||||
pid_t (*tcgetsid)(int fd); /*!< tcgetsid without context pointer */
|
||||
};
|
||||
union {
|
||||
int (*tcsendbreak_p)(void *ctx, int fd, int duration);
|
||||
int (*tcsendbreak)(int fd, int duration);
|
||||
int (*tcsendbreak_p)(void *ctx, int fd, int duration); /*!< tcsendbreak with context pointer */
|
||||
int (*tcsendbreak)(int fd, int duration); /*!< tcsendbreak without context pointer */
|
||||
};
|
||||
#endif // CONFIG_VFS_SUPPORT_TERMIOS
|
||||
|
||||
|
||||
359
docs/Doxyfile
359
docs/Doxyfile
@@ -24,270 +24,271 @@ INPUT = \
|
||||
##
|
||||
## Wi-Fi - API Reference
|
||||
##
|
||||
../../components/esp_wifi/include/esp_wifi.h \
|
||||
../../components/esp_wifi/include/esp_wifi_types.h \
|
||||
../../components/esp_wifi/include/esp_smartconfig.h \
|
||||
../../components/esp_wifi/include/esp_now.h \
|
||||
../../components/esp_wifi/include/esp_wifi_default.h \
|
||||
$(IDF_PATH)/components/esp_wifi/include/esp_wifi.h \
|
||||
$(IDF_PATH)/components/esp_wifi/include/esp_wifi_types.h \
|
||||
$(IDF_PATH)/components/esp_wifi/include/esp_smartconfig.h \
|
||||
$(IDF_PATH)/components/esp_wifi/include/esp_now.h \
|
||||
$(IDF_PATH)/components/esp_wifi/include/esp_wifi_default.h \
|
||||
## Mesh - API Reference
|
||||
../../components/esp_wifi/include/esp_mesh.h \
|
||||
$(IDF_PATH)/components/esp_wifi/include/esp_mesh.h \
|
||||
## Event loop - API Reference
|
||||
../../components/esp_event/include/esp_event.h \
|
||||
../../components/esp_event/include/esp_event_base.h \
|
||||
../../components/esp_event/include/esp_event_legacy.h \
|
||||
$(IDF_PATH)/components/esp_event/include/esp_event.h \
|
||||
$(IDF_PATH)/components/esp_event/include/esp_event_base.h \
|
||||
$(IDF_PATH)/components/esp_event/include/esp_event_legacy.h \
|
||||
## Bluetooth - API Reference
|
||||
## Controller && VHCI
|
||||
../../components/bt/include/esp_bt.h \
|
||||
$(IDF_PATH)/components/bt/include/esp_bt.h \
|
||||
## Bluetooth COMMON
|
||||
## Issue with __attribute__
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_bt_defs.h \
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_bt_main.h \
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_bt_device.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_main.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_device.h \
|
||||
## Bluetooth LE
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h \
|
||||
## Issue with __attribute__
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h \
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_gatts_api.h \
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_gattc_api.h \
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_blufi_api.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_blufi_api.h \
|
||||
## Bluetooth Classic
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h \
|
||||
## Issue with __attribute__
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h \
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_avrc_api.h \
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_spp_api.h \
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_hf_defs.h \
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h \
|
||||
../../components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_avrc_api.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_spp_api.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_defs.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h \
|
||||
$(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h \
|
||||
## NimBLE related Bluetooth APIs
|
||||
../../components/bt/host/nimble/esp-hci/include/esp_nimble_hci.h \
|
||||
$(IDF_PATH)/components/bt/host/nimble/esp-hci/include/esp_nimble_hci.h \
|
||||
## ESP BLE Mesh APIs
|
||||
../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_common_api.h \
|
||||
../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_local_data_operation_api.h \
|
||||
../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_low_power_api.h \
|
||||
../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_networking_api.h \
|
||||
../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_provisioning_api.h \
|
||||
../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_proxy_api.h \
|
||||
../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_config_model_api.h \
|
||||
../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_generic_model_api.h \
|
||||
../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_health_model_api.h \
|
||||
../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_lighting_model_api.h \
|
||||
../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_sensor_model_api.h \
|
||||
../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_time_scene_model_api.h \
|
||||
../../components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h \
|
||||
$(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_common_api.h \
|
||||
$(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_local_data_operation_api.h \
|
||||
$(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_low_power_api.h \
|
||||
$(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_networking_api.h \
|
||||
$(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_provisioning_api.h \
|
||||
$(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_proxy_api.h \
|
||||
$(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_config_model_api.h \
|
||||
$(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_generic_model_api.h \
|
||||
$(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_health_model_api.h \
|
||||
$(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_lighting_model_api.h \
|
||||
$(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_sensor_model_api.h \
|
||||
$(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_time_scene_model_api.h \
|
||||
$(IDF_PATH)/components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h \
|
||||
##
|
||||
## Ethernet - API Reference
|
||||
##
|
||||
../../components/esp_eth/include/esp_eth.h \
|
||||
../../components/esp_eth/include/esp_eth_com.h \
|
||||
../../components/esp_eth/include/esp_eth_mac.h \
|
||||
../../components/esp_eth/include/esp_eth_phy.h \
|
||||
../../components/esp_eth/include/esp_eth_netif_glue.h \
|
||||
$(IDF_PATH)/components/esp_eth/include/esp_eth.h \
|
||||
$(IDF_PATH)/components/esp_eth/include/esp_eth_com.h \
|
||||
$(IDF_PATH)/components/esp_eth/include/esp_eth_mac.h \
|
||||
$(IDF_PATH)/components/esp_eth/include/esp_eth_phy.h \
|
||||
$(IDF_PATH)/components/esp_eth/include/esp_eth_netif_glue.h \
|
||||
##
|
||||
## Peripherals - API Reference
|
||||
##
|
||||
../../components/driver/include/driver/adc.h \
|
||||
../../components/driver/include/driver/can.h \
|
||||
../../components/soc/include/hal/can_types.h \
|
||||
../../components/driver/include/driver/dac.h \
|
||||
../../components/driver/include/driver/gpio.h \
|
||||
../../components/driver/include/driver/rtc_io.h \
|
||||
../../components/driver/include/driver/i2c.h \
|
||||
../../components/driver/include/driver/i2s.h \
|
||||
../../components/driver/include/driver/ledc.h \
|
||||
../../components/driver/include/driver/mcpwm.h \
|
||||
../../components/soc/include/hal/mcpwm_types.h \
|
||||
../../components/driver/include/driver/pcnt.h \
|
||||
../../components/driver/include/driver/rmt.h \
|
||||
../../components/driver/include/driver/sigmadelta.h \
|
||||
../../components/driver/include/driver/spi_common.h \
|
||||
../../components/driver/include/driver/spi_master.h \
|
||||
../../components/driver/include/driver/spi_slave.h \
|
||||
../../components/driver/esp32s2/include/temp_sensor.h \
|
||||
../../components/driver/include/driver/timer.h \
|
||||
../../components/driver/include/driver/touch_pad.h \
|
||||
../../components/driver/include/driver/uart.h \
|
||||
../../components/esp_adc_cal/include/esp_adc_cal.h \
|
||||
../../components/soc/include/hal/rmt_types.h \
|
||||
../../components/soc/include/hal/spi_types.h \
|
||||
../../components/soc/include/hal/pcnt_types.h \
|
||||
../../components/soc/include/hal/i2s_types.h \
|
||||
../../components/soc/include/hal/rtc_io_types.h \
|
||||
../../components/soc/include/hal/sigmadelta_types.h \
|
||||
../../components/soc/include/hal/timer_types.h \
|
||||
../../components/soc/include/hal/ledc_types.h \
|
||||
../../components/soc/include/hal/i2c_types.h \
|
||||
../../components/soc/include/hal/dac_types.h \
|
||||
../../components/soc/include/hal/adc_types.h \
|
||||
../../components/soc/include/hal/gpio_types.h \
|
||||
../../components/soc/include/hal/uart_types.h \
|
||||
../../components/soc/include/hal/touch_sensor_types.h \
|
||||
../../components/soc/esp32/include/soc/adc_channel.h \
|
||||
../../components/soc/esp32/include/soc/dac_channel.h \
|
||||
../../components/soc/esp32/include/soc/touch_sensor_channel.h \
|
||||
../../components/soc/esp32/include/soc/uart_channel.h \
|
||||
../../components/soc/esp32/include/soc/rtc_io_channel.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/adc.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/can.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/can_types.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/dac.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/gpio.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/rtc_io.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/i2c.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/i2s.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/ledc.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/mcpwm.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/mcpwm_types.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/pcnt.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/rmt.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/sigmadelta.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/spi_common.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/spi_master.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/spi_slave.h \
|
||||
$(IDF_PATH)/components/driver/$(IDF_TARGET)/include/touch_sensor.h \
|
||||
$(IDF_PATH)/components/driver/esp32s2/include/temp_sensor.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/timer.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/touch_sensor_common.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/uart.h \
|
||||
$(IDF_PATH)/components/esp_adc_cal/include/esp_adc_cal.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/rmt_types.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/spi_types.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/pcnt_types.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/i2s_types.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/rtc_io_types.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/sigmadelta_types.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/timer_types.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/ledc_types.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/i2c_types.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/dac_types.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/adc_types.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/gpio_types.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/uart_types.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/touch_sensor_types.h \
|
||||
$(IDF_PATH)/components/soc/esp32/include/soc/adc_channel.h \
|
||||
$(IDF_PATH)/components/soc/esp32/include/soc/dac_channel.h \
|
||||
$(IDF_PATH)/components/soc/esp32/include/soc/touch_sensor_channel.h \
|
||||
$(IDF_PATH)/components/soc/esp32/include/soc/uart_channel.h \
|
||||
$(IDF_PATH)/components/soc/esp32/include/soc/rtc_io_channel.h \
|
||||
## esp_netif - API Reference
|
||||
../../components/esp_netif/include/esp_netif.h \
|
||||
../../components/esp_netif/include/esp_netif_net_stack.h \
|
||||
$(IDF_PATH)/components/esp_netif/include/esp_netif.h \
|
||||
$(IDF_PATH)/components/esp_netif/include/esp_netif_net_stack.h \
|
||||
##
|
||||
## Protocols - API Reference
|
||||
##
|
||||
## ESP-TLS
|
||||
../../components/esp-tls/esp_tls.h \
|
||||
$(IDF_PATH)/components/esp-tls/esp_tls.h \
|
||||
## MQTT
|
||||
../../components/mqtt/esp-mqtt/include/mqtt_client.h \
|
||||
$(IDF_PATH)/components/mqtt/esp-mqtt/include/mqtt_client.h \
|
||||
## ICMP-ECHO
|
||||
../../components/lwip/include/apps/ping/ping_sock.h \
|
||||
$(IDF_PATH)/components/lwip/include/apps/ping/ping_sock.h \
|
||||
## SNTP
|
||||
../../components/lwip/include/apps/sntp/sntp.h \
|
||||
$(IDF_PATH)/components/lwip/include/apps/sntp/sntp.h \
|
||||
## mDNS
|
||||
../../components/mdns/include/mdns.h \
|
||||
../../components/esp_http_client/include/esp_http_client.h \
|
||||
../../components/esp_websocket_client/include/esp_websocket_client.h \
|
||||
$(IDF_PATH)/components/mdns/include/mdns.h \
|
||||
$(IDF_PATH)/components/esp_http_client/include/esp_http_client.h \
|
||||
$(IDF_PATH)/components/esp_websocket_client/include/esp_websocket_client.h \
|
||||
## HTTP / HTTPS Server
|
||||
../../components/esp_http_server/include/esp_http_server.h \
|
||||
../../components/esp_https_server/include/esp_https_server.h \
|
||||
$(IDF_PATH)/components/esp_http_server/include/esp_http_server.h \
|
||||
$(IDF_PATH)/components/esp_https_server/include/esp_https_server.h \
|
||||
## ESP Local Ctrl
|
||||
../../components/esp_local_ctrl/include/esp_local_ctrl.h \
|
||||
$(IDF_PATH)/components/esp_local_ctrl/include/esp_local_ctrl.h \
|
||||
## ESP Serial Slave Link
|
||||
../../components/esp_serial_slave_link/include/esp_serial_slave_link/essl.h \
|
||||
../../components/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h \
|
||||
$(IDF_PATH)/components/esp_serial_slave_link/include/esp_serial_slave_link/essl.h \
|
||||
$(IDF_PATH)/components/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h \
|
||||
##
|
||||
## Provisioning - API Reference
|
||||
##
|
||||
## Protocol Communication
|
||||
../../components/protocomm/include/common/protocomm.h \
|
||||
../../components/protocomm/include/security/protocomm_security.h \
|
||||
../../components/protocomm/include/security/protocomm_security0.h \
|
||||
../../components/protocomm/include/security/protocomm_security1.h \
|
||||
../../components/protocomm/include/transports/protocomm_ble.h \
|
||||
../../components/protocomm/include/transports/protocomm_console.h \
|
||||
../../components/protocomm/include/transports/protocomm_httpd.h \
|
||||
$(IDF_PATH)/components/protocomm/include/common/protocomm.h \
|
||||
$(IDF_PATH)/components/protocomm/include/security/protocomm_security.h \
|
||||
$(IDF_PATH)/components/protocomm/include/security/protocomm_security0.h \
|
||||
$(IDF_PATH)/components/protocomm/include/security/protocomm_security1.h \
|
||||
$(IDF_PATH)/components/protocomm/include/transports/protocomm_ble.h \
|
||||
$(IDF_PATH)/components/protocomm/include/transports/protocomm_console.h \
|
||||
$(IDF_PATH)/components/protocomm/include/transports/protocomm_httpd.h \
|
||||
## WiFi Provisioning
|
||||
../../components/wifi_provisioning/include/wifi_provisioning/manager.h \
|
||||
../../components/wifi_provisioning/include/wifi_provisioning/scheme_ble.h \
|
||||
../../components/wifi_provisioning/include/wifi_provisioning/scheme_softap.h \
|
||||
../../components/wifi_provisioning/include/wifi_provisioning/scheme_console.h \
|
||||
../../components/wifi_provisioning/include/wifi_provisioning/wifi_config.h \
|
||||
../../components/wifi_provisioning/include/wifi_provisioning/wifi_scan.h \
|
||||
$(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/manager.h \
|
||||
$(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_ble.h \
|
||||
$(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_softap.h \
|
||||
$(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_console.h \
|
||||
$(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/wifi_config.h \
|
||||
$(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/wifi_scan.h \
|
||||
##
|
||||
## Storage - API Reference
|
||||
##
|
||||
## SPI Flash and Partition APIs
|
||||
../../components/spi_flash/include/esp_flash_spi_init.h \
|
||||
../../components/spi_flash/include/esp_flash.h \
|
||||
../../components/spi_flash/include/esp_partition.h \
|
||||
../../components/bootloader_support/include/esp_flash_encrypt.h \
|
||||
../../components/soc/include/hal/spi_flash_types.h \
|
||||
$(IDF_PATH)/components/spi_flash/include/esp_flash_spi_init.h \
|
||||
$(IDF_PATH)/components/spi_flash/include/esp_flash.h \
|
||||
$(IDF_PATH)/components/spi_flash/include/esp_partition.h \
|
||||
$(IDF_PATH)/components/bootloader_support/include/esp_flash_encrypt.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/spi_flash_types.h \
|
||||
## SPIFFS
|
||||
../../components/spiffs/include/esp_spiffs.h \
|
||||
$(IDF_PATH)/components/spiffs/include/esp_spiffs.h \
|
||||
## SD/MMC Card Host
|
||||
../../components/sdmmc/include/sdmmc_cmd.h \
|
||||
../../components/driver/include/driver/sdmmc_host.h \
|
||||
../../components/driver/include/driver/sdmmc_types.h \
|
||||
../../components/driver/include/driver/sdspi_host.h \
|
||||
$(IDF_PATH)/components/sdmmc/include/sdmmc_cmd.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/sdmmc_host.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/sdmmc_types.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/sdspi_host.h \
|
||||
## SDIO slave
|
||||
../../components/driver/include/driver/sdio_slave.h \
|
||||
../../components/soc/include/hal/sdio_slave_types.h \
|
||||
$(IDF_PATH)/components/driver/include/driver/sdio_slave.h \
|
||||
$(IDF_PATH)/components/soc/include/hal/sdio_slave_types.h \
|
||||
## Non-Volatile Storage
|
||||
../../components/nvs_flash/include/nvs.h \
|
||||
../../components/nvs_flash/include/nvs_flash.h \
|
||||
$(IDF_PATH)/components/nvs_flash/include/nvs.h \
|
||||
$(IDF_PATH)/components/nvs_flash/include/nvs_flash.h \
|
||||
## Virtual Filesystem
|
||||
../../components/vfs/include/esp_vfs.h \
|
||||
../../components/vfs/include/esp_vfs_dev.h \
|
||||
../../components/vfs/include/esp_vfs_semihost.h \
|
||||
$(IDF_PATH)/components/vfs/include/esp_vfs.h \
|
||||
$(IDF_PATH)/components/vfs/include/esp_vfs_dev.h \
|
||||
$(IDF_PATH)/components/vfs/include/esp_vfs_semihost.h \
|
||||
## FAT Filesystem
|
||||
## NOTE: for two lines below header_file.inc is not used
|
||||
../../components/fatfs/vfs/esp_vfs_fat.h \
|
||||
../../components/fatfs/diskio/diskio_impl.h \
|
||||
../../components/fatfs/diskio/diskio_sdmmc.h \
|
||||
../../components/fatfs/diskio/diskio_wl.h \
|
||||
../../components/fatfs/diskio/diskio_rawflash.h \
|
||||
$(IDF_PATH)/components/fatfs/vfs/esp_vfs_fat.h \
|
||||
$(IDF_PATH)/components/fatfs/diskio/diskio_impl.h \
|
||||
$(IDF_PATH)/components/fatfs/diskio/diskio_sdmmc.h \
|
||||
$(IDF_PATH)/components/fatfs/diskio/diskio_wl.h \
|
||||
$(IDF_PATH)/components/fatfs/diskio/diskio_rawflash.h \
|
||||
## Wear Levelling
|
||||
../../components/wear_levelling/include/wear_levelling.h \
|
||||
$(IDF_PATH)/components/wear_levelling/include/wear_levelling.h \
|
||||
##
|
||||
## System - API Reference
|
||||
##
|
||||
## Memory Allocation #
|
||||
../../components/heap/include/esp_heap_caps.h \
|
||||
../../components/heap/include/esp_heap_trace.h \
|
||||
../../components/heap/include/esp_heap_caps_init.h \
|
||||
../../components/heap/include/multi_heap.h \
|
||||
$(IDF_PATH)/components/heap/include/esp_heap_caps.h \
|
||||
$(IDF_PATH)/components/heap/include/esp_heap_trace.h \
|
||||
$(IDF_PATH)/components/heap/include/esp_heap_caps_init.h \
|
||||
$(IDF_PATH)/components/heap/include/multi_heap.h \
|
||||
## Himem
|
||||
../../components/esp32/include/esp32/himem.h \
|
||||
$(IDF_PATH)/components/esp32/include/esp32/himem.h \
|
||||
## Interrupt Allocation
|
||||
../../components/esp32/include/esp_intr_alloc.h \
|
||||
$(IDF_PATH)/components/$(IDF_TARGET)/include/esp_intr_alloc.h \
|
||||
## Watchdogs
|
||||
## NOTE: for two lines below header_file.inc is not used
|
||||
../../components/esp_common/include/esp_int_wdt.h \
|
||||
../../components/esp_common/include/esp_task_wdt.h \
|
||||
$(IDF_PATH)/components/esp_common/include/esp_int_wdt.h \
|
||||
$(IDF_PATH)/components/esp_common/include/esp_task_wdt.h \
|
||||
## Hooks
|
||||
../../components/esp_common/include/esp_freertos_hooks.h \
|
||||
$(IDF_PATH)/components/esp_common/include/esp_freertos_hooks.h \
|
||||
## Inter-Processor Call
|
||||
../../components/esp_common/include/esp_ipc.h \
|
||||
$(IDF_PATH)/components/esp_common/include/esp_ipc.h \
|
||||
## Call Function with External stack
|
||||
../../components/esp_common/include/esp_expression_with_stack.h \
|
||||
$(IDF_PATH)/components/esp_common/include/esp_expression_with_stack.h \
|
||||
## Over The Air Updates (OTA)
|
||||
../../components/app_update/include/esp_ota_ops.h \
|
||||
$(IDF_PATH)/components/app_update/include/esp_ota_ops.h \
|
||||
## ESP HTTPS OTA
|
||||
../../components/esp_https_ota/include/esp_https_ota.h \
|
||||
$(IDF_PATH)/components/esp_https_ota/include/esp_https_ota.h \
|
||||
## Sleep
|
||||
../../components/esp32/include/esp_sleep.h \
|
||||
$(IDF_PATH)/components/$(IDF_TARGET)/include/esp_sleep.h \
|
||||
## Logging
|
||||
../../components/log/include/esp_log.h \
|
||||
$(IDF_PATH)/components/log/include/esp_log.h \
|
||||
## Base MAC address
|
||||
## NOTE: for line below header_file.inc is not used
|
||||
../../components/esp_common/include/esp_system.h \
|
||||
$(IDF_PATH)/components/esp_common/include/esp_system.h \
|
||||
## IDF version
|
||||
../../components/esp_common/include/esp_idf_version.h \
|
||||
$(IDF_PATH)/components/esp_common/include/esp_idf_version.h \
|
||||
##
|
||||
## ULP Coprocessor - API Guides
|
||||
##
|
||||
## NOTE: for line below header_file.inc is not used
|
||||
../../components/ulp/include/esp32/ulp.h \
|
||||
../../components/ulp/include/ulp_common.h \
|
||||
$(IDF_PATH)/components/ulp/include/$(IDF_TARGET)/ulp.h \
|
||||
$(IDF_PATH)/components/ulp/include/ulp_common.h \
|
||||
##
|
||||
## Application Level Tracing - API Reference
|
||||
##
|
||||
../../components/app_trace/include/esp_app_trace.h \
|
||||
../../components/app_trace/include/esp_sysview_trace.h \
|
||||
$(IDF_PATH)/components/app_trace/include/esp_app_trace.h \
|
||||
$(IDF_PATH)/components/app_trace/include/esp_sysview_trace.h \
|
||||
### Power management
|
||||
../../components/esp_common/include/esp_pm.h \
|
||||
../../components/esp32/include/esp32/pm.h \
|
||||
$(IDF_PATH)/components/esp_common/include/esp_pm.h \
|
||||
$(IDF_PATH)/components/$(IDF_TARGET)/include/$(IDF_TARGET)/pm.h \
|
||||
### esp_timer, High Resolution Timer
|
||||
../../components/esp_timer/include/esp_timer.h \
|
||||
$(IDF_PATH)/components/esp_timer/include/esp_timer.h \
|
||||
### esp_event, Event Loop Library
|
||||
../../components/esp_event/include/esp_event.h \
|
||||
../../components/esp_event/include/esp_event_base.h \
|
||||
$(IDF_PATH)/components/esp_event/include/esp_event.h \
|
||||
$(IDF_PATH)/components/esp_event/include/esp_event_base.h \
|
||||
### eFuse Manager
|
||||
../../components/efuse/include/esp_efuse.h \
|
||||
$(IDF_PATH)/components/efuse/include/esp_efuse.h \
|
||||
### App Image Format
|
||||
../../components/bootloader_support/include/esp_app_format.h \
|
||||
$(IDF_PATH)/components/bootloader_support/include/esp_app_format.h \
|
||||
### ESP Pthread parameters
|
||||
../../components/pthread/include/esp_pthread.h \
|
||||
$(IDF_PATH)/components/pthread/include/esp_pthread.h \
|
||||
###
|
||||
### FreeRTOS
|
||||
###
|
||||
../../components/freertos/include/freertos/task.h \
|
||||
../../components/freertos/include/freertos/queue.h \
|
||||
../../components/freertos/include/freertos/semphr.h \
|
||||
../../components/freertos/include/freertos/timers.h \
|
||||
../../components/freertos/include/freertos/event_groups.h \
|
||||
$(IDF_PATH)/components/freertos/include/freertos/task.h \
|
||||
$(IDF_PATH)/components/freertos/include/freertos/queue.h \
|
||||
$(IDF_PATH)/components/freertos/include/freertos/semphr.h \
|
||||
$(IDF_PATH)/components/freertos/include/freertos/timers.h \
|
||||
$(IDF_PATH)/components/freertos/include/freertos/event_groups.h \
|
||||
### Ringbuffer
|
||||
../../components/esp_ringbuf/include/freertos/ringbuf.h \
|
||||
$(IDF_PATH)/components/esp_ringbuf/include/freertos/ringbuf.h \
|
||||
### Helper functions for error codes
|
||||
../../components/esp_common/include/esp_err.h \
|
||||
$(IDF_PATH)/components/esp_common/include/esp_err.h \
|
||||
### System APIs
|
||||
../../components/esp_common/include/esp_system.h \
|
||||
$(IDF_PATH)/components/esp_common/include/esp_system.h \
|
||||
### Modbus controller component header file
|
||||
../../components/freemodbus/common/include/esp_modbus_common.h \
|
||||
../../components/freemodbus/common/include/esp_modbus_slave.h \
|
||||
../../components/freemodbus/common/include/esp_modbus_master.h \
|
||||
$(IDF_PATH)/components/freemodbus/common/include/esp_modbus_common.h \
|
||||
$(IDF_PATH)/components/freemodbus/common/include/esp_modbus_slave.h \
|
||||
$(IDF_PATH)/components/freemodbus/common/include/esp_modbus_master.h \
|
||||
### Performance Monitor component header file
|
||||
../../components/perfmon/include/xtensa_perfmon_access.h \
|
||||
../../components/perfmon/include/xtensa_perfmon_apis.h \
|
||||
../../components/perfmon/include/xtensa_perfmon_masks.h
|
||||
$(IDF_PATH)/components/perfmon/include/xtensa_perfmon_access.h \
|
||||
$(IDF_PATH)/components/perfmon/include/xtensa_perfmon_apis.h \
|
||||
$(IDF_PATH)/components/perfmon/include/xtensa_perfmon_masks.h
|
||||
|
||||
|
||||
## Get warnings for functions that have no documentation for their parameters or return value
|
||||
@@ -300,7 +301,9 @@ ENABLE_PREPROCESSING = YES
|
||||
MACRO_EXPANSION = YES
|
||||
EXPAND_ONLY_PREDEF = YES
|
||||
PREDEFINED = \
|
||||
$(ENV_DOXYGEN_DEFINES) \
|
||||
__attribute__(x)= \
|
||||
_Static_assert()= \
|
||||
IDF_DEPRECATED(X)= \
|
||||
IRAM_ATTR= \
|
||||
configSUPPORT_DYNAMIC_ALLOCATION=1 \
|
||||
|
||||
@@ -16,16 +16,12 @@ The above URLs are all for the master branch latest version. Click the drop-down
|
||||
|
||||
# Building Documentation
|
||||
|
||||
* Install `make` and `doxygen` for your platform (`make` may already be installed as an ESP-IDF prerequisite).
|
||||
* Change to either the docs/en or docs/zh_CN subdirectory and run `make html`
|
||||
* `make` will probably prompt you to run a python pip install step to get some other Python-related prerequisites. Run the command as shown, then re-run `make html` to build the docs.
|
||||
* Documentation build requres Python 3 and will not work with Python 2
|
||||
* Install dependencies for ESP-IDF as per the Getting Started guide
|
||||
* Install documentation Python depdendencies, ie `pip install -r $IDF_PATH/docs/requirements.txt`
|
||||
* Run `./build_docs.py build` to build docs for all supported Language & Target combinations, or `./build_docs.py -t esp32 -l en build` to build docs for a single supported language & target combination only.
|
||||
|
||||
## For MSYS2 MINGW32 on Windows
|
||||
See [Documenting Code](https://docs.espressif.com/projects/esp-idf/en/latest/contribute/documenting-code.rst) for more information.
|
||||
|
||||
If using Windows and the MSYS2 MINGW32 terminal, run this command before running "make html" the first time:
|
||||
Available languages are `en` and `zh_CN`, targets are any target supported by ESP-IDF - for example `esp32` or `esp32s2`.
|
||||
|
||||
```
|
||||
pacman -S doxygen mingw-w64-i686-python2-pillow
|
||||
```
|
||||
|
||||
Note: Currently it is not possible to build docs on Windows without using a Unix-on-Windows layer such as MSYS2 MINGW32.
|
||||
|
||||
368
docs/build_docs.py
Executable file
368
docs/build_docs.py
Executable file
@@ -0,0 +1,368 @@
|
||||
#!/usr/bin/env python3
|
||||
# coding=utf-8
|
||||
#
|
||||
# Top-level docs builder
|
||||
#
|
||||
# This is just a front-end to sphinx-build that can call it multiple times for different language/target combinations
|
||||
#
|
||||
# Will build out to _build/LANG/TARGET by default
|
||||
#
|
||||
# Specific custom docs functionality should be added in conf_common.py or in a Sphinx extension, not here.
|
||||
#
|
||||
from __future__ import print_function
|
||||
import argparse
|
||||
import locale
|
||||
import math
|
||||
import multiprocessing
|
||||
import os
|
||||
import os.path
|
||||
import subprocess
|
||||
import sys
|
||||
import re
|
||||
from collections import namedtuple
|
||||
|
||||
LANGUAGES = ["en", "zh_CN"]
|
||||
TARGETS = ["esp32", "esp32s2"]
|
||||
|
||||
SPHINX_WARN_LOG = "sphinx-warning-log.txt"
|
||||
SPHINX_SANITIZED_LOG = "sphinx-warning-log-sanitized.txt"
|
||||
SPHINX_KNOWN_WARNINGS = os.path.join(os.environ["IDF_PATH"], "docs", "sphinx-known-warnings.txt")
|
||||
|
||||
DXG_WARN_LOG = "doxygen-warning-log.txt"
|
||||
DXG_SANITIZED_LOG = "doxygen-warning-log-sanitized.txt"
|
||||
DXG_KNOWN_WARNINGS = os.path.join(os.environ["IDF_PATH"], "docs", "doxygen-known-warnings.txt")
|
||||
|
||||
LogMessage = namedtuple("LogMessage", "original_text sanitized_text")
|
||||
|
||||
languages = LANGUAGES
|
||||
targets = TARGETS
|
||||
|
||||
|
||||
def main():
|
||||
# check Python dependencies for docs
|
||||
try:
|
||||
subprocess.check_call([sys.executable,
|
||||
os.path.join(os.environ["IDF_PATH"],
|
||||
"tools",
|
||||
"check_python_dependencies.py"),
|
||||
"-r",
|
||||
"{}/docs/requirements.txt".format(os.environ["IDF_PATH"])
|
||||
])
|
||||
except subprocess.CalledProcessError:
|
||||
raise SystemExit(2) # stdout will already have these errors
|
||||
|
||||
# This is not the only way to make sure that all files opened by Python are treated as UTF-8, but the other way is passing encoding='utf-8' to all open()
|
||||
# functions and this way makes Python 2 compatibility really tough if there is any code that assumes text files contain strings (kconfiglib assumes this).
|
||||
# The reason for that is that you need to import io.open() to support the encoding argument on Python 2, and this function always uses Py2's unicode
|
||||
# type not the str type.
|
||||
if 'UTF-8' not in locale.getlocale():
|
||||
raise RuntimeError("build_docs.py requires the default locale's encoding to be UTF-8. " +
|
||||
"Setting environment variable LC_ALL=C.UTF-8 when running build_docs.py may be enough to fix this.")
|
||||
|
||||
parser = argparse.ArgumentParser(description='build_docs.py: Build IDF docs', prog='build_docs.py')
|
||||
|
||||
parser.add_argument("--language", "-l", choices=LANGUAGES, required=False)
|
||||
parser.add_argument("--target", "-t", choices=TARGETS, required=False)
|
||||
parser.add_argument("--build-dir", "-b", type=str, default="_build")
|
||||
parser.add_argument("--sphinx-parallel-builds", "-p", choices=["auto"] + [str(x) for x in range(8)],
|
||||
help="Parallel Sphinx builds - number of independent Sphinx builds to run", default="auto")
|
||||
parser.add_argument("--sphinx-parallel-jobs", "-j", choices=["auto"] + [str(x) for x in range(8)],
|
||||
help="Sphinx parallel jobs argument - number of threads for each Sphinx build to use", default="1")
|
||||
|
||||
action_parsers = parser.add_subparsers(dest='action')
|
||||
|
||||
build_parser = action_parsers.add_parser('build', help='Build documentation')
|
||||
build_parser.add_argument("--check-warnings-only", "-w", action='store_true')
|
||||
|
||||
action_parsers.add_parser('linkcheck', help='Check links (a current IDF revision should be uploaded to GitHub)')
|
||||
|
||||
action_parsers.add_parser('gh-linkcheck', help='Checking for hardcoded GitHub links')
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
global languages
|
||||
if args.language is None:
|
||||
print("Building all languages")
|
||||
languages = LANGUAGES
|
||||
else:
|
||||
languages = [args.language]
|
||||
|
||||
global targets
|
||||
if args.target is None:
|
||||
print("Building all targets")
|
||||
targets = TARGETS
|
||||
else:
|
||||
targets = [args.target]
|
||||
|
||||
if args.action == "build" or args.action is None:
|
||||
sys.exit(action_build(args))
|
||||
|
||||
if args.action == "linkcheck":
|
||||
sys.exit(action_linkcheck(args))
|
||||
|
||||
if args.action == "gh-linkcheck":
|
||||
sys.exit(action_gh_linkcheck(args))
|
||||
|
||||
|
||||
def parallel_call(args, callback):
|
||||
num_sphinx_builds = len(languages) * len(targets)
|
||||
num_cpus = multiprocessing.cpu_count()
|
||||
|
||||
if args.sphinx_parallel_builds == "auto":
|
||||
# at most one sphinx build per CPU, up to the number of CPUs
|
||||
args.sphinx_parallel_builds = min(num_sphinx_builds, num_cpus)
|
||||
else:
|
||||
args.sphinx_parallel_builds = int(args.sphinx_parallel_builds)
|
||||
|
||||
# Force -j1 because sphinx works incorrectly
|
||||
args.sphinx_parallel_jobs = 1
|
||||
if args.sphinx_parallel_jobs == "auto":
|
||||
# N CPUs per build job, rounded up - (maybe smarter to round down to avoid contention, idk)
|
||||
args.sphinx_parallel_jobs = int(math.ceil(num_cpus / args.sphinx_parallel_builds))
|
||||
else:
|
||||
args.sphinx_parallel_jobs = int(args.sphinx_parallel_jobs)
|
||||
|
||||
print("Will use %d parallel builds and %d jobs per build" % (args.sphinx_parallel_builds, args.sphinx_parallel_jobs))
|
||||
pool = multiprocessing.Pool(args.sphinx_parallel_builds)
|
||||
|
||||
if args.sphinx_parallel_jobs > 1:
|
||||
print("WARNING: Sphinx parallel jobs currently produce incorrect docs output with Sphinx 1.8.5")
|
||||
|
||||
# make a list of all combinations of build_docs() args as tuples
|
||||
#
|
||||
# there's probably a fancy way to do this with itertools but this way is actually readable
|
||||
entries = []
|
||||
for target in targets:
|
||||
for language in languages:
|
||||
build_dir = os.path.realpath(os.path.join(args.build_dir, language, target))
|
||||
entries.append((language, target, build_dir, args.sphinx_parallel_jobs))
|
||||
|
||||
print(entries)
|
||||
errcodes = pool.map(callback, entries)
|
||||
print(errcodes)
|
||||
|
||||
is_error = False
|
||||
for ret in errcodes:
|
||||
if ret != 0:
|
||||
print("\nThe following language/target combinations failed to build:")
|
||||
is_error = True
|
||||
break
|
||||
if is_error:
|
||||
for ret, entry in zip(errcodes, entries):
|
||||
if ret != 0:
|
||||
print("language: %s, target: %s, errcode: %d" % (entry[0], entry[1], ret))
|
||||
# Don't re-throw real error code from each parallel process
|
||||
return 1
|
||||
else:
|
||||
return 0
|
||||
|
||||
|
||||
def sphinx_call(language, target, build_dir, sphinx_parallel_jobs, buildername):
|
||||
# Note: because this runs in a multiprocessing Process, everything which happens here should be isolated to a single process
|
||||
# (ie it doesn't matter if Sphinx is using global variables, as they're it's own copy of the global variables)
|
||||
|
||||
# wrap stdout & stderr in a way that lets us see which build_docs instance they come from
|
||||
#
|
||||
# this doesn't apply to subprocesses, they write to OS stdout & stderr so no prefix appears
|
||||
prefix = "%s/%s: " % (language, target)
|
||||
|
||||
print("Building in build_dir: %s" % (build_dir))
|
||||
try:
|
||||
os.makedirs(build_dir)
|
||||
except OSError:
|
||||
pass
|
||||
|
||||
environ = {}
|
||||
environ.update(os.environ)
|
||||
environ['BUILDDIR'] = build_dir
|
||||
|
||||
args = [sys.executable, "-u", "-m", "sphinx.cmd.build",
|
||||
"-j", str(sphinx_parallel_jobs),
|
||||
"-b", buildername,
|
||||
"-d", os.path.join(build_dir, "doctrees"),
|
||||
"-w", SPHINX_WARN_LOG,
|
||||
"-t", target,
|
||||
"-D", "idf_target={}".format(target),
|
||||
os.path.join(os.path.abspath(os.path.dirname(__file__)), language), # srcdir for this language
|
||||
os.path.join(build_dir, buildername) # build directory
|
||||
]
|
||||
|
||||
saved_cwd = os.getcwd()
|
||||
os.chdir(build_dir) # also run sphinx in the build directory
|
||||
print("Running '%s'" % (" ".join(args)))
|
||||
|
||||
ret = 1
|
||||
try:
|
||||
# Note: we can't call sphinx.cmd.build.main() here as multiprocessing doesn't est >1 layer deep
|
||||
# and sphinx.cmd.build() also does a lot of work in the calling thread, especially for j ==1,
|
||||
# so using a Pyhthon thread for this part is a poor option (GIL)
|
||||
p = subprocess.Popen(args, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
|
||||
for c in iter(lambda: p.stdout.readline(), b''):
|
||||
sys.stdout.write(prefix)
|
||||
sys.stdout.write(c.decode('utf-8'))
|
||||
ret = p.wait()
|
||||
assert (ret is not None)
|
||||
sys.stdout.flush()
|
||||
except KeyboardInterrupt: # this seems to be the only way to get Ctrl-C to kill everything?
|
||||
p.kill()
|
||||
os.chdir(saved_cwd)
|
||||
return 130 # FIXME It doesn't return this errorcode, why? Just prints stacktrace
|
||||
os.chdir(saved_cwd)
|
||||
return ret
|
||||
|
||||
|
||||
def action_build(args):
|
||||
if not args.check_warnings_only:
|
||||
ret = parallel_call(args, call_build_docs)
|
||||
if ret != 0:
|
||||
return ret
|
||||
|
||||
# check Doxygen warnings:
|
||||
ret = 0
|
||||
for target in targets:
|
||||
for language in languages:
|
||||
build_dir = os.path.realpath(os.path.join(args.build_dir, language, target))
|
||||
ret += check_docs(language, target,
|
||||
log_file=os.path.join(build_dir, DXG_WARN_LOG),
|
||||
known_warnings_file=DXG_KNOWN_WARNINGS,
|
||||
out_sanitized_log_file=os.path.join(build_dir, DXG_SANITIZED_LOG))
|
||||
|
||||
# check Sphinx warnings:
|
||||
for target in targets:
|
||||
for language in languages:
|
||||
build_dir = os.path.realpath(os.path.join(args.build_dir, language, target))
|
||||
ret += check_docs(language, target,
|
||||
log_file=os.path.join(build_dir, SPHINX_WARN_LOG),
|
||||
known_warnings_file=SPHINX_KNOWN_WARNINGS,
|
||||
out_sanitized_log_file=os.path.join(build_dir, SPHINX_SANITIZED_LOG))
|
||||
if ret != 0:
|
||||
return ret
|
||||
|
||||
|
||||
def call_build_docs(entry):
|
||||
return sphinx_call(*entry, buildername="html")
|
||||
|
||||
|
||||
SANITIZE_FILENAME_REGEX = re.compile("[^:]*/([^/:]*)(:.*)")
|
||||
SANITIZE_LINENUM_REGEX = re.compile("([^:]*)(:[0-9]+:)(.*)")
|
||||
|
||||
|
||||
def sanitize_line(line):
|
||||
"""
|
||||
Clear a log message from insignificant parts
|
||||
|
||||
filter:
|
||||
- only filename, no path at the beginning
|
||||
- no line numbers after the filename
|
||||
"""
|
||||
|
||||
line = re.sub(SANITIZE_FILENAME_REGEX, r'\1\2', line)
|
||||
line = re.sub(SANITIZE_LINENUM_REGEX, r'\1:line:\3', line)
|
||||
return line
|
||||
|
||||
|
||||
def check_docs(language, target, log_file, known_warnings_file, out_sanitized_log_file):
|
||||
"""
|
||||
Check for Documentation warnings in `log_file`: should only contain (fuzzy) matches to `known_warnings_file`
|
||||
|
||||
It prints all unknown messages with `target`/`language` prefix
|
||||
It leaves `out_sanitized_log_file` file for observe and debug
|
||||
"""
|
||||
|
||||
# Sanitize all messages
|
||||
all_messages = list()
|
||||
with open(log_file) as f, open(out_sanitized_log_file, 'w') as o:
|
||||
for line in f:
|
||||
sanitized_line = sanitize_line(line)
|
||||
all_messages.append(LogMessage(line, sanitized_line))
|
||||
o.write(sanitized_line)
|
||||
|
||||
known_messages = list()
|
||||
with open(known_warnings_file) as k:
|
||||
for known_line in k:
|
||||
known_messages.append(known_line)
|
||||
|
||||
if "doxygen" in known_warnings_file:
|
||||
# Clean a known Doxygen limitation: it's expected to always document anonymous
|
||||
# structs/unions but we don't do this in our docs, so filter these all out with a regex
|
||||
# (this won't match any named field, only anonymous members -
|
||||
# ie the last part of the field is is just <something>::@NUM not <something>::name)
|
||||
RE_ANONYMOUS_FIELD = re.compile(r".+:line: warning: parameters of member [^:\s]+(::[^:\s]+)*(::@\d+)+ are not \(all\) documented")
|
||||
all_messages = [msg for msg in all_messages if not re.match(RE_ANONYMOUS_FIELD, msg.sanitized_text)]
|
||||
|
||||
# Collect all new messages that are not match with the known messages.
|
||||
# The order is an important.
|
||||
new_messages = list()
|
||||
known_idx = 0
|
||||
for msg in all_messages:
|
||||
try:
|
||||
known_idx = known_messages.index(msg.sanitized_text, known_idx)
|
||||
except ValueError:
|
||||
new_messages.append(msg)
|
||||
|
||||
if new_messages:
|
||||
print("\n%s/%s: Build failed due to new/different warnings (%s):\n" % (language, target, log_file))
|
||||
for msg in new_messages:
|
||||
print("%s/%s: %s" % (language, target, msg.original_text), end='')
|
||||
print("\n%s/%s: (Check files %s and %s for full details.)" % (language, target, known_warnings_file, log_file))
|
||||
return 1
|
||||
|
||||
return 0
|
||||
|
||||
|
||||
def action_linkcheck(args):
|
||||
return parallel_call(args, call_linkcheck)
|
||||
|
||||
|
||||
def call_linkcheck(entry):
|
||||
return sphinx_call(*entry, buildername="linkcheck")
|
||||
|
||||
|
||||
# https://github.com/espressif/esp-idf/tree/
|
||||
# https://github.com/espressif/esp-idf/blob/
|
||||
# https://github.com/espressif/esp-idf/raw/
|
||||
GH_LINK_RE = r"https://github.com/espressif/esp-idf/(?:tree|blob|raw)/[^\s]+"
|
||||
|
||||
# we allow this one link, because we always want users to see the latest support policy
|
||||
GH_LINK_ALLOWED = ["https://github.com/espressif/esp-idf/blob/master/SUPPORT_POLICY.md"]
|
||||
|
||||
|
||||
def action_gh_linkcheck(args):
|
||||
print("Checking for hardcoded GitHub links\n")
|
||||
|
||||
github_links = []
|
||||
|
||||
docs_dir = os.path.relpath(os.path.dirname(__file__))
|
||||
for root, _, files in os.walk(docs_dir):
|
||||
if "_build" in root:
|
||||
continue
|
||||
files = [os.path.join(root, f) for f in files if f.endswith(".rst")]
|
||||
for path in files:
|
||||
with open(path, "r") as f:
|
||||
for link in re.findall(GH_LINK_RE, f.read()):
|
||||
if link not in GH_LINK_ALLOWED:
|
||||
github_links.append((path, link))
|
||||
|
||||
if github_links:
|
||||
for path, link in github_links:
|
||||
print("%s: %s" % (path, link))
|
||||
print("WARNING: Some .rst files contain hardcoded Github links.")
|
||||
print("Please check above output and replace links with one of the following:")
|
||||
print("- :idf:`dir` - points to directory inside ESP-IDF")
|
||||
print("- :idf_file:`file` - points to file inside ESP-IDF")
|
||||
print("- :idf_raw:`file` - points to raw view of the file inside ESP-IDF")
|
||||
print("- :component:`dir` - points to directory inside ESP-IDF components dir")
|
||||
print("- :component_file:`file` - points to file inside ESP-IDF components dir")
|
||||
print("- :component_raw:`file` - points to raw view of the file inside ESP-IDF components dir")
|
||||
print("- :example:`dir` - points to directory inside ESP-IDF examples dir")
|
||||
print("- :example_file:`file` - points to file inside ESP-IDF examples dir")
|
||||
print("- :example_raw:`file` - points to raw view of the file inside ESP-IDF examples dir")
|
||||
print("These link types will point to the correct GitHub version automatically")
|
||||
return 1
|
||||
else:
|
||||
print("No hardcoded links found")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,39 +0,0 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
# Check for Documentation warnings:
|
||||
# doxygen-warning-log.txt should be an empty file
|
||||
# sphinx-warning-log.txt should only contain (fuzzy) matches to ../sphinx-known-warnings.txt
|
||||
RESULT=0
|
||||
STARS='***************************************************'
|
||||
|
||||
if [ -s doxygen-warning-log.txt ]; then
|
||||
echo "$STARS"
|
||||
echo "Build failed due to doxygen warnings:"
|
||||
cat doxygen-warning-log.txt
|
||||
echo "$STARS"
|
||||
RESULT=1
|
||||
fi
|
||||
|
||||
# Remove escape characters, file paths, line numbers from
|
||||
# the Sphinx warning log
|
||||
# (escape char removal from https://www.commandlinefu.com/commands/view/6141/remove-color-codes-special-characters-with-sed
|
||||
sed -r 's:\x1B\[[0-9;]*[mK]::g' sphinx-warning-log.txt | \
|
||||
sed -E "s/.*\/(.*):[0-9]+:/\1:line:/" > sphinx-warning-log-sanitized.txt
|
||||
|
||||
# diff sanitized warnings, ignoring lines which only appear in ../sphinx-known-warnings.txt
|
||||
|
||||
# format is to display only lines new or changed in second argument
|
||||
DIFF_FORMAT="--unchanged-line-format= --old-line-format= --new-line-format=%L"
|
||||
|
||||
SPHINX_WARNINGS=$(diff $DIFF_FORMAT ../sphinx-known-warnings.txt sphinx-warning-log-sanitized.txt)
|
||||
if ! [ -z "$SPHINX_WARNINGS" ]; then
|
||||
echo "$STARS"
|
||||
echo "Build failed due to new/different Sphinx warnings:"
|
||||
echo "$SPHINX_WARNINGS"
|
||||
echo "$STARS"
|
||||
RESULT=1
|
||||
echo "(Check files ../sphinx-known-warnings.txt and sphinx-warning-log.txt for full details.)"
|
||||
fi
|
||||
|
||||
exit $RESULT
|
||||
|
||||
@@ -18,141 +18,15 @@ from __future__ import print_function
|
||||
from __future__ import unicode_literals
|
||||
import sys
|
||||
import os
|
||||
import os.path
|
||||
import re
|
||||
import subprocess
|
||||
|
||||
# Note: If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute
|
||||
|
||||
from local_util import run_cmd_get_output, copy_if_modified
|
||||
from idf_extensions.util import download_file_if_missing
|
||||
|
||||
# build_docs on the CI server sometimes fails under Python3. This is a workaround:
|
||||
sys.setrecursionlimit(3500)
|
||||
|
||||
try:
|
||||
builddir = os.environ['BUILDDIR']
|
||||
except KeyError:
|
||||
builddir = '_build'
|
||||
|
||||
# Fill in a default IDF_PATH if it's missing (ie when Read The Docs is building the docs)
|
||||
try:
|
||||
idf_path = os.environ['IDF_PATH']
|
||||
except KeyError:
|
||||
idf_path = os.path.realpath(os.path.join(os.path.dirname(__file__), '..'))
|
||||
|
||||
|
||||
def call_with_python(cmd):
|
||||
# using sys.executable ensures that the scripts are called with the same Python interpreter
|
||||
if os.system('{} {}'.format(sys.executable, cmd)) != 0:
|
||||
raise RuntimeError('{} failed'.format(cmd))
|
||||
|
||||
|
||||
# Call Doxygen to get XML files from the header files
|
||||
print("Calling Doxygen to generate latest XML files")
|
||||
if os.system("doxygen ../Doxyfile") != 0:
|
||||
raise RuntimeError('Doxygen call failed')
|
||||
|
||||
# Doxygen has generated XML files in 'xml' directory.
|
||||
# Copy them to 'xml_in', only touching the files which have changed.
|
||||
copy_if_modified('xml/', 'xml_in/')
|
||||
|
||||
# Generate 'api_name.inc' files using the XML files by Doxygen
|
||||
call_with_python('../gen-dxd.py')
|
||||
|
||||
|
||||
def find_component_files(parent_dir, target_filename):
|
||||
parent_dir = os.path.abspath(parent_dir)
|
||||
result = []
|
||||
|
||||
component_files = dict()
|
||||
|
||||
for (dirpath, dirnames, filenames) in os.walk(parent_dir):
|
||||
try:
|
||||
# note: trimming "examples" dir as MQTT submodule
|
||||
# has its own examples directory in the submodule, not part of IDF
|
||||
dirnames.remove("examples")
|
||||
except ValueError:
|
||||
pass
|
||||
if target_filename in filenames:
|
||||
component_files[os.path.basename(dirpath)] = os.path.join(dirpath, target_filename)
|
||||
|
||||
components = sorted(component_files.keys())
|
||||
|
||||
for component in components:
|
||||
result.append(component_files[component])
|
||||
|
||||
print("List of %s: %s" % (target_filename, ", ".join(components)))
|
||||
return result
|
||||
|
||||
|
||||
# Generate 'kconfig.inc' file from components' Kconfig files
|
||||
print("Generating kconfig.inc from kconfig contents")
|
||||
kconfig_inc_path = '{}/inc/kconfig.inc'.format(builddir)
|
||||
temp_sdkconfig_path = '{}/sdkconfig.tmp'.format(builddir)
|
||||
|
||||
kconfigs = find_component_files("../../components", "Kconfig")
|
||||
kconfig_projbuilds = find_component_files("../../components", "Kconfig.projbuild")
|
||||
sdkconfig_renames = find_component_files("../../components", "sdkconfig.rename")
|
||||
|
||||
kconfigs_source_path = '{}/inc/kconfigs_source.in'.format(builddir)
|
||||
kconfig_projbuilds_source_path = '{}/inc/kconfig_projbuilds_source.in'.format(builddir)
|
||||
|
||||
prepare_kconfig_files_args = [sys.executable,
|
||||
"../../tools/kconfig_new/prepare_kconfig_files.py",
|
||||
"--env", "COMPONENT_KCONFIGS={}".format(" ".join(kconfigs)),
|
||||
"--env", "COMPONENT_KCONFIGS_PROJBUILD={}".format(" ".join(kconfig_projbuilds)),
|
||||
"--env", "COMPONENT_KCONFIGS_SOURCE_FILE={}".format(kconfigs_source_path),
|
||||
"--env", "COMPONENT_KCONFIGS_PROJBUILD_SOURCE_FILE={}".format(kconfig_projbuilds_source_path),
|
||||
]
|
||||
subprocess.check_call(prepare_kconfig_files_args)
|
||||
|
||||
confgen_args = [sys.executable,
|
||||
"../../tools/kconfig_new/confgen.py",
|
||||
"--kconfig", "../../Kconfig",
|
||||
"--sdkconfig-rename", "../../sdkconfig.rename",
|
||||
"--config", temp_sdkconfig_path,
|
||||
"--env", "COMPONENT_KCONFIGS={}".format(" ".join(kconfigs)),
|
||||
"--env", "COMPONENT_KCONFIGS_PROJBUILD={}".format(" ".join(kconfig_projbuilds)),
|
||||
"--env", "COMPONENT_SDKCONFIG_RENAMES={}".format(" ".join(sdkconfig_renames)),
|
||||
"--env", "COMPONENT_KCONFIGS_SOURCE_FILE={}".format(kconfigs_source_path),
|
||||
"--env", "COMPONENT_KCONFIGS_PROJBUILD_SOURCE_FILE={}".format(kconfig_projbuilds_source_path),
|
||||
"--env", "IDF_PATH={}".format(idf_path),
|
||||
"--env", "IDF_TARGET={}".format(os.environ.get('IDF_TARGET', 'esp32')),
|
||||
"--output", "docs", kconfig_inc_path + '.in'
|
||||
]
|
||||
subprocess.check_call(confgen_args)
|
||||
copy_if_modified(kconfig_inc_path + '.in', kconfig_inc_path)
|
||||
|
||||
# Generate 'esp_err_defs.inc' file with ESP_ERR_ error code definitions
|
||||
esp_err_inc_path = '{}/inc/esp_err_defs.inc'.format(builddir)
|
||||
call_with_python('../../tools/gen_esp_err_to_name.py --rst_output ' + esp_err_inc_path + '.in')
|
||||
copy_if_modified(esp_err_inc_path + '.in', esp_err_inc_path)
|
||||
|
||||
|
||||
# Generate version-related includes
|
||||
#
|
||||
# (Note: this is in a function as it needs to access configuration to get the language)
|
||||
def generate_version_specific_includes(app):
|
||||
print("Generating version-specific includes...")
|
||||
version_tmpdir = '{}/version_inc'.format(builddir)
|
||||
call_with_python('../gen-version-specific-includes.py {} {}'.format(app.config.language, version_tmpdir))
|
||||
copy_if_modified(version_tmpdir, '{}/inc'.format(builddir))
|
||||
|
||||
|
||||
# Generate toolchain download links
|
||||
print("Generating toolchain download links")
|
||||
base_url = 'https://dl.espressif.com/dl/'
|
||||
toolchain_tmpdir = '{}/toolchain_inc'.format(builddir)
|
||||
call_with_python('../gen-toolchain-links.py ../../tools/toolchain_versions.mk {} {}'.format(base_url, toolchain_tmpdir))
|
||||
copy_if_modified(toolchain_tmpdir, '{}/inc'.format(builddir))
|
||||
|
||||
print("Generating IDF Tools list")
|
||||
os.environ["IDF_MAINTAINER"] = "1"
|
||||
tools_rst = os.path.join(builddir, 'idf-tools-inc.rst')
|
||||
tools_rst_tmp = os.path.join(builddir, 'inc', 'idf-tools-inc.rst')
|
||||
call_with_python("{}/tools/idf_tools.py gen-doc --output {}".format(idf_path, tools_rst_tmp))
|
||||
copy_if_modified(tools_rst_tmp, tools_rst)
|
||||
config_dir = os.path.abspath(os.path.dirname(__file__))
|
||||
|
||||
# http://stackoverflow.com/questions/12772927/specifying-an-online-image-in-sphinx-restructuredtext-format
|
||||
#
|
||||
@@ -160,23 +34,41 @@ suppress_warnings = ['image.nonlocal_uri']
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
# needs_sphinx = '1.0'
|
||||
|
||||
idf_target = ''
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = ['breathe',
|
||||
'link-roles',
|
||||
|
||||
'sphinx.ext.todo',
|
||||
|
||||
'sphinxcontrib.blockdiag',
|
||||
'sphinxcontrib.seqdiag',
|
||||
'sphinxcontrib.actdiag',
|
||||
'sphinxcontrib.nwdiag',
|
||||
'sphinxcontrib.rackdiag',
|
||||
'sphinxcontrib.packetdiag',
|
||||
'html_redirects',
|
||||
'sphinx.ext.todo',
|
||||
|
||||
'extensions.html_redirects',
|
||||
'extensions.toctree_filter',
|
||||
|
||||
'idf_extensions.include_build_file',
|
||||
'idf_extensions.link_roles',
|
||||
'idf_extensions.build_system',
|
||||
'idf_extensions.esp_err_definitions',
|
||||
'idf_extensions.gen_toolchain_links',
|
||||
'idf_extensions.gen_version_specific_includes',
|
||||
'idf_extensions.kconfig_reference',
|
||||
'idf_extensions.run_doxygen',
|
||||
'idf_extensions.gen_idf_tools_links',
|
||||
'idf_extensions.format_idf_target',
|
||||
|
||||
# from https://github.com/pfalcon/sphinx_selective_exclude
|
||||
'sphinx_selective_exclude.eager_only',
|
||||
# TODO: determine if we need search_auto_exclude
|
||||
# 'sphinx_selective_exclude.search_auto_exclude',
|
||||
]
|
||||
|
||||
# sphinx.ext.todo extension parameters
|
||||
@@ -187,13 +79,6 @@ todo_include_todos = False
|
||||
# Enabling this fixes cropping of blockdiag edge labels
|
||||
seqdiag_antialias = True
|
||||
|
||||
# Breathe extension variables
|
||||
|
||||
# Doxygen regenerates files in 'xml/' directory every time,
|
||||
# but we copy files to 'xml_in/' only when they change, to speed up
|
||||
# incremental builds.
|
||||
breathe_projects = {"esp32-idf": "xml_in/"}
|
||||
breathe_default_project = "esp32-idf"
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
@@ -222,7 +107,7 @@ master_doc = 'index'
|
||||
# This is supposed to be "the short X.Y version", but it's the only version
|
||||
# visible when you open index.html.
|
||||
# Display full version to make things less confusing.
|
||||
version = run_cmd_get_output('git describe')
|
||||
version = subprocess.check_output(['git', 'describe']).strip().decode('utf-8')
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
# If needed, nearest tag is returned by 'git describe --abbrev=0'.
|
||||
release = version
|
||||
@@ -236,7 +121,45 @@ print('Version: {0} Release: {1}'.format(version, release))
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
exclude_patterns = ['_build','README.md']
|
||||
exclude_patterns = ['**/inc/**', '_static', '**/_build']
|
||||
|
||||
|
||||
# Add target-specific excludes based on tags (for the IDF_TARGET). Haven't found any better way to do this yet
|
||||
def update_exclude_patterns(tags):
|
||||
if "esp32" not in tags:
|
||||
# Exclude ESP32-only document pages so they aren't found in the initial search for .rst files
|
||||
# note: in toctrees, these also need to be marked with a :esp32: filter
|
||||
for e in ['api-guides/blufi.rst',
|
||||
'api-guides/build-system-legacy.rst',
|
||||
'api-guides/esp-ble-mesh/**',
|
||||
'api-guides/RF_calibration.rst', # temporary until support re-added in esp_wifi
|
||||
'api-guides/ulp-legacy.rst',
|
||||
'api-guides/unit-tests-legacy.rst',
|
||||
'api-guides/ulp_instruction_set.rst',
|
||||
'api-guides/jtag-debugging/configure-wrover.rst',
|
||||
'api-reference/system/himem.rst',
|
||||
'api-reference/bluetooth/**',
|
||||
'api-reference/peripherals/sdio_slave.rst',
|
||||
'api-reference/peripherals/esp_slave_protocol.rst',
|
||||
'api-reference/peripherals/mcpwm.rst',
|
||||
'api-reference/peripherals/sd_pullup_requirements.rst',
|
||||
'api-reference/peripherals/sdmmc_host.rst',
|
||||
'api-reference/protocols/esp_serial_slave_link.rst',
|
||||
'api-reference/system/ipc.rst',
|
||||
'get-started-legacy/**',
|
||||
'gnu-make-legacy.rst',
|
||||
'hw-reference/esp32/**',
|
||||
]:
|
||||
exclude_patterns.append(e)
|
||||
|
||||
if "esp32s2" not in tags:
|
||||
# Exclude ESP32-only document pages so they aren't found in the initial search for .rst files
|
||||
# note: in toctrees, these also need to be marked with a :esp32: filter
|
||||
for e in ['hw-reference/esp32s2/**',
|
||||
'api-guides/ulps2_instruction_set.rst',
|
||||
'api-reference/peripherals/temp_sensor.rst']:
|
||||
exclude_patterns.append(e)
|
||||
|
||||
|
||||
# The reST default role (used for this markup: `text`) to use for all
|
||||
# documents.
|
||||
@@ -442,4 +365,36 @@ texinfo_documents = [
|
||||
# https://github.com/rtfd/sphinx_rtd_theme/pull/432
|
||||
def setup(app):
|
||||
app.add_stylesheet('theme_overrides.css')
|
||||
generate_version_specific_includes(app)
|
||||
app.add_config_value('idf_target', '', 'env')
|
||||
# Breathe extension variables (depend on build_dir)
|
||||
# note: we generate into xml_in and then copy_if_modified to xml dir
|
||||
app.config.breathe_projects = {"esp32-idf": os.path.join(app.config.build_dir, "xml_in/")}
|
||||
app.config.breathe_default_project = "esp32-idf"
|
||||
|
||||
setup_diag_font(app)
|
||||
|
||||
|
||||
def setup_diag_font(app):
|
||||
# blockdiag and other tools require a font which supports their character set
|
||||
# the font file is stored on the download server to save repo size
|
||||
|
||||
font_name = {
|
||||
'en': 'DejaVuSans.ttf',
|
||||
'zh_CN': 'NotoSansSC-Regular.otf',
|
||||
}[app.config.language]
|
||||
|
||||
font_dir = os.path.join(config_dir, '_static')
|
||||
assert os.path.exists(font_dir)
|
||||
|
||||
print("Downloading font file %s for %s" % (font_name, app.config.language))
|
||||
download_file_if_missing('https://dl.espressif.com/dl/esp-idf/docs/_static/{}'.format(font_name), font_dir)
|
||||
|
||||
font_path = os.path.abspath(os.path.join(font_dir, font_name))
|
||||
assert os.path.exists(font_path)
|
||||
|
||||
app.config.blockdiag_fontpath = font_path
|
||||
app.config.seqdiag_fontpath = font_path
|
||||
app.config.actdiag_fontpath = font_path
|
||||
app.config.nwdiag_fontpath = font_path
|
||||
app.config.rackdiag_fontpath = font_path
|
||||
app.config.packetdiag_fontpath = font_path
|
||||
|
||||
@@ -1,217 +0,0 @@
|
||||
# "Common" Makefile for Sphinx documentation
|
||||
#
|
||||
# (included from en/Makefile & zh_CN/Makefile
|
||||
#
|
||||
# NOTE: This makefile runs with cwd=either en or zh_CN subfolder, so this
|
||||
# (docs/) directory is '..' relative to it.
|
||||
|
||||
# ************ IMPORTANT *****************
|
||||
#
|
||||
# ReadTheDocs DOES NOT USE THIS MAKEFILE,
|
||||
# so any behaviour additions must be
|
||||
# done via Sphinx Config not here
|
||||
#
|
||||
# ****************************************
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
# note: this is changed from sphinx-build so it depends on default python interpreter, not on /bin/sphinx-build
|
||||
# (which will be the most recently installed version of sphinx and may not match)
|
||||
SPHINXBUILD = python -m sphinx
|
||||
PAPER =
|
||||
BUILDDIR = _build
|
||||
|
||||
# Internal variables.
|
||||
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||
PAPEROPT_letter = -D latex_paper_size=letter
|
||||
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -w sphinx-warning-log.txt .
|
||||
# the i18n builder cannot share the environment and doctrees with the others
|
||||
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||
|
||||
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext dependencies version-specific-includes check_python_packages
|
||||
|
||||
help:
|
||||
@echo "Please use \`make <target>\' where <target> is one of"
|
||||
@echo " html to make standalone HTML files"
|
||||
@echo " dirhtml to make HTML files named index.html in directories"
|
||||
@echo " singlehtml to make a single large HTML file"
|
||||
@echo " pickle to make pickle files"
|
||||
@echo " json to make JSON files"
|
||||
@echo " htmlhelp to make HTML files and a HTML help project"
|
||||
@echo " qthelp to make HTML files and a qthelp project"
|
||||
@echo " devhelp to make HTML files and a Devhelp project"
|
||||
@echo " epub to make an epub"
|
||||
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
||||
@echo " latexpdf to make LaTeX files and run them through pdflatex"
|
||||
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
|
||||
@echo " text to make text files"
|
||||
@echo " man to make manual pages"
|
||||
@echo " texinfo to make Texinfo files"
|
||||
@echo " info to make Texinfo files and run them through makeinfo"
|
||||
@echo " gettext to make PO message catalogs"
|
||||
@echo " changes to make an overview of all changed/added/deprecated items"
|
||||
@echo " xml to make Docutils-native XML files"
|
||||
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
|
||||
@echo " linkcheck to check all external links for integrity"
|
||||
@echo " doctest to run all doctests embedded in the documentation (if enabled) "
|
||||
|
||||
clean:
|
||||
rm -rf $(BUILDDIR)/*
|
||||
|
||||
# Notify users when some of the required python packages are not installed.
|
||||
# Note: This is intended to help developers who generate the documentation on their local machine. Read The Docs uses
|
||||
# the requirements.txt file directly and calls sphinx also directly without the use of the makefile!
|
||||
check_python_packages:
|
||||
$(IDF_PATH)/tools/check_python_dependencies.py -r $(IDF_PATH)/docs/requirements.txt
|
||||
|
||||
html: | check_python_packages
|
||||
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||
|
||||
dirhtml: | check_python_packages
|
||||
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
|
||||
|
||||
singlehtml: | check_python_packages
|
||||
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
|
||||
|
||||
pickle: | check_python_packages
|
||||
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
|
||||
@echo
|
||||
@echo "Build finished; now you can process the pickle files."
|
||||
|
||||
json: | check_python_packages
|
||||
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
|
||||
@echo
|
||||
@echo "Build finished; now you can process the JSON files."
|
||||
|
||||
htmlhelp: | check_python_packages
|
||||
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run HTML Help Workshop with the" \
|
||||
".hhp project file in $(BUILDDIR)/htmlhelp."
|
||||
|
||||
qthelp: | check_python_packages
|
||||
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
||||
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
|
||||
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ReadtheDocsTemplate.qhcp"
|
||||
@echo "To view the help file:"
|
||||
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ReadtheDocsTemplate.qhc"
|
||||
|
||||
devhelp: | check_python_packages
|
||||
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
|
||||
@echo
|
||||
@echo "Build finished."
|
||||
@echo "To view the help file:"
|
||||
@echo "# mkdir -p $$HOME/.local/share/devhelp/ReadtheDocsTemplate"
|
||||
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ReadtheDocsTemplate"
|
||||
@echo "# devhelp"
|
||||
|
||||
epub: | check_python_packages
|
||||
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
|
||||
@echo
|
||||
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
|
||||
|
||||
latex: | check_python_packages
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo
|
||||
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
|
||||
@echo "Run \`make' in that directory to run these through (pdf)latex" \
|
||||
"(use \`make latexpdf' here to do that automatically)."
|
||||
|
||||
latexpdf: | check_python_packages
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo "Running LaTeX files through pdflatex..."
|
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf
|
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||
|
||||
latexpdfja: | check_python_packages
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo "Running LaTeX files through platex and dvipdfmx..."
|
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
|
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||
|
||||
text: | check_python_packages
|
||||
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
|
||||
@echo
|
||||
@echo "Build finished. The text files are in $(BUILDDIR)/text."
|
||||
|
||||
man: | check_python_packages
|
||||
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
|
||||
@echo
|
||||
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
|
||||
|
||||
texinfo: | check_python_packages
|
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||
@echo
|
||||
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
|
||||
@echo "Run \`make' in that directory to run these through makeinfo" \
|
||||
"(use \`make info' here to do that automatically)."
|
||||
|
||||
info: | check_python_packages
|
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||
@echo "Running Texinfo files through makeinfo..."
|
||||
make -C $(BUILDDIR)/texinfo info
|
||||
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
|
||||
|
||||
gettext: | check_python_packages
|
||||
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
|
||||
@echo
|
||||
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
|
||||
|
||||
changes: | check_python_packages
|
||||
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
|
||||
@echo
|
||||
@echo "The overview file is in $(BUILDDIR)/changes."
|
||||
|
||||
linkcheck: | check_python_packages
|
||||
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
|
||||
@echo
|
||||
@echo "Link check complete; look for any errors in the above output " \
|
||||
"or in $(BUILDDIR)/linkcheck/output.txt."
|
||||
|
||||
gh-linkcheck: | check_python_packages
|
||||
@echo "Checking for hardcoded GitHub links" # note: exception for links to support policy doc as we *want* this to be a link to master's policy
|
||||
@if (find ../ -name '*.rst' | xargs grep \
|
||||
'https://github.com/espressif/esp-idf/tree\|https://github.com/espressif/esp-idf/blob\|https://github.com/espressif/esp-idf/raw' \
|
||||
| grep -v 'SUPPORT_POLICY\.md' \
|
||||
); \
|
||||
then \
|
||||
echo "WARNINIG: Some .rst files contain hardcoded Github links."; \
|
||||
echo "Please check above output and replace links with one of the following:"; \
|
||||
echo "- :idf:\`dir\` - points to directory inside ESP-IDF"; \
|
||||
echo "- :idf_file:\`file\` - points to file inside ESP-IDF"; \
|
||||
echo "- :idf_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \
|
||||
echo "- :component:\`dir\` - points to directory inside ESP-IDF components dir"; \
|
||||
echo "- :component_file:\`file\` - points to file inside ESP-IDF components dir"; \
|
||||
echo "- :component_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \
|
||||
echo " components dir"; \
|
||||
echo "- :example:\`dir\` - points to directory inside ESP-IDF examples dir"; \
|
||||
echo "- :example_file:\`file\` - points to file inside ESP-IDF examples dir"; \
|
||||
echo "- :example_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \
|
||||
echo " examples dir"; \
|
||||
echo "These link types will point to the correct GitHub version automatically"; \
|
||||
exit 1; \
|
||||
fi
|
||||
@echo "No hardcoded links found"
|
||||
|
||||
doctest: | check_python_packages
|
||||
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
|
||||
@echo "Testing of doctests in the sources finished, look at the " \
|
||||
"results in $(BUILDDIR)/doctest/output.txt."
|
||||
|
||||
xml: | check_python_packages
|
||||
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
|
||||
@echo
|
||||
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
|
||||
|
||||
pseudoxml: | check_python_packages
|
||||
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
|
||||
@echo
|
||||
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
|
||||
1
docs/doxygen-known-warnings.txt
Normal file
1
docs/doxygen-known-warnings.txt
Normal file
@@ -0,0 +1 @@
|
||||
semphr.h:line: warning: argument 'pxStaticSemaphore' of command @param is not found in the argument list of xSemaphoreCreateCounting(uxMaxCount, uxInitialCount)
|
||||
@@ -1,2 +0,0 @@
|
||||
LANGUAGE=en
|
||||
include ../docs_common.mk
|
||||
@@ -2,9 +2,18 @@ About
|
||||
=====
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
This is documentation of `ESP-IDF <https://github.com/espressif/esp-idf>`_, the framework to develop applications for `ESP32 <https://espressif.com/en/products/hardware/esp32/overview>`_ chip by `Espressif <https://espressif.com>`_.
|
||||
.. only:: esp32
|
||||
|
||||
The ESP32 is 2.4 GHz Wi-Fi and Bluetooth combo, which integrates one or two 32-bit microprocessors, with up to 600 DMIPS processing power.
|
||||
This is documentation of `ESP-IDF <https://github.com/espressif/esp-idf>`_, the framework to develop applications for `{IDF_TARGET_NAME} <https://espressif.com/en/products/hardware/esp32/overview>`_ chip by `Espressif <https://espressif.com>`_.
|
||||
|
||||
The {IDF_TARGET_NAME} is 2.4 GHz Wi-Fi and Bluetooth combo, which integrates one or two 32-bit microprocessors, with up to 600 DMIPS processing power.
|
||||
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
This is documentation of `ESP-IDF <https://github.com/espressif/esp-idf>`_, the framework to develop applications for {IDF_TARGET_NAME}.
|
||||
|
||||
The {IDF_TARGET_NAME} is a 2.4 GHz Wi-Fi module, which integrates a 32-bit microprocessors, with up to 600 DMIPS processing power.
|
||||
|
||||
.. figure:: ../_static/about-doc.png
|
||||
:align: center
|
||||
@@ -13,5 +22,5 @@ The ESP32 is 2.4 GHz Wi-Fi and Bluetooth combo, which integrates one or two 32-b
|
||||
|
||||
Espressif IoT Integrated Development Framework
|
||||
|
||||
The ESP-IDF, Espressif IoT Development Framework, provides toolchain, API, components and workflows to develop applications for ESP32 using Windows, Linux and Mac OS operating systems.
|
||||
The ESP-IDF, Espressif IoT Development Framework, provides toolchain, API, components and workflows to develop applications for {IDF_TARGET_NAME} using Windows, Linux and Mac OS operating systems.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
RF calibration
|
||||
==============
|
||||
|
||||
ESP32 supports three RF calibration methods during RF initialization:
|
||||
{IDF_TARGET_NAME} supports three RF calibration methods during RF initialization:
|
||||
|
||||
1. Partial calibration
|
||||
|
||||
@@ -41,14 +41,15 @@ If you use the default method of RF calibration, there are two ways to add the f
|
||||
|
||||
No calibration
|
||||
---------------
|
||||
No calibration method is only used when ESP32 wakes up from deep sleep.
|
||||
No calibration method is only used when {IDF_TARGET_NAME} wakes up from deep sleep.
|
||||
|
||||
PHY initialization data
|
||||
-----------------------
|
||||
The PHY initialization data is used for RF calibration.
|
||||
There are two ways to get the PHY initialization data.
|
||||
|
||||
One is the default initialization data which is located in the header file :idf_file:`components/esp_wifi/esp32/include/phy_init_data.h`.
|
||||
One is the default initialization data which is located in the header file :idf_file:`components/esp_wifi/{IDF_TARGET_PATH_NAME}/include/phy_init_data.h`.
|
||||
|
||||
It is embedded into the application binary after compiling and then stored into read-only memory (DROM).
|
||||
To use the default initialization data, please go to ``menuconfig`` and disable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION`.
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ Application Level Tracing library
|
||||
Overview
|
||||
--------
|
||||
|
||||
IDF provides useful feature for program behavior analysis: application level tracing. It is implemented in the corresponding library and can be enabled in menuconfig. This feature allows to transfer arbitrary data between host and ESP32 via JTAG interface with small overhead on program execution.
|
||||
IDF provides useful feature for program behavior analysis: application level tracing. It is implemented in the corresponding library and can be enabled in menuconfig. This feature allows to transfer arbitrary data between host and {IDF_TARGET_NAME} via JTAG interface with small overhead on program execution.
|
||||
|
||||
Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are:
|
||||
|
||||
@@ -31,7 +31,7 @@ The library supports two modes of operation:
|
||||
|
||||
**Post-mortem mode**. This is the default mode. The mode does not need interaction with the host side. In this mode tracing module does not check whether host has read all the data from *HW UP BUFFER* buffer and overwrites old data with the new ones. This mode is useful when only the latest trace data are interesting to the user, e.g. for analyzing program's behavior just before the crash. Host can read the data later on upon user request, e.g. via special OpenOCD command in case of working via JTAG interface.
|
||||
|
||||
**Streaming mode.** Tracing module enters this mode when host connects to ESP32. In this mode before writing new data to *HW UP BUFFER* tracing module checks that there is enough space in it and if necessary waits for the host to read data and free enough memory. Maximum waiting time is controlled via timeout values passed by users to corresponding API routines. So when application tries to write data to trace buffer using finite value of the maximum waiting time it is possible situation that this data will be dropped. Especially this is true for tracing from time critical code (ISRs, OS scheduler code etc.) when infinite timeouts can lead to system malfunction. In order to avoid loss of such critical data developers can enable additional data buffering via menuconfig option :ref:`CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX`. This macro specifies the size of data which can be buffered in above conditions. The option can also help to overcome situation when data transfer to the host is temporarily slowed down, e.g due to USB bus congestions etc. But it will not help when average bitrate of trace data stream exceeds HW interface capabilities.
|
||||
**Streaming mode.** Tracing module enters this mode when host connects to {IDF_TARGET_NAME}. In this mode before writing new data to *HW UP BUFFER* tracing module checks that there is enough space in it and if necessary waits for the host to read data and free enough memory. Maximum waiting time is controlled via timeout values passed by users to corresponding API routines. So when application tries to write data to trace buffer using finite value of the maximum waiting time it is possible situation that this data will be dropped. Especially this is true for tracing from time critical code (ISRs, OS scheduler code etc.) when infinite timeouts can lead to system malfunction. In order to avoid loss of such critical data developers can enable additional data buffering via menuconfig option :ref:`CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX`. This macro specifies the size of data which can be buffered in above conditions. The option can also help to overcome situation when data transfer to the host is temporarily slowed down, e.g due to USB bus congestions etc. But it will not help when average bitrate of trace data stream exceeds HW interface capabilities.
|
||||
|
||||
|
||||
Configuration Options and Dependencies
|
||||
@@ -55,7 +55,7 @@ There are two additional menuconfig options not mentioned above:
|
||||
How to use this library
|
||||
-----------------------
|
||||
|
||||
This library provides API for transferring arbitrary data between host and ESP32. When enabled in menuconfig target application tracing module is initialized automatically at the system startup, so all what the user needs to do is to call corresponding API to send, receive or flush the data.
|
||||
This library provides API for transferring arbitrary data between host and {IDF_TARGET_NAME}. When enabled in menuconfig target application tracing module is initialized automatically at the system startup, so all what the user needs to do is to call corresponding API to send, receive or flush the data.
|
||||
|
||||
.. _app_trace-application-specific-tracing:
|
||||
|
||||
@@ -326,7 +326,7 @@ How To Use It
|
||||
|
||||
Support for this feature is enabled by *Component config > Application Level Tracing > FreeRTOS SystemView Tracing* (:ref:`CONFIG_SYSVIEW_ENABLE`) menuconfig option. There are several other options enabled under the same menu:
|
||||
|
||||
1. *ESP32 timer to use as SystemView timestamp source* (:ref:`CONFIG_SYSVIEW_TS_SOURCE`) selects the source of timestamps for SystemView events. In single core mode timestamps are generated using ESP32 internal cycle counter running at maximum 240 Mhz (~4 ns granularity). In dual-core mode external timer working at 40 Mhz is used, so timestamp granularity is 25 ns.
|
||||
1. {IDF_TARGET_NAME} timer to use as SystemView timestamp source: (:ref:`CONFIG_SYSVIEW_TS_SOURCE`) selects the source of timestamps for SystemView events. In single core mode timestamps are generated using {IDF_TARGET_NAME} internal cycle counter running at maximum 240 Mhz (~4 ns granularity). In dual-core mode external timer working at 40 Mhz is used, so timestamp granularity is 25 ns.
|
||||
2. Individually enabled or disabled collection of SystemView events (``CONFIG_SYSVIEW_EVT_XXX``):
|
||||
|
||||
- Trace Buffer Overflow Event
|
||||
@@ -405,7 +405,7 @@ Command usage examples:
|
||||
Data Visualization
|
||||
""""""""""""""""""
|
||||
|
||||
After trace data are collected user can use special tool to visualize the results and inspect behavior of the program. Unfortunately SystemView does not support tracing from multiple cores. So when tracing from ESP32 working in dual-core mode two files are generated: one for PRO CPU and another one for APP CPU. User can load every file into separate instance of the tool.
|
||||
After trace data are collected user can use special tool to visualize the results and inspect behavior of the program. Unfortunately SystemView does not support tracing from multiple cores. So when tracing from {IDF_TARGET_NAME} working in dual-core mode two files are generated: one for PRO CPU and another one for APP CPU. User can load every file into separate instance of the tool.
|
||||
|
||||
It is uneasy and awkward to analyze data for every core in separate instance of the tool. Fortunately there is Eclipse plugin called *Impulse* which can load several trace files and makes it possible to inspect events from both cores in one view. Also this plugin has no limitation of 1,000,000 events as compared to free version of SystemView.
|
||||
|
||||
@@ -511,15 +511,12 @@ ESP-IDF supports two methods of dumping code coverage data form the target to th
|
||||
Instant Run-Time Dump
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
An Instant Run-Time Dump is triggered by calling the ``esp32 gcov`` OpenOCD command (via a telnet session). Once called, OpenOCD will immediately preempt the ESP32's current state and execute a builtin IDF Gcov debug stub function. The debug stub function will handle the dumping of data to the Host. Upon completion, the ESP32 will resume it's current state.
|
||||
|
||||
.. note::
|
||||
Due to the use of the debug stub function, the OpenOCD Debug Stub option must be enabled in project configuration. The option can be found under ``Component config -> ESP32-specific -> OpenOCD debug stubs``.
|
||||
An Instant Run-Time Dump is triggered by calling the ``esp32 gcov`` OpenOCD command (via a telnet session). Once called, OpenOCD will immediately preempt the {IDF_TARGET_NAME}'s current state and execute a builtin IDF Gcov debug stub function. The debug stub function will handle the dumping of data to the Host. Upon completion, the {IDF_TARGET_NAME} will resume it's current state.
|
||||
|
||||
Hard-coded Dump
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
A Hard-coded Dump is triggered by the application itself by calling :cpp:func:`esp_gcov_dump` from somewhere within the application. When called, the application will halt and wait for OpenOCD to connect and retrieve the code coverage data. Once :cpp:func:`esp_gcov_dump` is called, the Host must execute the ``esp32 gcov dump`` OpenOCD command (via a telnet session). The ``esp32 gcov dump`` command will cause OpenOCD to connect to the ESP32, retrieve the code coverage data, then disconnect from the ESP32 thus allowing the application to resume. Hard-coded Dumps can also be triggered multiple times throughout an application's lifetime.
|
||||
A Hard-coded Dump is triggered by the application itself by calling :cpp:func:`esp_gcov_dump` from somewhere within the application. When called, the application will halt and wait for OpenOCD to connect and retrieve the code coverage data. Once :cpp:func:`esp_gcov_dump` is called, the Host must execute the ``esp32 gcov dump`` OpenOCD command (via a telnet session). The ``esp32 gcov dump`` command will cause OpenOCD to connect to the {IDF_TARGET_NAME}, retrieve the code coverage data, then disconnect from the {IDF_TARGET_NAME} thus allowing the application to resume. Hard-coded Dumps can also be triggered multiple times throughout an application's lifetime.
|
||||
|
||||
Hard-coded dumps are useful if code coverage data is required at certain points of an application's lifetime by placing :cpp:func:`esp_gcov_dump` where necessary (e.g., after application initialization, during each iteration of an application's main loop).
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ BluFi
|
||||
|
||||
Overview
|
||||
--------
|
||||
The BluFi for ESP32 is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to the ESP32. Using this information ESP32 can then e.g. connect to an AP or establish a SoftAP.
|
||||
The BluFi for {IDF_TARGET_NAME} is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to the {IDF_TARGET_NAME}. Using this information {IDF_TARGET_NAME} can then e.g. connect to an AP or establish a SoftAP.
|
||||
|
||||
Fragmenting, data encryption, checksum verification in the BluFi layer are the key elements of this process.
|
||||
|
||||
@@ -16,29 +16,29 @@ The BluFi networking flow includes the configuration of the SoftAP and Station.
|
||||
|
||||
The following uses Station as an example to illustrate the core parts of the procedure, including broadcast, connection, service discovery, negotiation of the shared key, data transmission, connection status backhaul.
|
||||
|
||||
1. Set the ESP32 into GATT Server mode and then it will send broadcasts with specific *advertising data*. You can customize this broadcast as needed, which is not a part of the BluFi Profile.
|
||||
1. Set the {IDF_TARGET_NAME} into GATT Server mode and then it will send broadcasts with specific *advertising data*. You can customize this broadcast as needed, which is not a part of the BluFi Profile.
|
||||
|
||||
2. Use the App installed on the mobile phone to search for this particular broadcast. The mobile phone will connect to ESP32 as the GATT Client once the broadcast is confirmed. The App used during this part is up to you.
|
||||
2. Use the App installed on the mobile phone to search for this particular broadcast. The mobile phone will connect to {IDF_TARGET_NAME} as the GATT Client once the broadcast is confirmed. The App used during this part is up to you.
|
||||
|
||||
3. After the GATT connection is successfully established, the mobile phone will send a data frame for key negotiation to ESP32 (see the section :ref:`frame_formats` for details).
|
||||
3. After the GATT connection is successfully established, the mobile phone will send a data frame for key negotiation to {IDF_TARGET_NAME} (see the section :ref:`frame_formats` for details).
|
||||
|
||||
4. After ESP32 receives the data frame of key negotiation, it will parse the content according to the user-defined negotiation method.
|
||||
4. After {IDF_TARGET_NAME} receives the data frame of key negotiation, it will parse the content according to the user-defined negotiation method.
|
||||
|
||||
5. The mobile phone works with ESP32 for key negotiation using the encryption algorithms such as DH, RSA or ECC.
|
||||
5. The mobile phone works with {IDF_TARGET_NAME} for key negotiation using the encryption algorithms such as DH, RSA or ECC.
|
||||
|
||||
6. After the negotiation process is completed, the mobile phone will send a control frame for security-mode setup to ESP32.
|
||||
6. After the negotiation process is completed, the mobile phone will send a control frame for security-mode setup to {IDF_TARGET_NAME}.
|
||||
|
||||
7. When receiving this control frame, ESP32 will be able to encrypt and decrypt the communication data using the shared key and the security configuration.
|
||||
7. When receiving this control frame, {IDF_TARGET_NAME} will be able to encrypt and decrypt the communication data using the shared key and the security configuration.
|
||||
|
||||
8. The mobile phone sends the data frame defined in the section of :ref:`frame_formats`，with the Wi-Fi configuration information to ESP32, including SSID, password, etc.
|
||||
8. The mobile phone sends the data frame defined in the section of :ref:`frame_formats`，with the Wi-Fi configuration information to {IDF_TARGET_NAME}, including SSID, password, etc.
|
||||
|
||||
9. The mobile phone sends a control frame of Wi-Fi connection request to ESP32. When receiving this control frame, ESP32 will regard the communication of essential information as done and get ready to connect to the Wi-Fi.
|
||||
9. The mobile phone sends a control frame of Wi-Fi connection request to {IDF_TARGET_NAME}. When receiving this control frame, {IDF_TARGET_NAME} will regard the communication of essential information as done and get ready to connect to the Wi-Fi.
|
||||
|
||||
10. After connecting to the Wi-Fi, ESP32 will send a control frame of Wi-Fi connection status report to the mobile phone，to report the connection status. At this point the networking procedure is completed.
|
||||
10. After connecting to the Wi-Fi, {IDF_TARGET_NAME} will send a control frame of Wi-Fi connection status report to the mobile phone，to report the connection status. At this point the networking procedure is completed.
|
||||
|
||||
.. note::
|
||||
|
||||
1. After ESP32 receives the control frame of security-mode configuration, it will execute the operations in accordance with the defined security mode.
|
||||
1. After {IDF_TARGET_NAME} receives the control frame of security-mode configuration, it will execute the operations in accordance with the defined security mode.
|
||||
|
||||
2. The data lengths before and after symmetric encryption/decryption must stay the same. It also supports in-place encryption and decryption.
|
||||
|
||||
@@ -57,16 +57,16 @@ The flow chart of BluFi
|
||||
span_height = 10;
|
||||
default_fontsize = 12;
|
||||
|
||||
Phone <- ESP32 [label="Advertising"];
|
||||
Phone -> ESP32 [label="Create GATT connection"];
|
||||
Phone <- ESP32 [label="Negotiate key procedure"];
|
||||
Phone -> ESP32 [label="Negotiate key procedure"];
|
||||
Phone -> ESP32 [label="CTRL: Set ESP32 to Phone Security mode"];
|
||||
Phone -> ESP32 [label="DATA: SSID"];
|
||||
Phone -> ESP32 [label="DATA: Password"];
|
||||
Phone -> ESP32 [label="DATA: Other information, such as CA certification"];
|
||||
Phone -> ESP32 [label="CTRL: Connect to AP"];
|
||||
Phone <- ESP32 [label="DATA: Connection State Report"];
|
||||
Phone <- {IDF_TARGET_NAME} [label="Advertising"];
|
||||
Phone -> {IDF_TARGET_NAME} [label="Create GATT connection"];
|
||||
Phone <- {IDF_TARGET_NAME} [label="Negotiate key procedure"];
|
||||
Phone -> {IDF_TARGET_NAME} [label="Negotiate key procedure"];
|
||||
Phone -> {IDF_TARGET_NAME} [label="CTRL: Set {IDF_TARGET_NAME} to Phone Security mode"];
|
||||
Phone -> {IDF_TARGET_NAME} [label="DATA: SSID"];
|
||||
Phone -> {IDF_TARGET_NAME} [label="DATA: Password"];
|
||||
Phone -> {IDF_TARGET_NAME} [label="DATA: Other information, such as CA certification"];
|
||||
Phone -> {IDF_TARGET_NAME} [label="CTRL: Connect to AP"];
|
||||
Phone <- {IDF_TARGET_NAME} [label="DATA: Connection State Report"];
|
||||
}
|
||||
|
||||
.. _frame_formats:
|
||||
@@ -74,7 +74,7 @@ The flow chart of BluFi
|
||||
The Frame Formats Defined in BluFi
|
||||
-----------------------------------
|
||||
|
||||
The frame formats for the communication between the mobile phone App and ESP32 are defined as follows:
|
||||
The frame formats for the communication between the mobile phone App and {IDF_TARGET_NAME} are defined as follows:
|
||||
|
||||
The frame format with no fragment (8 bit)：
|
||||
|
||||
@@ -391,8 +391,8 @@ The format of Ack Frame（8 bit）：
|
||||
|
||||
This field takes 2 bytes that is used to check "sequence + data length + clear text data".
|
||||
|
||||
The Security Implementation of ESP32
|
||||
-------------------------------------
|
||||
The Security Implementation of {IDF_TARGET_NAME}
|
||||
------------------------------------------------
|
||||
|
||||
1. Securing data
|
||||
|
||||
@@ -410,7 +410,7 @@ The Security Implementation of ESP32
|
||||
|
||||
It is added to the Sequence field and used during the checksum verification.
|
||||
|
||||
For the coding of ESP32, you can determine and develop the security processing, such as key negotiation. The mobile application sends the negotiation data to ESP32 and then the data will be sent to the application layer for processing. If the application layer does not process it, you can use the DH encryption algorithm provided by BluFi to negotiate the key.
|
||||
For the coding of {IDF_TARGET_NAME}, you can determine and develop the security processing, such as key negotiation. The mobile application sends the negotiation data to {IDF_TARGET_NAME} and then the data will be sent to the application layer for processing. If the application layer does not process it, you can use the DH encryption algorithm provided by BluFi to negotiate the key.
|
||||
|
||||
The application layer needs to register several security-related functions to BluFi:
|
||||
|
||||
@@ -418,7 +418,7 @@ The Security Implementation of ESP32
|
||||
|
||||
typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free)
|
||||
|
||||
This function is for ESP32 to receive normal data during negotiation, and after processing is completed, the data will be transmitted using Output_data and Output_len.
|
||||
This function is for {IDF_TARGET_NAME} to receive normal data during negotiation, and after processing is completed, the data will be transmitted using Output_data and Output_len.
|
||||
|
||||
BluFi will send output_data from Negotiate_data_handler after Negotiate_data_handler is called.
|
||||
|
||||
@@ -450,6 +450,6 @@ UUID
|
||||
|
||||
BluFi Service UUID: 0xFFFF，16 bit
|
||||
|
||||
BluFi (the mobile -> ESP32): 0xFF01, writable
|
||||
BluFi (the mobile -> {IDF_TARGET_NAME}): 0xFF01, writable
|
||||
|
||||
Blufi (ESP32 -> the mobile phone): 0xFF02, readable and callable
|
||||
Blufi ({IDF_TARGET_NAME} -> the mobile phone): 0xFF02, readable and callable
|
||||
|
||||
@@ -22,7 +22,7 @@ Overview
|
||||
An ESP-IDF project can be seen as an amalgamation of a number of components.
|
||||
For example, for a webserver that shows the current humidity, there could be:
|
||||
|
||||
- The ESP32 base libraries (libc, rom bindings etc)
|
||||
- The {IDF_TARGET_NAME} base libraries (libc, rom bindings etc)
|
||||
- The Wi-Fi drivers
|
||||
- A TCP/IP stack
|
||||
- The FreeRTOS operating system
|
||||
|
||||
@@ -5,6 +5,8 @@ Build System
|
||||
|
||||
This document explains the implementation of the ESP-IDF build system and the concept of "components". Read this document if you want to know how to organise and build a new ESP-IDF project or component.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. note:: This document describes the CMake-based build system, which is the default since ESP-IDF V4.0. ESP-IDF also supports a :doc:`legacy build system based on GNU Make <build-system-legacy>`, which was the default before ESP-IDF V4.0.
|
||||
|
||||
|
||||
@@ -14,7 +16,7 @@ Overview
|
||||
An ESP-IDF project can be seen as an amalgamation of a number of components.
|
||||
For example, for a webserver that shows the current humidity, there could be:
|
||||
|
||||
- The ESP32 base libraries (libc, ROM bindings, etc)
|
||||
- The ESP-IDF base libraries (libc, ROM bindings, etc)
|
||||
- The WiFi drivers
|
||||
- A TCP/IP stack
|
||||
- The FreeRTOS operating system
|
||||
@@ -61,7 +63,7 @@ The ``idf.py`` command line tool provides a front-end for easily managing your p
|
||||
|
||||
- CMake_, which configures the project to be built
|
||||
- A command line build tool (either Ninja_ build or `GNU Make`)
|
||||
- `esptool.py`_ for flashing ESP32.
|
||||
- `esptool.py`_ for flashing the target.
|
||||
|
||||
The :ref:`getting started guide <get-started-configure>` contains a brief introduction to how to set up ``idf.py`` to configure, build, and flash projects.
|
||||
|
||||
@@ -80,10 +82,10 @@ Type ``idf.py --help`` for a list of commands. Here are a summary of the most us
|
||||
Building is incremental so if no source files or configuration has changed since the last build, nothing will be done.
|
||||
- ``idf.py clean`` will "clean" the project by deleting build output files from the build directory, forcing a "full rebuild" the next time the project is built. Cleaning doesn't delete CMake configuration output and some other files.
|
||||
- ``idf.py fullclean`` will delete the entire "build" directory contents. This includes all CMake configuration output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively deletes *all* files in the build directory, so use with care. Project configuration is not deleted.
|
||||
- ``idf.py flash`` will automatically build the project if necessary, and then flash it to an ESP32. The ``-p`` and ``-b`` options can be used to set serial port name and flasher baud rate, respectively.
|
||||
- ``idf.py monitor`` will display serial output from the ESP32. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor. See :doc:`tools/idf-monitor` for more details about using the monitor.
|
||||
- ``idf.py flash`` will automatically build the project if necessary, and then flash it to the target. The ``-p`` and ``-b`` options can be used to set serial port name and flasher baud rate, respectively.
|
||||
- ``idf.py monitor`` will display serial output from the target. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor. See :doc:`tools/idf-monitor` for more details about using the monitor.
|
||||
|
||||
Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the ESP32 before running the serial monitor.
|
||||
Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the target before running the serial monitor.
|
||||
|
||||
For commands that are not known to ``idf.py`` an attempt to execute them as a build system target will be made.
|
||||
|
||||
@@ -95,8 +97,8 @@ Advanced Commands
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
- ``idf.py app``, ``idf.py bootloader``, ``idf.py partition_table`` can be used to build only the app, bootloader, or partition table from the project as applicable.
|
||||
- There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the ESP32.
|
||||
- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the ESP32's entire flash chip.
|
||||
- There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the target.
|
||||
- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the target's entire flash chip.
|
||||
- ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively. If you define variable ``-DOUTPUT_JSON=1`` when running CMake (or ``idf.py``), the output will be formatted as JSON not as human readable text.
|
||||
- ``idf.py reconfigure`` re-runs CMake_ even if it doesn't seem to need re-running. This isn't necessary during normal usage, but can be useful after adding/removing files from the source tree, or when modifying CMake cache variables. For example, ``idf.py -DNAME='VALUE' reconfigure`` can be used to set variable ``NAME`` in CMake cache to value ``VALUE``.
|
||||
|
||||
@@ -883,6 +885,8 @@ the ESP-IDF build system entirely by using a CMake feature called ExternalProjec
|
||||
- The second set of commands adds a library target, which points to the "imported" library file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is.
|
||||
- Finally, the generated library is added to `ADDITIONAL_MAKE_CLEAN_FILES`_. This means ``make clean`` will delete this library. (Note that the other object files from the build won't be deleted.)
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. note:: When using an external build process with PSRAM, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag.
|
||||
|
||||
.. _ADDITIONAL_MAKE_CLEAN_FILES_note:
|
||||
@@ -1108,7 +1112,10 @@ It is possible to do so by using the :ref:`build system APIs provided<cmake_buil
|
||||
The example in :example:`build_system/cmake/idf_as_lib` demonstrates the creation of an application equivalent to :example:`hello world application <get-started/hello_world>`
|
||||
using a custom CMake project.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. note:: The IDF build system can only set compiler flags for source files that it builds. When an external CMakeLists.txt file is used and PSRAM is enabled, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag.
|
||||
|
||||
.. _cmake_buildsystem_api:
|
||||
|
||||
ESP-IDF CMake Build System API
|
||||
|
||||
@@ -16,7 +16,7 @@ Line editing
|
||||
|
||||
Line editing feature lets users compose commands by typing them, erasing symbols using 'backspace' key, navigating within the command using left/right keys, navigating to previously typed commands using up/down keys, and performing autocompletion using 'tab' key.
|
||||
|
||||
.. note:: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running get_started/console example instead of a command prompt (``[esp32]>``), it means that the serial monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and idf_monitor.py (which can be invoked using ``idf.py monitor`` from project directory).
|
||||
.. note:: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running get_started/console example instead of a command prompt (``[{IDF_TARGET_PATH_NAME}]>``), it means that the serial monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and idf_monitor.py (which can be invoked using ``idf.py monitor`` from project directory).
|
||||
|
||||
Here is an overview of functions provided by `linenoise`_ library.
|
||||
|
||||
|
||||
@@ -1,9 +1,15 @@
|
||||
ESP32 Core Dump
|
||||
===============
|
||||
Core Dump
|
||||
=========
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
.. note::
|
||||
|
||||
The python utility does not currently support ESP32-S2
|
||||
|
||||
ESP-IDF provides support to generate core dumps on unrecoverable software errors. This useful technique allows post-mortem analysis of software state at the moment of failure.
|
||||
Upon the crash system enters panic state, prints some information and halts or reboots depending configuration. User can choose to generate core dump in order to analyse
|
||||
the reason of failure on PC later on. Core dump contains snapshots of all tasks in the system at the moment of failure. Snapshots include tasks control blocks (TCB) and stacks.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
Deep Sleep Wake Stubs
|
||||
=====================
|
||||
|
||||
ESP32 supports running a "deep sleep wake stub" when coming out of deep sleep. This function runs immediately as soon as the chip wakes up - before any normal initialisation, bootloader, or ESP-IDF code has run. After the wake stub runs, the SoC can go back to sleep or continue to start ESP-IDF normally.
|
||||
{IDF_TARGET_NAME} supports running a "deep sleep wake stub" when coming out of deep sleep. This function runs immediately as soon as the chip wakes up - before any normal initialisation, bootloader, or ESP-IDF code has run. After the wake stub runs, the SoC can go back to sleep or continue to start ESP-IDF normally.
|
||||
|
||||
Deep sleep wake stub code is loaded into "RTC Fast Memory" and any data which it uses must also be loaded into RTC memory. RTC memory regions hold their contents during deep sleep.
|
||||
|
||||
@@ -33,7 +33,7 @@ It is not necessary to implement ``esp_wake_deep_sleep()`` in your app in order
|
||||
|
||||
If you want to swap between different deep sleep stubs at runtime, it is also possible to do this by calling the ``esp_set_deep_sleep_wake_stub()`` function. This is not necessary if you only use the default ``esp_wake_deep_sleep()`` function.
|
||||
|
||||
All of these functions are declared in the ``esp_deepsleep.h`` header under components/esp32.
|
||||
All of these functions are declared in the ``esp_sleep.h`` header under components/{IDF_TARGET_PATH_NAME}.
|
||||
|
||||
Loading Code Into RTC Memory
|
||||
----------------------------
|
||||
@@ -69,9 +69,11 @@ The first way is to use the ``RTC_DATA_ATTR`` and ``RTC_RODATA_ATTR`` to specify
|
||||
ets_printf(fmt_str, wake_count++);
|
||||
}
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
The RTC memory area where this data will be placed can be configured via menuconfig option named ``CONFIG_ESP32_RTCDATA_IN_FAST_MEM``. This option allows to keep slow memory area for ULP programs and once it is enabled the data marked with ``RTC_DATA_ATTR`` and ``RTC_RODATA_ATTR`` are placed in the RTC fast memory segment otherwise it goes to RTC slow memory (default option). This option depends on the ``CONFIG_FREERTOS_UNICORE`` because RTC fast memory can be accessed only by PRO_CPU.
|
||||
|
||||
The similar attributes ``RTC_FAST_ATTR`` and ``RTC_SLOW_ATTR`` can be used to specify data that will be force placed into RTC_FAST and RTC_SLOW memory respectively. Any access to data marked with ``RTC_FAST_ATTR`` is allowed by PRO_CPU only and it is responsibility of user to make sure about it.
|
||||
The attributes ``RTC_FAST_ATTR`` and ``RTC_SLOW_ATTR`` can be used to specify data that will be force placed into RTC_FAST and RTC_SLOW memory respectively. Any access to data marked with ``RTC_FAST_ATTR`` is allowed by PRO_CPU only and it is responsibility of user to make sure about it.
|
||||
|
||||
Unfortunately, any string constants used in this way must be declared as arrays and marked with RTC_RODATA_ATTR, as shown in the example above.
|
||||
|
||||
|
||||
@@ -527,7 +527,7 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m
|
||||
3.2 Why is the Wi-Fi throughput so low when Wi-Fi and ESP-BLE-MESH coexist?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The `ESP32-DevKitC <../../hw-reference/get-started-devkitc>`_ board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1Mbps.
|
||||
The `ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>`_ board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1Mbps.
|
||||
|
||||
And some configurations in menuconfig shall be enabled to support PSRAM.
|
||||
|
||||
@@ -647,8 +647,8 @@ You can find meaning of errors or warnings when they appear at the bottom of ESP
|
||||
|
||||
The examples use :cpp:func:`ESP_LOG_BUFFER_HEX` to print the message context while the ESP-BLE-MESH protocol stack uses :cpp:func:`bt_hex`.
|
||||
|
||||
7.2 Which API can be used to restart ESP32?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
7.2 Which API can be used to restart {IDF_TARGET_NAME}?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The API :cpp:func:`esp_restart`.
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.
|
||||
|
||||
.. note::
|
||||
|
||||
If you are looking for Wi-Fi based implementation of mesh for ESP32, please check another product by Espressif called ESP-MESH. For more information and documentation see :doc:`ESP-MESH <../../api-reference/network/esp_mesh>`.
|
||||
If you are looking for Wi-Fi based implementation of mesh for {IDF_TARGET_NAME}, please check another product by Espressif called ESP-MESH. For more information and documentation see :doc:`ESP-MESH <../../api-reference/network/esp_mesh>`.
|
||||
|
||||
|
||||
.. _getting-started-with-ble-mesh:
|
||||
@@ -26,7 +26,7 @@ ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.
|
||||
Getting Started with ESP-BLE-MESH
|
||||
=================================
|
||||
|
||||
This section is intended to help you get started with ESP-BLE-MESH for the hardware based on the ESP32 chip by Espressif.
|
||||
This section is intended to help you get started with ESP-BLE-MESH for the hardware based on the {IDF_TARGET_NAME} chip by Espressif.
|
||||
|
||||
We are going to demonstrate process of setting and operation of a small ESP-BLE-MESH network of three nodes. This process will cover device provisioning and node configuration, and then sending on/off commands to Generic OnOff Server Models on specific nodes.
|
||||
|
||||
@@ -38,14 +38,14 @@ What You Need
|
||||
|
||||
Hardware:
|
||||
|
||||
* Three ESP32 boards, see :ref:`options <get-started-ble-mesh-check-hardware>`.
|
||||
* Three {IDF_TARGET_NAME} boards, see :ref:`options <get-started-ble-mesh-check-hardware>`.
|
||||
* USB cables to connect the boards.
|
||||
* Computer configured with ESP-IDF.
|
||||
* Mobile phone or tablet running Android or iOS.
|
||||
|
||||
Software:
|
||||
|
||||
* Example application :example:`bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server` code to load to the ESP32 boards.
|
||||
* Example application :example:`bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server` code to load to the ${IDF_TARGET_NAME} boards.
|
||||
* Mobile App: **nRF Mesh** for Android or iOS. Optionally you can use some other Apps:
|
||||
|
||||
- `EspBleMesh <https://github.com/EspressifApp/EspBLEMeshForAndroid/releases/tag/v1.0.0>`_ Android App
|
||||
@@ -219,7 +219,7 @@ ESP-BLE-MESH Examples
|
||||
|
||||
* ESP-BLE-MESH Fast Provisioning - :example:`Client <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_client/tutorial/BLE_Mesh_Fast_Prov_Client_Example_Walkthrough.md>` and :example:`Server <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_server/tutorial/BLE_Mesh_Fast_Prov_Server_Example_Walkthrough.md>` - this example is used for showing how fast provisioning can be used in order to create a mesh network. It takes no more than 60 seconds to provision 100 devices, see :example:`example client code <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_client>` and :example:`example server code <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_server>`.
|
||||
|
||||
* :example:`ESP-BLE-MESH and Wi-Fi Coexistence <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist/tutorial/BLE_Mesh_WiFi_Coexist_Example_Walkthrough.md>` - an example that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of ESP32. Simply put, users can use the Wi-Fi while operating Bluetooth, see :example:`example code <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist>`.
|
||||
* :example:`ESP-BLE-MESH and Wi-Fi Coexistence <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist/tutorial/BLE_Mesh_WiFi_Coexist_Example_Walkthrough.md>` - an example that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of {IDF_TARGET_NAME}. Simply put, users can use the Wi-Fi while operating Bluetooth, see :example:`example code <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist>`.
|
||||
|
||||
* ESP-BLE-MESH Node Console - an example that implements BLE Mesh node basic features. Within this example a node can be scanned and provisioned by Provisioner and reply to get/set message from Provisioner, see :example:`example node code <bluetooth/esp_ble_mesh/ble_mesh_console/ble_mesh_node>` and :example:`example Provisioner code <bluetooth/esp_ble_mesh/ble_mesh_console/ble_mesh_provisioner>`.
|
||||
|
||||
|
||||
@@ -9,15 +9,17 @@ Support for external RAM
|
||||
Introduction
|
||||
============
|
||||
|
||||
ESP32 has a few hundred kilobytes of internal RAM, residing on the same die as the rest of the chip components. It can be insufficient for some purposes, so ESP32 has the ability to also use up to 4 MB of external SPI RAM memory. The external memory is incorporated in the memory map and, with certain restrictions, is usable in the same way as internal data RAM.
|
||||
{IDF_TARGET_NAME} has a few hundred kilobytes of internal RAM, residing on the same die as the rest of the chip components. It can be insufficient for some purposes, so {IDF_TARGET_NAME} has the ability to also use up to 4 MB of external SPI RAM memory. The external memory is incorporated in the memory map and, with certain restrictions, is usable in the same way as internal data RAM.
|
||||
|
||||
|
||||
Hardware
|
||||
========
|
||||
|
||||
ESP32 supports SPI PSRAM connected in parallel with the SPI flash chip. While ESP32 is capable of supporting several types of RAM chips, the ESP32 SDK only supports the ESP-PSRAM32 chip at the moment.
|
||||
{IDF_TARGET_NAME} supports SPI PSRAM connected in parallel with the SPI flash chip. While {IDF_TARGET_NAME} is capable of supporting several types of RAM chips, ESP-IDF only supports the ESP-PSRAM32 chip at the moment.
|
||||
|
||||
The ESP-PSRAM32 chip is a 1.8 V device which can only be used in parallel with a 1.8 V flash component. Make sure to either set the MTDI pin to a high signal level on bootup, or program ESP32 eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip.
|
||||
The ESP-PSRAM32 chip is a 1.8 V device which can only be used in parallel with a 1.8 V flash component. Make sure to either set the MTDI pin to a high signal level on bootup, or program {IDF_TARGET_NAME} eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
To connect the ESP-PSRAM32 chip to ESP32D0W*, connect the following signals:
|
||||
|
||||
@@ -31,7 +33,8 @@ To connect the ESP-PSRAM32 chip to ESP32D0W*, connect the following signals:
|
||||
|
||||
Connections for ESP32D2W* chips are TBD.
|
||||
|
||||
.. NOTE::
|
||||
.. note::
|
||||
|
||||
Espressif produces the line of ESP32-WROVER modules which contain ESP32, 1.8 V flash, and ESP-PSRAM32. These modules are ready to be mounted on an end product PCB.
|
||||
|
||||
.. _external_ram_config:
|
||||
@@ -50,10 +53,10 @@ ESP-IDF fully supports the use of external memory in applications. Once the exte
|
||||
.. _external_ram_config_memory_map:
|
||||
|
||||
|
||||
Integrate RAM into the ESP32 memory map
|
||||
---------------------------------------
|
||||
Integrate RAM into the {IDF_TARGET_NAME} memory map
|
||||
---------------------------------------------------
|
||||
|
||||
Select this option by choosing "Integrate RAM into ESP32 memory map" from :ref:`CONFIG_SPIRAM_USE`.
|
||||
Select this option by choosing "Integrate RAM into memory map" from :ref:`CONFIG_SPIRAM_USE`.
|
||||
|
||||
This is the most basic option for external SPI RAM integration. Most likely, you will need another, more advanced option.
|
||||
|
||||
@@ -119,36 +122,12 @@ External RAM use has the following restrictions:
|
||||
* When flash cache is disabled (for example, if the flash is being written to), the external RAM also becomes inaccessible; any reads from or writes to it will lead to an illegal cache access exception. This is also the reason why ESP-IDF does not by default allocate any task stacks in external RAM (see below).
|
||||
* External RAM cannot be used as a place to store DMA transaction descriptors or as a buffer for a DMA transfer to read from or write into. Any buffers that will be used in combination with DMA must be allocated using ``heap_caps_malloc(size, MALLOC_CAP_DMA)`` and can be freed using a standard ``free()`` call.
|
||||
* External RAM uses the same cache region as the external flash. This means that frequently accessed variables in external RAM can be read and modified almost as quickly as in internal ram. However, when accessing large chunks of data (>32 KB), the cache can be insufficient, and speeds will fall back to the access speed of the external RAM. Moreover, accessing large chunks of data can "push out" cached flash, possibly making the execution of code slower afterwards.
|
||||
* External RAM cannot be used as task stack memory. Due to this, :cpp:func:`xTaskCreate` and similar functions will always allocate internal memory for stack and task TCBs, and functions such as :cpp:func:`xTaskCreateStatic` will check if the buffers passed are internal. However, for tasks not calling on code in ROM in any way, directly or indirectly, the menuconfig option :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` will eliminate the check in xTaskCreateStatic, allowing a task's stack to be in external RAM. Using this is not advised, however.
|
||||
* External RAM cannot be used as task stack memory. Due to this, :cpp:func:`xTaskCreate` and similar functions will always allocate internal memory for stack and task TCBs, and functions such as :cpp:func:`xTaskCreateStatic` will check if the buffers passed are internal.
|
||||
* By default, failure to initialize external RAM will cause the ESP-IDF startup to abort. This can be disabled by enabling the config item :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND`. If :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` is enabled, the option to ignore failure is not available as the linker will have assigned symbols to external memory addresses at link time.
|
||||
* When used at 80 MHz clock speed, external RAM must also occupy either the HSPI or VSPI bus. Select which SPI host will be used by :ref:`CONFIG_SPIRAM_OCCUPY_SPI_HOST`.
|
||||
|
||||
|
||||
Chip revisions
|
||||
==============
|
||||
|
||||
There are some issues with certain revisions of ESP32 that have repercussions for use with external RAM. The issues are documented in the ESP32 ECO_ document. In particular, ESP-IDF handles the bugs mentioned in the following ways:
|
||||
|
||||
|
||||
ESP32 rev v0
|
||||
------------
|
||||
ESP-IDF has no workaround for the bugs in this revision of silicon, and it cannot be used to map external PSRAM into ESP32's main memory map.
|
||||
|
||||
|
||||
ESP32 rev v1
|
||||
------------
|
||||
The bugs in this revision of silicon cause issues if certain sequences of machine instructions operate on external memory. (ESP32 ECO 3.2). As a workaround, the GCC compiler received the flag ``-mfix-esp32-psram-cache-issue`` to filter these sequences and only output the code that can safely be executed. Enable this flag by checking :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`.
|
||||
|
||||
Aside from linking to a recompiled version of Newlib with the additional flag, ESP-IDF also does the following:
|
||||
|
||||
- Avoids using some ROM functions
|
||||
- Allocates static memory for the WiFi stack
|
||||
|
||||
|
||||
.. _ECO: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf
|
||||
|
||||
|
||||
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. include:: inc/external-ram-esp32-notes.rst
|
||||
|
||||
.. _ESP32 ECO: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf
|
||||
|
||||
@@ -38,29 +38,31 @@ For some of the system level checks (interrupt watchdog, cache access error), th
|
||||
|
||||
In all cases, error cause will be printed in parens. See `Guru Meditation Errors`_ for a list of possible error causes.
|
||||
|
||||
Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32_PANIC` configuration choice. The available options are:
|
||||
Subsequent behavior of the panic handler can be set using :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC` configuration choice. The available options are:
|
||||
|
||||
- Print registers and reboot (``CONFIG_ESP32_PANIC_PRINT_REBOOT``) — default option.
|
||||
- Print registers and reboot — default option.
|
||||
|
||||
This will print register values at the point of the exception, print the backtrace, and restart the chip.
|
||||
|
||||
- Print registers and halt (``CONFIG_ESP32_PANIC_PRINT_HALT``)
|
||||
- Print registers and halt
|
||||
|
||||
Similar to the above option, but halt instead of rebooting. External reset is required to restart the program.
|
||||
|
||||
- Silent reboot (``CONFIG_ESP32_PANIC_SILENT_REBOOT``)
|
||||
- Silent reboot
|
||||
|
||||
Don't print registers or backtrace, restart the chip immediately.
|
||||
|
||||
- Invoke GDB Stub (``CONFIG_ESP32_PANIC_GDBSTUB``)
|
||||
- Invoke GDB Stub
|
||||
|
||||
Start GDB server which can communicate with GDB over console UART port. See `GDB Stub`_ for more details.
|
||||
|
||||
Behavior of panic handler is affected by two other configuration options.
|
||||
|
||||
- If :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used.
|
||||
- If :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used.
|
||||
|
||||
- If :doc:`Core Dump <core_dump>` feature is enabled (``CONFIG_ESP32_ENABLE_COREDUMP_TO_FLASH`` or ``CONFIG_ESP32_ENABLE_COREDUMP_TO_UART`` options), then system state (task stacks and registers) will be dumped either to Flash or UART, for later analysis.
|
||||
- If :doc:`Core Dump <core_dump>` feature is enabled, then system state (task stacks and registers) will be dumped either to Flash or UART, for later analysis.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
- If :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM` is disabled (disabled by default), the panic handler code is placed in flash memory not IRAM. This means that if ESP-IDF crashes while flash cache is disabled, the panic handler will automatically re-enable flash cache before running GDB Stub or Core Dump. This adds some minor risk, if the flash cache status is also corrupted during the crash.
|
||||
|
||||
@@ -114,7 +116,7 @@ The following diagram illustrates panic handler behavior:
|
||||
Register Dump and Backtrace
|
||||
---------------------------
|
||||
|
||||
Unless ``CONFIG_ESP32_PANIC_SILENT_REBOOT`` option is enabled, panic handler prints some of the CPU registers, and the backtrace, to the console::
|
||||
Unless ``CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC_SILENT_REBOOT`` option is enabled, panic handler prints some of the CPU registers, and the backtrace, to the console::
|
||||
|
||||
Core 0 register dump:
|
||||
PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030
|
||||
@@ -151,14 +153,14 @@ If :doc:`IDF Monitor <tools/idf-monitor>` is used, Program Counter values will b
|
||||
Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050
|
||||
0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36
|
||||
|
||||
0x400d0802: main_task at /Users/user/esp/esp-idf/components/esp32/cpu_start.c:470
|
||||
0x400d0802: main_task at /Users/user/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/cpu_start.c:470
|
||||
|
||||
To find the location where a fatal error has happened, look at the lines which follow the "Backtrace" line. Fatal error location is the top line, and subsequent lines show the call stack.
|
||||
|
||||
GDB Stub
|
||||
--------
|
||||
|
||||
If ``CONFIG_ESP32_PANIC_GDBSTUB`` option is enabled, panic handler will not reset the chip when fatal error happens. Instead, it will start GDB remote protocol server, commonly referred to as GDB Stub. When this happens, GDB instance running on the host computer can be instructed to connect to the ESP32 UART port.
|
||||
If ``CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC_GDBSTUB`` option is enabled, panic handler will not reset the chip when fatal error happens. Instead, it will start GDB remote protocol server, commonly referred to as GDB Stub. When this happens, GDB instance running on the host computer can be instructed to connect to the {IDF_TARGET_NAME} UART port.
|
||||
|
||||
If :doc:`IDF Monitor <tools/idf-monitor>` is used, GDB is started automatically when GDB Stub prompt is detected on the UART. The output would look like this::
|
||||
|
||||
@@ -169,7 +171,7 @@ If :doc:`IDF Monitor <tools/idf-monitor>` is used, GDB is started automatically
|
||||
This is free software: you are free to change and redistribute it.
|
||||
There is NO WARRANTY, to the extent permitted by law. Type "show copying"
|
||||
and "show warranty" for details.
|
||||
This GDB was configured as "--host=x86_64-build_apple-darwin16.3.0 --target=xtensa-esp32-elf".
|
||||
This GDB was configured as "--host=x86_64-build_apple-darwin16.3.0 --target=xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf".
|
||||
Type "show configuration" for configuration details.
|
||||
For bug reporting instructions, please see:
|
||||
<http://www.gnu.org/software/gdb/bugs/>.
|
||||
@@ -210,7 +212,7 @@ Most common reasons for this error include:
|
||||
|
||||
- Application has reconfigured SPI flash pins as some other function (GPIO, UART, etc.). Consult Hardware Design Guidelines and the Datasheet for the chip or module for details about SPI flash pins.
|
||||
|
||||
- Some external device was accidentally connected to SPI flash pins, and has interfered with communication between ESP32 and SPI flash.
|
||||
- Some external device was accidentally connected to SPI flash pins, and has interfered with communication between {IDF_TARGET_NAME} and SPI flash.
|
||||
|
||||
|
||||
InstrFetchProhibited
|
||||
@@ -265,7 +267,8 @@ Other Fatal Errors
|
||||
Brownout
|
||||
^^^^^^^^
|
||||
|
||||
ESP32 has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_ESP32_BROWNOUT_DET` and :ref:`CONFIG_ESP32_BROWNOUT_DET_LVL_SEL` options.
|
||||
{IDF_TARGET_NAME} has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_BROWNOUT_DET` and :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_BROWNOUT_DET_LVL_SEL` options.
|
||||
|
||||
When brownout detector triggers, the following message is printed::
|
||||
|
||||
Brownout detector was triggered
|
||||
|
||||
@@ -4,6 +4,8 @@ ESP-IDF FreeRTOS SMP Changes
|
||||
Overview
|
||||
--------
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
The vanilla FreeRTOS is designed to run on a single core. However the ESP32 is
|
||||
dual core containing a Protocol CPU (known as **CPU 0** or **PRO_CPU**) and an
|
||||
Application CPU (known as **CPU 1** or **APP_CPU**). The two cores are
|
||||
@@ -23,6 +25,8 @@ see :doc:`ESP-IDF FreeRTOS Additions<../api-reference/system/freertos_additions>
|
||||
port of FreeRTOS v8.2.0, a number of FreeRTOS v9.0.0 features have been backported
|
||||
to ESP-IDF.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
:ref:`tasks-and-task-creation`: Use :cpp:func:`xTaskCreatePinnedToCore` or
|
||||
:cpp:func:`xTaskCreateStaticPinnedToCore` to create tasks in ESP-IDF FreeRTOS. The
|
||||
last parameter of the two functions is ``xCoreID``. This parameter specifies
|
||||
@@ -53,14 +57,14 @@ scheduler and interrupts of the calling core. However the other core is left
|
||||
unaffected. If the other core attemps to take same mutex, it will spin until
|
||||
the calling core has released the mutex by exiting the critical section.
|
||||
|
||||
:ref:`floating-points`: The ESP32 supports hardware acceleration of single
|
||||
:ref:`floating-points`: The {IDF_TARGET_NAME} supports hardware acceleration of single
|
||||
precision floating point arithmetic (``float``). However the use of hardware
|
||||
acceleration leads to some behavioral restrictions in ESP-IDF FreeRTOS.
|
||||
Therefore, tasks that utilize ``float`` will automatically be pinned to a core if
|
||||
not done so already. Furthermore, ``float`` cannot be used in interrupt service
|
||||
routines.
|
||||
|
||||
:ref:`task-deletion`: Task deletion behavior has been backported from FreeRTOS
|
||||
`Task Deletion`_: Task deletion behavior has been backported from FreeRTOS
|
||||
v9.0.0 and modified to be SMP compatible. Task memory will be freed immediately
|
||||
when :cpp:func:`vTaskDelete` is called to delete a task that is not currently running
|
||||
and not pinned to the other core. Otherwise, freeing of task memory will still
|
||||
@@ -134,6 +138,8 @@ the function :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback` can als
|
||||
called.
|
||||
|
||||
|
||||
|
||||
|
||||
.. _tasks-and-task-creation:
|
||||
|
||||
Tasks and Task Creation
|
||||
@@ -349,6 +355,8 @@ context switches and servicing of ISRs during a critical section. Therefore,
|
||||
critical sections are used as a valid protection method against simultaneous
|
||||
access in vanilla FreeRTOS.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
On the other hand, the ESP32 has no hardware method for cores to disable each
|
||||
other’s interrupts. Calling ``portDISABLE_INTERRUPTS()`` will have no effect on
|
||||
the interrupts of the other core. Therefore, disabling interrupts is **NOT**
|
||||
@@ -356,8 +364,13 @@ a valid protection method against simultaneous access to shared data as it
|
||||
leaves the other core free to access the data even if the current core has
|
||||
disabled its own interrupts.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
ESP-IDF contains some modifications to work with dual core concurrency,
|
||||
and the dual core API is used even on a single core only chip.
|
||||
|
||||
For this reason, ESP-IDF FreeRTOS implements critical sections using special mutexes,
|
||||
referred by portMUX_Type objects on top of specific ESP32 spinlock component
|
||||
referred by portMUX_Type objects on top of specific spinlock component
|
||||
and calls to enter or exit a critical must provide a spinlock object that
|
||||
is associated with a shared resource requiring access protection.
|
||||
When entering a critical section in ESP-IDF FreeRTOS, the calling core will disable
|
||||
@@ -394,15 +407,12 @@ spinlock is provided upon entering and exiting, the type of call should not
|
||||
matter.
|
||||
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. _floating-points:
|
||||
|
||||
Floating Point Aritmetic
|
||||
------------------------
|
||||
|
||||
The ESP32 supports hardware acceleration of single precision floating point
|
||||
arithmetic (``float``) via Floating Point Units (FPU, also known as coprocessors)
|
||||
attached to each core. The use of the FPUs imposes some behavioral restrictions
|
||||
on ESP-IDF FreeRTOS.
|
||||
Floating Point Arithmetic
|
||||
-------------------------
|
||||
|
||||
ESP-IDF FreeRTOS implements Lazy Context Switching for FPUs. In other words,
|
||||
the state of a core's FPU registers are not immediately saved when a context
|
||||
@@ -419,7 +429,6 @@ behavioral restrictions with regards to ``float`` do not apply to ``double``. No
|
||||
that due to the lack of hardware acceleration, ``double`` operations may consume
|
||||
significantly larger amount of CPU time in comparison to ``float``.
|
||||
|
||||
|
||||
.. _task-deletion:
|
||||
|
||||
Task Deletion
|
||||
@@ -452,7 +461,7 @@ occur.
|
||||
ESP-IDF FreeRTOS provides the added feature of Deletion Callbacks. Deletion
|
||||
Callbacks are called automatically during task deletion to free memory pointed
|
||||
to by TLSP. Each TLSP can have its own Deletion Callback. Note that due to the
|
||||
to :ref:`task-deletion` behavior, there can be instances where Deletion
|
||||
to `Task Deletion`_ behavior, there can be instances where Deletion
|
||||
Callbacks are called in the context of the Idle Tasks. Therefore Deletion
|
||||
Callbacks **should never attempt to block** and critical sections should be kept
|
||||
as short as possible to minimize priority inversion.
|
||||
@@ -489,7 +498,7 @@ ESP-IDF FreeRTOS configurations, see :doc:`FreeRTOS <../api-reference/kconfig>`
|
||||
:ref:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF FreeRTOS only
|
||||
on **PRO_CPU**. Note that this is **not equivalent to running vanilla
|
||||
FreeRTOS**. Behaviors of multiple components in ESP-IDF will be modified such
|
||||
as :component_file:`esp32/cpu_start.c`. For more details regarding the
|
||||
as :component_file:`{IDF_TARGET_PATH_NAME}/cpu_start.c`. For more details regarding the
|
||||
effects of running ESP-IDF FreeRTOS on a single core, search for
|
||||
occurences of ``CONFIG_FREERTOS_UNICORE`` in the ESP-IDF components.
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ This process is explained in detail in the following sections.
|
||||
First stage bootloader
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
After SoC reset, PRO CPU will start running immediately, executing reset vector code, while APP CPU will be held in reset. During startup process, PRO CPU does all the initialization. APP CPU reset is de-asserted in the ``call_start_cpu0`` function of application startup code. Reset vector code is located at address 0x40000400 in the mask ROM of the ESP32 chip and can not be modified.
|
||||
After SoC reset, PRO CPU will start running immediately, executing reset vector code, while APP CPU will be held in reset. During startup process, PRO CPU does all the initialization. APP CPU reset is de-asserted in the ``call_start_cpu0`` function of application startup code. Reset vector code is located at address 0x40000400 in the mask ROM of the {IDF_TARGET_NAME} chip and can not be modified.
|
||||
|
||||
Startup code called from the reset vector determines the boot mode by checking ``GPIO_STRAP_REG`` register for bootstrap pin states. Depending on the reset reason, the following takes place:
|
||||
|
||||
@@ -35,7 +35,7 @@ Application binary image is loaded from flash starting at address 0x1000. First
|
||||
Second stage bootloader
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In ESP-IDF, the binary image which resides at offset 0x1000 in flash is the second stage bootloader. Second stage bootloader source code is available in components/bootloader directory of ESP-IDF. Note that this arrangement is not the only one possible with the ESP32 chip. It is possible to write a fully featured application which would work when flashed to offset 0x1000, but this is out of scope of this document. Second stage bootloader is used in ESP-IDF to add flexibility to flash layout (using partition tables), and allow for various flows associated with flash encryption, secure boot, and over-the-air updates (OTA) to take place.
|
||||
In ESP-IDF, the binary image which resides at offset 0x1000 in flash is the second stage bootloader. Second stage bootloader source code is available in components/bootloader directory of ESP-IDF. Note that this arrangement is not the only one possible with the {IDF_TARGET_NAME} chip. It is possible to write a fully featured application which would work when flashed to offset 0x1000, but this is out of scope of this document. Second stage bootloader is used in ESP-IDF to add flexibility to flash layout (using partition tables), and allow for various flows associated with flash encryption, secure boot, and over-the-air updates (OTA) to take place.
|
||||
|
||||
When the first stage bootloader is finished checking and loading the second stage bootloader, it jumps to the second stage bootloader entry point found in the binary image header.
|
||||
|
||||
@@ -48,9 +48,9 @@ Currently it is not possible to add application-defined hooks to the bootloader
|
||||
Application startup
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
ESP-IDF application entry point is ``call_start_cpu0`` function found in ``components/esp32/cpu_start.c``. Two main things this function does are to enable heap allocator and to make APP CPU jump to its entry point, ``call_start_cpu1``. The code on PRO CPU sets the entry point for APP CPU, de-asserts APP CPU reset, and waits for a global flag to be set by the code running on APP CPU, indicating that it has started. Once this is done, PRO CPU jumps to ``start_cpu0`` function, and APP CPU jumps to ``start_cpu1`` function.
|
||||
ESP-IDF application entry point is ``call_start_cpu0`` function found in ``components/{IDF_TARGET_PATH_NAME}/cpu_start.c``. Two main things this function does are to enable heap allocator and to make APP CPU jump to its entry point, ``call_start_cpu1``. The code on PRO CPU sets the entry point for APP CPU, de-asserts APP CPU reset, and waits for a global flag to be set by the code running on APP CPU, indicating that it has started. Once this is done, PRO CPU jumps to ``start_cpu0`` function, and APP CPU jumps to ``start_cpu1`` function.
|
||||
|
||||
Both ``start_cpu0`` and ``start_cpu1`` are weak functions, meaning that they can be overridden in the application, if some application-specific change to initialization sequence is needed. Default implementation of ``start_cpu0`` enables or initializes components depending on choices made in ``menuconfig``. Please see source code of this function in ``components/esp32/cpu_start.c`` for an up to date list of steps performed. Note that any C++ global constructors present in the application will be called at this stage. Once all essential components are initialized, *main task* is created and FreeRTOS scheduler is started.
|
||||
Both ``start_cpu0`` and ``start_cpu1`` are weak functions, meaning that they can be overridden in the application, if some application-specific change to initialization sequence is needed. Default implementation of ``start_cpu0`` enables or initializes components depending on choices made in ``menuconfig``. Please see source code of this function in ``components/{IDF_TARGET_PATH_NAME}/cpu_start.c`` for an up to date list of steps performed. Note that any C++ global constructors present in the application will be called at this stage. Once all essential components are initialized, *main task* is created and FreeRTOS scheduler is started.
|
||||
|
||||
While PRO CPU does initialization in ``start_cpu0`` function, APP CPU spins in ``start_cpu1`` function, waiting for the scheduler to be started on the PRO CPU. Once the scheduler is started on the PRO CPU, code on the APP CPU starts the scheduler as well.
|
||||
|
||||
@@ -61,7 +61,7 @@ Main task is the task which runs ``app_main`` function. Main task stack size and
|
||||
Application memory layout
|
||||
-------------------------
|
||||
|
||||
ESP32 chip has flexible memory mapping features. This section describes how ESP-IDF uses these features by default.
|
||||
{IDF_TARGET_NAME} chip has flexible memory mapping features. This section describes how ESP-IDF uses these features by default.
|
||||
|
||||
Application code in ESP-IDF can be placed into one of the following memory regions.
|
||||
|
||||
@@ -85,7 +85,7 @@ Here are the cases when parts of application may or should be placed into IRAM.
|
||||
|
||||
- Interrupt handlers must be placed into IRAM if ``ESP_INTR_FLAG_IRAM`` is used when registering the interrupt handler. In this case, ISR may only call functions placed into IRAM or functions present in ROM. *Note 1:* all FreeRTOS APIs are currently placed into IRAM, so are safe to call from interrupt handlers. If the ISR is placed into IRAM, all constant data used by the ISR and functions called from ISR (including, but not limited to, ``const char`` arrays), must be placed into DRAM using ``DRAM_ATTR``.
|
||||
|
||||
- Some timing critical code may be placed into IRAM to reduce the penalty associated with loading the code from flash. ESP32 reads code and data from flash via a 32 kB cache. In some cases, placing a function into IRAM may reduce delays caused by a cache miss.
|
||||
- Some timing critical code may be placed into IRAM to reduce the penalty associated with loading the code from flash. {IDF_TARGET_NAME} reads code and data from flash via a 32 kB cache. In some cases, placing a function into IRAM may reduce delays caused by a cache miss.
|
||||
|
||||
IROM (code executed from Flash)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -4,7 +4,7 @@ High-Level Interrupts
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
The Xtensa architecture has support for 32 interrupts, divided over 8 levels, plus an assortment of exceptions. On the ESP32, the interrupt mux allows most interrupt sources to be routed to these interrupts using the :doc:`interrupt allocator <../api-reference/system/intr_alloc>`. Normally, interrupts will be written in C, but ESP-IDF allows high-level interrupts to be written in assembly as well, allowing for very low interrupt latencies.
|
||||
The Xtensa architecture has support for 32 interrupts, divided over 8 levels, plus an assortment of exceptions. On the {IDF_TARGET_NAME}, the interrupt mux allows most interrupt sources to be routed to these interrupts using the :doc:`interrupt allocator <../api-reference/system/intr_alloc>`. Normally, interrupts will be written in C, but ESP-IDF allows high-level interrupts to be written in assembly as well, allowing for very low interrupt latencies.
|
||||
|
||||
Interrupt Levels
|
||||
----------------
|
||||
@@ -31,8 +31,8 @@ Using these symbols is done by creating an assembly file (suffix .S) and definin
|
||||
rsr a0, EXCSAVE_5
|
||||
rfi 5
|
||||
|
||||
For a real-life example, see the :component_file:`{IDF_TARGET_PATH_NAME}/dport_panic_highint_hdl.S` file; the panic handler interrupt is implemented there.
|
||||
|
||||
For a real-life example, see the :component_file:`esp32/dport_panic_highint_hdl.S` file; the panic handler interrupt is implemented there.
|
||||
|
||||
Notes
|
||||
-----
|
||||
|
||||
23
docs/en/api-guides/inc/external-ram-esp32-notes.rst
Normal file
23
docs/en/api-guides/inc/external-ram-esp32-notes.rst
Normal file
@@ -0,0 +1,23 @@
|
||||
* Regarding stacks in PSRAM: For tasks not calling on code in ROM in any way, directly or indirectly, the menuconfig option :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` will eliminate the check in xTaskCreateStatic, allowing a task's stack to be in external RAM. Using this is not advised, however.
|
||||
* When used at 80 MHz clock speed, external RAM must also occupy either the HSPI or VSPI bus. Select which SPI host will be used by :ref:`CONFIG_SPIRAM_OCCUPY_SPI_HOST`.
|
||||
|
||||
|
||||
Chip revisions
|
||||
==============
|
||||
|
||||
There are some issues with certain revisions of ESP32 that have repercussions for use with external RAM. The issues are documented in the `ESP32 ECO`_ document. In particular, ESP-IDF handles the bugs mentioned in the following ways:
|
||||
|
||||
|
||||
ESP32 rev v0
|
||||
------------
|
||||
ESP-IDF has no workaround for the bugs in this revision of silicon, and it cannot be used to map external PSRAM into ESP32's main memory map.
|
||||
|
||||
|
||||
ESP32 rev v1
|
||||
------------
|
||||
The bugs in this revision of silicon cause issues if certain sequences of machine instructions operate on external memory. (`ESP32 ECO`_ 3.2). As a workaround, the GCC compiler received the flag ``-mfix-esp32-psram-cache-issue`` to filter these sequences and only output the code that can safely be executed. Enable this flag by checking :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`.
|
||||
|
||||
Aside from linking to a recompiled version of Newlib with the additional flag, ESP-IDF also does the following:
|
||||
|
||||
- Avoids using some ROM functions
|
||||
- Allocates static memory for the WiFi stack
|
||||
@@ -6,16 +6,16 @@ API Guides
|
||||
:maxdepth: 1
|
||||
|
||||
Application Level Tracing <app_trace>
|
||||
BluFi <blufi>
|
||||
:esp32: BluFi <blufi>
|
||||
Bootloader <bootloader>
|
||||
Build System <build-system>
|
||||
Build System (Legacy GNU Make) <build-system-legacy>
|
||||
:esp32: Build System (Legacy GNU Make) <build-system-legacy>
|
||||
Console Component <console>
|
||||
Deep Sleep Wake Stubs <deep-sleep-stub>
|
||||
Error Handling <error-handling>
|
||||
ESP-BLE-MESH <esp-ble-mesh/ble-mesh-index>
|
||||
:esp32: ESP-BLE-MESH <esp-ble-mesh/ble-mesh-index>
|
||||
ESP-MESH (Wi-Fi) <mesh>
|
||||
ESP32 Core Dump <core_dump>
|
||||
Core Dump <core_dump>
|
||||
Event Handling <event-handling>
|
||||
External SPI-connected RAM <external-ram>
|
||||
Fatal Errors <fatal-errors>
|
||||
@@ -27,13 +27,13 @@ API Guides
|
||||
Linker Script Generation <linker-script-generation>
|
||||
lwIP TCP/IP Stack <lwip>
|
||||
Partition Tables <partition-tables>
|
||||
RF Calibration <RF_calibration>
|
||||
:esp32: RF Calibration <RF_calibration>
|
||||
ROM debug console <romconsole>
|
||||
Secure Boot <../security/secure-boot>
|
||||
Thread Local Storage <thread-local-storage>
|
||||
Tools <tools/index>
|
||||
ULP Coprocessor <ulp>
|
||||
ULP Coprocessor (Legacy GNU Make) <ulp-legacy>
|
||||
Unit Testing (Legacy GNU Make) <unit-tests-legacy>
|
||||
:esp32: ULP Coprocessor (Legacy GNU Make) <ulp-legacy>
|
||||
Unit Testing <unit-tests>
|
||||
:esp32: Unit Testing (Legacy GNU Make) <unit-tests-legacy>
|
||||
WiFi Driver <wifi>
|
||||
|
||||
@@ -11,7 +11,7 @@ The following instructions are alternative to downloading binary OpenOCD from `E
|
||||
Download Sources of OpenOCD
|
||||
===========================
|
||||
|
||||
The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
|
||||
The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
|
||||
|
||||
cd ~/esp
|
||||
git clone --recursive https://github.com/espressif/openocd-esp32.git
|
||||
@@ -73,4 +73,4 @@ Once ``make`` process is successfully completed, the executable of OpenOCD will
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`.
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`.
|
||||
|
||||
@@ -10,7 +10,7 @@ The following instructions are alternative to downloading binary OpenOCD from `E
|
||||
Download Sources of OpenOCD
|
||||
===========================
|
||||
|
||||
The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
|
||||
The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
|
||||
|
||||
cd ~/esp
|
||||
git clone --recursive https://github.com/espressif/openocd-esp32.git
|
||||
@@ -50,6 +50,5 @@ Once ``make`` process is successfully completed, the executable of OpenOCD will
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`.
|
||||
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`.
|
||||
|
||||
@@ -29,7 +29,7 @@ Install packages that are required to compile OpenOCD::
|
||||
Download Sources of OpenOCD
|
||||
===========================
|
||||
|
||||
The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
|
||||
The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
|
||||
|
||||
cd ~/esp
|
||||
git clone --recursive https://github.com/espressif/openocd-esp32.git
|
||||
@@ -110,4 +110,4 @@ A complete described previously process is provided below for the faster executi
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`.
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`.
|
||||
|
||||
@@ -2,33 +2,53 @@ Configure Other JTAG Interface
|
||||
==============================
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Refer to section :ref:`jtag-debugging-selecting-jtag-adapter` for guidance what JTAG interface to select, so it is able to operate with OpenOCD and ESP32. Then follow three configuration steps below to get it working.
|
||||
Refer to section :ref:`jtag-debugging-selecting-jtag-adapter` for guidance what JTAG interface to select, so it is able to operate with OpenOCD and {IDF_TARGET_NAME}. Then follow three configuration steps below to get it working.
|
||||
|
||||
|
||||
Configure Hardware
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
1. Identify all pins / signals on JTAG interface and ESP32 board, that should be connected to establish communication.
|
||||
1. Identify all pins / signals on JTAG interface and {IDF_TARGET_NAME} board, that should be connected to establish communication.
|
||||
|
||||
+---+---------------+-------------+
|
||||
.. only:: esp32
|
||||
|
||||
+---+-----------------------+-------------+
|
||||
| | ESP32 Pin | JTAG Signal |
|
||||
+===+===============+=============+
|
||||
+===+=======================+=============+
|
||||
| 1 | CHIP_PU | TRST_N |
|
||||
+---+---------------+-------------+
|
||||
+---+-----------------------+-------------+
|
||||
| 2 | MTDO / GPIO15 | TDO |
|
||||
+---+---------------+-------------+
|
||||
+---+-----------------------+-------------+
|
||||
| 3 | MTDI / GPIO12 | TDI |
|
||||
+---+---------------+-------------+
|
||||
+---+-----------------------+-------------+
|
||||
| 4 | MTCK / GPIO13 | TCK |
|
||||
+---+---------------+-------------+
|
||||
+---+-----------------------+-------------+
|
||||
| 5 | MTMS / GPIO14 | TMS |
|
||||
+---+---------------+-------------+
|
||||
+---+-----------------------+-------------+
|
||||
| 6 | GND | GND |
|
||||
+---+---------------+-------------+
|
||||
+---+-----------------------+-------------+
|
||||
|
||||
2. Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation.
|
||||
.. only:: esp32s2
|
||||
|
||||
3. Connect identified pin / signals of ESP32 and JTAG interface.
|
||||
+---+-----------------------+-------------+
|
||||
| | ESP32-S2 Pin | JTAG Signal |
|
||||
+===+=======================+=============+
|
||||
| 1 | CHIP_PU | TRST_N |
|
||||
+---+-----------------------+-------------+
|
||||
| 2 | MTDO / GPIO40 | TDO |
|
||||
+---+-----------------------+-------------+
|
||||
| 3 | MTDI / GPIO41 | TDI |
|
||||
+---+-----------------------+-------------+
|
||||
| 4 | MTCK / GPIO39 | TCK |
|
||||
+---+-----------------------+-------------+
|
||||
| 5 | MTMS / GPIO42 | TMS |
|
||||
+---+-----------------------+-------------+
|
||||
| 6 | GND | GND |
|
||||
+---+-----------------------+-------------+
|
||||
|
||||
2. Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation.
|
||||
|
||||
3. Connect identified pin / signals of {IDF_TARGET_NAME} and JTAG interface.
|
||||
|
||||
|
||||
Configure Drivers
|
||||
@@ -39,7 +59,7 @@ You may need to install driver s/w to make JTAG work with computer. Refer to doc
|
||||
Connect
|
||||
^^^^^^^
|
||||
|
||||
Connect JTAG interface to the computer. Power on ESP32 and JTAG interface boards. Check if JTAG interface is visible by computer.
|
||||
Connect JTAG interface to the computer. Power on {IDF_TARGET_NAME} and JTAG interface boards. Check if JTAG interface is visible by computer.
|
||||
|
||||
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
|
||||
|
||||
@@ -8,7 +8,7 @@ All versions of ESP-WROVER-KIT boards have built-in JTAG functionality. Putting
|
||||
Configure Hardware
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
1. Enable on-board JTAG functionality by setting JP8 according to :doc:`../../hw-reference/get-started-wrover-kit`, Section :ref:`get-started-esp-wrover-kit-v4.1-setup-options`.
|
||||
1. Enable on-board JTAG functionality by setting JP8 according to :doc:`../../hw-reference/esp32/get-started-wrover-kit`, Section :ref:`get-started-esp-wrover-kit-v4.1-setup-options`.
|
||||
|
||||
2. Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation:
|
||||
|
||||
|
||||
@@ -150,10 +150,11 @@ See :ref:`jtag-debugging-tip-why-next-works-as-step` for potential limitation of
|
||||
|
||||
Checking and setting memory
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To display or set contents of memory use "Memory" tab at the bottom of "Debug" perspective.
|
||||
|
||||
With the "Memory" tab, we will read from and write to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's. For more information please refer to `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`__, chapter IO_MUX and GPIO Matrix.
|
||||
With the "Memory" tab, we will read from and write to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's.
|
||||
|
||||
For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`__, chapter IO_MUX and GPIO Matrix.
|
||||
|
||||
Being in the same ``blink.c`` project as before, set two breakpoints right after ``gpio_set_level`` instruction. Click "Memory" tab and then "Add Memory Monitor" button. Enter ``0x3FF44004`` in provided dialog.
|
||||
|
||||
@@ -272,7 +273,7 @@ You can use ``bt`` or ``backtrace`` to see what function calls lead up to this c
|
||||
|
||||
(gdb) bt
|
||||
#0 app_main () at /home/user-name/esp/blink/main/./blink.c:43
|
||||
#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/esp32/./cpu_start.c:339
|
||||
#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:339
|
||||
(gdb)
|
||||
|
||||
Line #0 of output provides the last function call before the application halted, i.e. ``app_main ()`` we have listed previously. The ``app_main ()`` was in turn called by function ``main_task`` from line 339 of code located in file ``cpu_start.c``.
|
||||
@@ -280,7 +281,7 @@ Line #0 of output provides the last function call before the application halted,
|
||||
To get to the context of ``main_task`` in file ``cpu_start.c``, enter ``frame N``, where N = 1, because the ``main_task`` is listed under #1)::
|
||||
|
||||
(gdb) frame 1
|
||||
#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/esp32/./cpu_start.c:339
|
||||
#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:339
|
||||
339 app_main();
|
||||
(gdb)
|
||||
|
||||
@@ -324,14 +325,14 @@ To see the other code, enter ``i threads``. This will show the list of threads r
|
||||
(gdb) i threads
|
||||
Id Target Id Frame
|
||||
8 Thread 1073411336 (dport) 0x400d0848 in dport_access_init_core (arg=<optimized out>)
|
||||
at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:170
|
||||
at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./dport_access.c:170
|
||||
7 Thread 1073408744 (ipc0) xQueueGenericReceive (xQueue=0x3ffae694, pvBuffer=0x0, xTicksToWait=1644638200,
|
||||
xJustPeeking=0) at /home/user-name/esp/esp-idf/components/freertos/./queue.c:1452
|
||||
6 Thread 1073431096 (Tmr Svc) prvTimerTask (pvParameters=0x0)
|
||||
at /home/user-name/esp/esp-idf/components/freertos/./timers.c:445
|
||||
5 Thread 1073410208 (ipc1 : Running) 0x4000bfea in ?? ()
|
||||
4 Thread 1073432224 (dport) dport_access_init_core (arg=0x0)
|
||||
at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:150
|
||||
at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./dport_access.c:150
|
||||
3 Thread 1073413156 (IDLE) prvIdleTask (pvParameters=0x0)
|
||||
at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282
|
||||
2 Thread 1073413512 (IDLE) prvIdleTask (pvParameters=0x0)
|
||||
@@ -438,7 +439,7 @@ To check it delete all breakpoints and enter ``c`` to resume application. Then e
|
||||
|
||||
Program received signal SIGINT, Interrupt.
|
||||
[Switching to Thread 1073413512]
|
||||
0x400d0c00 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/esp32/./freertos_hooks.c:52
|
||||
0x400d0c00 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./freertos_hooks.c:52
|
||||
52 asm("waiti 0");
|
||||
(gdb)
|
||||
|
||||
@@ -513,7 +514,9 @@ Checking and setting memory
|
||||
|
||||
Displaying the contents of memory is done with command ``x``. With additional parameters you may vary the format and count of memory locations displayed. Run ``help x`` to see more details. Companion command to ``x`` is ``set`` that let you write values to the memory.
|
||||
|
||||
We will demonstrate how ``x`` and ``set`` work by reading from and writing to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's. For more information please refer to `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`__, chapter IO_MUX and GPIO Matrix.
|
||||
We will demonstrate how ``x`` and ``set`` work by reading from and writing to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's.
|
||||
|
||||
For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`__, chapter IO_MUX and GPIO Matrix.
|
||||
|
||||
Being in the same ``blink.c`` project as before, set two breakpoints right after ``gpio_set_level`` instruction. Enter two times ``c`` to get to the break point followed by ``x /1wx 0x3FF44004`` to display contents of ``GPIO_OUT_REG`` memory location::
|
||||
|
||||
|
||||
@@ -2,18 +2,18 @@ JTAG Debugging
|
||||
==============
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
This document provides a guide to installing OpenOCD for ESP32 and debugging using
|
||||
This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and debugging using
|
||||
GDB. The document is structured as follows:
|
||||
|
||||
:ref:`jtag-debugging-introduction`
|
||||
Introduction to the purpose of this guide.
|
||||
:ref:`jtag-debugging-how-it-works`
|
||||
Description how ESP32, JTAG interface, OpenOCD and GDB are interconnected and working together to enable debugging of ESP32.
|
||||
Description how {IDF_TARGET_NAME}, JTAG interface, OpenOCD and GDB are interconnected and working together to enable debugging of {IDF_TARGET_NAME}.
|
||||
:ref:`jtag-debugging-selecting-jtag-adapter`
|
||||
What are the criteria and options to select JTAG adapter hardware.
|
||||
:ref:`jtag-debugging-setup-openocd`
|
||||
Procedure to install OpenOCD and verify that it is installed.
|
||||
:ref:`jtag-debugging-configuring-esp32-target`
|
||||
:ref:`jtag-debugging-configuring-target`
|
||||
Configuration of OpenOCD software and set up JTAG adapter hardware that will make together a debugging target.
|
||||
:ref:`jtag-debugging-launching-debugger`
|
||||
Steps to start up a debug session with GDB from :ref:`jtag-debugging-using-debugger-eclipse` and from :ref:`jtag-debugging-using-debugger-command-line`.
|
||||
@@ -22,7 +22,7 @@ GDB. The document is structured as follows:
|
||||
:ref:`jtag-debugging-building-openocd`
|
||||
Procedure to build OpenOCD from sources for :doc:`Windows <building-openocd-windows>`, :doc:`Linux <building-openocd-linux>` and :doc:`MacOS <building-openocd-macos>` operating systems.
|
||||
:ref:`jtag-debugging-tips-and-quirks`
|
||||
This section provides collection of tips and quirks related JTAG debugging of ESP32 with OpenOCD and GDB.
|
||||
This section provides collection of tips and quirks related JTAG debugging of {IDF_TARGET_NAME} with OpenOCD and GDB.
|
||||
|
||||
|
||||
.. _jtag-debugging-introduction:
|
||||
@@ -30,13 +30,15 @@ GDB. The document is structured as follows:
|
||||
Introduction
|
||||
------------
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
The ESP32 has two powerful Xtensa cores, allowing for a great deal of variety of program architectures. The FreeRTOS OS that comes with ESP-IDF is capable of multi-core preemptive multithreading, allowing for an intuitive way of writing software.
|
||||
|
||||
The downside of the ease of programming is that debugging without the right tools is harder: figuring out a bug that is caused by two threads, running even simultaneously on two different CPU cores, can take a long time when all you have are printf statements. A better and in many cases quicker way to debug such problems is by using a debugger, connected to the processors over a debug port.
|
||||
|
||||
Espressif has ported OpenOCD to support the ESP32 processor and the multicore FreeRTOS, which will be the foundation of most ESP32 apps, and has written some tools to help with features OpenOCD does not support natively.
|
||||
Espressif has ported OpenOCD to support the {IDF_TARGET_NAME} processor and the multicore FreeRTOS, which will be the foundation of most {IDF_TARGET_NAME} apps, and has written some tools to help with features OpenOCD does not support natively.
|
||||
|
||||
This document provides a guide to installing OpenOCD for ESP32 and debugging using GDB under Linux, Windows and MacOS. Except for OS specific installation procedures, the s/w user interface and use procedures are the same across all supported operating systems.
|
||||
This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and debugging using GDB under Linux, Windows and MacOS. Except for OS specific installation procedures, the s/w user interface and use procedures are the same across all supported operating systems.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -47,7 +49,7 @@ This document provides a guide to installing OpenOCD for ESP32 and debugging usi
|
||||
How it Works?
|
||||
-------------
|
||||
|
||||
The key software and hardware to perform debugging of ESP32 with OpenOCD over JTAG (Joint Test Action Group) interface is presented below and includes **xtensa-esp32-elf-gdb debugger**, **OpenOCD on chip debugger** and **JTAG adapter** connected to **ESP32** target.
|
||||
The key software and hardware to perform debugging of {IDF_TARGET_NAME} with OpenOCD over JTAG (Joint Test Action Group) interface is presented below and includes xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb debugger, OpenOCD on chip debugger and JTAG adapter connected to {IDF_TARGET_NAME} target.
|
||||
|
||||
.. figure:: ../../../_static/jtag-debugging-overview.jpg
|
||||
:align: center
|
||||
@@ -56,10 +58,12 @@ The key software and hardware to perform debugging of ESP32 with OpenOCD over JT
|
||||
|
||||
JTAG debugging - overview diagram
|
||||
|
||||
Under "Application Loading and Monitoring" there is another software and hardware to compile, build and flash application to ESP32, as well as to provide means to monitor diagnostic messages from ESP32.
|
||||
Under "Application Loading and Monitoring" there is another software and hardware to compile, build and flash application to {IDF_TARGET_NAME}, as well as to provide means to monitor diagnostic messages from {IDF_TARGET_NAME}.
|
||||
|
||||
Debugging using JTAG and application loading / monitoring is integrated under the `Eclipse <https://www.eclipse.org/>`_ environment, to provide quick and easy transition from writing, compiling and loading the code to debugging, back to writing the code, and so on. All the software is available for Windows, Linux and MacOS platforms.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
If the :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>` is used, then connection from PC to ESP32 is done effectively with a single USB cable thanks to FT2232H chip installed on WROVER, which provides two USB channels, one for JTAG and the second for UART connection.
|
||||
|
||||
Depending on user preferences, both `debugger` and `idf.py build` can be operated directly from terminal/command line, instead from Eclipse.
|
||||
@@ -70,13 +74,13 @@ Depending on user preferences, both `debugger` and `idf.py build` can be operate
|
||||
Selecting JTAG Adapter
|
||||
----------------------
|
||||
|
||||
The quickest and most convenient way to start with JTAG debugging is by using :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>`. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to ESP32. WROVER KIT is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
|
||||
The quickest and most convenient way to start with JTAG debugging is by using :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>`. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. WROVER KIT is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
|
||||
|
||||
If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the ESP32 as well as with the OpenOCD software. The JTAG port on the ESP32 is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range.
|
||||
If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the {IDF_TARGET_NAME} as well as with the OpenOCD software. The JTAG port on the {IDF_TARGET_NAME} is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range.
|
||||
|
||||
On the software side, OpenOCD supports a fair amount of JTAG adapters. See http://openocd.org/doc/html/Debug-Adapter-Hardware.html for an (unfortunately slightly incomplete) list of the adapters OpenOCD works with. This page lists SWD-compatible adapters as well; take note that the ESP32 does not support SWD. JTAG adapters that are hardcoded to a specific product line, e.g. ST-LINK debugging adapters for STM32 families, will not work.
|
||||
On the software side, OpenOCD supports a fair amount of JTAG adapters. See http://openocd.org/doc/html/Debug-Adapter-Hardware.html for an (unfortunately slightly incomplete) list of the adapters OpenOCD works with. This page lists SWD-compatible adapters as well; take note that the {IDF_TARGET_NAME} does not support SWD. JTAG adapters that are hardcoded to a specific product line, e.g. ST-LINK debugging adapters for STM32 families, will not work.
|
||||
|
||||
The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and GND. Some JTAG debuggers also need a connection from the ESP32 power line to a line called e.g. Vtar to set the working voltage. SRST can optionally be connected to the CH_PD of the ESP32, although for now, support in OpenOCD for that line is pretty minimal.
|
||||
The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and GND. Some JTAG debuggers also need a connection from the {IDF_TARGET_NAME} power line to a line called e.g. Vtar to set the working voltage. SRST can optionally be connected to the CH_PD of the {IDF_TARGET_NAME}, although for now, support in OpenOCD for that line is pretty minimal.
|
||||
|
||||
|
||||
.. _jtag-debugging-setup-openocd:
|
||||
@@ -94,7 +98,7 @@ If you have already set up ESP-IDF with CMake build system according to the :doc
|
||||
|
||||
The output should be as follows (although the version may be more recent than listed here)::
|
||||
|
||||
Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04)
|
||||
Open On-Chip Debugger v0.10.0-{IDF_TARGET_TOOLCHAIN_NAME}-20190708 (2019-07-08-11:04)
|
||||
Licensed under GNU GPL v2
|
||||
For bug reports, read
|
||||
http://openocd.org/doc/doxygen/bugs.html
|
||||
@@ -107,12 +111,12 @@ If any of these steps do not work, please go back to the :ref:`setting up the to
|
||||
|
||||
It is also possible to build OpenOCD from source. Please refer to :ref:`jtag-debugging-building-openocd` section for details.
|
||||
|
||||
.. _jtag-debugging-configuring-esp32-target:
|
||||
.. _jtag-debugging-configuring-target:
|
||||
|
||||
Configuring ESP32 Target
|
||||
------------------------
|
||||
Configuring {IDF_TARGET_NAME} Target
|
||||
-------------------------------------
|
||||
|
||||
Once OpenOCD is installed, move to configuring ESP32 target (i.e ESP32 board with JTAG interface). You will do it in the following three steps:
|
||||
Once OpenOCD is installed, move to configuring {IDF_TARGET_NAME} target (i.e {IDF_TARGET_NAME} board with JTAG interface). You will do it in the following three steps:
|
||||
|
||||
* Configure and connect JTAG interface
|
||||
* Run OpenOCD
|
||||
@@ -122,12 +126,12 @@ Once OpenOCD is installed, move to configuring ESP32 target (i.e ESP32 board wit
|
||||
Configure and connect JTAG interface
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This step depends on JTAG and ESP32 board you are using - see the two cases described below.
|
||||
This step depends on JTAG and {IDF_TARGET_NAME} board you are using - see the two cases described below.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
configure-wrover
|
||||
:esp32: configure-wrover
|
||||
configure-other-jtag
|
||||
|
||||
|
||||
@@ -146,7 +150,7 @@ Open a terminal and set it up for using the ESP-IDF as described in the :ref:`se
|
||||
|
||||
.. note::
|
||||
|
||||
The files provided after ``-f`` above are specific for ESP-WROVER-KIT with :ref:`esp-modules-and-boards-esp32-wroom-32` module. You may need to provide different files depending on used hardware. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`.
|
||||
The files provided after ``-f`` above are specific for ESP-WROVER-KIT with esp32-wroom-32 module. You may need to provide different files depending on used hardware. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`.
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
@@ -169,7 +173,7 @@ You should now see similar output (this log is for ESP-WROVER-KIT)::
|
||||
|
||||
* If there is an error indicating permission problems, please see the "Permissions delegation" bit in the OpenOCD README file in ``~/esp/openocd-esp32`` directory.
|
||||
* In case there is an error finding configuration files, e.g. ``Can't find board/esp32-wrover-kit-3.3v.cfg``, check the path after ``-s``. This path is used by OpenOCD to look for the files specified after ``-f``. Also check if the file is indeed under provided path.
|
||||
* If you see JTAG errors (...all ones/...all zeroes) please check your connections, whether no other signals are connected to JTAG besides ESP32's pins, and see if everything is powered on.
|
||||
* If you see JTAG errors (...all ones/...all zeroes) please check your connections, whether no other signals are connected to JTAG besides {IDF_TARGET_NAME}'s pins, and see if everything is powered on.
|
||||
|
||||
|
||||
.. _jtag-upload-app-debug:
|
||||
@@ -177,7 +181,7 @@ You should now see similar output (this log is for ESP-WROVER-KIT)::
|
||||
Upload application for debugging
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Build and upload your application to ESP32 as usual, see :ref:`get-started-build`.
|
||||
Build and upload your application to {IDF_TARGET_NAME} as usual, see :ref:`get-started-build`.
|
||||
|
||||
Another option is to write application image to flash using OpenOCD via JTAG with commands like this::
|
||||
|
||||
@@ -201,7 +205,7 @@ You are now ready to start application debugging. Follow steps described in sect
|
||||
Launching Debugger
|
||||
------------------
|
||||
|
||||
The toolchain for ESP32 features GNU Debugger, in short GDB. It is available with other toolchain programs under filename ``xtensa-esp32-elf-gdb``. GDB can be called and operated directly from command line in a terminal. Another option is to call it from within IDE (like Eclipse, Visual Studio Code, etc.) and operate indirectly with help of GUI instead of typing commands in a terminal.
|
||||
The toolchain for {IDF_TARGET_NAME} features GNU Debugger, in short GDB. It is available with other toolchain programs under filename: xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb. GDB can be called and operated directly from command line in a terminal. Another option is to call it from within IDE (like Eclipse, Visual Studio Code, etc.) and operate indirectly with help of GUI instead of typing commands in a terminal.
|
||||
|
||||
Both options of using debugger are discussed under links below.
|
||||
|
||||
@@ -228,7 +232,7 @@ This section is intended for users not familiar with GDB. It presents example de
|
||||
|
||||
Similar debugging actions are provided using GDB from :ref:`jtag-debugging-examples-command-line`.
|
||||
|
||||
Before proceeding to examples, set up your ESP32 target and load it with :example:`get-started/blink`.
|
||||
Before proceeding to examples, set up your {IDF_TARGET_NAME} target and load it with :example:`get-started/blink`.
|
||||
|
||||
|
||||
.. _jtag-debugging-building-openocd:
|
||||
@@ -275,20 +279,10 @@ Tips and Quirks
|
||||
|
||||
This section provides collection of links to all tips and quirks referred to from various parts of this guide.
|
||||
|
||||
* :ref:`jtag-debugging-tip-breakpoints`
|
||||
* :ref:`jtag-debugging-tip-where-breakpoints`
|
||||
* :ref:`jtag-debugging-tip-flash-mappings`
|
||||
* :ref:`jtag-debugging-tip-why-next-works-as-step`
|
||||
* :ref:`jtag-debugging-tip-code-options`
|
||||
* :ref:`jtag-debugging-tip-freertos-support`
|
||||
* :ref:`jtag-debugging-tip-code-flash-voltage`
|
||||
* :ref:`jtag-debugging-tip-optimize-jtag-speed`
|
||||
* :ref:`jtag-debugging-tip-debugger-startup-commands`
|
||||
* :ref:`jtag-debugging-tip-openocd-configure-target`
|
||||
* :ref:`jtag-debugging-tip-reset-by-debugger`
|
||||
* :ref:`jtag-debugging-tip-jtag-pins-reconfigured`
|
||||
* :ref:`jtag-debugging-tip-at-firmware-issue`
|
||||
* :ref:`jtag-debugging-tip-reporting-issues`
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
tips-and-quirks
|
||||
|
||||
|
||||
Related Documents
|
||||
|
||||
@@ -10,7 +10,7 @@ This section provides collection of all tips and quirks referred to from various
|
||||
Breakpoints and watchpoints available
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
ESP32 debugger supports 2 hardware implemented breakpoints and 64 software ones. Hardware breakpoints are implemented by ESP32 chip's logic and can be set anywhere in the code: either in flash or IRAM program's regions. Additionally there are 2 types of software breakpoints implemented by OpenOCD: flash (up to 32) and IRAM (up to 32) breakpoints. Currently GDB can not set software breakpoints in flash. So until this limitation is removed those breakpoints have to be emulated by OpenOCD as hardware ones (see :ref:`below <jtag-debugging-tip-where-breakpoints>` for details). ESP32 also supports two watchpoints, so two variables can be watched for change or read by the GDB command ``watch myVariable``. Note that menuconfig option :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` uses the 2nd watchpoint and will not provide expected results, if you also try to use it within OpenOCD / GDB. See menuconfig's help for detailed description.
|
||||
{IDF_TARGET_NAME} debugger supports 2 hardware implemented breakpoints and 64 software ones. Hardware breakpoints are implemented by {IDF_TARGET_NAME} chip's logic and can be set anywhere in the code: either in flash or IRAM program's regions. Additionally there are 2 types of software breakpoints implemented by OpenOCD: flash (up to 32) and IRAM (up to 32) breakpoints. Currently GDB can not set software breakpoints in flash. So until this limitation is removed those breakpoints have to be emulated by OpenOCD as hardware ones (see :ref:`below <jtag-debugging-tip-where-breakpoints>` for details). {IDF_TARGET_NAME} also supports two watchpoints, so two variables can be watched for change or read by the GDB command ``watch myVariable``. Note that menuconfig option :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` uses the 2nd watchpoint and will not provide expected results, if you also try to use it within OpenOCD / GDB. See menuconfig's help for detailed description.
|
||||
|
||||
|
||||
.. _jtag-debugging-tip-where-breakpoints:
|
||||
@@ -26,7 +26,7 @@ Emulating part of hardware breakpoints using software flash ones means that the
|
||||
Flash Mappings vs SW Flash Breakpoints
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In order to set/clear software breakpoints in flash, OpenOCD needs to know their flash addresses. To accomplish conversion from the ESP32 address space to the flash one, OpenOCD uses mappings of program's code regions resided in flash. Those mappings are kept in the image header which is prepended to program binary data (code and data segments) and is specific to every application image written to the flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found application image, but there can be the cases when it will not work, e.g. partition table is not at standard flash location or even there can be multiple images: one factory and two OTA and you may want to debbug any of them. To cover all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of application image to debug. The command has the following format:
|
||||
In order to set/clear software breakpoints in flash, OpenOCD needs to know their flash addresses. To accomplish conversion from the {IDF_TARGET_NAME} address space to the flash one, OpenOCD uses mappings of program's code regions resided in flash. Those mappings are kept in the image header which is prepended to program binary data (code and data segments) and is specific to every application image written to the flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found application image, but there can be the cases when it will not work, e.g. partition table is not at standard flash location or even there can be multiple images: one factory and two OTA and you may want to debbug any of them. To cover all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of application image to debug. The command has the following format:
|
||||
|
||||
``esp32 appimage_offset <offset>``
|
||||
|
||||
@@ -55,7 +55,8 @@ Support options for OpenOCD at compile time
|
||||
|
||||
ESP-IDF has some support options for OpenOCD debugging which can be set at compile time:
|
||||
|
||||
* :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger.
|
||||
* :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger.
|
||||
|
||||
* :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` (disabled by default) sets watchpoint index 1 (the second of two) at the end of any task stack. This is the most accurate way to debug task stack overflows. Click the link for more details.
|
||||
|
||||
Please see the :ref:`project configuration menu <get-started-configure>` menu for more details on setting compile-time options.
|
||||
@@ -70,6 +71,8 @@ OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS task
|
||||
|
||||
.. _jtag-debugging-tip-code-flash-voltage:
|
||||
|
||||
.. only:: esp33
|
||||
|
||||
Why to set SPI flash voltage in OpenOCD configuration?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -100,7 +103,7 @@ What is the meaning of debugger's startup commands?
|
||||
|
||||
On startup, debugger is issuing sequence of commands to reset the chip and halt it at specific line of code. This sequence (shown below) is user defined to pick up at most convenient / appropriate line and start debugging.
|
||||
|
||||
* ``set remote hardware-watchpoint-limit 2`` — Restrict GDB to using two hardware watchpoints supported by ESP32. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html.
|
||||
* ``set remote hardware-watchpoint-limit 2`` — Restrict GDB to using two hardware watchpoints supported by the chip, 2 for {IDF_TARGET_NAME}. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html.
|
||||
* ``mon reset halt`` — reset the chip and keep the CPUs halted
|
||||
* ``flushregs`` — monitor (``mon``) command can not inform GDB that the target state has changed. GDB will assume that whatever stack the target had before ``mon reset halt`` will still be valid. In fact, after reset the target state will change, and executing ``flushregs`` is a way to force GDB to get new state from the target.
|
||||
* ``thb app_main`` — insert a temporary hardware breakpoint at ``app_main``, put here another function name if required
|
||||
@@ -114,7 +117,7 @@ Configuration of OpenOCD for specific target
|
||||
|
||||
OpenOCD needs to be told what JTAG adapter to use and processor the JTAG adapter is connected to. To do so, use existing **board** configuration files located in OpenOCD's ``share/openocd/scripts/board`` folder.
|
||||
|
||||
For example, if you connect to ESP-WROVER-KIT with ESP-WROOM-32 module installed (see section :ref:`esp-modules-and-boards-esp-wrover-kit-v1`), use the following configuration files:
|
||||
For example, if you connect to ESP-WROVER-KIT with ESP-WROOM-32 module installed, use the following configuration files:
|
||||
|
||||
* ``board/esp32-wrover-kit-3.3v.cfg``
|
||||
|
||||
@@ -132,6 +135,7 @@ Adapter's clock speed
|
||||
|
||||
See :ref:`jtag-debugging-tip-optimize-jtag-speed` for guidance how to set this value.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
Single core debugging
|
||||
"""""""""""""""""""""
|
||||
@@ -163,6 +167,8 @@ Power supply voltage of ESP32's SPI flash chip
|
||||
Comment out this line to set 3.3 V, ref: :ref:`jtag-debugging-tip-code-flash-voltage`
|
||||
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
Configuration file for ESP32 targets
|
||||
""""""""""""""""""""""""""""""""""""
|
||||
|
||||
@@ -195,8 +201,8 @@ Look inside ``board/esp-wroom-32.cfg`` for additional information provided in co
|
||||
|
||||
.. _jtag-debugging-tip-reset-by-debugger:
|
||||
|
||||
How debugger resets ESP32?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
How debugger resets {IDF_TARGET_NAME}?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The board can be reset by entering ``mon reset`` or ``mon reset halt`` into GDB.
|
||||
|
||||
@@ -206,19 +212,35 @@ The board can be reset by entering ``mon reset`` or ``mon reset halt`` into GDB.
|
||||
Do not use JTAG pins for something else
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides ESP32 module and JTAG adapter. ESP32 JTAG us using the following pins:
|
||||
Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides {IDF_TARGET_NAME} module and JTAG adapter. {IDF_TARGET_NAME} JTAG us using the following pins:
|
||||
|
||||
+---+----------------+-------------+
|
||||
| | ESP32 JTAG Pin | JTAG Signal |
|
||||
+===+================+=============+
|
||||
.. only:: esp32
|
||||
|
||||
+---+-----------------------+-------------+
|
||||
| | ESP32 Pin | JTAG Signal |
|
||||
+===+=======================+=============+
|
||||
| 1 | MTDO / GPIO15 | TDO |
|
||||
+---+----------------+-------------+
|
||||
+---+-----------------------+-------------+
|
||||
| 2 | MTDI / GPIO12 | TDI |
|
||||
+---+----------------+-------------+
|
||||
+---+-----------------------+-------------+
|
||||
| 3 | MTCK / GPIO13 | TCK |
|
||||
+---+----------------+-------------+
|
||||
+---+-----------------------+-------------+
|
||||
| 4 | MTMS / GPIO14 | TMS |
|
||||
+---+----------------+-------------+
|
||||
+---+-----------------------+-------------+
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
+---+-----------------------+-------------+
|
||||
| | ESP32-S2 Pin | JTAG Signal |
|
||||
+===+=======================+=============+
|
||||
| 1 | MTDO / GPIO40 | TDO |
|
||||
+---+-----------------------+-------------+
|
||||
| 2 | MTDI / GPIO41 | TDI |
|
||||
+---+-----------------------+-------------+
|
||||
| 3 | MTCK / GPIO39 | TCK |
|
||||
+---+-----------------------+-------------+
|
||||
| 4 | MTMS / GPIO42 | TMS |
|
||||
+---+-----------------------+-------------+
|
||||
|
||||
JTAG communication will likely fail, if configuration of JTAG pins is changed by user application. If OpenOCD initializes correctly (detects the two Tensilica cores), but loses sync and spews out a lot of DTR/DIR errors when the program is ran, it is likely that the application reconfigures the JTAG pins to something else, or the user forgot to connect Vtar to a JTAG adapter that needed it.
|
||||
|
||||
@@ -236,6 +258,8 @@ Below is an excerpt from series of errors reported by GDB after the application
|
||||
|
||||
.. _jtag-debugging-tip-at-firmware-issue:
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
JTAG and ESP32-WROOM-32 AT firmware Compatibility Issue
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
@@ -36,7 +36,7 @@ Once installation is complete, configure debugging session following steps below
|
||||
|
||||
Configuration of GDB Hardware Debugging - Main tab
|
||||
|
||||
6. Click "Debugger" tab. In field "GDB Command" enter ``xtensa-esp32-elf-gdb`` to invoke debugger.
|
||||
6. Click "Debugger" tab. In field "GDB Command" enter ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb`` to invoke debugger.
|
||||
|
||||
7. Change default configuration of "Remote host" by entering ``3333`` under the "Port number".
|
||||
|
||||
@@ -82,7 +82,7 @@ Once installation is complete, configure debugging session following steps below
|
||||
|
||||
If the "Startup" sequence looks convoluted and respective "Initialization Commands" are not clear to you, check :ref:`jtag-debugging-tip-debugger-startup-commands` for additional explanation.
|
||||
|
||||
12. If you previously completed :ref:`jtag-debugging-configuring-esp32-target` steps described above, so the target is running and ready to talk to debugger, go right to debugging by pressing "Debug" button. Otherwise press "Apply" to save changes, go back to :ref:`jtag-debugging-configuring-esp32-target` and return here to start debugging.
|
||||
12. If you previously completed :ref:`jtag-debugging-configuring-target` steps described above, so the target is running and ready to talk to debugger, go right to debugging by pressing "Debug" button. Otherwise press "Apply" to save changes, go back to :ref:`jtag-debugging-configuring-target` and return here to start debugging.
|
||||
|
||||
Once all 1 - 12 configuration steps are satisfied, the new Eclipse perspective called "Debug" will open as shown on example picture below.
|
||||
|
||||
@@ -101,7 +101,7 @@ If you are not quite sure how to use GDB, check :ref:`jtag-debugging-examples-ec
|
||||
Command Line
|
||||
^^^^^^^^^^^^
|
||||
|
||||
1. Begin with completing steps described under :ref:`jtag-debugging-configuring-esp32-target`. This is prerequisite to start a debugging session.
|
||||
1. Begin with completing steps described under :ref:`jtag-debugging-configuring-target`. This is prerequisite to start a debugging session.
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
@@ -134,7 +134,7 @@ Command Line
|
||||
|
||||
::
|
||||
|
||||
xtensa-esp32-elf-gdb -x gdbinit build/blink.elf
|
||||
xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit build/blink.elf
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
@@ -142,14 +142,14 @@ Command Line
|
||||
|
||||
::
|
||||
|
||||
user-name@computer-name:~/esp/blink$ xtensa-esp32-elf-gdb -x gdbinit build/blink.elf
|
||||
user-name@computer-name:~/esp/blink$ xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit build/blink.elf
|
||||
GNU gdb (crosstool-NG crosstool-ng-1.22.0-61-gab8375a) 7.10
|
||||
Copyright (C) 2015 Free Software Foundation, Inc.
|
||||
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
|
||||
This is free software: you are free to change and redistribute it.
|
||||
There is NO WARRANTY, to the extent permitted by law. Type "show copying"
|
||||
and "show warranty" for details.
|
||||
This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=xtensa-esp32-elf".
|
||||
This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf".
|
||||
Type "show configuration" for configuration details.
|
||||
For bug reporting instructions, please see:
|
||||
<http://www.gnu.org/software/gdb/bugs/>.
|
||||
@@ -158,17 +158,17 @@ Command Line
|
||||
For help, type "help".
|
||||
Type "apropos word" to search for commands related to "word"...
|
||||
Reading symbols from build/blink.elf...done.
|
||||
0x400d10d8 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/esp32/./freertos_hooks.c:52
|
||||
0x400d10d8 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./freertos_hooks.c:52
|
||||
52 asm("waiti 0");
|
||||
JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
|
||||
JTAG tap: esp32.slave tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
|
||||
esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
|
||||
esp32: Core was reset (pwrstat=0x5F, after clear 0x0F).
|
||||
JTAG tap: {IDF_TARGET_PATH_NAME}.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
|
||||
JTAG tap: {IDF_TARGET_PATH_NAME}.slave tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
|
||||
{IDF_TARGET_PATH_NAME}: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
|
||||
{IDF_TARGET_PATH_NAME}: Core was reset (pwrstat=0x5F, after clear 0x0F).
|
||||
Target halted. PRO_CPU: PC=0x5000004B (active) APP_CPU: PC=0x00000000
|
||||
esp32: target state: halted
|
||||
esp32: Core was reset (pwrstat=0x1F, after clear 0x0F).
|
||||
{IDF_TARGET_PATH_NAME}: target state: halted
|
||||
{IDF_TARGET_PATH_NAME}: Core was reset (pwrstat=0x1F, after clear 0x0F).
|
||||
Target halted. PRO_CPU: PC=0x40000400 (active) APP_CPU: PC=0x40000400
|
||||
esp32: target state: halted
|
||||
{IDF_TARGET_PATH_NAME}: target state: halted
|
||||
Hardware assisted breakpoint 1 at 0x400db717: file /home/user-name/esp/blink/main/./blink.c, line 43.
|
||||
0x0: 0x00000000
|
||||
Target halted. PRO_CPU: PC=0x400DB717 (active) APP_CPU: PC=0x400D10D8
|
||||
|
||||
@@ -426,11 +426,11 @@ will be generated for the target ``flash_text``.
|
||||
|
||||
These catch-all rules then effectively serve as fallback rules for those whose mappings were not specified.
|
||||
|
||||
.. note::
|
||||
|
||||
The ``default scheme`` is defined in :component:`esp32/ld/esp32_fragments.lf`. The ``noflash`` and ``rtc`` scheme fragments which are
|
||||
The ``default scheme`` is defined in :component:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}_fragments.lf`. The ``noflash`` and ``rtc`` scheme fragments which are
|
||||
built-in schemes referenced in the quick start guide are also defined in this file.
|
||||
|
||||
|
||||
.. _ldgen-mapping-fragment :
|
||||
|
||||
**Mapping**
|
||||
@@ -589,9 +589,5 @@ Then the corresponding excerpt from the generated linker script will be as follo
|
||||
it too is placed wherever ``iram0_text`` is referenced by a marker. Since it is a rule generated from the default scheme, it comes first
|
||||
among all other rules collected under the same target name.
|
||||
|
||||
.. note::
|
||||
|
||||
The linker script template currently used is :component:`esp32/ld/esp32.project.ld.in`, specified by the ``esp32`` component; the
|
||||
The linker script template currently used is :component:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}.project.ld.in`, specified by the ``{IDF_TARGET_PATH_NAME}`` component; the
|
||||
generated output script is put under its build directory.
|
||||
|
||||
|
||||
|
||||
@@ -325,7 +325,15 @@ IP layer features
|
||||
Limitations
|
||||
^^^^^^^^^^^
|
||||
|
||||
- Calling ``send()`` or ``sendto()`` repeatedly on a UDP socket may eventually fail with ``errno`` equal to ``ENOMEM``. This is a limitation of buffer sizes in the lower layer network interface drivers. If all driver transmit buffers are full then UDP transmission will fail. Applications sending a high volume of UDP datagrams who don't wish for any to be dropped by the sender should check for this error code and re-send the datagram after a short delay. Increasing the number of TX buffers in the :ref:`Wi-Fi <CONFIG_ESP32_WIFI_TX_BUFFER>` or :ref:`Ethernet <CONFIG_ETH_DMA_TX_BUFFER_NUM>` project configuration (as applicable) may also help.
|
||||
- Calling ``send()`` or ``sendto()`` repeatedly on a UDP socket may eventually fail with ``errno`` equal to ``ENOMEM``. This is a limitation of buffer sizes in the lower layer network interface drivers. If all driver transmit buffers are full then UDP transmission will fail. Applications sending a high volume of UDP datagrams who don't wish for any to be dropped by the sender should check for this error code and re-send the datagram after a short delay.
|
||||
|
||||
.. only::esp32
|
||||
|
||||
Increasing the number of TX buffers in the :ref:`Wi-Fi <CONFIG_ESP32_WIFI_TX_BUFFER>` or :ref:`Ethernet <CONFIG_ETH_DMA_TX_BUFFER_NUM>` project configuration (as applicable) may also help.
|
||||
|
||||
.. only::esp32s2
|
||||
|
||||
Increasing the number of TX buffers in the :ref:`Wi-Fi <CONFIG_ESP32_WIFI_TX_BUFFER>` project configuration may also help.
|
||||
|
||||
Performance Optimization
|
||||
------------------------
|
||||
|
||||
@@ -5,7 +5,7 @@ Partition Tables
|
||||
Overview
|
||||
--------
|
||||
|
||||
A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to (:ref:`default offset <CONFIG_PARTITION_TABLE_OFFSET>`) 0x8000 in the flash.
|
||||
A single {IDF_TARGET_NAME}'s flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to (:ref:`default offset <CONFIG_PARTITION_TABLE_OFFSET>`) 0x8000 in the flash.
|
||||
|
||||
Partition table length is 0xC00 bytes (maximum 95 partition table entries). An MD5 checksum, which is used for checking the integrity of the partition table, is appended after the table data. If the partition table is signed due to `secure boot`, the signature is appended after the partition table.
|
||||
|
||||
@@ -23,7 +23,7 @@ Built-in Partition Tables
|
||||
|
||||
Here is the summary printed for the "Single factory app, no OTA" configuration::
|
||||
|
||||
# Espressif ESP32 Partition Table
|
||||
# Espressif ESP Partition Table
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x6000,
|
||||
phy_init, data, phy, 0xf000, 0x1000,
|
||||
@@ -34,7 +34,7 @@ Here is the summary printed for the "Single factory app, no OTA" configuration::
|
||||
|
||||
Here is the summary printed for the "Factory app, two OTA definitions" configuration::
|
||||
|
||||
# Espressif ESP32 Partition Table
|
||||
# Espressif ESP Partition Table
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x4000,
|
||||
otadata, data, ota, 0xd000, 0x2000,
|
||||
@@ -69,7 +69,7 @@ The CSV format is the same format as printed in the summaries shown above. Howev
|
||||
Name field
|
||||
~~~~~~~~~~
|
||||
|
||||
Name field can be any meaningful name. It is not significant to the ESP32. Names longer than 16 characters will be truncated.
|
||||
Name field can be any meaningful name. It is not significant to the {IDF_TARGET_NAME}. Names longer than 16 characters will be truncated.
|
||||
|
||||
Type field
|
||||
~~~~~~~~~~
|
||||
@@ -136,7 +136,7 @@ Only one flag is currently supported, ``encrypted``. If this field is set to ``e
|
||||
Generating Binary Partition Table
|
||||
---------------------------------
|
||||
|
||||
The partition table which is flashed to the ESP32 is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats.
|
||||
The partition table which is flashed to the {IDF_TARGET_NAME} is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats.
|
||||
|
||||
If you configure the partition table CSV name in the project configuration (``idf.py menuconfig``) and then build the project or run ``idf.py partition_table``, this conversion is done as part of the build process.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
*****************
|
||||
ESP32 ROM console
|
||||
*****************
|
||||
*****************************
|
||||
{IDF_TARGET_NAME} ROM console
|
||||
*****************************
|
||||
|
||||
When an ESP32 is unable to boot from flash ROM (and the fuse disabling it hasn't been blown), it boots into a rom console. The console
|
||||
When an {IDF_TARGET_NAME} is unable to boot from flash ROM (and the fuse disabling it hasn't been blown), it boots into a rom console. The console
|
||||
is based on TinyBasic, and statements entered should be in the form of BASIC statements. As is common in the BASIC language, without a
|
||||
preceeding line number, commands entered are executed immediately; lines with a prefixed line number are stored as part of a program.
|
||||
|
||||
@@ -12,7 +12,7 @@ Full list of supported statements and functions
|
||||
System
|
||||
------
|
||||
|
||||
- BYE - *exits Basic, reboots ESP32, retries booting from flash*
|
||||
- BYE - *exits Basic, reboots and retries booting from flash*
|
||||
- END - *stops execution from the program, also "STOP"*
|
||||
- MEM - *displays memory usage statistics*
|
||||
- NEW - *clears the current program*
|
||||
|
||||
@@ -89,11 +89,11 @@ IDF Monitor adds more details to the dump::
|
||||
0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:47
|
||||
0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:42
|
||||
0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:33
|
||||
0x400d071d: main_task at /home/gus/esp/32/idf/components/esp32/./cpu_start.c:254
|
||||
0x400d071d: main_task at /home/gus/esp/32/idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:254
|
||||
|
||||
To decode each address, IDF Monitor runs the following command in the background::
|
||||
|
||||
xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
|
||||
xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
|
||||
|
||||
|
||||
Launching GDB with GDBStub
|
||||
@@ -103,13 +103,13 @@ By default, if esp-idf crashes, the panic handler prints relevant registers and
|
||||
|
||||
Optionally, the panic handler can be configured to run GDBStub, the tool which can communicate with GDB_ project debugger. GDBStub allows to read memory, examine call stack frames and variables, etc. It is not as versatile as JTAG debugging, but this method does not require any special hardware.
|
||||
|
||||
To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32_PANIC` to ``Invoke GDBStub``.
|
||||
To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC` to ``Invoke GDBStub``.
|
||||
|
||||
In this case, if the panic handler is triggered, as soon as IDF Monitor sees that GDBStub has loaded, it automatically pauses serial monitoring and runs GDB with necessary arguments. After GDB exits, the board is reset via the RTS serial line. If this line is not connected, please reset the board manually by pressing its Reset button.
|
||||
|
||||
In the background, IDF Monitor runs the following command::
|
||||
|
||||
xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf
|
||||
xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf :idf_target:`Hello NAME chip`
|
||||
|
||||
|
||||
Output Filtering
|
||||
|
||||
@@ -138,4 +138,4 @@ Although the methods above are recommended for ESP-IDF users, they are not a mus
|
||||
List of IDF Tools
|
||||
-----------------
|
||||
|
||||
.. include:: /_build/inc/idf-tools-inc.rst
|
||||
.. include-build-file:: idf-tools-inc.rst
|
||||
|
||||
@@ -6,8 +6,8 @@ ULP Coprocessor programming
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Instruction set reference for ESP32 ULP <ulp_instruction_set>
|
||||
Instruction set reference for ESP32-S2 ULP <ulps2_instruction_set>
|
||||
:esp32: Instruction set reference for ESP32 ULP <ulp_instruction_set>
|
||||
:esp32s2: Instruction set reference for ESP32-S2 ULP <ulps2_instruction_set>
|
||||
Programming using macros (legacy) <ulp_macros>
|
||||
|
||||
|
||||
@@ -20,6 +20,8 @@ The ULP coprocessor code is written in assembly and compiled using the `binutils
|
||||
|
||||
If you have already set up ESP-IDF with CMake build system according to the :doc:`Getting Started Guide <../../get-started/index>`, then the ULP toolchain will already be installed.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
If you are using ESP-IDF with the legacy GNU Make based build system, refer to the instructions on this page: :doc:`ulp-legacy`.
|
||||
|
||||
Compiling the ULP Code
|
||||
@@ -29,7 +31,7 @@ To compile the ULP code as part of the component, the following steps must be ta
|
||||
|
||||
1. The ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside the component directory, for instance `ulp/`.
|
||||
|
||||
.. note: When registering the component (via ``idf_component_register``), this directory should not be added to the ``SRC_DIRS`` argument. The logic behind this is that the ESP-IDF build system will compile files found in ``SRC_DIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files.
|
||||
.. note: When registering the component (via ``idf_component_register``), this directory should not be added to the ``SRC_DIRS`` argument. The logic behind this is that the ESP-IDF build system will compile files found in ``SRC_DIRS`` based on their extensions. For ``.S`` files, ``xtensa-{IDF_TARGET_NAME}-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files.
|
||||
|
||||
2. Call ``ulp_embed_binary`` from the component CMakeLists.txt after registration. For example::
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
ESP32 ULP coprocessor instruction set
|
||||
=====================================
|
||||
|
||||
This document provides details about the instructions used by ESP32 ULP coprocessor assembler.
|
||||
This document provides details about the instructions used by {IDF_TARGET_NAME} ULP coprocessor assembler.
|
||||
|
||||
ULP coprocessor has 4 16-bit general purpose registers, labeled R0, R1, R2, R3. It also has an 8-bit counter register (stage_cnt) which can be used to implement loops. Stage count regiter is accessed using special instructions.
|
||||
|
||||
@@ -13,7 +13,7 @@ The instruction syntax is case insensitive. Upper and lower case letters can be
|
||||
|
||||
Note about addressing
|
||||
---------------------
|
||||
ESP32 ULP coprocessor's JUMP, ST, LD instructions which take register as an argument (jump address, store/load base address) expect the argument to be expressed in 32-bit words.
|
||||
{IDF_TARGET_NAME} ULP coprocessor's JUMP, ST, LD instructions which take register as an argument (jump address, store/load base address) expect the argument to be expressed in 32-bit words.
|
||||
|
||||
Consider the following example program::
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
Unit Testing in ESP32
|
||||
=============================
|
||||
Unit Testing in {IDF_TARGET_NAME}
|
||||
=================================
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
ESP-IDF comes with a unit test application that is based on the Unity - unit test framework. Unit tests are integrated in the ESP-IDF repository and are placed in the ``test`` subdirectories of each component respectively.
|
||||
@@ -114,7 +114,7 @@ To support this, we can define multi-stage test cases, to group a set of test fu
|
||||
TEST_ASSERT(reason == DEEPSLEEP_RESET);
|
||||
}
|
||||
|
||||
TEST_CASE_MULTIPLE_STAGES("reset reason check for deepsleep", "[esp32]", trigger_deepsleep, check_deepsleep_reset_reason);
|
||||
TEST_CASE_MULTIPLE_STAGES("reset reason check for deepsleep", "[{IDF_TARGET_PATH_NAME}]", trigger_deepsleep, check_deepsleep_reset_reason);
|
||||
|
||||
Multi-stage test cases present a group of test functions to users. It needs user interactions (select cases and select different stages) to run the case.
|
||||
|
||||
@@ -142,7 +142,7 @@ Use menuconfig to set the serial port for flashing.
|
||||
Running Unit Tests
|
||||
------------------
|
||||
|
||||
After flashing reset the ESP32 and it will boot the unit test app.
|
||||
After flashing reset the {IDF_TARGET_NAME} and it will boot the unit test app.
|
||||
|
||||
When unit test app is idle, press "Enter" will make it print test menu with all available tests::
|
||||
|
||||
@@ -168,7 +168,7 @@ When unit test app is idle, press "Enter" will make it print test menu with all
|
||||
(17) "SPI Master no response when switch from host1 (HSPI) to host2 (VSPI)" [spi]
|
||||
(18) "SPI Master DMA test, TX and RX in different regions" [spi]
|
||||
(19) "SPI Master DMA test: length, start, not aligned" [spi]
|
||||
(20) "reset reason check for deepsleep" [esp32][test_env=UT_T2_1][multi_stage]
|
||||
(20) "reset reason check for deepsleep" [{IDF_TARGET_PATH_NAME}][test_env=UT_T2_1][multi_stage]
|
||||
(1) "trigger_deepsleep"
|
||||
(2) "check_deepsleep_reset_reason"
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
Wi-Fi Driver
|
||||
=============
|
||||
|
||||
ESP32 Wi-Fi Feature List
|
||||
-------------------------
|
||||
{IDF_TARGET_NAME} Wi-Fi Feature List
|
||||
------------------------------------
|
||||
- Support Station-only mode, AP-only mode, Station/AP-coexistence mode
|
||||
- Support IEEE-802.11B, IEEE-802.11G, IEEE802.11N and APIs to configure the protocol mode
|
||||
- Support WPA/WPA2/WPA2-Enterprise and WPS
|
||||
@@ -21,7 +21,7 @@ How To Write a Wi-Fi Application
|
||||
|
||||
Preparation
|
||||
+++++++++++
|
||||
Generally, the most effective way to begin your own Wi-Fi application is to select an example which is similar to your own application, and port the useful part into your project. It is not a MUST but it is strongly recommended that you take some time to read this article first, especially if you want to program a robust Wi-Fi application. This article is supplementary to the Wi-Fi APIs/Examples. It describes the principles of using the Wi-Fi APIs, the limitations of the current Wi-Fi API implementation, and the most common pitfalls in using Wi-Fi. This article also reveals some design details of the Wi-Fi driver. We recommend that you become familiar at least with the following sections: <`ESP32 Wi-Fi API Error Code`_>, <`ESP32 Wi-Fi Programming Model`_>, and <`ESP32 Wi-Fi Event Description`_>.
|
||||
Generally, the most effective way to begin your own Wi-Fi application is to select an example which is similar to your own application, and port the useful part into your project. It is not a MUST but it is strongly recommended that you take some time to read this article first, especially if you want to program a robust Wi-Fi application. This article is supplementary to the Wi-Fi APIs/Examples. It describes the principles of using the Wi-Fi APIs, the limitations of the current Wi-Fi API implementation, and the most common pitfalls in using Wi-Fi. This article also reveals some design details of the Wi-Fi driver. We recommend that you become familiar at least with the following sections: <`{IDF_TARGET_NAME} Wi-Fi API Error Code`_>, <`{IDF_TARGET_NAME} Wi-Fi Programming Model`_>, and <`{IDF_TARGET_NAME} Wi-Fi Event Description`_>.
|
||||
|
||||
Setting Wi-Fi Compile-time Options
|
||||
++++++++++++++++++++++++++++++++++++
|
||||
@@ -29,24 +29,24 @@ Refer to <`Wi-Fi Menuconfig`_>
|
||||
|
||||
Init Wi-Fi
|
||||
+++++++++++
|
||||
Refer to <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_>.
|
||||
Refer to <`{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_>, <`{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_>.
|
||||
|
||||
Start/Connect Wi-Fi
|
||||
++++++++++++++++++++
|
||||
Refer to <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_>.
|
||||
Refer to <`{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_>, <`{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_>.
|
||||
|
||||
Event-Handling
|
||||
++++++++++++++
|
||||
Generally, it is easy to write code in "sunny-day" scenarios, such as <`WIFI_EVENT_STA_START`_>, <`WIFI_EVENT_STA_CONNECTED`_> etc. The hard part is to write routines in "rainy-day" scenarios, such as <`WIFI_EVENT_STA_DISCONNECTED`_> etc. Good handling of "rainy-day" scenarios is fundamental to robust Wi-Fi applications. Refer to <`ESP32 Wi-Fi Event Description`_>, <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_>. See also :doc:`an overview of event handling in ESP-IDF<event-handling>`.
|
||||
Generally, it is easy to write code in "sunny-day" scenarios, such as <`WIFI_EVENT_STA_START`_>, <`WIFI_EVENT_STA_CONNECTED`_> etc. The hard part is to write routines in "rainy-day" scenarios, such as <`WIFI_EVENT_STA_DISCONNECTED`_> etc. Good handling of "rainy-day" scenarios is fundamental to robust Wi-Fi applications. Refer to <`{IDF_TARGET_NAME} Wi-Fi Event Description`_>, <`{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_>, <`{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_>. See also :doc:`an overview of event handling in ESP-IDF<event-handling>`.
|
||||
|
||||
Write Error-Recovery Routines Correctly at All Times
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
Just like the handling of "rainy-day" scenarios, a good error-recovery routine is also fundamental to robust Wi-Fi applications. Refer to <`ESP32 Wi-Fi API Error Code`_>
|
||||
Just like the handling of "rainy-day" scenarios, a good error-recovery routine is also fundamental to robust Wi-Fi applications. Refer to <`{IDF_TARGET_NAME} Wi-Fi API Error Code`_>
|
||||
|
||||
|
||||
ESP32 Wi-Fi API Error Code
|
||||
---------------------------
|
||||
All of the ESP32 Wi-Fi APIs have well-defined return values, namely, the error code. The error code can be categorized into:
|
||||
{IDF_TARGET_NAME} Wi-Fi API Error Code
|
||||
--------------------------------------
|
||||
All of the {IDF_TARGET_NAME} Wi-Fi APIs have well-defined return values, namely, the error code. The error code can be categorized into:
|
||||
- No errors, e.g. ESP_OK means that the API returns successfully
|
||||
- Recoverable errors, such as ESP_ERR_NO_MEM, etc.
|
||||
- Non-recoverable, non-critical errors
|
||||
@@ -63,8 +63,8 @@ Whether the error is critical or not depends on the API and the application scen
|
||||
In esp_err.h, ESP_ERROR_CHECK checks the return values. It is a rather commonplace error-handling code and can be used
|
||||
as the default error-handling code in the application development phase. However, we strongly recommend that API users write their own error-handling code.
|
||||
|
||||
ESP32 Wi-Fi API Parameter Initialization
|
||||
------------------------------------------
|
||||
{IDF_TARGET_NAME} Wi-Fi API Parameter Initialization
|
||||
----------------------------------------------------
|
||||
|
||||
When initializing struct parameters for the API, one of two approaches should be followed:
|
||||
- explicitly set all fields of the parameter or
|
||||
@@ -74,9 +74,9 @@ Initializing or getting the entire structure is very important because most of t
|
||||
|
||||
.. _wifi-programming-model:
|
||||
|
||||
ESP32 Wi-Fi Programming Model
|
||||
-----------------------------
|
||||
The ESP32 Wi-Fi programming model is depicted as follows:
|
||||
{IDF_TARGET_NAME} Wi-Fi Programming Model
|
||||
-----------------------------------------
|
||||
The {IDF_TARGET_NAME} Wi-Fi programming model is depicted as follows:
|
||||
|
||||
.. blockdiag::
|
||||
:caption: Wi-Fi Programming Model
|
||||
@@ -124,8 +124,8 @@ The Wi-Fi driver can be considered a black box that knows nothing about high-lay
|
||||
|
||||
Wi-Fi event handling is based on the :doc:`esp_event library <../api-reference/system/esp_event>`. Events are sent by the Wi-Fi driver to the :ref:`default event loop <esp-event-default-loops>`. Application may handle these events in callbacks registered using :cpp:func:`esp_event_handler_register`. Wi-Fi events are also handled by :doc:`esp_netif component <../api-reference/network/esp_netif>` to provide a set of default behaviors. For example, when Wi-Fi station connects to an AP, esp_netif will automatically start the DHCP client (by default).
|
||||
|
||||
ESP32 Wi-Fi Event Description
|
||||
------------------------------------
|
||||
{IDF_TARGET_NAME} Wi-Fi Event Description
|
||||
-----------------------------------------
|
||||
|
||||
WIFI_EVENT_WIFI_READY
|
||||
++++++++++++++++++++++++++++++++++++
|
||||
@@ -145,7 +145,7 @@ The scan-done event will not arise in the following scenarios:
|
||||
- The scan is caused by esp_wifi_connect().
|
||||
|
||||
Upon receiving this event, the event task does nothing. The application event callback needs to call esp_wifi_scan_get_ap_num() and esp_wifi_scan_get_ap_records() to fetch the scanned AP list and trigger the Wi-Fi driver to free the internal memory which is allocated during the scan **(do not forget to do this)**!
|
||||
Refer to 'ESP32 Wi-Fi Scan' for a more detailed description.
|
||||
Refer to '{IDF_TARGET_NAME} Wi-Fi Scan' for a more detailed description.
|
||||
|
||||
WIFI_EVENT_STA_START
|
||||
++++++++++++++++++++++++++++++++++++
|
||||
@@ -202,7 +202,7 @@ The socket is based on the IPV4 address, which means that, if the IPV4 changes,
|
||||
|
||||
IP_EVENT_GOT_IP6
|
||||
++++++++++++++++++++++++++++++++++++
|
||||
This event arises when the IPV6 SLAAC support auto-configures an address for the ESP32, or when this address changes. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets).
|
||||
This event arises when the IPV6 SLAAC support auto-configures an address for the {IDF_TARGET_NAME}, or when this address changes. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets).
|
||||
|
||||
IP_STA_LOST_IP
|
||||
++++++++++++++++++++++++++++++++++++
|
||||
@@ -222,7 +222,7 @@ Similar to <`WIFI_EVENT_STA_STOP`_>.
|
||||
|
||||
WIFI_EVENT_AP_STACONNECTED
|
||||
++++++++++++++++++++++++++++++++++++
|
||||
Every time a station is connected to ESP32 AP, the <`WIFI_EVENT_AP_STACONNECTED`_> will arise. Upon receiving this event, the event task will do nothing, and the application callback can also ignore it. However, you may want to do something, for example, to get the info of the connected STA, etc.
|
||||
Every time a station is connected to {IDF_TARGET_NAME} AP, the <`WIFI_EVENT_AP_STACONNECTED`_> will arise. Upon receiving this event, the event task will do nothing, and the application callback can also ignore it. However, you may want to do something, for example, to get the info of the connected STA, etc.
|
||||
|
||||
WIFI_EVENT_AP_STADISCONNECTED
|
||||
++++++++++++++++++++++++++++++++++++
|
||||
@@ -240,8 +240,8 @@ WIFI_EVENT_AP_PROBEREQRECVED
|
||||
This event is disabled by default. The application can enable it via API esp_wifi_set_event_mask().
|
||||
When this event is enabled, it will be raised each time the AP receives a probe request.
|
||||
|
||||
ESP32 Wi-Fi Station General Scenario
|
||||
---------------------------------------
|
||||
{IDF_TARGET_NAME} Wi-Fi Station General Scenario
|
||||
------------------------------------------------
|
||||
Below is a "big scenario" which describes some small scenarios in Station mode:
|
||||
|
||||
.. seqdiag::
|
||||
@@ -314,7 +314,7 @@ Step 1.1~1.5 is a recommended sequence that initializes a Wi-Fi-/LwIP-based appl
|
||||
|
||||
2. Wi-Fi Configuration Phase
|
||||
+++++++++++++++++++++++++++++++
|
||||
Once the Wi-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode is Station, so you may need to call esp_wifi_set_mode(WIFI_MODE_STA) to configure the Wi-Fi mode as Station. You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, country code, bandwidth, etc. Refer to <`ESP32 Wi-Fi Configuration`_>.
|
||||
Once the Wi-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode is Station, so you may need to call esp_wifi_set_mode(WIFI_MODE_STA) to configure the Wi-Fi mode as Station. You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, country code, bandwidth, etc. Refer to <`{IDF_TARGET_NAME} Wi-Fi Configuration`_>.
|
||||
|
||||
Generally, we configure the Wi-Fi driver before setting up the Wi-Fi connection, but this is **NOT** mandatory, which means that you can configure the Wi-Fi connection anytime, provided that the Wi-Fi driver is initialized successfully. However, if the configuration does not need to change after the Wi-Fi connection is set up, you should configure the Wi-Fi driver at this stage, because the configuration APIs (such as esp_wifi_set_protocol) will cause the Wi-Fi to reconnect, which may not be desirable.
|
||||
|
||||
@@ -363,7 +363,7 @@ In step 4.2, the Wi-Fi connection may fail because, for example, the password is
|
||||
- s8.3: Call esp_wifi_deinit() to unload the Wi-Fi driver.
|
||||
|
||||
|
||||
ESP32 Wi-Fi AP General Scenario
|
||||
{IDF_TARGET_NAME} Wi-Fi AP General Scenario
|
||||
---------------------------------------------
|
||||
Below is a "big scenario" which describes some small scenarios in AP mode:
|
||||
|
||||
@@ -411,8 +411,8 @@ Below is a "big scenario" which describes some small scenarios in AP mode:
|
||||
}
|
||||
|
||||
|
||||
ESP32 Wi-Fi Scan
|
||||
------------------------
|
||||
{IDF_TARGET_NAME} Wi-Fi Scan
|
||||
----------------------------
|
||||
|
||||
Currently, the esp_wifi_scan_start() API is supported only in Station or Station+AP mode.
|
||||
|
||||
@@ -662,7 +662,7 @@ If the block parameter of esp_wifi_scan_start() is true, then the scan is a bloc
|
||||
|
||||
Parallel Scan
|
||||
+++++++++++++
|
||||
Two application tasks may call esp_wifi_scan_start() at the same time, or the same application task calls esp_wifi_scan_start() before it gets a scan-done event. Both scenarios can happen. **However, the Wi-Fi driver does not support multiple concurrent scans adequately. As a result, concurrent scans should be avoided.** Support for concurrent scan will be enhanced in future releases, as the ESP32's Wi-Fi functionality improves continuously.
|
||||
Two application tasks may call esp_wifi_scan_start() at the same time, or the same application task calls esp_wifi_scan_start() before it gets a scan-done event. Both scenarios can happen. **However, the Wi-Fi driver does not support multiple concurrent scans adequately. As a result, concurrent scans should be avoided.** Support for concurrent scan will be enhanced in future releases, as the {IDF_TARGET_NAME}'s Wi-Fi functionality improves continuously.
|
||||
|
||||
Scan When Wi-Fi Is Connecting
|
||||
+++++++++++++++++++++++++++++++
|
||||
@@ -681,10 +681,10 @@ In above scenario the scan will never succeed because the connecting is in proce
|
||||
|
||||
The application can define its own reconnect strategy to avoid the scan starve to death. Refer to <`Wi-Fi Reconnect`_>.
|
||||
|
||||
ESP32 Wi-Fi Station Connecting Scenario
|
||||
----------------------------------------
|
||||
{IDF_TARGET_NAME} Wi-Fi Station Connecting Scenario
|
||||
---------------------------------------------------
|
||||
|
||||
This scenario only depicts the case when there is only one target AP are found in scan phase, for the scenario that more than one AP with the same SSID are found, refer to <`ESP32 Wi-Fi Station Connecting When Multiple APs Are Found`_>.
|
||||
This scenario only depicts the case when there is only one target AP are found in scan phase, for the scenario that more than one AP with the same SSID are found, refer to <`{IDF_TARGET_NAME} Wi-Fi Station Connecting When Multiple APs Are Found`_>.
|
||||
|
||||
Generally, the application does not need to care about the connecting process. Below is a brief introduction to the process for those who are really interested.
|
||||
|
||||
@@ -768,7 +768,7 @@ Four-way Handshake Phase
|
||||
Wi-Fi Reason Code
|
||||
+++++++++++++++++++++
|
||||
|
||||
The table below shows the reason-code defined in ESP32. The first column is the macro name defined in esp_wifi_types.h. The common prefix *WIFI_REASON* is removed, which means that *UNSPECIFIED* actually stands for *WIFI_REASON_UNSPECIFIED* and so on. The second column is the value of the reason. The third column is the standard value to which this reason is mapped in section 8.4.1.7 of ieee802.11-2012. (For more information, refer to the standard mentioned above.) The last column is a description of the reason.
|
||||
The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first column is the macro name defined in esp_wifi_types.h. The common prefix *WIFI_REASON* is removed, which means that *UNSPECIFIED* actually stands for *WIFI_REASON_UNSPECIFIED* and so on. The second column is the value of the reason. The third column is the standard value to which this reason is mapped in section 8.4.1.7 of ieee802.11-2012. (For more information, refer to the standard mentioned above.) The last column is a description of the reason.
|
||||
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| Reason code | Value |Mapped To| Description |
|
||||
@@ -779,12 +779,12 @@ The table below shows the reason-code defined in ESP32. The first column is the
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| AUTH_EXPIRE | 2 | 2 | The previous authentication is no longer valid. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - auth is timed out |
|
||||
| | | | - the reason is received from the AP. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 AP, this reason is reported when: |
|
||||
| | | | For the ESP AP, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - the AP has not received any packets from the station |
|
||||
| | | | in the past five minutes. |
|
||||
@@ -795,18 +795,18 @@ The table below shows the reason-code defined in ESP32. The first column is the
|
||||
| AUTH_LEAVE | 3 | 3 | De-authenticated, because the sending STA is |
|
||||
| | | | leaving (or has left). |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| ASSOC_EXPIRE | 4 | 4 | Disassociated due to inactivity. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 AP, this reason is reported when: |
|
||||
| | | | For the ESP AP, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - the AP has not received any packets from the |
|
||||
| | | | station in the past five minutes. |
|
||||
@@ -817,11 +817,11 @@ The table below shows the reason-code defined in ESP32. The first column is the
|
||||
| ASSOC_TOOMANY | 5 | 5 | Disassociated, because the AP is unable to handle |
|
||||
| | | | all currently associated STAs at the same time. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 AP, this reason is reported when: |
|
||||
| | | | For the ESP AP, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - the stations associated with the AP reach the |
|
||||
| | | | maximum number that the AP can support. |
|
||||
@@ -829,11 +829,11 @@ The table below shows the reason-code defined in ESP32. The first column is the
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| NOT_AUTHED | 6 | 6 | Class-2 frame received from a non-authenticated STA. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 AP, this reason is reported when: |
|
||||
| | | | For the ESP AP, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - the AP receives a packet with data from a |
|
||||
| | | | non-authenticated station. |
|
||||
@@ -841,11 +841,11 @@ The table below shows the reason-code defined in ESP32. The first column is the
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| NOT_ASSOCED | 7 | 7 | Class-3 frame received from a non-associated STA. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 AP, this reason is reported when: |
|
||||
| | | | For the ESP AP, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - the AP receives a packet with data from a |
|
||||
| | | | non-associated station. |
|
||||
@@ -854,7 +854,7 @@ The table below shows the reason-code defined in ESP32. The first column is the
|
||||
| ASSOC_LEAVE | 8 | 8 | Disassociated, because the sending STA is leaving (or has |
|
||||
| | | | left) BSS. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | - the station is disconnected by esp_wifi_disconnect() and |
|
||||
@@ -864,11 +864,11 @@ The table below shows the reason-code defined in ESP32. The first column is the
|
||||
| ASSOC_NOT_AUTHED | 9 | 9 | STA requesting (re)association is not authenticated by the |
|
||||
| | | | responding STA. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 AP, this reason is reported when: |
|
||||
| | | | For the ESP AP, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - the AP receives packets with data from an |
|
||||
| | | | associated, yet not authenticated, station. |
|
||||
@@ -877,7 +877,7 @@ The table below shows the reason-code defined in ESP32. The first column is the
|
||||
| DISASSOC_PWRCAP_BAD | 10 | 10 | Disassociated, because the information in the Power |
|
||||
| | | | Capability element is unacceptable. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
@@ -885,7 +885,7 @@ The table below shows the reason-code defined in ESP32. The first column is the
|
||||
| DISASSOC_SUPCHAN_BAD | 11 | 11 | Disassociated, because the information in the Supported |
|
||||
| | | | Channels element is unacceptable. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
@@ -893,27 +893,27 @@ The table below shows the reason-code defined in ESP32. The first column is the
|
||||
| IE_INVALID | 13 | 13 | Invalid element, i.e. an element whose content does not meet|
|
||||
| | | | the specifications of the Standard in Clause 8. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP |
|
||||
| | | | |
|
||||
| | | | For the ESP32 AP, this reason is reported when: |
|
||||
| | | | For the ESP AP, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - the AP parses a wrong WPA or RSN IE. |
|
||||
| | | | |
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| MIC_FAILURE | 14 | 14 | Message integrity code (MIC) failure. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| 4WAY_HANDSHAKE_TIMEOUT | 15 | 15 | Four-way handshake times out. For legacy reasons, in ESP32 |
|
||||
| 4WAY_HANDSHAKE_TIMEOUT | 15 | 15 | Four-way handshake times out. For legacy reasons, in ESP |
|
||||
| | | | this reason-code is replaced with |
|
||||
| | | | WIFI_REASON_HANDSHAKE_TIMEOUT. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - the handshake times out |
|
||||
| | | | - it is received from the AP. |
|
||||
@@ -921,7 +921,7 @@ The table below shows the reason-code defined in ESP32. The first column is the
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| GROUP_KEY_UPDATE_TIMEOUT | 16 | 16 | Group-Key Handshake times out. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 station, this reason is reported when: |
|
||||
| | | | For the ESP station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
@@ -929,7 +929,7 @@ The table below shows the reason-code defined in ESP32. The first column is the
|
||||
| IE_IN_4WAY_DIFFERS | 17 | 17 | The element in the four-way handshake is different from the |
|
||||
| | | | (Re-)Association Request/Probe and Response/Beacon frame. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 station, this reason is reported when: |
|
||||
| | | | For the ESP station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | - the station finds that the four-way handshake IE differs |
|
||||
@@ -939,53 +939,53 @@ The table below shows the reason-code defined in ESP32. The first column is the
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| GROUP_CIPHER_INVALID | 18 | 18 | Invalid group cipher. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| PAIRWISE_CIPHER_INVALID | 19 | 19 | Invalid pairwise cipher. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| AKMP_INVALID | 20 | 20 | Invalid AKMP. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| UNSUPP_RSN_IE_VERSION | 21 | 21 | Unsupported RSNE version. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| INVALID_RSN_IE_CAP | 22 | 22 | Invalid RSNE capabilities. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| 802_1X_AUTH_FAILED | 23 | 23 | IEEE 802.1X. authentication failed. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 AP, this reason is reported when: |
|
||||
| | | | For the ESP AP, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - 802.1 x authentication fails. |
|
||||
| | | | |
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
| CIPHER_SUITE_REJECTED | 24 | 24 | Cipher suite rejected due to security policies. |
|
||||
| | | | |
|
||||
| | | | For the ESP32 Station, this reason is reported when: |
|
||||
| | | | For the ESP Station, this reason is reported when: |
|
||||
| | | | |
|
||||
| | | | - it is received from the AP. |
|
||||
| | | | |
|
||||
@@ -1013,10 +1013,10 @@ The table below shows the reason-code defined in ESP32. The first column is the
|
||||
| | | | |
|
||||
+---------------------------+-------+---------+-------------------------------------------------------------+
|
||||
|
||||
ESP32 Wi-Fi Station Connecting When Multiple APs Are Found
|
||||
---------------------------------------------------------------
|
||||
{IDF_TARGET_NAME} Wi-Fi Station Connecting When Multiple APs Are Found
|
||||
----------------------------------------------------------------------
|
||||
|
||||
This scenario is similar as <`ESP32 Wi-Fi Station Connecting Scenario`_>, the difference is the station will not raise the event <`WIFI_EVENT_STA_DISCONNECTED`_> unless it fails to connect all of the found APs.
|
||||
This scenario is similar as <`{IDF_TARGET_NAME} Wi-Fi Station Connecting Scenario`_>, the difference is the station will not raise the event <`WIFI_EVENT_STA_DISCONNECTED`_> unless it fails to connect all of the found APs.
|
||||
|
||||
|
||||
Wi-Fi Reconnect
|
||||
@@ -1033,12 +1033,12 @@ Another thing we need to consider is the reconnect may not connect the same AP i
|
||||
Wi-Fi Beacon Timeout
|
||||
---------------------------
|
||||
|
||||
The beacon timeout mechanism is used by ESP32 station to detect whether the AP is alive or not. If the station continuously loses 60 beacons of the connected AP, the beacon timeout happens.
|
||||
The beacon timeout mechanism is used by {IDF_TARGET_NAME} station to detect whether the AP is alive or not. If the station continuously loses 60 beacons of the connected AP, the beacon timeout happens.
|
||||
|
||||
After the beacon timeout happens, the station sends 5 probe requests to AP, it disconnects the AP and raises the event <`WIFI_EVENT_STA_DISCONNECTED`_> if still no probe response or beacon is received from AP.
|
||||
|
||||
ESP32 Wi-Fi Configuration
|
||||
---------------------------
|
||||
{IDF_TARGET_NAME} Wi-Fi Configuration
|
||||
-------------------------------------
|
||||
|
||||
All configurations will be stored into flash when the Wi-Fi NVS is enabled; otherwise, refer to <`Wi-Fi NVS Flash`_>.
|
||||
|
||||
@@ -1071,8 +1071,8 @@ Call esp_wifi_set_mode() to set the Wi-Fi mode.
|
||||
| WIFI_MODE_APSTA | Station-AP coexistence mode: in this mode, esp_wifi_start() |
|
||||
| | will simultaneously init both the station and the AP. |
|
||||
| | This is done in station mode and AP mode. Please note |
|
||||
| | that the channel of the external AP, which the ESP32 Station |
|
||||
| | is connected to, has higher priority over the ESP32 AP |
|
||||
| | that the channel of the external AP, which the ESP Station |
|
||||
| | is connected to, has higher priority over the ESP AP |
|
||||
| | channel. |
|
||||
+------------------+--------------------------------------------------------------+
|
||||
|
||||
@@ -1169,7 +1169,7 @@ API esp_wifi_set_config() can be used to configure the AP. The table below descr
|
||||
| | sure the channel is within the required range. |
|
||||
| | For more details, refer to <`Wi-Fi Country Code`_>. |
|
||||
+------------------+--------------------------------------------------------------+
|
||||
| authmode | Auth mode of ESP32 AP; currently, ESP32 Wi-Fi does not |
|
||||
| authmode | Auth mode of ESP AP; currently, ESP Wi-Fi does not |
|
||||
| | support AUTH_WEP. If the authmode is an invalid value, |
|
||||
| | AP defaults the value to WIFI_AUTH_OPEN. |
|
||||
| | |
|
||||
@@ -1178,7 +1178,7 @@ API esp_wifi_set_config() can be used to configure the AP. The table below descr
|
||||
| | otherwise, it does broadcast the SSID. |
|
||||
| | |
|
||||
+------------------+--------------------------------------------------------------+
|
||||
| max_connection | Currently, ESP32 Wi-Fi supports up to 10 Wi-Fi connections. |
|
||||
| max_connection | Currently, ESP Wi-Fi supports up to 10 Wi-Fi connections. |
|
||||
| | If max_connection > 10, AP defaults the value to 10. |
|
||||
| | |
|
||||
+------------------+--------------------------------------------------------------+
|
||||
@@ -1219,7 +1219,7 @@ Currently, the IDF supports the following protocol modes:
|
||||
| | **This mode is an Espressif-patented mode which can achieve|
|
||||
| | a one-kilometer line of sight range. Please, make sure both|
|
||||
| | the station and the AP are connected to an |
|
||||
| | ESP32 device** |
|
||||
| | ESP device** |
|
||||
+--------------------+------------------------------------------------------------+
|
||||
|
||||
Long Range (LR)
|
||||
@@ -1230,7 +1230,7 @@ Long Range (LR) mode is an Espressif-patented Wi-Fi mode which can achieve a one
|
||||
LR Compitability
|
||||
*************************
|
||||
|
||||
Since LR is Espressif unique Wi-Fi mode, only ESP32 devices can transmit and receive the LR data. In other words, the ESP32 device should NOT transmit the data in LR data rate if the connected device doesn't support LR. The application can achieve this by configuring suitable Wi-Fi mode. If the negotiated mode supports LR, the ESP32 may transmit data in LR rate, otherwise, ESP32 will transmit all data in traditional Wi-Fi data rate.
|
||||
Since LR is Espressif unique Wi-Fi mode, only {IDF_TARGET_NAME} devices can transmit and receive the LR data. In other words, the {IDF_TARGET_NAME} device should NOT transmit the data in LR data rate if the connected device doesn't support LR. The application can achieve this by configuring suitable Wi-Fi mode. If the negotiated mode supports LR, the {IDF_TARGET_NAME} may transmit data in LR rate, otherwise, {IDF_TARGET_NAME} will transmit all data in traditional Wi-Fi data rate.
|
||||
|
||||
Following table depicts the Wi-Fi mode negotiation:
|
||||
|
||||
@@ -1255,9 +1255,9 @@ Following table depicts the Wi-Fi mode negotiation:
|
||||
In above table, the row is the Wi-Fi mode of AP and the column is the Wi-Fi mode of station. The "-" indicates Wi-Fi mode of the AP and station are not compatible.
|
||||
|
||||
According to the table, we can conclude that:
|
||||
- For LR enabled in ESP32 AP, it's incompatible with traditional 802.11 mode because the beacon is sent in LR mode.
|
||||
- For LR enabled in ESP32 station and the mode is NOT LR only mode, it's compatible with traditional 802.11 mode.
|
||||
- If both station and AP are ESP32 devices and both of them enable LR mode, the negotiated mode supports LR.
|
||||
- For LR enabled in {IDF_TARGET_NAME} AP, it's incompatible with traditional 802.11 mode because the beacon is sent in LR mode.
|
||||
- For LR enabled in {IDF_TARGET_NAME} station and the mode is NOT LR only mode, it's compatible with traditional 802.11 mode.
|
||||
- If both station and AP are {IDF_TARGET_NAME} devices and both of them enable LR mode, the negotiated mode supports LR.
|
||||
|
||||
If the negotiated Wi-Fi mode supports both traditional 802.11 mode and LR mode, it's the WiFi driver's responsibility to automatically select the best data rate in different Wi-Fi mode and the application don't need to care about it.
|
||||
|
||||
@@ -1284,7 +1284,7 @@ When to Use LR
|
||||
*************************
|
||||
|
||||
The general conditions for using LR are:
|
||||
- Both the AP and station are ESP32 devices.
|
||||
- Both the AP and station are devices.
|
||||
- Long distance WiFi connection and data transmission is required.
|
||||
- Data throughput requirements are very small, such as remote device control, etc.
|
||||
|
||||
@@ -1387,18 +1387,18 @@ Following table depicts which country info is used in different WiFi Mode and di
|
||||
Home Channel
|
||||
*************************
|
||||
|
||||
In AP mode, the home channel is defined as that of the AP channel. In Station mode, the home channel is defined as the channel of the AP to which the station is connected. In Station+AP mode, the home channel of AP and station must be the same. If the home channels of Station and AP are different, the station's home channel is always in priority. Take the following as an example: at the beginning, the AP is on channel 6, then the station connects to an AP whose channel is 9. Since the station's home channel has a higher priority, the AP needs to switch its channel from 6 to 9 to make sure that both station and AP have the same home channel. While switching channel, the ESP32 in SoftAP mode will notify the connected stations about the channel migration using a Channel Switch Announcement (CSA). Stations that support channel switching will transition smoothly whereas stations who do not will disconnect and reconnect to the SoftAP.
|
||||
In AP mode, the home channel is defined as that of the AP channel. In Station mode, the home channel is defined as the channel of the AP to which the station is connected. In Station+AP mode, the home channel of AP and station must be the same. If the home channels of Station and AP are different, the station's home channel is always in priority. Take the following as an example: at the beginning, the AP is on channel 6, then the station connects to an AP whose channel is 9. Since the station's home channel has a higher priority, the AP needs to switch its channel from 6 to 9 to make sure that both station and AP have the same home channel. While switching channel, the {IDF_TARGET_NAME} in SoftAP mode will notify the connected stations about the channel migration using a Channel Switch Announcement (CSA). Stations that support channel switching will transition smoothly whereas stations who do not will disconnect and reconnect to the SoftAP.
|
||||
|
||||
|
||||
Wi-Fi Vendor IE Configuration
|
||||
+++++++++++++++++++++++++++++++++++
|
||||
|
||||
By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and the application does not need to care about them. Some applications, however, may have to handle the beacon, probe request, probe response and other management frames. For example, if you insert some vendor-specific IE into the management frames, it is only the management frames which contain this vendor-specific IE that will be processed. In ESP32, esp_wifi_set_vendor_ie() and esp_wifi_set_vendor_ie_cb() are responsible for this kind of tasks.
|
||||
By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and the application does not need to care about them. Some applications, however, may have to handle the beacon, probe request, probe response and other management frames. For example, if you insert some vendor-specific IE into the management frames, it is only the management frames which contain this vendor-specific IE that will be processed. In {IDF_TARGET_NAME}, esp_wifi_set_vendor_ie() and esp_wifi_set_vendor_ie_cb() are responsible for this kind of tasks.
|
||||
|
||||
Wi-Fi Security
|
||||
-------------------------------
|
||||
|
||||
In addition to traditional security methods (WEP/WPA-TKIP/WPA2-CCMP), ESP32 Wi-Fi now supports state-of-the-art security protocols, namely Protected Management Frames based on 802.11w standard and Wi-Fi Protected Access 3 (WPA3-Personal). Together, PMF and WPA3 provide better privacy and robustness against known attacks in traditional modes.
|
||||
In addition to traditional security methods (WEP/WPA-TKIP/WPA2-CCMP), {IDF_TARGET_NAME} Wi-Fi now supports state-of-the-art security protocols, namely Protected Management Frames based on 802.11w standard and Wi-Fi Protected Access 3 (WPA3-Personal). Together, PMF and WPA3 provide better privacy and robustness against known attacks in traditional modes.
|
||||
|
||||
Protected Management Frames (PMF)
|
||||
++++++++++++++++++++++++++++++++++
|
||||
@@ -1414,11 +1414,11 @@ An attacker can use eavesdropping and packet injection to send spoofed (de)authe
|
||||
|
||||
PMF provides protection against these attacks by encrypting unicast management frames and providing integrity checks for broadcast management frames. These include deauthentication, disassociation and robust management frames. It also provides Secure Association (SA) teardown mechanism to prevent spoofed association/authentication frames from disconnecting already connected clients.
|
||||
|
||||
ESP32 supports the following three modes of operation with respect to PMF.
|
||||
{IDF_TARGET_NAME} supports the following three modes of operation with respect to PMF.
|
||||
|
||||
- PMF not supported: In this mode, ESP32 indicates to AP that it is not capable of supporting management protection during association. In effect, security in this mode will be equivalent to that in traditional mode.
|
||||
- PMF capable, but not required: In this mode, ESP32 indicates to AP that it is capable of supporting PMF. The management protection will be used if AP mandates PMF or is at least capable of supporting PMF.
|
||||
- PMF capable and required: In this mode, ESP32 will only connect to AP, if AP supports PMF. If not, ESP32 will refuse to connect to the AP.
|
||||
- PMF not supported: In this mode, {IDF_TARGET_NAME} indicates to AP that it is not capable of supporting management protection during association. In effect, security in this mode will be equivalent to that in traditional mode.
|
||||
- PMF capable, but not required: In this mode, {IDF_TARGET_NAME} indicates to AP that it is capable of supporting PMF. The management protection will be used if AP mandates PMF or is at least capable of supporting PMF.
|
||||
- PMF capable and required: In this mode, {IDF_TARGET_NAME} will only connect to AP, if AP supports PMF. If not, {IDF_TARGET_NAME} will refuse to connect to the AP.
|
||||
|
||||
:cpp:func:`esp_wifi_set_config` can be used to configure PMF mode by setting appropriate flags in `pmf_cfg` parameter. Currently, PMF is supported only in Station mode.
|
||||
|
||||
@@ -1428,15 +1428,15 @@ WPA3-Personal
|
||||
|
||||
Wi-Fi Protected Access-3 (WPA3) is a set of enhancements to Wi-Fi access security intended to replace the current WPA2 standard. In order to provide more robust authentication, WPA3 uses Simultaneous Authentication of Equals (SAE), which is password-authenticated key agreement method based on Diffie-Hellman key exchange. Unlike WPA2, the technology is resistant to offline-dictionary attack, where the attacker attempts to determine shared password based on captured 4-way handshake without any further network interaction. WPA3 also provides forward secrecy, which means the captured data cannot be decrypted even if password is compromised after data transmission. Please refer to `Security <https://www.wi-fi.org/discover-wi-fi/security>`_ section of Wi-Fi Alliance's official website for further details.
|
||||
|
||||
In order to enable WPA3-Personal, "Enable WPA3-Personal" should be selected in menuconfig. If enabled, ESP32 uses SAE for authentication if supported by the AP. Since PMF is a mandatory requirement for WPA3, PMF capability should be at least set to "PMF capable, but not required" for ESP32 to use WPA3 mode. Application developers need not worry about the underlying security mode as highest available is chosen from security standpoint. Note that Wi-Fi stack size requirement will increase approximately by 3k when WPA3 is used. Currently, WPA3 is supported only in Station mode.
|
||||
In order to enable WPA3-Personal, "Enable WPA3-Personal" should be selected in menuconfig. If enabled, {IDF_TARGET_NAME} uses SAE for authentication if supported by the AP. Since PMF is a mandatory requirement for WPA3, PMF capability should be at least set to "PMF capable, but not required" for {IDF_TARGET_NAME} to use WPA3 mode. Application developers need not worry about the underlying security mode as highest available is chosen from security standpoint. Note that Wi-Fi stack size requirement will increase approximately by 3k when WPA3 is used. Currently, WPA3 is supported only in Station mode.
|
||||
|
||||
ESP32 Wi-Fi Power-saving Mode
|
||||
-----------------------------------
|
||||
{IDF_TARGET_NAME} Wi-Fi Power-saving Mode
|
||||
-----------------------------------------
|
||||
|
||||
Station Sleep
|
||||
++++++++++++++++++++++
|
||||
|
||||
Currently, ESP32 Wi-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 protocol. Modem-sleep mode works in Station-only mode and the station must connect to the AP first. If the Modem-sleep mode is enabled, station will switch between active and sleep state periodically. In sleep state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem-sleep mode.
|
||||
Currently, {IDF_TARGET_NAME} Wi-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 protocol. Modem-sleep mode works in Station-only mode and the station must connect to the AP first. If the Modem-sleep mode is enabled, station will switch between active and sleep state periodically. In sleep state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem-sleep mode.
|
||||
|
||||
Modem-sleep mode includes minimum and maximum power save modes. In minimum power save mode, station wakes up every DTIM to receive beacon. Broadcast data will not be lost because it is transmitted after DTIM. However, it can not save much more power if DTIM is short for DTIM is determined by AP.
|
||||
|
||||
@@ -1451,20 +1451,20 @@ The default Modem-sleep mode is WIFI_PS_MIN_MODEM.
|
||||
AP Sleep
|
||||
+++++++++++++++++++++++++++++++
|
||||
|
||||
Currently ESP32 AP doesn't support all of the power save feature defined in Wi-Fi specification. To be specific, the AP only caches unicast data for the stations connect to this AP, but doesn't cache the multicast data for the stations. If stations connected to the ESP32 AP are power save enabled, they may experience multicast packet loss.
|
||||
Currently {IDF_TARGET_NAME} AP doesn't support all of the power save feature defined in Wi-Fi specification. To be specific, the AP only caches unicast data for the stations connect to this AP, but doesn't cache the multicast data for the stations. If stations connected to the {IDF_TARGET_NAME} AP are power save enabled, they may experience multicast packet loss.
|
||||
|
||||
In future, all power save features will be supported on ESP32 AP.
|
||||
In future, all power save features will be supported on {IDF_TARGET_NAME} AP.
|
||||
|
||||
ESP32 Wi-Fi Connect Crypto
|
||||
-----------------------------------
|
||||
Now ESP32 have two group crypto functions can be used when do wifi connect, one is the original functions, the other is optimized by ESP hardware:
|
||||
{IDF_TARGET_NAME} Wi-Fi Connect Crypto
|
||||
--------------------------------------
|
||||
Now {IDF_TARGET_NAME} have two group crypto functions can be used when do wifi connect, one is the original functions, the other is optimized by ESP hardware:
|
||||
1. Original functions which is the source code used in the folder components/wpa_supplicant/src/crypto function;
|
||||
2. The optimized functions is in the folder components/wpa_supplicant/src/fast_crypto, these function used the hardware crypto to make it faster than origin one, the type of function's name add `fast_` to distinguish with the original one. For example, the API aes_wrap() is used to encrypt frame information when do 4 way handshake, the fast_aes_wrap() has the same result but can be faster.
|
||||
|
||||
Two groups of crypto function can be used when register in the wpa_crypto_funcs_t, wpa2_crypto_funcs_t and wps_crypto_funcs_t structure, also we have given the recommend functions to register in the
|
||||
fast_crypto_ops.c, you can register the function as the way you need, however what should make action is that the crypto_hash_xxx function and crypto_cipher_xxx function need to register with the same function to operation. For example, if you register crypto_hash_init() function to initialize the esp_crypto_hash structure, you need use the crypto_hash_update() and crypto_hash_finish() function to finish the operation, rather than fast_crypto_hash_update() or fast_crypto_hash_finish().
|
||||
|
||||
ESP32 Wi-Fi Throughput
|
||||
{IDF_TARGET_NAME} Wi-Fi Throughput
|
||||
-----------------------------------
|
||||
|
||||
The table below shows the best throughput results we got in Espressif's lab and in a shield box.
|
||||
@@ -1504,7 +1504,7 @@ Preconditions of Using esp_wifi_80211_tx
|
||||
++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
- The Wi-Fi mode is Station, or AP, or Station+AP.
|
||||
- Either esp_wifi_set_promiscuous(true), or esp_wifi_start(), or both of these APIs return ESP_OK. This is because we need to make sure that Wi-Fi hardware is initialized before esp_wifi_80211_tx() is called. In ESP32, both esp_wifi_set_promiscuous(true) and esp_wifi_start() can trigger the initialization of Wi-Fi hardware.
|
||||
- Either esp_wifi_set_promiscuous(true), or esp_wifi_start(), or both of these APIs return ESP_OK. This is because we need to make sure that Wi-Fi hardware is initialized before esp_wifi_80211_tx() is called. In {IDF_TARGET_NAME}, both esp_wifi_set_promiscuous(true) and esp_wifi_start() can trigger the initialization of Wi-Fi hardware.
|
||||
- The parameters of esp_wifi_80211_tx are hereby correctly provided.
|
||||
|
||||
Data rate
|
||||
@@ -1636,9 +1636,9 @@ The Wi-Fi multiple antennas selecting can be depicted as following picture::
|
||||
|__________|
|
||||
|
||||
|
||||
ESP32 supports up to sixteen antennas through external antenna switch. The antenna switch can be controlled by up to four address pins - antenna_select[0:3]. Different input value of antenna_select[0:3] means selecting different antenna. E.g. the value '0b1011' means the antenna 11 is selected. The default value of antenna_select[3:0] is '0b0000', it means the antenna 0 is selected by default.
|
||||
{IDF_TARGET_NAME} supports up to sixteen antennas through external antenna switch. The antenna switch can be controlled by up to four address pins - antenna_select[0:3]. Different input value of antenna_select[0:3] means selecting different antenna. E.g. the value '0b1011' means the antenna 11 is selected. The default value of antenna_select[3:0] is '0b0000', it means the antenna 0 is selected by default.
|
||||
|
||||
Up to four GPIOs are connected to the four active high antenna_select pins. ESP32 can select the antenna by control the GPIO[0:3]. The API :cpp:func:`esp_wifi_set_ant_gpio()` is used to configure which GPIOs are connected to antenna_selects. If GPIO[x] is connected to antenna_select[x], then gpio_config->gpio_cfg[x].gpio_select should be set to 1 and gpio_config->gpio_cfg[x].gpio_num should be provided.
|
||||
Up to four GPIOs are connected to the four active high antenna_select pins. {IDF_TARGET_NAME} can select the antenna by control the GPIO[0:3]. The API :cpp:func:`esp_wifi_set_ant_gpio()` is used to configure which GPIOs are connected to antenna_selects. If GPIO[x] is connected to antenna_select[x], then gpio_config->gpio_cfg[x].gpio_select should be set to 1 and gpio_config->gpio_cfg[x].gpio_num should be provided.
|
||||
|
||||
Although up to sixteen anteenas are supported, only one or two antennas can be simultaneously enabled for RX/TX. The API :cpp:func:`esp_wifi_set_ant()` is used to configure which antennas are enabled.
|
||||
|
||||
@@ -1679,7 +1679,7 @@ Generally, following steps can be taken to configure the multiple antennas:
|
||||
Wi-Fi Channel State Information
|
||||
------------------------------------
|
||||
|
||||
Channel state information (CSI) refers to the channel information of a Wi-Fi connection. In ESP32, this information consists of channel frequency responses of sub-carriers and is estimated when packets are received from the transmitter. Each channel frequency response of sub-carrier is recorded by two bytes of signed characters. The first one is imaginary part and the second one is real part. There are up to three fields of channel frequency responses according to the type of received packet. They are legacy long training field (LLTF), high throughput LTF (HT-LTF) and space time block code HT-LTF (STBC-HT-LTF). For different types of packets which are received on channels with different state, the sub-carrier index and total bytes of signed characters of CSI is shown in the following table.
|
||||
Channel state information (CSI) refers to the channel information of a Wi-Fi connection. In {IDF_TARGET_NAME}, this information consists of channel frequency responses of sub-carriers and is estimated when packets are received from the transmitter. Each channel frequency response of sub-carrier is recorded by two bytes of signed characters. The first one is imaginary part and the second one is real part. There are up to three fields of channel frequency responses according to the type of received packet. They are legacy long training field (LLTF), high throughput LTF (HT-LTF) and space time block code HT-LTF (STBC-HT-LTF). For different types of packets which are received on channels with different state, the sub-carrier index and total bytes of signed characters of CSI is shown in the following table.
|
||||
|
||||
+-------------+--------------------+-----------------------------------------+--------------------------------------------------------+----------------------------------------------------------+
|
||||
| channel | secondary channel | none | below | above |
|
||||
@@ -1707,7 +1707,7 @@ All of the information in the table can be found in the structure wifi_csi_info_
|
||||
- STBC refers to stbc field of rx_ctrl field.
|
||||
- Total bytes refers to len field.
|
||||
- The CSI data corresponding to each Long Training Field(LTF) type is stored in a buffer starting from the buf field. Each item is stored as two bytes: imaginary part followed by real part. The order of each item is the same as the sub-carrier in the table. The order of LTF is: LLTF, HT-LTF, STBC-HT-LTF. However all 3 LTFs may not be present, depending on the channel and packet information (see above).
|
||||
- If first_word_invalid field of wifi_csi_info_t is true, it means that the first four bytes of CSI data is invalid due to a hardware limitation in ESP32.
|
||||
- If first_word_invalid field of wifi_csi_info_t is true, it means that the first four bytes of CSI data is invalid due to a hardware limitation in {IDF_TARGET_NAME}.
|
||||
- More information like RSSI, noise floor of RF, receiving time and antenna is in the rx_ctrl field.
|
||||
|
||||
.. note::
|
||||
@@ -1730,24 +1730,24 @@ The CSI receiving callback function runs from Wi-Fi task. So, do not do lengthy
|
||||
Wi-Fi HT20/40
|
||||
-------------------------
|
||||
|
||||
ESP32 supports Wi-Fi bandwidth HT20 or HT40, it doesn't support HT20/40 coexist. `esp_wifi_set_bandwidth` can be used to change the default bandwidth of station or AP. The default bandwidth for ESP32 station and AP is HT40.
|
||||
{IDF_TARGET_NAME} supports Wi-Fi bandwidth HT20 or HT40, it doesn't support HT20/40 coexist. `esp_wifi_set_bandwidth` can be used to change the default bandwidth of station or AP. The default bandwidth for {IDF_TARGET_NAME} station and AP is HT40.
|
||||
|
||||
In station mode, the actual bandwidth is firstly negotiated during the Wi-Fi connection. It is HT40 only if both the station and the connected AP support HT40, otherwise it's HT20. If the bandwidth of connected AP is changes, the actual bandwidth is negotiated again without Wi-Fi disconnecting.
|
||||
|
||||
Similarly, in AP mode, the actual bandwidth is negotiated between AP and the stations that connect to the AP. It's HT40 if the AP and one of the stations support HT40, otherwise it's HT20.
|
||||
|
||||
In station/AP coexist mode, the station/AP can configure HT20/40 seperately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in ESP32. E.g. the configured bandwidth of AP is HT40, the configured primary channel is 6 and the configured secondary channel is 10. The station is connected to an router whose primary channel is 6 and secondary channel is 2, then the actual channel of AP is changed to primary 6 and secondary 2 automatically.
|
||||
In station/AP coexist mode, the station/AP can configure HT20/40 seperately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in {IDF_TARGET_NAME}. E.g. the configured bandwidth of AP is HT40, the configured primary channel is 6 and the configured secondary channel is 10. The station is connected to an router whose primary channel is 6 and secondary channel is 2, then the actual channel of AP is changed to primary 6 and secondary 2 automatically.
|
||||
|
||||
Theoretically the HT40 can gain better throughput because the maximum raw physicial (PHY) data rate for HT40 is 150Mbps while it's 72Mbps for HT20. However, if the device is used in some special environment, e.g. there are too many other Wi-Fi devices around the ESP32 device, the performance of HT40 may be degraded. So if the applications need to support same or similar scenarios, it's recommended that the bandwidth is always configured to HT20.
|
||||
Theoretically the HT40 can gain better throughput because the maximum raw physicial (PHY) data rate for HT40 is 150Mbps while it's 72Mbps for HT20. However, if the device is used in some special environment, e.g. there are too many other Wi-Fi devices around the {IDF_TARGET_NAME} device, the performance of HT40 may be degraded. So if the applications need to support same or similar scenarios, it's recommended that the bandwidth is always configured to HT20.
|
||||
|
||||
Wi-Fi QoS
|
||||
-------------------------
|
||||
|
||||
ESP32 supports all the mandatory features required in WFA Wi-Fi QoS Certification.
|
||||
{IDF_TARGET_NAME} supports all the mandatory features required in WFA Wi-Fi QoS Certification.
|
||||
|
||||
Four ACs(Access Category) are defined in Wi-Fi specification, each AC has a its own priority to access the Wi-Fi channel. Moreover a map rule is defined to map the QoS priority of other protocol, such as 802.11D or TCP/IP precedence to Wi-Fi AC.
|
||||
|
||||
Below is a table describes how the IP Precedences are mapped to Wi-Fi ACs in ESP32, it also indicates whether the AMPDU is supported for this AC. The table is sorted with priority descending order, namely, the AC_VO has highest priority.
|
||||
Below is a table describes how the IP Precedences are mapped to Wi-Fi ACs in {IDF_TARGET_NAME}, it also indicates whether the AMPDU is supported for this AC. The table is sorted with priority descending order, namely, the AC_VO has highest priority.
|
||||
|
||||
+------------------+------------------------+-----------------+
|
||||
| IP Precedence | Wi-Fi AC | Support AMPDU? |
|
||||
@@ -1776,17 +1776,17 @@ Theoretically the higher priority AC has better performance than the low priorit
|
||||
Wi-Fi AMSDU
|
||||
-------------------------
|
||||
|
||||
ESP32 supports receiving AMSDU but doesn't support transmitting AMSDU. The transmitting AMSDU is not necessary since ESP32 has transmitting AMPDU.
|
||||
{IDF_TARGET_NAME} supports receiving AMSDU but doesn't support transmitting AMSDU. The transmitting AMSDU is not necessary since {IDF_TARGET_NAME} has transmitting AMPDU.
|
||||
|
||||
Wi-Fi Fragment
|
||||
-------------------------
|
||||
|
||||
ESP32 supports Wi-Fi receiving fragment, but doesn't support Wi-Fi transmitting fragment. The Wi-Fi transmitting fragment will be supported in future release.
|
||||
{IDF_TARGET_NAME} supports Wi-Fi receiving fragment, but doesn't support Wi-Fi transmitting fragment. The Wi-Fi transmitting fragment will be supported in future release.
|
||||
|
||||
WPS Enrolle
|
||||
-------------------------
|
||||
|
||||
ESP32 supports WPS enrollee feature in Wi-Fi mode WIFI_MODE_STA or WIFI_MODE_APSTA. Currently ESP32 supports WPS enrollee type PBC and PIN.
|
||||
{IDF_TARGET_NAME} supports WPS enrollee feature in Wi-Fi mode WIFI_MODE_STA or WIFI_MODE_APSTA. Currently {IDF_TARGET_NAME} supports WPS enrollee type PBC and PIN.
|
||||
|
||||
.. _wifi-buffer-usage:
|
||||
|
||||
@@ -1799,11 +1799,11 @@ Why Buffer Configuration Is Important
|
||||
+++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
In order to get a robust, high-performance system, we need to consider the memory usage/configuration very carefully, because:
|
||||
- the available memory in ESP32 is limited.
|
||||
- the available memory in {IDF_TARGET_NAME} is limited.
|
||||
- currently, the default type of buffer in LwIP and Wi-Fi drivers is "dynamic", **which means that both the LwIP and Wi-Fi share memory with the application**. Programmers should always keep this in mind; otherwise, they will face a memory issue, such as "running out of heap memory".
|
||||
- it is very dangerous to run out of heap memory, as this will cause ESP32 an "undefined behavior". Thus, enough heap memory should be reserved for the application, so that it never runs out of it.
|
||||
- it is very dangerous to run out of heap memory, as this will cause {IDF_TARGET_NAME} an "undefined behavior". Thus, enough heap memory should be reserved for the application, so that it never runs out of it.
|
||||
- the Wi-Fi throughput heavily depends on memory-related configurations, such as the TCP window size, Wi-Fi RX/TX dynamic buffer number, etc.
|
||||
- the peak heap memory that the ESP32 LwIP/Wi-Fi may consume depends on a number of factors, such as the maximum TCP/UDP connections that the application may have, etc.
|
||||
- the peak heap memory that the {IDF_TARGET_NAME} LwIP/Wi-Fi may consume depends on a number of factors, such as the maximum TCP/UDP connections that the application may have, etc.
|
||||
- the total memory that the application requires is also an important factor when considering memory configuration.
|
||||
|
||||
Due to these reasons, there is not a good-for-all application configuration. Rather, we have to consider memory configurations separately for every different application.
|
||||
@@ -1994,7 +1994,7 @@ If the Wi-Fi NVS flash is enabled, all Wi-Fi configurations set via the Wi-Fi AP
|
||||
Wi-Fi AMPDU
|
||||
+++++++++++++++++++++++++++
|
||||
|
||||
ESP32 supports both receiving and transmitting AMPDU, the AMPDU can greatly improve the Wi-Fi throughput.
|
||||
{IDF_TARGET_NAME} supports both receiving and transmitting AMPDU, the AMPDU can greatly improve the Wi-Fi throughput.
|
||||
|
||||
Generally, the AMPDU should be enabled. Disabling AMPDU is usually for debugging purposes.
|
||||
|
||||
|
||||
@@ -18,4 +18,4 @@ Check :example:`bluetooth/bluedroid/hci` folder in ESP-IDF examples, which conta
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_bt.inc
|
||||
.. include-build-file:: inc/esp_bt.inc
|
||||
|
||||
@@ -42,7 +42,7 @@ This section contains only one header file, which lists the following items of E
|
||||
* Structs used to transmit/receive messages
|
||||
* Event types and related event parameters
|
||||
|
||||
.. include:: /_build/inc/esp_ble_mesh_defs.inc
|
||||
.. include-build-file:: inc/esp_ble_mesh_defs.inc
|
||||
|
||||
|
||||
ESP-BLE-MESH Core API Reference
|
||||
@@ -64,37 +64,37 @@ This API reference covers six components:
|
||||
ESP-BLE-MESH Stack Initialization
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/esp_ble_mesh_common_api.inc
|
||||
.. include-build-file:: inc/esp_ble_mesh_common_api.inc
|
||||
|
||||
|
||||
Reading of Local Data Information
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/esp_ble_mesh_local_data_operation_api.inc
|
||||
.. include-build-file:: inc/esp_ble_mesh_local_data_operation_api.inc
|
||||
|
||||
|
||||
Low Power Operation (Updating)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/esp_ble_mesh_low_power_api.inc
|
||||
.. include-build-file:: inc/esp_ble_mesh_low_power_api.inc
|
||||
|
||||
|
||||
Send/Publish Messages, add Local AppKey, etc.
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/esp_ble_mesh_networking_api.inc
|
||||
.. include-build-file:: inc/esp_ble_mesh_networking_api.inc
|
||||
|
||||
|
||||
ESP-BLE-MESH Node/Provisioner Provisioning
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/esp_ble_mesh_provisioning_api.inc
|
||||
.. include-build-file:: inc/esp_ble_mesh_provisioning_api.inc
|
||||
|
||||
|
||||
ESP-BLE-MESH GATT Proxy Server
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/esp_ble_mesh_proxy_api.inc
|
||||
.. include-build-file:: inc/esp_ble_mesh_proxy_api.inc
|
||||
|
||||
|
||||
ESP-BLE-MESH Models API Reference
|
||||
@@ -120,35 +120,35 @@ There are six categories of models:
|
||||
Configuration Client/Server Models
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/esp_ble_mesh_config_model_api.inc
|
||||
.. include-build-file:: inc/esp_ble_mesh_config_model_api.inc
|
||||
|
||||
|
||||
Health Client/Server Models
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/esp_ble_mesh_generic_model_api.inc
|
||||
.. include-build-file:: inc/esp_ble_mesh_generic_model_api.inc
|
||||
|
||||
|
||||
Generic Client/Server Models
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/esp_ble_mesh_health_model_api.inc
|
||||
.. include-build-file:: inc/esp_ble_mesh_health_model_api.inc
|
||||
|
||||
|
||||
Sensor Client/Server Models
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/esp_ble_mesh_lighting_model_api.inc
|
||||
.. include-build-file:: inc/esp_ble_mesh_lighting_model_api.inc
|
||||
|
||||
|
||||
Time and Scenes Client/Server Models
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/esp_ble_mesh_sensor_model_api.inc
|
||||
.. include-build-file:: inc/esp_ble_mesh_sensor_model_api.inc
|
||||
|
||||
|
||||
Lighting Client/Server Models
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/esp_ble_mesh_time_scene_model_api.inc
|
||||
.. include-build-file:: inc/esp_ble_mesh_time_scene_model_api.inc
|
||||
|
||||
|
||||
@@ -18,5 +18,5 @@ Check :example:`bluetooth/bluedroid/classic_bt` folder in ESP-IDF examples, whic
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_a2dp_api.inc
|
||||
.. include-build-file:: inc/esp_a2dp_api.inc
|
||||
|
||||
|
||||
@@ -18,6 +18,6 @@ Application Example
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_avrc_api.inc
|
||||
.. include-build-file:: inc/esp_avrc_api.inc
|
||||
|
||||
|
||||
|
||||
@@ -19,5 +19,5 @@ Check :example:`bluetooth/bluedroid/ble` folder in ESP-IDF examples, which conta
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_blufi_api.inc
|
||||
.. include-build-file:: inc/esp_blufi_api.inc
|
||||
|
||||
|
||||
@@ -17,5 +17,5 @@ Application Example
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_bt_defs.inc
|
||||
.. include-build-file:: inc/esp_bt_defs.inc
|
||||
|
||||
|
||||
@@ -18,4 +18,4 @@ Application Example
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_bt_device.inc
|
||||
.. include-build-file:: inc/esp_bt_device.inc
|
||||
|
||||
@@ -17,6 +17,6 @@ Application Example
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_bt_main.inc
|
||||
.. include-build-file:: inc/esp_bt_main.inc
|
||||
|
||||
|
||||
|
||||
@@ -26,5 +26,5 @@ Check :example:`bluetooth/bluedroid/ble` folder in ESP-IDF examples, which conta
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_gap_ble_api.inc
|
||||
.. include-build-file:: inc/esp_gap_ble_api.inc
|
||||
|
||||
|
||||
@@ -16,5 +16,5 @@ Application Example
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_gap_bt_api.inc
|
||||
.. include-build-file:: inc/esp_gap_bt_api.inc
|
||||
|
||||
|
||||
@@ -16,6 +16,6 @@ Application Example
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_gatt_defs.inc
|
||||
.. include-build-file:: inc/esp_gatt_defs.inc
|
||||
|
||||
|
||||
|
||||
@@ -30,5 +30,5 @@ Check :example:`bluetooth/bluedroid/ble` folder in ESP-IDF examples, which conta
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_gattc_api.inc
|
||||
.. include-build-file:: inc/esp_gattc_api.inc
|
||||
|
||||
|
||||
@@ -30,5 +30,5 @@ Check :example:`bluetooth/bluedroid/ble` folder in ESP-IDF examples, which conta
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_gatts_api.inc
|
||||
.. include-build-file:: inc/esp_gatts_api.inc
|
||||
|
||||
|
||||
@@ -1,14 +1,7 @@
|
||||
HFP AG API
|
||||
==============
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
`Instructions`_
|
||||
|
||||
.. _Instructions: ../template.html
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_hf_ag_api.inc
|
||||
.. include-build-file:: inc/esp_hf_ag_api.inc
|
||||
|
||||
@@ -11,4 +11,4 @@ Overview
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_hf_client_api.inc
|
||||
.. include-build-file:: inc/esp_hf_client_api.inc
|
||||
|
||||
@@ -11,6 +11,6 @@ Overview
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_hf_defs.inc
|
||||
.. include-build-file:: inc/esp_hf_defs.inc
|
||||
|
||||
|
||||
|
||||
@@ -18,5 +18,5 @@ Check :example:`bluetooth/bluedroid/classic_bt` folder in ESP-IDF examples, whic
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_spp_api.inc
|
||||
.. include-build-file:: inc/esp_spp_api.inc
|
||||
|
||||
|
||||
@@ -41,4 +41,4 @@ This documentation does not cover NimBLE APIs. Refer to `NimBLE tutorial <https:
|
||||
API Reference
|
||||
=============
|
||||
|
||||
.. include:: /_build/inc/esp_nimble_hci.inc
|
||||
.. include-build-file:: inc/esp_nimble_hci.inc
|
||||
|
||||
@@ -5,4 +5,4 @@ This section lists various error code constants defined in ESP-IDF.
|
||||
|
||||
For general information about error codes in ESP-IDF, see :doc:`Error Handling <../api-guides/error-handling>`.
|
||||
|
||||
.. include:: /_build/inc/esp_err_defs.inc
|
||||
.. include-build-file:: inc/esp_err_defs.inc
|
||||
|
||||
@@ -6,7 +6,7 @@ API Reference
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
Bluetooth <bluetooth/index>
|
||||
:esp32: Bluetooth <bluetooth/index>
|
||||
Networking <network/index>
|
||||
Peripherals <peripherals/index>
|
||||
Protocols <protocols/index>
|
||||
|
||||
@@ -85,7 +85,7 @@ Subsequent sections contain the list of available ESP-IDF options, automatically
|
||||
By convention, all option names are upper case with underscores. When Kconfig generates sdkconfig and sdkconfig.h files, option names are prefixed with ``CONFIG_``. So if an option ``ENABLE_FOO`` is defined in a Kconfig file and selected in menuconfig, then sdkconfig and sdkconfig.h files will have ``CONFIG_ENABLE_FOO`` defined. In this reference, option names are also prefixed with ``CONFIG_``, same as in the source code.
|
||||
|
||||
|
||||
.. include:: /_build/inc/kconfig.inc
|
||||
.. include-build-file:: inc/kconfig.inc
|
||||
|
||||
Customisations
|
||||
==============
|
||||
|
||||
@@ -37,24 +37,24 @@ Ethernet PHY Common Registers
|
||||
API Reference - Driver Model
|
||||
----------------------------
|
||||
|
||||
.. include:: /_build/inc/esp_eth.inc
|
||||
.. include-build-file:: inc/esp_eth.inc
|
||||
|
||||
API Reference - Common Interface
|
||||
--------------------------------
|
||||
|
||||
.. include:: /_build/inc/esp_eth_com.inc
|
||||
.. include-build-file:: inc/esp_eth_com.inc
|
||||
|
||||
API Reference - MAC Interface
|
||||
-----------------------------
|
||||
|
||||
.. include:: /_build/inc/esp_eth_mac.inc
|
||||
.. include-build-file:: inc/esp_eth_mac.inc
|
||||
|
||||
API Reference - PHY Interface
|
||||
-----------------------------
|
||||
|
||||
.. include:: /_build/inc/esp_eth_phy.inc
|
||||
.. include-build-file:: inc/esp_eth_phy.inc
|
||||
|
||||
API Reference - Glue for esp_netif
|
||||
----------------------------------
|
||||
|
||||
.. include:: /_build/inc/esp_eth_netif_glue.inc
|
||||
.. include-build-file:: inc/esp_eth_netif_glue.inc
|
||||
|
||||
@@ -332,4 +332,4 @@ ESP-IDF contains these ESP-MESH example projects:
|
||||
API Reference
|
||||
--------------
|
||||
|
||||
.. include:: /_build/inc/esp_mesh.inc
|
||||
.. include-build-file:: inc/esp_mesh.inc
|
||||
|
||||
@@ -168,10 +168,10 @@ configured with default settings, which as a consequence, means that:
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_netif.inc
|
||||
.. include-build-file:: inc/esp_netif.inc
|
||||
|
||||
|
||||
WiFi default API reference
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/esp_wifi_default.inc
|
||||
.. include-build-file:: inc/esp_wifi_default.inc
|
||||
|
||||
@@ -94,4 +94,4 @@ The packet data path functions for transmitting and freeing the rx buffer (defin
|
||||
the esp-netif, specifically from its TCP/IP stack connecting layer. The following API reference outlines these network stack
|
||||
interaction with the esp-netif.
|
||||
|
||||
.. include:: /_build/inc/esp_netif_net_stack.inc
|
||||
.. include-build-file:: inc/esp_netif_net_stack.inc
|
||||
|
||||
@@ -84,4 +84,4 @@ Instead, post the necessary data to a queue and handle it from a lower priority
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_now.inc
|
||||
.. include-build-file:: inc/esp_now.inc
|
||||
|
||||
@@ -6,4 +6,4 @@ SmartConfig
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_smartconfig.inc
|
||||
.. include-build-file:: inc/esp_smartconfig.inc
|
||||
|
||||
@@ -6,11 +6,11 @@ Wi-Fi
|
||||
Introduction
|
||||
------------
|
||||
|
||||
The WiFi libraries provide support for configuring and monitoring the ESP32 WiFi networking functionality. This includes configuration for:
|
||||
The WiFi libraries provide support for configuring and monitoring the {IDF_TARGET_NAME} WiFi networking functionality. This includes configuration for:
|
||||
|
||||
- Station mode (aka STA mode or WiFi client mode). ESP32 connects to an access point.
|
||||
- AP mode (aka Soft-AP mode or Access Point mode). Stations connect to the ESP32.
|
||||
- Combined AP-STA mode (ESP32 is concurrently an access point and a station connected to another access point).
|
||||
- Station mode (aka STA mode or WiFi client mode). {IDF_TARGET_NAME} connects to an access point.
|
||||
- AP mode (aka Soft-AP mode or Access Point mode). Stations connect to the {IDF_TARGET_NAME}.
|
||||
- Combined AP-STA mode ({IDF_TARGET_NAME} is concurrently an access point and a station connected to another access point).
|
||||
|
||||
- Various security modes for the above (WPA, WPA2, WEP, etc.)
|
||||
- Scanning for access points (active & passive scanning).
|
||||
@@ -30,7 +30,7 @@ In addition, there is a simple `esp-idf-template <https://github.com/espressif/e
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_wifi.inc
|
||||
.. include:: /_build/inc/esp_wifi_types.inc
|
||||
.. include-build-file:: inc/esp_wifi.inc
|
||||
.. include-build-file:: inc/esp_wifi_types.inc
|
||||
|
||||
|
||||
|
||||
@@ -1,10 +1,16 @@
|
||||
Analog to Digital Converter
|
||||
===========================
|
||||
|
||||
{IDF_TARGET_ADC1_CH0: default="GPIO 0", esp32="GPIO 36"}
|
||||
{IDF_TARGET_ADC2_CH7: default="GPIO 0", esp32="GPIO 27"}
|
||||
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The ESP32 integrates two 12-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs supporting a total of 18 measurement channels (analog enabled pins).
|
||||
.. only:: esp32
|
||||
|
||||
The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs supporting a total of 18 measurement channels (analog enabled pins).
|
||||
|
||||
The ADC driver API supports ADC1 (8 channels, attached to GPIOs 32 - 39), and ADC2 (10 channels, attached to GPIOs 0, 2, 4, 12 - 15 and 25 - 27). However, the usage of ADC2 has some restrictions for the application:
|
||||
|
||||
@@ -14,6 +20,14 @@ The ADC driver API supports ADC1 (8 channels, attached to GPIOs 32 - 39), and AD
|
||||
- :ref:`ESP32 DevKitC <esp-modules-and-boards-esp32-devkitc>`: GPIO 0 cannot be used due to external auto program circuits.
|
||||
- :ref:`ESP-WROVER-KIT <esp-modules-and-boards-esp-wrover-kit>`: GPIO 0, 2, 4 and 15 cannot be used due to external connections for different purposes.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs supporting a total of 20 measurement channels (analog enabled pins).
|
||||
|
||||
The ADC driver API supports ADC1 (10 channels, attached to GPIOs 1 - 10), and ADC2 (10 channels, attached to GPIOs 11 - 20). However, the usage of ADC2 has some restrictions for the application:
|
||||
|
||||
1. ADC2 is used by the Wi-Fi driver. Therefore the application can only use ADC2 when the Wi-Fi driver has not started.
|
||||
|
||||
Configuration and Reading ADC
|
||||
-----------------------------
|
||||
|
||||
@@ -28,6 +42,8 @@ Then it is possible to read ADC conversion result with :cpp:func:`adc1_get_raw`
|
||||
|
||||
.. note:: Since the ADC2 is shared with the WIFI module, which has higher priority, reading operation of :cpp:func:`adc2_get_raw` will fail between :cpp:func:`esp_wifi_start()` and :cpp:func:`esp_wifi_stop()`. Use the return code to see whether the reading is successful.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
It is also possible to read the internal hall effect sensor via ADC1 by calling dedicated function :cpp:func:`hall_sensor_read`. Note that even the hall sensor is internal to ESP32, reading from it uses channels 0 and 3 of ADC1 (GPIO 36 and 39). Do not connect anything else to these pins and do not change their configuration. Otherwise it may affect the measurement of low value signal from the sensor.
|
||||
|
||||
This API provides convenient way to configure ADC1 for reading from :doc:`ULP <../../api-guides/ulp>`. To do so, call function :cpp:func:`adc1_ulp_enable` and then set precision and attenuation as discussed above.
|
||||
@@ -37,7 +53,7 @@ There is another specific function :cpp:func:`adc2_vref_to_gpio` used to route i
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
Reading voltage on ADC1 channel 0 (GPIO 36)::
|
||||
Reading voltage on ADC1 channel 0 ({IDF_TARGET_ADC1_CH0})::
|
||||
|
||||
#include <driver/adc.h>
|
||||
|
||||
@@ -50,7 +66,7 @@ Reading voltage on ADC1 channel 0 (GPIO 36)::
|
||||
The input voltage in above example is from 0 to 1.1V (0 dB attenuation). The input range can be extended by setting higher attenuation, see :cpp:type:`adc_atten_t`.
|
||||
An example using the ADC driver including calibration (discussed below) is available in esp-idf: :example:`peripherals/adc`
|
||||
|
||||
Reading voltage on ADC2 channel 7 (GPIO 27)::
|
||||
Reading voltage on ADC2 channel 7 ({IDF_TARGET_ADC2_CH7})::
|
||||
|
||||
#include <driver/adc.h>
|
||||
|
||||
@@ -69,6 +85,8 @@ Reading voltage on ADC2 channel 7 (GPIO 27)::
|
||||
The reading may fail due to collision with Wi-Fi, should check it.
|
||||
An example using the ADC2 driver to read the output of DAC is available in esp-idf: :example:`peripherals/adc2`
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
Reading the internal hall effect sensor::
|
||||
|
||||
#include <driver/adc.h>
|
||||
@@ -87,7 +105,7 @@ The value read in both these examples is 12 bits wide (range 0-4095).
|
||||
Minimizing Noise
|
||||
----------------
|
||||
|
||||
The ESP32 ADC can be sensitive to noise leading to large discrepancies in ADC readings. To minimize noise, users may connect a 0.1uF capacitor to the ADC input pad in use. Multisampling may also be used to further mitigate the effects of noise.
|
||||
The {IDF_TARGET_NAME} ADC can be sensitive to noise leading to large discrepancies in ADC readings. To minimize noise, users may connect a 0.1uF capacitor to the ADC input pad in use. Multisampling may also be used to further mitigate the effects of noise.
|
||||
|
||||
.. figure:: ../../../_static/adc-noise-graph.jpg
|
||||
:align: center
|
||||
@@ -98,7 +116,7 @@ The ESP32 ADC can be sensitive to noise leading to large discrepancies in ADC re
|
||||
ADC Calibration
|
||||
---------------
|
||||
|
||||
The :component_file:`esp_adc_cal/include/esp_adc_cal.h` API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100mV, however the true reference voltage can range from 1000mV to 1200mV amongst different ESP32s.
|
||||
The :component_file:`esp_adc_cal/include/esp_adc_cal.h` API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100mV, however the true reference voltage can range from 1000mV to 1200mV amongst different {IDF_TARGET_NAME}s.
|
||||
|
||||
.. figure:: ../../../_static/adc-vref-graph.jpg
|
||||
:align: center
|
||||
@@ -111,7 +129,7 @@ Correcting ADC readings using this API involves characterizing one of the ADCs a
|
||||
Calibration Values
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Calibration values are used to generate characteristic curves that account for the unique ADC reference voltage of a particular ESP32. There are currently three sources of calibration values. The availability of these calibration values will depend on the type and production date of the ESP32 chip/module.
|
||||
Calibration values are used to generate characteristic curves that account for the unique ADC reference voltage of a particular {IDF_TARGET_NAME}. There are currently three sources of calibration values. The availability of these calibration values will depend on the type and production date of the {IDF_TARGET_NAME} chip/module.
|
||||
|
||||
* **Two Point** values represent each of the ADCs’ readings at 150mV and 850mV. To obtain more accurate calibration results these values should be measured by user and burned into eFuse ``BLOCK3``.
|
||||
|
||||
@@ -119,6 +137,8 @@ Calibration values are used to generate characteristic curves that account for t
|
||||
|
||||
* **Default Vref** is an estimate of the ADC reference voltage provided by the user as a parameter during characterization. If Two Point or eFuse Vref values are unavailable, **Default Vref** will be used.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
Individual measurement and burning of the **eFuse Vref** has been applied to ESP32-D0WD and ESP32-D0WDQ6 chips produced on/after the 1st week of 2018. Such chips may be recognized by date codes on/later than 012018 (see Line 4 on figure below).
|
||||
|
||||
.. figure:: ../../../_static/chip_surface_marking.png
|
||||
@@ -135,7 +155,7 @@ If you are unable to check the date code (i.e. the chip may be enclosed inside a
|
||||
|
||||
$IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 adc_info
|
||||
|
||||
Replace ``/dev/ttyUSB0`` with ESP32 board's port name.
|
||||
Replace ``/dev/ttyUSB0`` with {IDF_TARGET_NAME} board's port name.
|
||||
|
||||
A chip that has specific **eFuse Vref** value programmed (in this case 1093mV) will be reported as follows::
|
||||
|
||||
@@ -224,18 +244,18 @@ This reference covers three components:
|
||||
ADC driver
|
||||
^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/adc.inc
|
||||
.. include-build-file:: inc/adc.inc
|
||||
|
||||
.. _adc-api-reference-adc-calibration:
|
||||
|
||||
ADC Calibration
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/esp_adc_cal.inc
|
||||
.. include-build-file:: inc/esp_adc_cal.inc
|
||||
|
||||
.. _adc-api-reference-gpio-lookup-macros:
|
||||
|
||||
GPIO Lookup Macros
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: /_build/inc/adc_channel.inc
|
||||
.. include-build-file:: inc/adc_channel.inc
|
||||
|
||||
@@ -6,10 +6,18 @@ Controller Area Network (CAN)
|
||||
Overview
|
||||
--------
|
||||
|
||||
The ESP32's peripherals contains a CAN Controller that supports Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID) of the CAN2.0B specification.
|
||||
.. only:: esp32s2
|
||||
|
||||
.. note::
|
||||
|
||||
The CAN driver is not updated for {IDF_TARGET_NAME} and is temporarily disabled.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
The {IDF_TARGET_NAME}'s peripherals contains a CAN Controller that supports Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID) of the CAN2.0B specification.
|
||||
|
||||
.. warning::
|
||||
The ESP32 CAN controller is not compatible with CAN FD frames and will interpret such frames as errors.
|
||||
The {IDF_TARGET_NAME} CAN controller is not compatible with CAN FD frames and will interpret such frames as errors.
|
||||
|
||||
This programming guide is split into the following sections:
|
||||
|
||||
@@ -168,7 +176,11 @@ The operating bit rate of the CAN controller is configured using the :cpp:type:`
|
||||
2. **Timing Segment 1** consists of 1 to 16 time quanta before sample point
|
||||
3. **Timing Segment 2** consists of 1 to 8 time quanta after sample point
|
||||
|
||||
The **Baudrate Prescaler** is used to determine the period of each time quanta by dividing the CAN controller's source clock (80 MHz APB clock). The ``brp`` can be **any even number from 2 to 128**. If the ESP32 is a revision 2 or later chip, the ``brp`` will also support **any multiple of 4 from 132 to 256**, and can be enabled by setting the :ref:`CONFIG_ESP32_REV_MIN` to revision 2 or higher.
|
||||
The **Baudrate Prescaler** is used to determine the period of each time quanta by dividing the CAN controller's source clock (80 MHz APB clock). The ``brp`` can be **any even number from 2 to 128**.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
If the ESP32 is a revision 2 or later chip, the ``brp`` will also support **any multiple of 4 from 132 to 256**, and can be enabled by setting the :ref:`CONFIG_ESP32_REV_MIN` to revision 2 or higher.
|
||||
|
||||
.. packetdiag:: ../../../_static/diagrams/can/can_bit_timing.diag
|
||||
:caption: Bit timing configuration for 500kbit/s given BRP = 8
|
||||
@@ -195,6 +207,8 @@ Bit timing **macro initializers** are also available for commonly used CAN bus b
|
||||
- ``CAN_TIMING_CONFIG_800KBITS()``
|
||||
- ``CAN_TIMING_CONFIG_1MBITS()``
|
||||
|
||||
.. only::esp32
|
||||
|
||||
.. note::
|
||||
The macro initializers for 12.5K, 16K, and 20K bit rates are only available
|
||||
for ESP32 revision 2 or later.
|
||||
@@ -473,7 +487,7 @@ The following example shows how the calculate the acceptance mask given multiple
|
||||
Application Examples
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
**Network Example:** The CAN Network example demonstrates communication between two ESP32s using the CAN driver API. One CAN node acts as a network master initiate and ceasing the transfer of a data from another CAN node acting as a network slave. The example can be found via :example:`peripherals/can/can_network`.
|
||||
**Network Example:** The CAN Network example demonstrates communication between two {IDF_TARGET_NAME}s using the CAN driver API. One CAN node acts as a network master initiate and ceasing the transfer of a data from another CAN node acting as a network slave. The example can be found via :example:`peripherals/can/can_network`.
|
||||
|
||||
**Alert and Recovery Example:** This example demonstrates how to use the CAN driver's alert and bus recovery API. The example purposely introduces errors on the CAN bus to put the CAN controller into the Bus-Off state. An alert is used to detect the Bus-Off state and trigger the bus recovery process. The example can be found via :example:`peripherals/can/can_alert_and_recovery`.
|
||||
|
||||
@@ -485,5 +499,5 @@ Application Examples
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/can_types.inc
|
||||
.. include:: /_build/inc/can.inc
|
||||
.. include-build-file:: inc/can_types.inc
|
||||
.. include-build-file:: inc/can.inc
|
||||
|
||||
@@ -1,10 +1,15 @@
|
||||
Digital To Analog Converter
|
||||
===========================
|
||||
|
||||
{IDF_TARGET_DAC_CH_1: default = "GPIO25", esp32 = "GPIO25", esp32s2 = "GPIO17"}
|
||||
{IDF_TARGET_DAC_CH_2: default = "GPIO26", esp32 = "GPIO26", esp32s2 = "GPIO18"}
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
ESP32 has two 8-bit DAC (digital to analog converter) channels, connected to GPIO25 (Channel 1) and GPIO26 (Channel 2).
|
||||
{IDF_TARGET_NAME} has two 8-bit DAC (digital to analog converter) channels, connected to {IDF_TARGET_DAC_CH_1} (Channel 1) and {IDF_TARGET_DAC_CH_2} (Channel 2).
|
||||
|
||||
|
||||
|
||||
The DAC driver allows these channels to be set to arbitrary voltages.
|
||||
|
||||
@@ -16,7 +21,7 @@ For other analog output options, see the :doc:`Sigma-delta Modulation module <si
|
||||
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::
|
||||
Setting DAC channel 1 ({IDF_TARGET_DAC_CH_1}) 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>
|
||||
|
||||
@@ -28,14 +33,14 @@ Setting DAC channel 1 (GPIO 25) voltage to approx 0.78 of VDD_A voltage (VDD * 2
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/dac.inc
|
||||
.. include-build-file:: inc/dac.inc
|
||||
|
||||
GPIO Lookup Macros
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
Some useful macros can be used to specified the GPIO number of a DAC channel, or vice versa.
|
||||
e.g.
|
||||
|
||||
1. ``DAC_CHANNEL_1_GPIO_NUM`` is the GPIO number of channel 1 (25);
|
||||
2. ``DAC_GPIO26_CHANNEL`` is the channel number of GPIO 26 (channel 2).
|
||||
1. ``DAC_CHANNEL_1_GPIO_NUM`` is the GPIO number of channel 1 ({IDF_TARGET_DAC_CH_1});
|
||||
2. ``DAC_{IDF_TARGET_DAC_CH_2}_CHANNEL`` is the channel number of GPIO 26 (channel 2).
|
||||
|
||||
.. include:: /_build/inc/dac_channel.inc
|
||||
.. include-build-file:: inc/dac_channel.inc
|
||||
|
||||
@@ -6,7 +6,7 @@ Communication with ESP SDIO Slave
|
||||
ESP SDIO slave initialization
|
||||
------------------------------
|
||||
|
||||
The host should initialize the ESP32 SDIO slave according to the standard
|
||||
The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the standard
|
||||
SDIO initialization process (Sector 3.1.2 of `SDIO Simplified
|
||||
Specification <https://www.sdcard.org/downloads/pls/>`_). In this specification
|
||||
and below, the SDIO slave is also called an (SD)IO card. All the
|
||||
|
||||
@@ -4,11 +4,21 @@ 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.
|
||||
.. only:: esp32
|
||||
|
||||
The {IDF_TARGET_NAME} 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.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
The {IDF_TARGET_NAME} chip features 43 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 GPIO26-32 are usually used for SPI flash.
|
||||
- GPIO46 is fixed to pull-down and is input only
|
||||
|
||||
|
||||
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
|
||||
@@ -19,10 +29,10 @@ GPIO output and input interrupt example: :example:`peripherals/gpio`.
|
||||
API Reference - Normal GPIO
|
||||
---------------------------
|
||||
|
||||
.. include:: /_build/inc/gpio.inc
|
||||
.. include-build-file:: inc/gpio.inc
|
||||
|
||||
API Reference - RTC GPIO
|
||||
------------------------
|
||||
|
||||
.. include:: /_build/inc/rtc_io.inc
|
||||
.. include-build-file:: inc/rtc_io.inc
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ I2C is a serial, synchronous, half-duplex communication protocol that allows co-
|
||||
|
||||
With such advantages as simplicity and low manufacturing cost, I2C is mostly used for communication of low-speed peripheral devices over short distances (within one foot).
|
||||
|
||||
ESP32 has two I2C controllers (also referred to as ports) which are responsible for handling communications on two I2C buses. Each I2C controller can operate as master or slave. As an example, one controller can act as a master and the other as a slave at the same time.
|
||||
{IDF_TARGET_NAME} has two I2C controllers (also referred to as ports) which are responsible for handling communications on two I2C buses. Each I2C controller can operate as master or slave. As an example, one controller can act as a master and the other as a slave at the same time.
|
||||
|
||||
|
||||
Driver Features
|
||||
@@ -50,7 +50,7 @@ To establish I2C communication, start by configuring the driver. This is done by
|
||||
- Configure **communication pins**
|
||||
|
||||
- Assign GPIO pins for SDA and SCL signals
|
||||
- Set whether to enable ESP32's internal pull-ups
|
||||
- Set whether to enable {IDF_TARGET_NAME}'s internal pull-ups
|
||||
|
||||
- (Master only) Set I2C **clock speed**
|
||||
- (Slave only) Configure the following
|
||||
@@ -81,9 +81,9 @@ After the I2C driver is configured, install it by calling the function :cpp:func
|
||||
Communication as Master
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
After installing the I2C driver, ESP32 is ready to communicate with other I2C devices.
|
||||
After installing the I2C driver, {IDF_TARGET_NAME} is ready to communicate with other I2C devices.
|
||||
|
||||
ESP32's I2C controller operating as master is responsible for establishing communication with I2C slave devices and sending commands to trigger a slave to action, for example, to take a measurement and send the readings back to the master.
|
||||
{IDF_TARGET_NAME}'s I2C controller operating as master is responsible for establishing communication with I2C slave devices and sending commands to trigger a slave to action, for example, to take a measurement and send the readings back to the master.
|
||||
|
||||
For better process organization, the driver provides a container, called a "command link", that should be populated with a sequence of commands and then passed to the I2C controller for execution.
|
||||
|
||||
@@ -155,7 +155,7 @@ Likewise, the command link to read from the slave looks as follows:
|
||||
Communication as Slave
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
After installing the I2C driver, ESP32 is ready to communicate with other I2C devices.
|
||||
After installing the I2C driver, {IDF_TARGET_NAME} is ready to communicate with other I2C devices.
|
||||
|
||||
The API provides the following functions for slaves
|
||||
|
||||
@@ -175,11 +175,10 @@ A code example showing how to use these functions can be found in :example:`peri
|
||||
Interrupt Handling
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
During driver installation, an interrupt handler is installed by default. However, you can register your own interrupt handler instead of the default one by calling the function :cpp:func:`i2c_isr_register`. When implementing your own interrupt handler, refer to the `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#page=292>`_ for the description of interrupts triggered by the I2C controller.
|
||||
During driver installation, an interrupt handler is installed by default. However, you can register your own interrupt handler instead of the default one by calling the function :cpp:func:`i2c_isr_register`. When implementing your own interrupt handler, refer to the `{IDF_TARGET_NAME} Technical Reference Manual (PDF) <{IDF_TARGET_TRM_EN_URL}>`_ for the description of interrupts triggered by the I2C controller.
|
||||
|
||||
To delete an interrupt handler, call :cpp:func:`i2c_isr_free`.
|
||||
|
||||
|
||||
.. _i2c-api-customized-configuration:
|
||||
|
||||
Customized Configuration
|
||||
@@ -217,7 +216,7 @@ You can also select different pins for SDA and SCL signals and alter the configu
|
||||
|
||||
.. note::
|
||||
|
||||
ESP32's internal pull-ups are in the range of tens of kOhm, which is, in most cases, insufficient for use as I2C pull-ups. Users are advised to use external pull-ups with values described in the `I2C specification <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_.
|
||||
{IDF_TARGET_NAME}'s internal pull-ups are in the range of tens of kOhm, which is, in most cases, insufficient for use as I2C pull-ups. Users are advised to use external pull-ups with values described in the `I2C specification <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_.
|
||||
|
||||
|
||||
.. _i2c-api-error-handling:
|
||||
@@ -249,4 +248,4 @@ I2C master and slave example: :example:`peripherals/i2c`.
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/i2c.inc
|
||||
.. include-build-file:: inc/i2c.inc
|
||||
|
||||
@@ -6,7 +6,13 @@ Overview
|
||||
|
||||
I2S (Inter-IC Sound) is a serial, synchronous communication protocol that is usually used for transmitting audio data between two digital audio devices.
|
||||
|
||||
ESP32 integrates two I2S controllers, referred to as I2S0 and I2S1, both of which can be used for streaming audio and video digital data.
|
||||
.. only:: esp32
|
||||
|
||||
{IDF_TARGET_NAME} contains two I2S peripherals. These peripherals can be configured to input and output sample data via the I2S driver.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
{IDF_TARGET_NAME} contains one I2S peripheral. These peripherals can be configured to input and output sample data via the I2S driver.
|
||||
|
||||
An I2S bus consists of the following lines:
|
||||
|
||||
@@ -30,6 +36,8 @@ The I2S peripherals also support LCD mode for communicating data over a parallel
|
||||
- Camera slave receiving mode
|
||||
- ADC/DAC mode
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
For more information, see the `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#page=306>`_.
|
||||
|
||||
.. note::
|
||||
@@ -208,5 +216,5 @@ Configuring I2S to use internal DAC for analog output
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/i2s.inc
|
||||
.. include-build-file:: inc/i2s.inc
|
||||
|
||||
|
||||
@@ -14,17 +14,17 @@ Peripherals API
|
||||
I2C <i2c>
|
||||
I2S <i2s>
|
||||
LED Control <ledc>
|
||||
MCPWM <mcpwm>
|
||||
:esp32: MCPWM <mcpwm>
|
||||
Pulse Counter <pcnt>
|
||||
Remote Control <rmt>
|
||||
SD Pull-up Requirements <sd_pullup_requirements>
|
||||
SDMMC Host <sdmmc_host>
|
||||
:esp32: SD Pull-up Requirements <sd_pullup_requirements>
|
||||
:esp32: SDMMC Host <sdmmc_host>
|
||||
SD SPI Host <sdspi_host>
|
||||
SDIO Slave <sdio_slave>
|
||||
:esp32: SDIO Slave <sdio_slave>
|
||||
Sigma-delta Modulation <sigmadelta>
|
||||
SPI Master <spi_master>
|
||||
SPI Slave <spi_slave>
|
||||
Temp sensor <temp_sensor>
|
||||
:esp32s2: Temp sensor <temp_sensor>
|
||||
Timer <timer>
|
||||
Touch Sensor <touch_pad>
|
||||
UART <uart>
|
||||
|
||||
@@ -6,8 +6,14 @@ LED Control
|
||||
Introduction
|
||||
------------
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
The LED control (LEDC) peripheral is primarily designed to control the intensity of LEDs, although it can also be used to generate PWM signals for other purposes as well. It has 16 channels which can generate independent waveforms that can be used, for example, to drive RGB LED devices.
|
||||
|
||||
A half of LEDC's channels operate in high speed mode. This mode is implemented in hardware and offers automatic and glitch-free changing of the PWM duty cycle. The other half of channels operate in low speed mode, where the moment of change depends on the application software. Each group of channels is also able to use different clock sources, but this feature is not yet supported in the LEDC driver.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
A half of LEDC's channels operate in high speed mode. This mode is implemented in hardware and offers automatic and glitch-free changing of the PWM duty cycle. The other half of channels operate in low speed mode, where the moment of change depends on the application software. Each group of channels is also able to use different clock sources.
|
||||
|
||||
The PWM controller can automatically increase or decrease the duty cycle gradually, allowing for fades without any processor interference.
|
||||
@@ -131,13 +137,21 @@ For registration of a handler to address this interrupt, call :cpp:func:`ledc_is
|
||||
LEDC High and Low Speed Mode
|
||||
----------------------------
|
||||
|
||||
Of the total 8 timers and 16 channels available in the LED PWM Controller, half of them are dedicated to operation in high speed mode and the other half in low speed mode. Selection of a low or high speed timer or channel is done with the parameter :cpp:type:`ledc_mode_t` that can be found in applicable function calls.
|
||||
.. only:: esp32
|
||||
|
||||
The advantage of high speed mode is glitch-free changeover of the timer settings. This means that if the timer settings are modified, the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the background, e.g., when :cpp:func:`ledc_timer_config` or :cpp:func:`ledc_timer_set` is called.
|
||||
|
||||
For additional details regarding speed modes, refer to `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver.
|
||||
The advantage of high speed mode is hardware-supported, glitch-free changeover of the timer settings. This means that if the timer settings are modified, the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the background, e.g., when :cpp:func:`ledc_timer_config` or :cpp:func:`ledc_timer_set` is called.
|
||||
|
||||
|
||||
For additional details regarding speed modes, refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
.. note::
|
||||
|
||||
All the timers and channels in the {IDF_TARGET_NAME}'s LED PWM Controller only support low speed mode.
|
||||
|
||||
.. _ledc-api-supported-range-frequency-duty-resolution:
|
||||
|
||||
Supported Range of Frequency and Duty Resolutions
|
||||
@@ -175,5 +189,5 @@ The LEDC change duty cycle and fading control example: :example:`peripherals/led
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/ledc.inc
|
||||
.. include-build-file:: inc/ledc.inc
|
||||
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
MCPWM
|
||||
=====
|
||||
|
||||
.. This peripheral is ESP32 only
|
||||
|
||||
ESP32 has two MCPWM units which can be used to control different types of motors. Each unit has three pairs of PWM outputs.
|
||||
|
||||
.. figure:: ../../../_static/mcpwm-overview.png
|
||||
@@ -53,7 +55,7 @@ In this case we will describe a simple configuration to control a brushed DC mot
|
||||
|
||||
Configuration covers the following steps:
|
||||
|
||||
1. Selection of a MPWn unit that will be used to drive the motor. There are two units available on-board of ESP32 and enumerated in :cpp:type:`mcpwm_unit_t`.
|
||||
1. Selection of a MPWn unit that will be used to drive the motor. There are two units available on-board of {IDF_TARGET_NAME} and enumerated in :cpp:type:`mcpwm_unit_t`.
|
||||
2. Initialization of two GPIOs as output signals within selected unit by calling :cpp:func:`mcpwm_gpio_init`. The two output signals are typically used to command the motor to rotate right or left. All available signal options are listed in :cpp:type:`mcpwm_io_signals_t`. To set more than a single pin at a time, use function :cpp:func:`mcpwm_set_pin` together with :cpp:type:`mcpwm_pin_config_t`.
|
||||
3. Selection of a timer. There are three timers available within the unit. The timers are listed in :cpp:type:`mcpwm_timer_t`.
|
||||
4. Setting of the timer frequency and initial duty within :cpp:type:`mcpwm_config_t` structure.
|
||||
@@ -89,8 +91,8 @@ There are couple of ways to adjust a signal on the outputs and changing how the
|
||||
|
||||
Synchronization signals are referred to using two different enumerations. First one :cpp:type:`mcpwm_io_signals_t` is used together with function :cpp:func:`mcpwm_gpio_init` when selecting a GPIO as the signal input source. The second one :cpp:type:`mcpwm_sync_signal_t` is used when enabling or disabling synchronization with :cpp:func:`mcpwm_sync_enable` or :cpp:func:`mcpwm_sync_disable`.
|
||||
|
||||
* Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `ESP32 Technical Reference Manual`_.
|
||||
|
||||
* Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `{IDF_TARGET_NAME} Technical Reference Manual`_.
|
||||
|
||||
Capture
|
||||
-------
|
||||
@@ -148,7 +150,7 @@ To use the carrier submodule, it should be first initialized by calling :cpp:fun
|
||||
|
||||
The carrier parameters may be then alerted at a runtime by calling dedicated functions to change individual fields of the :cpp:type:`mcpwm_carrier_config_t` structure, like :cpp:func:`mcpwm_carrier_set_period`, :cpp:func:`mcpwm_carrier_set_duty_cycle`, :cpp:func:`mcpwm_carrier_output_invert`, etc.
|
||||
|
||||
This includes enabling and setting duration of the first pulse of the career with :cpp:func:`mcpwm_carrier_oneshot_mode_enable`. For more details please refer to "PWM Carrier Submodule" section of the `ESP32 Technical Reference Manual`_.
|
||||
This includes enabling and setting duration of the first pulse of the career with :cpp:func:`mcpwm_carrier_oneshot_mode_enable`. For more details please refer to "PWM Carrier Submodule" section of the `{IDF_TARGET_NAME} Technical Reference Manual`_.
|
||||
|
||||
To disable carrier functionality call :cpp:func:`mcpwm_carrier_disable`.
|
||||
|
||||
@@ -169,12 +171,13 @@ Examples of using MCPWM for motor control: :example:`peripherals/mcpwm`:
|
||||
* Brushed DC motor control - :example:`peripherals/mcpwm/mcpwm_brushed_dc_control`
|
||||
* Servo motor control - :example:`peripherals/mcpwm/mcpwm_servo_control`
|
||||
|
||||
.. _ESP32 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
|
||||
.. _{IDF_TARGET_NAME} Technical Reference Manual: {IDF_TARGET_TRM_EN_URL}
|
||||
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/mcpwm_types.inc
|
||||
.. include:: /_build/inc/mcpwm.inc
|
||||
.. include-build-file:: inc/mcpwm_types.inc
|
||||
.. include-build-file:: inc/mcpwm.inc
|
||||
|
||||
|
||||
|
||||
@@ -22,9 +22,14 @@ Description of functionality of this API has been broken down into four sections
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
.. only:: esp32
|
||||
|
||||
The PCNT module has eight independent counting "units" numbered from 0 to 7. In the API they are referred to using :cpp:type:`pcnt_unit_t`. Each unit has two independent channels numbered as 0 and 1 and specified with :cpp:type:`pcnt_channel_t`.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
The PCNT module has four independent counting "units" numbered from 0 to 3. In the API they are referred to using :cpp:type:`pcnt_unit_t`. Each unit has two independent channels numbered as 0 and 1 and specified with :cpp:type:`pcnt_channel_t`.
|
||||
|
||||
The configuration is provided separately per unit's channel using :cpp:type:`pcnt_config_t` and covers:
|
||||
|
||||
* The unit and the channel number this configuration refers to.
|
||||
@@ -92,5 +97,5 @@ Pulse counter with control signal and event interrupt example: :example:`periphe
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/pcnt.inc
|
||||
.. include-build-file:: inc/pcnt.inc
|
||||
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user