API 速查表

全部模块函数的索引。点模块名进对应章节看完整参数说明。带 obj: 前缀的是对象方法，模块. 前缀的是库级函数。

system — 系统功能

函数	作用
system.restart()	重启设备
system.sleep(ms)	延时。主线程里不推进消息泵，期间回调全部收不到；任务/协程内是让出。周期任务请用 timer.start
system.fs_info([path])	文件系统容量信息

| system.fs_list(path) | 列出目录 | | system.fs_exists(path) | 判断路径是否存在 |

timer — 定时器

函数	作用
timer.start(ms, cb, [once])	创建并启动定时器
timer.stop(t) / t:stop()	停止并销毁定时器

coroutine — 协程

函数	作用
coroutine.create(fn)	创建协程
coroutine.resume(co, [...])	恢复运行
coroutine.yield([...])	让出
coroutine.status(co)	查询状态
coroutine.wrap(fn)	包装成可调用函数
coroutine.isyieldable()	是否可让出
coroutine.running()	当前协程
coroutine.close(co)	关闭协程

plc — PLC 数据交互

位软元件

函数	作用
plc.x(n, [v])	X 输入
plc.y(n, [v])	Y 输出
plc.m(n, [v])	M 辅助继电器
plc.ms(n, [v])	M8000+ 特殊继电器
plc.s(n, [v])	S 状态
plc.ts(n, [v])	定时器触点
plc.cs(n, [v])	计数器触点

字软元件

函数	作用
plc.d(n, [v])	D 寄存器 16 位
plc.dd(n, [v])	D 寄存器 32 位
plc.df(n, [v])	D 寄存器浮点
plc.dstr(n, [v])	D 寄存器字符串
plc.ds/dsd/dsf(n [, v])	D8000+ 特殊寄存器 16/32/浮点
plc.tn(n, [v])	定时器当前值
plc.cn(n, [v])	计数器当前值
plc.r/rd/rf/rstr(n [, v])	R 文件寄存器 16/32/浮点/字符串

网络配置（读写省略参数即读）

函数	作用
plc.sta_dhcp/eth_dhcp([v])	STA / 以太网 DHCP 开关
plc.sta_ip/ap_ip/eth_ip([v])	各接口 IP
plc.sta_mask/ap_mask/eth_mask([v])	子网掩码
plc.sta_gateway/ap_gateway/eth_gateway([v])	网关
plc.sta_ssid/sta_password([v])	STA 连接的 WiFi
plc.ap_ssid/ap_password([v])	本机 AP 热点

工具与安全

函数	作用
plc.led(v)	LED（0 灭 / 1 亮 / 其它自动）
plc.bite(data, bit, [val])	整数按位读写
plc.rtc_set(...)	设置 RTC
plc.sta_autochn([v])	STA 自动切换信道
plc.plc_name([name])	设备名
plc.plc_password(hex)	PLC 密码
plc.lua_password(str)	Lua 下载密码
plc.kv_set(key, data) / plc.kv_get(key)	掉电保存的键值
plc.base64_encode/decode(str)	Base64
plc.aes_encode/decode(str)	AES
plc.get(ip, raddr, laddr, len)	远程读对方 D 区
plc.put(ip, raddr, laddr, len)	远程写对方 D 区
plc.AI(value 或 cmd_table)	多用途入口：普通值做类型转换，带 cmd 的 table 执行内置命令（echo / ShowMe / set / config），详见 plc.AI

云平台通信 — cloud_*

函数	作用
plc.cloud_bind(table)	绑定上下行数据点
plc.cloud_reg(type, cb)	注册云事件回调
plc.cloud_publish(k, v, ...)	主动上报
plc.cloud_subscribe(n, ...)	订阅下发
plc.cloud_compute(json)	让云服务器执行任务（发邮件等）

http — HTTP 客户端

函数	作用
http.creat(url, [ip])	创建客户端对象
http.get(url, [ip])	一次性同步 GET
http.post(url, body, [ip])	一次性同步 POST
c:add_head(name, val)	加请求头
c:get([ip]) / c:post(body, [ip])	对象模式同步请求
c:get_asy(url, cb, [ip])	异步 GET
c:post_asy(url, body, cb, [ip])	异步 POST

