主题
Lua 库总表
设备上能被脚本调用的全部 Lua 库：共 50 个库、413 个库级函数 + 161 个对象方法。
有没有、叫什么、在哪个机型能用，以本页为准； 参数怎么填、返回什么、怎么用，点进各库页看。同一个库在不同机型上的可调用集合并不相同，「可用机型」只写"哪里有"。
- 签名怎么读：括号内按顺序列全参数，方括号里的可以省略（不传就走默认值），
...表示还可继续传同类参数；参数位上写的是类型名（integer整数、string字符串、table表…）表示该处要传这个类型的值。各库页尾部的「函数速查表」直接给出每个函数的完整签名，如com.setup(com_num, [baud, parity, databits, stopbits])= 最少传 1 个、最多 5 个。 - 两种调用形态：
plc.get(...)这类库级函数直接点调用；先拿回对象的要冒号调用方法（h:read_u16(...)），h就是拿回的对象。
逐函数的调用形态与机型可用性另见 D. API 全集与机型可用性。
| 库 | 作用 | 函数 | 方法 | 常量 | 库页 | 可用机型 |
|---|---|---|---|---|---|---|
base | 内建基础函数库（print、pcall、type 等） | 24 | 0 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
string | 字符串处理库（格式化、查找、替换、匹配） | 19 | 0 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
table | 表库（插入、删除、排序、拼接） | 8 | 0 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
math | 数学库 | 35 | 0 | 4 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
io | 文件与流 I/O 库（4G 真机与模拟器/上位机可用；ESP32 真机里 io 为 nil） | 11 | 0 | 0 | 去 | 软 PLC 模拟器 / 上位机 · 4G 机型 |
os | 操作系统库（时间、日期、文件名分隔等） | 11 | 0 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
system | 系统功能 | 7 | 0 | 1 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
timer | 定时器 | 2 | 1 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
task | 后台任务（与 event 配套，见 3.4 / 3.5） | 3 | 0 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
event | 事件订阅与发布（与 task 配套，见 3.5） | 6 | 0 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
coroutine | 协程库（本项目协作式多任务的基石） | 8 | 0 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
plc | PLC 数据交互 | 61 | 0 | 10 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
http | HTTP 客户端 | 6 | 5 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
mqtt | MQTT 客户端 | 10 | 9 | 6 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
tcp_client | TCP 客户端 | 8 | 7 | 3 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
tcp_server | TCP 服务器 | 5 | 4 | 3 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 |
net | 网络工具 | 24 | 14 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
udp | UDP 通信 | 4 | 3 | 1 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
websocketserver | WebSocket 服务器 | 1 | 0 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 |
com | 串口通信 | 11 | 10 | 3 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
com_modbus | 串口 Modbus 主站 | 8 | 7 | 22 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
com_fx | 串口三菱 FX 协议 | 4 | 3 | 16 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
com_dlt645 | DLT645 电表 | 4 | 3 | 35 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
modbus | Modbus TCP 主站（自动轮询） | 12 | 11 | 19 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
pipe | 统一管道通信 | 1 | 18 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 |
mc_server | 三菱 MC 协议从站服务器 | 1 | 0 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 |
modbus_tcp_server | Modbus TCP 从站服务器 | 1 | 0 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 |
bacnet | BACnet 楼宇自控（MS/TP 与 BACnet/IP） | 1 | 15 | 14 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机（仅 ESP32-S3） |
opcua | OPC UA | 1 | 14 | 21 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机（仅 ESP32-S3） |
water | 水务遥测（SZY206-2016 / SL/T 427） | 1 | 11 | 23 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机（仅 ESP32-S3） |
pid | PID 闭环控制 | 7 | 6 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
encoder | 编码转换 | 6 | 0 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
crypto | 加密模块 | 9 | 0 | 4 | 去 | ESP32 机型 |
data | 共享数据对象 | 4 | 4 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
json | JSON 编解码 | 2 | 0 | 2 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
fdb | 数据存储 | 7 | 0 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 |
ini | INI 配置文件 | 11 | 0 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 |
bit32 | 32 位位运算库（Lua 自带扩展） | 12 | 0 | 0 | 去 | ESP32 机型 |
com2 | 模拟器第二串口通道库（设备固件无此库） | 8 | 0 | 3 | 去 | 软 PLC 模拟器 / 上位机 |
com2_dlt645 | 模拟器第二串口上的 DLT645 电表 | 1 | 0 | 11 | 去 | 软 PLC 模拟器 / 上位机 |
com2_fx | 模拟器第二串口上的三菱 FX 协议 | 1 | 0 | 6 | 去 | 软 PLC 模拟器 / 上位机 |
com2_modbus | 模拟器第二串口上的 Modbus 主站 | 2 | 0 | 14 | 去 | 软 PLC 模拟器 / 上位机 |
debug | 调试库（Lua 自带，正式脚本慎用） | 17 | 0 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
dog | 看门狗库（仅模拟器/上位机） | 1 | 9 | 0 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 |
miniz | 压缩与解压库（仅软 PLC 模拟器 / 上位机，设备固件里没注册） | 2 | 0 | 0 | 去 | 软 PLC 模拟器 / 上位机 |
package | 包与模块加载库（require 的底层） | 8 | 0 | 3 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
pahomqtt | Paho 风格 MQTT 兼容库（仅模拟器/上位机） | 1 | 5 | 6 | 去 | 软 PLC 模拟器 / 上位机 |
thread | 线程库（仅模拟器/上位机） | 6 | 2 | 0 | 去 | 软 PLC 模拟器 / 上位机 |
utf8 | UTF-8 字符处理库（Lua 自带） | 6 | 0 | 1 | 去 | ESP32 机型 · 软 PLC 模拟器 / 上位机 · 4G 机型 |
xml | XML 解析库（仅软 PLC 模拟器 / 上位机，设备固件里没注册） | 4 | 0 | 0 | 去 | 软 PLC 模拟器 / 上位机 |
「4G 机型」指哪几台：LP8910 / LP8913 / LP8916 / LP8922（RDA8910 平台，见 3.4 LP8910）。这一列在 2026-10-10 之前只写了 ESP32 机型与模拟器， 所以 4G 的客户在这张「以本页为准」的表里查不到自己有什么库 —— 现已逐库按 4G 固件的库注册表补齐； 判"某台机器上有没有这个库"，看的都是那台机器固件里的注册表，不是磁盘上有没有对应的源文件。
4G 机型上的 net 与 ESP32 差三处（写脚本前先看这条，否则同一份程序烧进 4G 会踩空）：
| 差异 | 表现 | 怎么办 |
|---|---|---|
少 net.ping_stats | 上面 24 个函数在 4G 上是 23 个（ping_stats 只在 DEBUG 构建里注册） | 那条本来也不是给客户用的，忽略 |
net.localip 恒返回 nil | 4G 的出口地址是运营商现场分配的，机器上没有"网口"可查 | 要拿本机地址：net.socket 连一个外网地址后用 sock:sockname() |
setoption 没有组播三个分支 | multicast_join / multicast_ttl / multicast_loop 在 4G 上返回错误码 | 组播/广播是局域网的事，4G 上用不了；跨网段发现设备请改用「平台侧下发」或 tcp_client |
另有一条不是差异而是前提：4G 上的套接字总额度只有 8 个，且与云服务、MQTT、HTTP 用的是同一份池子， 所以 net.socket 一次开太多会把云连接一起挤掉（返回错误码，不报错崩溃）。 逐函数的说明见 net — 网络工具。
只有模拟器与上位机有的两个库（xml、miniz）：下表里它们的「可用机型」只写 「软 PLC 模拟器 / 上位机」—— 设备固件里没注册这两个名字，同一句脚本烧进真机会取到 nil。 在模拟器里先验通解析/压缩逻辑没问题，要上设备就得换写法。 调用形态、参数边界与实测过的失败形状见 附录 F 内建扩展与模拟器专有库。