rtos

作者：王城钧

一、概述

rtos 库是 LuatOS 中用于管理底层操作系统资源、硬件信息及实时任务的系统级工具库，提供消息队列处理、定时器控制、设备信息查询、内存管理、固件标识及路径配置等功能。

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考 LuatOS 仓库中各个产品目录下的 demo/rtos

PROJECT = "rtos_demo"
VERSION = "001.000.000"


-- 1. 系统信息查询测试
log.info("固件信息", "版本:", rtos.version())
log.info("编译信息", "日期:", rtos.buildDate(), "BSP:", rtos.bsp())
log.info("完整描述", rtos.firmware())

-- 2. 内存信息测试
local total_lua, used_lua, max_used_lua = rtos.meminfo("lua")
local total_sys, used_sys, max_used_sys = rtos.meminfo("sys")
log.info("内存信息", 
    "Lua - 总:", total_lua, "已用:", used_lua, "峰值:", max_used_lua,
    "系统 - 总:", total_sys, "已用:", used_sys, "峰值:", max_used_sys)


-- 3. 内存自动回收配置
rtos.autoCollectMem(200, 75, 85)  -- 配置较宽松的自动回收

-- 4. 空函数测试（性能测试用）
local function test_nop()
    local start = os.clock()
    for i = 1, 1000 do
        rtos.nop()
    end
    log.info("性能测试", "1000次nop耗时:", os.clock()-start, "秒")
end

-- 10秒后执行空函数测试
sys.timerStart(test_nop, 10000)

-- sys.timerStart(reboot, 30000)
-- local function reboot()
--     log.info("系统", "准备重启...")
--     rtos.reboot()
-- end, 30000)
-- 5. 重启测试（注释掉防止意外重启）
-- sys.timerStart(reboot, 30000)

log.info("RTOS测试", "所有测试已启动")
sys.run()

三、常量详解

核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；

每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为LuatOS内核固件可能会变更每个常量对应的常量取值；

如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；

rtos 核心库没有常量。

四、函数详解

rtos.timer_start(id,timeout,repeat)

功能启动一个定时器（这个 api 只给 sys 核心库使用，如果需要软件定时器功能，可以直接使用 sys 核心库中的 timer 接口）参数

id

参数含义：定时器id；
数据类型：number；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：1；

timeout

参数含义：超时时长，单位毫秒；
数据类型：number；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：2000；

repeat

参数含义：重复次数，当repeat = -1时表示定时器会持续周期性触发，
         当repeat = 0时，定时器会被停止并释放；当repeat > 0时，每触发一次递减1
         默认值为0；
数据类型：number；
取值范围：无特别限制；
是否必选：可选传入此参数；
注意事项：暂无；
参数示例：5；

返回值

local result = rtos.timer_start(id,timeout,repeat)

result

含义说明：表示定时器启动操作的结果状态，1表示成功，0表示失败；
数据类型：number；
取值范围：暂无；
注意事项：暂无；
返回示例：1；

示例

rtos.timer_start(10000, 3000, 0)

rtos.timer_stop(id)

功能

关闭并释放一个定时器（这个 api 只给 sys 核心库使用，如果需要定时器功能，可以直接使用 sys 核心库中的 timer 接口）

参数

id

参数含义：定时器id，与rtos.timer_start的第一个参数id对应；
数据类型：number；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：1；

返回值

nil

示例

rtos.timer_stop(1)

rtos.reboot()

功能

设备重启

参数

nil

返回值

nil

示例

rtos.reboot()

rtos.buildDate()

功能

获取内核固件编译日期

参数

nil

返回值

local result = rtos.buildDate()

result

含义说明：固件编译日期；
数据类型：string；
取值范围：暂无；
注意事项：暂无；
返回示例："Aug 31 2025"；

示例

local result = rtos.buildDate()

rtos.bsp()

功能

获取硬件 bsp

参数

nil

返回值

local bsp = rtos.bsp()

bsp

含义说明：硬件bsp型号；
数据类型：string；
取值范围：暂无；
注意事项：暂无；
返回示例："Air8000"；

示例

local bsp = rtos.bsp()

rtos.version()

功能

获取内核固件版本号

参数

nil

返回值

local luatos_version = rtos.version()

luatos_version

含义说明：固件版本号；
数据类型：string；
取值范围：暂无；
注意事项：暂无；
返回示例："V2014"；

示例

local luatos_version = rtos.version()

rtos.meminfo(type)

功能

获取内存信息

1.虚拟机内存内存直接关联 Lua 虚拟机的内存使用，包括 Lua 脚本中变量、函数、表、字符串等动态分配的内存，以及 Lua GC 管理的堆空间，用户可用来关注内存泄漏。 2.系统内存涵盖系统级内存资源，包括内核堆（Heap）、任务栈、中断栈、驱动缓冲区等，用户在 Lua 脚本底层硬件操作：如 GPIO、UART、I2C 等驱动程序的内存分配。系统级任务：如任务调度、中断处理、消息队列等会用到系统内存。

3.psram 内存针对外接的伪静态随机存取存储器，Lua 脚本使用大容量数据缓存（如图像/音频处理）、网络通信（TCP/UDP/OTA）在接收大文件时会用到 psram 内存。

