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 核心库。