其他接口函数

本页说明日期时间、运行计时、音频播放、设备标识、页面查询、数据库及兼容接口。寄存器读写、串口通信、定时器和系统回调请查看第五章对应页面。

1. 通用调用约定

接口名称及参数顺序区分大小写。注明“无返回值”的函数，正常调用不返回任何值；参数数量、类型或取值错误通常会抛出 Lua 错误。使用 pcall() 可以捕获错误并继续处理。不要用无返回值接口的 == 0 来判断成功。

数据库接口通常用返回值表示失败，请先检查句柄与返回结果。本文示例应合并到工程现有回调，同名回调只保留一份。

2. 日期时间与运行计时

2.1 set_date_time：设置日期和时钟

set_date_time(year, month, day, hour, minute, second)

六个参数必须全部为整数，不能省略。返回值：无。无效日期、RTC 拒绝设置或设备设置失败时抛出 Lua 错误。例如 2026-02-30 不会被自动改为 3 月日期。

local ok, err = pcall(set_date_time, 2026, 10, 8, 14, 30, 0)
if not ok then
    print("设置时间失败：", err)
end

屏端设置设备时钟；Windows 模拟器设置模拟器的虚拟时钟。该接口不提供时区参数。

2.2 get_timestamp：取得运行毫秒计数

local now_ms = get_timestamp()

无参数，返回有符号 32 位整数，单位为毫秒。用于延时判断、间隔计算和性能计时。它不是 Unix 时间戳，也不能直接当作年月日进行显示。计数长期运行会回绕；计算小于 2147483648 ms（约 24.8 天）的短间隔时，直接使用整数相减，Lua 整数运算会按 32 位回绕：

local start_ms = get_timestamp()

-- 在后续回调中计算间隔，不使用空循环等待。
local elapsed_ms = get_timestamp() - start_ms

3. 音频播放

play_audio(volume, audio_id)

play_audio(volume, audio_id)

volume 为 0～100 的整数，0 表示静音；audio_id 为 0～65535 的整数，指向工程的音频资源。返回值：无。音量设置失败、文件不可用或播放器启动失败时抛出 Lua 错误。

当前资源编号中，最高位选择音频类型，低 7 位选择文件编号：WAV 使用 0～127；MP3 使用 0x8000～0x807F。其余位不参与文件编号，请使用工程实际导出的资源 ID。不要把文件路径字符串传给 audio_id。

-- 示例要求工程中已配置 0 号 WAV 资源。
local ok, err = pcall(play_audio, 70, 0)
if not ok then
    print("播放失败：", err)
end

本接口按单次播放请求处理，返回不表示已经播放完毕；没有循环次数参数。停止、暂停等需求应使用音频功能及系统寄存器对应说明，不能给此函数添加额外参数。

4. 设备标识与当前页面

4.1 get_device_uuid()

local uuid, source = get_device_uuid()

无参数。成功返回两个值：uuid 为 32 个大写十六进制字符组成的字符串；source 为 "hardware" 或 "simulator"。

屏端返回芯片标识；模拟器返回固定模拟标识 53494D554C41544F5200000000000001，不同模拟器实例不能据此区分。硬件标识读取失败或空白时，返回 nil, error_message。

local uuid, source = get_device_uuid()
if uuid == nil then
    print("读取设备标识失败：", source)
elseif source == "simulator" then
    print("当前是模拟器：", uuid)
else
    print("设备标识：", uuid)
end

4.2 get_view_page()

local page_id = get_view_page()

无参数，返回实际显示的嵌入页面 ID；没有活动嵌入页面时返回当前主页面 ID。用于滑动嵌入页场景下判断当前视图。它不表示尚未完成的页面跳转请求，也不返回弹窗或系统键盘的页面 ID。没有可用页面时可能返回 0xFFFF，应等待页面创建后再操作控件。

查询页面不会切页。控件接口只接收控件 ID，没有 page_id 参数。

5. EasyDB 数据库

EasyDB 用于读写已经存在的固定记录数据库文件。easydb_open() 不会新建数据库，不接受 CSV 或普通文本作为数据库。文件应先由工程配置或配套工具生成，并放在设备或模拟器实际可访问的路径。

所有 easydb_* 函数都具有完全相同的 stt_gui_easydb_* 别名。建议同一脚本统一使用短名称。

5.1 完整接口索引

