# 8×8 ToF 硬件避障展示

2026-09-23，Android v10.15.1（45），手机热点直连。
**打开 App 先进入原首页，不启动辅助。点击原首页“开始辅助”才运行当前 A+LOCAL；
“结束辅助”返回首页并停止采集、推理和反馈。** 这修正了 v10.13–10.15.0 把硬件页面
设为默认入口的误解。首页按钮明确使用 Wi-Fi A+LOCAL，复制首页语音/震动开关；
辅助页面仍可手动切回基础 ToF。模型、阈值与实验边界不变。

v10.15.1：6 项 S24 Ultra / Android 16 回归通过，覆盖 launcher、首页未启动、
开始/结束、语音/震动设置传递、模式持久化和详情折叠；debug/androidTest 构建、lint
及 APK 45 / 10.15.1 身份/签名/16 KB 检查通过，原位安装保留数据。手机最终停留原首页。
证据与截图：`artifacts.local/hardware-bringup/home-assist-20260923/`。

## A+LOCAL 实验模式

用户要求将研究组合移到实物手机。新增开关默认开启，可随时关闭并回到原基础 ToF。
冻结 A 阈值 0.4071309640537889、LOCAL 阈值 0.7959699076137833，LOCAL 为 200 棵
HGB 树、961 维公开输入特征，仅中央 BODY/HEAD 查询 1/4 参与 A OR LOCAL；不包含失败的
额外救援门控，不改模型或阈值。模型在手机 CPU 离线运行，纯标量/树操作不依赖 GPU。

**这是名义几何适配实验，不是标定后的实机升级效果证明。** RGB 640×480 中央裁成
640×360，再用 2×2 面积平均到 320×180；名义相机水平视场 100°、ToF 45°、同轴无平移，
粗朝向沿用原安装记录。径向读数按区域中心射线换算轴向，不能精确代表区域内实际反射位置。
研究 ToF 是假设的单回波模拟器，实物状态/材质/畸变/安装偏差没有因此被消除。
真实原始区域、读数和显示画面保留，界面显示未标定，不画伪配准框。

LOCAL 需要有效 RGB 和 8×8 ToF；两路时龄上界差大于 250 ms 时暂停 LOCAL，此规则不是
曝光同步证明。缺少画面时保留 A；ToF 失效时停止判决。推理结束和主线程恢复时再次检查
750 ms 新鲜度，拒绝过期贡献。LOCAL 单独触发保留 UNKNOWN，不输出虚构距离。
同一 ToF 样本不重复推理，旧缓存受相机时龄限制；无后台积压。USB 中转缺少双路时龄，
仅 A，不声称支持 USB LOCAL。模型加载或输入格式失败明确显示回退基础 ToF。

留证继续保存当时判决和包含算法来源的状态，回放不重新推理、不发声。
模型来源和二进制 SHA 位于 `app/src/main/assets/hardware_local/local-v1.json`，
导出脚本 `tools/export_hardware_local.py` 校验原模型/阈值/源码身份，不进行拟合。

### v10.15.0 验证

- 7 项 JVM 测试无跳过通过：A 的 111 条 Python 对照（含阈值两侧和 12 条已消费帧），
  LOCAL 的 8 帧 / 48 查询特征与概率对照、中心查询子集一致性、输入拒绝与安装映射。
- S24 Ultra / Android 16 上 8 项测试通过：4 项运行时/裁剪/失效检查、1 项显式真实
  输入检查、3 项入口与设置切换检查。没有清除 App 数据或修改固件。
- 真实输入 10 秒窗口、101 个不同 ToF 样本全部完成 A+LOCAL，101/101 输出双路有效；
  模型适配与推理总耗时中位数 53 ms、P95 61 ms、最大 82 ms。此为手机处理时间，
  不含物理感测到语音的端到端时延，也没有障碍真值或实机优于基线结论。
- debug / androidTest 构建及 lint 通过（0 errors / 19 warnings）；版本 44 / 10.15.0、
  签名及 16 KB 静态检查通过。最后仅将资产说明 JSON 换行规范化，模型二进制与运行代码不变。
- 原始构建、单测夹具、设备测试及实机时序、归档回执位于
  `artifacts.local/hardware-bringup/a-local-port-20260923/`。未完成物理标定、
  真实漏报/误报对照、长时间/锁屏、TalkBack 或实际听感验收。

