SDK 文档 / 10 · 调试与排错

10 · 调试与排错

设备上没有 IDE、没有 gdb 图形界面,能用的就是日志和几条命令。这一章先给"症状 → 原因"的速查表,再讲怎么手跑应用、怎么确认触摸/服务状态。

10.1 症状速查

症状 最可能的原因 怎么确认 处理
桌面没有图标 目录不在 /blackbox/apps/ 下;或 bbui 没重扫 ls /blackbox/apps 装完等 0.25 s;不行就重启 bbui
图标是灰的(点了提示装坏了) app.json 读不到 / entry 文件不在 cat /blackbox/apps/<id>/app.json;ls -l 看入口 修文件名;unzip -o 重装
点图标黑一下又回桌面 应用启动即退出(连不上 wayland、init 非 0、崩溃) tail -30 app.log,看最后一行 [bbapp] 见 10.3
应用起来了但点不到 选中了副屏触摸;或没抢到独占 日志找 触摸独占成功 / touch ... MT 400x712 用 BBAPP_TOUCH 指定设备
点 A 处却响应 B 处坐标 同上(坐标整体偏) 看日志 tap x,y 是否落在预期区 同上
画面转 90° / 竖着 自己开了窗口或设了 BBAPP_ROT=90 echo $BBAPP_ROT 去掉;别自己开 wayland 窗口
画面正常但动不了 draw 阻塞(死循环/大 IO),主线程卡住 top 看 CPU 是否 100% 别在 draw 里做重活
文字是方块 设备缺字体 `fc-list \ grep -i quan` 重跑部署器(10.1 字体注册)
画面全黑但进程活着 首帧没提交(卡在 init) 日志停在 启动 ... 之后、没有 tap 记录 检查 init 是否阻塞
应用 1 秒后消失 没跑在独立 cgroup 里(旧版启动方式) systemctl status bbui-app-* 用当前 apps.c 的 systemd-run 路径
相机界面盖住应用 DJI 服务被拉回来了 systemctl is-active dji_camera3 确认 app-run.sh 在跑(每 2 s 压一次)
回桌面后触摸失灵 独占没释放(应用被 SIGKILL 硬杀) 重启 bbui:bbui-stop; bbui EVIOCGRAB 随 fd 关闭自动释放,通常立刻恢复
中文路径打不开 snprintf 缓冲太小被截断 日志里的路径 缓冲给 600 字节

10.2 日志怎么读

adb shell tail -f /blackbox/apps/com.example.hello/app.log

一次成功的启动,日志里这几行一定都在(顺序固定):

[20:11:03] === app-run 开始: /blackbox/apps/com.example.hello/hello ===
[20:11:03] exec /blackbox/apps/com.example.hello/hello
[1762...] [bbapp] touch /dev/input/event2 'fts_ts_3269' MT 400x712 -> 有匹配屏 score=1000
[1762...] [bbapp] 主屏 712x400(面板 400x712, 输出 'DSI-1' mode 400x712, rot=0)
[1762...] [bbapp] 触摸独占成功 (0..399, 0..711)
[1762...] [bbapp] 启动 com.example.hello (示例) 画布 712x400

对着缺哪行判断:

缺的行 说明
=== app-run 开始 === 脚本没被执行(/blackbox/svc/app-run.sh 不存在或不可执行)
exec ... 脚本卡在"等 bbui 退出"那 5 秒里,或者脚本本身被杀了(systemctl status 看单元状态)
触摸独占成功 EVIOCGRAB 失败——常见于 bbui 还没真正退出
一行 [bbapp] 都没有 应用在连 wayland 之前就崩了(动态库缺失最常见)
有 启动 ... 但没有首帧 卡在 init()

10.3 手跑(不经 bbui,直接看输出)

排查"到底是我崩了还是启动链路坏了"的最快办法:bbui 不在的时候手动跑。

adb shell
# 1) 停掉 bbui,把屏幕让出来
bbui-stop

