Ping as a part of net module

Author: vsky

app/include/user_config.h

@@ -136,6 +136,9 @@
 //#define TIMER_SUSPEND_ENABLE
 //#define PMSLEEP_ENABLE
 
+// The net module optionally offers net info functionnality. Uncomment the following
+// to enable the functionnality.
+//#define NET_INFO_ENABLE 
 
 // The WiFi module optionally offers an enhanced level of WiFi connection
 // management, using internal timer callbacks.  Whilst many Lua developers

app/include/user_modules.h

@@ -39,7 +39,6 @@
 //#define LUA_USE_MODULES_MDNS
 #define LUA_USE_MODULES_MQTT
 #define LUA_USE_MODULES_NET
-//#define LUA_USE_MODULES_NET_INFO
 #define LUA_USE_MODULES_NODE
 #define LUA_USE_MODULES_OW
 //#define LUA_USE_MODULES_PCM

app/modules/net.c

@@ -20,6 +20,8 @@
 #include "lwip/udp.h"
 #include "lwip/dhcp.h"
 
+#include "net_info.h"
+
 typedef enum net_type {
   TYPE_TCP_SERVER = 0,
   TYPE_TCP_CLIENT,
@@ -1070,6 +1072,9 @@ LROT_BEGIN(net, NULL, 0)
   LROT_FUNCENTRY( ifinfo, net_ifinfo )
   LROT_FUNCENTRY( multicastJoin, net_multicastJoin )
   LROT_FUNCENTRY( multicastLeave, net_multicastLeave )
+#ifdef NET_INFO_ENABLE
+  LROT_FUNCENTRY( ping, net_info_ping )
+#endif
   LROT_TABENTRY( dns, net_dns_map )
 #ifdef TLS_MODULE_PRESENT
   LROT_TABENTRY( cert, tls_cert )

app/modules/net_info.c

@@ -5,8 +5,9 @@
 // ***************************************************************************
 
 // #define NODE_DEBUG
-#define LUA_USE_MODULES_NET_INFO
 
+#include "net_info.h"
+
 #include "module.h"
 #include "lauxlib.h"
 
@@ -103,8 +104,8 @@ static void net_info_ping_raw(const char *name, ip_addr_t *ipaddr, ping_t nip) {
     }
 }
 
-// Lua:  net_info.ping(target, [count], responseCB)
-static int net_info_ping(lua_State *L)
+// Lua:  net.ping(domain, [count], callback)
+int net_info_ping(lua_State *L)
 {
     ip_addr_t addr;
 
@@ -118,7 +119,7 @@ static int net_info_ping(lua_State *L)
     ping_t nip = (ping_t) memset(lua_newuserdata(L, sizeof(*nip)), 0, sizeof(*nip));
 
     /* Register C closure with 2 Upvals: (1) Lua CB function; (2) nip Userdata */ 
-    lua_pushcclosure(L, ping_received_sent, 2); // stack has nip UD, responseCB; [-n, +1, m]
+    lua_pushcclosure(L, ping_received_sent, 2); // stack has nip UD, callback; [-n, +1, m]
 
     nip->ping_callback_ref = luaL_ref(L, LUA_REGISTRYINDEX); // registers the closure to registry [-1, +0, m]
     nip->ping_opt.count = l_count;
@@ -127,7 +128,7 @@ static int net_info_ping(lua_State *L)
     nip->ping_opt.sent_function = (ping_sent_function) &ping_CB;
 
     NODE_DBG("[net_info_ping] nip = %p, nip->ping_callback_ref = %p\n", nip, nip->ping_callback_ref);
- 
+
     err_t err = dns_gethostbyname(ping_target, &addr, (dns_found_callback) net_info_ping_raw, nip);
     if (err != ERR_OK && err != ERR_INPROGRESS) {
         luaL_unref(L, LUA_REGISTRYINDEX, nip->ping_callback_ref);
@@ -139,9 +140,3 @@ static int net_info_ping(lua_State *L)
     }
     return 0;
 }
-
-LROT_BEGIN(net_info, NULL, 0)
-  LROT_FUNCENTRY( ping, net_info_ping )
-LROT_END( net_info, NULL, 0 )
-
-NODEMCU_MODULE(NET_INFO, "net_info", net_info, NULL);

app/modules/net_info.h

@@ -0,0 +1,3 @@
+#ifdef NET_INFO_ENABLE
+int net_info_ping(lua_State *L);
+#endif

docs/modules/net.md

@@ -626,6 +626,61 @@ Sets the IP of the DNS server used to resolve hostnames. Default: resolver1.open
 #### See also
 [`net.dns:getdnsserver()`](#netdnsgetdnsserver)
 
+
+### net.ping()
+
+This is a function to ping a server. A callback function is called when response is or is not received.
+
+The function is disabled by default to enable this functionnality define `NET_INFO_ENABLE` macro needs to be defined in `user_config.h`.
+
+#### Syntax
+`net.ping(domain, [count], callback)`
+
+#### Parameters
+- `domain` destination domain or IP address
+- `count` number of ping packets to be sent (optional parameter, default value is 4)
+- `callback(bytes, ipaddr, seqno, rtt)` callback function which is invoked when response is received where
+    - `bytes` number of bytes received from destination server (0 means no response)
+    - `ipaddr` destination serve IP address
+    - `seqno` ICMP sequence number
+    - `rtt` round trip time in ms
+
+If domain name cannot be resolved callback is invoked with `bytes` parameter equal to 0 (i.e. no response) and `nil` values for all other parameters.
+  
+#### Returns
+`nil`
+
+#### Example
+```lua
+net.ping("www.nodemcu.com", function (b, ip, sq, tm) 
+    if ip then print(("%d bytes from %s, icmp_seq=%d time=%dms"):format(b, ip, sq, tm)) else print("Invalid IP address") end 
+  end)
+```
+
+Multiple pings can start in short sequence thought if the new ping overlaps with the previous one the first stops receiving answers, i.e.
+```lua
+function ping_resp(b, ip, sq, tm)
+  print(string.format("%d bytes from %s, icmp_seq=%d time=%dms", b, ip, sq, tm))
+end
+
+net.ping("8.8.8.8", 4, ping_resp)
+tmr.create():alarm(1000, tmr.ALARM_SINGLE, function() net.ping("8.8.4.4", 4, ping_resp) end)
+```
+gives
+```
+32 bytes from 8.8.8.8, icmp_seq=9 time=14ms
+32 bytes from 8.8.8.8, icmp_seq=10 time=9ms
+32 bytes from 8.8.4.4, icmp_seq=11 time=6ms
+32 bytes from 8.8.4.4, icmp_seq=13 time=12ms
+0 bytes from 8.8.8.8, icmp_seq=0 time=0ms
+32 bytes from 8.8.4.4, icmp_seq=15 time=16ms
+0 bytes from 8.8.8.8, icmp_seq=0 time=0ms
+32 bytes from 8.8.4.4, icmp_seq=16 time=7ms
+```
+
+
+
+
 # net.cert Module
 
 This part gone to the [TLS](tls.md) module, link kept for backward compatibility.