alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

docs: fix Doxygen warnings, fail CI build on Doxygen warnings

Browse Source
This commit is contained in:
Ivan Grokhotkov 2016-11-16 01:35:09 +08:00
parent ca202cbb46
commit 13d4734399
11 changed files with 444 additions and 387 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.gitlab-ci.yml
View File

@ -118,6 +118,9 @@ build_docs:
- build_docs - build_docs
script: script:
- cd docs - cd docs
- doxygen
# If not building master branch, and there are Doxygen warnings, print them and bail out
- test "${CI_BUILD_REF_NAME}" = "master" || test $(cat doxygen-warning-log.txt | wc -l) -eq 0 || ( echo "Doxygen pass had some warnings:" && cat doxygen-warning-log.txt && false )
- make html - make html
artifacts: artifacts:
paths: paths:

7
components/bt/include/bt.h
View File

@ -32,13 +32,10 @@ void bt_controller_init(void);
/** @brief vhci_host_callback /** @brief vhci_host_callback
* used for vhci call host function to notify what host need to do * used for vhci call host function to notify what host need to do
*
* notify_host_send_available: notify host can send packet to controller
* notify_host_recv: notify host that controller has packet send to host
*/ */
typedef struct vhci_host_callback { typedef struct vhci_host_callback {
void (*notify_host_send_available)(void); void (*notify_host_send_available)(void); /*!< callback used to notify that the host can send packet to controller */
int (*notify_host_recv)(uint8_t *data, uint16_t len); int (*notify_host_recv)(uint8_t *data, uint16_t len); /*!< callback used to notify that the controller has a packet to send to the host*/
} vhci_host_callback_t; } vhci_host_callback_t;
/** @brief API_vhci_host_check_send_available /** @brief API_vhci_host_check_send_available

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

@ -117,6 +117,9 @@ extern const uint32_t GPIO_PIN_MUX_REG[GPIO_PIN_COUNT];
#define GPIO_IS_VALID_GPIO(gpio_num) ((gpio_num < GPIO_PIN_COUNT && GPIO_PIN_MUX_REG[gpio_num] != 0)) //to decide whether it is a valid GPIO number #define GPIO_IS_VALID_GPIO(gpio_num) ((gpio_num < GPIO_PIN_COUNT && GPIO_PIN_MUX_REG[gpio_num] != 0)) //to decide whether it is a valid GPIO number
#define GPIO_IS_VALID_OUTPUT_GPIO(gpio_num) ((GPIO_IS_VALID_GPIO(gpio_num)) && (gpio_num < 34)) //to decide whether it can be a valid GPIO number of output mode #define GPIO_IS_VALID_OUTPUT_GPIO(gpio_num) ((GPIO_IS_VALID_GPIO(gpio_num)) && (gpio_num < 34)) //to decide whether it can be a valid GPIO number of output mode
/**
* @brief Pullup/pulldown information for a single GPIO pad
*/
typedef struct { typedef struct {
uint32_t reg; /*!< Register to modify to enable or disable pullups or pulldowns */ uint32_t reg; /*!< Register to modify to enable or disable pullups or pulldowns */
uint32_t pu; /*!< Bit to set or clear in the above register to enable or disable the pullup, respectively */ uint32_t pu; /*!< Bit to set or clear in the above register to enable or disable the pullup, respectively */
@ -208,6 +211,9 @@ typedef enum {
GPIO_PULLDOWN_ENABLE = 0x1, /*!< Enable GPIO pull-down resistor */ GPIO_PULLDOWN_ENABLE = 0x1, /*!< Enable GPIO pull-down resistor */
} gpio_pulldown_t; } gpio_pulldown_t;
/**
* @brief Configuration parameters of GPIO pad for gpio_config function
*/
typedef struct { typedef struct {
uint64_t pin_bit_mask; /*!< GPIO pin: set with bit mask, each bit maps to a GPIO */ uint64_t pin_bit_mask; /*!< GPIO pin: set with bit mask, each bit maps to a GPIO */
gpio_mode_t mode; /*!< GPIO mode: set input/output mode */ gpio_mode_t mode; /*!< GPIO mode: set input/output mode */

6
components/driver/include/driver/ledc.h
View File

@ -78,6 +78,9 @@ typedef enum {
LEDC_TIMER_15_BIT = 15, /*!< LEDC PWM depth 15Bit */ LEDC_TIMER_15_BIT = 15, /*!< LEDC PWM depth 15Bit */
} ledc_timer_bit_t; } ledc_timer_bit_t;
/**
* @brief Configuration parameters of LEDC channel for ledc_channel_config function
*/
typedef struct { typedef struct {
int gpio_num; /*!< the LEDC output gpio_num, if you want to use gpio16, gpio_num = 16*/ int gpio_num; /*!< the LEDC output gpio_num, if you want to use gpio16, gpio_num = 16*/
ledc_mode_t speed_mode; /*!< LEDC speed speed_mode, high-speed mode or low-speed mode*/ ledc_mode_t speed_mode; /*!< LEDC speed speed_mode, high-speed mode or low-speed mode*/
@ -87,6 +90,9 @@ typedef struct {
uint32_t duty; /*!< LEDC channel duty, the duty range is [0, (2**bit_num) - 1], */ uint32_t duty; /*!< LEDC channel duty, the duty range is [0, (2**bit_num) - 1], */
} ledc_channel_config_t; } ledc_channel_config_t;
/**
* @brief Configuration parameters of LEDC Timer timer for ledc_timer_config function
*/
typedef struct { typedef struct {
ledc_mode_t speed_mode; /*!< LEDC speed speed_mode, high-speed mode or low-speed mode*/ ledc_mode_t speed_mode; /*!< LEDC speed speed_mode, high-speed mode or low-speed mode*/
ledc_timer_bit_t bit_num; /*!< LEDC channel duty depth*/ ledc_timer_bit_t bit_num; /*!< LEDC channel duty depth*/

121
components/driver/include/driver/uart.h
View File

@ -32,11 +32,11 @@ extern "C" {
#include "freertos/ringbuf.h" #include "freertos/ringbuf.h"
#include <esp_types.h> #include <esp_types.h>
#define UART_FIFO_LEN (128) /*< Length of the hardware FIFO buffers */ #define UART_FIFO_LEN (128) /*!< Length of the hardware FIFO buffers */
#define UART_INTR_MASK 0x1ff #define UART_INTR_MASK 0x1ff /*!< mask of all UART interrupts */
#define UART_LINE_INV_MASK (0x3f << 19) #define UART_LINE_INV_MASK (0x3f << 19) /*!< TBD */
#define UART_BITRATE_MAX 5000000 #define UART_BITRATE_MAX 5000000 /*!< Max bit rate supported by UART */
#define UART_PIN_NO_CHANGE (-1) #define UART_PIN_NO_CHANGE (-1) /*!< Constant for uart_set_pin function which indicates that UART pin should not be changed */
#define UART_INVERSE_DISABLE (0x0) /*!< Disable UART signal inverse*/ #define UART_INVERSE_DISABLE (0x0) /*!< Disable UART signal inverse*/
#define UART_INVERSE_RXD (UART_RXD_INV_M) /*!< UART RXD input inverse*/ #define UART_INVERSE_RXD (UART_RXD_INV_M) /*!< UART RXD input inverse*/
@ -44,6 +44,9 @@ extern "C" {
#define UART_INVERSE_TXD (UART_TXD_INV_M) /*!< UART TXD output inverse*/ #define UART_INVERSE_TXD (UART_TXD_INV_M) /*!< UART TXD output inverse*/
#define UART_INVERSE_RTS (UART_RTS_INV_M) /*!< UART RTS output inverse*/ #define UART_INVERSE_RTS (UART_RTS_INV_M) /*!< UART RTS output inverse*/
/**
* @brief UART word length constants
*/
typedef enum { typedef enum {
UART_DATA_5_BITS = 0x0, /*!< word length: 5bits*/ UART_DATA_5_BITS = 0x0, /*!< word length: 5bits*/
UART_DATA_6_BITS = 0x1, /*!< word length: 6bits*/ UART_DATA_6_BITS = 0x1, /*!< word length: 6bits*/
@ -52,6 +55,9 @@ typedef enum {
UART_DATA_BITS_MAX = 0X4, UART_DATA_BITS_MAX = 0X4,
} uart_word_length_t; } uart_word_length_t;
/**
* @brief UART stop bits number
*/
typedef enum { typedef enum {
UART_STOP_BITS_1 = 0x1, /*!< stop bit: 1bit*/ UART_STOP_BITS_1 = 0x1, /*!< stop bit: 1bit*/
UART_STOP_BITS_1_5 = 0x2, /*!< stop bit: 1.5bits*/ UART_STOP_BITS_1_5 = 0x2, /*!< stop bit: 1.5bits*/
@ -59,6 +65,9 @@ typedef enum {
UART_STOP_BITS_MAX = 0x4, UART_STOP_BITS_MAX = 0x4,
} uart_stop_bits_t; } uart_stop_bits_t;
/**
* @brief UART peripheral number
*/
typedef enum { typedef enum {
UART_NUM_0 = 0x0, /*!< UART base address 0x3ff40000*/ UART_NUM_0 = 0x0, /*!< UART base address 0x3ff40000*/
UART_NUM_1 = 0x1, /*!< UART base address 0x3ff50000*/ UART_NUM_1 = 0x1, /*!< UART base address 0x3ff50000*/
@ -66,12 +75,18 @@ typedef enum {
UART_NUM_MAX, UART_NUM_MAX,
} uart_port_t; } uart_port_t;
/**
* @brief UART parity constants
*/
typedef enum { typedef enum {
UART_PARITY_DISABLE = 0x0, /*!< Disable UART parity*/ UART_PARITY_DISABLE = 0x0, /*!< Disable UART parity*/
UART_PARITY_EVEN = 0x2, /*!< Enable UART even parity*/ UART_PARITY_EVEN = 0x2, /*!< Enable UART even parity*/
UART_PARITY_ODD = 0x3 /*!< Enable UART odd parity*/ UART_PARITY_ODD = 0x3 /*!< Enable UART odd parity*/
} uart_parity_t; } uart_parity_t;
/**
* @brief UART hardware flow control modes
*/
typedef enum { typedef enum {
UART_HW_FLOWCTRL_DISABLE = 0x0, /*!< disable hardware flow control*/ UART_HW_FLOWCTRL_DISABLE = 0x0, /*!< disable hardware flow control*/
UART_HW_FLOWCTRL_RTS = 0x1, /*!< enable RX hardware flow control (rts)*/ UART_HW_FLOWCTRL_RTS = 0x1, /*!< enable RX hardware flow control (rts)*/
@ -80,6 +95,9 @@ typedef enum {
UART_HW_FLOWCTRL_MAX = 0x4, UART_HW_FLOWCTRL_MAX = 0x4,
} uart_hw_flowcontrol_t; } uart_hw_flowcontrol_t;
/**
* @brief UART configuration parameters for uart_param_config function
*/
typedef struct { typedef struct {
int baud_rate; /*!< UART baudrate*/ int baud_rate; /*!< UART baudrate*/
uart_word_length_t data_bits; /*!< UART byte size*/ uart_word_length_t data_bits; /*!< UART byte size*/
@ -89,6 +107,9 @@ typedef struct {
uint8_t rx_flow_ctrl_thresh ; /*!< UART HW RTS threshold*/ uint8_t rx_flow_ctrl_thresh ; /*!< UART HW RTS threshold*/
} uart_config_t; } uart_config_t;
/**
* @brief UART interrupt configuration parameters for uart_intr_config function
*/
typedef struct { typedef struct {
uint32_t intr_enable_mask; /*!< UART interrupt enable mask, choose from UART_XXXX_INT_ENA_M under UART_INT_ENA_REG(i), connect with bit-or operator*/ uint32_t intr_enable_mask; /*!< UART interrupt enable mask, choose from UART_XXXX_INT_ENA_M under UART_INT_ENA_REG(i), connect with bit-or operator*/
uint8_t rx_timeout_thresh; /*!< UART timeout interrupt threshold(unit: time of sending one byte)*/ uint8_t rx_timeout_thresh; /*!< UART timeout interrupt threshold(unit: time of sending one byte)*/
@ -96,6 +117,9 @@ typedef struct {
uint8_t rxfifo_full_thresh; /*!< UART RX full interrupt threshold.*/ uint8_t rxfifo_full_thresh; /*!< UART RX full interrupt threshold.*/
} uart_intr_config_t; } uart_intr_config_t;
/**
* @brief UART event types used in the ringbuffer
*/
typedef enum { typedef enum {
UART_DATA, /*!< UART data event*/ UART_DATA, /*!< UART data event*/
UART_BREAK, /*!< UART break event*/ UART_BREAK, /*!< UART break event*/
@ -107,6 +131,9 @@ typedef enum {
UART_EVENT_MAX, /*!< UART event max index*/ UART_EVENT_MAX, /*!< UART event max index*/
} uart_event_type_t; } uart_event_type_t;
/**
* @brief Event structure used in UART event queue
*/
typedef struct { typedef struct {
uart_event_type_t type; /*!< UART event type */ uart_event_type_t type; /*!< UART event type */
size_t size; /*!< UART data size for UART_DATA event*/ size_t size; /*!< UART data size for UART_DATA event*/
@ -116,7 +143,6 @@ typedef struct {
* @brief Set UART data bits. * @brief Set UART data bits.
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param data_bit UART data bits * @param data_bit UART data bits
* *
* @return * @return
@ -129,7 +155,6 @@ esp_err_t uart_set_word_length(uart_port_t uart_num, uart_word_length_t data_bit
* @brief Get UART data bits. * @brief Get UART data bits.
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param data_bit Pointer to accept value of UART data bits. * @param data_bit Pointer to accept value of UART data bits.
* *
* @return * @return
@ -142,7 +167,6 @@ esp_err_t uart_get_word_length(uart_port_t uart_num, uart_word_length_t* data_bi
* @brief Set UART stop bits. * @brief Set UART stop bits.
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param bit_num UART stop bits * @param bit_num UART stop bits
* *
* @return * @return
@ -155,7 +179,6 @@ esp_err_t uart_set_stop_bits(uart_port_t uart_num, uart_stop_bits_t bit_num);
* @brief Set UART stop bits. * @brief Set UART stop bits.
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param stop_bit Pointer to accept value of UART stop bits. * @param stop_bit Pointer to accept value of UART stop bits.
* *
* @return * @return
@ -168,7 +191,6 @@ esp_err_t uart_get_stop_bits(uart_port_t uart_num, uart_stop_bits_t* stop_bit);
* @brief Set UART parity. * @brief Set UART parity.
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param parity_mode the enum of uart parity configuration * @param parity_mode the enum of uart parity configuration
* *
* @return * @return
@ -181,7 +203,6 @@ esp_err_t uart_set_parity(uart_port_t uart_num, uart_parity_t parity_mode);
* @brief Get UART parity mode. * @brief Get UART parity mode.
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param parity_mode Pointer to accept value of UART parity mode. * @param parity_mode Pointer to accept value of UART parity mode.
* *
* @return * @return
@ -195,7 +216,6 @@ esp_err_t uart_get_parity(uart_port_t uart_num, uart_parity_t* parity_mode);
* @brief Set UART baud rate. * @brief Set UART baud rate.
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param baud_rate UART baud-rate. * @param baud_rate UART baud-rate.
* *
* @return * @return
@ -208,7 +228,6 @@ esp_err_t uart_set_baudrate(uart_port_t uart_num, uint32_t baud_rate);
* @brief Get UART bit-rate. * @brief Get UART bit-rate.
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param baudrate Pointer to accept value of UART baud rate * @param baudrate Pointer to accept value of UART baud rate
* *
* @return * @return
@ -222,10 +241,8 @@ esp_err_t uart_get_baudrate(uart_port_t uart_num, uint32_t* baudrate);
* @brief Set UART line inverse mode * @brief Set UART line inverse mode
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
* * @param inverse_mask Choose the wires that need to be inversed.
* @param Inverse_mask Choose the wires that need to be inversed. * Inverse_mask should be chosen from UART_INVERSE_RXD/UART_INVERSE_TXD/UART_INVERSE_RTS/UART_INVERSE_CTS, combine with OR operation.
*
* (inverse_mask should be chosen from UART_INVERSE_RXD/UART_INVERSE_TXD/UART_INVERSE_RTS/UART_INVERSE_CTS, combine with OR-OPERATION)
* *
* @return * @return
* - ESP_OK Success * - ESP_OK Success
@ -237,12 +254,9 @@ esp_err_t uart_set_line_inverse(uart_port_t uart_num, uint32_t inverse_mask);
* @brief Set hardware flow control. * @brief Set hardware flow control.
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param flow_ctrl Hardware flow control mode * @param flow_ctrl Hardware flow control mode
* * @param rx_thresh Threshold of Hardware RX flow control(0 ~ UART_FIFO_LEN).
* @param rx_thresh Threshold of Hardware RX flow control(0 ~ UART_FIFO_LEN) * Only when UART_HW_FLOWCTRL_RTS is set, will the rx_thresh value be set.
*
* Only when UART_HW_FLOWCTRL_RTS is set , will the rx_thresh value be set.
* *
* @return * @return
* - ESP_OK Success * - ESP_OK Success
@ -254,7 +268,6 @@ esp_err_t uart_set_hw_flow_ctrl(uart_port_t uart_num, uart_hw_flowcontrol_t flow
* @brief Get hardware flow control mode * @brief Get hardware flow control mode
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param flow_ctrl Option for different flow control mode. * @param flow_ctrl Option for different flow control mode.
* *
* @return * @return
@ -267,10 +280,8 @@ esp_err_t uart_get_hw_flow_ctrl(uart_port_t uart_num, uart_hw_flowcontrol_t* flo
* @brief Clear UART interrupt status * @brief Clear UART interrupt status
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param clr_mask Bit mask of the status that to be cleared. * @param clr_mask Bit mask of the status that to be cleared.
* * enable_mask should be chosen from the fields of register UART_INT_CLR_REG.
* (enable_mask should be chosen from the fields of register UART_INT_CLR_REG)
* *
* @return * @return
* - ESP_OK Success * - ESP_OK Success
@ -282,10 +293,8 @@ esp_err_t uart_clear_intr_status(uart_port_t uart_num, uint32_t clr_mask);
* @brief Set UART interrupt enable * @brief Set UART interrupt enable
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param enable_mask Bit mask of the enable bits. * @param enable_mask Bit mask of the enable bits.
* * enable_mask should be chosen from the fields of register UART_INT_ENA_REG.
* (enable_mask should be chosen from the fields of register UART_INT_ENA_REG)
* *
* @return * @return
* - ESP_OK Success * - ESP_OK Success
@ -297,10 +306,8 @@ esp_err_t uart_enable_intr_mask(uart_port_t uart_num, uint32_t enable_mask);
* @brief Clear UART interrupt enable bits * @brief Clear UART interrupt enable bits
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param disable_mask Bit mask of the disable bits. * @param disable_mask Bit mask of the disable bits.
* * disable_mask should be chosen from the fields of register UART_INT_ENA_REG.
* (disable_mask should be chosen from the fields of register UART_INT_ENA_REG)
* *
* @return * @return
* - ESP_OK Success * - ESP_OK Success
@ -346,9 +353,7 @@ esp_err_t uart_disable_tx_intr(uart_port_t uart_num);
* @brief Enable UART TX interrupt(RX_FULL & RX_TIMEOUT INTERRUPT) * @brief Enable UART TX interrupt(RX_FULL & RX_TIMEOUT INTERRUPT)
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param enable 1: enable; 0: disable * @param enable 1: enable; 0: disable
*
* @param thresh Threshold of TX interrupt, 0 ~ UART_FIFO_LEN * @param thresh Threshold of TX interrupt, 0 ~ UART_FIFO_LEN
* *
* @return * @return
@ -358,19 +363,17 @@ esp_err_t uart_disable_tx_intr(uart_port_t uart_num);
esp_err_t uart_enable_tx_intr(uart_port_t uart_num, int enable, int thresh); esp_err_t uart_enable_tx_intr(uart_port_t uart_num, int enable, int thresh);
/** /**
* @brief register UART interrupt handler(ISR). * @brief register UART interrupt handler(ISR).
* @note *
* UART ISR handler will be attached to the same CPU core that this function is running on. * @note UART ISR handler will be attached to the same CPU core that this function is running on.
* Users should know that which CPU is running and then pick a INUM that is not used by system. * Users should know that which CPU is running and then pick a INUM that is not used by system.
* We can find the information of INUM and interrupt level in soc.h. * We can find the information of INUM and interrupt level in soc.h.
* *
* @attention The ISR handler function MUST be defined with attribution of "IRAM_ATTR" for now.
*
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param uart_intr_num UART interrupt number,check the info in soc.h, and please refer to core-isa.h for more details * @param uart_intr_num UART interrupt number,check the info in soc.h, and please refer to core-isa.h for more details
*
* @param fn Interrupt handler function. * @param fn Interrupt handler function.
* @attention
* The ISR handler function MUST be defined with attribution of "IRAM_ATTR" for now.
* @param arg parameter for handler function * @param arg parameter for handler function
* *
* @return * @return
@ -382,18 +385,13 @@ esp_err_t uart_isr_register(uart_port_t uart_num, uint8_t uart_intr_num, void (*
/** /**
* @brief Set UART pin number * @brief Set UART pin number
* *
* @note * @note Internal signal can be output to multiple GPIO pads.
* Internal signal can be output to multiple GPIO pads * Only one GPIO pad can connect with input signal.
* Only one GPIO pad can connect with input signal
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param tx_io_num UART TX pin GPIO number, if set to UART_PIN_NO_CHANGE, use the current pin. * @param tx_io_num UART TX pin GPIO number, if set to UART_PIN_NO_CHANGE, use the current pin.
*
* @param rx_io_num UART RX pin GPIO number, if set to UART_PIN_NO_CHANGE, use the current pin. * @param rx_io_num UART RX pin GPIO number, if set to UART_PIN_NO_CHANGE, use the current pin.
*
* @param rts_io_num UART RTS pin GPIO number, if set to UART_PIN_NO_CHANGE, use the current pin. * @param rts_io_num UART RTS pin GPIO number, if set to UART_PIN_NO_CHANGE, use the current pin.
*
* @param cts_io_num UART CTS pin GPIO number, if set to UART_PIN_NO_CHANGE, use the current pin. * @param cts_io_num UART CTS pin GPIO number, if set to UART_PIN_NO_CHANGE, use the current pin.
* *
* @return * @return
@ -407,7 +405,6 @@ esp_err_t uart_set_pin(uart_port_t uart_num, int tx_io_num, int rx_io_num, int r
* UART rx hardware flow control should not be set. * UART rx hardware flow control should not be set.
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param level 1: RTS output low(active); 0: RTS output high(block) * @param level 1: RTS output low(active); 0: RTS output high(block)
* *
* @return * @return
@ -420,7 +417,6 @@ esp_err_t uart_set_rts(uart_port_t uart_num, int level);
* @brief UART set DTR level (before inverse) * @brief UART set DTR level (before inverse)
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param level 1: DTR output low; 0: DTR output high * @param level 1: DTR output low; 0: DTR output high
* *
* @return * @return
@ -433,7 +429,6 @@ esp_err_t uart_set_dtr(uart_port_t uart_num, int level);
* @brief UART parameter configure * @brief UART parameter configure
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param uart_config UART parameter settings * @param uart_config UART parameter settings
* *
* @return * @return
@ -446,7 +441,6 @@ esp_err_t uart_param_config(uart_port_t uart_num, const uart_config_t *uart_conf
* @brief UART interrupt configure * @brief UART interrupt configure
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param intr_conf UART interrupt settings * @param intr_conf UART interrupt settings
* *
* @return * @return
@ -463,17 +457,11 @@ esp_err_t uart_intr_config(uart_port_t uart_num, const uart_intr_config_t *intr_
* We can find the information of INUM and interrupt level in soc.h. * We can find the information of INUM and interrupt level in soc.h.
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param rx_buffer_size UART RX ring buffer size * @param rx_buffer_size UART RX ring buffer size
*
* @param tx_buffer_size UART TX ring buffer size. * @param tx_buffer_size UART TX ring buffer size.
*
* If set to zero, driver will not use TX buffer, TX function will block task until all data have been sent out.. * If set to zero, driver will not use TX buffer, TX function will block task until all data have been sent out..
*
* @param queue_size UART event queue size/depth. * @param queue_size UART event queue size/depth.
*
* @param uart_intr_num UART interrupt number,check the info in soc.h, and please refer to core-isa.h for more details * @param uart_intr_num UART interrupt number,check the info in soc.h, and please refer to core-isa.h for more details
*
* @param uart_queue UART event queue handle, if set NULL, driver will not use an event queue. * @param uart_queue UART event queue handle, if set NULL, driver will not use an event queue.
* *
* @return * @return
@ -497,7 +485,6 @@ esp_err_t uart_driver_delete(uart_port_t uart_num);
* @brief Wait UART TX FIFO empty * @brief Wait UART TX FIFO empty
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param ticks_to_wait Timeout, count in RTOS ticks * @param ticks_to_wait Timeout, count in RTOS ticks
* *
* @return * @return
@ -508,15 +495,13 @@ esp_err_t uart_driver_delete(uart_port_t uart_num);
esp_err_t uart_wait_tx_done(uart_port_t uart_num, TickType_t ticks_to_wait); esp_err_t uart_wait_tx_done(uart_port_t uart_num, TickType_t ticks_to_wait);
/** /**
* @brief Send data to the UART port from a given buffer and length, * @brief Send data to the UART port from a given buffer and length.
*
* This function will not wait for the space in TX FIFO, just fill the TX FIFO and return when the FIFO is full. * This function will not wait for the space in TX FIFO, just fill the TX FIFO and return when the FIFO is full.
* @note * @note This function should only be used when UART TX buffer is not enabled.
* This function should only be used when UART TX buffer is not enabled.
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param buffer data buffer address * @param buffer data buffer address
*
* @param len data length to send * @param len data length to send
* *
* @return * @return
@ -535,9 +520,7 @@ int uart_tx_chars(uart_port_t uart_num, const char* buffer, uint32_t len);
* then, UART ISR will move data from ring buffer to TX FIFO gradually. * then, UART ISR will move data from ring buffer to TX FIFO gradually.
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param src data buffer address * @param src data buffer address
*
* @param size data length to send * @param size data length to send
* *
* @return * @return
@ -558,11 +541,8 @@ int uart_write_bytes(uart_port_t uart_num, const char* src, size_t size);
* After all data send out, send a break signal. * After all data send out, send a break signal.
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param src data buffer address * @param src data buffer address
*
* @param size data length to send * @param size data length to send
*
* @param brk_len break signal length (unit: time of one data bit at current_baudrate) * @param brk_len break signal length (unit: time of one data bit at current_baudrate)
* *
* @return * @return
@ -576,11 +556,8 @@ int uart_write_bytes_with_break(uart_port_t uart_num, const char* src, size_t si
* @brief UART read bytes from UART buffer * @brief UART read bytes from UART buffer
* *
* @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2 * @param uart_num UART_NUM_0, UART_NUM_1 or UART_NUM_2
*
* @param buf pointer to the buffer. * @param buf pointer to the buffer.
*
* @param length data length * @param length data length
*
* @param ticks_to_wait sTimeout, count in RTOS ticks * @param ticks_to_wait sTimeout, count in RTOS ticks
* *
* @return * @return

429
components/esp32/include/esp_wifi.h
View File

@ -88,6 +88,9 @@ extern "C" {
#define ESP_ERR_WIFI_PASSWORD (ESP_ERR_WIFI_BASE + 10) /*!< Passord is invalid */ #define ESP_ERR_WIFI_PASSWORD (ESP_ERR_WIFI_BASE + 10) /*!< Passord is invalid */
#define ESP_ERR_WIFI_TIMEOUT (ESP_ERR_WIFI_BASE + 11) /*!< Timeout error */ #define ESP_ERR_WIFI_TIMEOUT (ESP_ERR_WIFI_BASE + 11) /*!< Timeout error */
/**
* @brief WiFi stack configuration parameters passed to esp_wifi_init call.
*/
typedef struct { typedef struct {
system_event_handler_t event_handler; /**< WiFi event handler */ system_event_handler_t event_handler; /**< WiFi event handler */
} wifi_init_config_t; } wifi_init_config_t;
@ -108,12 +111,12 @@ typedef struct {
* will post station connected event to this queue. If the queue is not initialized, WiFi * will post station connected event to this queue. If the queue is not initialized, WiFi
* will not post any events * will not post any events
* *
* @param wifi_init_config_t *config : provide WiFi init configuration * @param config provide WiFi init configuration
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NO_MEM : out of memory * - ESP_ERR_WIFI_NO_MEM: out of memory
* - others : refer to error code esp_err.h * - others: refer to error code esp_err.h
*/ */
esp_err_t esp_wifi_init(wifi_init_config_t *config); esp_err_t esp_wifi_init(wifi_init_config_t *config);
@ -123,7 +126,7 @@ esp_err_t esp_wifi_init(wifi_init_config_t *config);
* *
* @attention 1. This API should be called if you want to remove WiFi driver from the system * @attention 1. This API should be called if you want to remove WiFi driver from the system
* *
* @return ESP_OK : succeed * @return ESP_OK: succeed
*/ */
esp_err_t esp_wifi_deinit(void); esp_err_t esp_wifi_deinit(void);
@ -133,25 +136,25 @@ esp_err_t esp_wifi_deinit(void);
* Set the WiFi operating mode as station, soft-AP or station+soft-AP, * Set the WiFi operating mode as station, soft-AP or station+soft-AP,
* The default mode is soft-AP mode. * The default mode is soft-AP mode.
* *
* @param wifi_mode_t mode : WiFi operating modes: * @param mode WiFi operating mode
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
* - others : refer to error code in esp_err.h * - others: refer to error code in esp_err.h
*/ */
esp_err_t esp_wifi_set_mode(wifi_mode_t mode); esp_err_t esp_wifi_set_mode(wifi_mode_t mode);
/** /**
* @brief Get current operating mode of WiFi * @brief Get current operating mode of WiFi
* *
* @param wifi_mode_t *mode : store current WiFi mode * @param[out] mode store current WiFi mode
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
*/ */
esp_err_t esp_wifi_get_mode(wifi_mode_t *mode); esp_err_t esp_wifi_get_mode(wifi_mode_t *mode);
@ -161,29 +164,25 @@ esp_err_t esp_wifi_get_mode(wifi_mode_t *mode);
* If mode is WIFI_MODE_AP, it create soft-AP control block and start soft-AP * If mode is WIFI_MODE_AP, it create soft-AP control block and start soft-AP
* If mode is WIFI_MODE_APSTA, it create soft-AP and station control block and start soft-AP and station * If mode is WIFI_MODE_APSTA, it create soft-AP and station control block and start soft-AP and station
* *
* @param null
*
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
* - ESP_ERR_WIFI_NO_MEM : out of memory * - ESP_ERR_WIFI_NO_MEM: out of memory
* - ESP_ERR_WIFI_CONN : WiFi internal error, station or soft-AP control block wrong * - ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong
* - ESP_ERR_WIFI_FAIL : other WiFi internal errors * - ESP_ERR_WIFI_FAIL: other WiFi internal errors
*/ */
esp_err_t esp_wifi_start(void); esp_err_t esp_wifi_start(void);
/** /**
* @brief Stop WiFi * @brief Stop WiFi
If mode is WIFI_MODE_STA, it stop station and free station control block * If mode is WIFI_MODE_STA, it stop station and free station control block
* If mode is WIFI_MODE_AP, it stop soft-AP and free soft-AP control block * If mode is WIFI_MODE_AP, it stop soft-AP and free soft-AP control block
* If mode is WIFI_MODE_APSTA, it stop station/soft-AP and free station/soft-AP control block * If mode is WIFI_MODE_APSTA, it stop station/soft-AP and free station/soft-AP control block
* *
* @param null
*
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
*/ */
esp_err_t esp_wifi_stop(void); esp_err_t esp_wifi_stop(void);
@ -193,52 +192,47 @@ esp_err_t esp_wifi_stop(void);
* @attention 1. This API only impact WIFI_MODE_STA or WIFI_MODE_APSTA mode * @attention 1. This API only impact WIFI_MODE_STA or WIFI_MODE_APSTA mode
* @attention 2. If the ESP32 is connected to an AP, call esp_wifi_disconnect to disconnect. * @attention 2. If the ESP32 is connected to an AP, call esp_wifi_disconnect to disconnect.
* *
* @param null
*
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_NOT_START : WiFi is not started by esp_wifi_start * - ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start
* - ESP_ERR_WIFI_CONN : WiFi internal error, station or soft-AP control block wrong * - ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong
* - ESP_ERR_WIFI_SSID : SSID of AP which station connects is invalid * - ESP_ERR_WIFI_SSID: SSID of AP which station connects is invalid
*/ */
esp_err_t esp_wifi_connect(void); esp_err_t esp_wifi_connect(void);
/** /**
* @brief Disconnect the ESP32 WiFi station from the AP. * @brief Disconnect the ESP32 WiFi station from the AP.
* *
* @param null
*
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_NOT_START : WiFi is not started by esp_wifi_start * - ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start
* - ESP_ERR_WIFI_FAIL : other WiFi internal errors * - ESP_ERR_WIFI_FAIL: other WiFi internal errors
*/ */
esp_err_t esp_wifi_disconnect(void); esp_err_t esp_wifi_disconnect(void);
/** /**
* @brief Currently this API is just an stub API * @brief Currently this API is just an stub API
* *
* @param null
*
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - others : fail * - others: fail
*/ */
esp_err_t esp_wifi_clear_fast_connect(void); esp_err_t esp_wifi_clear_fast_connect(void);
/** /**
* @brief deauthenticate all stations or associated id equals to aid * @brief deauthenticate all stations or associated id equals to aid
* *
* @param uint16_t aid : when aid is 0, deauthenticate all stations, otherwise deauthenticate station whose associated id is aid * @param aid when aid is 0, deauthenticate all stations, otherwise deauthenticate station whose associated id is aid
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_NOT_START : WiFi is not started by esp_wifi_start * - ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
* - ESP_ERR_WIFI_MODE : WiFi mode is wrong * - ESP_ERR_WIFI_MODE: WiFi mode is wrong
*/ */
esp_err_t esp_wifi_deauth_sta(uint16_t aid); esp_err_t esp_wifi_deauth_sta(uint16_t aid);
@ -249,88 +243,87 @@ esp_err_t esp_wifi_deauth_sta(uint16_t aid);
* will be freed in esp_wifi_get_ap_list, so generally, call esp_wifi_get_ap_list to cause * will be freed in esp_wifi_get_ap_list, so generally, call esp_wifi_get_ap_list to cause
* the memory to be freed once the scan is done * the memory to be freed once the scan is done
* *
* @param struct scan_config *config : configuration of scanning * @param config configuration of scanning
* @param bool block : if block is true, this API will block the caller until the scan is done, otherwise * @param block if block is true, this API will block the caller until the scan is done, otherwise
* it will return immediately * it will return immediately
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_NOT_START : WiFi is not started by esp_wifi_start * - ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start
* - ESP_ERR_WIFI_TIMEOUT : blocking scan is timeout * - ESP_ERR_WIFI_TIMEOUT: blocking scan is timeout
* - others : refer to error code in esp_err.h * - others: refer to error code in esp_err.h
*/ */
esp_err_t esp_wifi_scan_start(wifi_scan_config_t *conf, bool block); esp_err_t esp_wifi_scan_start(wifi_scan_config_t *config, bool block);
/** /**
* @brief Stop the scan in process * @brief Stop the scan in process
* *
* @param null
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_NOT_START : WiFi is not started by esp_wifi_start * - ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start
*/ */
esp_err_t esp_wifi_scan_stop(void); esp_err_t esp_wifi_scan_stop(void);
/** /**
* @brief Get number of APs found in last scan * @brief Get number of APs found in last scan
* *
* @param uint16_t *number : store number of APIs found in last scan * @param[out] number store number of APIs found in last scan
* *
* @attention This API can only be called when the scan is completed, otherwise it may get wrong value * @attention This API can only be called when the scan is completed, otherwise it may get wrong value.
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_NOT_START : WiFi is not started by esp_wifi_start * - ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
*/ */
esp_err_t esp_wifi_scan_get_ap_num(uint16_t *number); esp_err_t esp_wifi_scan_get_ap_num(uint16_t *number);
/** /**
* @brief Get AP list found in last scan * @brief Get AP list found in last scan
* *
* @param uint16_t *number : as input param, it stores max AP number ap_records can hold, as output param, it store * @param[inout] number As input param, it stores max AP number ap_records can hold.
the actual AP number this API returns * As output param, it receives the actual AP number this API returns.
* @param wifi_ap_record_t *ap_records: wifi_ap_record_t array to hold the found APs * @param ap_records wifi_ap_record_t array to hold the found APs
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_NOT_START : WiFi is not started by esp_wifi_start * - ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
* - ESP_ERR_WIFI_NO_MEM : out of memory * - ESP_ERR_WIFI_NO_MEM: out of memory
*/ */
esp_err_t esp_wifi_scan_get_ap_records(uint16_t *number, wifi_ap_record_t *ap_records); esp_err_t esp_wifi_scan_get_ap_records(uint16_t *number, wifi_ap_record_t *ap_records);
/** /**
* @brief Get information of AP associated with ESP32 station * @brief Get information of AP which the ESP32 station is associated with
* *
* @param wifi_ap_record_t *ap_info: the wifi_ap_record_t to hold station assocated AP * @param ap_info the wifi_ap_record_t to hold AP information
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - others : fail * - others: fail
*/ */
esp_err_t esp_wifi_sta_get_ap_info(wifi_ap_record_t *ap_info); esp_err_t esp_wifi_sta_get_ap_info(wifi_ap_record_t *ap_info);
/** /**
* @brief Set current power save type * @brief Set current power save type
* *
* @param wifi_ps_type_t type : power save type * @param type power save type
* *
* @return ESP_ERR_WIFI_NOT_SUPPORT : not support yet * @return ESP_ERR_WIFI_NOT_SUPPORT: not supported yet
*/ */
esp_err_t esp_wifi_set_ps(wifi_ps_type_t type); esp_err_t esp_wifi_set_ps(wifi_ps_type_t type);
/** /**
* @brief Get current power save type * @brief Get current power save type
* *
* @param wifi_ps_type_t *type : store current power save type * @param[out] type: store current power save type
* *
* @return ESP_ERR_WIFI_NOT_SUPPORT : not support yet * @return ESP_ERR_WIFI_NOT_SUPPORT: not supported yet
*/ */
esp_err_t esp_wifi_get_ps(wifi_ps_type_t *type); esp_err_t esp_wifi_get_ps(wifi_ps_type_t *type);
@ -340,47 +333,47 @@ esp_err_t esp_wifi_get_ps(wifi_ps_type_t *type);
* *
* @attention Currently we only support 802.11b or 802.11bg or 802.11bgn mode * @attention Currently we only support 802.11b or 802.11bg or 802.11bgn mode
* *
* @param wifi_interface_t ifx : interfaces * @param ifx interfaces
* @param uint8_t protocol : WiFi protocol bitmap * @param protocol_bitmap WiFi protocol bitmap
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_IF : invalid interface * - ESP_ERR_WIFI_IF: invalid interface
* - others : refer to erro code in esp_err.h * - others: refer to error codes in esp_err.h
*/ */
esp_err_t esp_wifi_set_protocol(wifi_interface_t ifx, uint8_t protocol_bitmap); esp_err_t esp_wifi_set_protocol(wifi_interface_t ifx, uint8_t protocol_bitmap);
/** /**
* @brief Get the current protocol bitmap of specified ifx * @brief Get the current protocol bitmap of the specified interface
* *
* @param wifi_interface_t ifx : interfaces * @param ifx interface
* @param uint8_t protocol : store current WiFi protocol bitmap of interface ifx * @param[out] protocol_bitmap store current WiFi protocol bitmap of interface ifx
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_IF : invalid interface * - ESP_ERR_WIFI_IF: invalid interface
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
* - others : refer to error code in esp_err.h * - others: refer to error codes in esp_err.h
*/ */
esp_err_t esp_wifi_get_protocol(wifi_interface_t ifx, uint8_t *protocol_bitmap); esp_err_t esp_wifi_get_protocol(wifi_interface_t ifx, uint8_t *protocol_bitmap);
/** /**
* @brief Set the bandwidth of ESP32 specified interface * @brief Set the bandwidth of ESP32 specified interface
* *
* @attention 1. API return false if try to configure a interface that is not enable * @attention 1. API return false if try to configure an interface that is not enabled
* @attention 2. WIFI_BW_HT40 is supported only when the interface support 11N * @attention 2. WIFI_BW_HT40 is supported only when the interface support 11N
* *
* @param wifi_interface_t ifx : interface to be configured * @param ifx interface to be configured
* @param wifi_bandwidth_t bw : bandwidth * @param bw bandwidth
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_IF : invalid interface * - ESP_ERR_WIFI_IF: invalid interface
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
* - others : refer to error code in esp_err.h * - others: refer to error codes in esp_err.h
*/ */
esp_err_t esp_wifi_set_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t bw); esp_err_t esp_wifi_set_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t bw);
@ -389,45 +382,45 @@ esp_err_t esp_wifi_set_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t bw);
* *
* @attention 1. API return false if try to get a interface that is not enable * @attention 1. API return false if try to get a interface that is not enable
* *
* @param wifi_interface_t ifx : interface to be configured * @param ifx interface to be configured
* @param wifi_bandwidth_t *bw : store bandwidth of interface ifx * @param[out] bw store bandwidth of interface ifx
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_IF : invalid interface * - ESP_ERR_WIFI_IF: invalid interface
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
*/ */
esp_err_t esp_wifi_get_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t *bw); esp_err_t esp_wifi_get_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t *bw);
/** /**
* @brief Set primary/second channel of ESP32 * @brief Set primary/secondary channel of ESP32
* *
* @attention 1. This is a special API for sniffer * @attention 1. This is a special API for sniffer
* *
* @param uint8_t primary : for HT20, primary is the channel number, for HT40, primary is the primary channel * @param primary for HT20, primary is the channel number, for HT40, primary is the primary channel
* @param wifi_second_chan_t second : for HT20, second is ignored, for HT40, second is the second channel * @param second for HT20, second is ignored, for HT40, second is the second channel
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_IF : invalid interface * - ESP_ERR_WIFI_IF: invalid interface
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
*/ */
esp_err_t esp_wifi_set_channel(uint8_t primary, wifi_second_chan_t second); esp_err_t esp_wifi_set_channel(uint8_t primary, wifi_second_chan_t second);
/** /**
* @brief Get the primary/second channel of ESP32 * @brief Get the primary/secondary channel of ESP32
* *
* @attention 1. API return false if try to get a interface that is not enable * @attention 1. API return false if try to get a interface that is not enable
* *
* @param uint8_t *primary : store current primary channel * @param primary store current primary channel
* @param wifi_second_chan_t *second : store current second channel * @param[out] second store current second channel
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
*/ */
esp_err_t esp_wifi_get_channel(uint8_t *primary, wifi_second_chan_t *second); esp_err_t esp_wifi_get_channel(uint8_t *primary, wifi_second_chan_t *second);
@ -435,25 +428,25 @@ esp_err_t esp_wifi_get_channel(uint8_t *primary, wifi_second_chan_t *second);
* @brief Set country code * @brief Set country code
* The default value is WIFI_COUNTRY_CN * The default value is WIFI_COUNTRY_CN
* *
* @param wifi_country_t country : country type * @param country country type
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
* - others : refer to error code in esp_err.h * - others: refer to error code in esp_err.h
*/ */
esp_err_t esp_wifi_set_country(wifi_country_t country); esp_err_t esp_wifi_set_country(wifi_country_t country);
/** /**
* @brief Get country code * @brief Get country code
* *
* @param wifi_country_t country : store current country * @param country store current country
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
*/ */
esp_err_t esp_wifi_get_country(wifi_country_t *country); esp_err_t esp_wifi_get_country(wifi_country_t *country);
@ -462,33 +455,34 @@ esp_err_t esp_wifi_get_country(wifi_country_t *country);
* *
* @attention 1. This API can only be called when the interface is disabled * @attention 1. This API can only be called when the interface is disabled
* @attention 2. ESP32 soft-AP and station have different MAC addresses, do not set them to be the same. * @attention 2. ESP32 soft-AP and station have different MAC addresses, do not set them to be the same.
* - The bit0 of the first byte of ESP32 MAC address can not be 1. For example, the MAC address * @attention 3. The bit 0 of the first byte of ESP32 MAC address can not be 1. For example, the MAC address
* can set to be "1a:XX:XX:XX:XX:XX", but can not be "15:XX:XX:XX:XX:XX". * can set to be "1a:XX:XX:XX:XX:XX", but can not be "15:XX:XX:XX:XX:XX".
* *
* @param wifi_interface_t ifx : interface * @param ifx interface
* @param uint8 mac[6]: the MAC address. * @param mac the MAC address
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
* - ESP_ERR_WIFI_IF : invalid interface * - ESP_ERR_WIFI_IF: invalid interface
* - ESP_ERR_WIFI_MAC : invalid mac address * - ESP_ERR_WIFI_MAC: invalid mac address
* - ESP_ERR_WIFI_MODE : WiFi mode is wrong * - ESP_ERR_WIFI_MODE: WiFi mode is wrong
* - others : refer to error code in esp_err.h * - others: refer to error codes in esp_err.h
*/ */
esp_err_t esp_wifi_set_mac(wifi_interface_t ifx, uint8_t mac[6]); esp_err_t esp_wifi_set_mac(wifi_interface_t ifx, uint8_t mac[6]);
/** /**
* @brief Get mac of specified interface * @brief Get mac of specified interface
* *
* @param uint8_t mac[6] : store mac of this interface ifx * @param ifx interface
* @param[out] mac store mac of the interface ifx
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
* - ESP_ERR_WIFI_IF : invalid interface * - ESP_ERR_WIFI_IF: invalid interface
*/ */
esp_err_t esp_wifi_get_mac(wifi_interface_t ifx, uint8_t mac[6]); esp_err_t esp_wifi_get_mac(wifi_interface_t ifx, uint8_t mac[6]);
@ -497,8 +491,8 @@ esp_err_t esp_wifi_get_mac(wifi_interface_t ifx, uint8_t mac[6]);
* *
* Each time a packet is received, the callback function will be called. * Each time a packet is received, the callback function will be called.
* *
* @param void *buf : the data received * @param buf the data received
* @param uint16_t len : data length * @param len data length
* *
* @return none * @return none
*/ */
@ -509,34 +503,34 @@ typedef void (* wifi_promiscuous_cb_t)(void *buf, uint16_t len);
* *
* Each time a packet is received, the registered callback function will be called. * Each time a packet is received, the registered callback function will be called.
* *
* @param wifi_promiscuous_cb_t cb : callback * @param cb callback
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
*/ */
esp_err_t esp_wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb); esp_err_t esp_wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb);
/** /**
* @brief Enable the promiscuous mode. * @brief Enable the promiscuous mode.
* *
* @param bool promiscuous : false - disable / true - enable * @param en false - disable, true - enable
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
*/ */
esp_err_t esp_wifi_set_promiscuous(bool en); esp_err_t esp_wifi_set_promiscuous(bool en);
/** /**
* @brief Get the promiscuous mode. * @brief Get the promiscuous mode.
* *
* @param bool *enable : store the current status of promiscuous mode * @param[out] en store the current status of promiscuous mode
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
*/ */
esp_err_t esp_wifi_get_promiscuous(bool *en); esp_err_t esp_wifi_get_promiscuous(bool *en);
@ -548,32 +542,32 @@ esp_err_t esp_wifi_get_promiscuous(bool *en);
* @attention 3. ESP32 is limited to only one channel, so when in the soft-AP+station mode, the soft-AP will adjust its channel automatically to be the same as * @attention 3. ESP32 is limited to only one channel, so when in the soft-AP+station mode, the soft-AP will adjust its channel automatically to be the same as
* the channel of the ESP32 station. * the channel of the ESP32 station.
* *
* @param wifi_interface_t ifx : interface * @param ifx interface
* @param wifi_config_t *conf : station or soft-AP configuration * @param conf station or soft-AP configuration
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
* - ESP_ERR_WIFI_IF : invalid interface * - ESP_ERR_WIFI_IF: invalid interface
* - ESP_ERR_WIFI_MODE : invalid mode * - ESP_ERR_WIFI_MODE: invalid mode
* - ESP_ERR_WIFI_PASSWORD : invalid password * - ESP_ERR_WIFI_PASSWORD: invalid password
* - ESP_ERR_WIFI_NVS : WiFi internal NVS error * - ESP_ERR_WIFI_NVS: WiFi internal NVS error
* - others : refer to the erro code in esp_err.h * - others: refer to the erro code in esp_err.h
*/ */
esp_err_t esp_wifi_set_config(wifi_interface_t ifx, wifi_config_t *conf); esp_err_t esp_wifi_set_config(wifi_interface_t ifx, wifi_config_t *conf);
/** /**
* @brief Get configuration of specified interface * @brief Get configuration of specified interface
* *
* @param wifi_interface_t ifx : interface * @param ifx interface
* @param wifi_config_t *conf : station or soft-AP configuration * @param[out] conf station or soft-AP configuration
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
* - ESP_ERR_WIFI_IF : invalid interface * - ESP_ERR_WIFI_IF: invalid interface
*/ */
esp_err_t esp_wifi_get_config(wifi_interface_t ifx, wifi_config_t *conf); esp_err_t esp_wifi_get_config(wifi_interface_t ifx, wifi_config_t *conf);
@ -582,14 +576,14 @@ esp_err_t esp_wifi_get_config(wifi_interface_t ifx, wifi_config_t *conf);
* *
* @attention SSC only API * @attention SSC only API
* *
* @param wifi_sta_list_t *sta: station list * @param[out] sta station list
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
* - ESP_ERR_WIFI_MODE : WiFi mode is wrong * - ESP_ERR_WIFI_MODE: WiFi mode is wrong
* - ESP_ERR_WIFI_CONN : WiFi internal error, the station/soft-AP control block is invalid * - ESP_ERR_WIFI_CONN: WiFi internal error, the station/soft-AP control block is invalid
*/ */
esp_err_t esp_wifi_ap_get_sta_list(wifi_sta_list_t *sta); esp_err_t esp_wifi_ap_get_sta_list(wifi_sta_list_t *sta);
@ -599,12 +593,12 @@ esp_err_t esp_wifi_ap_get_sta_list(wifi_sta_list_t *sta);
* *
* @attention 1. The default value is WIFI_STORAGE_FLASH * @attention 1. The default value is WIFI_STORAGE_FLASH
* *
* @param wifi_storage_t storage : storage type * @param storage : storage type
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
*/ */
esp_err_t esp_wifi_set_storage(wifi_storage_t storage); esp_err_t esp_wifi_set_storage(wifi_storage_t storage);
@ -612,72 +606,63 @@ esp_err_t esp_wifi_set_storage(wifi_storage_t storage);
* @brief Set auto connect * @brief Set auto connect
* The default value is true * The default value is true
* *
* @param bool en : true - enable auto connect / false - disable auto connect * @param en : true - enable auto connect / false - disable auto connect
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_MODE : WiFi internal error, the station/soft-AP control block is invalid * - ESP_ERR_WIFI_MODE: WiFi internal error, the station/soft-AP control block is invalid
* - others : refer to error code in esp_err.h * - others: refer to error code in esp_err.h
*/ */
esp_err_t esp_wifi_set_auto_connect(bool en); esp_err_t esp_wifi_set_auto_connect(bool en);
/** /**
* @brief Get the auto connect flag * @brief Get the auto connect flag
* *
* @param bool *en : store current auto connect configuration * @param[out] en store current auto connect configuration
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
*/ */
esp_err_t esp_wifi_get_auto_connect(bool *en); esp_err_t esp_wifi_get_auto_connect(bool *en);
/** /**
* @brief Set vendor specific element * @brief Set vendor specific element
* *
* @param bool enable : enable or not * @param enable enable or not
* @param wifi_vendor_ie_type_t type : 0 - WIFI_VND_IE_TYPE_BEACON * @param type information element type
* 1 - WIFI_VND_IE_TYPE_PROBE_REQ * @param idx information element index
* 2 - WIFI_VND_IE_TYPE_PROBE_RESP * @param vnd_ie pointer to a vendor specific element
* 3 - WIFI_VND_IE_TYPE_ASSOC_REQ
* 4 - WIFI_VND_IE_TYPE_ASSOC_RESP
* @param wifi_vendor_ie_id_t idx : 0 - WIFI_VND_IE_ID_0
1 - WIFI_VND_IE_ID_1
* @param uint8_t *vnd_ie : pointer to a vendor specific element
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
* - ESP_ERR_WIFI_ARG : invalid argument * - ESP_ERR_WIFI_ARG: invalid argument
* - ESP_ERR_WIFI_NO_MEM : out of memory * - ESP_ERR_WIFI_NO_MEM: out of memory
*/ */
esp_err_t esp_wifi_set_vendor_ie(bool enable, wifi_vendor_ie_type_t type, wifi_vendor_ie_id_t idx, uint8_t *vnd_ie); esp_err_t esp_wifi_set_vendor_ie(bool enable, wifi_vendor_ie_type_t type, wifi_vendor_ie_id_t idx, uint8_t *vnd_ie);
/** /**
* @brief Define function pointer for vendor specific element callback * @brief Define function pointer for vendor specific element callback
* @param void *ctx : reserved * @param ctx reserved
* @param wifi_vendor_ie_type_t type : 0 - WIFI_VND_IE_TYPE_BEACON * @param type information element type
* 1 - WIFI_VND_IE_TYPE_PROBE_REQ * @param sa source address
* 2 - WIFI_VND_IE_TYPE_PROBE_RESP * @param vnd_ie pointer to a vendor specific element
* 3 - WIFI_VND_IE_TYPE_ASSOC_REQ * @param rssi received signal strength indication
* 4 - WIFI_VND_IE_TYPE_ASSOC_RESP
* @param const uint8_t sa[6] : source address
* @param const uint8_t *vnd_ie : pointer to a vendor specific element
* @param int rssi : received signal strength indication
*/ */
typedef void (*esp_vendor_ie_cb_t) (void *ctx, wifi_vendor_ie_type_t type, const uint8_t sa[6], const uint8_t *vnd_ie, int rssi); typedef void (*esp_vendor_ie_cb_t) (void *ctx, wifi_vendor_ie_type_t type, const uint8_t sa[6], const uint8_t *vnd_ie, int rssi);
/** /**
* @brief Set vendor specific element callback * @brief Set vendor specific element callback
* *
* @param esp_vendor_ie_cb_t cb : callback function * @param cb callback function
* @param void *ctx : reserved * @param ctx reserved
* *
* @return * @return
* - ESP_OK : succeed * - ESP_OK: succeed
* - ESP_ERR_WIFI_NOT_INIT : WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init
*/ */
esp_err_t esp_wifi_set_vendor_ie_cb(esp_vendor_ie_cb_t cb, void *ctx); esp_err_t esp_wifi_set_vendor_ie_cb(esp_vendor_ie_cb_t cb, void *ctx);

107
components/nvs_flash/include/nvs.h
View File

@ -77,8 +77,9 @@ typedef enum {
*/ */
esp_err_t nvs_open(const char* name, nvs_open_mode open_mode, nvs_handle *out_handle); esp_err_t nvs_open(const char* name, nvs_open_mode open_mode, nvs_handle *out_handle);
/**@{*/
/** /**
* @brief nvs_set_X - set value for given key * @brief set value for given key
* *
* This family of functions set value for the key, given its name. Note that * This family of functions set value for the key, given its name. Note that
* actual storage will not be updated until nvs_commit function is called. * actual storage will not be updated until nvs_commit function is called.
@ -89,7 +90,6 @@ esp_err_t nvs_open(const char* name, nvs_open_mode open_mode, nvs_handle *out_ha
* implementation, but is guaranteed to be at least * implementation, but is guaranteed to be at least
* 16 characters. Shouldn't be empty. * 16 characters. Shouldn't be empty.
* @param[in] value The value to set. * @param[in] value The value to set.
* @param[in] length For nvs_set_blob: length of binary value to set, in bytes.
* *
* @return * @return
* - ESP_OK if value was set successfully * - ESP_OK if value was set successfully
@ -112,10 +112,39 @@ esp_err_t nvs_set_u32 (nvs_handle handle, const char* key, uint32_t value);
esp_err_t nvs_set_i64 (nvs_handle handle, const char* key, int64_t value); esp_err_t nvs_set_i64 (nvs_handle handle, const char* key, int64_t value);
esp_err_t nvs_set_u64 (nvs_handle handle, const char* key, uint64_t value); esp_err_t nvs_set_u64 (nvs_handle handle, const char* key, uint64_t value);
esp_err_t nvs_set_str (nvs_handle handle, const char* key, const char* value); esp_err_t nvs_set_str (nvs_handle handle, const char* key, const char* value);
esp_err_t nvs_set_blob(nvs_handle handle, const char* key, const void* value, size_t length); /**@}*/
/** /**
* @brief nvs_get_X - get value for given key * @brief set variable length binary value for given key
*
* This family of functions set value for the key, given its name. Note that
* actual storage will not be updated until nvs_commit function is called.
*
* @param[in] handle Handle obtained from nvs_open function.
* Handles that were opened read only cannot be used.
* @param[in] key Key name. Maximal length is determined by the underlying
* implementation, but is guaranteed to be at least
* 16 characters. Shouldn't be empty.
* @param[in] value The value to set.
* @param[in] length length of binary value to set, in bytes.
*
* @return
* - ESP_OK if value was set successfully
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the
* underlying storage to save the value
* - ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash
* write operation has failed. The value was written however, and
* update will be finished after re-initialization of nvs, provided that
* flash operation doesn't fail again.
*/
esp_err_t nvs_set_blob(nvs_handle handle, const char* key, const void* value, size_t length);
/**@{*/
/**
* @brief get value for given key
* *
* These functions retrieve value for the key, given its name. If key does not * These functions retrieve value for the key, given its name. If key does not
* exist, or the requested variable type doesn't match the type which was used * exist, or the requested variable type doesn't match the type which was used
@ -125,7 +154,55 @@ esp_err_t nvs_set_blob(nvs_handle handle, const char* key, const void* value, si
* *
* All functions expect out_value to be a pointer to an already allocated variable * All functions expect out_value to be a pointer to an already allocated variable
* of the given type. * of the given type.
* Additionally, nvs_get_str and nvs_get_blob support WinAPI-style length queries. *
* \code{c}
* // Example of using nvs_get_i32:
* int32_t max_buffer_size = 4096; // default value
* esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size);
* assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND);
* // if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still
* // have its default value.
*
* \endcode
*
* @param[in] handle Handle obtained from nvs_open function.
* @param[in] key Key name. Maximal length is determined by the underlying
* implementation, but is guaranteed to be at least
* 16 characters. Shouldn't be empty.
* @param out_value Pointer to the output value.
* May be NULL for nvs_get_str and nvs_get_blob, in this
* case required length will be returned in length argument.
*
* @return
* - ESP_OK if the value was retrieved successfully
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data
*/
esp_err_t nvs_get_i8 (nvs_handle handle, const char* key, int8_t* out_value);
esp_err_t nvs_get_u8 (nvs_handle handle, const char* key, uint8_t* out_value);
esp_err_t nvs_get_i16 (nvs_handle handle, const char* key, int16_t* out_value);
esp_err_t nvs_get_u16 (nvs_handle handle, const char* key, uint16_t* out_value);
esp_err_t nvs_get_i32 (nvs_handle handle, const char* key, int32_t* out_value);
esp_err_t nvs_get_u32 (nvs_handle handle, const char* key, uint32_t* out_value);
esp_err_t nvs_get_i64 (nvs_handle handle, const char* key, int64_t* out_value);
esp_err_t nvs_get_u64 (nvs_handle handle, const char* key, uint64_t* out_value);
/**@}*/
/**
* @brief get value for given key
*
* These functions retrieve value for the key, given its name. If key does not
* exist, or the requested variable type doesn't match the type which was used
* when setting a value, an error is returned.
*
* In case of any error, out_value is not modified.
*
* All functions expect out_value to be a pointer to an already allocated variable
* of the given type.
*
* nvs_get_str and nvs_get_blob functions support WinAPI-style length queries.
* To get the size necessary to store the value, call nvs_get_str or nvs_get_blob * To get the size necessary to store the value, call nvs_get_str or nvs_get_blob
* with zero out_value and non-zero pointer to length. Variable pointed to * with zero out_value and non-zero pointer to length. Variable pointed to
* by length argument will be set to the required length. For nvs_get_str, * by length argument will be set to the required length. For nvs_get_str,
@ -136,13 +213,6 @@ esp_err_t nvs_set_blob(nvs_handle handle, const char* key, const void* value, si
* nvs_get/set_blob used for arbitrary data structures. * nvs_get/set_blob used for arbitrary data structures.
* *
* \code{c} * \code{c}
* // Example of using nvs_get_i32:
* int32_t max_buffer_size = 4096; // default value
* esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size);
* assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND);
* // if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still
* // have its default value.
*
* // Example (without error checking) of using nvs_get_str to get a string into dynamic array: * // Example (without error checking) of using nvs_get_str to get a string into dynamic array:
* size_t required_size; * size_t required_size;
* nvs_get_str(my_handle, "server_name", NULL, &required_size); * nvs_get_str(my_handle, "server_name", NULL, &required_size);
@ -163,8 +233,7 @@ esp_err_t nvs_set_blob(nvs_handle handle, const char* key, const void* value, si
* @param out_value Pointer to the output value. * @param out_value Pointer to the output value.
* May be NULL for nvs_get_str and nvs_get_blob, in this * May be NULL for nvs_get_str and nvs_get_blob, in this
* case required length will be returned in length argument. * case required length will be returned in length argument.
* @param[inout] length For nvs_get_str and nvs_get_blob, non-zero pointer * @param[inout] length A non-zero pointer to the variable holding the length of out_value.
* to the variable holding the length of out_value.
* In case out_value a zero, will be set to the length * In case out_value a zero, will be set to the length
* required to hold the value. In case out_value is not * required to hold the value. In case out_value is not
* zero, will be set to the actual length of the value * zero, will be set to the actual length of the value
@ -177,16 +246,10 @@ esp_err_t nvs_set_blob(nvs_handle handle, const char* key, const void* value, si
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints * - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data * - ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data
*/ */
esp_err_t nvs_get_i8 (nvs_handle handle, const char* key, int8_t* out_value); /**@{*/
esp_err_t nvs_get_u8 (nvs_handle handle, const char* key, uint8_t* out_value);
esp_err_t nvs_get_i16 (nvs_handle handle, const char* key, int16_t* out_value);
esp_err_t nvs_get_u16 (nvs_handle handle, const char* key, uint16_t* out_value);
esp_err_t nvs_get_i32 (nvs_handle handle, const char* key, int32_t* out_value);
esp_err_t nvs_get_u32 (nvs_handle handle, const char* key, uint32_t* out_value);
esp_err_t nvs_get_i64 (nvs_handle handle, const char* key, int64_t* out_value);
esp_err_t nvs_get_u64 (nvs_handle handle, const char* key, uint64_t* out_value);
esp_err_t nvs_get_str (nvs_handle handle, const char* key, char* out_value, size_t* length); esp_err_t nvs_get_str (nvs_handle handle, const char* key, char* out_value, size_t* length);
esp_err_t nvs_get_blob(nvs_handle handle, const char* key, void* out_value, size_t* length); esp_err_t nvs_get_blob(nvs_handle handle, const char* key, void* out_value, size_t* length);
/**@}*/
/** /**
* @brief Erase key-value pair with given key name. * @brief Erase key-value pair with given key name.

95
components/spi_flash/include/esp_partition.h
View File

@ -25,57 +25,78 @@
extern "C" { extern "C" {
#endif #endif
/**
* @file esp_partition.h
* @brief Partition APIs
*/
/**
* @brief Partition type
* @note Keep this enum in sync with PartitionDefinition class gen_esp32part.py
*/
typedef enum { typedef enum {
ESP_PARTITION_TYPE_APP = 0x00, ESP_PARTITION_TYPE_APP = 0x00, //!< Application partition type
ESP_PARTITION_TYPE_DATA = 0x01, ESP_PARTITION_TYPE_DATA = 0x01, //!< Data partition type
ESP_PARTITION_TYPE_FILESYSTEM = 0x02,
} esp_partition_type_t; } esp_partition_type_t;
/**
* @brief Partition subtype
* @note Keep this enum in sync with PartitionDefinition class gen_esp32part.py
*/
typedef enum { typedef enum {
ESP_PARTITION_SUBTYPE_APP_FACTORY = 0x00, ESP_PARTITION_SUBTYPE_APP_FACTORY = 0x00, //!< Factory application partition
ESP_PARTITION_SUBTYPE_APP_OTA_MIN = 0x10, ESP_PARTITION_SUBTYPE_APP_OTA_MIN = 0x10, //!< Base for OTA partition subtypes
ESP_PARTITION_SUBTYPE_APP_OTA_0 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 0, ESP_PARTITION_SUBTYPE_APP_OTA_0 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 0, //!< OTA partition 0
ESP_PARTITION_SUBTYPE_APP_OTA_1 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 1, ESP_PARTITION_SUBTYPE_APP_OTA_1 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 1, //!< OTA partition 1
ESP_PARTITION_SUBTYPE_APP_OTA_2 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 2, ESP_PARTITION_SUBTYPE_APP_OTA_2 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 2, //!< OTA partition 2
ESP_PARTITION_SUBTYPE_APP_OTA_3 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 3, ESP_PARTITION_SUBTYPE_APP_OTA_3 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 3, //!< OTA partition 3
ESP_PARTITION_SUBTYPE_APP_OTA_4 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 4, ESP_PARTITION_SUBTYPE_APP_OTA_4 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 4, //!< OTA partition 4
ESP_PARTITION_SUBTYPE_APP_OTA_5 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 5, ESP_PARTITION_SUBTYPE_APP_OTA_5 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 5, //!< OTA partition 5
ESP_PARTITION_SUBTYPE_APP_OTA_6 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 6, ESP_PARTITION_SUBTYPE_APP_OTA_6 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 6, //!< OTA partition 6
ESP_PARTITION_SUBTYPE_APP_OTA_7 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 7, ESP_PARTITION_SUBTYPE_APP_OTA_7 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 7, //!< OTA partition 7
ESP_PARTITION_SUBTYPE_APP_OTA_8 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 8, ESP_PARTITION_SUBTYPE_APP_OTA_8 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 8, //!< OTA partition 8
ESP_PARTITION_SUBTYPE_APP_OTA_9 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 9, ESP_PARTITION_SUBTYPE_APP_OTA_9 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 9, //!< OTA partition 9
ESP_PARTITION_SUBTYPE_APP_OTA_10 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 10, ESP_PARTITION_SUBTYPE_APP_OTA_10 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 10,//!< OTA partition 10
ESP_PARTITION_SUBTYPE_APP_OTA_11 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 11, ESP_PARTITION_SUBTYPE_APP_OTA_11 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 11,//!< OTA partition 11
ESP_PARTITION_SUBTYPE_APP_OTA_12 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 12, ESP_PARTITION_SUBTYPE_APP_OTA_12 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 12,//!< OTA partition 12
ESP_PARTITION_SUBTYPE_APP_OTA_13 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 13, ESP_PARTITION_SUBTYPE_APP_OTA_13 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 13,//!< OTA partition 13
ESP_PARTITION_SUBTYPE_APP_OTA_14 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 14, ESP_PARTITION_SUBTYPE_APP_OTA_14 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 14,//!< OTA partition 14
ESP_PARTITION_SUBTYPE_APP_OTA_15 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 15, ESP_PARTITION_SUBTYPE_APP_OTA_15 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 15,//!< OTA partition 15
ESP_PARTITION_SUBTYPE_APP_OTA_MAX = 15, ESP_PARTITION_SUBTYPE_APP_OTA_MAX = 15, //!< Max subtype of OTA partition
ESP_PARTITION_SUBTYPE_APP_TEST = 0x20, ESP_PARTITION_SUBTYPE_APP_TEST = 0x20, //!< Test application partition
ESP_PARTITION_SUBTYPE_DATA_OTA = 0x00, ESP_PARTITION_SUBTYPE_DATA_OTA = 0x00, //!< OTA selection partition
ESP_PARTITION_SUBTYPE_DATA_RF = 0x01, ESP_PARTITION_SUBTYPE_DATA_PHY = 0x01, //!< PHY init data partition
ESP_PARTITION_SUBTYPE_DATA_NVS = 0x02, ESP_PARTITION_SUBTYPE_DATA_NVS = 0x02, //!< NVS partition
ESP_PARTITION_SUBTYPE_FILESYSTEM_ESPHTTPD = 0x00, ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD = 0x80, //!< ESPHTTPD partition
ESP_PARTITION_SUBTYPE_FILESYSTEM_FAT = 0x01, ESP_PARTITION_SUBTYPE_DATA_FAT = 0x81, //!< FAT partition
ESP_PARTITION_SUBTYPE_FILESYSTEM_SPIFFS = 0x02, ESP_PARTITION_SUBTYPE_DATA_SPIFFS = 0x82, //!< SPIFFS partition
ESP_PARTITION_SUBTYPE_ANY = 0xff, ESP_PARTITION_SUBTYPE_ANY = 0xff, //!< Used to search for partitions with any subtype
} esp_partition_subtype_t; } esp_partition_subtype_t;
/**
* @brief Convenience macro to get esp_partition_subtype_t value for the i-th OTA partition
*/
#define ESP_PARTITION_SUBTYPE_OTA(i) ((esp_partition_subtype_t)(ESP_PARTITION_SUBTYPE_APP_OTA_MIN + ((i) & 0xf))) #define ESP_PARTITION_SUBTYPE_OTA(i) ((esp_partition_subtype_t)(ESP_PARTITION_SUBTYPE_APP_OTA_MIN + ((i) & 0xf)))
/**
* @brief Opaque partition iterator type
*/
typedef struct esp_partition_iterator_opaque_* esp_partition_iterator_t; typedef struct esp_partition_iterator_opaque_* esp_partition_iterator_t;
/**
* @brief partition information structure
*/
typedef struct { typedef struct {
esp_partition_type_t type; esp_partition_type_t type; /*!< partition type (app/data) */
esp_partition_subtype_t subtype; esp_partition_subtype_t subtype; /*!< partition subtype */
uint32_t address; uint32_t address; /*!< starting address of the partition in flash */
uint32_t size; uint32_t size; /*!< size of the partition, in bytes */
char label[17]; char label[17]; /*!< partition label, zero-terminated ASCII string */
bool encrypted; bool encrypted; /*!< flag is set to true if partition is encrypted */
} esp_partition_t; } esp_partition_t;
/** /**

6
components/spi_flash/include/esp_spi_flash.h
View File

@ -62,13 +62,13 @@ esp_err_t spi_flash_erase_sector(size_t sector);
/** /**
* @brief Erase a range of flash sectors * @brief Erase a range of flash sectors
* *
* @param uint32_t start_address : Address where erase operation has to start. * @param start_address Address where erase operation has to start.
* Must be 4kB-aligned * Must be 4kB-aligned
* @param uint32_t size : Size of erased range, in bytes. Must be divisible by 4kB. * @param size Size of erased range, in bytes. Must be divisible by 4kB.
* *
* @return esp_err_t * @return esp_err_t
*/ */
esp_err_t spi_flash_erase_range(size_t start_addr, size_t size); esp_err_t spi_flash_erase_range(size_t start_address, size_t size);
/** /**

10
components/vfs/include/esp_vfs.h
View File

@ -57,15 +57,15 @@ extern "C" {
* flags member to ESP_VFS_FLAG_CONTEXT_PTR and provide the context pointer * flags member to ESP_VFS_FLAG_CONTEXT_PTR and provide the context pointer
* to esp_vfs_register function. * to esp_vfs_register function.
* If the implementation doesn't use this extra argument, populate the * If the implementation doesn't use this extra argument, populate the
* members without _p suffix and set flags memeber to ESP_VFS_FLAG_DEFAULT. * members without _p suffix and set flags member to ESP_VFS_FLAG_DEFAULT.
* *
* If the FS driver doesn't provide some of the functions, set corresponding * If the FS driver doesn't provide some of the functions, set corresponding
* members to NULL. * members to NULL.
*/ */
typedef struct typedef struct
{ {
int fd_offset; int fd_offset; /*!< file descriptor offset, determined by the FS driver */
int flags; int flags; /*!< ESP_VFS_FLAG_CONTEXT_PTR or ESP_VFS_FLAG_DEFAULT */
union { union {
size_t (*write_p)(void* p, int fd, const void * data, size_t size); size_t (*write_p)(void* p, int fd, const void * data, size_t size);
size_t (*write)(int fd, const void * data, size_t size); size_t (*write)(int fd, const void * data, size_t size);
@ -135,7 +135,7 @@ esp_err_t esp_vfs_register(const char* base_path, const esp_vfs_t* vfs, void* ct
* These functions are to be used in newlib syscall table. They will be called by * These functions are to be used in newlib syscall table. They will be called by
* newlib when it needs to use any of the syscalls. * newlib when it needs to use any of the syscalls.
*/ */
/**@{*/
ssize_t esp_vfs_write(struct _reent *r, int fd, const void * data, size_t size); ssize_t esp_vfs_write(struct _reent *r, int fd, const void * data, size_t size);
off_t esp_vfs_lseek(struct _reent *r, int fd, off_t size, int mode); off_t esp_vfs_lseek(struct _reent *r, int fd, off_t size, int mode);
ssize_t esp_vfs_read(struct _reent *r, int fd, void * dst, size_t size); ssize_t esp_vfs_read(struct _reent *r, int fd, void * dst, size_t size);
@ -146,7 +146,7 @@ int esp_vfs_stat(struct _reent *r, const char * path, struct stat * st);
int esp_vfs_link(struct _reent *r, const char* n1, const char* n2); int esp_vfs_link(struct _reent *r, const char* n1, const char* n2);
int esp_vfs_unlink(struct _reent *r, const char *path); int esp_vfs_unlink(struct _reent *r, const char *path);
int esp_vfs_rename(struct _reent *r, const char *src, const char *dst); int esp_vfs_rename(struct _reent *r, const char *src, const char *dst);
/**@}*/
#ifdef __cplusplus #ifdef __cplusplus

3
docs/Doxyfile
View File

@ -20,9 +20,8 @@ XML_OUTPUT = xml
GENERATE_HTML = NO GENERATE_HTML = NO
HAVE_DOT = NO HAVE_DOT = NO
GENERATE_LATEX = NO GENERATE_LATEX = NO
GENERATE_MAN = NO GENERATE_MAN = YES
GENERATE_RTF = NO GENERATE_RTF = NO
QUIET = YES
WARN_LOGFILE = "doxygen-warning-log.txt" WARN_LOGFILE = "doxygen-warning-log.txt"