ICMP 回显
概述
网际控制报文协议 (ICMP) 通常用于诊断或控制目的,或响应 IP 操作中的错误。常用的网络工具 ping
的应答,即 Echo Reply
,就是基于类型字段值为 0 的 ICMP 数据包实现的。
在 ping 会话中,首先由源主机发出请求包 (ICMP echo request),然后等待应答包 (ICMP echo reply),等待具有超时限制。通过这一过程,还能测量出信息的往返用时。收到有效的应答包后,源主机会生成 IP 链路层的统计数据(如失包率、运行时间等)。
IoT 设备通常需要检查远程服务器是否可用。如果服务器离线,设备应向用户发出警告。通过创建 ping 会话,定期发送或解析 ICMP echo 数据包,就能实现这一功能。
为简化这一过程方便用户操作,ESP-IDF 提供了一些好用的 API。
创建 ping 会话
要创建 ping 会话,首先需填写 esp_ping_config_t
,指定目标芯片 IP 地址、间隔时间等配置。此外,还可以通过 esp_ping_callbacks_t
注册回调函数。
创建 ping 会话并注册回调函数示例:
static void test_on_ping_success(esp_ping_handle_t hdl, void *args)
{
// optionally, get callback arguments
// const char* str = (const char*) args;
// printf("%s\r\n", str); // "foo"
uint8_t ttl;
uint16_t seqno;
uint32_t elapsed_time, recv_len;
ip_addr_t target_addr;
esp_ping_get_profile(hdl, ESP_PING_PROF_SEQNO, &seqno, sizeof(seqno));
esp_ping_get_profile(hdl, ESP_PING_PROF_TTL, &ttl, sizeof(ttl));
esp_ping_get_profile(hdl, ESP_PING_PROF_IPADDR, &target_addr, sizeof(target_addr));
esp_ping_get_profile(hdl, ESP_PING_PROF_SIZE, &recv_len, sizeof(recv_len));
esp_ping_get_profile(hdl, ESP_PING_PROF_TIMEGAP, &elapsed_time, sizeof(elapsed_time));
printf("%d bytes from %s icmp_seq=%d ttl=%d time=%d ms\n",
recv_len, inet_ntoa(target_addr.u_addr.ip4), seqno, ttl, elapsed_time);
}
static void test_on_ping_timeout(esp_ping_handle_t hdl, void *args)
{
uint16_t seqno;
ip_addr_t target_addr;
esp_ping_get_profile(hdl, ESP_PING_PROF_SEQNO, &seqno, sizeof(seqno));
esp_ping_get_profile(hdl, ESP_PING_PROF_IPADDR, &target_addr, sizeof(target_addr));
printf("From %s icmp_seq=%d timeout\n", inet_ntoa(target_addr.u_addr.ip4), seqno);
}
static void test_on_ping_end(esp_ping_handle_t hdl, void *args)
{
uint32_t transmitted;
uint32_t received;
uint32_t total_time_ms;
esp_ping_get_profile(hdl, ESP_PING_PROF_REQUEST, &transmitted, sizeof(transmitted));
esp_ping_get_profile(hdl, ESP_PING_PROF_REPLY, &received, sizeof(received));
esp_ping_get_profile(hdl, ESP_PING_PROF_DURATION, &total_time_ms, sizeof(total_time_ms));
printf("%d packets transmitted, %d received, time %dms\n", transmitted, received, total_time_ms);
}
void initialize_ping()
{
/* convert URL to IP address */
ip_addr_t target_addr;
struct addrinfo hint;
struct addrinfo *res = NULL;
memset(&hint, 0, sizeof(hint));
memset(&target_addr, 0, sizeof(target_addr));
getaddrinfo("www.espressif.com", NULL, &hint, &res);
struct in_addr addr4 = ((struct sockaddr_in *) (res->ai_addr))->sin_addr;
inet_addr_to_ip4addr(ip_2_ip4(&target_addr), &addr4);
freeaddrinfo(res);
esp_ping_config_t ping_config = ESP_PING_DEFAULT_CONFIG();
ping_config.target_addr = target_addr; // target IP address
ping_config.count = ESP_PING_COUNT_INFINITE; // ping in infinite mode, esp_ping_stop can stop it
/* set callback functions */
esp_ping_callbacks_t cbs;
cbs.on_ping_success = test_on_ping_success;
cbs.on_ping_timeout = test_on_ping_timeout;
cbs.on_ping_end = test_on_ping_end;
cbs.cb_args = "foo"; // arguments that will feed to all callback functions, can be NULL
cbs.cb_args = eth_event_group;
esp_ping_handle_t ping;
esp_ping_new_session(&ping_config, &cbs, &ping);
}
启动和停止 ping 会话
使用 esp_ping_new_session
返回的句柄可以启动或停止 ping 会话。注意,ping 会话在创建后不会自动启动。如果 ping 会话停止后重启,ICMP 数据包的序列号会归零重新计数。
删除 ping 会话
如果不再使用 ping 会话,可用 esp_ping_delete_session
将其删除。在删除 ping 会话时,确保该会话已处于停止状态(即已调用了 esp_ping_stop
,或该会话已完成所有步骤)。
获取运行时间数据
在回调函数中调用 esp_ping_get_profile
,可获取 ping 会话的不同运行时间数据,如上文代码示例所示。
应用示例
ICMP echo 示例: protocols/icmp_echo
API 参考
Header File
This header file can be included with:
#include "ping/ping_sock.h"
This header file is a part of the API provided by the
lwip
component. To declare that your component depends onlwip
, add the following to your CMakeLists.txt:REQUIRES lwip
or
PRIV_REQUIRES lwip
Functions
-
esp_err_t esp_ping_new_session(const esp_ping_config_t *config, const esp_ping_callbacks_t *cbs, esp_ping_handle_t *hdl_out)
Create a ping session.
- 参数
config -- ping configuration
cbs -- a bunch of callback functions invoked by internal ping task
hdl_out -- handle of ping session
- 返回
ESP_ERR_INVALID_ARG: invalid parameters (e.g. configuration is null, etc)
ESP_ERR_NO_MEM: out of memory
ESP_FAIL: other internal error (e.g. socket error)
ESP_OK: create ping session successfully, user can take the ping handle to do follow-on jobs
-
esp_err_t esp_ping_delete_session(esp_ping_handle_t hdl)
Delete a ping session.
- 参数
hdl -- handle of ping session
- 返回
ESP_ERR_INVALID_ARG: invalid parameters (e.g. ping handle is null, etc)
ESP_OK: delete ping session successfully
-
esp_err_t esp_ping_start(esp_ping_handle_t hdl)
Start the ping session.
- 参数
hdl -- handle of ping session
- 返回
ESP_ERR_INVALID_ARG: invalid parameters (e.g. ping handle is null, etc)
ESP_OK: start ping session successfully
-
esp_err_t esp_ping_stop(esp_ping_handle_t hdl)
Stop the ping session.
- 参数
hdl -- handle of ping session
- 返回
ESP_ERR_INVALID_ARG: invalid parameters (e.g. ping handle is null, etc)
ESP_OK: stop ping session successfully
-
esp_err_t esp_ping_get_profile(esp_ping_handle_t hdl, esp_ping_profile_t profile, void *data, uint32_t size)
Get runtime profile of ping session.
- 参数
hdl -- handle of ping session
profile -- type of profile
data -- profile data
size -- profile data size
- 返回
ESP_ERR_INVALID_ARG: invalid parameters (e.g. ping handle is null, etc)
ESP_ERR_INVALID_SIZE: the actual profile data size doesn't match the "size" parameter
ESP_OK: get profile successfully
Structures
-
struct esp_ping_callbacks_t
Type of "ping" callback functions.
Public Members
-
void *cb_args
arguments for callback functions
-
void (*on_ping_success)(esp_ping_handle_t hdl, void *args)
Invoked by internal ping thread when received ICMP echo reply packet.
-
void (*on_ping_timeout)(esp_ping_handle_t hdl, void *args)
Invoked by internal ping thread when receive ICMP echo reply packet timeout.
-
void (*on_ping_end)(esp_ping_handle_t hdl, void *args)
Invoked by internal ping thread when a ping session is finished.
-
void *cb_args
-
struct esp_ping_config_t
Type of "ping" configuration.
Public Members
-
uint32_t count
A "ping" session contains count procedures
-
uint32_t interval_ms
Milliseconds between each ping procedure
-
uint32_t timeout_ms
Timeout value (in milliseconds) of each ping procedure
-
uint32_t data_size
Size of the data next to ICMP packet header
-
int tos
Type of Service, a field specified in the IP header
-
int ttl
Time to Live,a field specified in the IP header
-
ip_addr_t target_addr
Target IP address, either IPv4 or IPv6
-
uint32_t task_stack_size
Stack size of internal ping task
-
uint32_t task_prio
Priority of internal ping task
-
uint32_t interface
Netif index, interface=0 means NETIF_NO_INDEX
-
uint32_t count
Macros
-
ESP_PING_DEFAULT_CONFIG()
Default ping configuration.
-
ESP_PING_COUNT_INFINITE
Set ping count to zero will ping target infinitely
Type Definitions
-
typedef void *esp_ping_handle_t
Type of "ping" session handle.
Enumerations
-
enum esp_ping_profile_t
Profile of ping session.
Values:
-
enumerator ESP_PING_PROF_SEQNO
Sequence number of a ping procedure
-
enumerator ESP_PING_PROF_TOS
Type of service of a ping procedure
-
enumerator ESP_PING_PROF_TTL
Time to live of a ping procedure
-
enumerator ESP_PING_PROF_REQUEST
Number of request packets sent out
-
enumerator ESP_PING_PROF_REPLY
Number of reply packets received
-
enumerator ESP_PING_PROF_IPADDR
IP address of replied target
-
enumerator ESP_PING_PROF_SIZE
Size of received packet
-
enumerator ESP_PING_PROF_TIMEGAP
Elapsed time between request and reply packet
-
enumerator ESP_PING_PROF_DURATION
Elapsed time of the whole ping session
-
enumerator ESP_PING_PROF_SEQNO