HeimLink App 蓝牙层架构

App 内蓝牙层的职责、模块与规则 · 定稿 · 2026-09-26

HeimLink 用手机蓝牙管理多台设备：随时知道每台设备是否在附近，按需连接其中一台完成控制、配网或 OTA，并在设备重启、换地址、断链后可靠地找回它。蓝牙层是 App 里夹在原生蓝牙库与业务代码之间的那一层，只仲裁射频资源，止于链路可用，不认识任何协议报文。它上面是按协议族实现的设备会话层，把链路变成可控制的会话；再上面是业务层，只声明需求。本页描述定稿的目标架构；已经实现的部分和迁移顺序见第十节。

一 · 在 App 里的位置

App 分四层，每层只依赖它下面的层。蓝牙层和设备会话层都属于基础库，蓝牙层是原生蓝牙库的唯一调用方。

业务代码指设备列表、控制页、配网、OTA 和 WebView Bridge。它们不直接操作原生扫描和连接，只声明需求：要找哪台设备、要连接哪台设备、要独占哪台设备，然后拿到控制会话去用。协议内容（广播格式、AUTH、OTA 帧）以 HeimLink 协议规范为准，由设备会话层实现；为建链的每一步计时、超时后取消原生操作、记录链路状态，才是蓝牙层的事。

二 · 手机蓝牙的硬约束

来自平台文档、原生库源码、协议规范或真机日志，设计必须满足。

#	约束	对设计的影响
F1	手机只有一个 BLE 射频；原生库同一时刻只维护一个扫描。	多个业务的扫描需求必须合并到一个原生扫描上。
F2	Android 7.0 起，一个 App 在 30 s 内最多启动 5 次扫描，按最近 5 次已停止扫描的启动时间判定。较早版本超出后不报错也收不到结果；较新版本回调 `SCAN_FAILED_SCANNING_TOO_FREQUENTLY`（值 6，Android 13 起公开），原生库把它放在停扫事件的 `status` 字段里。	扫描额度由一处计数；系统回调是权威信号；扫描要长期保持，不能反复启停。
F3	Android 的 `connectGatt` 没有超时参数，协议栈约 30 s 后才报失败；JS 侧停止等待不会取消原生连接。	每一步超时后必须主动断开挂起的 GATT，不能只停止等待。
F4	Android 保留 App 建立的每一条 GATT 连接；被连接的设备通常停止广播。	每条链路都要记录在 App 状态里，否则设备会在扫描中"消失"。
F5	使用随机静态地址的设备每次启动都可能换地址。	地址不是身份，只用来挑候选。
F6	设备重启时，手机要等监督超时才发现链路断开；重启前设备可能仍用旧地址广播。	找回设备只接受需求提交之后收到的广播。
F7	部分 Android 厂商的省电服务会强制停止后台 App，连接随之断开。	只保证前台。
F8	Android 息屏后、iOS 进入后台后，不带服务 UUID 过滤的扫描会被限制或停止。	后台需要服务 UUID，见 F13。
F9	设备的应用层请求可能收到链路层确认，却得不到应答。	事务超时要覆盖写入与等待应答的全程。
F10	Android 会把持续超过 30 min 的无过滤扫描降级为 opportunistic 模式，之后只在其它 App 扫描时才有结果，且不产生任何事件（待真机验证）。	调度器自己计时，在期限前主动重启一次。
F11	iOS 的断开事件只带 CoreBluetooth 错误码，没有 HCI 原因码。	失败分类要有 iOS 一列。
F12	原生库在 Android 上已按外设串行执行 GATT 操作。	蓝牙层的事务定义在往返级别，不重做 GATT 队列。
F13	现行 19 B 广播只有 Flags、本地名和厂商数据，没有服务 UUID；Company ID 是开发暂用的 0xFFFF。	系统的服务 UUID 过滤匹配不到设备；按占位 ID 过滤不能识别设备。两端都不过滤，后台留待协议改动。

三 · 为什么要有这一层

