diff --git a/esp_iot_sdk_v1.5.2/include/espconn.h b/esp_iot_sdk_v1.5.2/include/espconn.h index 5c2454a..174c34d 100644 --- a/esp_iot_sdk_v1.5.2/include/espconn.h +++ b/esp_iot_sdk_v1.5.2/include/espconn.h @@ -7,7 +7,45 @@ typedef sint8 err_t; typedef void *espconn_handle; + +/** + * @brief Connect callback. + * + * Callback which will be called if successful listening (ESP8266 as TCP server) + * or connection (ESP8266 as TCP client) callback, register by espconn_regist_connectcb. + * + * @attention The pointer "void *arg" may be different in different callbacks, please don't + * use this pointer directly to distinguish one from another in multiple connections, + * use remote_ip and remote_port in espconn instead. + * + * @param void *arg : pointer corresponding structure espconn. + * + * @return null + */ typedef void (* espconn_connect_callback)(void *arg); + +/** + * @brief Reconnect callback. + * + * Enter this callback when error occurred, TCP connection broke. This callback is + * registered by espconn_regist_reconcb. + * + * @attention The pointer "void *arg" may be different in different callbacks, please don't + * use this pointer directly to distinguish one from another in multiple connections, + * use remote_ip and remote_port in espconn instead. + * + * @param void *arg : pointer corresponding structure espconn. + * @param sint8 err : error code + * - ESCONN_TIMEOUT - Timeout + * - ESPCONN_ABRT - TCP connection aborted + * - ESPCONN_RST - TCP connection abort + * - ESPCONN_CLSD - TCP connection closed + * - ESPCONN_CONN - TCP connection + * - ESPCONN_HANDSHAKE - TCP SSL handshake fail + * - ESPCONN_PROTO_MSG - SSL application invalid + * + * @return null + */ typedef void (* espconn_reconnect_callback)(void *arg, sint8 err); /* Definitions for error constants. */ @@ -17,7 +55,7 @@ typedef void (* espconn_reconnect_callback)(void *arg, sint8 err); #define ESPCONN_TIMEOUT -3 /* Timeout. */ #define ESPCONN_RTE -4 /* Routing problem. */ #define ESPCONN_INPROGRESS -5 /* Operation in progress */ -#define ESPCONN_MAXNUM -7 /* Total number exceeds the set maximum*/ +#define ESPCONN_MAXNUM -7 /* Total number exceeds the set maximum*/ #define ESPCONN_ABRT -8 /* Connection aborted. */ #define ESPCONN_RST -9 /* Connection reset. */ @@ -25,55 +63,53 @@ typedef void (* espconn_reconnect_callback)(void *arg, sint8 err); #define ESPCONN_CONN -11 /* Not connected. */ #define ESPCONN_ARG -12 /* Illegal argument. */ -#define ESPCONN_IF -14 /* UDP send error */ +#define ESPCONN_IF -14 /* UDP send error */ #define ESPCONN_ISCONN -15 /* Already connected. */ -#define ESPCONN_HANDSHAKE -28 /* ssl handshake failed */ -#define ESPCONN_SSL_INVALID_DATA -61 /* ssl application invalid */ +#define ESPCONN_HANDSHAKE -28 /* ssl handshake failed */ +#define ESPCONN_SSL_INVALID_DATA -61 /* ssl application invalid */ /** Protocol family and type of the espconn */ enum espconn_type { - ESPCONN_INVALID = 0, - /* ESPCONN_TCP Group */ - ESPCONN_TCP = 0x10, - /* ESPCONN_UDP Group */ - ESPCONN_UDP = 0x20, + ESPCONN_INVALID = 0, /**< invalid type */ + ESPCONN_TCP = 0x10, /**< TCP */ + ESPCONN_UDP = 0x20, /**< UDP */ }; -/** Current state of the espconn. Non-TCP espconn are always in state ESPCONN_NONE! */ +/** Current state of the espconn. */ enum espconn_state { - ESPCONN_NONE, - ESPCONN_WAIT, - ESPCONN_LISTEN, - ESPCONN_CONNECT, - ESPCONN_WRITE, - ESPCONN_READ, - ESPCONN_CLOSE + ESPCONN_NONE, /**< idle state, no connection */ + ESPCONN_WAIT, /**< ESP8266 is as TCP client, and waiting for connection */ + ESPCONN_LISTEN, /**< ESP8266 is as TCP server, and waiting for connection */ + ESPCONN_CONNECT, /**< connected */ + ESPCONN_WRITE, /**< sending data */ + ESPCONN_READ, /**< receiving data */ + ESPCONN_CLOSE /**< connection closed */ }; typedef struct _esp_tcp { - int remote_port; - int local_port; - uint8 local_ip[4]; - uint8 remote_ip[4]; - espconn_connect_callback connect_callback; - espconn_reconnect_callback reconnect_callback; - espconn_connect_callback disconnect_callback; - espconn_connect_callback write_finish_fn; + int remote_port; /**< remote port of TCP connection */ + int local_port; /**< ESP8266's local port of TCP connection */ + uint8 local_ip[4]; /**< local IP of ESP8266 */ + uint8 remote_ip[4]; /**< remote IP of TCP connection */ + espconn_connect_callback connect_callback; /**< connected callback */ + espconn_reconnect_callback reconnect_callback; /**< as error handler, the TCP connection broke unexpectedly */ + espconn_connect_callback disconnect_callback; /**< disconnected callback */ + espconn_connect_callback write_finish_fn; /**< data send by espconn_send has wrote into buffer waiting for sending, or has sent successfully */ } esp_tcp; typedef struct _esp_udp { - int remote_port; - int local_port; - uint8 local_ip[4]; - uint8 remote_ip[4]; + int remote_port; /**< remote port of UDP transmission */ + int local_port; /**< ESP8266's local port for UDP transmission */ + uint8 local_ip[4]; /**< local IP of ESP8266 */ + uint8 remote_ip[4]; /**< remote IP of UDP transmission */ } esp_udp; -typedef struct _remot_info{ - enum espconn_state state; - int remote_port; - uint8 remote_ip[4]; -}remot_info; +typedef struct _remot_info { + enum espconn_state state; /**< state of espconn */ + int remote_port; /**< remote port */ + uint8 remote_ip[4]; /**< remote IP address */ +} remot_info; /** A callback prototype to inform about events for a espconn */ typedef void (* espconn_recv_callback)(void *arg, char *pdata, unsigned short len); @@ -81,34 +117,31 @@ typedef void (* espconn_sent_callback)(void *arg); /** A espconn descriptor */ struct espconn { - /** type of the espconn (TCP, UDP) */ - enum espconn_type type; - /** current state of the espconn */ - enum espconn_state state; + enum espconn_type type; /**< type of the espconn (TCP or UDP) */ + enum espconn_state state; /**< current state of the espconn */ union { esp_tcp *tcp; esp_udp *udp; } proto; - /** A callback function that is informed about events for this espconn */ - espconn_recv_callback recv_callback; - espconn_sent_callback sent_callback; - uint8 link_cnt; - void *reverse; + espconn_recv_callback recv_callback; /**< data received callback */ + espconn_sent_callback sent_callback; /**< data sent callback */ + uint8 link_cnt; /**< link count */ + void *reserve; /**< reserved for user data */ }; -enum espconn_option{ - ESPCONN_START = 0x00, - ESPCONN_REUSEADDR = 0x01, - ESPCONN_NODELAY = 0x02, - ESPCONN_COPY = 0x04, - ESPCONN_KEEPALIVE = 0x08, - ESPCONN_END +enum espconn_option { + ESPCONN_START = 0x00, /**< no option, start enum. */ + ESPCONN_REUSEADDR = 0x01, /**< free memory after TCP disconnection happen, need not wait 2 minutes. */ + ESPCONN_NODELAY = 0x02, /**< disable nagle algorithm during TCP data transmission, quicken the data transmission. */ + ESPCONN_COPY = 0x04, /**< enable espconn_regist_write_finish, enter write_finish_callback means that the data espconn_send sending was written into 2920 bytes write-buffer waiting for sending or already sent. */ + ESPCONN_KEEPALIVE = 0x08, /**< enable TCP keep alive. */ + ESPCONN_END /**< no option, end enum. */ }; -enum espconn_level{ - ESPCONN_KEEPIDLE, - ESPCONN_KEEPINTVL, - ESPCONN_KEEPCNT +enum espconn_level { + ESPCONN_KEEPIDLE, /**< TCP keep-alive interval, unit : second. */ + ESPCONN_KEEPINTVL, /**< packet interval during TCP keep-alive, unit : second. */ + ESPCONN_KEEPCNT /**< maximum packet retry count of TCP keep-alive. */ }; enum { @@ -119,13 +152,13 @@ enum { ESPCONN_MAX }; -struct espconn_packet{ - uint16 sent_length; /* sent length successful*/ - uint16 snd_buf_size; /* Available buffer size for sending */ - uint16 snd_queuelen; /* Available buffer space for sending */ - uint16 total_queuelen; /* total Available buffer space for sending */ - uint32 packseqno; /* seqno to be sent */ - uint32 packseq_nxt; /* seqno expected */ +struct espconn_packet { + uint16 sent_length; /* sent length successful*/ + uint16 snd_buf_size; /* Available buffer size for sending */ + uint16 snd_queuelen; /* Available buffer space for sending */ + uint16 total_queuelen; /* total Available buffer space for sending */ + uint32 packseqno; /* seqno to be sent */ + uint32 packseq_nxt; /* seqno expected */ uint32 packnum; }; @@ -136,303 +169,443 @@ struct mdns_info { unsigned long ipAddr; char *txt_data[10]; }; -/****************************************************************************** - * FunctionName : espconn_connect - * Description : The function given as the connect - * Parameters : espconn -- the espconn used to listen the connection - * Returns : none -*******************************************************************************/ +/** + * @brief Connect to a TCP server (ESP8266 acting as TCP client). + * + * @attention If espconn_connect fail, returns non-0 value, there is no connection, so it + * won't enter any espconn callback. + * + * @param struct espconn *espconn : the network connection structure, the espconn to + * listen to the connection + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_RTE - Routing Problem + * - ESPCONN_MEM - Out of memory + * - ESPCONN_ISCONN - Already connected + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection + * according to structure espconn + */ sint8 espconn_connect(struct espconn *espconn); -/****************************************************************************** - * FunctionName : espconn_disconnect - * Description : disconnect with host - * Parameters : espconn -- the espconn used to disconnect the connection - * Returns : none -*******************************************************************************/ - +/** + * @brief Disconnect a TCP connection. + * + * @attention Don't call this API in any espconn callback. If needed, please use system + * task to trigger espconn_disconnect. + * + * @param struct espconn *espconn : the network connection structure + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection + * according to structure espconn + */ sint8 espconn_disconnect(struct espconn *espconn); -/****************************************************************************** - * FunctionName : espconn_delete - * Description : disconnect with host - * Parameters : espconn -- the espconn used to disconnect the connection - * Returns : none -*******************************************************************************/ - +/** + * @brief Delete a transmission. + * + * @attention Corresponding creation API : + * - TCP: espconn_accept, + * - UDP: espconn_create + * + * @param struct espconn *espconn : the network connection structure + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding network according + * to structure espconn + */ sint8 espconn_delete(struct espconn *espconn); -/****************************************************************************** - * FunctionName : espconn_accept - * Description : The function given as the listen - * Parameters : espconn -- the espconn used to listen the connection - * Returns : none -*******************************************************************************/ - +/** + * @brief Creates a TCP server (i.e. accepts connections). + * + * @param struct espconn *espconn : the network connection structure + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_MEM - Out of memory + * - ESPCONN_ISCONN - Already connected + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection + * according to structure espconn + */ sint8 espconn_accept(struct espconn *espconn); -/****************************************************************************** - * FunctionName : espconn_create - * Description : sent data for client or server - * Parameters : espconn -- espconn to the data transmission - * Returns : result -*******************************************************************************/ - +/** + * @brief Create UDP transmission. + * + * @attention Parameter remote_ip and remote_port need to be set, do not set to be 0. + * + * @param struct espconn *espconn : the UDP control block structure + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_MEM - Out of memory + * - ESPCONN_ISCONN - Already connected + * - ESPCONN_ARG - illegal argument, can't find the corresponding UDP transmission + * according to structure espconn + */ sint8 espconn_create(struct espconn *espconn); -/****************************************************************************** - * FunctionName : espconn_tcp_get_max_con - * Description : get the number of simulatenously active TCP connections - * Parameters : none - * Returns : none -*******************************************************************************/ +/** + * @brief Get maximum number of how many TCP connections are allowed. + * + * @param null + * + * @return Maximum number of how many TCP connections are allowed. + */ uint8 espconn_tcp_get_max_con(void); -/****************************************************************************** - * FunctionName : espconn_tcp_set_max_con - * Description : set the number of simulatenously active TCP connections - * Parameters : num -- total number - * Returns : none -*******************************************************************************/ - +/** + * @brief Set the maximum number of how many TCP connection is allowed. + * + * @param uint8 num : Maximum number of how many TCP connection is allowed. + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection + * according to structure espconn + */ sint8 espconn_tcp_set_max_con(uint8 num); -/****************************************************************************** - * FunctionName : espconn_tcp_get_max_con_allow - * Description : get the count of simulatenously active connections on the server - * Parameters : espconn -- espconn to get the count - * Returns : result -*******************************************************************************/ - +/** + * @brief Get the maximum number of TCP clients which are allowed to connect to ESP8266 TCP server. + * + * @param struct espconn *espconn : the TCP server structure + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection according + * to structure espconn + */ sint8 espconn_tcp_get_max_con_allow(struct espconn *espconn); -/****************************************************************************** - * FunctionName : espconn_tcp_set_max_con_allow - * Description : set the count of simulatenously active connections on the server - * Parameters : espconn -- espconn to set the count - * num -- support the connection number - * Returns : result -*******************************************************************************/ - +/** + * @brief Set the maximum number of TCP clients allowed to connect to ESP8266 TCP server. + * + * @param struct espconn *espconn : the TCP server structure + * @param uint8 num : Maximum number of TCP clients which are allowed + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection according + * to structure espconn + */ sint8 espconn_tcp_set_max_con_allow(struct espconn *espconn, uint8 num); -/****************************************************************************** - * FunctionName : espconn_regist_time - * Description : used to specify the time that should be called when don't recv data - * Parameters : espconn -- the espconn used to the connection - * interval -- the timer when don't recv data - * Returns : none -*******************************************************************************/ - +/** + * @brief Register timeout interval of ESP8266 TCP server. + * + * @attention 1. If timeout is set to 0, timeout will be disable and ESP8266 TCP server will + * not disconnect TCP clients has stopped communication. This usage of timeout=0, + * is deprecated. + * @attention 2. This timeout interval is not very precise, only as reference. + * + * @param struct espconn *espconn : the TCP connection structure + * @param uint32 interval : timeout interval, unit: second, maximum: 7200 seconds + * @param uint8 type_flag : 0, set for all connections; 1, set for a specific connection + * - If the type_flag set to be 0, please call this API after espconn_accept, before listened + * a TCP connection. + * - If the type_flag set to be 1, the first parameter *espconn is the specific connection. + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection according + * to structure espconn + */ sint8 espconn_regist_time(struct espconn *espconn, uint32 interval, uint8 type_flag); -/****************************************************************************** - * FunctionName : espconn_get_connection_info - * Description : used to specify the function that should be called when disconnect - * Parameters : espconn -- espconn to set the err callback - * discon_cb -- err callback function to call when err - * Returns : none -*******************************************************************************/ - +/** + * @brief Get the information about a TCP connection or UDP transmission. + * + * @param struct espconn *espconn : the network connection structure + * @param remot_info **pcon_info : connect to client info + * @param uint8 typeflags : 0, regular server; 1, ssl server + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding transmission according to + * structure espconn + */ sint8 espconn_get_connection_info(struct espconn *pespconn, remot_info **pcon_info, uint8 typeflags); /****************************************************************************** * FunctionName : espconn_get_packet_info * Description : get the packet info with host * Parameters : espconn -- the espconn used to disconnect the connection - * infoarg -- the packet info + * infoarg -- the packet info * Returns : the errur code *******************************************************************************/ sint8 espconn_get_packet_info(struct espconn *espconn, struct espconn_packet* infoarg); -/****************************************************************************** - * FunctionName : espconn_regist_sentcb - * Description : Used to specify the function that should be called when data - * has been successfully delivered to the remote host. - * Parameters : struct espconn *espconn -- espconn to set the sent callback - * espconn_sent_callback sent_cb -- sent callback function to - * call for this espconn when data is successfully sent - * Returns : none -*******************************************************************************/ - +/** + * @brief Register data sent callback which will be called back when data are successfully sent. + * + * @param struct espconn *espconn : the network connection structure + * @param espconn_sent_callback sent_cb : registered callback function which will be called if + * the data is successfully sent + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding transmission according + * to structure espconn + */ sint8 espconn_regist_sentcb(struct espconn *espconn, espconn_sent_callback sent_cb); -/****************************************************************************** - * FunctionName : espconn_regist_sentcb - * Description : Used to specify the function that should be called when data - * has been successfully delivered to the remote host. - * Parameters : espconn -- espconn to set the sent callback - * sent_cb -- sent callback function to call for this espconn - * when data is successfully sent - * Returns : none -*******************************************************************************/ - +/** + * @brief Register a callback which will be called when all sending TCP data is completely + * write into write-buffer or sent. + * + * Need to call espconn_set_opt to enable write-buffer first. + * + * @attention 1. write-buffer is used to keep TCP data that waiting to be sent, queue number + * of the write-buffer is 8 which means that it can keep 8 packets at most. + * The size of write-buffer is 2920 bytes. + * @attention 2. Users can enable it by using espconn_set_opt. + * @attention 3. Users can call espconn_send to send the next packet in write_finish_callback + * instead of using espconn_sent_callback. + * + * @param struct espconn *espconn : the network connection structure + * @param espconn_connect_callback write_finish_fn : registered callback function which will + * be called if the data is completely write + * into write buffer or sent. + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection according + * to structure espconn + */ sint8 espconn_regist_write_finish(struct espconn *espconn, espconn_connect_callback write_finish_fn); -/****************************************************************************** - * FunctionName : espconn_send - * Description : sent data for client or server - * Parameters : espconn -- espconn to set for client or server - * psent -- data to send - * length -- length of data to send - * Returns : none -*******************************************************************************/ - +/** + * @brief Send data through network. + * + * @attention 1. Please call espconn_send after espconn_sent_callback of the pre-packet. + * @attention 2. If it is a UDP transmission, it is suggested to set espconn->proto.udp->remote_ip + * and remote_port before every calling of espconn_send. + * + * @param struct espconn *espconn : the network connection structure + * @param uint8 *psent : pointer of data + * @param uint16 length : data length + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_MEM - Out of memory + * - ESPCONN_ARG - illegal argument, can't find the corresponding network transmission + * according to structure espconn + * - ESPCONN_MAXNUM - buffer of sending data is full + * - ESPCONN_IF - send UDP data fail + */ sint8 espconn_send(struct espconn *espconn, uint8 *psent, uint16 length); -/****************************************************************************** - * FunctionName : espconn_sent - * Description : sent data for client or server - * Parameters : espconn -- espconn to set for client or server - * psent -- data to send - * length -- length of data to send - * Returns : none -*******************************************************************************/ - +/** + * @brief Send data through network. + * + * This API is deprecated, please use espconn_send instead. + * + * @attention 1. Please call espconn_sent after espconn_sent_callback of the pre-packet. + * @attention 2. If it is a UDP transmission, it is suggested to set espconn->proto.udp->remote_ip + * and remote_port before every calling of espconn_sent. + * + * @param struct espconn *espconn : the network connection structure + * @param uint8 *psent : pointer of data + * @param uint16 length : data length + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_MEM - Out of memory + * - ESPCONN_ARG - illegal argument, can't find the corresponding network transmission + * according to structure espconn + * - ESPCONN_MAXNUM - buffer of sending data is full + * - ESPCONN_IF - send UDP data fail + */ sint8 espconn_sent(struct espconn *espconn, uint8 *psent, uint16 length); -/****************************************************************************** - * FunctionName : espconn_sendto - * Description : send data for UDP - * Parameters : espconn -- espconn to set for UDP - * psent -- data to send - * length -- length of data to send - * Returns : error -*******************************************************************************/ - +/** + * @brief Send UDP data. + * + * @param struct espconn *espconn : the UDP structure + * @param uint8 *psent : pointer of data + * @param uint16 length : data length + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_MEM - Out of memory + * - ESPCONN_MAXNUM - buffer of sending data is full + * - ESPCONN_IF - send UDP data fail + */ sint16 espconn_sendto(struct espconn *espconn, uint8 *psent, uint16 length); -/****************************************************************************** - * FunctionName : espconn_regist_connectcb - * Description : used to specify the function that should be called when - * connects to host. - * Parameters : espconn -- espconn to set the connect callback - * connect_cb -- connected callback function to call when connected - * Returns : none -*******************************************************************************/ - +/** + * @brief Register connection function which will be called back under successful TCP connection. + * + * @param struct espconn *espconn : the TCP connection structure + * @param espconn_connect_callback connect_cb : registered callback function + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection according + * to structure espconn + */ sint8 espconn_regist_connectcb(struct espconn *espconn, espconn_connect_callback connect_cb); -/****************************************************************************** - * FunctionName : espconn_regist_recvcb - * Description : used to specify the function that should be called when recv - * data from host. - * Parameters : espconn -- espconn to set the recv callback - * recv_cb -- recv callback function to call when recv data - * Returns : none -*******************************************************************************/ - +/** + * @brief register data receive function which will be called back when data are received. + * + * @param struct espconn *espconn : the network transmission structure + * @param espconn_recv_callback recv_cb : registered callback function + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection according + * to structure espconn + */ sint8 espconn_regist_recvcb(struct espconn *espconn, espconn_recv_callback recv_cb); -/****************************************************************************** - * FunctionName : espconn_regist_reconcb - * Description : used to specify the function that should be called when connection - * because of err disconnect. - * Parameters : espconn -- espconn to set the err callback - * recon_cb -- err callback function to call when err - * Returns : none -*******************************************************************************/ - +/** + * @brief Register reconnect callback. + * + * @attention espconn_reconnect_callback is more like a network-broken error handler; it handles + * errors that occurs in any phase of the connection. + * For instance, if espconn_send fails, espconn_reconnect_callback will be called + * because the network is broken. + * + * @param struct espconn *espconn : the TCP connection structure + * @param espconn_reconnect_callback recon_cb : registered callback function + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection according + * to structure espconn + */ sint8 espconn_regist_reconcb(struct espconn *espconn, espconn_reconnect_callback recon_cb); -/****************************************************************************** - * FunctionName : espconn_regist_disconcb - * Description : used to specify the function that should be called when disconnect - * Parameters : espconn -- espconn to set the err callback - * discon_cb -- err callback function to call when err - * Returns : none -*******************************************************************************/ - +/** + * @brief Register disconnection function which will be called back under successful TCP + * disconnection. + * + * @param struct espconn *espconn : the TCP connection structure + * @param espconn_connect_callback discon_cb : registered callback function + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection according + * to structure espconn + */ sint8 espconn_regist_disconcb(struct espconn *espconn, espconn_connect_callback discon_cb); -/****************************************************************************** - * FunctionName : espconn_port - * Description : access port value for client so that we don't end up bouncing - * all connections at the same time . - * Parameters : none - * Returns : access port value -*******************************************************************************/ - +/** + * @brief Get an available port for network. + * + * @param null + * + * @return Port number. + */ uint32 espconn_port(void); -/****************************************************************************** - * FunctionName : espconn_set_opt - * Description : access port value for client so that we don't end up bouncing - * all connections at the same time . - * Parameters : none - * Returns : access port value -*******************************************************************************/ - +/** + * @brief Set option of TCP connection. + * + * @attention In general, we need not call this API. If call espconn_set_opt, please call + * it in espconn_connect_callback. + * + * @param struct espconn *espconn : the TCP connection structure + * @param uint8 opt : option of TCP connection, refer to enum espconn_option + * - bit 0: 1: free memory after TCP disconnection happen need not wait 2 minutes; + * - bit 1: 1: disable nagle algorithm during TCP data transmission, quiken the data transmission. + * - bit 2: 1: enable espconn_regist_write_finish, enter write finish callback means + * the data espconn_send sending was written into 2920 bytes write-buffer + * waiting for sending or already sent. + * - bit 3: 1: enable TCP keep alive + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection according + * to structure espconn + */ sint8 espconn_set_opt(struct espconn *espconn, uint8 opt); -/****************************************************************************** - * FunctionName : espconn_clear_opt - * Description : clear the option for connections so that we don't end up bouncing - * all connections at the same time . - * Parameters : espconn -- the espconn used to set the connection - * opt -- the option for clear - * Returns : the result -*******************************************************************************/ - +/** + * @brief Clear option of TCP connection. + * + * @param struct espconn *espconn : the TCP connection structure + * @param uint8 opt : enum espconn_option + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection according + * to structure espconn + */ sint8 espconn_clear_opt(struct espconn *espconn, uint8 opt); -/****************************************************************************** - * FunctionName : espconn_set_keepalive - * Description : access level value for connection so that we set the value for - * keep alive - * Parameters : espconn -- the espconn used to set the connection - * level -- the connection's level - * value -- the value of time(s) - * Returns : access port value -*******************************************************************************/ - -sint8 espconn_set_keepalive(struct espconn *espconn, uint8 level, void* optarg); - -/****************************************************************************** - * FunctionName : espconn_get_keepalive - * Description : access level value for connection so that we get the value for - * keep alive - * Parameters : espconn -- the espconn used to get the connection - * level -- the connection's level - * Returns : access keep alive value -*******************************************************************************/ - +/** + * @brief Set configuration of TCP keep alive. + * + * @attention In general, we need not call this API. If needed, please call it in + * espconn_connect_callback and call espconn_set_opt to enable keep alive first. + * + * @param struct espconn *espconn : the TCP connection structure + * @param uint8 level : To do TCP keep-alive detection every ESPCONN_KEEPIDLE. If there + * is no response, retry ESPCONN_KEEPCNT times every ESPCONN_KEEPINTVL. + * If still no response, considers it as TCP connection broke, goes + * into espconn_reconnect_callback. Notice, keep alive interval is not + * precise, only for reference, it depends on priority. + * @param void* optarg : value of parameter + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection according + * to structure espconn + */ +sint8 espconn_set_keepalive(struct espconn *espconn, uint8 level, void *optarg); + +/** + * @brief Get configuration of TCP keep alive. + * + * @param struct espconn *espconn : the TCP connection structure + * @param uint8 level : enum espconn_level + * @param void* optarg : value of parameter + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection according + * to structure espconn + */ sint8 espconn_get_keepalive(struct espconn *espconn, uint8 level, void *optarg); -/****************************************************************************** - * TypedefName : dns_found_callback - * Description : Callback which is invoked when a hostname is found. - * Parameters : name -- pointer to the name that was looked up. - * ipaddr -- pointer to an ip_addr_t containing the IP address of - * the hostname, or NULL if the name could not be found (or on any - * other error). - * callback_arg -- a user-specified callback argument passed to - * dns_gethostbyname -*******************************************************************************/ - +/** + * @brief Callback which is invoked when a hostname is found. + * + * @param const char *name : hostname + * @param ip_addr_t *ipaddr : IP address of the hostname, or to be NULL if the name could + * not be found (or on any other error). + * @param void *callback_arg : callback argument. + * + * @return null + */ typedef void (*dns_found_callback)(const char *name, ip_addr_t *ipaddr, void *callback_arg); -/****************************************************************************** - * FunctionName : espconn_gethostbyname - * Description : Resolve a hostname (string) into an IP address. - * Parameters : pespconn -- espconn to resolve a hostname - * hostname -- the hostname that is to be queried - * addr -- pointer to a ip_addr_t where to store the address if - * it is already cached in the dns_table (only valid if ESPCONN_OK - * is returned!) - * found -- a callback function to be called on success, failure - * or timeout (only if ERR_INPROGRESS is returned!) - * Returns : err_t return code - * - ESPCONN_OK if hostname is a valid IP address string or the host - * name is already in the local names table. - * - ESPCONN_INPROGRESS enqueue a request to be sent to the DNS server - * for resolution if no errors are present. - * - ESPCONN_ARG: dns client not initialized or invalid hostname -*******************************************************************************/ - +/** + * @brief DNS function. + * + * Parse a hostname (string) to an IP address. + * + * @param struct espconn *pespconn : espconn to parse a hostname. + * @param const char *hostname : the hostname. + * @param ip_addr_t *addr : IP address. + * @param dns_found_callback found : callback of DNS + * + * @return err_t : + * - ESPCONN_OK - succeed + * - ESPCONN_INPROGRESS - error code : already connected + * - ESPCONN_ARG - error code : illegal argument, can't find network transmission + * according to structure espconn + */ err_t espconn_gethostbyname(struct espconn *pespconn, const char *hostname, ip_addr_t *addr, dns_found_callback found); /****************************************************************************** @@ -466,7 +639,7 @@ sint8 espconn_secure_disconnect(struct espconn *espconn); * FunctionName : espconn_secure_send * Description : sent data for client or server * Parameters : espconn -- espconn to set for client or server - * psent -- data to send + * psent -- data to send * length -- length of data to send * Returns : none *******************************************************************************/ @@ -477,7 +650,7 @@ sint8 espconn_secure_send(struct espconn *espconn, uint8 *psent, uint16 length); * FunctionName : espconn_encry_sent * Description : sent data for client or server * Parameters : espconn -- espconn to set for client or server - * psent -- data to send + * psent -- data to send * length -- length of data to send * Returns : none *******************************************************************************/ @@ -488,8 +661,8 @@ sint8 espconn_secure_sent(struct espconn *espconn, uint8 *psent, uint16 length); * FunctionName : espconn_secure_set_size * Description : set the buffer size for client or server * Parameters : level -- set for client or server - * 1: client,2:server,3:client and server - * size -- buffer size + * 1: client,2:server,3:client and server + * size -- buffer size * Returns : true or false *******************************************************************************/ @@ -499,7 +672,7 @@ bool espconn_secure_set_size(uint8 level, uint16 size); * FunctionName : espconn_secure_get_size * Description : get buffer size for client or server * Parameters : level -- set for client or server - * 1: client,2:server,3:client and server + * 1: client,2:server,3:client and server * Returns : buffer size for client or server *******************************************************************************/ @@ -508,20 +681,20 @@ sint16 espconn_secure_get_size(uint8 level); /****************************************************************************** * FunctionName : espconn_secure_ca_enable * Description : enable the certificate authenticate and set the flash sector - * as client or server + * as client or server * Parameters : level -- set for client or server - * 1: client,2:server,3:client and server - * flash_sector -- flash sector for save certificate + * 1: client,2:server,3:client and server + * flash_sector -- flash sector for save certificate * Returns : result true or false *******************************************************************************/ -bool espconn_secure_ca_enable(uint8 level, uint8 flash_sector ); +bool espconn_secure_ca_enable(uint8 level, uint8 flash_sector); /****************************************************************************** * FunctionName : espconn_secure_ca_disable * Description : disable the certificate authenticate as client or server * Parameters : level -- set for client or server - * 1: client,2:server,3:client and server + * 1: client,2:server,3:client and server * Returns : result true or false *******************************************************************************/ @@ -531,20 +704,20 @@ bool espconn_secure_ca_disable(uint8 level); /****************************************************************************** * FunctionName : espconn_secure_cert_req_enable * Description : enable the client certificate authenticate and set the flash sector - * as client or server + * as client or server * Parameters : level -- set for client or server - * 1: client,2:server,3:client and server - * flash_sector -- flash sector for save certificate + * 1: client,2:server,3:client and server + * flash_sector -- flash sector for save certificate * Returns : result true or false *******************************************************************************/ -bool espconn_secure_cert_req_enable(uint8 level, uint8 flash_sector ); +bool espconn_secure_cert_req_enable(uint8 level, uint8 flash_sector); /****************************************************************************** * FunctionName : espconn_secure_ca_disable * Description : disable the client certificate authenticate as client or server * Parameters : level -- set for client or server - * 1: client,2:server,3:client and server + * 1: client,2:server,3:client and server * Returns : result true or false *******************************************************************************/ @@ -553,9 +726,9 @@ bool espconn_secure_cert_req_disable(uint8 level); /****************************************************************************** * FunctionName : espconn_secure_set_default_certificate * Description : Load the certificates in memory depending on compile-time - * and user options. + * and user options. * Parameters : certificate -- Load the certificate - * length -- Load the certificate length + * length -- Load the certificate length * Returns : result true or false *******************************************************************************/ @@ -564,9 +737,9 @@ bool espconn_secure_set_default_certificate(const uint8* certificate, uint16 len /****************************************************************************** * FunctionName : espconn_secure_set_default_private_key * Description : Load the key in memory depending on compile-time - * and user options. + * and user options. * Parameters : private_key -- Load the key - * length -- Load the key length + * length -- Load the key length * Returns : result true or false *******************************************************************************/ @@ -590,57 +763,80 @@ sint8 espconn_secure_accept(struct espconn *espconn); sint8 espconn_secure_delete(struct espconn *espconn); -/****************************************************************************** - * FunctionName : espconn_igmp_join - * Description : join a multicast group - * Parameters : host_ip -- the ip address of udp server - * multicast_ip -- multicast ip given by user - * Returns : none -*******************************************************************************/ +/** + * @brief Join a multicast group. + * + * @attention This API can only be called after the ESP8266 station connects to a router. + * + * @param ip_addr_t *host_ip : IP of UDP host + * @param ip_addr_t *multicast_ip : IP of multicast group + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_MEM - Out of memory + */ sint8 espconn_igmp_join(ip_addr_t *host_ip, ip_addr_t *multicast_ip); -/****************************************************************************** - * FunctionName : espconn_igmp_leave - * Description : leave a multicast group - * Parameters : host_ip -- the ip address of udp server - * multicast_ip -- multicast ip given by user - * Returns : none -*******************************************************************************/ +/** + * @brief Leave a multicast group. + * + * @attention This API can only be called after the ESP8266 station connects to a router. + * + * @param ip_addr_t *host_ip : IP of UDP host + * @param ip_addr_t *multicast_ip : IP of multicast group + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_MEM - Out of memory + */ sint8 espconn_igmp_leave(ip_addr_t *host_ip, ip_addr_t *multicast_ip); -/****************************************************************************** - * FunctionName : espconn_recv_hold - * Description : hold tcp receive - * Parameters : espconn -- espconn to hold - * Returns : none -*******************************************************************************/ +/** + * @brief Puts in a request to block the TCP receive function. + * + * @attention The function does not act immediately; we recommend calling it while + * reserving 5*1460 bytes of memory. This API can be called more than once. + * + * @param struct espconn *espconn : corresponding TCP connection structure + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection + * according to structure espconn. + */ sint8 espconn_recv_hold(struct espconn *pespconn); -/****************************************************************************** - * FunctionName : espconn_recv_unhold - * Description : unhold tcp receive - * Parameters : espconn -- espconn to unhold - * Returns : none -*******************************************************************************/ +/** + * @brief Unblock TCP receiving data (i.e. undo espconn_recv_hold). + * + * @attention This API takes effect immediately. + * + * @param struct espconn *espconn : corresponding TCP connection structure + * + * @return 0 : succeed + * @return Non-0 : error code + * - ESPCONN_ARG - illegal argument, can't find the corresponding TCP connection + * according to structure espconn. + */ sint8 espconn_recv_unhold(struct espconn *pespconn); /****************************************************************************** * FunctionName : espconn_mdns_init * Description : register a device with mdns * Parameters : ipAddr -- the ip address of device - * hostname -- the hostname of device + * hostname -- the hostname of device * Returns : none *******************************************************************************/ - void espconn_mdns_init(struct mdns_info *info); + /****************************************************************************** * FunctionName : espconn_mdns_close * Description : close a device with mdns * Parameters : a * Returns : none *******************************************************************************/ - void espconn_mdns_close(void); + /****************************************************************************** * FunctionName : espconn_mdns_server_register * Description : register a device with mdns @@ -662,9 +858,9 @@ void espconn_mdns_server_unregister(void); * Description : get server name of device with mdns * Parameters : a * Returns : none -*******************************************************************************/ - +******************************************************************************/ char* espconn_mdns_get_servername(void); + /****************************************************************************** * FunctionName : espconn_mdns_set_servername * Description : set server name of device with mdns @@ -704,14 +900,18 @@ void espconn_mdns_disable(void); * Returns : none *******************************************************************************/ void espconn_mdns_enable(void); -/****************************************************************************** - * FunctionName : espconn_dns_setserver - * Description : Initialize one of the DNS servers. - * Parameters : numdns -- the index of the DNS server to set must - * be < DNS_MAX_SERVERS = 2 - * dnsserver -- IP address of the DNS server to set - * Returns : none -*******************************************************************************/ + +/** + * @brief Set default DNS server. Two DNS server is allowed to be set. + * + * @attention Only if ESP8266 DHCP client is disabled (wifi_station_dhcpc_stop), + * this API can be used. + * + * @param char numdns : DNS server ID, 0 or 1 + * @param ip_addr_t *dnsserver : DNS server IP + * + * @return null + */ void espconn_dns_setserver(char numdns, ip_addr_t *dnsserver); #endif diff --git a/esp_iot_sdk_v1.5.2/include/user_interface.h b/esp_iot_sdk_v1.5.2/include/user_interface.h index 99bb01c..a4f3425 100644 --- a/esp_iot_sdk_v1.5.2/include/user_interface.h +++ b/esp_iot_sdk_v1.5.2/include/user_interface.h @@ -23,17 +23,17 @@ #endif enum rst_reason { - REASON_DEFAULT_RST = 0, - REASON_WDT_RST = 1, - REASON_EXCEPTION_RST = 2, - REASON_SOFT_WDT_RST = 3, - REASON_SOFT_RESTART = 4, - REASON_DEEP_SLEEP_AWAKE = 5, - REASON_EXT_SYS_RST = 6 + REASON_DEFAULT_RST = 0, /**< normal startup by power on */ + REASON_WDT_RST, /**< hardware watch dog reset */ + REASON_EXCEPTION_RST, /**< exception reset, GPIO status won't change */ + REASON_SOFT_WDT_RST, /**< software watch dog reset, GPIO status won't change */ + REASON_SOFT_RESTART, /**< software restart ,system_restart , GPIO status won't change */ + REASON_DEEP_SLEEP_AWAKE, /**< wake up from deep-sleep */ + REASON_EXT_SYS_RST /**< external system reset */ }; struct rst_info{ - uint32 reason; + uint32 reason; /**< enum rst_reason */ uint32 exccause; uint32 epc1; uint32 epc2; @@ -42,15 +42,78 @@ struct rst_info{ uint32 depc; }; +/** + * @brief Get the reason of restart. + * + * @param null + * + * @return struct rst_info* : information of the system restart + */ struct rst_info* system_get_rst_info(void); #define UPGRADE_FW_BIN1 0x00 #define UPGRADE_FW_BIN2 0x01 +/** + * @brief Reset to default settings. + * + * Reset to default settings of the following APIs : wifi_station_set_auto_connect, + * wifi_set_phy_mode, wifi_softap_set_config related, wifi_station_set_config + * related, and wifi_set_opmode. + * + * @param null + * + * @return null + */ void system_restore(void); + +/** + * @brief Restart system. + * + * @param null + * + * @return null + */ void system_restart(void); +/** + * @brief Call this API before system_deep_sleep to set the activity after the + * next deep-sleep wakeup. + * + * If this API is not called, default to be system_deep_sleep_set_option(1). + * + * @param uint8 option : + * @param 0 : Radio calibration after the deep-sleep wakeup is decided by byte + * 108 of esp_init_data_default.bin (0~127byte). + * @param 1 : Radio calibration will be done after the deep-sleep wakeup. This + * will lead to stronger current. + * @param 2 : Radio calibration will not be done after the deep-sleep wakeup. + * This will lead to weaker current. + * @param 4 : Disable radio calibration after the deep-sleep wakeup (the same + * as modem-sleep). This will lead to the weakest current, but the device + * can't receive or transmit data after waking up. + * + * @return true : succeed + * @return false : fail + */ bool system_deep_sleep_set_option(uint8 option); + +/** + * @brief Set the chip to deep-sleep mode. + * + * The device will automatically wake up after the deep-sleep time set + * by the users. Upon waking up, the device boots up from user_init. + * + * @attention 1. XPD_DCDC should be connected to EXT_RSTB through 0 ohm resistor + * in order to support deep-sleep wakeup. + * @attention 2. system_deep_sleep(0): there is no wake up timer; in order to wake + * up, connect a GPIO to pin RST, the chip will wake up by a falling-edge + * on pin RST + * + * @param uint32 time_in_us : deep-sleep time, unit: microsecond + * + * @return null + */ void system_deep_sleep(uint32 time_in_us); uint8 system_upgrade_userbin_check(void); @@ -59,20 +122,43 @@ uint8 system_upgrade_flag_check(); void system_upgrade_flag_set(uint8 flag); void system_timer_reinit(void); + +/** + * @brief Get system time, unit: microsecond. + * + * @param null + * + * @return System time, unit: microsecond. + */ uint32 system_get_time(void); /* user task's prio must be 0/1/2 !!!*/ enum { - USER_TASK_PRIO_0 = 0, - USER_TASK_PRIO_1, - USER_TASK_PRIO_2, - USER_TASK_PRIO_MAX + USER_TASK_PRIO_0 = 0, + USER_TASK_PRIO_1, + USER_TASK_PRIO_2, + USER_TASK_PRIO_MAX }; bool system_os_task(os_task_t task, uint8 prio, os_event_t *queue, uint8 qlen); bool system_os_post(uint8 prio, os_signal_t sig, os_param_t par); +/** + * @brief Print the system memory distribution, including data/rodata/bss/heap. + * + * @param null + * + * @return null + */ void system_print_meminfo(void); + +/** + * @brief Get the size of available heap. + * + * @param null + * + * @return Available heap size. + */ uint32 system_get_free_heap_size(void); void system_set_os_print(uint8 onoff); @@ -86,18 +172,149 @@ typedef void (* init_done_cb_t)(void); void system_init_done_cb(init_done_cb_t cb); +/** + * @brief Get the RTC clock cycle. + * + * @attention 1. The RTC clock cycle has decimal part. + * @attention 2. The RTC clock cycle will change according to the temperature, + * so RTC timer is not very precise. + * + * @param null + * + * @return RTC clock period (unit: microsecond), bit11~ bit0 are decimal. + */ uint32 system_rtc_clock_cali_proc(void); + +/** + * @brief Get RTC time, unit: RTC clock cycle. + * + * Example: + * If system_get_rtc_time returns 10 (it means 10 RTC cycles), and + * system_rtc_clock_cali_proc returns 5.75 (it means 5.75 microseconds per RTC clock cycle), + * (then the actual time is 10 x 5.75 = 57.5 microseconds. + * + * @attention System time will return to zero because of system_restart, but the + * RTC time still goes on. If the chip is reset by pin EXT_RST or pin + * CHIP_EN (including the deep-sleep wakeup), situations are shown as below: + * @attention 1. reset by pin EXT_RST : RTC memory won't change, RTC timer returns to zero + * @attention 2. watchdog reset : RTC memory won't change, RTC timer won't change + * @attention 3. system_restart : RTC memory won't change, RTC timer won't change + * @attention 4. power on : RTC memory is random value, RTC timer starts from zero + * @attention 5. reset by pin CHIP_EN : RTC memory is random value, RTC timer starts from zero + * + * @param null + * + * @return RTC time. + */ uint32 system_get_rtc_time(void); +/** + * @brief Read user data from the RTC memory. + * + * The user data segment (512 bytes, as shown below) is used to store user data. + * + * |<---- system data(256 bytes) ---->|<----------- user data(512 bytes) --------->| + * + * @attention Read and write unit for data stored in the RTC memory is 4 bytes. + * @attention src_addr is the block number (4 bytes per block). So when reading data + * at the beginning of the user data segment, src_addr will be 256/4 = 64, + * n will be data length. + * + * @param uint8 src : source address of rtc memory, src_addr >= 64 + * @param void *dst : data pointer + * @param uint16 n : data length, unit: byte + * + * @return true : succeed + * @return false : fail + */ bool system_rtc_mem_read(uint8 src_addr, void *des_addr, uint16 load_size); + +/** + * @brief Write user data to the RTC memory. + * + * During deep-sleep, only RTC is working. So users can store their data + * in RTC memory if it is needed. The user data segment below (512 bytes) + * is used to store the user data. + * + * |<---- system data(256 bytes) ---->|<----------- user data(512 bytes) --------->| + * + * @attention Read and write unit for data stored in the RTC memory is 4 bytes. + * @attention src_addr is the block number (4 bytes per block). So when storing data + * at the beginning of the user data segment, src_addr will be 256/4 = 64, + * n will be data length. + * + * @param uint8 src : source address of rtc memory, src_addr >= 64 + * @param void *dst : data pointer + * @param uint16 n : data length, unit: byte + * + * @return true : succeed + * @return false : fail + */ bool system_rtc_mem_write(uint8 des_addr, const void *src_addr, uint16 save_size); +/** + * @brief UART0 swap. + * + * Use MTCK as UART0 RX, MTDO as UART0 TX, so ROM log will not output from + * this new UART0. We also need to use MTDO (U0CTS) and MTCK (U0RTS) as UART0 in hardware. + * + * @param null + * + * @return null + */ void system_uart_swap(void); + +/** + * @brief Disable UART0 swap. + * + * Use the original UART0, not MTCK and MTDO. + * + * @param null + * + * @return null + */ void system_uart_de_swap(void); +/** + * @brief Measure the input voltage of TOUT pin 6, unit : 1/1024 V. + * + * @attention 1. system_adc_read can only be called when the TOUT pin is connected + * to the external circuitry, and the TOUT pin input voltage should + * be limited to 0~1.0V. + * @attention 2. When the TOUT pin is connected to the external circuitry, the 107th + * byte (vdd33_const) of esp_init_data_default.bin(0~127byte) should be + * set as the real power voltage of VDD3P3 pin 3 and 4. + * @attention 3. The unit of vdd33_const is 0.1V, the effective value range is [18, 36]; + * if vdd33_const is in [0, 18) or (36, 255), 3.3V is used to optimize RF by default. + * + * @param null + * + * @return Input voltage of TOUT pin 6, unit : 1/1024 V + */ uint16 system_adc_read(void); + +/** + * @brief Measure the power voltage of VDD3P3 pin 3 and 4, unit : 1/1024 V. + * + * @attention 1. system_get_vdd33 can only be called when TOUT pin is suspended. + * @attention 2. The 107th byte in esp_init_data_default.bin (0~127byte) is named + * as "vdd33_const", when TOUT pin is suspended vdd33_const must be + * set as 0xFF, that is 255. + * + * @param null + * + * @return Power voltage of VDD33, unit : 1/1024 V + */ uint16 system_get_vdd33(void); + +/** + * @brief Get information of the SDK version. + * + * @param null + * + * @return Information of the SDK version. + */ const char *system_get_sdk_version(void); #define SYS_BOOT_ENHANCE_MODE 0 @@ -106,145 +323,596 @@ const char *system_get_sdk_version(void); #define SYS_BOOT_NORMAL_BIN 0 #define SYS_BOOT_TEST_BIN 1 +/** + * @brief Get information of the boot version. + * + * @attention If boot version >= 1.3 , users can enable the enhanced boot mode + * (refer to system_restart_enhance). + * + * @param null + * + * @return Information of the boot version. + */ uint8 system_get_boot_version(void); + +/** + * @brief Get the address of the current running user bin (user1.bin or user2.bin). + * + * @param null + * + * @return The address of the current running user bin. + */ uint32 system_get_userbin_addr(void); + +/** + * @brief Get the boot mode. + * + * @param null + * + * @return #define SYS_BOOT_ENHANCE_MODE 0 + * @return #define SYS_BOOT_NORMAL_MODE 1 + */ uint8 system_get_boot_mode(void); + +/** + * @brief Restarts the system, and enters the enhanced boot mode. + * + * @attention SYS_BOOT_TEST_BIN is used for factory test during production; users + * can apply for the test bin from Espressif Systems. + * + * @param uint8 bin_type : type of bin + * - #define SYS_BOOT_NORMAL_BIN 0 // user1.bin or user2.bin + * - #define SYS_BOOT_TEST_BIN 1 // can only be Espressif test bin + * @param uint32 bin_addr : starting address of the bin file + * + * @return true : succeed + * @return false : fail + */ bool system_restart_enhance(uint8 bin_type, uint32 bin_addr); #define SYS_CPU_80MHZ 80 #define SYS_CPU_160MHZ 160 +/** + * @brief Set CPU frequency. Default is 80MHz. + * + * System bus frequency is 80MHz, will not be affected by CPU frequency. + * The frequency of UART, SPI, or other peripheral devices, are divided + * from system bus frequency, so they will not be affected by CPU frequency either. + * + * @param uint8 freq : CPU frequency, 80 or 160. + * + * @return true : succeed + * @return false : fail + */ bool system_update_cpu_freq(uint8 freq); -uint8 system_get_cpu_freq(void); -enum flash_size_map { - FLASH_SIZE_4M_MAP_256_256 = 0, - FLASH_SIZE_2M, - FLASH_SIZE_8M_MAP_512_512, - FLASH_SIZE_16M_MAP_512_512, - FLASH_SIZE_32M_MAP_512_512, - FLASH_SIZE_16M_MAP_1024_1024, - FLASH_SIZE_32M_MAP_1024_1024 -}; +/** + * @brief Get CPU frequency. + * + * @param null + * + * @return CPU frequency, unit : MHz. + */ +uint8 system_get_cpu_freq(void); -enum flash_size_map system_get_flash_size_map(void); +typedef enum { + FLASH_SIZE_4M_MAP_256_256 = 0, /**< Flash size : 4Mbits. Map : 256KBytes + 256KBytes */ + FLASH_SIZE_2M, /**< Flash size : 2Mbits. Map : 256KBytes */ + FLASH_SIZE_8M_MAP_512_512, /**< Flash size : 8Mbits. Map : 512KBytes + 512KBytes */ + FLASH_SIZE_16M_MAP_512_512, /**< Flash size : 16Mbits. Map : 512KBytes + 512KBytes */ + FLASH_SIZE_32M_MAP_512_512, /**< Flash size : 32Mbits. Map : 512KBytes + 512KBytes */ + FLASH_SIZE_16M_MAP_1024_1024, /**< Flash size : 16Mbits. Map : 1024KBytes + 1024KBytes */ + FLASH_SIZE_32M_MAP_1024_1024 /**< Flash size : 32Mbits. Map : 1024KBytes + 1024KBytes */ +} flash_size_map; + +/** + * @brief Get the current Flash size and Flash map. + * + * Flash map depends on the selection when compiling, more details in document + * "2A-ESP8266__IOT_SDK_User_Manual" + * + * @param null + * + * @return enum flash_size_map + */ +flash_size_map system_get_flash_size_map(void); + +/** + * @brief Set the maximum value of RF TX Power, unit : 0.25dBm. + * + * @param uint8 max_tpw : the maximum value of RF Tx Power, unit : 0.25dBm, range [0, 82]. + * It can be set refer to the 34th byte (target_power_qdb_0) + * of esp_init_data_default.bin(0~127byte) + * + * @return null + */ void system_phy_set_max_tpw(uint8 max_tpw); + +/** + * @brief Adjust the RF TX Power according to VDD33, unit : 1/1024 V. + * + * @attention 1. When TOUT pin is suspended, VDD33 can be measured by system_get_vdd33. + * @attention 2. When TOUT pin is connected to the external circuitry, system_get_vdd33 + * can not be used to measure VDD33. + * + * @param uint16 vdd33 : VDD33, unit : 1/1024V, range [1900, 3300] + * + * @return null + */ void system_phy_set_tpw_via_vdd33(uint16 vdd33); + +/** + * @brief Enable RF or not when wakeup from deep-sleep. + * + * @attention 1. This API can only be called in user_rf_pre_init. + * @attention 2. Function of this API is similar to system_deep_sleep_set_option, + * if they are both called, it will disregard system_deep_sleep_set_option + * which is called before deep-sleep, and refer to system_phy_set_rfoption + * which is called when deep-sleep wake up. + * @attention 3. Before calling this API, system_deep_sleep_set_option should be called + * once at least. + * + * @param uint8 option : + * - 0 : Radio calibration after deep-sleep wake up depends on esp_init_data_default.bin (0~127byte) byte 108. + * - 1 : Radio calibration is done after deep-sleep wake up; this increases the + * current consumption. + * - 2 : No radio calibration after deep-sleep wake up; this reduces the current consumption. + * - 4 : Disable RF after deep-sleep wake up, just like modem sleep; this has the + * least current consumption; the device is not able to transmit or receive + * data after wake up. + * + * @return null + */ void system_phy_set_rfoption(uint8 option); + void system_phy_set_powerup_option(uint8 option); + +/** + * @brief Write data into flash with protection. + * + * Flash read/write has to be 4-bytes aligned. + * + * Protection of flash read/write : + * use 3 sectors (4KBytes per sector) to save 4KB data with protect, + * sector 0 and sector 1 are data sectors, back up each other, + * save data alternately, sector 2 is flag sector, point out which sector + * is keeping the latest data, sector 0 or sector 1. + * + * @param uint16 start_sec : start sector (sector 0) of the 3 sectors which are + * used for flash read/write protection. + * - For example, in IOT_Demo we can use the 3 sectors (3 * 4KB) starting from flash + * 0x3D000 for flash read/write protection, so the parameter start_sec should be 0x3D + * @param void *param : pointer of the data to be written + * @param uint16 len : data length, should be less than a sector, which is 4 * 1024 + * + * @return true : succeed + * @return false : fail + */ bool system_param_save_with_protect(uint16 start_sec, void *param, uint16 len); + + +/** + * @brief Read the data saved into flash with the read/write protection. + * + * Flash read/write has to be 4-bytes aligned. + * + * Read/write protection of flash: + * use 3 sectors (4KB per sector) to save 4KB data with protect, sector + * 0 and sector 1 are data sectors, back up each other, save data alternately, + * sector 2 is flag sector, point out which sector is keeping the latest data, + * sector 0 or sector 1. + * + * @param uint16 start_sec : start sector (sector 0) of the 3 sectors used for + * flash read/write protection. It cannot be sector 1 or sector 2. + * - For example, in IOT_Demo, the 3 sectors (3 * 4KB) starting from flash 0x3D000 + * can be used for flash read/write protection. + * The parameter start_sec is 0x3D, and it cannot be 0x3E or 0x3F. + * @param uint16 offset : offset of data saved in sector + * @param void *param : data pointer + * @param uint16 len : data length, offset + len =< 4 * 1024 + * + * @return true : succeed + * @return false : fail + */ bool system_param_load(uint16 start_sec, uint16 offset, void *param, uint16 len); + void system_soft_wdt_stop(void); void system_soft_wdt_restart(void); void system_soft_wdt_feed(void); void system_show_malloc(void); -#define NULL_MODE 0x00 -#define STATION_MODE 0x01 -#define SOFTAP_MODE 0x02 -#define STATIONAP_MODE 0x03 - -typedef enum _auth_mode { - AUTH_OPEN = 0, - AUTH_WEP, - AUTH_WPA_PSK, - AUTH_WPA2_PSK, - AUTH_WPA_WPA2_PSK, - AUTH_MAX +typedef enum { + NULL_MODE = 0, /**< null mode */ + STATION_MODE, /**< WiFi station mode */ + SOFTAP_MODE, /**< WiFi soft-AP mode */ + STATIONAP_MODE, /**< WiFi station + soft-AP mode */ + MAX_MODE +} WIFI_MODE; + +typedef enum { + AUTH_OPEN = 0, /**< authenticate mode : open */ + AUTH_WEP, /**< authenticate mode : WEP */ + AUTH_WPA_PSK, /**< authenticate mode : WPA_PSK */ + AUTH_WPA2_PSK, /**< authenticate mode : WPA2_PSK */ + AUTH_WPA_WPA2_PSK, /**< authenticate mode : WPA_WPA2_PSK */ + AUTH_MAX } AUTH_MODE; -uint8 wifi_get_opmode(void); -uint8 wifi_get_opmode_default(void); -bool wifi_set_opmode(uint8 opmode); -bool wifi_set_opmode_current(uint8 opmode); +/** + * @brief Get the current operating mode of the WiFi. + * + * @param null + * + * @return WiFi operating modes: + * - 0x01: station mode; + * - 0x02: soft-AP mode + * - 0x03: station+soft-AP mode + */ +WIFI_MODE wifi_get_opmode(void); + +/** + * @brief Get the operating mode of the WiFi saved in the Flash. + * + * @param null + * + * @return WiFi operating modes: + * - 0x01: station mode; + * - 0x02: soft-AP mode + * - 0x03: station+soft-AP mode + */ +WIFI_MODE wifi_get_opmode_default(void); + +/** + * @brief Set the WiFi operating mode, and save it to Flash. + * + * Set the WiFi operating mode as station, soft-AP or station+soft-AP, + * and save it to Flash. The default mode is soft-AP mode. + * + * @attention This configuration will be saved in the Flash system parameter area if changed. + * + * @param uint8 opmode : WiFi operating modes: + * - 0x01: station mode; + * - 0x02: soft-AP mode + * - 0x03: station+soft-AP mode + * + * @return true : succeed + * @return false : fail + */ +bool wifi_set_opmode(WIFI_MODE opmode); + +/** + * @brief Set the WiFi operating mode, and will not save it to Flash. + * + * Set the WiFi operating mode as station, soft-AP or station+soft-AP, and + * the mode won't be saved to the Flash. + * + * @param uint8 opmode : WiFi operating modes: + * - 0x01: station mode; + * - 0x02: soft-AP mode + * - 0x03: station+soft-AP mode + * + * @return true : succeed + * @return false : fail + */ +bool wifi_set_opmode_current(WIFI_MODE opmode); + uint8 wifi_get_broadcast_if(void); bool wifi_set_broadcast_if(uint8 interface); struct bss_info { - STAILQ_ENTRY(bss_info) next; - - uint8 bssid[6]; - uint8 ssid[32]; - uint8 ssid_len; - uint8 channel; - sint8 rssi; - AUTH_MODE authmode; - uint8 is_hidden; - sint16 freq_offset; - sint16 freqcal_val; + STAILQ_ENTRY(bss_info) next; + + uint8 bssid[6]; + uint8 ssid[32]; + uint8 ssid_len; + uint8 channel; + sint8 rssi; + AUTH_MODE authmode; + uint8 is_hidden; + sint16 freq_offset; + sint16 freqcal_val; uint8 *esp_mesh_ie; }; typedef struct _scaninfo { - STAILQ_HEAD(, bss_info) *pbss; - struct espconn *pespconn; - uint8 totalpage; - uint8 pagenum; - uint8 page_sn; - uint8 data_cnt; + STAILQ_HEAD(, bss_info) *pbss; + struct espconn *pespconn; + uint8 totalpage; + uint8 pagenum; + uint8 page_sn; + uint8 data_cnt; } scaninfo; +/** + * @brief Callback function for wifi_station_scan. + * + * @param void *arg : information of APs that are found; save them as linked list; + * refer to struct bss_info + * @param STATUS status : status of scanning + * + * @return null + */ typedef void (* scan_done_cb_t)(void *arg, STATUS status); struct station_config { - uint8 ssid[32]; - uint8 password[64]; - uint8 bssid_set; // Note: If bssid_set is 1, station will just connect to the router - // with both ssid[] and bssid[] matched. Please check about this. - uint8 bssid[6]; + uint8 ssid[32]; + uint8 password[64]; + uint8 bssid_set; // Note: If bssid_set is 1, station will just connect to the router + // with both ssid[] and bssid[] matched. Please check about this. + uint8 bssid[6]; }; +/** + * @brief Get the current configuration of the ESP8266 WiFi station. + * + * @param struct station_config *config : ESP8266 station configuration + * + * @return true : succeed + * @return false : fail + */ bool wifi_station_get_config(struct station_config *config); + +/** + * @brief Get the configuration parameters saved in the Flash of the ESP8266 WiFi station. + * + * @param struct station_config *config : ESP8266 station configuration + * + * @return true : succeed + * @return false : fail + */ bool wifi_station_get_config_default(struct station_config *config); + +/** + * @brief Set the configuration of the ESP8266 station and save it to the Flash. + * + * @attention 1. This API can be called only when the ESP8266 station is enabled. + * @attention 2. If wifi_station_set_config is called in user_init , there is no + * need to call wifi_station_connect. + * The ESP8266 station will automatically connect to the AP (router) + * after the system initialization. Otherwise, wifi_station_connect should be called. + * @attention 3. Generally, station_config.bssid_set needs to be 0; and it needs + * to be 1 only when users need to check the MAC address of the AP. + * @attention 4. This configuration will be saved in the Flash system parameter area if changed. + * + * @param struct station_config *config : ESP8266 station configuration + * + * @return true : succeed + * @return false : fail + */ bool wifi_station_set_config(struct station_config *config); + +/** + * @brief Set the configuration of the ESP8266 station. And the configuration + * will not be saved to the Flash. + * + * @attention 1. This API can be called only when the ESP8266 station is enabled. + * @attention 2. If wifi_station_set_config_current is called in user_init , there + * is no need to call wifi_station_connect. + * The ESP8266 station will automatically connect to the AP (router) + * after the system initialization. Otherwise, wifi_station_connect + * should be called. + * @attention 3. Generally, station_config.bssid_set needs to be 0; and it needs + * to be 1 only when users need to check the MAC address of the AP. + * + * @param struct station_config *config : ESP8266 station configuration + * + * @return true : succeed + * @return false : fail + */ bool wifi_station_set_config_current(struct station_config *config); +/** + * @brief Connect the ESP8266 WiFi station to the AP. + * + * @attention 1. This API should be called when the ESP8266 station is enabled, + * and the system initialization is completed. Do not call this API in user_init. + * @attention 2. If the ESP8266 is connected to an AP, call wifi_station_disconnect to disconnect. + * + * @param null + * + * @return true : succeed + * @return false : fail + */ bool wifi_station_connect(void); + +/** + * @brief Disconnect the ESP8266 WiFi station from the AP. + * + * @attention This API should be called when the ESP8266 station is enabled, + * and the system initialization is completed. Do not call this API in user_init. + * + * @param null + * + * @return true : succeed + * @return false : fail + */ bool wifi_station_disconnect(void); +/** + * @brief Get rssi of the AP which ESP8266 station connected to. + * + * @param null + * + * @return 31 : fail, invalid value. + * @return others : succeed, value of rssi. In general, rssi value < 10 + */ sint8 wifi_station_get_rssi(void); struct scan_config { - uint8 *ssid; // Note: ssid == NULL, don't filter ssid. - uint8 *bssid; // Note: bssid == NULL, don't filter bssid. - uint8 channel; // Note: channel == 0, scan all channels, otherwise scan set channel. - uint8 show_hidden; // Note: show_hidden == 1, can get hidden ssid routers' info. + uint8 *ssid; // Note: ssid == NULL, don't filter ssid. + uint8 *bssid; // Note: bssid == NULL, don't filter bssid. + uint8 channel; // Note: channel == 0, scan all channels, otherwise scan set channel. + uint8 show_hidden; // Note: show_hidden == 1, can get hidden ssid routers' info. }; +/** + * @brief Scan all available APs. + * + * @attention This API should be called when the ESP8266 station is enabled, and + * the system initialization is completed. Do not call this API in user_init. + * + * @param struct scan_config *config : configuration of scanning + * @param struct scan_done_cb_t cb : callback of scanning + * + * @return true : succeed + * @return false : fail + */ bool wifi_station_scan(struct scan_config *config, scan_done_cb_t cb); -uint8 wifi_station_get_auto_connect(void); -bool wifi_station_set_auto_connect(uint8 set); - -bool wifi_station_set_reconnect_policy(bool set); - -enum { - STATION_IDLE = 0, - STATION_CONNECTING, - STATION_WRONG_PASSWORD, - STATION_NO_AP_FOUND, - STATION_CONNECT_FAIL, - STATION_GOT_IP -}; +/** + * @brief Check if the ESP8266 station will connect to the recorded AP automatically + * when the power is on. + * + * @param null + * + * @return true : connect to the AP automatically + * @return false : not connect to the AP automatically + */ +bool wifi_station_get_auto_connect(void); + +/** + * @brief Set whether the ESP8266 station will connect to the recorded AP + * automatically when the power is on. It will do so by default. + * + * @attention 1. If this API is called in user_init, it is effective immediately + * after the power is on. If it is called in other places, it will + * be effective the next time when the power is on. + * @attention 2. This configuration will be saved in Flash system parameter area if changed. + * + * @param bool set : If it will automatically connect to the AP when the power is on + * - true : it will connect automatically + * - false: it will not connect automatically + * + * @return true : succeed + * @return false : fail + */ +bool wifi_station_set_auto_connect(bool set); + +/** + * @brief Check whether the ESP8266 station will reconnect to the AP after disconnection. + * + * @param null + * + * @return true : succeed + * @return false : fail + */ +bool wifi_station_get_reconnect_policy(void); + +typedef enum { + STATION_IDLE = 0, /**< ESP8266 station idle */ + STATION_CONNECTING, /**< ESP8266 station is connecting to AP*/ + STATION_WRONG_PASSWORD, /**< the password is wrong*/ + STATION_NO_AP_FOUND, /**< ESP8266 station can not find the target AP*/ + STATION_CONNECT_FAIL, /**< ESP8266 station fail to connect to AP*/ + STATION_GOT_IP /**< ESP8266 station got IP address from AP*/ +} STATION_STATUS; enum dhcp_status { DHCP_STOPPED, DHCP_STARTED }; -uint8 wifi_station_get_connect_status(void); - +/** + * @brief Get the connection status of the ESP8266 WiFi station. + * + * @param null + * + * @return the status of connection + */ +STATION_STATUS wifi_station_get_connect_status(void); + +/** + * @brief Get the information of APs (5 at most) recorded by ESP8266 station. + * + * @param struct station_config config[] : information of the APs, the array size should be 5. + * + * @return The number of APs recorded. + */ uint8 wifi_station_get_current_ap_id(void); + +/** + * @brief Switch the ESP8266 station connection to a recorded AP. + * + * @param uint8 new_ap_id : AP's record id, start counting from 0. + * + * @return true : succeed + * @return false : fail + */ bool wifi_station_ap_change(uint8 current_ap_id); + +/** + * @brief Set the number of APs that can be recorded in the ESP8266 station. + * When the ESP8266 station is connected to an AP, the SSID and password + * of the AP will be recorded. + * + * @attention This configuration will be saved in the Flash system parameter area if changed. + * + * @param uint8 ap_number : the number of APs that can be recorded (MAX: 5) + * + * @return true : succeed + * @return false : fail + */ bool wifi_station_ap_number_set(uint8 ap_number); + +/** + * @brief Get the information of APs (5 at most) recorded by ESP8266 station. + * + * Example: + * 
+  *         struct station_config config[5];
+  *         nt i = wifi_station_get_ap_info(config);
+  *
+ * + * @param struct station_config config[] : information of the APs, the array size should be 5. + * + * @return The number of APs recorded. + */ uint8 wifi_station_get_ap_info(struct station_config config[]); +/** + * @brief Enable the ESP8266 station DHCP client. + * + * @attention 1. The DHCP is enabled by default. + * @attention 2. The DHCP and the static IP API ((wifi_set_ip_info)) influence each other, + * and if the DHCP is enabled, the static IP will be disabled; + * if the static IP is enabled, the DHCP will be disabled. + * It depends on the latest configuration. + * + * @param null + * + * @return true : succeed + * @return false : fail + */ bool wifi_station_dhcpc_start(void); + +/** + * @brief Disable the ESP8266 station DHCP client. + * + * @attention 1. The DHCP is enabled by default. + * @attention 2. The DHCP and the static IP API ((wifi_set_ip_info)) influence each other, + * and if the DHCP is enabled, the static IP will be disabled; + * if the static IP is enabled, the DHCP will be disabled. + * It depends on the latest configuration. + * + * @param null + * + * @return true : succeed + * @return false : fail + */ bool wifi_station_dhcpc_stop(void); + +/** + * @brief Get the ESP8266 station DHCP client status. + * + * @param null + * + * @return enum dhcp_status + */ enum dhcp_status wifi_station_dhcpc_status(void); bool wifi_station_dhcpc_set_maxtry(uint8 num); @@ -252,24 +920,75 @@ char* wifi_station_get_hostname(void); bool wifi_station_set_hostname(char *name); int wifi_station_set_cert_key(uint8 *client_cert, int client_cert_len, - uint8 *private_key, int private_key_len, - uint8 *private_key_passwd, int private_key_passwd_len); + uint8 *private_key, int private_key_len, + uint8 *private_key_passwd, int private_key_passwd_len); void wifi_station_clear_cert_key(void); + +/** \defgroup SoftAP_APIs SoftAP APIs + * @brief ESP8266 Soft-AP APIs + * @attention To call APIs related to ESP8266 soft-AP has to enable soft-AP mode first (wifi_set_opmode) + */ + struct softap_config { - uint8 ssid[32]; - uint8 password[64]; - uint8 ssid_len; // Note: Recommend to set it according to your ssid - uint8 channel; // Note: support 1 ~ 13 - AUTH_MODE authmode; // Note: Don't support AUTH_WEP in softAP mode. - uint8 ssid_hidden; // Note: default 0 - uint8 max_connection; // Note: default 4, max 4 - uint16 beacon_interval; // Note: support 100 ~ 60000 ms, default 100 + uint8 ssid[32]; /**< SSID of ESP8266 soft-AP */ + uint8 password[64]; /**< Password of ESP8266 soft-AP */ + uint8 ssid_len; /**< Length of SSID. If softap_config.ssid_len==0, check the SSID until there is a termination character; otherwise, set the SSID length according to softap_config.ssid_len. */ + uint8 channel; /**< Channel of ESP8266 soft-AP */ + AUTH_MODE authmode; /**< Auth mode of ESP8266 soft-AP. Do not support AUTH_WEP in soft-AP mode */ + uint8 ssid_hidden; /**< Broadcast SSID or not, default 0, broadcast the SSID */ + uint8 max_connection; /**< Max number of stations allowed to connect in, default 4, max 4 */ + uint16 beacon_interval; /**< Beacon interval, 100 ~ 60000 ms, default 100 */ }; +/** + * @brief Get the current configuration of the ESP8266 WiFi soft-AP + * + * @param struct softap_config *config : ESP8266 soft-AP configuration + * + * @return true : succeed + * @return false : fail + */ bool wifi_softap_get_config(struct softap_config *config); + +/** + * @brief Get the configuration of the ESP8266 WiFi soft-AP saved in the flash + * + * @param struct softap_config *config : ESP8266 soft-AP configuration + * + * @return true : succeed + * @return false : fail + */ bool wifi_softap_get_config_default(struct softap_config *config); + +/** + * @brief Set the configuration of the WiFi soft-AP and save it to the Flash. + * + * @attention 1. This configuration will be saved in flash system parameter area if changed + * @attention 2. The ESP8266 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 ESP8266 station. + * + * @param struct softap_config *config : ESP8266 soft-AP configuration + * + * @return true : succeed + * @return false : fail + */ bool wifi_softap_set_config(struct softap_config *config); + +/** + * @brief Set the configuration of the WiFi soft-AP; the configuration will + * not be saved to the Flash. + * + * @attention The ESP8266 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 ESP8266 station. + * + * @param struct softap_config *config : ESP8266 soft-AP configuration + * + * @return true : succeed + * @return false : fail + */ bool wifi_softap_set_config_current(struct softap_config *config); struct station_info { @@ -291,83 +1010,475 @@ enum dhcps_offer_option{ OFFER_END }; +/** + * @brief Get the number of stations connected to the ESP8266 soft-AP. + * + * @attention The ESP8266 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 ESP8266 station. + * + * @param null + * + * @return the number of stations connected to the ESP8266 soft-AP + */ uint8 wifi_softap_get_station_num(void); -struct station_info * wifi_softap_get_station_info(void); + +/** + * @brief Get the information of stations connected to the ESP8266 soft-AP, + * including MAC and IP. + * + * @attention wifi_softap_get_station_info can not get the static IP, it can only + * be used when DHCP is enabled. + * + * @param null + * + * @return struct station_info* : station information structure + */ +struct station_info *wifi_softap_get_station_info(void); + +/** + * @brief Free the space occupied by station_info when wifi_softap_get_station_info is called. + * + * @attention The ESP8266 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 ESP8266 station. + * + * @param null + * + * @return null + */ void wifi_softap_free_station_info(void); +/** + * @brief Enable the ESP8266 soft-AP DHCP server. + * + * @attention 1. The DHCP is enabled by default. + * @attention 2. The DHCP and the static IP related API (wifi_set_ip_info) influence + * each other, if the DHCP is enabled, the static IP will be disabled; + * if the static IP is enabled, the DHCP will be disabled. + * It depends on the latest configuration. + * + * @param null + * + * @return true : succeed + * @return false : fail + */ bool wifi_softap_dhcps_start(void); + +/** + * @brief Disable the ESP8266 soft-AP DHCP server. The DHCP is enabled by default. + * + * @param null + * + * @return true : succeed + * @return false : fail + */ bool wifi_softap_dhcps_stop(void); -bool wifi_softap_set_dhcps_lease(struct dhcps_lease *please); +/** + * @brief Get the ESP8266 soft-AP DHCP server status. + * + * @param null + * + * @return enum dhcp_status + */ +enum dhcp_status wifi_softap_dhcps_status(void); + +/** + * @brief Query the IP range that can be got from the ESP8266 soft-AP DHCP server. + * + * @attention This API can only be called during ESP8266 soft-AP DHCP server enabled. + * + * @param struct dhcps_lease *please : IP range of the ESP8266 soft-AP DHCP server. + * + * @return true : succeed + * @return false : fail + */ bool wifi_softap_get_dhcps_lease(struct dhcps_lease *please); -uint32 wifi_softap_get_dhcps_lease_time(void); -bool wifi_softap_set_dhcps_lease_time(uint32 minute); -bool wifi_softap_reset_dhcps_lease_time(void); -enum dhcp_status wifi_softap_dhcps_status(void); -bool wifi_softap_set_dhcps_offer_option(uint8 level, void* optarg); +/** + * @brief Set the IP range of the ESP8266 soft-AP DHCP server. + * + * @attention 1. The IP range should be in the same sub-net with the ESP8266 + * soft-AP IP address. + * @attention 2. This API should only be called when the DHCP server is disabled + * (wifi_softap_dhcps_stop). + * @attention 3. This configuration will only take effect the next time when the + * DHCP server is enabled (wifi_softap_dhcps_start). + * - If the DHCP server is disabled again, this API should be called to set the IP range. + * - Otherwise, when the DHCP server is enabled later, the default IP range will be used. + * + * @param struct dhcps_lease *please : IP range of the ESP8266 soft-AP DHCP server. + * + * @return true : succeed + * @return false : fail + */ +bool wifi_softap_set_dhcps_lease(struct dhcps_lease *please); + +/** + * @brief Get ESP8266 soft-AP DHCP server lease time. + * + * @attention This API can only be called during ESP8266 soft-AP DHCP server enabled. + * + * @param null + * + * @return lease time, uint: minute. + */ +uint32 wifi_softap_get_dhcps_lease_time(void); -#define STATION_IF 0x00 -#define SOFTAP_IF 0x01 +/** + * @brief Set ESP8266 soft-AP DHCP server lease time, default is 120 minutes. + * + * @attention This API can only be called during ESP8266 soft-AP DHCP server enabled. + * + * @param uint32 minute : lease time, uint: minute, range:[1, 2880]. + * + * @return true : succeed + * @return false : fail + */ +bool wifi_softap_set_dhcps_lease_time(uint32 minute); -bool wifi_get_ip_info(uint8 if_index, struct ip_info *info); -bool wifi_set_ip_info(uint8 if_index, struct ip_info *info); -bool wifi_get_macaddr(uint8 if_index, uint8 *macaddr); -bool wifi_set_macaddr(uint8 if_index, uint8 *macaddr); +/** + * @brief Reset ESP8266 soft-AP DHCP server lease time which is 120 minutes by default. + * + * @attention This API can only be called during ESP8266 soft-AP DHCP server enabled. + * + * @param null + * + * @return true : succeed + * @return false : fail + */ +bool wifi_softap_reset_dhcps_lease_time(void); +/** + * @brief Set the ESP8266 soft-AP DHCP server option. + * + * Example: + * 
+  *         uint8 mode = 0;
+  *         wifi_softap_set_dhcps_offer_option(OFFER_ROUTER, &mode);
+  *
+ * + * @param uint8 level : OFFER_ROUTER, set the router option. + * @param void* optarg : + * - bit0, 0 disable the router information; + * - bit0, 1 enable the router information. + * + * @return true : succeed + * @return false : fail + */ +bool wifi_softap_set_dhcps_offer_option(uint8 level, void *optarg); + + +typedef enum { + STATION_IF = 0, /**< ESP8266 station interface */ + SOFTAP_IF, /**< ESP8266 soft-AP interface */ + MAX_IF +} WIFI_INTERFACE; + +/** + * @brief Get the IP address of the ESP8266 WiFi station or the soft-AP interface. + * + * @attention Users need to enable the target interface (station or soft-AP) by wifi_set_opmode first. + * + * @param WIFI_INTERFACE if_index : get the IP address of the station or the soft-AP interface, + * 0x00 for STATION_IF, 0x01 for SOFTAP_IF. + * @param struct ip_info *info : the IP information obtained. + * + * @return true : succeed + * @return false : fail + */ +bool wifi_get_ip_info(WIFI_INTERFACE if_index, struct ip_info *info); + +/** + * @brief Set the IP address of the ESP8266 WiFi station or the soft-AP interface. + * + * @attention 1. Users need to enable the target interface (station or soft-AP) by + * wifi_set_opmode first. + * @attention 2. To set static IP, users need to disable DHCP first (wifi_station_dhcpc_stop + * or wifi_softap_dhcps_stop): + * - If the DHCP is enabled, the static IP will be disabled; if the static IP is enabled, + * the DHCP will be disabled. It depends on the latest configuration. + * + * @param WIFI_INTERFACE if_index : get the IP address of the station or the soft-AP interface, + * 0x00 for STATION_IF, 0x01 for SOFTAP_IF. + * @param struct ip_info *info : the IP information obtained. + * + * @return true : succeed + * @return false : fail + */ +bool wifi_set_ip_info(WIFI_INTERFACE if_index, struct ip_info *info); + +/** + * @brief Get MAC address of the ESP8266 WiFi station or the soft-AP interface. + * + * @param WIFI_INTERFACE if_index : get the IP address of the station or the soft-AP interface, + * 0x00 for STATION_IF, 0x01 for SOFTAP_IF. + * @param uint8 *macaddr : the MAC address. + * + * @return true : succeed + * @return false : fail + */ +bool wifi_get_macaddr(WIFI_INTERFACE if_index, uint8 *macaddr); + +/** + * @brief Set MAC address of the ESP8266 WiFi station or the soft-AP interface. + * + * @attention 1. This API can only be called in user_init. + * @attention 2. Users need to enable the target interface (station or soft-AP) by wifi_set_opmode first. + * @attention 3. ESP8266 soft-AP and station have different MAC addresses, do not set them to be the same. + * - The bit0 of the first byte of ESP8266 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". + * + * @param WIFI_INTERFACE if_index : get the IP address of the station or the soft-AP interface, + * 0x00 for STATION_IF, 0x01 for SOFTAP_IF. + * @param uint8 *macaddr : the MAC address. + * + * @return true : succeed + * @return false : fail + */ +bool wifi_set_macaddr(WIFI_INTERFACE if_index, uint8 *macaddr); + + +/** + * @brief Get the channel number for sniffer functions. + * + * @param null + * + * @return channel number + */ uint8 wifi_get_channel(void); + +/** + * @brief Set the channel number for sniffer functions. + * + * @param uint8 channel : channel number + * + * @return true : succeed + * @return false : fail + */ bool wifi_set_channel(uint8 channel); +/** + * @brief Install the WiFi status LED. + * + * @param uint8 gpio_id : GPIO ID + * @param uint8 gpio_name : GPIO mux name + * @param uint8 gpio_func : GPIO function + * + * @return null + */ void wifi_status_led_install(uint8 gpio_id, uint32 gpio_name, uint8 gpio_func); + +/** + * @brief Uninstall the WiFi status LED. + * + * @param null + * + * @return null + */ void wifi_status_led_uninstall(); /** Get the absolute difference between 2 u32_t values (correcting overflows) * 'a' is expected to be 'higher' (without overflow) than 'b'. */ #define ESP_U32_DIFF(a, b) (((a) >= (b)) ? ((a) - (b)) : (((a) + ((b) ^ 0xFFFFFFFF) + 1))) +/** + * @brief Enable the promiscuous mode. + * + * @attention 1. The promiscuous mode can only be enabled in the ESP8266 station mode. + * @attention 2. When in the promiscuous mode, the ESP8266 station and soft-AP are disabled. + * @attention 3. Call wifi_station_disconnect to disconnect before enabling the promiscuous mode. + * @attention 4. Don't call any other APIs when in the promiscuous mode. Call + * wifi_promiscuous_enable(0) to quit sniffer before calling other APIs. + * + * @param uint8 promiscuous : + * - 0: to disable the promiscuous mode + * - 1: to enable the promiscuous mode + * + * @return null + */ void wifi_promiscuous_enable(uint8 promiscuous); +/** + * @brief The RX callback function in the promiscuous mode. + * + * Each time a packet is received, the callback function will be called. + * + * @param uint8 *buf : the data received + * @param uint16 len : data length + * + * @return null + */ typedef void (* wifi_promiscuous_cb_t)(uint8 *buf, uint16 len); +/** + * @brief Register the RX callback function in the promiscuous mode. + * + * Each time a packet is received, the registered callback function will be called. + * + * @param wifi_promiscuous_cb_t cb : callback + * + * @return null + */ void wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb); +/** + * @brief Set the MAC address filter for the sniffer mode. + * + * @attention This filter works only for the current sniffer mode. + * If users disable and then enable the sniffer mode, and then enable + * sniffer, they need to set the MAC address filter again. + * + * @param const uint8_t *address : MAC address + * + * @return true : succeed + * @return false : fail + */ void wifi_promiscuous_set_mac(const uint8_t *address); -enum phy_mode { - PHY_MODE_11B = 1, - PHY_MODE_11G = 2, - PHY_MODE_11N = 3 -}; - -enum phy_mode wifi_get_phy_mode(void); -bool wifi_set_phy_mode(enum phy_mode mode); - -enum sleep_type { - NONE_SLEEP_T = 0, +typedef enum { + PHY_MODE_11B = 1, /**< 802.11b */ + PHY_MODE_11G = 2, /**< 802.11g */ + PHY_MODE_11N = 3 /**< 802.11n */ +} WIFI_PHY_MODE; + +/** + * @brief Get the ESP8266 physical mode (802.11b/g/n). + * + * @param null + * + * @return enum WIFI_PHY_MODE + */ +WIFI_PHY_MODE wifi_get_phy_mode(void); + +/** + * @brief Set the ESP8266 physical mode (802.11b/g/n). + * + * @attention The ESP8266 soft-AP only supports bg. + * + * @param WIFI_PHY_MODE mode : physical mode + * + * @return true : succeed + * @return false : fail + */ +bool wifi_set_phy_mode(WIFI_PHY_MODE mode); + +typedef enum { + NONE_SLEEP_T = 0, LIGHT_SLEEP_T, MODEM_SLEEP_T -}; - -bool wifi_set_sleep_type(enum sleep_type type); -enum sleep_type wifi_get_sleep_type(void); - +} sleep_type; + +/** + * @brief Sets sleep type. + * + * Set NONE_SLEEP_T to disable sleep. Default to be Modem sleep. + * + * @attention Sleep function only takes effect in station-only mode. + * + * @param sleep_type type : sleep type + * + * @return true : succeed + * @return false : fail + */ +bool wifi_set_sleep_type(sleep_type type); + +/** + * @brief Gets sleep type. + * + * @param null + * + * @return sleep type + */ +sleep_type wifi_get_sleep_type(void); + +/** + * @brief Enable force sleep function. + * + * @attention Force sleep function is disabled by default. + * + * @param null + * + * @return null + */ void wifi_fpm_open(void); + +/** + * @brief Disable force sleep function. + * + * @param null + * + * @return null + */ void wifi_fpm_close(void); + +/** + * @brief Wake ESP8266 up from MODEM_SLEEP_T force sleep. + * + * @attention This API can only be called when MODEM_SLEEP_T force sleep function + * is enabled, after calling wifi_fpm_open. + * This API can not be called after calling wifi_fpm_close. + * + * @param null + * + * @return null + */ void wifi_fpm_do_wakeup(void); + +/** + * @brief Force ESP8266 enter sleep mode, and it will wake up automatically when time out. + * + * @attention 1. This API can only be called when force sleep function is enabled, after + * calling wifi_fpm_open. This API can not be called after calling wifi_fpm_close. + * @attention 2. If this API returned 0 means that the configuration is set successfully, + * but the ESP8266 will not enter sleep mode immediately, it is going to sleep + * in the system idle task. Please do not call other WiFi related function right + * after calling this API. + * + * @param uint32 sleep_time_in_us : sleep time, ESP8266 will wake up automatically + * when time out. Unit: us. Range: 10000 ~ 268435455(0xFFFFFFF). + * - If sleep_time_in_us is 0xFFFFFFF, the ESP8266 will sleep till + * - if wifi_fpm_set_sleep_type is set to be LIGHT_SLEEP_T, ESP8266 can wake up by GPIO. + * - if wifi_fpm_set_sleep_type is set to be MODEM_SLEEP_T, ESP8266 can wake up by wifi_fpm_do_wakeup. + * + * @return 0, setting succeed; + * @return -1, fail to sleep, sleep status error; + * @return -2, fail to sleep, force sleep function is not enabled. + */ sint8 wifi_fpm_do_sleep(uint32 sleep_time_in_us); -void wifi_fpm_set_sleep_type(enum sleep_type type); -enum sleep_type wifi_fpm_get_sleep_type(void); + +/** + * @brief Set sleep type for force sleep function. + * + * @attention This API can only be called before wifi_fpm_open. + * + * @param sleep_type type : sleep type + * + * @return null + */ +void wifi_fpm_set_sleep_type(sleep_type type); + +/** + * @brief Get sleep type of force sleep function. + * + * @param null + * + * @return sleep type + */ +sleep_type wifi_fpm_get_sleep_type(void); + enum { - EVENT_STAMODE_CONNECTED = 0, - EVENT_STAMODE_DISCONNECTED, - EVENT_STAMODE_AUTHMODE_CHANGE, - EVENT_STAMODE_GOT_IP, - EVENT_STAMODE_DHCP_TIMEOUT, - EVENT_SOFTAPMODE_STACONNECTED, + EVENT_STAMODE_CONNECTED = 0, + EVENT_STAMODE_DISCONNECTED, + EVENT_STAMODE_AUTHMODE_CHANGE, + EVENT_STAMODE_GOT_IP, + EVENT_STAMODE_DHCP_TIMEOUT, + EVENT_SOFTAPMODE_STACONNECTED, EVENT_SOFTAPMODE_STADISCONNECTED, EVENT_SOFTAPMODE_PROBEREQRECVED, - EVENT_MAX + EVENT_MAX }; enum { @@ -453,13 +1564,33 @@ typedef union { } Event_Info_u; typedef struct _esp_event { - uint32 event; - Event_Info_u event_info; + uint32 event; + Event_Info_u event_info; } System_Event_t; +/** + * @brief The Wi-Fi event handler. + * + * @attention No complex operations are allowed in callback. + * If you want to execute any complex operations, please post message to another task instead. + * + * @param System_Event_t *event : WiFi event + * + * @return null + */ typedef void (* wifi_event_handler_cb_t)(System_Event_t *event); -void wifi_set_event_handler_cb(wifi_event_handler_cb_t cb); +/** + * @brief Register the Wi-Fi event handler. + * + * @param wifi_event_handler_cb_t cb : callback function + * + * @return true : succeed + * @return false : fail + */ +bool wifi_set_event_handler_cb(wifi_event_handler_cb_t cb); + +/* WPS can only be used when ESP8266 station is enabled. */ typedef enum wps_type { WPS_TYPE_DISABLE = 0, @@ -470,40 +1601,192 @@ typedef enum wps_type { } WPS_TYPE_t; enum wps_cb_status { - WPS_CB_ST_SUCCESS = 0, - WPS_CB_ST_FAILED, - WPS_CB_ST_TIMEOUT, - WPS_CB_ST_WEP, + WPS_CB_ST_SUCCESS = 0, /**< WPS succeed */ + WPS_CB_ST_FAILED, /**< WPS fail */ + WPS_CB_ST_TIMEOUT, /**< WPS timeout, fail */ + WPS_CB_ST_WEP, /**< WPS failed because that WEP is not supported */ + WPS_CB_ST_SCAN_ERR, /**< can not find the target WPS AP */ }; + +/** + * @brief Enable Wi-Fi WPS function. + * + * @attention WPS can only be used when ESP8266 station is enabled. + * + * @param WPS_TYPE_t wps_type : WPS type, so far only WPS_TYPE_PBC is supported + * + * @return true : succeed + * @return false : fail + */ bool wifi_wps_enable(WPS_TYPE_t wps_type); + +/** + * @brief Disable Wi-Fi WPS function and release resource it taken. + * + * @param null + * + * @return true : succeed + * @return false : fail + */ bool wifi_wps_disable(void); + +/** + * @brief WPS starts to work. + * + * @attention WPS can only be used when ESP8266 station is enabled. + * + * @param null + * + * @return true : WPS starts to work successfully, but does not mean WPS succeed. + * @return false : fail + */ bool wifi_wps_start(void); +/** + * @brief WPS callback. + * + * @param int status : status of WPS, enum wps_cb_status. + * - If parameter status == WPS_CB_ST_SUCCESS in WPS callback, it means WPS got AP's + * information, user can call wifi_wps_disable to disable WPS and release resource, + * then call wifi_station_connect to connect to target AP. + * - Otherwise, it means that WPS fail, user can create a timer to retry WPS by + * wifi_wps_start after a while, or call wifi_wps_disable to disable WPS and release resource. + * + * @return null + */ typedef void (*wps_st_cb_t)(int status); + +/** + * @brief Set WPS callback. + * + * @attention WPS can only be used when ESP8266 station is enabled. + * + * @param wps_st_cb_t cb : callback. + * + * @return true : WPS starts to work successfully, but does not mean WPS succeed. + * @return false : fail + */ bool wifi_set_wps_cb(wps_st_cb_t cb); + +/** + * @brief Callback of sending user-define 802.11 packets. + * + * @param uint8 status : 0, packet sending succeed; otherwise, fail. + * + * @return null + */ typedef void (*freedom_outside_cb_t)(uint8 status); -int wifi_register_send_pkt_freedom_cb(freedom_outside_cb_t cb); + +/** + * @brief Register a callback for sending user-define 802.11 packets. + * + * @attention Only after the previous packet was sent, entered the freedom_outside_cb_t, + * the next packet is allowed to send. + * + * @param freedom_outside_cb_t cb : sent callback + * + * @return 0, succeed; + * @return -1, fail. + */ +sint32 wifi_register_send_pkt_freedom_cb(freedom_outside_cb_t cb); + +/** + * @brief Unregister the callback for sending user-define 802.11 packets. + * + * @param null + * + * @return null + */ void wifi_unregister_send_pkt_freedom_cb(void); -int wifi_send_pkt_freedom(uint8 *buf, int len, bool sys_seq); -int wifi_rfid_locp_recv_open(void); +/** + * @brief Send user-define 802.11 packets. + * + * @attention 1. Packet has to be the whole 802.11 packet, does not include the FCS. + * The length of the packet has to be longer than the minimum length + * of the header of 802.11 packet which is 24 bytes, and less than 1400 bytes. + * @attention 2. Duration area is invalid for user, it will be filled in SDK. + * @attention 3. The rate of sending packet is same as the management packet which + * is the same as the system rate of sending packets. + * @attention 4. Only after the previous packet was sent, entered the sent callback, + * the next packet is allowed to send. Otherwise, wifi_send_pkt_freedom + * will return fail. + * + * @param uint8 *buf : pointer of packet + * @param uint16 len : packet length + * @param bool sys_seq : follow the system's 802.11 packets sequence number or not, + * if it is true, the sequence number will be increased 1 every + * time a packet sent. + * + * @return 0, succeed; + * @return -1, fail. + */ +sint32 wifi_send_pkt_freedom(uint8 *buf, uint16 len, bool sys_seq); + +/** + * @brief Enable RFID LOCP (Location Control Protocol) to receive WDS packets. + * + * @param null + * + * @return 0, succeed; + * @return otherwise, fail. + */ +sint32 wifi_rfid_locp_recv_open(void); + +/** + * @brief Disable RFID LOCP (Location Control Protocol) . + * + * @param null + * + * @return null + */ void wifi_rfid_locp_recv_close(void); -typedef void (*rfid_locp_cb_t)(uint8 *frm, int len, int rssi); -int wifi_register_rfid_locp_recv_cb(rfid_locp_cb_t cb); +/** + * @brief RFID LOCP (Location Control Protocol) receive callback . + * + * @param uint8 *frm : point to the head of 802.11 packet + * @param int len : packet length + * @param int rssi : signal strength + * + * @return null + */ +typedef void (*rfid_locp_cb_t)(uint8 *frm, int len, sint8 rssi); + +/** + * @brief Register a callback of receiving WDS packets. + * + * Register a callback of receiving WDS packets. Only if the first MAC + * address of the WDS packet is a multicast address. + * + * @param rfid_locp_cb_t cb : callback + * + * @return 0, succeed; + * @return otherwise, fail. + */ +sint32 wifi_register_rfid_locp_recv_cb(rfid_locp_cb_t cb); + +/** + * @brief Unregister the callback of receiving WDS packets. + * + * @param null + * + * @return null + */ void wifi_unregister_rfid_locp_recv_cb(void); + enum FIXED_RATE { - PHY_RATE_48 = 0x8, - PHY_RATE_24 = 0x9, - PHY_RATE_12 = 0xA, - PHY_RATE_6 = 0xB, - PHY_RATE_54 = 0xC, - PHY_RATE_36 = 0xD, - PHY_RATE_18 = 0xE, - PHY_RATE_9 = 0xF, + PHY_RATE_48 = 0x8, + PHY_RATE_24 = 0x9, + PHY_RATE_12 = 0xA, + PHY_RATE_6 = 0xB, + PHY_RATE_54 = 0xC, + PHY_RATE_36 = 0xD, + PHY_RATE_18 = 0xE, + PHY_RATE_9 = 0xF, }; #define FIXED_RATE_MASK_NONE 0x00 @@ -511,7 +1794,36 @@ enum FIXED_RATE { #define FIXED_RATE_MASK_AP 0x02 #define FIXED_RATE_MASK_ALL 0x03 -int wifi_set_user_fixed_rate(uint8 enable_mask, uint8 rate); +/** + * @brief Set the fixed rate and mask of sending data from ESP8266. + * + * @attention 1. Only if the corresponding bit in enable_mask is 1, ESP8266 station + * or soft-AP will send data in the fixed rate. + * @attention 2. If the enable_mask is 0, both ESP8266 station and soft-AP will not + * send data in the fixed rate. + * @attention 3. ESP8266 station and soft-AP share the same rate, they can not be + * set into the different rate. + * + * @param uint8 enable_mask : 0x00 - disable the fixed rate + * - 0x01 - use the fixed rate on ESP8266 station + * - 0x02 - use the fixed rate on ESP8266 soft-AP + * - 0x03 - use the fixed rate on ESP8266 station and soft-AP + * @param uint8 rate : value of the fixed rate + * + * @return 0 : succeed + * @return otherwise : fail + */ +sint32 wifi_set_user_fixed_rate(uint8 enable_mask, uint8 rate); + +/** + * @brief Get the fixed rate and mask of ESP8266. + * + * @param uint8 *enable_mask : pointer of the enable_mask + * @param uint8 *rate : pointer of the fixed rate + * + * @return 0 : succeed + * @return otherwise : fail + */ int wifi_get_user_fixed_rate(uint8 *enable_mask, uint8 *rate); enum support_rate { @@ -529,7 +1841,24 @@ enum support_rate { RATE_11G36M = 11, }; -int wifi_set_user_sup_rate(uint8 min, uint8 max); +/** + * @brief Set the support rate of ESP8266. + * + * Set the rate range in the IE of support rate in ESP8266's beacon, + * probe req/resp and other packets. + * Tell other devices about the rate range supported by ESP8266 to limit + * the rate of sending packets from other devices. + * Example : wifi_set_user_sup_rate(RATE_11G6M, RATE_11G24M); + * + * @attention This API can only support 802.11g now, but it will support 802.11b in next version. + * + * @param uint8 min : the minimum value of the support rate, according to enum support_rate. + * @param uint8 max : the maximum value of the support rate, according to enum support_rate. + * + * @return 0 : succeed + * @return otherwise : fail + */ +sint32 wifi_set_user_sup_rate(uint8 min, uint8 max); enum RATE_11B_ID { RATE_11B_B11M = 0, @@ -579,23 +1908,122 @@ enum RATE_11N_ID { #define LIMIT_RATE_MASK_AP 0x02 #define LIMIT_RATE_MASK_ALL 0x03 +/** + * @brief Limit the initial rate of sending data from ESP8266. + * + * Example: + * wifi_set_user_rate_limit(RC_LIMIT_11G, 0, RATE_11G_G18M, RATE_11G_G6M); + * + * @attention The rate of retransmission is not limited by this API. + * + * @param uint8 mode : WiFi mode + * - #define RC_LIMIT_11B 0 + * - #define RC_LIMIT_11G 1 + * - #define RC_LIMIT_11N 2 + * @param uint8 ifidx : interface of ESP8266 + * - 0x00 - ESP8266 station + * - 0x01 - ESP8266 soft-AP + * @param uint8 max : the maximum value of the rate, according to the enum rate + * corresponding to the first parameter mode. + * @param uint8 min : the minimum value of the rate, according to the enum rate + * corresponding to the first parameter mode. + * + * @return 0 : succeed + * @return otherwise : fail + */ bool wifi_set_user_rate_limit(uint8 mode, uint8 ifidx, uint8 max, uint8 min); + +/** + * @brief Get the interfaces of ESP8266 whose rate of sending data is limited by + * wifi_set_user_rate_limit. + * + * @param null + * + * @return LIMIT_RATE_MASK_NONE - disable the limitation on both ESP8266 station and soft-AP + * @return LIMIT_RATE_MASK_STA - enable the limitation on ESP8266 station + * @return LIMIT_RATE_MASK_AP - enable the limitation on ESP8266 soft-AP + * @return LIMIT_RATE_MASK_ALL - enable the limitation on both ESP8266 station and soft-AP + */ uint8 wifi_get_user_limit_rate_mask(void); + +/** + * @brief Set the interfaces of ESP8266 whose rate of sending packets is limited by + * wifi_set_user_rate_limit. + * + * @param uint8 enable_mask : + * - LIMIT_RATE_MASK_NONE - disable the limitation on both ESP8266 station and soft-AP + * - LIMIT_RATE_MASK_STA - enable the limitation on ESP8266 station + * - LIMIT_RATE_MASK_AP - enable the limitation on ESP8266 soft-AP + * - LIMIT_RATE_MASK_ALL - enable the limitation on both ESP8266 station and soft-AP + * + * @return true : succeed + * @return false : fail + */ bool wifi_set_user_limit_rate_mask(uint8 enable_mask); -enum { +typedef enum { USER_IE_BEACON = 0, USER_IE_PROBE_REQ, USER_IE_PROBE_RESP, USER_IE_ASSOC_REQ, USER_IE_ASSOC_RESP, USER_IE_MAX -}; - -typedef void (*user_ie_manufacturer_recv_cb_t)(uint8 type, const uint8 sa[6], const uint8 m_oui[3], uint8 *ie, uint8 ie_len, int rssi); - -bool wifi_set_user_ie(bool enable, uint8 *m_oui, uint8 type, uint8 *user_ie, uint8 len); -int wifi_register_user_ie_manufacturer_recv_cb(user_ie_manufacturer_recv_cb_t cb); +} user_ie_type; + +/** + * @brief User IE received callback. + * + * @param user_ie_type type : type of user IE. + * @param const uint8 sa[6] : source address of the packet. + * @param const uint8 m_oui[3] : factory tag. + * @param uint8 *user_ie : pointer of user IE. + * @param uint8 ie_len : length of user IE. + * @param sint32 rssi : signal strength. + * + * @return null + */ +typedef void (*user_ie_manufacturer_recv_cb_t)(user_ie_type type, const uint8 sa[6], const uint8 m_oui[3], uint8 *ie, uint8 ie_len, sint32 rssi); + +/** + * @brief Set user IE of ESP8266. + * + * The user IE will be added to the target packets of user_ie_type. + * + * @param bool enable : + * - true, enable the corresponding user IE function, all parameters below have to be set. + * - false, disable the corresponding user IE function and release the resource, + * only the parameter "type" below has to be set. + * @param uint8 *m_oui : factory tag, apply for it from Espressif System. + * @param user_ie_type type : IE type. If it is USER_IE_BEACON, please disable the + * IE function and enable again to take the configuration + * effect immediately . + * @param uint8 *user_ie : user-defined information elements, need not input the whole + * 802.11 IE, need only the user-define part. + * @param uint8 len : length of user IE, 247 bytes at most. + * + * @return true : succeed + * @return false : fail + */ + +bool wifi_set_user_ie(bool enable, uint8 *m_oui, user_ie_type type, uint8 *user_ie, uint8 len); + +/** + * @brief Register user IE received callback. + * + * @param user_ie_manufacturer_recv_cb_t cb : callback + * + * @return 0 : succeed + * @return -1 : fail + */ +sint32 wifi_register_user_ie_manufacturer_recv_cb(user_ie_manufacturer_recv_cb_t cb); + +/** + * @brief Unregister user IE received callback. + * + * @param null + * + * @return null + */ void wifi_unregister_user_ie_manufacturer_recv_cb(void); #endif diff --git a/esp_meas.pro.user b/esp_meas.pro.user index ef218b3..e2ec31d 100644 --- a/esp_meas.pro.user +++ b/esp_meas.pro.user @@ -1,6 +1,6 @@ - + EnvironmentId diff --git a/include/ets_sys_extra.h b/include/ets_sys_extra.h index e9f8963..a1a27e1 100644 --- a/include/ets_sys_extra.h +++ b/include/ets_sys_extra.h @@ -13,5 +13,5 @@ extern void system_soft_wdt_feed(); extern int ets_str2macaddr(void *, void *); extern void ets_update_cpu_frequency(int freqmhz); extern int os_printf_plus(const char *format, ...) __attribute__ ((format (printf, 1, 2))); -extern uint8 wifi_get_opmode(void); +//extern uint8 wifi_get_opmode(void); extern void ets_bzero(void *s, size_t n); diff --git a/libesphttpd/include/espmissingprotos.h b/libesphttpd/include/espmissingprotos.h index ce77720..a72e6d0 100644 --- a/libesphttpd/include/espmissingprotos.h +++ b/libesphttpd/include/espmissingprotos.h @@ -10,6 +10,7 @@ int strcasecmp(const char *a, const char *b); #include #include #include +//#include //Missing function prototypes in include folders. Gcc will warn on these if we don't define 'em anywhere. //MOST OF THESE ARE GUESSED! but they seem to swork and shut up the compiler. typedef struct espconn espconn; @@ -40,7 +41,7 @@ int os_printf(const char *format, ...) __attribute__ ((format (printf, 1, 2))); int os_snprintf(char *str, size_t size, const char *format, ...) __attribute__ ((format (printf, 3, 4))); int os_printf_plus(const char *format, ...) __attribute__ ((format (printf, 1, 2))); void uart_div_modify(int no, unsigned int freq); -uint8 wifi_get_opmode(void); +//uint8 wifi_get_opmode(void); uint32 system_get_time(); int rand(void); void ets_bzero(void *s, size_t n);