32 udpsrv-UDP服务器

作者：王世豪　|　最后修改：2026-03-10

一、概述

udpsrv 是 LuatOS 提供的一个 UDP 服务器扩展库，用于创建和管理 UDP 网络服务。该库允许开发者在设备上创建 UDP 服务器，监听指定端口，实现基于 UDP 协议的网络通信功能。

在 ram 资源足够的情况下：

1、Air780 系列/Air8000 系列的模组，允许创建的同时存在的 udp server 对象数量为 64 个；

2Air8101 系列的模组，允许创建的同时存在的 udp server 对象数量为 32 个；

UDP 协议本身是无连接的，这意味着任何在同一局域网下的客户端都可以向服务器的 IP 和端口发送数据包。

二、核心

核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；
核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；
更加完整和详细的 demo，请参考 LuatOS 仓库中支持充电管理的产品目录下的 demo/socket/server；

function udpsrv_task()
    sys.waitUntil("IP_READY")
    local mytopic = "my_udpsrv"

    -- 创建UDP服务器，监听12345端口
    -- 注意, udpsrv.create有3个参数, 最后一个参数是网络适配器编号
    local udpsrv = udpsrv.create(12345, mytopic)
    -- 若需要在AP监听,则需要指定编号
    -- local udpsrv = udpsrv.create(12345, mytopic, socket.LWIP_AP)

    if udpsrv then
        -- 单播
        udpsrv:send("I am UP", "192.168.1.5", 777)
        -- 广播
        udpsrv:send("I am UP", "255.255.255.255", 777)
        while true do
            -- 等待接收数据，超时时间15秒
            local ret, data, remote_ip, remote_port = sys.waitUntil(mytopic, 15000)
            if ret then
                log.info("udpsrv", "收到数据", data:toHex(), remote_ip, remote_port)
                -- 按业务处理收到的数据
            else
                log.info("udpsrv", "没数据,那广播一条")
                udpsrv:send("I am UP", "255.255.255.255", 777)
            end
        end
    else
        log.info("udpsrv", "启动失败")
    end
    -- 如果关闭,调用
    -- udpsrv:close()
end

sys.taskInit(udpsrv_task)

三、常量详解

核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；
udpsrv 扩展库本身没有定义常量，但在创建 UDP 服务器时可使用 socket 核心库中的网络适配器类型常量。

四、函数详解

4.1 udpsrv.create(port, topic, adapter)

功能

创建 UDP 服务器并开始监听指定端口；

注意事项

1、创建 UDP 服务器前需要确保网络已就绪（"IP_READY"）；

2、若需要在 AP/STA/ETH 监听，则需要指定适配器编号；

AP 模式（Access Point）：

在此模式下，设备作为一个 WiFi 热点，允许其他设备连接到此热点。
当设备作为 TCP/UDP 服务器时，它会在热点的 IP 地址上监听端口。其他连接到该热点的设备可以作为客户端连接到此服务器。

STA 模式（Station）：

在此模式下，设备连接到现有的 WiFi 网络，作为该网络的一个站点。
设备作为 TCP/UDP 服务器时，它会使用从路由器获取的 IP 地址（或静态 IP）来监听端口。同一网络下的其他设备可以通过这个 IP 和端口连接到此服务器。

ETH 模式（Ethernet）：

在此模式下，设备通过有线以太网连接网络。
设备作为 TCP/UDP 服务器时，使用有线网络分配的 IP 地址（或静态 IP）来监听端口。通过有线网络可达的设备可以连接到此服务器。

3、创建的 UDP 服务器可以通过 sys.waitUntil 接收数据，接收到的数据会通过指定的 topic 传递；

参数

port

含义说明：UDP服务器监听的端口号；
数值类型：number；
取值范围：0-65525；
是否必选：是；
注意事项：端口号不能和其他服务冲突；
参数示例：udpsrv.create(12345, "my_topic")

topic

含义说明：接收UDP数据的消息主题；
数值类型：string；
取值范围：任意有效的字符串；
是否必选：是；
注意事项：该topic用于通过sys.waitUntil接收数据；
参数示例：udpsrv.create(12345, "my_topic")