从 0.4.12 到 2026-09-24，扫描、连接和重连相关的修复有 14 次，每次都修在出问题的业务路径上：配网和 OTA 各自处理扫描次数限制，设备匹配规则在四处各写一份，连接超时只保护传了参数的调用方，等待设备应答的编排没有总超时。同类问题在另一条路径上重复出现，因为规则由调用方遵守，而不是由共享层强制执行；各业务路径的测试也覆盖不到"配网刚结束、OTA 开始、列表页仍在扫描"这类组合。

一句话

把"何时启动扫描、何时建链、多久算超时、哪台设备是同一台、谁在独占"这些决定从业务代码收回到蓝牙层，让每条规则只有一份实现、一套测试；协议报文一律留在设备会话层。

四 · 三层与模块

蓝牙层内部分七个模块。上面两个回答"设备在哪、是谁"，中间四个管理射频资源，最下面一个负责可观测。

模块	职责	对上暴露什么
原生适配	调用原生库、转发原生事件（发现、扫描停止、断开、通知、蓝牙开关）。状态码原样转发，不做解释。	不暴露；只有扫描调度与连接管理可以调用。
扫描调度	合并五种扫描需求到一个原生扫描上，执行扫描额度，分发候选，处理暂停与重启。	`requestScan(need)`，返回可释放的句柄。
在场信息	只记事实：每台已保存设备最近一次被看到的时间、信号强度和地址。"在不在场"的判定归设备列表。	只读。
设备匹配	把一条广播对应到候选：唯一、多个或无。SecureLink 按协议标识、绑定标志、品类和 discriminator 匹配，ShimLink 按其协议规定的字段匹配。全 App 只有这一份实现。	候选随广播一起投递。
连接管理	链路状态机，止于 `connected`；每一步有默认超时，超时即取消原生操作；建链原语 `acquireLink`；断开原因分类上报，自己不重连。	`acquireLink(need, { deadline })`，返回已 `connected` 的链路和候选。
链路事务	同一链路同时只有一个出站往返，超时取消，调用方放弃即释放；设备推送的通知不受限制。	`link.transaction(fn, { timeoutMs })`、`link.subscribe`。
独占管理	配网、OTA 持有一台设备的令牌，每台设备一个持有者；自动重连和状态同步动作前先查询。	`acquireDevice(target, owner)`、`isHeld(target)`。
诊断	维护只读快照和最近事件列表，每个决定都有日志。	调试工具台的 BLE 标签页订阅快照。

设备会话层在蓝牙层之上，按协议族各一份：SecureLink 的应用帧信道、ShimLink 的安全帧、按特征值建模的数据点。它在 connected 的链路上用事务完成认证、订阅通知、发首个 GET_STATE，然后发布控制会话；它把业务或 Bridge 给的截止时间传给建链和每个事务，Bridge 契约的默认值不变；它还提供自动重连这一共用行为，控制页和 OTA 使用，设备列表不使用。

五 · 十条原则

蓝牙层止于链路，不认识协议。 状态机止于 connected，不解析任何报文；会话层用它的原语实现协议。
业务代码不直接操作原生扫描和连接。 用 ESLint 限制原生适配的导入方，靠工具而不是约定。
原生扫描只有一个，业务需求合并到它上面，不过滤，没有优先级。
Android 扫描次数限制由蓝牙层统一执行。 系统的限频回调是权威信号，JS 侧计数只用于预判。
找设备时扫描持续到任务结束，只在建链暂停和 30 min 期限两种情况下重启。
同一时间只有一条链路，每一步都有默认超时，超时即取消原生操作；截止时间自上而下传递。
设备身份只由认证确定。 候选可能不止一个，凭据只在候选唯一或全部被拒时才标为可疑。
同一条链路上的事务串行，每个事务都有超时；设备推送的通知不受限制。
独占由蓝牙层管理，持有令牌每台设备一个，自动重连先问它。
每个决定都能从日志和调试工具台看到。

六 · 扫描调度：一个原生扫描

