常见问题答疑

1. 名词/流程说明

1.1 单备份OTA与双备份OTA的区别

类型	单备份	双备份
存储	除了工程所需支持空间，额外增加loader所需的空间即可	需要工程所需支持空间 * 2
升级	需要断开回连一次	无感升级, 无需回连
流程	下载loader -> 设备重启(运行loader)-> 回连设备 -> 升级固件	升级固件
安全	有几率需要强制升级(蓝牙断开、APP杀死中止OTA等)	无安全风险
成本	较低	较高

Warning

双备份方式的产品暂时不能通过OTA, 变成单备份OTA的产品。只能通过线刷方式, 才能改变OTA方式。

1.2 Boot Loader的作用

设备的最小系统, 提供BLE操作和实现OTA功能。用于单备份OTA的升级。同时保证设备OTA发生异常后, 不至于变砖, 还能通过升级恢复。

类似Windows系统的Dos操作系统。

Warning

Boot loader需要根据配置决定是否走认证流程。
目前loader仅支持BLE通讯
loader仅有OTA功能的UUID服务

2. 接入问题

2.1 蓝牙设备已连接, 为什么调用OTA库接口返回错误, 4114(0x1012), 设备未连接

OTA库回调的 设备未连接 的意思是OTA库没有初始化成功, 没有获取到设备信息。

如果发生上述情况，可以按照以下步骤排查：

1. 确认固件与OTA库的设备认证状态是否一致;

* 设备认证只在设备连接成功时进行，不能重复进行。

2. 确认是否有正确传入设备已连接状态到OTA库内。注意: 连接状态需要转换成 3.6 状态码

* 确保传入的设备状态正确, 不能重复传入相同的设备状态

3. 确认是否收到 3.4 蓝牙事件回调 # onConnection 回调的连接状态为 StateCode#CONNECTION_OK

* 保证OTA库初始完成才进行OTA库的接口操作

OTA库会在客户传入 设备已连接 状态进行RCSP协议初始化和同步设备信息等操作。

Warning

设备断开 也需要实时传入OTA库, 对相关设备的资源进行释放, 否则可能影响下一次的OTA库初始化。

2.2 错误码: 12290(0x3002), 发送数据失败

如果发生上述情况，可以按照以下步骤排查:

1. 请检查 BluetoothOTAManager#sendDataToDevice(device, data) 的返回结果

2.3 发送数据成功, 却没有收到回复数据

OTA库的命令数据大多是采取 一问一答 的方式进行

如果发生上述情况，可以按照以下步骤排查:

1. 确保通讯通道有效

* 保证有使能设备的UUID的通知属性

* 保证写入数据的设备UUID有效

2. 确保发送数据完整

* BLE实现的话, 需要根据 MTU分包 和 队列式发数, 具体参考下Demo的 SendBleDataThread

2.4 错误码: 12295(0x3007), 发送数据超时

OTA流程, 命令交互是采取 一问一答 的机制。

当SDK发送的命令在限定时间内没有得到回复, SDK会重复三次, 如果都没有得到回复, SDK会抛出 发送命令超时 的错误。

如果发生上述情况，可以按照以下步骤排查：

1. 确保通讯通道有效

* 保证有使能设备的UUID的通知属性

* 保证写入数据的设备UUID有效

2. 确保发送数据完整

* BLE实现的话, 需要根据 MTU分包 和 队列式发数, 具体参考下Demo的 SendBleDataThread

3. 确保数据正确回传到OTA库

* 接收到的数据，通过 2.1.3.2 传递接收到的蓝牙数据回传OTA库

Warning

OTA库会根据数据结构解析属于OTA流程的命令, 可以直接传入裸数据。

2.5 错误码:20481(0x5001), 设备认证失败

OTA库的设备认证动作发生在客户传入 设备已连接 状态并设置开启设备认证的条件。

如果发生上述情况，可以按照以下步骤排查：

1. 确保固件与OTA库的设备认证转态是否一致;

* 保证固件 开启设备认证, OTA库也是 开启设备认证, 反之, 亦然。

2. 确保通讯通道有效

* 保证有使能设备的UUID的通知属性

* 保证写入数据的设备UUID有效

3. 确保传入设备状态正确

* 保证 设备状态 不重复传入
* 设备认证只在设备连接成功时进行，不能重复进行。 如果设备已经过了认证，不会再响应认证数据。
* 用户应该记录设备认证标识, 用来判断是否需要进行 设备认证

2.6 错误码:12296(0x3008), 回复失败状态

设备收到命令后，根据自身原因，回复失败的状态，表示操作失败。

具体原因，请参考 3.6.2 回复状态

3. OTA问题

3.1 升级失败，错误码: 12299(0x300B), 等待命令超时

OTA过程中, 是设备不断向SDK端请求数据的过程。

如果设备在OTA流程没结束的情况下, 超过 20秒 仍然没有请求下一包数据, OTA库就会报错。

如果发生上述情况，可以按照以下步骤排查

1. 确保发送数据完整

* BLE实现的话, 需要根据 MTU分包 和 队列式发数, 具体参考下Demo的 SendBleDataThread

2. 确认设备收到SDK发送的数据

3. 确认是否设备端没有处理SDK发送的数据

Warning

这种情况, 需要先排除SDK端的问题, 然后由设备端查找问题。

3.2 升级失败，错误码: 16392(0x4008), 升级程序正在进行

当``BluetoothOTAManager#isOTA()` == true 时，调用 startOTA 接口, SDK会返回 “升级程序正在进行” 的错误。

3.3 升级失败，错误码: 16385(0x4001), OTA升级失败

OTA过程中, 设备端或SDK端返回OTA失败错误。

Warning

此情况造成的原因较多, 需要附带上打印日志。
输出打印日志, 参考: 调试说明