adapter

含义说明：网络适配器编号；
数值类型：number；
取值范围：可选值为[socket 核心库](https://docs.openluat.com/osapi/core/socket/)中的网络适配器类型常量；
是否必选：否；
注意事项：默认为nil，使用默认网络适配器；
参数示例：-- 默认
         udpsrv.create(12345, "my_topic")
         -- 使用socket.LWIP_AP
         udpsrv.create(12345, "my_topic"，socket.LWIP_AP)

返回值

local udpsrv_object = udpsrv.create(port, topic, adapter)

udpsrv_object

含义说明：UDP服务器对象；
数据类型：table；
取值范围：成功返回table对象，失败返回nil；
注意事项：返回的对象具有send和close等方法；
返回示例：成功返回table对象：table: 0C7F56F0
         失败返回：nil

示例

-- 创建UDP服务器监听12345端口
 local udpsrv = udpsrv.create(12345, "udp_topic")
 if udpsrv then
     log.info("udpsrv", "服务器创建成功")
     -- 发送广播消息
     udpsrv:send("Hello", "255.255.255.255", 8888)
 else
     log.info("udpsrv", "服务器创建失败")
 end

4.1 udpsrv:send(data, ip, port)

功能

通过 UDP 服务器发送数据到指定地址。

注意事项

此方法只能在 UDP 服务器创建成功后调用，确保 udpsrv 已经创建成功（非 nil）；

udpsrv:send(data, ip, port) 的 udpsrv 是通过 udpsrv.create()接口创建后，返回的 UDP 服务器对象；

支持单播和广播两种发送方式；

广播发送时，IP 地址应设置为"255.255.255.255"；

参数

data

含义说明：要发送的数据内容；
数值类型：string；
取值范围: 0-1460字节；
是否必选：是；
注意事项：无；
参数示例：udpsrv:send("I am UP", "192.168.3.23", 50000)

ip

含义说明：目标IP地址
数值类型：string；
取值范围：合法的IPv4地址格式；
是否必选：是；
注意事项：支持单播地址和广播地址
参数示例：udp_srv:send("Hello Server", "192.168.1.100", 8888) --单播
         udp_srv:send("Broadcast Message", "255.255.255.255", 9999) --广播

port

含义说明：目标端口号；
数值类型：number；
取值范围：0-65535；
是否必选：是；
注意事项：目标端口号必须与接收方监听的端口一致
参数示例：udp_srv:send("Hello Server", "192.168.1.100", 8888) --目标端口号为8888

返回值

local result = udpsrv:send(data, ip, port)

result

含义说明：是否成功执行发送操作；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示协议栈已经执行了数据发送动作；
         false表示出现错误，没有执行数据发送动作；
返回示例：-- 单播发送数据
         local result = udpsrv:send("Hello Server", "192.168.1.100", 8888)
         log.info("是否成功执行发送动作", result)

示例

-- 单播发送数据
local result = udpsrv:send("Hello Server", "192.168.1.100", 8888)
if not result then
    log.info("数据发送动作执行失败")
end

-- 广播发送数据
local result = udpsrv:send("Broadcast Message", "255.255.255.255", 9999)
if not result then
    log.info("数据发送动作执行失败")
end

4.1 udpsrv:close()

功能

关闭 UDP 服务器，释放相关资源；

注意事项

此方法只能在 UDP 服务器创建成功后调用，确保 udpsrv 已经创建成功（非 nil）；

udpsrv:close() 的 udpsrv 是通过 udpsrv.create()接口创建后，返回的 UDP 服务器对象；

关闭后，UDP 服务器将停止监听端口，无法再通过该服务器发送或接收数据；

参数

无

返回值

无

示例

-- 创建UDP服务器监听12345端口
local udpsrv = udpsrv.create(12345, "udp_topic")
-- 使用服务器进行通信
...
-- 关闭服务器
udpsrv:close()

五、产品支持说明

支持 LuatOS 开发的所有产品都支持 udpsrv 扩展库。