主题
Lua 编程指南
LPPLC 设备内置 Lua 5.4 脚本引擎，可与 PLC 梯形图协同运行。本文档覆盖设备真实支持的所有 Lua 模块 API。
快速开始
首次使用 LPPLC 的 Lua 功能时，推荐按以下顺序阅读：
- Lua 概述 — 了解 Lua 在设备中的定位
- 基础语法 — 变量、运算符、字符串
- 第一个 Lua 脚本 — 从零跑通一个脚本
- 定时器 — 最常用的功能：定时采集数据
- 后台任务与事件 — 需要"一直跑、中间还要等"时用它们
- PLC 数据交互 — 读写 D/M/X/Y 寄存器
编写脚本前建议先阅读 并发模型概述：脚本运行在单线程事件循环中，理解这一点可以避免多数「定时器不准」「回调不触发」类问题。
模块总览
以下是设备固件真实注册的全部 Lua 模块（按使用场景分类）：
系统与核心
| 模块 | 说明 | 链接 |
|---|---|---|
system | 重启、延时、文件系统操作 | 系统功能 |
timer | 创建周期/单次定时器 | 定时器 |
task | 后台任务：一段代码在后台一直跑、中间还能等 | 后台任务 |
event | 事件订阅与发布：任务与回调之间互通消息 | 事件订阅与发布 |
plc | 读写 PLC 寄存器(X/Y/M/D/R/T/C)、网络配置、云平台 | PLC 数据交互 |
coroutine | 协程，把「多步 + 等待」写成顺序代码 | 协程 |
网络通信（socket 与 IT 协议）
| 模块 | 说明 | 链接 |
|---|---|---|
mqtt | MQTT 客户端，连接 Broker 发布订阅 | MQTT 客户端 |
http | HTTP 客户端，GET/POST 同步异步 | HTTP 客户端 |
tcp_client | TCP 客户端连接 | TCP 客户端 |
tcp_server | TCP 服务器监听 | TCP 服务器 |
udp | UDP 数据收发 | UDP 通信 |
net | 底层 Socket、Ping、DNS、NTP | 网络工具 |
websocketserver | WebSocket 服务器 | WebSocket |
串口基础
| 模块 | 说明 | 链接 |
|---|---|---|
com | 打开物理串口，直接收发字节流，或作为父设备挂载协议子设备 | 串口基础 |
自动轮询采集（配好通道，后台线程采到寄存器）
| 模块 | 说明 | 链接 |
|---|---|---|
com_modbus | Modbus RTU / ASCII 主站（挂在 com 上） | Modbus RTU |
com_fx | 三菱 FX 编程口（挂在 com 上） | 三菱 FX 编程口 |
com_dlt645 | DL/T 645 电表，只读（挂在 com 上） | DL/T 645 电表 |
modbus | Modbus TCP 主站，独立轮询线程 | Modbus TCP |
按需读写 · Pipe 统一接口
| 模块 | 说明 | 链接 |
|---|---|---|
pipe | 一套接口读写多品牌 PLC，调一次发一帧同步等回复（Modbus TCP/RTU、三菱 MC/FX、FINS、S7、台达、信捷、汇川） | Pipe 通信概述 |
做从站（其他设备读取本机）
| 模块 | 说明 | 链接 |
|---|---|---|
mc_server | 三菱 MC 协议从站服务器 | MC 协议服务器 |
modbus_tcp_server | Modbus TCP 从站服务器 | Modbus TCP 服务器 |
楼宇与 OT 协议（同一模块兼主从两种角色）
| 模块 | 说明 | 链接 |
|---|---|---|
bacnet | BACnet 楼宇自控，MS/TP（串口）与 BACnet/IP（以太网）仅 ESP32-S3 / 模拟器 | BACnet |
opcua | OPC UA（opc.tcp）服务端与客户端 仅 ESP32-S3 / 模拟器 | OPC UA |
water | 水务遥测终端，SZY206-2016 / SL/T 427 仅 ESP32-S3 / 模拟器 | 水务遥测 |
数据处理与专业功能
| 模块 | 说明 | 链接 |
|---|---|---|
encoder | Base64/Hex 编解码 | 编码转换 |
crypto | ⚠ 当前版本未注册，不可调用（AES 只有 plc.aes_encode） | 加密模块 |
data | 共享数据缓冲（lpchar 类型） | 共享变量 |
json | JSON 编解码 | JSON |
pid | PID 闭环控制 | PID 控制 |
fdb | FlashDB 键值/时序数据库 | 数据存储 |
ini | INI 配置文件读写 | INI 配置 |
pcnt | 硬件脉冲计数器/编码器 | 脉冲计数 |
云平台
| 模块 | 说明 | 链接 |
|---|---|---|
plc.cloud_* | 云平台绑定、发布、订阅、计算 | 云平台通信 |
标准库
设备同时提供 Lua 标准库（精简版）：
| 库 | 说明 | 链接 |
|---|---|---|
| 基础库 | print/type/tonumber/tostring/pcall 等 | 基础库 |
| string | 字符串操作 | 字符串库 |
| table | 表操作 | 表库 |
| math | 数学函数 | 数学库 |
| os | 时间日期、文件删除/重命名 | 操作系统库 |
| coroutine | 协程 | 协程 |
| utf8 | UTF-8 支持 | — |
| debug | 调试 | — |
常用代码片段
lua
-- 每 2 秒读取 D100 温度并上传到云平台
timer.start(2000, function()
local temp = plc.d(100) -- 读 D100
plc.cloud_publish("temperature", temp)
end)lua
-- MQTT 连接并订阅（mqtt.xxx(client, ...) 与 client:xxx(...) 写法等价）
c = mqtt.creat("broker.example.com", 1883, "device01", "", "")
mqtt.reg(c, mqtt.RECVDATA, function(topic, data)
print("收到: " .. topic .. " = " .. data)
end)
mqtt.reg(c, mqtt.CONNECTED, function()
mqtt.subscribe(c, "cmd/device01", 0)
end)
c:start()lua
-- 串口 Modbus RTU 读温度传感器：从站 1 的 40001 → D100
port = com.setup(1, 9600, com.NONE, 8, 1)
dev = com_modbus.creat(com_modbus.RTU, 1)
dev:add_channel(400001, com_modbus.S16, 100, com_modbus.READ)
port:add_device(dev)
port:start()