db 必须是 easydb_open() 返回且尚未关闭的句柄；不要自行构造。最多同时打开 16 个句柄。path 为可访问的数据库文件路径字符串；打开失败还可能是文件格式不正确、文件不完整或内存不足。

index 为 0～65535 的整数，必须小于文件配置的容量；文件支持的容量上限为 32767 条。它是从 0 开始的物理记录槽位索引，不是排序后的显示行号。删除只清空该槽，不把后续记录整体向前移动；添加会使用第一个空槽。

data 为字符串。数据库每条记录长度固定，超过配置长度的内容按字节截断；注意避免截断中文字符。easydb_add() 不接受空字符串。easydb_update() 更新空槽时也会建立记录，传入空字符串会将该槽内容清零；真正删除记录使用 easydb_delete()。

记录表数据可用分号分隔各列，例如 "产品A;100;合格"。分号是列分隔符，没有 CSV 的双引号转义规则；单元格文本不应包含分号，字符串中也不要嵌入 \0。

5.2 共享槽位与保存

share_index 为 0～15 的整数。将数据库绑定到数据记录控件配置使用的相同槽位；即使不显示表格，需要后台处理保存时也要共享该数据库。

easydb_share(0, db)
local pending = easydb_flush(db)

增加、更新、删除及清空首先改变内存记录，不表示文件已持久保存。easydb_flush() 请求后台分步保存，仅后台可见的共享数据库会被处理；不能在 Lua 中用忙循环不断调用 flush 等待，否则会阻塞保存任务和界面。

flush 返回正数表示当前还有多少条记录需要写入，0 表示当前没有待写记录，但不单独证明后续文件同步、关闭及重新打开已经完成；当前 Lua 接口没有完整保存结束状态查询，保存结束或失败可查看运行日志。关闭时会尝试保存剩余修改，但 easydb_close() 无返回值，不能据此检测存储错误。

不再使用时调用 easydb_close()，然后把 Lua 变量置为 nil；关闭会解除该句柄的共享绑定。可用 easydb_share(share_index, nil) 主动解除槽位。脚本关闭或重新加载也会关闭打开的数据库。

5.3 打开、读取与修改示例

local db = nil

function open_user_database(database_path)
    db = easydb_open(database_path)
    if db == nil then
        print("无法打开数据库：", database_path)
        return false
    end

    easydb_share(0, db)
    print("当前记录数：", easydb_get_count(db))
    return true
end

function update_first_record()
    if db == nil then
        return
    end

    local result = easydb_update(db, 0, "产品A;100;合格")
    if result ~= 0 then
        print("更新失败：", result)
        return
    end

    local record = easydb_get(db, 0)
    print("物理槽 0 的记录：", record or "空")

    local pending = easydb_flush(db)
    if pending < 0 then
        print("保存请求失败：", pending)
    else
        print("已请求后台保存，待写记录数：", pending)
    end
end

function close_user_database()
    if db ~= nil then
        easydb_close(db)
        db = nil
    end
end

把设备实际数据库文件路径传给 open_user_database()，文件需有至少 1 个记录槽、足够的记录字节数。根据业务在现有初始化、控件事件和页面回调中调用这些函数。需要追加数据使用 easydb_add()；需要移除物理槽 0 使用 easydb_delete(db, 0)。

6. set_notify：控制 DCBUS/DGUS 自动上传

set_notify(enable)

enable 只接受整数 0（关闭）或 1（开启），不能传布尔值；正常无返回值，参数错误会抛出 Lua 错误。新版固件和模拟器已实现此接口，默认开启。

工程仍须开启对应自动上传配置；set_notify(1) 不会代替工程配置，也不会补发关闭期间的值。脚本关闭或加载失败清理后恢复默认开启。请先更新到支持此功能的固件或模拟器。

-- 示例：暂停 DCBUS/DGUS 自动上传，再修改本地演示变量。
-- LW 0x1014 应是本地变量，不能换成 PLC 外部寄存器来当作禁发测试。
set_notify(0)
set_uint16(1, 0x1014, 9)
set_notify(1)

要停止脚本持续发送，应调用 stop_timer(timer_id)，或在 on_run 等业务回调中增加运行开关。set_run_cycle(0) 不会停止周期回调，set_notify(0) 也不是全局串口停止指令。

更完整的参数说明见寄存器操作函数，暂停与恢复示例见定时器函数。

7. 常见错误