5.1 Lua 脚本编辑器

新版上位机的 Lua 编辑器基于 Monaco（VS Code 用的那个编辑器内核），有自动补全、语法检查、格式化、跳转定义。

Lua 各个库的完整 API 文档在 Lua 编程，这一页只讲编辑器怎么用。

右侧有「AI 助手」面板

不想手写？Lua 编辑器右侧有 AI 助手 面板：用自然语言描述需求，AI 生成 Lua 并一键插入光标处 / 替换整文件。详见 AI 编程助手。

新建 Lua 文件

工程树 → 「Lua 程序」右边的 [+]。

第一个文件必须叫 main.lua

新建第一个 Lua 文件时不会弹输入框，直接创建 main.lua，这是设备启动时执行的入口。之后新建文件才会提示命名（默认 lib.lua）。文件名不带 .lua 后缀时会自动补上。

多个 Lua 文件之间用 require 互相引用，都会一起下载到设备。

编辑器能力

能力	说明
自动补全	输入 plc. mqtt. json. 等会列出该库的所有函数和参数说明
语法检查	写错语法会实时下划线标出
格式化	一键整理缩进和排版
跳转定义	点函数名跳到定义处
查找替换	Ctrl+F（菜单 编辑 → 查找 / 替换 也能触发）

API 参考面板

右侧面板切到 「API」（编辑 Lua 时才显示）：

• 按库分组列出所有可用函数，每项带简短说明
• 可以搜索函数名
• 点击即把调用代码插入编辑器，无需记函数名和参数顺序
• 顶部有 「仅当前设备」 勾选框

「仅当前设备」能少走很多弯路

勾上之后，面板只列当前这台设备真正支持的函数，并提示"已隐藏 N 个不适用函数"。比如选的是不带 4G 的型号，rda8910 相关函数就不显示了。

这避免了一个常见问题：照着完整 API 列表写了代码，下载到设备上才发现这个型号没这个功能。

支持哪些库

设备端 Lua 提供的库，编辑器对它们全都有补全提示：

分类	库
PLC 寄存器	plc
系统与任务	system task thread timer dog（看门狗）
网络	net tcp_client tcp_server udp http mqtt pahomqtt websocketserver
工业协议	modbus modbus_tcp_server mc_server（三菱 MC）
串口协议	com com_modbus com_fx com_dlt645
数据处理	json data ini fdb（FlashDB 持久化）
加密编码	encoder crypto
进程通讯	pipe server_plc
控制与硬件	pid pcnt（脉冲计数）
4G 专用	rda8910

plc 库常用写法

访问软元件有两种写法：

-- 语法糖，直接当变量用
plc.D100 = 1234
local v = plc.D100
if plc.X0 == 1 then plc.Y0 = 1 end

-- 函数式（可以指定长度、类型）
plc.d(100, 1234)          -- 写 D100
local x = plc.d(100)      -- 读 D100

覆盖的软元件：D X Y M S T C R，以及 32 位 / 浮点 / 双精度 / 字符串等变体。

还能读写网络参数（plc.sta_ip plc.eth_ip plc.ap_ssid …）、操作云服务（plc.cloud_bind plc.cloud_publish plc.cloud_subscribe）、远程读写别的 PLC（plc.get / plc.put）。

运行与调试

操作	位置
下载 Lua 到设备	设备工具栏 ⬇ 下载：一键下发全部 Lua 文件并写好启动清单，不需要勾选；完成后重启设备生效
编译并模拟运行（不上设备）	设备工具栏 编译：先检查语法和危险写法，通过后在电脑沙箱里模拟运行；运行中按钮变 ⏹ 停止
在线监视寄存器与 Lua 变量	设备工具栏 监视（见 在线监视与写入变量）
下断点 / 单步调试（不上设备）	调试工具栏 调试运行（见 在线单步调试（调试运行））
看 print 输出和报错	底部 系统输出 面板
看设备端运行日志	底部 LUA日志 面板（每 2 秒拉一次）
看编译 / 模拟运行结果	底部 编译 面板

Lua 程序下载后要重启设备才生效

Lua 程序在其它项都写完之后才写入，写完需要重启设备。用主窗口标题栏的「🔄 重启设备」。

编译并模拟运行（离线，不上设备）

点设备工具栏 编译：

1. 用真实的 Lua 内核做语法检查，并检查危险写法（比如顶层写死循环、长时间不让出控制权的程序，在设备上会让其它功能卡住）
2. 检查通过后，自动在电脑沙箱里模拟运行这段 Lua，输出显示在底部「编译」面板
3. 再点一次（按钮变成 ⏹ 停止）结束模拟运行

沙箱跑通 ≠ 设备没问题

沙箱验证的是语法和程序逻辑。串口、网络这些和真实硬件相关的部分，仍以下到设备后的实测为准。

