Netdrv

作者：魏健强　|　最后修改：2026-04-30

一、概述

netdrv 是指网络设备，用于初始化并管理不同的网络设备。如：4G,以太网，WIFI。还可以提供路由功能.把各种联网方式融合起来,如：4G 连接外部网络,支持以太网 lan 模式为其他以太网设备提供接入。exnetif 扩展库对 netdrv 做了进一步封装可以查看详细的 api 文档；

支持指定任意一个 netdrv 作为外网访问的出口，使用本文的 netdrv 和 exnetif 扩展库的流程对比，推荐使用 exnetif 扩展库实现，使用更简单

如：通过以太网访问外网时，使用 netdrv 和 exnetif 的流程参考下图

支持设置路由功能，如：4G 连接外部网络,支持以太网 lan 模式为其他以太网设备提供接入，使用本文的 netdrv 和 exnetif 扩展库的流程对比,推荐使用 exnetif 扩展库实现，使用更简单

本文中提到的网卡、网络适配器，网络设备，均为同一概念，如："4G 网卡"等同于"4G 网络适配器"。

二、准备硬件环境

Air780EPM V1.3 开发板一块 +TYPE-C USB 数据线一根 + 可上网的 sim 卡一张 +4g 天线一根 + 网线一根：

sim 卡插入开发板的 sim 卡槽
天线装到开发板上

2、网线接线说明：

netdrv_eth_wan 模块以太网口接路由器 LAN 口或交换机
netdrv_eth_lan 模块以太网口接电脑或需要上网的设备
netdrv_4g_multiple 模块以太网口接电脑或需要上网的设备
netdrv_eth_multiple 模块以太网 WAN 接路由器 LAN 口或交换机,AirETH_1000 配件板 LAN 口接需要上网的设备
AirETH_1000 配件板接到开发板上可以用电脑接 AirETH_1000 配件板网口

3、TYPE-C USB 数据线一根 Air780EPM 开发板和数据线的硬件接线方式为：

TYPE-C USB 数据线直接插到核心板的 TYPE-C USB 座子，另外一端连接电脑 USB 口；

三、准备软件环境

3.1 文章内容应用

烧录工具：Luatools 工具
本demo开发测试时使用的固件为Air780EPM V2016 版本固件，本demo对固件版本没有什么特殊要求，所以你如果要测试本demo时，可以直接使用最新版本的内核固件Air780EPM固件，Air780EHM固件；如果发现最新版本的内核固件测试有问题，可以使用我们开发本demo时使用的内核固件版本来对比测试。
脚本文件：https://gitee.com/openLuat/LuatOS/tree/master/module/Air780EPM/demo/netdrv
LuatOS 运行所需要的 lib 文件：使用 Luatools 烧录时，勾选添加默认 lib 选项，使用默认 lib 脚本文件。
准备好软件环境之后，接下来查看如何烧录项目文件到 Air780EPM 开发板，将本篇文章中演示使用的项目文件烧录到 Air780EPM 开发板中。

3.2 API 介绍

本文仅介绍程序中使用到的 API 接口，详细接口说明请查看：netdrv 核心库。

四、实现功能概述

main.lua：主程序入口；
netdrv_eth_wan.lua：以太网 wan
netdrv_eth_lan.lua：以太网 lan
netdrv_4g_multiple.lua：4G 连接外部网络，生成 WiFi 热点为 WiFi 终端设备提供接入，支持以太网 lan 模式为其他以太网设备提供接入
netdrv_eth_multiple.lua：以太网连接外部网络,生成 WiFi 热点为 WiFi 终端设备提供接入

4.1 运行流程图

参考第一章节中的流程图

4.2 代码示例

netdrv_eth_wan.lua

--[[
@module  netdrv_eth_wan
@summary “通过SPI外挂CH390H芯片的以太网卡”驱动模块 
@version 1.0
@date    2025.10.20
@author  魏健强
@usage
本文件为“通过SPI外挂CH390H芯片的以太网卡”驱动模块 ，核心业务逻辑为：
1、开启以太网wan；

直接使用Air780EPM V1.3开发板硬件测试即可；

本文件没有对外接口，直接在其他功能模块中require "netdrv_eth_wan"就可以加载运行；
]] 
local static_ip = false