## 留证与回放

1. 连接后，前台在内存循环保留最近最多 20 秒 / 256 帧。点 **保存刚才 20 秒** 保存已有记录；连接刚启动时会短于 20 秒。新 ToF 序号、判决变化与流状态变化不会被普通显示采样限速忽略。
2. 默认只记录测距、有效性、时龄、原判决及提示请求。展开 **记录 / 回放**，可开启 **附带画面抽帧**：异步最多 2 Hz、320×240 JPEG，非连续录像，不表示曝光同步。关闭会清除未保存的画面；已保存记录不变。
3. 在记录列表点 **回放**，可拖动时间轴或播放/暂停。回放保留当时判决，不重新运行新算法，不播语音/震动；离开页面暂停，页面重建后仍保持暂停回放。点 **返回实时** 才恢复连接。
4. 记录保存在 App 私有不备份目录，最多 50 条 / 50 MB，不自动上传或淘汰。**导出**写入用户选择的文档位置，JSON 包含可选 Base64 JPEG；**删除**需要确认，仅删除选中的本地记录。

保存的时钟为 Android 单调时间；保存日期另用墙钟。语音入队不证明已听到，震动请求不证明实际触感；记录不是障碍真值。记录帧与图像抽帧可能不同步，回放会注明无画面或 2 Hz 抽帧。

## 安装朝向粗检查

展开 **安装朝向检查**，固定设备和背景，依次采集背景、画面中央、左侧、右侧。
目标需比背景近至少 20 cm，上下尽量居中；每步 2 秒、至少 5 个不同的新 ToF 帧，要求双路实时完整输入。
断流会终止当前步骤，会话或实时/回放模式改变时清空检查。结果只是与用户声明摆放位置的粗一致性，未完成像素、视场或距离标定，不自动调整方向或几何参数。

## 分路降级

Wi-Fi 两路新鲜度独立检查，原 750 ms 上限不变：

- 两路有效：实时画面与 ToF 判决。
- 相机不可用、ToF 有效：清除旧画面，明确显示并提示 **仅测距模式**；基础 ToF 判决继续。
- ToF 不可用、相机有效：只显示新鲜画面，判决为 UNKNOWN，停止障碍提醒并提示测距中断。
- 两路不可用：不显示旧画面，不保留旧判决。有效测距流不代表每个区域有效，无效区域仍被原规则拒绝。

## 事件式反馈

- 首次有效障碍触发立即提醒；持续触发每 12 秒提醒一次。距离相对上次提醒缩短至少 300 mm、间隔至少 1 秒时追加“前方测距变近”。这只是读数变化，不表示追踪到同一物体或估计碰撞时间。
- 非触发持续至少 1 秒后重新允许首次提醒；短暂抖动不反复启动事件。非触发与 UNKNOWN 都不会播报安全或可通行。
- 曾经有效的实时输入中断时只提醒一次；恢复时播报恢复，若同时触发则合并障碍提示。初次未连接不循环播报失联。
- 语音和震动独立控制，设置随 App 保存；回放两者均关闭，离开页面停止连接与反馈。当前不提供锁屏持续运行模式。
- 离线页面有直接重连按钮；发现、时钟、新鲜度和几何规则仍使用既有协议。

## 手机热点直连

相机与 XIAO 8×8 ToF 各自加入手机的 2.4 GHz 热点，App 直接接收 MJPEG 与
64 区测距。电脑仅用于首次刷写、配网与开发；运行不需要电脑中转或 ADB reverse。
两块板仍需 USB 电源（可使用移动电源），不要求 USB 数据连接。

1. 手机开启与已配网凭据一致的热点，频段包含 2.4 GHz。
2. 给两块硬件供电。首次配网通过 `host/provision_wifi.py` 读取忽略目录中的
   SSID/password JSON，经物理 USB 写入硬件 NVS；凭据不进入仓库。
3. 打开 App 进入原首页，点击 **开始辅助** 后进入 **前视感知**，自动发现两个设备；**结束辅助**回到首页。
4. 若未找到，打开 **设备连接 → 自动发现**，或填入两块板的局域网 IP 后连接。
   **网络设置**可进入手机无线设置。局域网路由器也可使用相同协议。