mqtt — MQTT 客户端

除 start 和 set_keepalive 外，全部要写成 mqtt.xxx(client, ...)，不能用 client:xxx()。

函数	作用
mqtt.creat(url, port, id, user, pass)	创建客户端
mqtt.set_version(client, ver)	协议版本
mqtt.set_keepalive(client, sec)	KeepAlive
mqtt.set_cleansession(client, v)	CleanSession
mqtt.reg(client, type, cb)	注册事件回调
mqtt.start(client)	启动连接
mqtt.publish(client, topic, payload, [qos, retain])	发布
mqtt.subscribe(client, topic, qos, ...)	批量订阅
mqtt.unsubscribe(client, topic, ...)	批量取消订阅（2026-08-16 之前的固件调用会抛错）
mqtt.is_linked(client)	连接状态

tcp_client — TCP 客户端

函数	作用
tcp_client.creat(ip, port, [local_ip])	创建客户端
c:start()	启动连接
c:send(data)	发送
c:set_timeout(ms)	超时
c:close()	关闭
c:is_linked()	连接状态（整数）
c:set_transparent(...)	透传绑定
c:reg(type, cb)	注册回调

tcp_server — TCP 服务器

函数	作用
tcp_server.creat([port, max, buf])	创建服务器（默认 5000/1/1024）
s:start()	启动监听
s:send(sock, data)	发给指定连接
s:close(sock)	断开指定连接
s:reg(type, cb)	注册回调

udp — UDP 通信

函数	作用
udp.creat(port, ip)	创建 UDP 对象（两参都必填）
u:start()	启动
u:send(...)	发送
u:close()	关闭
u:reg(type, cb)	注册回调

websocketserver — WebSocket 服务器

函数	作用
websocketserver.creat([port])	创建并自动启动（默认 80）

net — 网络工具

函数	作用
net.socket(type)	创建 socket，返回句柄（不是数字，失败是 nil）
sock:bind([ip, port])	绑定本地 ip:port（服务器必填 port）
sock:listen([backlog])	开始监听（TCP 服务器）
sock:accept([timeout])	接受客户端连接（可反复调用，多客户端）
sock:connect(ip, port, [timeout])	连接 / 设定 UDP 默认目标
sock:send(data, [ip, port])	发送
sock:sendto(data, ip, port)	UDP 发到指定地址
sock:recv(size_or_line)	接收（TCP / 已设目标的 UDP）
sock:recvfrom([maxsize])	接收并带回发件人地址（UDP 服务器）
net.select({sock, ...}, [timeout])	等一批 socket 就绪（多客户端并发）
sock:peer() / sock:sockname()	对端 / 本机 ip:port
sock:setoption(option, ...)	唯一的选项入口：超时 / keepalive / nodelay / reuseaddr / broadcast
sock:close()	关闭（忘了也会在回收时自动关）
net.packip(...) / net.unpackip(ip, fmt)	IP 与整数互转
net.lookup(host)	DNS 解析
net.localip(iface, [fmt])	本机 IP（STA=0 / AP=1 / ETH=2）
net.errstr(err)	错误码转中文
net.ping(...)	Ping
net.get_ntp_time_async(...)	异步对时

net.send(sock, ...) 与 sock:send(...) 两种写法都行，挑一种用到底。设备一共只有 16 个 socket。

com — 串口基础

函数	作用
com.setup(port, baud, parity, databits, stopbits)	打开串口
p:send(data)	发送
p:recv(...)	接收
p:print(...)	格式化发送
p:reg(type, cb)	注册回调
p:set_timeout(ms)	接收超时
p:set_time_lunxun(ms)	轮询间隔
p:add_device(dev)	挂载协议从站对象
p:set_transparent(...)	透传绑定
p:start()	启动轮询
p:close()	关闭串口

com_modbus — 串口 Modbus 主站

函数	作用
com_modbus.creat(mode, addr, [status])	创建从站对象
d:add_channel(...)	加通道（4 参或 5 参形式）
d:set_16_ab/set_32_abcd/set_float_abcd/set_double_abcdefgh(order)	字节序（四者各自独立，只对同类型通道生效：16→S16/U16、32→S32/U32、float→FLOAT、double→DOUBLE）
d:set_time_recv(ms) / d:set_time_error(ms)	超时与重试延时