local function ip_ready_func(ip, adapter)
    if adapter == socket.LWIP_ETH then
        -- 在位置1和2设置自定义的DNS服务器ip地址：
        -- "223.5.5.5"，这个DNS服务器IP地址是阿里云提供的DNS服务器IP地址；
        -- "114.114.114.114"，这个DNS服务器IP地址是国内通用的DNS服务器IP地址；
        -- 可以加上以下两行代码，在自动获取的DNS服务器工作不稳定的情况下，这两个新增的DNS服务器会使DNS服务更加稳定可靠；
        -- 如果使用专网卡，不要使用这两行代码；
        -- 如果使用国外的网络，不要使用这两行代码；
        socket.setDNS(adapter, 1, "223.5.5.5")
        socket.setDNS(adapter, 2, "114.114.114.114")

        log.info("netdrv_eth_wan.ip_ready_func", "IP_READY", socket.localIP(socket.LWIP_ETH))
    end
end

local function ip_lose_func(adapter)
    if adapter == socket.LWIP_ETH then
        log.warn("netdrv_eth_wan.ip_lose_func", "IP_LOSE")
    end
end

-- 本功能在2025.9.3新增
local function ping_test()
    -- 要等联网了才能ping
    sys.waitUntil("IP_READY")
    while 1 do
        -- 必须指定使用哪个网卡
        netdrv.ping(socket.LWIP_ETH, "112.125.89.8")
        sys.waitUntil("PING_RESULT", 3000)
        sys.wait(3000)
    end
end
local function ping_res(id, time, dst)
    log.info("ping", id, time, dst); -- 获取到响应结果
end

-- 以太网联网成功（成功连接路由器，并且获取到了IP地址）后，内核固件会产生一个"IP_READY"消息
-- 各个功能模块可以订阅"IP_READY"消息实时处理以太网联网成功的事件
-- 也可以在任何时刻调用socket.adapter(socket.LWIP_ETH)来获取以太网是否连接成功

-- 以太网断网后，内核固件会产生一个"IP_LOSE"消息
-- 各个功能模块可以订阅"IP_LOSE"消息实时处理以太网断网的事件
-- 也可以在任何时刻调用socket.adapter(socket.LWIP_ETH)来获取以太网是否连接成功

-- 此处订阅"IP_READY"和"IP_LOSE"两种消息
-- 在消息的处理函数中，仅仅打印了一些信息，便于实时观察“通过SPI外挂CH390H芯片的以太网卡”的连接状态
-- 也可以根据自己的项目需求，在消息处理函数中增加自己的业务逻辑控制，例如可以在连网状态发生改变时更新网络图标
sys.subscribe("IP_READY", ip_ready_func)
sys.subscribe("IP_LOSE", ip_lose_func)

local function eth_wan_setup()
    -- 本demo使用Air8000开发板测试，开发板上的硬件配置为：
    -- GPIO140为CH390H以太网芯片的供电使能控制引脚
    -- 使用spi1，片选引脚使用GPIO12
    -- 如果使用的硬件不是Air8000开发板，根据自己的硬件配置修改以下参数
    log.info("ch390", "打开LDO供电")
    gpio.setup(20, 1, gpio.PULLUP) -- 打开ch390供电
    local result = spi.setup(0, -- spi_id
    nil, 0, -- CPHA
    0, -- CPOL
    8, -- 数据宽度
    25600000 -- ,--频率
    -- spi.MSB,--高低位顺序    可选，默认高位在前
    -- spi.master,--主模式     可选，默认主
    -- spi.full--全双工       可选，默认全双工
    )
    log.info("main", "open", result)
    if result ~= 0 then -- 返回值为0，表示打开成功
        log.info("main", "spi open error", result)
        return
    end
    -- 初始化指定netdrv设备,
    -- socket.LWIP_ETH 网络适配器编号
    -- netdrv.CH390外挂CH390
    -- SPI ID 1, 片选 GPIO12, 中断引脚 GPIO222
    netdrv.setup(socket.LWIP_ETH, netdrv.CH390, {
        spi = 0,
        cs = 8,
        irq = 22
    })
    sys.wait(1000) -- 等待以太网模块初始化完成,去掉会导致以太网初始化失败
    if static_ip then
        -- 静态ip配置
        log.info("静态ip", netdrv.ipv4(socket.LWIP_ETH, "192.168.4.100", "255.255.255.0", "192.168.4.1"))
    else
        -- 使用dhcp动态获取ip地址
        netdrv.dhcp(socket.LWIP_ETH, true)
    end
    log.info("LWIP_ETH", "mac addr", netdrv.mac(socket.LWIP_ETH))
    sys.taskInit(ping_test)
    sys.subscribe("PING_RESULT", ping_res)