设备列表、控制页、配网、OTA 的需求合并到同一个原生扫描上；各需求按自己的种类收候选。

五种需求，匹配由调度器统一执行。 全部已保存设备的在场；找一台已保存设备；可配对候选列表；按 SetupCode 的 discriminator 找一台待配对设备；按系统连接标识找回一台设备，只在一次配网会话内部使用。调用方不写判断。
不过滤，没有优先级。 原生参数固定：无过滤条件，允许重复，Android 用 LowLatency。现行广播没有服务 UUID，Company ID 又是占位值，过滤既匹配不到也识别不了设备。
只投递需求提交之后收到的广播。 提交前缓存的发现结果不投递，找回设备时不会撞上重启前的旧地址（F6）。
只在两种情况下重启。 建链期间暂停，链路建立或失败后恢复；Android 上连续运行接近 30 min 时主动重启一次。两者都计入额度，由调度器统一安排。
系统停止扫描后的重启有条件。 限频回调按额度重排；其它情况在额度允许的最早时间重启，但只在 App 处于前台时进行，回到前台按在册需求恢复。
最后一个需求释放后延迟几秒再停。 页面切换时不再反复启停消耗额度。

七 · 链路：状态机、建链与事务

蓝牙层的状态机到 connected 为止；认证和控制会话是会话层在它之上做的事。

状态	进入条件	超时	超时或失败后
`idle`	初始；断开完成	—	—
`connecting`	调用连接；调度器同时暂停原生扫描	10 s	取消原生连接，回到 `idle`
`discovering`	链路建立；包含服务发现、MTU 协商两步	每步 10 s	断开，回到 `idle`
`connected`	链路可用：服务已发现、MTU 已知。会话层从这里开始认证或配对，通知订阅也在此之后由会话层完成	—	—
`disconnecting`	App 请求断开，或另一台设备要建链	5 s	以系统连接列表为准清理状态，回到 `idle`

建链原语 acquireLink(need, { deadline })。 内部完成提交扫描需求、按发现顺序取候选、走状态机建链、建链失败按 1、2、4 s 最多重试 3 次、到截止时间放弃。它不认证，也不判断候选对不对；调用方认证后判定"不是这台"可以调用 reject() 换下一个候选。
链路事务 link.transaction(fn, { timeoutMs })。 租约式：会话层在 fn 内自己写入、等应答，蓝牙层保证同一链路同时只有一个 fn 在跑。默认 10 s，OTA 的数据帧、VERIFY、APPLY 由独占方指定。调用方先放弃就释放链路，后续事务不排在它后面；同一链路连续两个事务超时就断开并上报"链路超时"，独占方可以关掉这条规则。
默认超时是蓝牙层常量，两端同值。 业务或 Bridge 的截止时间作为总上限自上而下传递，每一步取默认值与剩余时间中较小者；Bridge 契约里 connect 15 s、读写 8 s 的默认值不动。
连接记录以设备为键。 服务、特征、MTU 和当前状态都属于这条记录，不再有与设备无关的全局字段。

八 · 找回设备

设备重启或链路断开后找回设备，由会话层的自动重连执行；OTA、控制页、配网后的首次连接共用。

确认旧链路已断。 可预期的重启（OTA 收到 REBOOT_SCHEDULED）先等设备断开链路，最长 rebootInMs 加余量，再由 App 主动断开。
查询独占。 目标设备被别的持有者独占时不动。
调用建链原语。 蓝牙层提交扫描需求、只接受提交之后的广播、按发现顺序逐个建链、建链失败按 1、2、4 s 重试，直到截止时间。
认证。 在事务里发 AUTH 或 REJOIN。凭据被拒时，候选唯一或全部候选都已被拒才标记凭据可能失效；还有未尝试的候选就换下一个。其它失败回到第 3 步。
认证成功后更新地址和身份记录，订阅通知，发首个 GET_STATE，发布控制会话。

九 · 失败怎么分类

断开原因：蓝牙层只分类上报，不重连