com_fx — 三菱 FX 协议

函数	作用
com_fx.creat(...)	创建从站对象
d:add_channel(dev_name, type, target, rw)	加通道（软元件用字符串如 "D0"）
d:set_time_recv(ms) / d:set_time_error(ms)	超时与重试延时

com_dlt645 — DLT645 电表

函数	作用
com_dlt645.creat(...)	创建电表对象
d:add_channel(item, target)	加数据项通道（只读协议）
d:set_time_recv(ms) / d:set_time_error(ms)	超时与重试延时

bacnet — BACnet 楼宇自控

仅 ESP32-S3 固件和软 PLC 模拟器支持，其他机型上没有 bacnet 模块。模拟器的 MS/TP 时序不保证，只能验逻辑。

dest 参数：MS/TP 传数字 MAC（1~127），BACnet/IP 传 IP 字符串（'192.168.1.50'）。

函数	作用
bacnet.creat(cfg)	创建节点。link='mstp'（com/baud/mac/max_master/reply_delay_ms）或 link='ip'（port/ifname）
node:add_object(addr, mode, var, [access, name, opt])	从站：把寄存器暴露成 BACnet 对象
node:add_poll(dest, addr, mode, var, [opt])	主站：周期读别人的点（interval/fail_flag/on_change）
node:del_object(addr) / node:del_poll(dest, addr)	删点。只能在 start() 之前调，运行中返回 0
node:start() / node:close()	启停。MS/TP 占用/释放串口（固定 8N1）；IP 开/关 UDP 套接字
node:read(dest, addr, [count]) / node:read_prop(dest, addr, prop)	同步读，返回 {errno, data}。会阻塞，生产用 add_poll
node:write(dest, addr, value, [prio]) / node:release(dest, addr, [prio])	写 / 释放优先级槽
node:who_is()	广播 Who-Is 并列出已发现设备（异步，要调两次；IP 下给 ip 字段）
node:object_list(dest, [device, max])	枚举对方有哪些点。要先 who_is()，且会阻塞很久
node:stat() / node:is_online()	通讯质量（含 max_reply_ms，IP 下多个 ip）/ 离线窗 MS/TP 5s、IP 60s
node:reg(event, cb)	bacnet.WRITE(addr,value,prio,effective) / ONLINE() / OFFLINE() / ERROR(code,addr)

opcua — OPC UA

ESP32-S3 固件与软 PLC 模拟器支持；普通 ESP32 因 1536K app 分区放不下 open62541 而不支持。服务端和客户端是两个独立对象，用 mode 区分，方法不通用。

地址写法：服务端 id 填标识符本身（'Boiler1.Temp'，会拼成 ns=2;s=...，每段 [A-Za-z_][A-Za-z0-9_]*、. 分段最多 3 段）；客户端 addr 填对方的完整 NodeId（'ns=2;s=Tank.Level' / 'ns=3;i=1001'）。

函数	作用
opcua.creat(cfg)	创建节点。mode='server'（port/ifname/app_name/app_uri/ns_uri/anonymous/user/password/max_sessions/pub_interval_min）或 mode='client'（url/timeout/retries/sub）
node:add_node(id, mode, var, [access, name, opt])	服务端：把寄存器暴露成 OPC UA 变量。opt={unit,desc,min,max}，量程要 min/max 都给
node:del_node(id) / node:add_folder(id, [name])	删节点 / 给目录起中文名（带 . 的层级会自动建目录，通常不用调）
node:add_poll(addr, mode, var, [opt])	客户端：周期采集（interval/access/deadband/fail_flag/on_change）
node:del_poll(addr)	删采集点
node:read(addr|{addr,...} [, mode]) / node:write(addr, value, [mode])	同步读写，返回 {errno,data} / errno。会阻塞，生产用 add_poll
node:browse([id, max])	列出对方节点：{errno, data={ {id,name,class,type_id} }}。只做一层，会阻塞
node:session_list()	服务端：当前会话 { {name,user,items,up_ms} }。name 是 sessionName，拿不到对方 IP
node:start() / node:close()	启停。服务端在这里绑端口；客户端连接是异步的，看 is_online()
node:stat() / node:is_online()	通讯质量（last_err 是原始 32 位 UA_StatusCode，排查现场看它；服务端多 sessions/monitored_items，客户端多 reconnects/sub_active）/ 服务端 60s 离线窗、客户端看 Session
node:reg(event, cb)	opcua.WRITE(id,value) / SESSION(up,name,user) / ONLINE() / OFFLINE() / ERROR(code,addr)。采集点变化走 add_poll 的 on_change(addr,value)

