1ICMP Echo
2=========
3
4Overview
5--------
6
7ICMP (Internet Control Message Protocol) is used for diagnostic or control purposes or generated in response to errors in IP operations. The common network util ``ping`` is implemented based on the ICMP packets with the type field value of 0, also called ``Echo Reply``.
8
9During a ping session, the source host firstly sends out an ICMP echo request packet and wait for an ICMP echo reply with specific times. In this way, it also measures the round-trip time for the messages. After receiving a valid ICMP echo reply, the source host will generate statistics about the IP link layer (e.g. packet loss, elapsed time, etc).
10
11It is common that IoT device needs to check whether a remote server is alive or not. The device should show the warnings to users when it got offline. It can be achieved by creating a ping session and sending/parsing ICMP echo packets periodically.
12
13To make this internal procedure much easier for users, ESP-IDF provides some out-of-box APIs.
14
15Create a new ping session
16^^^^^^^^^^^^^^^^^^^^^^^^^
17
18To create a ping session, you need to fill in the ``esp_ping_config_t`` configuration structure firstly, specifying target IP address, interval times, and etc. Optionally, you can also register some callback functions with the `esp_ping_callbacks_t`` structure.
19
20Example method to create a new ping session and register callbacks:
21
22.. highlight:: c
23
24::
25
26    static void test_on_ping_success(esp_ping_handle_t hdl, void *args)
27    {
28        // optionally, get callback arguments
29        // const char* str = (const char*) args;
30        // printf("%s\r\n", str); // "foo"
31        uint8_t ttl;
32        uint16_t seqno;
33        uint32_t elapsed_time, recv_len;
34        ip_addr_t target_addr;
35        esp_ping_get_profile(hdl, ESP_PING_PROF_SEQNO, &seqno, sizeof(seqno));
36        esp_ping_get_profile(hdl, ESP_PING_PROF_TTL, &ttl, sizeof(ttl));
37        esp_ping_get_profile(hdl, ESP_PING_PROF_IPADDR, &target_addr, sizeof(target_addr));
38        esp_ping_get_profile(hdl, ESP_PING_PROF_SIZE, &recv_len, sizeof(recv_len));
39        esp_ping_get_profile(hdl, ESP_PING_PROF_TIMEGAP, &elapsed_time, sizeof(elapsed_time));
40        printf("%d bytes from %s icmp_seq=%d ttl=%d time=%d ms\n",
41               recv_len, inet_ntoa(target_addr.u_addr.ip4), seqno, ttl, elapsed_time);
42    }
43
44    static void test_on_ping_timeout(esp_ping_handle_t hdl, void *args)
45    {
46        uint16_t seqno;
47        ip_addr_t target_addr;
48        esp_ping_get_profile(hdl, ESP_PING_PROF_SEQNO, &seqno, sizeof(seqno));
49        esp_ping_get_profile(hdl, ESP_PING_PROF_IPADDR, &target_addr, sizeof(target_addr));
50        printf("From %s icmp_seq=%d timeout\n", inet_ntoa(target_addr.u_addr.ip4), seqno);
51    }
52
53    static void test_on_ping_end(esp_ping_handle_t hdl, void *args)
54    {
55        uint32_t transmitted;
56        uint32_t received;
57        uint32_t total_time_ms;
58
59        esp_ping_get_profile(hdl, ESP_PING_PROF_REQUEST, &transmitted, sizeof(transmitted));
60        esp_ping_get_profile(hdl, ESP_PING_PROF_REPLY, &received, sizeof(received));
61        esp_ping_get_profile(hdl, ESP_PING_PROF_DURATION, &total_time_ms, sizeof(total_time_ms));
62        printf("%d packets transmitted, %d received, time %dms\n", transmitted, received, total_time_ms);
63    }
64
65    void initialize_ping()
66    {
67        /* convert URL to IP address */
68        ip_addr_t target_addr;
69        struct addrinfo hint;
70        struct addrinfo *res = NULL;
71        memset(&hint, 0, sizeof(hint));
72        memset(&target_addr, 0, sizeof(target_addr));
73        getaddrinfo("www.espressif.com", NULL, &hint, &res);
74        struct in_addr addr4 = ((struct sockaddr_in *) (res->ai_addr))->sin_addr;
75        inet_addr_to_ip4addr(ip_2_ip4(&target_addr), &addr4);
76        freeaddrinfo(res);
77
78        esp_ping_config_t ping_config = ESP_PING_DEFAULT_CONFIG();
79        ping_config.target_addr = target_addr;          // target IP address
80        ping_config.count = ESP_PING_COUNT_INFINITE;    // ping in infinite mode, esp_ping_stop can stop it
81
82        /* set callback functions */
83        esp_ping_callbacks_t cbs;
84        cbs.on_ping_success = test_on_ping_success;
85        cbs.on_ping_timeout = test_on_ping_timeout;
86        cbs.on_ping_end = test_on_ping_end;
87        cbs.cb_args = "foo";  // arguments that will feed to all callback functions, can be NULL
88        cbs.cb_args = eth_event_group;
89
90        esp_ping_handle_t ping;
91        esp_ping_new_session(&ping_config, &cbs, &ping);
92    }
93
94Start and Stop ping session
95^^^^^^^^^^^^^^^^^^^^^^^^^^^
96
97You can start and stop ping session with the handle returned by ``esp_ping_new_session``. Note that, the ping session won't start automatically after creation. If the ping session is stopped, and restart again, the sequence number in ICMP packets will recount from zero again.
98
99
100Delete a ping session
101^^^^^^^^^^^^^^^^^^^^^
102
103If a ping session won't be used any more, you can delete it with ``esp_ping_delete_session``. Please make sure the ping session is in stop state (i.e. you have called ``esp_ping_stop`` before or the ping session has finished all the procedures) when you call this function.
104
105
106Get runtime statistics
107^^^^^^^^^^^^^^^^^^^^^^
108
109As the example code above, you can call ``esp_ping_get_profile`` to get different runtime statistics of ping session in the callback function.
110
111
112Application Example
113-------------------
114
115ICMP echo example: :example:`protocols/icmp_echo`
116
117API Reference
118-------------
119
120.. include-build-file:: inc/ping_sock.inc
121
122
123