跳转至

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。

搜索