在线单步调试（调试运行）

调试工具栏的 调试运行（断点直接打在编辑器左侧行号槽）：

1. 用与 ESP32 同一套语义的 C++ 运行库，在电脑内置的软设备上跑当前 Lua —— 不需要连设备
2. 在行号槽点一下设断点；命中后自动停下，底部 调试 面板显示调用栈、局部变量、闭包变量、全局变量，还有一个 Watch 子页可盯任意表达式。回调函数体里也能停：timer.start(1000, function() … end) 这类回调体内打的断点，回调执行到那一行同样会命中
3. 停下后可 继续 / 逐语句 / 逐过程 / 跳出 / 周期单步（周期单步 是 PLC 特有：停在下一次消息泵推进，即推进一个扫描周期）/ 停止 / 重启 / 清断点

调试跑的是「内置软设备」，不是真机

断点、单步看到的值，来自上位机进程内那台软设备（行为对齐 ESP32），和真正下到设备运行是两套环境。它适合写完程序先在自己电脑上验证逻辑、看变量，不必先找一台 PLC。

软设备里的特殊继电器是活的：M8000（运行监视）常 ON；M8011 / M8012 / M8013 / M8014 四个时钟脉冲按 10ms / 100ms / 1s / 1min 自动翻转——想要「每秒跳一次」就读 M8013，即 plc.ms(13)。特殊继电器是 M8000~M8511 这一段、要用 plc.ms(偏移) 访问，写成 plc.M9013 或 plc.m(9013) 都拿不到时钟脉冲（读回来是 nil / 恒 false）。

监视与调试运行互斥（互锁）

调试运行期间，在线监视会自动停用并锁定，两者不能同时进行：

• 点「调试运行」时若正在监视，会先自动停掉监视（底部若停在「监视」页会自动切到「调试」页）
• 调试进行中（运行中 / 已暂停在断点），底部「监视」标签与工具栏「监视」按钮置灰禁用，监视面板显示锁定提示
• 点「停止」结束调试后，监视自动解锁

原因：监视读的是设备 / 模拟器的真实寄存器，调试看的是内置软设备的变量快照，两边数值不是一个来源，同时开着必然互相误导。

在线监视与写入变量

点设备工具栏 监视（未连接设备会提示先在主界面启动软PLC或搜索连接设备），底部切到「监视」面板：

调试运行期间本功能会被锁定

监视与「调试运行」互斥（互锁）：调试进行中，监视标签与按钮置灰不可用，调试停止后自动解锁。原因与细节见 在线单步调试（调试运行）。

子页	用途
监视表	看设备真实寄存器的当前值，可直接改值。点 「提取程序中的地址」 一键扫描代码里 plc.d(100)、plc.Y0 这类写法，全部加进监视表，不用手抄地址
Lua 变量	看正在运行的 Lua 程序内部：按调用链逐层显示局部变量、闭包变量、全局变量。双击值（或点旁边的 ✎）写入新值
强制	把位软元件强制 ON / OFF 或解除，和梯形图编辑器是同一套，见 工作模式与在线监视

两个写变量的入口，效果一样：

• 在代码区右键点变量名 → 「写入变量值…」（弹出框已带当前值，改完确认）
• 在「Lua 变量」子页双击变量值（或点 ✎）

写入是「只写一次」

新值立刻生效，但下一轮循环保留与否由程序自己决定：程序里是 local x = x + 1，写 10 后下回就是 11；程序里是 local x = 0，下回又回到 0。这是写入和「强制」的区别 —— 要持续生效用「强制」子页（仅位软元件）。

值的类型自动判定：能当数字就按数字写，true / false 按布尔写，其余按字符串写。

「Lua 变量」页什么时候有数据

显示的是正在运行的程序里的变量。设备上没跑 Lua 程序、或程序还没执行到收发数据的地方时，可能显示「暂无帧」。提示「设备未上报 Lua 变量段」说明设备固件版本较旧，升级固件后重试。

为不占用通讯口，变量快照只在停在该子页（或监视开启）时刷新，切走就停。

边改边试的最快路径

用软 PLC 模拟器。模拟器支持完整的 Lua 环境（含 socket、MQTT、FlashDB），改完直接在电脑上跑，不用等设备重启，也不怕把现场设备搞挂。

打印和导出

• 文件 → 打印 Lua 程序...
• 文件 → 导出 Lua 文件

这两项要求当前活动标签是 Lua

如果当前在梯形图标签页上点这两项，会提示「请先切换到 Lua 程序标签页再打印」。

示例程序

工程树底部「示例LUA程序」里有一批现成脚本，点击是只读预览，不会写进您的工程。想用就复制粘贴到自己的文件里。

内置示例：lua 基本使用示例、json 示例、mqtt 例程、http 示例、云交互示例、云计算示例、协程示例。