ESP-Brookesia多运行时架构：一套平台同时跑JS、Lua、WASM、ELF四种应用-开发者社区

【免费下载链接】esp-brookesia

ESP-Brookesia is a human-machine interaction development framework designed for AIoT devices.

项目地址：https://gitcode.com/gh_mirrors/es/esp-brookesia

ESP-Brookesia 是乐鑫推出的面向 AIoT 与 HMI 产品开发的全栈式开发框架。它的多运行时架构允许同一个设备固件中同时加载 JavaScript、Lua、WASM、ELF 四种类型的动态应用包——你无需为每种语言单独维护一套系统，一个 Runtime Manager 就能统一调度。本文将带你快速看懂这套架构的设计思路与核心机制。

为什么需要多运行时？

传统嵌入式产品开发中，"换一种脚本语言 = 换一套框架"是常见痛点：

迭代效率：JS / Lua 应用可以热更新脚本，不必重新烧录固件；
资源约束：Lua 内存占用小，适合轻量小屏设备；
安全隔离：WASM 提供沙箱执行，适合运行第三方应用；
性能上限：ELF 原生二进制可以跑在高性能扩展场景。

ESP-Brookesia 的做法是：把四种后端收敛到同一套生命周期合约之下，让上层系统（System Core）不需要关心具体跑的是哪种语言。

整体架构：一个 Runtime Manager + 四个后端

下图展示了运行时组件的层级关系：

核心组件职责如下：

组件	角色	说明
brookesia_runtime_manager	宿主框架	后端注册、应用上下文归属、生命周期调度
brookesia_runtime_js	JS 后端	脚本化业务逻辑、快速迭代、ES module 入口
brookesia_runtime_lua	Lua 后端	小型脚本应用、低资源占用、简洁嵌入接口
brookesia_runtime_wasm	WASM 后端	沙箱执行、跨语言模块、可移植部署
brookesia_runtime_elf	ELF 后端	原生二进制加载、高性能扩展、平台相关能力

四个后端组件完全独立发布，通过插件注册机制挂到 Manager 上。在 backend.hpp 中可以看到核心接口IRuntimeBackend：所有后端必须实现init / load_app / start_app / stop_app / unload_app / call_function等统一方法，并以BackendType（Lua、JavaScript、Wasm、Elf）向RuntimeBackendRegistry注册。Manager 通过插件系统枚举所有已注册后端，实现"后端可插拔"。

💡 这意味着开发者按需引入：只跑 Lua 应用的产品就只依赖brookesia_runtime_lua，固件体积不会浪费在其他后端上。

四种语言怎么选？

维度	JS 运行时	Lua 运行时	WASM 运行时	ELF 运行时
定位	轻量应用入口	小型脚本应用	沙箱化第三方部署	原生高性能扩展
生态优势	Web 开发者技能可复用	嵌入式经典、资源占用低	语言无关、安全隔离	性能上限最高
适用场景	快速迭代业务逻辑	简单控制/采集类应用	应用市场分发第三方包	平台相关、重计算模块
入口约定	ES module 入口文件	脚本入口 + 约定回调	WASM 产物	可执行产物
文档	js.rst	lua.rst	wasm.rst	elf.rst

应用包结构：manifest 决定跑哪个运行时

所有运行时应用都打包成标准的App Package，其最小结构如下：

brookesia.app.demo/ manifest.json app/ app.lua res/ profile.json root.json

manifest.json的runtime对象是"语言选择器"：

"runtime": { "type": "Lua", "entry": "app/app.lua", "resource_dir": "res", "arguments": [] }

type：指定后端类型（Lua、JavaScript等）；
entry：入口文件相对路径；
resource_dir：资源目录，内含 JSON UI 描述文件。

应用包有两种部署形态：

.bpk压缩包（ZIP 容器）：运行时由 System Core 解包，可选发布验签；
解包目录：直接部署manifest.json + app/ + res/，由System::init()扫描安装。

System Core 扫描 storage 中apps/目录，找到含manifest.json的一级目录即识别为一个应用。完整字段说明与安全约束见应用包规范文档。

统一生命周期：四种语言同一套状态机

在 types.hpp 中定义了统一的应用状态：

Unloaded → Loaded → Running → Stopped →（可重新加载） └→ Error

Manager 对外暴露的高层 API（见 runtime.hpp）：

load_app(config)/unload_app(id)
start_app(id)/stop_app(id)
call_function(id, module, fn, args)：调用应用导出的函数
list_apps()：快照查询所有已加载应用

脚本侧只需在入口文件创建全局表brookesia_app，实现约定回调即可接入：

brookesia_app.on_install() / on_uninstall() brookesia_app.on_start() / on_stop() brookesia_app.on_pause() / on_resume() brookesia_app.on_action(action) / on_timer(timer_id, name)

无论 JS 还是 Lua，生命周期语义完全一致——这是"一套平台跑四种应用"的关键所在。详细状态迁移见应用模型文档。

原生桥接：脚本如何调用设备能力？

脚本语言本身够不到 Wi-Fi、音频、存储这些原生服务，ESP-Brookesia 通过 **Host Bridge（宿主桥接）**打通：

Manager 把原生服务注册为脚本可见的模块（host_bridge.hpp）；
独立运行时默认提供brookesia.print()、finish_app()、应用上下文 attach/detach 等基础函数；
服务声明即权限：manifest.json的services数组声明依赖的 RPC 服务名与最低版本，Host Bridge 在调用时强制校验——未声明的服务一律不可用，天然形成沙箱边界。

下图展示了服务层如何与运行时、Agent 协作：

从应用市场到设备运行

这套多运行时架构并非孤立存在，而是嵌在完整的产品链路中：应用从 App Store 下载.bpk→ System Core 验签解包 → Runtime Manager 按runtime.type分发给对应后端 → 启动 JSON UI 界面。

目录与文档指南

资料	路径
运行时组件文档索引	docs/zh_CN/runtime/index.rst
Runtime Manager 设计说明	runtime/brookesia_runtime_manager/docs/main.md
Runtime Manager 源码	runtime/brookesia_runtime_manager/src/runtime.cpp
JS 后端	runtime/brookesia_runtime_js/
Lua 后端	runtime/brookesia_runtime_lua/
WASM 后端	runtime/brookesia_runtime_wasm/
ELF 后端	runtime/brookesia_runtime_elf/
应用包规范	docs/zh_CN/system/core/app_package.rst

每个后端组件均提供独立测试工程（如 pytest_runtime_manager.py），覆盖 ESP32-P4 与 ESP32-S3 等平台。

常见问题

Q：一台设备能同时跑多个不同语言的应用吗？A：能。list_apps()会返回所有已知应用记录，每个AppId归属各自的后端类型，互不干扰。

Q：ELF 后端在所有平台上都可用吗？A：ELF 是平台相关的原生二进制加载，仅在目标平台支持时生效（见 elf.rst）；JS、Lua、WASM 的移植性更好。

Q：第三方应用如何保证安全？A：推荐 WASM 后端做沙箱化部署；同时 manifest 的服务声明机制对所有运行时应用强制生效，未声明的服务无法调用。

总结

ESP-Brookesia 的多运行时架构用一句话概括就是：统一合约、后端可插拔、包格式标准化。Runtime Manager 管生命周期，manifest 选语言，Host Bridge 控权限——四种语言的应用在同一套系统里平等共存。对于 AIoT 开发者而言，这意味着可以用最熟悉的语言写业务逻辑，同时享受框架层带来的硬件抽象、服务调用和应用分发能力。