end

local function http_test()
    -- sys.waitUntil("IP_READY")
    while 1 do
        sys.wait(6000)
        log.info("http", http.request("GET", "http://httpbin.air32.cn/bytes/4096", nil, nil, {
            adapter = socket.LWIP_ETH
        }).wait()) -- adapter指定为以太网联网方式
        log.info("lua", rtos.meminfo())
        log.info("sys", rtos.meminfo("sys"))
    end
end
sys.taskInit(eth_wan_setup)
sys.taskInit(http_test)

netdrv_eth_multiple.lua

--[[
@module  netdrv_4g_multiple
@summary 多网卡（4G网卡、通过SPI外挂CH390H芯片的以太网卡）驱动模块 
@version 1.0
@date    2025.10.20
@author  魏健强
@usage
本文件为多网卡驱动模块 ，核心业务逻辑为：
1、4G连接外部网络，以太网lan模式为其他以太网设备提供接入 ；

直接使用Air780EPM V1.3开发板硬件测试即可；

本文件没有对外接口，直接在其他功能模块中require "netdrv_4g_multiple"就可以加载运行；
]] 
dhcpsrv = require "dhcpsrv"
dnsproxy = require "dnsproxy"

local function lte_eth_setup()
    log.info("ch390", "打开LDO供电")
    gpio.setup(20, 1, gpio.PULLUP) -- 打开ch390供电
    local result = spi.setup(0, -- spi_id
    nil, 0, -- CPHA
    0, -- CPOL
    8, -- 数据宽度
    25600000 -- ,--频率
    )
    log.info("main", "open", result)
    if result ~= 0 then -- 返回值为0，表示打开成功
        log.info("main", "spi open error", result)
        return
    end
    -- 初始化指定netdrv设备,
    -- socket.LWIP_ETH 网络适配器编号
    -- netdrv.CH390外挂CH390
    -- SPI ID 1, 片选 GPIO12, 中断引脚 GPIO22
    netdrv.setup(socket.LWIP_ETH, netdrv.CH390, {
        spi = 0,
        cs = 8,
        irq = 22
    })
    -- 确保ch390初始化完成,否则会出现netdrv.ipv4设置失败的情况
    sys.wait(1000)
    -- 设置ip, 子网掩码，网关
    local ipv4, mark, gw = netdrv.ipv4(socket.LWIP_ETH, "192.168.4.1", "255.255.255.0", "192.168.4.1")
    log.info("LWIP_ETH", ipv4, mark, gw)
    -- 开启dhcp服务器
    dhcpsrv.create({adapter = socket.LWIP_ETH})
    -- 设置dns转发
    dnsproxy.setup(socket.LWIP_ETH, socket.LWIP_GP)
end


local function netdrv_multiple_task_func()
    -- 等待4G网络连接成功
    while not socket.adapter() do
        -- 在此处阻塞等待4G网卡连接成功的消息"IP_READY"
        -- 或者等待1秒超时退出阻塞等待状态;
        -- 注意：此处的1000毫秒超时不要修改的更长；
        sys.waitUntil("IP_READY", 1000)
    end
    -- 开启4G->以太网的多网融合
    lte_eth_setup()
    -- 设置4G为数据出口
    netdrv.napt(socket.LWIP_GP)
end

-- 启动一个task，task的处理函数为netdrv_multiple_task_func
sys.taskInit(netdrv_multiple_task_func)

netdrv_eth_lan.lua

--[[
@module  netdrv_eth_lan
@summary “通过SPI外挂CH390H芯片的以太网卡”驱动模块 
@version 1.0
@date    2025.10.20
@author  魏健强
@usage
本文件为“通过SPI外挂CH390H芯片的以太网卡”驱动模块 ，核心业务逻辑为：
1、开启以太网lan；

直接使用Air780EPM V1.3开发板硬件测试即可；

本文件没有对外接口，直接在其他功能模块中require "netdrv_eth_lan"就可以加载运行；
]] 
dhcps = require "dhcpsrv"