5. 展示页以相机、最近触发读数和有效区数量为主体；展开 **感知数据** 显示原始热图，
   可查看数据时龄。未完成相机—ToF 空间标定，不显示伪造的目标框或像素映射。

相机使用最新帧替换及 UDP 单调时钟映射；ToF 独立以固定 10 Hz 采样，新样本通过
UDP3335 主动推送。手机每秒续订，租约五秒，到期自动停止发送；HTTP 保留诊断用途。
两路时龄上界均包含各自的时钟误差界；这些不是屏幕发光或语音输出延迟，ToF 时间戳
是读出完成，未包含此前感测和 I²C 时间。两路独立采样，不声称曝光同步。
无线任一路超过 750 ms 或时间/数据无效时，该路单独失效；相机握手失效清除画面，ToF 失效清除判决，详见分路降级。
设备重启会重建相机时钟与序号状态；前后台切换停止连接及语音。

ESP32 演示传输是可信局域网内的明文 HTTP/UDP，未提供设备身份认证或 TLS。
Android 为动态热点地址允许明文网络；无线展示端点仅接受 RFC1918 数字 IPv4，
HTTP 80/流 81，不接受任意域名、凭据 URL 或跳转。应仅连接用户自己的演示硬件。
USB 中转作为可选兼容入口保留；需要刷回对应 USB 固件，不会与无线固件同时采集。

## v10.14.0 留证与分路验证

- 31 项 JVM 单测通过：反馈 7、原几何 8、安装检查 4、无线协议 6、分路有效性 6。
- S24 Ultra / Android 16 上 17 项测试通过：记录器 9、回放交互及页面重建 1、入口/设置 2、旧客户端 4、显式启用的真实硬件检查 1。
- 关闭记录 / 只记测距 / 附带抽帧三个约 8 秒窗口分别为 160/160、160/160、159/159 双路有效快照；记录接口 P95 0.242 / 0.398 ms。记录分别保存 88 / 84 帧，抽帧模式含 16 张图；全部保存判决与读取回放一致。相机/ToF 时龄 P95 分别 205/119、176/125、165/120 ms，短时顺序测量不能推导传输加速或物理端到端延迟。
- 使用已发现的同两块板进行端点角色拒绝/ToF UDP 不可用注入，39/39 仅测距、40/40 仅画面检查通过；不等同于拔线、断电及所有恢复路径实测。
- 实机界面保存了 19.989 秒、234 帧、2 个提示请求的无图记录，已检查列表、回放及安装检查布局；记录保留在手机供用户查看。未移动目标完成物理安装检查，未声称标定成功。
- 系统文档选择器实测导出到手机下载目录，导出文件与私有原记录 SHA256 一致；保留文件为 clip-0714dc3f-cb81-4977-99bb-28661493846a.json，用户可在 App 中删除私有记录并自行处理下载副本。
- 最终 debug / androidTest 构建与 lint 通过（0 errors / 19 warnings）；APK 43 / 10.14.0 的版本、签名、16 KB 静态检查通过，原位安装未清数据。手工 TalkBack、听感/震动感受、长时间及锁屏运行未测。
- 原始日志、回执、截图和 APK 归档回执：artifacts.local/hardware-bringup/app-evidence-20260923-*。测试临时文件已清理，真实保留记录不自动删除。

## v10.13.0 入口与反馈验证

- 7 项事件策略单测、8 项既有 ToF 几何单测通过。覆盖首次提醒、12 秒间隔、接近提示、短暂抖动、单次失联、恢复、回放与生命周期重置。
- 最终 debug / androidTest 构建通过；lint 0 errors / 19 warnings。
- S24 Ultra / Android 16：2 项入口和设置 Compose 测试、4 项客户端测试及 1 项无线实测通过；补充开关读屏名称后，最终 APK 上重新运行 2 项入口/设置测试通过。
- 无线实测窗口 10 秒，287/287 快照有效，203 个不同相机帧和 100 个不同 ToF 帧。只证明此次短时直连链路可用，不证明提醒效果或实物准确率。
- 截图检查了主界面；“更多功能”点击已进入原 MainActivity。系统 Launcher 解析与 PackageManager 测试均指向 HardwareDemoActivity。一次不带显式组件的 adb am start 探测未解析成功，随后使用系统解析得到的组件冷启动成功；不将该探测混作点击桌面图标测试。
- 最终 APK 已原位安装，版本 42 / 10.13.0；包名、签名、16 KB 静态对齐校验通过，未清用户数据。语音听感、实际震动感受、TalkBack 手工流程与长时间运行为 NOT_TESTED。
- 原始日志、无线回执、截图与归档回执位于 artifacts.local/hardware-bringup/app-entry-20260923-*。反馈策略来自工程规则，未重新训练或改变基础判决算法。

