固件升级指引

FIRMWARE UPGRADE

v1.9.8p 网页模式切换与 OTA 升级

2026-09-25：本版自动化回归1286通过、8项明确跳过，当前构建被工具链下载阻塞，尚无本轮固件包。以下是构建及硬件验收完成后的客户升级说明，不代表已正式发布；不要使用历史同名镜像冒充本候选。候选关闭实验解耦同步栈，保留原有 KabuSync，不承诺同房间立体声精度达标。实际检查结果见 docs/validation_v1.9.8p.md。

适用设备与文件

适用于本项目 ESP32-S3 N16R8、16 MB Flash 双 OTA 分区设备。客户所称 v1.9.6p 对应发布包 v1.9.6Plus，可直接升级至本版，无需中间版本。

网页升级用 kabu_ota_v1.9.8p.bin。
kabu_factory_v1.9.8p.bin 用于 USB 工厂烧录，不能上传到网页 OTA。
同名 .sha256 文件用于核对下载完整性。
版本、大小及散列见 kabu_v1.9.8p.manifest.json。

用户升级步骤

停止音乐播放；KabuSync 请先停止组播放。
打开设备原管理地址，在“固件升级”中选择 OTA 文件并上传。
保持供电和网络，等待校验及重启；此时不要按模式键或进行其他设置。
约 20 秒后刷新原地址，确认固件版本为 1.9.8p。
主页连接状态下方应出现“设备模式”卡片。无需另刷网页或 SPIFFS。

若上传失败，保留错误信息，重新访问管理页确认旧版本仍可用后再试。重启期间短暂断连属于正常行为；长时间不可达时先确认设备网络地址。新固件首次启动检查未通过时，Bootloader 会在下次启动回退到上一个可用应用。

使用模式切换

选择 AirPlay、网络电台、DLNA 或 KabuSync，再点击“切换模式”。当前播放存在时会请求确认。进入或退出 KabuSync 需要重启，并可能影响组播放。普通三模式之间使用现有热切换流程；语音和灯效与实体按键一致。

“当前模式”由设备回报。通过实体按键、MQTT 或其他网页进行的切换也会同步显示。 “请求已接受”不等于完成；页面会继续显示切换、重启、等待网络或失败状态。请求失去响应时只查询状态，不会自动重复发送模式命令。

兼容与实现

分区及 NVS 布局保持 v1.9.6Plus 兼容，OTA 不擦除 Wi-Fi、设备名、EQ、电台等配置。
六个管理页面和共享 CSS 随应用固件发布，直接从当前应用的只读资源提供服务。

SPIFFS 中旧网页不再用于管理页；电台与提示音数据仍由原流程管理。

浏览页面、读取模式不会切换或暂停播放；用户明确确认切换才会结束当前音源。
OTA 与模式命令共用互斥门禁。上传失败释放门禁，上传成功保持占用直至重启。
本版继承 v1.9.8 已记录限制：HomePod 绝对声场对齐仍需专门实测，弱网络 HTTP 请求可能超时。

开发者验证与发布

本机使用已有 Python 3.11 的 ~/.venvs/kabu-release，按 requirements-test.txt 固定依赖；不要用旧 Python 3.9 环境的专项通过代替全量验证。macOS 的 tccbox 需有效系统头及运行库搜索路径，本轮实际命令如下（每轮另选新的日志和临时目录）：

export PATH="$HOME/.venvs/kabu-release/bin:$PATH"
export LIBRARY_PATH="$HOME/.venvs/kabu-release/lib/python3.11/site-packages/tccbox/tcc_dist/lib"
git diff --check
python -m pytest tests -q
KABU_BROWSER_TESTS=1 KABU_BROWSER_CHANNEL=chromium python -m pytest tests/test_web_mode_browser.py -q
pio run -e airplay2
pio run -e airplay2 -t buildfs

先完成重新配置，再按下述来源流程构建；正式候选的应用 config/sdkconfig.h 必须关闭实验解耦同步、FI及Sendspin测试注入。airplay2-fi 和实验ON仅用于独立编译回归，不交付；本地 .pio 存在其他构建时使用独立 PLATFORMIO_BUILD_DIR。

开发写入仅使用另行确认的 USB app-only 流程。禁止根据这里的客户OTA说明自行升级台架、运行通用 pio -t upload/uploadfs，或覆盖现存工厂镜像。软件通过后仍须完成该候选硬件和客户升级验收。

发布构建前必须先用 scripts/v198p_validation_evidence.py capture 保存构建输入快照；构建后立即用 verify --manifest <same-source-manifest> 确认源树未变化。调用 scripts/package_release.py 时必须传入同一份 --source-manifest，且 --app、--factory 必须来自这次通过门禁的 airplay2 构建。每次验证使用新的 output/validation/<version>-<build-id>/<stage>/<run-id>/ 目录，不能覆盖既有证据。

浏览器测试使用 Playwright Chromium 和模拟设备服务，不访问真实局域网设备；不得依赖 Windows Edge。打包脚本检查应用内嵌版本、ESP32-S3 芯片标识、旧 OTA 槽容量，以及工厂镜像中应用与分区是否匹配，并将构建前源文件 manifest 绑定到固件 manifest。打包成功只代表产物检查通过，不代表真机验收完成。真机与播放结论见本版验证报告。

使用指南固件下载返回首页