原因	Android `status`	iOS `CBError`	典型来源	上报为
对端断开	`0x13` Remote User Terminated Connection	7 peripheralDisconnected	设备主动断开、重启	可重连
链路超时	`0x08` Connection Timeout	6 connectionTimeout	超出范围、设备重启、连续两个事务超时	可重连
建链失败	`0x3E` Connection Failed to be Established、`133` GATT_ERROR	10 connectionFailed	建立链路失败	在建链原语内重试，最多 3 次后作为建链失败返回
App 发起	按连接管理记录的"断开由 App 请求"标记判定，不看原因码		释放链路、超时取消	不可重连
蓝牙关闭、权限被拒	由蓝牙状态与权限事件判定，不看原因码		系统	不可重连；清空扫描和连接状态，恢复后按在册需求恢复

未列入上表的原因码记录名称后按"对端断开"上报。要不要找回设备，由会话层的自动重连按业务是否仍持有会话决定。

事务失败

情况	处理
单个事务超时	调用方收到超时错误，链路释放
调用方先于超时放弃事务	事务取消并释放链路，后续事务不排在它后面
同一链路连续两个事务超时	断开链路并上报"链路超时"；被独占时由持有者决定
设备返回协议错误	交给会话层处理，蓝牙层不重试

十 · 现状与迁移

目标架构分十一步落地，每步单独提交、单独验证，改到扫描或链路的步骤各跑一次 TRV901Z 和 BK7238 的真机回归。截至 2026-09-26 尚未开始迁移；已具备的部分列在右栏。

步骤	内容	完成标志	现已具备
0	GATT 写入加默认超时；连接未传超时时使用默认值	"写入永不回调""连接永不回调"的测试通过	连接超时只在调用方传参时生效；等应答已有 10 s 超时
1	扫描调度与扫描额度统一；旧的扫描接口转接为带自动释放的需求；迁移 OTA 重连和配网扫描；诊断快照随本步起步	原则 3、4 的核对测试通过	额度计数已在原生适配中，只有配网和 OTA 使用
2	迁移其余扫描调用，五种需求类型定型，ESLint 限制按文件列表写	原则 2 中关于扫描的核对通过	—
3	设备匹配合并为一份实现	原则 7 的核对通过	四处各有一份
4	链路状态机止于 connected，默认超时，断开分类，建链前暂停扫描	原则 6 的核对测试通过	连接新设备前释放旧连接、断开只影响所属设备已实现；三条路径已是先停扫再连接
5	acquireLink；自动重连、OTA 重连、配网后首连改用它	两个同 discriminator 候选的场景测试通过	—
6	link.transaction；安全信道、ShimLink 帧、数据点读写改用它，删各自的互斥标志	"请求永不应答""调用方先放弃"的测试通过	—
7	独占令牌；自动重连先查询令牌，删手写的暂停判断	自动重连中不再有针对 OTA 的特判	OTA 期间暂停自动重连是手写判断
8	在场只记事实，设备列表自己判定	设备列表不再直接解释扫描结果	—
9	会话层代码搬到独立目录，ESLint 改按目录	蓝牙层目录不再导入协议常量	—
10	调试工具台 BLE 标签页收口	快照里的每类事件都能在标签页看到	—

待确认事项

iOS 的默认值：Core Bluetooth 的连接请求不会自行超时，默认超时同样作用于 iOS；数值需 iOS 真机验证，不改结构。
F10 在目标机型上的表现：未验证。若不存在降级，30 min 重启无害，规则保留。
协议侧：广播追加服务 UUID：后台扫描、息屏扫描、iOS 后台重连的共同前提，属于空中协议改动。协议改完后过滤在两端同时引入，作为调度器的固定策略。
产品契约的广播间隔字段：设备列表判定窗口的依据，待固件给出 TRV901Z 亮屏与息屏的广播间隔；蓝牙层不受影响。

HeimLink App Bluetooth Layer Architecture

Responsibilities, modules and rules of the BLE layer inside the app · final · 2026-09-26

