HeimLink App 使用说明：固件升级
这一页讲 App 里的固件升级页怎么用。两类设备走两套协议：SecureLink 设备（温控器等）用 OTA wire v5，ShimLink 恒温阀（TRV）用阀门厂商定义的传输通道。两个页面布局相同，流程和按钮不同，下面分开讲。升级页的界面文案大部分是英文原文。
先看这三点
- 入口在设备设置页的「固件升级」按钮，设备必须已连接才能按。
- SecureLink 设备的升级分两段：先传固件、设备校验，再由你点「Apply firmware」确认应用；TRV 是传完即装，不需要二次确认。
- Android 上离开升级页升级会继续，底部有横幅可以点回来；iOS 上页面会提醒保持 App 在前台，锁屏或切走会中断传输。
页面布局
两种协议共用
| 区块 | 内容 |
|---|---|
| Upgrade | Device（设备名）、Status（Connected / Disconnected）、Protocol（OTA wire v5 或 ShimLink OTA）。 |
| Firmware | Current version（设备当前固件版本，连接后从设备读；读不到显示 Reading… 或 Unavailable，读取失败时下面有一行红字原因）、Target version（服务器上这个通道的版本）、Channel（当前固件通道）。 |
| Firmware channel | beta / stable 两段开关。内测包和开发包默认 beta；商店包默认 stable，解锁开发者选项后也能切到 beta。切换通道会重新检查更新。 |
| 状态行 | 带转圈的一行字，表示正在进行的阶段。 |
| 面板 | 带底色的结果卡片：绿色是成功或有更新，黄色是需要你确认或正在等设备，红色是失败，灰色是中性提示。 |
| 进度条 | 下载或传输时显示，左边是已传 / 总字节数，右边是百分比。 |
| 按钮 | 按当前状态出现，见下面的流程。 |
| Source | 只在检查失败或该通道没有发布时显示：Server（固件服务器域名）、Package（包类型）。 |
SecureLink 设备：OTA wire v5
温控器等 v0.8 协议设备
进入页面且设备已连接时，App 自动检查所选通道的更新，状态行显示「Checking for updates」，需要下载时是「Downloading firmware」。未连接时面板显示「Connect the device to check for updates」。检查结果有四种：
- Firmware x.y.z is available 下面一行「The artifact header is valid. The device will verify the complete package.」，按钮「Start upgrade」。
- Firmware is up to date 设备已是最新，按钮「Check again」。
- No firmware release has been published for this channel 这个通道没有发布，换通道或联系固件同事。
- Update check failed / Firmware download failed 下面是错误原文和固件包地址。多为网络问题，点「Check again」。
升级流程
- 点「Start upgrade」。App 独占这台设备，其它页面对它的操作都会被拒绝。
- 状态行「Preparing firmware」→「Preflight complete」。页面出现预检报告：升级包头部、产品、硬件、分区、最低版本、目标版本、包大小、签名、能力、信任策略，每项是「Passed | 详情」或「Failed | 详情」。任何一项 Failed 都会终止升级。
- 传输固件，进度条走到 100%。这一步最久，几十 KB 到几百 KB 的固件在几十秒到几分钟之间。
- 状态行「Verifying firmware」，设备自己校验整个包。
- 面板 Ready to apply x.y.z，下面写着预计校验与应用时间。按钮变成「Apply firmware」。不点这个按钮设备不会切换固件。
- 点「Apply firmware」。状态行「Applying firmware」，然后面板 Waiting for the device to restart，写着设备自己估计的重启和就绪时间；App 至少等 3 分钟。
- 设备重启回来后 App 自动重连并认证，状态行「Confirming the upgrade with the device」，最后面板 Upgrade succeeded: x.y.z，Current version 更新为新版本。
升级中「Cancel」按钮一直在，点了之后面板显示「Upgrade cancelled」。传输中途断开时面板显示 Reconnecting to the device，重连成功后从设备已收到的位置继续，不用重头传。
结果不确定与失败
| 面板 | 含义 | 下一步 |
|---|---|---|
| Upgrade x.y.z is ready but was not applied Confirm again to create a fresh, durable apply authorization. | 固件已经传到设备并校验过，但上次没有完成应用（比如 App 被杀）。 | 点「Confirm and apply」。 |
| Upgrade result is not confirmed: … | 应用已下发，但 App 没能在设备重启后确认结果。下面几行是诊断和 Transfer 编号。 | 设备重连后点「Verify result」。如果设备读出来的版本已经是目标版本，App 会自动补做确认。 |
| Firmware is up to date The device now runs x.y.z according to DIS. The App still has to confirm the earlier upgrade with the device. | 设备已经在跑新版本，只差最后的确认。 | 点「Verify result」。 |
| 设备报告 CODE：详情 / 其它红色面板 | 设备或 App 报了错。下面几行是诊断摘要与建议，「The device retained a durable transfer cursor.」表示设备记住了传输位置，重试能续传。 | 按诊断行的建议处理。每个错误码的含义与处理见 OTA v5 报错与处理。 |
ShimLink 恒温阀：TRV 升级
Protocol 显示 ShimLink OTA，界面文案是中文
设备连接后 App 自动检查并下载所选通道的最新固件镜像，状态行「正在下载固件…」，进度条显示下载进度。之后面板显示结果：
- 最新固件镜像已下载，可以开始安装。 按钮「安装固件」。
- 阀门固件已是最新（x.y.z）。 无需操作。
- 此通道尚未发布固件。 换通道或联系固件同事。
- 固件下载失败 / 无法检查固件更新 检查网络后点「下载最新固件」。
未连接时面板显示「请先连接阀门，再开始更新。」。「下载最新固件」按钮在检查过一次之后一直可用，用来重新检查。
升级流程
- 点「安装固件」。状态行「正在联系阀门…」。
- 进度条「正在发送固件… N%」。App 连续发送数据，阀门只在异常时回应。中途可以点「取消传输」。
- 状态行「正在校验…」，阀门校验整个镜像。
- 面板 固件已发送，阀门正在安装：阀门会重启并安装新固件，蓝牙连接暂时断开，通常需要 30 秒左右。不要重复安装。
- 阀门重连后面板 固件已更新，显示当前固件版本。如果阀门一直没回来，面板显示「阀门还没有重新连接。请确认阀门在手机附近；重新连接后这里会显示当前固件版本。」
帧间隔与从文件更新
按钮下方有「帧间隔（0–1000 毫秒）」输入框，默认 60，是相邻两帧之间的等待时间。丢包多、阀门报超时时调大；只能填整数，填错会提示范围。这个值会保存，下次升级沿用。
「高级：从文件更新」展开后有三项：「选择固件文件」（显示文件名和 KB 数）、「目标版本」（必须是 major.minor.patch，每段 0 到 255）、「开始更新」。用于测试还没发布到服务器的固件。页面提示：该传输通道由阀门厂商定义，未经加密，只用设备厂商提供的固件文件。
失败提示
| 提示 | 怎么处理 |
|---|---|
| 阀门电量低于 30%，无法升级。请更换电池后重试。 | 换电池。 |
| 阀门在校验后拒绝了该镜像。请确认固件文件正确后重试。 | 镜像不是这个型号的，或文件损坏。 |
| 阀门停止响应。请靠近设备后重试——传输会从断点继续。 | 靠近后再点「安装固件」，也可以把帧间隔调大。 |
| 传输过程中出现问题。请重试——传输会从断点继续。 | 直接重试。 |
| 服务器提供版本 x，当前安装的 y 无法比较。您仍然可以更新。 | 阀门报的版本格式与服务器不同，App 无法判断新旧，由你决定是否装。 |
离开升级页之后
后台横幅与前台提醒
升级不随页面关闭而停止。回到设备列表或别的页面时，屏幕底部会有一条蓝色横幅，写着「正在升级 设备名」和当前阶段（正在准备升级… / 正在发送固件 · N% / 正在校验固件… / 固件已传完，打开升级页确认应用 / 正在应用固件… / 正在等待设备重启… / 正在重新连接设备… / 设备正在安装固件…），下沿是进度条，点一下回到升级页。Android 上通知栏同时有一条「固件升级」通知，切到别的 App 传输也继续。
iOS 上升级页会显示黄色面板「升级期间请保持 App 在前台」：锁屏或切换到其他 App 会中断传输。中断后回到页面重试即可续传。
升级期间的限制
- 被升级的设备处于独占状态，控制页和设备设置里的操作会提示「设备正在升级固件，请等升级结束后再试。」。
- 列表里其它设备的自动连接暂停，等这次升级结束。
- 提示「请先重新连接并认证设备，再进行升级。」或「该设备保存的身份已不匹配。请移除后重新配对。」时，先回设备列表把连接弄好再进升级页。