local function eth_lan_setup()
    -- 本demo使用Air8000开发板测试，开发板上的硬件配置为：
    -- GPIO140为CH390H以太网芯片的供电使能控制引脚
    -- 使用spi1，片选引脚使用GPIO12
    -- 如果使用的硬件不是Air8000开发板，根据自己的硬件配置修改以下参数
    log.info("ch390", "打开LDO供电")
    gpio.setup(20, 1, gpio.PULLUP) -- 打开ch390供电
    local result = spi.setup(0, -- spi_id
    nil, 0, -- CPHA
    0, -- CPOL
    8, -- 数据宽度
    25600000 -- ,--频率
    )
    log.info("main", "open", result)
    if result ~= 0 then -- 返回值为0，表示打开成功
        log.info("main", "spi open error", result)
        return
    end

    -- 初始化指定netdrv设备,
    -- socket.LWIP_ETH 网络适配器编号
    -- netdrv.CH390外挂CH390
    -- SPI ID 1, 片选 GPIO12, 中断引脚 GPIO22
    netdrv.setup(socket.LWIP_ETH, netdrv.CH390, {
        spi = 0,
        cs = 8,
        irq = 22
    })
    -- 确保ch390初始化完成,否则会出现netdrv.ipv4设置失败的情况
    sys.wait(1000)
    -- 设置ip, 子网掩码，网关
    local ipv4, mark, gw = netdrv.ipv4(socket.LWIP_ETH, "192.168.4.1", "255.255.255.0", "192.168.4.1")
    log.info("ipv4", ipv4, mark, gw)
    -- 开启dhcp服务器
    dhcps.create({
        adapter = socket.LWIP_ETH
    })
end

sys.taskInit(eth_lan_setup)

netdrv_4g_multiple.lua

--[[
@module  netdrv_4g_multiple
@summary 多网卡（4G网卡、通过SPI外挂CH390H芯片的以太网卡）驱动模块 
@version 1.0
@date    2025.10.20
@author  魏健强
@usage
本文件为多网卡驱动模块 ，核心业务逻辑为：
1、4G连接外部网络，以太网lan模式为其他以太网设备提供接入 ；

直接使用Air780EPM V1.3开发板硬件测试即可；

本文件没有对外接口，直接在其他功能模块中require "netdrv_4g_multiple"就可以加载运行；
]] 
dhcpsrv = require "dhcpsrv"
dnsproxy = require "dnsproxy"

local function lte_eth_setup()
    log.info("ch390", "打开LDO供电")
    gpio.setup(20, 1, gpio.PULLUP) -- 打开ch390供电
    local result = spi.setup(0, -- spi_id
    nil, 0, -- CPHA
    0, -- CPOL
    8, -- 数据宽度
    25600000 -- ,--频率
    )
    log.info("main", "open", result)
    if result ~= 0 then -- 返回值为0，表示打开成功
        log.info("main", "spi open error", result)
        return
    end
    -- 初始化指定netdrv设备,
    -- socket.LWIP_ETH 网络适配器编号
    -- netdrv.CH390外挂CH390
    -- SPI ID 1, 片选 GPIO12, 中断引脚 GPIO22
    netdrv.setup(socket.LWIP_ETH, netdrv.CH390, {
        spi = 0,
        cs = 8,
        irq = 22
    })
    -- 确保ch390初始化完成,否则会出现netdrv.ipv4设置失败的情况
    sys.wait(1000)
    -- 设置ip, 子网掩码，网关
    local ipv4, mark, gw = netdrv.ipv4(socket.LWIP_ETH, "192.168.4.1", "255.255.255.0", "192.168.4.1")
    log.info("LWIP_ETH", ipv4, mark, gw)
    -- 开启dhcp服务器
    dhcpsrv.create({adapter = socket.LWIP_ETH})
    -- 设置dns转发
    dnsproxy.setup(socket.LWIP_ETH, socket.LWIP_GP)
end


local function netdrv_multiple_task_func()
    -- 等待4G网络连接成功
    while not socket.adapter() do
        -- 在此处阻塞等待4G网卡连接成功的消息"IP_READY"
        -- 或者等待1秒超时退出阻塞等待状态;
        -- 注意：此处的1000毫秒超时不要修改的更长；
        sys.waitUntil("IP_READY", 1000)
    end
    -- 开启4G->以太网的多网融合
    lte_eth_setup()
    -- 设置4G为数据出口
    netdrv.napt(socket.LWIP_GP)