HeimLink manages several devices over the phone's Bluetooth: it needs to know at any time whether each device is nearby, connect to one of them on demand for control, pairing or OTA, and reliably find a device again after it reboots, changes address or drops the link. The BLE layer is the part of the app that sits between the native Bluetooth library and the feature code. It only arbitrates the radio, stops at a usable link, and knows no protocol messages. Above it sits the device session layer, one implementation per protocol family, which turns a link into a controllable session; above that, feature code only declares what it needs. This page describes the agreed target architecture. What is already implemented, and the migration order, are in section 10.

1 · Where it sits in the app

The app has four layers; each depends only on the layer below. The BLE layer and the device session layer both belong to the libraries layer; the BLE layer is the sole caller of the native Bluetooth library.

Feature code means the device list, the control screen, pairing, OTA and the WebView bridge. None of them drive the native scan or connection directly. They declare needs: which device to find, which device to link to, which device to hold exclusively, and then use the control session they get back. Protocol content (advertising formats, AUTH, OTA frames) follows the HeimLink protocol specifications and is implemented by the device session layer. Timing every step of link setup, cancelling the native operation on timeout and recording link state are what the BLE layer does.

2 · Hard constraints of phone Bluetooth

From platform documentation, native-library source, the protocol specification or device logs. The design must satisfy all of them.

#	Constraint	Effect on the design
F1	The phone has a single BLE radio; the native library keeps at most one scan at a time.	Scan requests from several features must be merged into one native scan.
F2	Since Android 7.0 an app may start at most 5 scans within 30 s, judged by the start times of the last 5 scans that have stopped. Older versions report no error and simply deliver no results; newer versions call `onScanFailed` with `SCAN_FAILED_SCANNING_TOO_FREQUENTLY` (value 6, public since Android 13), which the native library exposes in the `status` field of the scan-stop event.	The quota is counted in one place; the system callback is the authoritative signal; scans stay up instead of restarting.
F3	Android's `connectGatt` takes no timeout; the stack reports failure only after about 30 s, and giving up on the JS side does not cancel the native connection.	After every step's timeout the pending GATT must be disconnected explicitly; ceasing to wait is not enough.
F4	Android keeps every GATT connection the app creates; a connected device usually stops advertising.	Every link must be recorded in app state, otherwise the device "disappears" from scans.
F5	A device using a random static address may change it on every boot.	The address is not the identity; it only selects candidates.
F6	When a device reboots, the phone only notices after the supervision timeout; before rebooting, the device may still advertise with the old address.	Finding a device again accepts only advertisements received after the request was made.
F7	Some Android vendors' power-saving services force-stop background apps, dropping the connection.	Only the foreground is guaranteed.
F8	With the screen off on Android, or in the background on iOS, scans without a service-UUID filter are throttled or stopped.	Background needs a service UUID; see F13.
F9	A device may acknowledge an application-layer request at the link layer and still never answer it.	Transaction timeouts cover both the write and the wait for a reply.
F10	Android downgrades an unfiltered scan that runs longer than 30 min to opportunistic mode, after which results arrive only while other apps are scanning, with no event of any kind (to be verified on real devices).	The scheduler keeps its own timer and restarts the scan once before the limit.
F11	iOS disconnect events carry only CoreBluetooth error codes, not HCI reason codes.	Failure classification needs an iOS column.
F12	On Android the native library already serialises GATT operations per peripheral.	The BLE layer's transactions work at the level of round trips; it does not re-implement a GATT queue.
F13	The current 19-byte advertisement carries only Flags, the local name and manufacturer-specific data, with no service UUID; the Company ID is the development placeholder 0xFFFF.	The OS service-UUID filter cannot match the device, and filtering on a placeholder ID identifies nothing. Neither platform filters; background work waits for a protocol change.

3 · Why this layer exists

