跳转至

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 的顺序搜索脚本

可用于

  1. 多模块项目开发

当项目包含多个功能模块(如传感器驱动、网络通信、业务逻辑),且各模块的 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 核心库。