参数

type

参数含义："sys"系统内存, "lua"虚拟机内存,"psram"psram内存, 默认为lua虚拟机内存；
数据类型：string；
取值范围：无特别限制；
是否必选：可选传入此参数；
注意事项：暂无；
参数示例：sys；

返回值

local total_lua, used_lua, max_used_lua = rtos.meminfo("lua")

total_lua

含义说明：总内存大小，单位字节；
数据类型：number；
取值范围：暂无；
注意事项：暂无；
返回示例：4194296；

used_lua

含义说明：当前已使用的内存大小，单位字节；
数据类型：number；
取值范围：暂无；
注意事项：暂无；
返回示例：16424；

max_used_lua

含义说明：历史最高已使用的内存大小，单位字节；
数据类型：number；
取值范围：暂无；
注意事项：暂无；
返回示例：16424；

示例

local total_lua, used_lua, max_used_lua = rtos.meminfo("lua")
local total_sys, used_sys, max_used_sys = rtos.meminfo("sys")

rtos.firmware()

功能

返回内核固件名称,格式为 LuatOS_$VERSION_$BSP,可用于 OTA 升级判断底层信息

参数

nil

返回值

local result = rtos.firmware()

result

含义说明：内核固件名称；
数据类型：string；
取值范围：暂无；
注意事项：暂无；
返回示例："LuatOS-SoC_V2014_Air8000"；

示例

log.info("底层信息", rtos.firmware())

rtos.setPaths(pathA, pathB, pathC, pathD)

功能

设置自定义 lua 脚本搜索路径,优先级高于内置路径，按 pathA → pathB → pathC → pathD 的顺序搜索脚本

可用于

多模块项目开发

当项目包含多个功能模块（如传感器驱动、网络通信、业务逻辑），且各模块的 Lua 脚本分散在不同目录时，可通过 rtos.setPaths 指定模块路径。

2.动态加载外部脚本

设备需从外部存储（如 SD 卡、SPI Flash）动态加载脚本时，通过路径配置实现灵活加载。

参数

pathA

参数含义：路径A,若不传值,将默认为""；
数据类型：string；
取值范围：无特别限制；
是否必选：可选传入此参数；
注意事项：最大长度不可超过23字节；
参数示例："/sdcard/%s.luac"；

pathB

参数含义：路径B,若不传值,将默认为""；
数据类型：string；
取值范围：无特别限制；
是否必选：可选传入此参数；
注意事项：最大长度不可超过23字节；
参数示例："/sdcard/%s.lua"；

pathC

参数含义：路径C,若不传值,将默认为""；
数据类型：string；
取值范围：无特别限制；
是否必选：可选传入此参数；
注意事项：最大长度不可超过23字节；
参数示例："/lfs2/%s.luac"；

pathD

参数含义：路径D,若不传值,将默认为""；
数据类型：string；
取值范围：无特别限制；
是否必选：可选传入此参数；
注意事项：最大长度不可超过23字节；
参数示例："/lfs2/%s.lua"；

返回值

nil

示例

-- 挂载sd卡或者spiflash后
rtos.setPaths("/sdcard/user/%s.luac", "/sdcard/user/%s.lua")
require("sd_user_main") -- 将搜索并加载 /sdcard/user/sd_user_main.luac 和 /sdcard/user/sd_user_main.lua

rtos.nop()

功能

空函数,什么都不做

参数

nil

返回值

nil

示例

-- 这个函数单纯就是 lua -> c -> lua 走一遍
-- 没有参数,没有返回值,没有逻辑处理
-- 它通常只会出现在性能测试的代码里, 因为它什么都不干.
rtos.nop()

rtos.autoCollectMem(period, warning_level, force_level)

功能

内存自动收集配置，是 lua 本身内存收集机制的一种补充，不是必要的，而且只在 luavm 空闲时触发

通过设置自动回收周期定期触发内存收集，并在内存低于阈值时强制执行完整 GC，避免 Lua 原生 GC 因惰性触发导致的延迟。两者协同工作：RTOS 负责主动监控和紧急干预，Lua GC 处理常规清理。

参数

period

参数含义：自动收集的周期，等同于receive调用次数，如果是0，则关闭自动收集功能，默认是100；
数据类型：number；
取值范围：0~60000；
是否必选：可选传入此参数；
注意事项：暂无；
参数示例：100；

warning_level

参数含义：内存使用警戒水位线，是总luavm内存量的百分比，内存达到(>=)警戒线时才会开始判断是否要收集；
数据类型：number；
取值范围：50~95；
是否必选：可选传入此参数；
注意事项：暂无；
参数示例：80；

force_level

参数含义：内存使用强制收集水位线，是总luavm内存量的百分比，内存达到(>=)强制收集线时会强制收回，
         默认是90；
数据类型：number；
取值范围：50~95；
是否必选：可选传入此参数；
注意事项：必须比警戒水位线大；
参数示例：90；

返回值

nil

示例

rtos.autoCollectMem(200, 75, 85)

五、产品支持说明

目前合宙主流模组都支持 rtos 核心库。