Between 0.4.12 and 2026-09-24 there were 14 fixes related to scanning, connecting and reconnecting, each made in the feature path where the problem showed up: pairing and OTA each handle the Android scan limit on their own, the device-matching rule is written four times, the connection timeout only protects callers that pass a parameter, and the orchestration that waits for a device reply has no overall timeout. The same problem reappears on another path because the rules are followed by callers instead of being enforced by a shared layer, and each path's tests cannot cover combinations such as "pairing just finished, OTA starts, the list screen is still scanning".

In one sentence

Take the decisions "when to start scanning, when to set up a link, how long counts as a timeout, which device is the same device, who holds a device" out of feature code and back into the BLE layer, so that every rule has one implementation and one set of tests; protocol messages stay in the device session layer.

4 · Three layers and the modules

The BLE layer has seven modules. The top two answer "where is the device and which one is it", the middle four manage the radio, and the bottom one provides observability.

Module	Responsibility	What it exposes upward
Native adapter	Calls the native library and forwards its events (discovery, scan stop, disconnect, notifications, adapter state). Status codes pass through uninterpreted.	Nothing; only scan scheduling and connection management may call it.
Scan scheduling	Merges the five kinds of scan need onto one native scan, enforces the scan quota, dispatches candidates, handles pauses and restarts.	`requestScan(need)`, returning a releasable handle.
Presence	Facts only: when each saved device was last seen, with RSSI and address. Whether a device counts as present is decided by the device list.	Read-only.
Device matching	Maps an advertisement to candidates: one, several or none. SecureLink matches on protocol identifier, bound flag, category and discriminator; ShimLink on the fields its protocol defines. There is exactly one implementation in the app.	Candidates travel with the advertisement.
Connection management	Link state machine ending at `connected`; every step has a default timeout that cancels the native operation; the `acquireLink` primitive; classifies and reports disconnects, never reconnects on its own.	`acquireLink(need, { deadline })`, returning a `connected` link and its candidate.
Link transactions	One outbound round trip at a time per link, cancelled on timeout, released when the caller gives up; device notifications are not affected.	`link.transaction(fn, { timeoutMs })`, `link.subscribe`.
Exclusive access	Pairing and OTA hold a token for one device, one holder per device; auto-connect and state sync ask before acting.	`acquireDevice(target, owner)`, `isHeld(target)`.
Diagnostics	Keeps a read-only snapshot and a list of recent events; every decision is logged.	The BLE tab of the debug console subscribes to the snapshot.

The device session layer sits above the BLE layer, one implementation per protocol family: the SecureLink frame channel, ShimLink secure frames, and data points modelled as characteristics. On a connected link it uses transactions to authenticate, subscribe to notifications and send the first GET_STATE, then publishes a control session. It passes the deadline given by the feature or the bridge down to link setup and to every transaction, so the bridge contract's defaults stay unchanged. It also provides auto-connect as a shared behaviour, used by the control screen and OTA but not by the device list.

5 · Ten principles

The BLE layer stops at the link and knows no protocol. Its state machine ends at connected and parses no messages; the session layer implements the protocol with its primitives.
Feature code never drives the native scan or connection directly. An ESLint rule restricts who may import the native adapter: tooling, not convention.
There is one native scan, feature needs are merged onto it, with no filter and no priority.
The Android scan limit is enforced by the BLE layer alone. The system's throttle callback is the authoritative signal; the JS-side counter is only a prediction.
When looking for a device, the scan lasts until the task ends; it restarts only for the link-setup pause and the 30 min limit.
One link at a time; every step has a default timeout that cancels the native operation; deadlines are passed down from the caller.
Device identity is established only by authentication. There may be several candidates; credentials are flagged only when the candidate was the only one or all were rejected.
Transactions on one link run one at a time, each with a timeout; device notifications are not affected.
Exclusive access is managed by the BLE layer: one token holder per device, and auto-connect asks it first.
Every decision can be seen in the logs and the debug console.

6 · Scan scheduling: one native scan

The needs of the device list, the control screen, pairing and OTA are merged onto the same native scan; each need receives candidates by its own kind.