数据类型：opcua.BOOLEAN（别名 BITE）/ S16 / U16 / S32 / U32 / FLOAT / DOUBLE / STRING（只能绑 data.creat() 变量）。 权限：opcua.READ / READ_WRITE / WRITE_ONLY。 错误码 8701~8713，上限：节点 256、目录 32、会话 4、采集点 128。

water — 水务遥测

仅 ESP32-S3 固件与软 PLC 模拟器。一个设备只允许一个节点。定位常供电站点：不做低功耗、没有 RTC，时钟未同步不采集不上报。配置必须在 start() 之前做完。

函数	作用
water.creat(cfg)	创建节点。version/addr_mode/region/station/hydro_code/password/keepalive/retry/ack_timeout/backfill_gap/total_save_interval + 子表 report{mode,offset,interval,period_min} / store{enable,days,max_kb} / clock{ntp_enable,ntp_hosts,ntp_interval,jump_alarm,flash_interval,center_time_first} + on_offline/on_clock_bad
node:add_center(cfg)	增加中心站，最多 4 个。{ip,port,proto,primary,need_ack}，主站只能一个
node:add_element(code, cfg)	绑要素，最多 16 个。{reg,type,scale,offset,invalid}，type='float' 时忽略 scale
node:add_alarm(code, cfg)	越限加报，最多 16 个。{high,low,mode,deadband,min_gap}，high/low 键在不在表示启不启用
node:start() / node:close()	启停
node:is_online([idx])	第 idx 个中心站是否在线，不传参查主站
node:report_now() / node:sync_time()	立刻上报一次 / 立刻发起 NTP 对时。失败返回 false,"原因"
node:preview(kind)	生成一帧十六进制文本但不发送：'report' / 'keepalive' / 'settime'
node:stat()	clock_quality(0未知/1粗/2已同步) clock_source running centers[] report{ok,fail,last_time,next_time} backfill{pending,sent,dropped} elements[code]{raw,value,hex,unit,sampled,invalid} erc{last,count}
node:reg(event, cb)	事件名可用字符串：center_online / center_offline / clock_synced / clock_bad / report_done / backfill_progress / cmd / store_full

版本：water.SZY206_2016 / SL427_2021 / SL427_2008。协议：water.TCP / UDP。 上报模式：water.MODE_HOUR（offset 0~3599）/ MODE_INTERVAL（interval 60~86400）/ MODE_PERIOD（period_min 必须整除 60）。 值类型：water.WORD / DWORD / FLOAT / BIT（字符串 'word' 等也行）。

要素代码与量纲（报文字节数和小数位是标准规定的，改不了）： rainfall 3B/1位/mm、water_level 4B/3位/m、flow_rate 5B/3位/m³h、total_water 5B/0位/m³、velocity 3B/3位、gate 3B/2位、power 3B/0位/kW、air_pressure 3B/0位/10Pa、wind 3B/2位、water_temp 2B/1位、soil_moisture 2B/1位、evaporation 3B/1位、water_pressure 4B/2位/kPa、volt 2B/2位。水质要素首批不做。

一帧只装一个参数类，所以配多个要素会发多帧；定时自报 AFN=C0H、越限加报 AFN=81H。

pipe — 统一管道通信

函数	作用
pipe.setup(protocol, [config])	创建管道对象
p:read_bite/read_s16/read_u16/read_s32/read_u32(addr [, count])	读位与整数
p:read_float/read_double/read_string(addr [, count])	读浮点与字符串
p:write_bite/write_s16/write_u16/write_s32/write_u32(addr, v)	写位与整数
p:write_float/write_double/write_string(addr, v)	写浮点与字符串
p:read() / p:write(params)	读写管道自身参数

