SDK 文档 / bbui 应用 SDK 文档
bbui 应用 SDK 文档
适用于 DJI Action 5 Pro(qcs8550)上的 bbui 启动器SDK 版本:API 1(
BBAPP_API_VERSION = 1)· 文档版本:v2(2026-11-03 重写)
这套文档写给要在本机上写第三方应用的人。读完第 2 章你能跑起第一个应用;第 9 章是逐个函数的完整参考(语法、参数、返回值、备注、示例)。
按目标找入口
| 我想…… | 看这里 |
|---|---|
| 先搞懂"为什么应用是独立进程"、有什么代价 | 01 概念与架构 |
| 马上写个 Hello World 装到机器上 | 02 快速开始 |
知道 app.json 每个字段的意思和长度上限 |
03 应用清单 |
打包 .bbapp、装、卸、升级 |
04 打包与安装 |
| 搞清楚启动/退出/崩溃兜底的完整时序 | 05 生命周期 |
| 画面怎么画、帧怎么刷、性能预算多少 | 06 绘制 |
| 触摸坐标为什么是 712×400、点击怎么判定 | 07 输入 |
| 应用跑在什么环境里(目录、环境变量、权限) | 08 运行时环境 |
| 查某个函数怎么用 | 09 API 参考 |
| 点不到 / 黑屏 / 一秒就被杀,怎么查 | 10 调试与排错 |
版本兼容、abi 字段到底管什么 |
11 版本与兼容 |
| 做列表、按钮、开关,不想自己写手势 | 13 控件层 |
| 要用户输入文字(输入框 / 中文键盘) | 14 文本输入 |
| 还没做的能力 | 12 路线图 |
一页速览
一个应用 = 一个可执行文件 + 一个 app.json,放在 /blackbox/apps/<id>/。bbui 只负责把它拉起来;屏幕和触摸由 SDK 运行时接管,应用点左上角「返回」回桌面。
#include "bbapp.h"
static void draw(cairo_t *cr, int w, int h) {
bbapp_text_c(cr, "Hello", w / 2.0, h / 2.0, 40, 1, 1, 1, 1);
}
static const bbapp_app g_app = { .id = "com.example.hello", .name = "示例", .draw = draw };
BBAPP_MAIN(&g_app)
zig cc -target aarch64-linux-gnu.2.28 -I sdk app.c sdk/bbapp_run.c sdk/bbapp_ui.c -o hello \
-l:libcairo.so.2 -l:libwayland-client.so.0 -lm
python sdk/mkbbapp.py . # -> com.example.hello-1.0.0.bbapp
本机既定事实(先记住,少踩坑)
| 事实 | 影响 |
|---|---|
weston 是 DJI 定制版,没有 wl_seat |
wayland 收不到输入,SDK 自己读 /dev/input/event* |
xdg-shell 有缺陷(resize 报错即断连) |
只能用 wl_shell 全屏 |
| 后屏 mode 报 400×712(竖),面板实际横放 | 画布是 712×400,SDK 已转置,应用按横屏写 |
| 没有物理返回键 | SDK 强制画左上「返回」,应用关不掉 |
触摸靠 EVIOCGRAB 进程级独占 |
同一时间只能有一个前台应用 |
| 应用以 root 跑,没有沙箱 | 能读写整块 /blackbox,见 08 |
约定
- 文中「画布」= 应用绘制坐标系,本机是 712×400(宽×高)。
- 「面板」= 触摸设备的原始坐标范围(本机 0..400 × 0..712)。
- 代码块里的
<repo>指本仓库根目录;设备上的路径一律以/blackbox开头。 - 标 【未实现】 的字段/能力表示文档先定契约、代码还没做,见 12 路线图。