end

-- 启动一个task，task的处理函数为netdrv_multiple_task_func
sys.taskInit(netdrv_multiple_task_func)

main.lua

--[[
@module  main
@summary LuatOS用户应用脚本文件入口，总体调度应用逻辑 
@version 1.0
@date    2025.10.20
@author  魏健强
@usage
本demo演示的核心功能为：
1.开启以太网功能
2.开启多网融合功能
更多说明参考本目录下的readme.md文件
]]
--[[
必须定义PROJECT和VERSION变量，Luatools工具会用到这两个变量，远程升级功能也会用到这两个变量
PROJECT：项目名，ascii string类型
        可以随便定义，只要不使用,就行
VERSION：项目版本号，ascii string类型
        如果使用合宙iot.openluat.com进行远程升级，必须按照"XXX.YYY.ZZZ"三段格式定义：
            X、Y、Z各表示1位数字，三个X表示的数字可以相同，也可以不同，同理三个Y和三个Z表示的数字也是可以相同，可以不同
            因为历史原因，YYY这三位数字必须存在，但是没有任何用处，可以一直写为999
        如果不使用合宙iot.openluat.com进行远程升级，根据自己项目的需求，自定义格式即可
]]
PROJECT = "netdrv"
VERSION = "001.999.000"


-- 在日志中打印项目名和项目版本号
log.info("main", PROJECT, VERSION)




-- 如果内核固件支持errDump功能，此处进行配置，【强烈建议打开此处的注释】
-- 因为此功能模块可以记录并且上传脚本在运行过程中出现的语法错误或者其他自定义的错误信息，可以初步分析一些设备运行异常的问题
-- 以下代码是最基本的用法，更复杂的用法可以详细阅读API说明文档
-- 启动errDump日志存储并且上传功能，600秒上传一次
-- if errDump then
--     errDump.config(true, 600)
-- end


-- 使用LuatOS开发的任何一个项目，都强烈建议使用远程升级FOTA功能
-- 可以使用合宙的iot.openluat.com平台进行远程升级
-- 也可以使用客户自己搭建的平台进行远程升级
-- 远程升级的详细用法，可以参考fota的demo进行使用


-- 启动一个循环定时器
-- 每隔3秒钟打印一次总内存，实时的已使用内存，历史最高的已使用内存情况
-- 方便分析内存使用是否有异常
-- sys.timerLoopStart(function()
--     log.info("mem.lua", rtos.meminfo())
--     log.info("mem.sys", rtos.meminfo("sys"))
-- end, 3000)


-- 开启以太网wan
-- require "netdrv_eth_wan"
-- 开启以太网lan
-- require "netdrv_eth_lan"
-- 4G连接外部网络，支持以太网lan模式为其他以太网设备提供接入 
-- require "netdrv_4g_multiple"
-- 双网口模式，以太网wan连接外部网络,以太网lan口为其他以太网设备提供接入
require "netdrv_eth_multiple"


-- 用户代码已结束---------------------------------------------
-- 结尾总是这一句
sys.run()
-- sys.run()之后后面不要加任何语句!!!!!

五、功能演示

如果需要开启以太网 lan，打开 require "netdrv_eth_lan"，其余注释掉

模块以太网接口接其他设备，这里演示使用电脑连接，可以 dhcp 获取 ip，可以 ping 通模块

如果需要开启以太网 wan，打开 require "netdrv_eth_wan"，其余注释掉模块以太网口接路由器，模块成功联网并 http 请求成功

如果需要开启 4G 转以太网的多网融合，打开 require "netdrv_4g_multiple"，其余注释掉

4G 作为数据出口，需要上网的设备连接模块以太网接口上网

如果需要开启以太网转 wifi 的多网融合，打开 require "netdrv_eth_multiple.lua"，其余注释掉

模块以太网 WAN 接路由器 LAN 口或交换机,这里使用电脑连接模块以太网 LAN，dhcp 获取到 ip，测试网络正常

六、总结

至此，使用 netdrv+dnsproxy+dhcpsrv 演示的单网卡初始化和多网融合的功能已经结束。如果大家在实际操作中遇到技术难题，欢迎联系合宙技术人员。