Five kinds of need, matched by the scheduler. Presence of all saved devices; find one saved device; the list of commissionable candidates; find one device to pair by the discriminator in its SetupCode; find one device again by its system connection identifier, used only inside a single pairing session. Callers write no matching logic.
No filter, no priority. Native parameters are fixed: unfiltered, duplicates allowed, LowLatency on Android. The current advertisement has no service UUID and the Company ID is a placeholder, so a filter could neither match nor identify the device.
Only advertisements received after the need was registered are delivered. Discoveries cached before that are not, so finding a device again never runs into the pre-reboot address (F6).
Restarts happen in two cases only. The scan pauses while a link is being set up and resumes once the link is up or has failed; on Android it restarts once when it has run for almost 30 min. Both count against the quota and are scheduled by the scheduler.
Restarting after the system stops the scan is conditional. A throttle callback waits for quota; other cases restart at the earliest moment the quota allows, but only while the app is in the foreground; on returning to the foreground the registered needs are resumed.
After the last need is released the scan lingers a few seconds. Switching screens no longer burns quota on repeated start/stop cycles.

7 · Links: state machine, link setup and transactions

The BLE layer's state machine ends at connected; authentication and the control session are the session layer's work on top of it.

State	Entered when	Timeout	On timeout or failure
`idle`	initial; a disconnect has completed	—	—
`connecting`	connect is called; the scheduler pauses the native scan at the same time	10 s	cancel the native connection, back to `idle`
`discovering`	link established; covers service discovery and MTU negotiation	10 s per step	disconnect, back to `idle`
`connected`	link usable: services discovered, MTU known. The session layer starts authentication or pairing here; notification subscriptions are also its job from here on	—	—
`disconnecting`	the app requests a disconnect, or another device is about to be linked	5 s	reconcile state with the OS connection list, back to `idle`

The link-setup primitive acquireLink(need, { deadline }). Internally it registers the scan need, takes candidates in discovery order, drives the state machine, retries link-setup failures after 1, 2 and 4 s at most 3 times, and gives up at the deadline. It neither authenticates nor judges whether a candidate is the right device; after authenticating, the caller may call reject() to move to the next candidate.
The link transaction link.transaction(fn, { timeoutMs }). A lease: the session layer writes and waits for replies inside fn, and the BLE layer guarantees that only one fn runs on a link at a time. Default 10 s; OTA data frames, VERIFY and APPLY get values from the exclusive holder. When the caller gives up first, the link is released and later transactions do not wait behind it; two consecutive timeouts on one link disconnect it and report "link timeout", a rule the exclusive holder may switch off.
Default timeouts are BLE-layer constants, equal on both platforms. The deadline given by the feature or the bridge is the overall cap and is passed down; every step takes the smaller of its default and the remaining time. The bridge contract's defaults, 15 s for connect and 8 s for reads and writes, stay as they are.
The connection record is keyed by device. Services, characteristics, MTU and the current state all belong to that record; there are no device-independent global fields any more.

8 · Finding a device again

After a reboot or a dropped link, the session layer's auto-connect finds the device again. OTA, the control screen and the first connection after pairing share this flow.

Confirm the old link is down. For an expected reboot (OTA received REBOOT_SCHEDULED), wait for the device to drop the link, at most rebootInMs plus a margin, then let the app disconnect.
Ask the exclusive token. If another holder owns the device, do nothing.
Call the link-setup primitive. The BLE layer registers the scan need, accepts only advertisements received afterwards, links candidates one by one in discovery order and retries link-setup failures after 1, 2 and 4 s, until the deadline.
Authenticate. Send AUTH or REJOIN inside a transaction. When the credentials are rejected, they are flagged as possibly invalid only if the candidate was the only one or all candidates have been rejected; otherwise move to the next candidate. Any other failure goes back to step 3.
After authentication succeeds, update the address and identity record, subscribe to notifications, send the first GET_STATE and publish the control session.

9 · Classifying failures

Disconnect reasons: the BLE layer classifies and reports, never reconnects

