Lua 脚本编程

Lua 脚本是 LPPLC 平台的核心差异化能力。梯形图负责控制逻辑，Lua 负责通信与数据处理，使传统 PLC 具备工业物联网网关能力。

Lua 在本机上承担什么

本机内置 Lua 5.4 脚本引擎，联网与数据处理这部分工作可用少量脚本代码完成，无需外挂设备：

能力项	常规实现方式	本机 Lua 实现方式
云平台对接	另配 DTU / 网关	内置 MQTT/HTTP，直连云平台
多品牌 PLC 通讯	另配协议转换器	统一 Pipe API，主流工业协议即插即用
数据处理	通常在上位侧处理	Lua 可直接处理 JSON、字符串与数学运算
多任务并发	依平台而定	线程 + 定时器 + 协程三种机制
二次开发	通常需厂商定制	用户自行编写脚本，在线下载即用
学习成本	—	语法简洁，学习周期短

核心能力一览

1. PLC 数据无缝交互

Lua 通过 plc 模块直接读写 PLC 内部寄存器，与梯形图程序共享数据。支持两种写法：

属性式写法（推荐，所有系列均支持）：

plc.D100 = 0         -- 写 D100 = 0
local val = plc.D100  -- 读 D100
local x0 = plc.X0     -- 读 X0
plc.Y0 = true         -- 置位 Y0
plc.M100 = false      -- 复位 M100

属性式写法支持的区号只有 D / X / Y / M / S / T / C / TS / CS / R（16 位与位软元件）。

32 位与浮点没有属性式写法

plc.DD100、plc.DF200 这种写法读出来是 nil、写进去没反应，而且不报错。32 位整数与浮点数必须用下面的函数式写法：

plc.dd(100, 100000)        -- 写 32 位整数到 D100/D101
local total = plc.dd(100)  -- 读
plc.df(200, 25.5)          -- 写浮点数到 D200/D201
local temp = plc.df(200)   -- 读

函数式写法（所有系列通用）：

plc.d(100, 0)      -- 写 D100 = 0
local val = plc.d(100)  -- 读 D100
plc.x(0)            -- 读 X0
plc.m(0, 1)         -- 置位 M0
local temp = plc.df(200)  -- 读浮点数 DF200

支持的寄存器类型：

属性名	寄存器	类型	范围
plc.D0	数据寄存器	int16	0-7999
plc.dd(0)	32位寄存器	int32	只有函数式写法
plc.df(0)	浮点寄存器	float	只有函数式写法
plc.X0	输入继电器	bool	0-255（八进制）
plc.Y0	输出继电器	bool	0-255（八进制）
plc.M0	辅助继电器	bool	0-7679
plc.S0	状态继电器	bool	0-4095
plc.T0	定时器当前值	int16	0-511
plc.TS0	定时器触点	bool	0-511
plc.C0	计数器当前值	int16/int32	0-255
plc.CS0	计数器触点	bool	0-255
plc.R0	扩展寄存器	int16	0-32767

X/Y 寄存器编号为八进制，如 plc.X10 指十进制编号 8 的输入点（八进制 10 = 十进制 8）。

2. 统一工业协议库（Pipe）

一套 API 适配各种工业协议，切换协议只需修改协议名参数：

local pipe = require("pipe")

-- Modbus TCP
device = pipe.setup("modbus.tcp", { slave=1, ip="192.168.1.100", port=502 })

-- 换成西门子 S7，只需改协议名
device = pipe.setup("siemens.smart", { ip="192.168.1.200", rack=0, slot=1 })

-- 读写操作完全一样
local result = device:read_u16("D1000", 3)
device:write_float("D2000", 3.14)

协议	目标设备
Modbus TCP/RTU/ASCII	任何 Modbus 设备
三菱 MC 协议	FX/Q/L 系列
西门子 S7 (SMART/1200/1500/300/200)	S7 全系列
欧姆龙 FINS	CP/CJ 系列
台达 / 汇川 / 信捷	国产 PLC

3. 丰富的网络通信栈

能力	模块	用途
MQTT 客户端	mqtt	物联网消息，发布/订阅
HTTP 客户端	http	REST API 调用，同步/异步
TCP 客户端/服务端	tcp_client / tcp_server	双向 TCP 通信
UDP	udp	无连接数据传输
WebSocket	ws	实时双向通信
网络工具	net	DNS、Ping、NTP、IP 操作

