35 icmp-ICMP(PING)协议
一、概述
icmp 是 LuatOS 的 ICMP 协议(PING)核心库,用来对指定 IP 地址发起 ping,判断目标是否可达,并拿到往返耗时(RTT)和 TTL,常用于联网诊断和断网检测。
icmp 库主要功能:
1、setup:为某一路网络适配器初始化 icmp 上下文,必须在网络就绪之后调用;
2、ping:对指定 IP 异步发起一次 ping,第三个参数可以改 ping 包大小(默认 128 字节);
3、debug:打开/关闭 icmp 的底层调试日志,排查收不到应答时用;
4、PING_RESULT:ping 的结果通过 sys 消息 PING_RESULT 发布,订阅后能拿到适配器 id、往返耗时、目标 IP、TTL。
注意事项:
1、ping 的第二个参数必须是 IP 地址,不支持域名;要用域名请先用 socket 的 DNS 接口解析成 IP 再传进来;
2、ping 是异步的,返回值只代表「包有没有发出去」,不代表对方已经应答;真正的结果要订阅 PING_RESULT 或用 sys.waitUntil("PING_RESULT", 超时) 等;
3、setup 和 ping 都要等网络就绪(IP_READY)之后调用,4G 还没联网时调用会失败;
4、本库由编译开关 LUAT_USE_ICMP 控制,用前建议先 if icmp then 自检:icmp 为 nil 说明当前固件没有编入该库。
二、核心示例
2.1 ping 一次并打印结果
sys.taskInit(function()
sys.waitUntil("IP_READY") -- 等网络就绪
sys.wait(1000)
icmp.setup(socket.LWIP_GP) -- 初始化 4G 网络的 icmp
local sent = icmp.ping(socket.LWIP_GP, "121.14.77.221")
log.info("icmp", "包发出去了吗", sent)
-- 等结果,最多等 3 秒
local ok, adapter, time_used, ip, ttl = sys.waitUntil("PING_RESULT", 3000)
if ok then
log.info("icmp", "ping 通", ip, time_used .. "ms", "ttl", ttl)
else
log.info("icmp", "3 秒内没有应答")
end
end)
2.2 循环 ping 做断网检测
sys.subscribe("PING_RESULT", function(adapter, time_used, ip, ttl)
log.info("ping", adapter, time_used, ip, ttl)
end)
sys.taskInit(function()
sys.waitUntil("IP_READY")
icmp.setup(socket.LWIP_GP)
while true do
icmp.ping(socket.LWIP_GP, "223.5.5.5") -- 这里只是示例地址,按实际需要换
sys.waitUntil("PING_RESULT", 3000)
sys.wait(3000)
end
end)
三、函数详解
3.1 icmp.setup(id)
功能
为指定网络适配器初始化 icmp 上下文。初始化之后才能用同一个适配器 id 调 icmp.ping;
通常在 4G / WiFi / 以太网联网成功、收到 IP_READY 之后调用一次即可。
参数
id
参数含义:网络适配器 id;
数据类型:number;
取值范围:socket.LWIP_GP(蜂窝网络)、socket.LWIP_STA / socket.LWIP_AP(WiFi)、socket.LWIP_ETH(以太网)等;
是否必选:必选;
注意事项:必须传正在使用的那路网卡的适配器 id,传错会用不上对应的网络;
参数示例:icmp.setup(socket.LWIP_GP);
返回值
local ok = icmp.setup(id)
ok
含义说明:初始化是否成功;
数据类型:boolean;
取值范围:true 成功,false 失败;
注意事项:失败一般是该适配器还没有可用网络,或者内存不足;
返回示例:true;
示例
sys.waitUntil("IP_READY")
icmp.setup(socket.LWIP_GP)
3.2 icmp.ping(id, ip, len)
功能
向指定 IP 异步发起一次 ping。不阻塞当前协程,结果通过 PING_RESULT 消息返回;
如果该适配器还没有初始化过 icmp,本函数会自己先初始化一次。
参数
id
参数含义:网络适配器 id;
数据类型:number;
取值范围:与 icmp.setup 一致,一般是 socket.LWIP_GP;
是否必选:必选;
注意事项:要和 icmp.setup 用同一个适配器 id;
参数示例:icmp.ping(socket.LWIP_GP, "121.14.77.221");
ip
参数含义:目标 IP 地址;
数据类型:string;
取值范围:点分十进制的 IPv4 地址,如 "121.14.77.221";
是否必选:必选;
注意事项:不支持域名,传域名会解析失败、直接返回且日志打印「目标地址非法」;
参数示例:"121.14.77.221";
len
参数含义:ping 包的数据区长度;
数据类型:number;
取值范围:默认 128,单位字节;
是否必选:可选,不传就是 128;
注意事项:一般不用改;改大只是让报文变大,不影响能否 ping 通;
参数示例:128;
返回值
local sent = icmp.ping(id, ip, len)
sent
含义说明:本次 ping 请求有没有成功发出去;
数据类型:boolean;
取值范围:true 已发出(不一定有应答),false 发送失败;
注意事项:返回 false 一般是 IP 格式不对或该网卡没有可用网络;返回 true 也不能说明对端可达,一定要再等 PING_RESULT;
返回示例:true;
示例
icmp.ping(socket.LWIP_GP, "121.14.77.221")
sys.waitUntil("PING_RESULT", 3000)
3.3 icmp.debug(on)
功能
打开或关闭 icmp 的底层调试日志,排查「包发出去了但一直收不到应答」这类问题时使用。
参数
on
参数含义:调试开关;
数据类型:boolean;
取值范围:true 打开,false 关闭;
是否必选:必选;
注意事项:只是日志开关,不影响 ping 的行为;排查完建议关掉,避免日志过多;
参数示例:icmp.debug(true);
返回值
local cur = icmp.debug(on)
cur
含义说明:设置之后的调试状态;
数据类型:boolean;
取值范围:true 为打开,false 为关闭;
注意事项:无;
返回示例:true;
示例
icmp.debug(true)
icmp.ping(socket.LWIP_GP, "121.14.77.221")
sys.waitUntil("PING_RESULT", 3000)
icmp.debug(false)
四、PING_RESULT 消息
icmp.ping 的结果通过 sys 消息 PING_RESULT 发布,订阅方式与其它 sys 消息一致:
sys.subscribe("PING_RESULT", function(adapter, time_used, ip, ttl)
log.info("icmp", "ping", ip, time_used, ttl)
end)
| 参数位置 | 类型 | 含义 |
|---|---|---|
| 第 1 个 | number | 网络适配器 id,和调用 ping 时传的一致 |
| 第 2 个 | number | 往返耗时,单位 ms |
| 第 3 个 | string | 目标 IP 地址 |
| 第 4 个 | number | TTL 值 |
用 sys.waitUntil 等结果时,第一个返回值是「有没有等到」,后面依次是上面 4 个参数:
local ok, adapter, time_used, ip, ttl = sys.waitUntil("PING_RESULT", 3000)
详细的消息说明见 sys系统消息 - PING_RESULT。
五、产品支持说明
1、本库由编译开关 LUAT_USE_ICMP 控制,在 ec718 系列(Air780EHM/Air780EHV/Air780EGH/Air780EGG/Air780EHU/Air780EHN、Air700ECH、Air8000 系列、Air1780H/Air1780P)和 ec718pm 系列(Air780EPM/Air780EGP)的 BSP 配置里都打开了这个开关,常规固件里可以直接用;
2、Air8101 等其它平台的固件是否编入本库,以对应型号的固件版本页库清单为准;
3、最直接的确认方式:在目标固件里跑 log.info("icmp", icmp),打印出 table 说明库在,打印 nil 说明没编进去;
4、ping 本身要消耗一次联网流量(一个 128 字节的包),做产品级断网检测时注意把间隔放长,不要高频 ping。