## v10.12.1 延迟优化验证

最终固定 10 Hz，保留 VGA 相机与原算法。45 秒热点测试 1300/1300 快照有效，
996 个不同相机帧、445 个 ToF 帧；ToF 序号推进 455。相机时龄上界中位数/P95
86/162 ms，ToF 为 71/132 ms。ToF 新读出至手机接收上界中位数/P95 为 14/44 ms。
相机采集至 JPEG 就绪中位数 36.6 ms、传输上界 14.9 ms、解码 5.4 ms、复制 2.3 ms。
各分段是独立分布，不能直接相加声称屏幕端到端延迟。

与旧 5 Hz HTTP 版本的 177/310 ms 相比，ToF 数据时龄上界明显缩小，但旧方法包含
整个 HTTP 请求 RTT，新方法使用时钟映射，部分差异来自估计界更紧，不能把百分比
差异当成严格物理响应改善。15 Hz 中间试验已结束；不再作为最终配置。
证据位于 `artifacts.local/hardware-bringup/wifi-latency-20260923/`，原始与汇总回执
分别为 `udp-10hz-receipt.json`、`udp-10hz-summary.json`。未证明新频率的实物测距精度。

6 项无线契约测试、连续真机测试、最终构建及 lint 通过，包版本/签名/16 KB 校验通过。
最终 Activity 的屏幕刷新回调已在真机显示；ToF 断连清除旧状态，重启后自动恢复。
最终安装包为证据目录下 `apk/BlindAssist-v10.12.1-debug-20260923-040736.apk`，
SHA256 `437A26013D1E30CE2020976631196C02F05D86CB78EE4F6CC375726288D8DA64`。

## 展示方法

选用基础 **ToF 完整区域支持与前方走廊相交**，不选 A*、学习增强或
校准分数筛选。来源是 `ba_camera_corridor.py::tof_readout`，无需模型权重、
RGB 语义类别或 CNH。原始 nominal-45° 模拟基线在已消费 96 帧中为
30 TP / 19 FP / 6 FN、5/6 事件；后续校准版本为 30/15/6，因此这里明确
选择较基础、有误报代价的版本。详见 [原始结果](../research/active/dtr-r0/nearfield/TOF_FOV45_20260920.md)。

硬件适配保留完整区域角范围，以径向测距区间换算轴向范围，再判定是否与
X±0.30 m、Y[-0.20,0.90] m、Z[0.30,3.00] m 相交。45°方形视场、
`0.13 + 0.06 × range` 距离半径和当前装配粗朝向都是展示工程假设，
没有完成实物标定；上面的仿真成绩不属于此硬件版本。它不规划绕行路线。

仅 status=5、有目标、quality=KNOWN 且距离>3 mm 的区域可贡献提示；
某一区无效不会覆盖其他独立有效区域。1–3 mm 是已有异常的排除规则，
不是实物精度保证。缺失、畸形网格、停止采集、断连、过期均为 UNKNOWN；
未提示也不代表可通行。极近处和视场外不在此走廊定义的覆盖承诺内。

## 旧 USB 中转使用（v10.11.0 验证）

1. Atom 相机和 XIAO ToF 接电脑；手机通过 USB 连接同一电脑并开启 ADB。
   XIAO 使用 `xiao-tof-8x8-v1`（64 区），CNH 暂不使用。
2. 保持已有硬件观测台在电脑 `127.0.0.1:8766` 运行；若未运行，在仓库执行
   `pwsh -NoProfile -File research/active/hardware-bringup/dashboard.ps1`。
3. 安装本次 APK；执行
   `pwsh -NoProfile -File research/active/hardware-bringup/app-demo.ps1 -Action Start`。
   脚本建立 USB 转发并开启有时限采集，显示实际串口和停止方式。