Reason	Android `status`	iOS `CBError`	Typical source	Reported as
Peer disconnected	`0x13` Remote User Terminated Connection	7 peripheralDisconnected	the device disconnected on purpose, or rebooted	reconnectable
Link timeout	`0x08` Connection Timeout	6 connectionTimeout	out of range, device rebooted, two consecutive transaction timeouts	reconnectable
Link setup failed	`0x3E` Connection Failed to be Established, `133` GATT_ERROR	10 connectionFailed	the link could not be established	retried inside the link-setup primitive, returned as a link-setup failure after 3 attempts
App-initiated	decided by connection management's own "disconnect requested by the app" marker, not by reason code		link released, cancelled on timeout	not reconnectable
Bluetooth off, permission denied	decided by adapter-state and permission events, not by reason code		system	not reconnectable; clear scan and link state, resume the registered needs once restored

Reason codes not listed above are logged by name and reported as "peer disconnected". Whether to find the device again is decided by the session layer's auto-connect, according to whether the feature still holds the session.

Transaction failures

Case	Handling
A single transaction times out	the caller receives a timeout error and the link is released
The caller gives up before the timeout	the transaction is cancelled and the link released; later transactions do not wait behind it
Two consecutive transactions on one link time out	disconnect the link and report "link timeout"; while the link is held exclusively, the holder decides
The device returns a protocol error	handed to the session layer; the BLE layer does not retry

10 · Current state and migration

The target architecture lands in eleven steps, each committed and verified on its own; steps that touch scanning or links each get a real-device run on TRV901Z and BK7238. As of 2026-09-26 the migration has not started; what already exists is listed in the right-hand column.

Step	Content	Done when	Already in place
0	Default timeout for GATT writes; connect uses the default when the caller passes none	tests for "write never calls back" and "connect never calls back" pass	the connect timeout only applies when the caller passes it; waiting for a reply already has a 10 s timeout
1	Unify scan scheduling and the quota; route the old scan calls through the scheduler as auto-released needs; migrate the OTA reconnect and pairing scans; start the diagnostics snapshot	verification tests for principles 3 and 4 pass	the quota counter lives in the native adapter, but only pairing and OTA use it
2	Migrate the remaining scan calls; fix the five kinds of need; write the ESLint restriction as a file list	the scan part of principle 2 passes	—
3	Merge device matching into one implementation	principle 7 verification passes	four separate copies
4	Link state machine ending at connected, default timeouts, disconnect classification, scan pause before link setup	principle 6 verification tests pass	releasing the old link before linking a new device, and disconnects affecting only their own device, are implemented; all three paths already stop scanning before connecting
5	acquireLink; auto-connect, OTA reconnect and the first connection after pairing switch to it	the scenario with two candidates sharing a discriminator passes	—
6	link.transaction; the secure channel, ShimLink frames and data-point access switch to it and drop their own mutex flags	tests for "request never answered" and "caller gives up first" pass	—
7	Exclusive token; auto-connect asks it first; hand-written pause checks removed	auto-connect no longer special-cases OTA	pausing auto-connect during OTA is a hand-written check
8	Presence records facts only; the device list decides	the device list no longer interprets scan results	—
9	Session-layer code moves to its own directory; the ESLint rule becomes directory-based	the BLE-layer directory imports no protocol constants	—
10	BLE tab in the debug console	every event kind in the snapshot is visible in the tab	—

Open questions

iOS defaults: Core Bluetooth connection requests never time out on their own; the default timeouts apply to iOS as well, and the values need verification on real iOS devices without changing the structure.
F10 on the target phones: unverified. If no downgrade happens, the 30 min restart is harmless and the rule stays.
Protocol side: a service UUID in the advertisement: the shared precondition for background scanning, screen-off scanning and iOS background reconnection, an over-the-air protocol change. Once it lands, filtering is introduced on both platforms as a fixed scheduler policy.
Advertising interval in the product contract: the basis for the device list's presence window, pending the firmware team's TRV901Z intervals with the screen on and off; the BLE layer is unaffected.