读方法返回 {errno, data}，写方法返回整数错误码。

modbus — Modbus TCP 主站

函数	作用
modbus.creat(ip, port)	创建主站对象
d:add_channel(slave, addr, type, target, rw)	加轮询通道
d:start()	启动连接与轮询
d:set_time_lunxun/set_time_recv/set_time_relink/set_time_error(ms)	各类时间参数
d:set_16_ab/set_32_abcd/set_float_abcd/set_double_abcdefgh(order)	字节序（四者各自独立，只对同类型通道生效）

从站服务器

函数	作用
mc_server.start([port, max_sockets, buffer_size])	MC 协议从站（默认 5000）
modbus_tcp_server.start([port, max_sockets, buffer_size])	Modbus TCP 从站（默认 502）

pid — PID 控制

ESP32 机型不提供此模块（只在 Windows / Linux 上位机版本可用）。设备上调用 pid.creat 会报 nil 错误，详见该章开头说明。

函数	作用
pid.creat([kp, ki, kd, ms, outmax, outmin])	创建控制器
o:set_set(v) / o:set_in(v)	设定值 / 测量值
o:loop(input)	执行一次运算
o:get_out()	取输出
o:at_start(cb) / o:at_stop()	自整定启停

encoder — 编码转换

函数	作用
encoder.tobase64/frombase64(str)	Base64
encoder.tohex(str)	转十六进制（小写）
encoder.fromhex(str)	十六进制转回二进制
encoder.from16hex(str)	二进制 → 大写十六进制 ASCII
encoder.to16hex(str)	十六进制 ASCII → 二进制（宽松）

crypto（⚠ 只有部分机型有）

详见加密模块页首说明。crypto 只在部分机型上提供：LP3232、LP3288（ESP32-S3 平台），LP8910、LP8911、LP8912、LP8913、LP8915、LP8916、LP8922（4G 平台），LP2300、LP2323（STM32H750 平台），以及上位机的内置软设备与软 PLC 模拟器。 NaN。

要覆盖全部机型请改用所有机型都有的 plc.aes_encode / plc.aes_decode / plc.base64_encode / plc.base64_decode， 并知悉 aes_encode 只加密长度为 16 整数倍的头部、不足 16 字节原样返回明文。

data — 共享变量

函数	作用
data.creat(v)	创建共享变量对象
o:set(v)	赋值
o:get_num() / o:get_bool() / o:get_string()	按类型取值

json — JSON

函数	作用
json.encode(v)	表 → JSON 字符串
json.decode(str)	JSON 字符串 → 表（要 pcall 保护）
json.null	表示 JSON null

fdb — 数据存储

函数	作用
fdb.kv_set(key, value)	写键值
fdb.kv_get(key, [skey])	读键值
fdb.kv_del(key)	删键
fdb.kv_iter() / fdb.kv_next(iter)	遍历所有键
fdb.ts_add(key, value)	追加时序数据（key 随值存入，可用于过滤）
fdb.ts_select(t1, t2, [key, cb])	按时间段查询，可选按 key 过滤；回调 (ts, value, key)

ini — INI 配置

函数	作用
ini.new()	创建对象
o:load_file(name) / o:load_data(str)	加载
o:get_value(sec, key, [def])	读值
o:set_value(sec, key, val)	写值
o:delete(sec, [key])	删段 / 删键
o:save_file(name) / o:save()	保存到文件 / 字符串
o:get_all_sections()	所有段名
o:get_all_keys(sec)	段下所有键
o:get_all_values(sec, key)	键的所有值

pcnt（⚠ 当前版本不可调用）

详见脉冲计数页首说明。pcnt 与上面 crypto 同一情况： 标准发布版（设备与模拟器）都不提供，脚本里 pcnt.create(...) 得到 nil。 功能本身是完整的（4 路脉冲计数单元、输入 X0–X3、16 位计数），仅定制构建可能提供。 标准机型上要做脉冲计数，请改用计数器软元件 C（当前值用 plc.cn(n) 读）。