4. App 首页 → **眼镜设备** → **实物前视感知展示**，设备连接中关闭无线直连。
   展示页显示相机、原始 8×8 区域、有效数、支持区域和前方提示。
   红色是可能相交支持，中性格也可能无效，不能把颜色理解为安全地图。
5. 在固定朝向下，把较大障碍移入/移出前方视场，观察读数与提示。
   语音开关只影响实时提示；回放始终静音。相机图不叠加假想像素级 ToF 定位。
6. 结束执行
   `pwsh -NoProfile -File research/active/hardware-bringup/app-demo.ps1 -Action Stop`。
   它只清理其回执拥有的录制和 USB 映射，不关闭用户观测台。

数据按电脑接收时间配对，不是曝光同步。实时必须同时具有正在录制、相机与
ToF 新鲜、序号继续推进以及手机请求及时完成；1.5 秒是展示失效上限。
手机前后台切换会停止轮询/语音并清空旧状态。回放有显眼标记，不会冒充实时。

## v10.11.0 验证与产物（USB，不能作为 Wi-Fi 证据）

纯 Kotlin 几何测试覆盖完整区域、径向/轴向转换、8×8、质量拒绝及 UNKNOWN。
Android 客户端测试覆盖实时/回放、停止录制、序号冻结、慢请求和畸形网格。
实际完成：8 项几何单测、4 项三星 S24 Ultra Android 客户端测试通过；
debug APK、androidTest APK 构建通过，lint 为 0 errors / 18 warnings
（依赖、既有 MainActivity 固定方向、QNN 权限及未用资源，未发现本次新页面 lint 错误）。
APK 包名/39/10.11.0、签名和 16 KB 静态对齐校验通过，已原位升级手机，未清数据。

180 秒有界采集保存 4242 JPEG、919 ToF 帧，双路无解析错误或序号缺帧。
手机截图确认 8×8 显示，相机/ToF 帧号由 2659/3533 增至 3214/3669；
断开转发后旧画面和提示清除，恢复后实时重新显示；回放显眼标记且禁用语音。
中文 TTS 引擎初始化成功；没有录音或用户听感验收，不声称实测可听音量。
动态界面的 accessibility XML 抓取两次未成功，截图可用；不将截图当成正式 UI 自动化断言。

证据：`artifacts.local/hardware-bringup/demo-8x8-20260922/`；
双路原始记录：`artifacts.local/hardware-bringup/paired/dashboard-20260922T100458Z-99cb51/`。
APK：`apk/BlindAssist-v10.11.0-debug-20260922-180828.apk`（相对证据目录），
SHA256 `79DE5B2869D95FB9C0E8B08286F799A97DF1AA215B394CC8A05F729676C2C0E2`。
采集、手机轮询及任务转发已停止；用户原有观测台保留在此次记录回放状态。
单元测试、安装和实机显示只证明对应工程链路，不给出实物准确率或安全效果。

## v10.12.0 无线验证与产物

2026-09-23，S24 Ultra 手机热点，未建立 ADB reverse。45 秒预热后测量窗口内，
1295/1295 个快照可用，919 个不同相机帧（约 20.4 fps），230 个 ToF 帧（约 5.1 Hz）。
相机时龄上界中位数/P95 为 95/203 ms；ToF 读出时龄上界为 177/310 ms；
相机时钟误差界为 5 ms。这不是屏幕端到端延迟，也没有实物准确率结论。
原始回执为 `wireless-demo-20260922/wifi-live-receipt.json`（相对 hardware-bringup 产物根）。

6 项无线契约单测、4 项 USB 客户端真机测试、1 项显式启用的无线真机连续测试通过。
构建与 lint 通过（0 errors / 19 warnings）；版本、签名和 16 KB 校验通过。
ToF 重启时旧画面/提示清除；修复 I2C 总线恢复后已观察到自动恢复。
隔日首次发现测试因热点关闭失败，开启热点后通过；失败日志保留。
TalkBack、语音听感和屏幕发光延迟未测。

APK：`wireless-demo-20260922/apk/BlindAssist-v10.12.0-debug-20260923-034035.apk`，
SHA256 `09D585755A9DCF5B60F99BE5950673472A508B141D1D9412D0249EEEE2051648`。
原始固件备份、私密配网和测试证据只留本地，不上传。展示需要两板持续供电及手机热点。