3.4 升级失败，错误码: 16386(0x4002), 设备低电压

设备端判断电量过低, 不允许进行OTA升级。请将设备充电到合适电量, 再进行OTA升级。

3.5 升级失败，错误码: 16387(0x4003), 升级文件错误

OTA过程中, 设备会校验数据。如果数据不全或者重复发相同数据, 会导致设备存储的数据错误。

如果发生上述情况，可以按照以下步骤排查：

1. 确保发送数据完整

* BLE实现的话, 需要根据 MTU分包 和 队列式发数, 具体参考下Demo的 SendBleDataThread

2. 确保升级文件与固件程序相同

* 设备升级会校验程序是否相同, 如果不同芯片平台的SDK升级文件, 是不能互相升级的。

* 即使相同的固件程序，但是换了存储方式，例如： 4K对齐, 256对齐等, 都会导致不能通过OTA升级, 需要线刷后才能OTA升级。

3. 确保一个设备只有对应一个OTAManager初始化, 如果重复初始化OTAManager, 会对同一个设备进行重复发数。

Warning

此情况造成的原因较多, 如果以上步骤不能解决问题, 请联系对应SDK负责人进行询问。需要附带上打印日志。
输出打印日志, 参考: 调试说明

3.6 升级失败, 错误吗: 16389(0x4005), 数据校验失败

OTA过程, 设备端校验升级数据的完整性失败。

如果发生上述情况，可以按照以下步骤排查：

1. 确保发送数据完整

* BLE实现的话, 需要根据 MTU分包 和 队列式发数, 具体参考下Demo的 SendBleDataThread

2. 确保一个设备只有对应一个OTAManager初始化, 如果重复初始化OTAManager, 会对同一个设备进行重复发数。

3.7 升级失败, 错误码: 16396(0x400C), 升级文件的固件版本一致

升级文件的版本号与当前设备的固件版本号一致, 不允许升级。

3.8 升级失败, 错误码: 16397(0x400D), TWS未连接

TWS耳机未进行TWS配对, 不允许升级。

3.9 升级失败, 错误码: 16399(0x400F), 相同文件

升级文件与当前设备的固件内容一致, 不允许升级。

3.10 升级失败，错误码: 16401(0x4011), 回连设备超时

单备份OTA流程, 下载完Loader后, 设备需要重启并切换到loader系统。这就需要SDK进行回连设备流程。

SDK根据 2.2.1 BluetoothOTAConfigure # isUseReconnect 是否走自定义回连设备流程。SDK默认内置回连设备流程。

客户也可以设置走自定义回连设备流程。SDK都会在回连设备时通过 3.3 OTA流程回调 # onNeedReconnect 回调。

如果发生上述情况，可以按照以下步骤排查：

1. 确保蓝牙权限已授予

* 如果是Android 6+，需要申请 位置定位权限

* 如果是Android 12+, 需要申请 蓝牙扫描权限 和 蓝牙连接权限

2. 确保设备端正常进入loader状态, 可以搜索到设备的广播包

3. 如果 3.3 OTA流程回调 # onNeedReconnect 回调设备使用新回连方式, 设备端会进行BLE地址变换

* 新回连方式根据特殊广播包进行变换地址确定，以下是新回连的广播包格式

Byte 0	Byte 1	Byte 2-3	Byte 4-8	Byte 9	Byte 10-15
长度	类型	VID	标识	版本号	Payload(原BLE地址)
0x??	0xFF	0xD605	ATOLJ	0x00	??:??:??:??:??:??

字段解析

* 长度 : 类型 + VID + 标识 + 版本号 + Payload 的长度
* 类型 : 固定0xFF, 厂商自定义数据
* VID : 芯片厂商ID, 默认是0xD605(小端), 表示”杰理科技”
* 标识 : 过滤标识, “ATOLJ”(小端), 表示”JLOTA”
* 版本号 : 0x00
* Payload : 有效数据, 根据 版本号 而改变

* 客户根据 3.3   OTA流程回调 # onNeedReconnect 回调的原BLE地址, 与广播包的原BLE地址一致对比, 如果是一致, 则该广播包的设备是需要回连的设备。

Warning

广播包数据是小端存储, 解析时注意大小端转换。
此情况造成的原因较多, 如果以上步骤不能解决问题, 请联系对应SDK负责人进行询问。需要附带上打印日志。
输出打印日志, 参考: 调试说明

3.11 升级失败, 错误码: 16404(0x4014), 设备处于设备双连模式

升级设备处于 设备双连模式, 不允许升级。

3.12 升级失败, 错误码: 16390(0x4006), 加密key不匹配

升级文件是否携带Key，需要与固件程序保持一致。
携带Key为量产版本，不携带Key为测试版本。
生产密钥(Key) 是客户向我司申请，由我司产生的唯一标识。主要用于区分产品。

3.13 升级失败, 错误码: 20484(0x5004), 未找到升级文件

读取升级文件数据过程中发生异常
如果发生上述情况，可以按照以下步骤排查：
1. 检查升级文件是否存在, 升级文件路径是否有误
2. 检查应用是否有读取升级文件数据的权限

4. 其他问题

4.1 可以同时使能两个Characteristic, 会有影响吗?

没有影响。

Warning

使能多个 Characteristic, 不能并发执行，需要队列式执行。等一个 Characteristic 使能结果回调，再执行下一个。
单备份OTA，回连设备，处于loader状态，设备仅有OTA的UUID服务，不能进行多个 Characteristic 使能

4.2 OTA升级的时候为什么有两次进度0-99的变化呢?

单备份OTA会有两个流程, 下载资源 和 升级固件。

3.3 OTA流程回调 # onProgress 回调type, 表示升级进度的类型。

- Type == 0, 下载资源

- Type == 1, 升级固件