iOS 错误与常见问题
SDK Version: 1.0.0
Platform: iOS
BLE 错误
| 错误 | 建议处理 |
|---|---|
bluetoothUnavailable | 提示打开蓝牙，状态恢复后重新扫描 |
permissionDenied | 引导到系统设置，不循环弹授权 |
scanFailed(String) | 记录原因，确认蓝牙状态后重试 |
deviceNotFound(UUID) | 重新扫描并重新选择设备 |
deviceMismatch(String) | 拒绝进入业务，检查设备/固件 |
connectionFailed(String) | 重连并重新认证 |
serviceMissing / characteristicMissing | 设备能力不兼容，停止接入流程 |
notConnected | 重新连接 |
notReady | 等待 atReady，不要固定 sleep 后盲发 |
busy | 串行排队，避免并发 no-wait/AT |
timeout | 检查最新连接状态，必要时重连 |
writeFailed(String) | 不复用不确定事务，重连 |
cancelled | 按正常取消处理 |
malformedResponse(String) | 保留响应并停止当前上层流程 |
deviceControlFailed(String) | 电量/版本可降级为不可用；持续失败则重连 |
Auth 错误
| 错误 | 建议处理 |
|---|---|
busy | 等当前认证结束；不要并发创建第二次认证 |
invalidConfiguration | 修正为全部大于 0 的超时和重试次数 |
transportUnavailable | 检查同一设备仍连接且 atReady == true，必要时重连 |
commandTimedOut(String) | 记录命令类别，恢复干净通道后有限重试 |
secureRandomUnavailable | 停止认证；不可使用弱随机数降级 |
invalidChallenge | 停止认证并升级 SDK/系统问题 |
challengeMissing | 设备未返回完整 Challenge 签名；重连后重试 |
malformedChallengeReply | 响应格式不符合协议；检查设备固件兼容性 |
invalidSignatureLength(Int) | 签名长度错误；拒绝认证并记录实际长度 |
signatureVerificationFailed | 签名无效；拒绝设备进入业务 |
challengeRetryExhausted | 多次 Challenge 结果不一致；重连后再试一次 |
invalidDeviceIdentity | DID/SN 响应无效；拒绝进入业务 |
cancelled | 页面退出、切换设备或调用取消时按正常结束处理 |
认证错误默认 fail closed：不要在认证失败后继续业务。先恢复干净的传输通道，重连后再认证。
推荐恢复决策
权限/蓝牙关闭 → 用户操作后重新扫描
设备未找到/断链 → 清空身份，重新扫描、连接、认证
notReady → 等待状态；进入 failed 则停止等待
busy → 等当前事务结束，不做高频循环重试
timeout/写入失败/通道不可用 → 断开重连，再重新认证
签名/DID 无效 → fail closed，不允许绕过认证
cancelled → 不弹错误，按生命周期正常结束
常见问题
已连接但 atReady 一直为 false
表示必要特征、写能力或通知订阅尚未就绪。观察 connectionState；若进入 .failed，按具体错误处理。不要提前发 AT。
.recoverableEncodingProbe 为什么不能提前返回？
错误编码的迟到响应可能污染下一次编码探测。transport 必须收集完整窗口，并在不确定失败后恢复干净通道。
页面关闭时怎样清理？
取消认证和事件 Task，调用 authenticator.cancel()，移除 observer，最后调用 ble.teardown()。临时断开但保留 client 时只调用 disconnect()。
iOS 为什么没有 Init 页面？
SDK 1.0.0 没有独立 iOS Device Init 产品。认证后参数初始化属于客户业务或另行交付的产品，不能把参数塞进 Auth API。
电量或版本返回 nil
先检查 deviceControlReady。这些查询为可降级 API，会把超时、断链或设备控制响应错误转换成 nil。持续失败时重连；客户业务不要把 nil 当作 0 或空版本。
收到同一事件两次
通常是同时消费了 events、onEvent 和 observer。选择一种主事件通道；细粒度 observer 只保留确有独立用途的订阅，并用返回的 UUID token 成对移除。
什么时候重新认证？
首次连接、断链重连、切换设备、认证失败后重新建立通道时都要重新认证。不要把上一台设备或上一条连接的身份状态沿用到新会话。