# 2) 直接跑应用,环境变量自己给
cd /blackbox/apps/com.example.hello
XDG_RUNTIME_DIR=/run/user/root WAYLAND_DISPLAY=wayland-1 \
BBAPP_DATA=$PWD/data BBAPP_ASSETS=$PWD/assets BBAPP_LOG=$PWD/app.log \
./hello

常见输出与含义

输出 原因
[bbapp] 连不上 wayland(WAYLAND_DISPLAY=...) 环境变量没给,或 bbui-stop 把 weston 也带下去了
error while loading shared libraries: libcairo.so.2 设备缺 cairo(部署不完整)
[bbapp] 触摸独占失败: Device or resource busy 还有别的进程(bbui?)抓着
[bbapp] 没有 MT 触摸设备 -> 用默认 712x400(只能看,点不了) 设备节点不存在(root 权限或 device 不匹配)

10.4 确认触摸状态

# 谁在用这个设备(有 grab 时看不到别的进程,但能看到自己的)
adb shell "cat /proc/bus/input/devices | grep -A5 fts_ts"

# 直接看原始事件(会被 grab 挡掉,所以先 bbui-stop 再跑)
adb shell "cat /dev/input/event2 | od -An -tx1 -w16 | head"

如果 cat 没有输出、而应用里点击有日志,说明 grab 正常工作(事件只给了应用)。

10.5 注入点击做自动化

adb push tools/tapinj.aarch64 /blackbox/tmp/tapinj
adb shell "chmod 755 /blackbox/tmp/tapinj"

# 面板坐标:raw_x = 399 - y, raw_y = x
adb shell "/blackbox/tmp/tapinj /dev/input/event2 200 356 40"

适用场景:验证"应用能不能收到点击"、跑冒烟测试、触摸屏坏了临时操作。

注意参数是面板坐标不是画布坐标(07 有换算表)。

10.6 确认 DJI 服务被压住

adb shell "for u in gui sub_gui dji_camera3; do \
           printf '%s=%s ' \$u \$(systemctl is-active \$u); done; echo"

应用运行期间三条都应该是 inactive/failed。如果 active,说明 app-run.sh 的守候循环没在跑(脚本被杀了、或者应用是用别的方式起的)。

10.7 检查应用单元

adb shell "systemctl list-units --all | grep bbui-app"
adb shell "systemctl status bbui-app-12345 --no-pager"
adb shell "journalctl -u bbui-app-12345 --no-pager | tail -30"

journalctl 能看到 systemd-run 启动失败的原因(比如单元名重复——我们的单元名带 pid,正常不会撞)。

10.8 拿崩溃信息

没有 gdb,但有三个手段:

# 1) 退出码(脚本会写进 app.log)
#    rc=139 段错误, rc=134 abort, rc=137 SIGKILL

# 2) dmesg 里的段错误记录(含 pc 和库名)
adb shell "dmesg | grep -i -A3 'segfault\|hello'"

# 3) 自己装一个信号处理器,把 backtrace 打到日志

经验值:crash 90% 是空指针、缓冲区越界、或者 cairo_t 跨帧使用(保存了 cr 指针)。

10.9 性能怎么看

# 应用占多少 CPU
adb shell "top -b -n1 | grep hello"

# 帧率:连续取 10 次绘制日志的时间(如果自己加了日志)

判断标准很简单:没有 tick 的应用,静止时 CPU 应该接近 0。如果静止也占几成 CPU,说明你注册了 tick(注册即持续重绘)。

10.10 恢复到干净状态

# 停掉所有应用相关进程
adb shell "pkill -f '/blackbox/apps/'"

# 回桌面
adb shell "bbui"

# 清日志重来
adb shell "> /blackbox/apps/com.example.hello/app.log"

如果屏幕彻底黑了(bbui 和应用都没起来):

adb shell "bbui"                 # 短命令,等价于 ui-start.sh
adb shell "sh /blackbox/opt/bin/ui-start.sh"   # 短命令不在时

下一步 → 11 版本与兼容。

bbui 第三方应用 SDK · API 1 · 本文档随仓库 docs/sdk 自动生成