4. 串口通信协议

协议	用途
UART	通用串口收发
Modbus RTU	串行 Modbus
三菱 FX 协议	FX 系列串口通信
DLT645	电表协议

5. PLC 作为从站

LPPLC 可以作为被控设备，被上位机/SCADA 系统通过标准协议读写：

• MC 协议服务端：作为三菱 MC 从站
• Modbus TCP 服务端：作为 Modbus 从站
• BACnet/IP 从站 与 OPC UA 服务端：见下一节（仅 ESP32-S3 机型和软 PLC 模拟器）

6. 楼宇与 OT 协议（主从双角色）

BACnet 和 OPC UA 各由一个模块同时提供主站与从站能力，仅 ESP32-S3 机型和软 PLC 模拟器支持：

协议	传输	做从站 / 服务端	做主站 / 客户端
BACnet	MS/TP（RS-485）与 BACnet/IP（UDP 47808）	寄存器包装成 AI/AO/AV/BI/BO/BV/MSI/MSO/MSV 对象给 BMS 采集，可写对象支持 16 级优先级	按周期读别的 BACnet 设备，值落进寄存器
OPC UA	opc.tcp（以太网）	寄存器做成变量节点，组态软件可读写、可订阅	主动读别人的 OPC UA 服务器

两者都需要与上位系统在同一网段（不支持 BBMD 跨子网）；OPC UA 当前只提供 SecurityPolicy None，可配用户名 / 密码，暂不支持证书加密。详见 BACnet 楼宇自控 与 OPC UA。

7. 云平台一键对接

通过 cloud_bind 一行代码绑定寄存器到云端，自动上传/下发：

plc.cloud_bind({
    {name = "temperature", reg = "D100", type = plc.FLOAT, mode = plc.CLOUD_UP},
    {name = "start",       reg = "Y0",   type = plc.BITE,  mode = plc.CLOUD_DOWN}
})

支持三种模式：CLOUD_UP（本地上云）、CLOUD_DOWN（云控本地）、CLOUD_AUTO（双向）。

8. 三种并发机制

机制	特点	适用场景
线程 (Thread)	抢占式，独立 Lua 状态机	CPU 密集、需要真正并行
定时器 (Timer)	事件驱动，最小 10ms	周期性采集、心跳
协程任务 (Task)	轻量协作式，事件驱动	生产者-消费者、异步流程

9. 专业工业功能

• PID 控制器：内置 PID 算法，支持自整定
• FlashDB：掉电保存的键值存储，支持时序数据
• INI 配置：读写 INI 配置文件
• AES 加密：内置加解密
• RTC 时钟：实时时钟管理

开发方式

1. 浏览器访问 PLC 的 Web 管理页面
2. 在线编写 Lua 脚本
3. 一键下载运行，在线查看日志
4. 三种写法：注册定时器与事件回调（推荐，脚本注册完即可结束，固件自动泵消息）、协程（把多步等待写成顺序代码）、任务（task.start 起后台任务，一直跑、中间还能等）—— 无论哪种，都不要在主线程里写 while true do ... sleep ... end，详见并发模型概述

典型应用场景

• 工业物联网网关：采集多品牌 PLC 数据，统一上云
• 协议转换器：Modbus ↔ 西门子 ↔ 三菱，自由转换
• 远程监控：MQTT 上报设备状态，HTTP 调用云端 API
• 数据采集终端：串口/网口采集传感器数据，本地存储 + 定时上报
• 边缘计算：本地 PID 控制、数据过滤、报警判断

---

相关例程

想直接抄可运行的脚本，去 例程总览 B-0：按模块分组列出了每个页面里的 3 个完整例程（场景 / 代码 / 要点 / 验证 / 注意事项）。

• 通信：com 串口 · tcp_server · mqtt · pipe 概述 · net
• 云与数据：cloud · json · data · fdb
• 综合工程：Modbus 采集 + MQTT 上报 + 云端下发

写例程的硬规矩（禁止阻塞主循环、API 不编造等）见 B-0 的「写例程时的硬性约定」。