常见问题答疑

记录客户比较经常遇到的问题，通过归纳和梳理，进行答疑记录，方便客户快速检索问题解答。

客户可以先检索 已有的问题 是否符合你遇到的问题；如果有，恭喜你，找到答案了。

如果是新的问题，请按照以下步骤进行提问，我们将尽快解答。

描述问题的情况以及测试环境，请参考[提问格式](#question_format)

提供打印日志，输出方式请参考测试调试

最好可以提供现象截图或视频

1. 提问格式

问题描述: XXXXXX
测试环境: 固件: AC695N_watch_SDK_Vxxx 或 JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: SDK接入  表盘操作  文件传输   健康数据/运动数据   资源更新(固件升级)  其他
复现步骤: 1. xxxx 2. xxxx 3.xxxx
复现概率: 必现, 1/20, n / m
公版Demo是否复现: 是，否
问题出现时间段: yyyy/MM/dd hh:mm - yyyy/MM/dd hh:mm 例如: 2022/05/28 17:00 - 2022/05/28 17:02
备注: xxxx

Important

开发前，请阅读杰理健康SDK开发文档

2. 常见问题

2.1 接入问题

2.1.1 设备连接成功，却一直返回”设备未连接”

问题描述: 自行实现蓝牙代理部分，在使用杰理健康SDK时，明明设备连接成功，却一直返回设备未连接的错误
测试环境: 固件: AC695N_watch_SDK_Vxxx 或 JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: SDK接入
备注: 无

解答: 这种情况可以按以下情况排查:

传递设备的连接状态错误，需要转换成 库内定义的连接状态

public class StateCode {

   /*---------------------------------------------------------------------
    *连接状态
    * ---------------------------------------------------------------------*/
   public final static int CONNECTION_OK = 1; //连接成功
   public final static int CONNECTION_FAILED = 2;//连接失败
   public final static int CONNECTION_DISCONNECT = 0;//断开连接
   public final static int CONNECTION_CONNECTING = 3;//连接中
   ...
}

实现 getConnectedDevice 方法有问题，返回null。
确认是否通过 设备认证

2.1.2 调用WatchManager的接口没有回调

问题描述: 设备连接成功后，调用WatchManager的查询列表的接口没有回调
测试环境: 固件: AC695N_watch_SDK_Vxxx 或 JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: SDK接入
备注: 无

解答: 这种情况，可以按照以下情况排查:

WatchManager的实现有问题，导致设备连接成功，库内还没开始初始化。具体参考 2.1.1 设备连接成功，却一直返回”设备未连接”

没有等到杰理健康库的初始化完成，就开始调用接口

 isSystemInit = false;
//初始化手表功能对象
demo = new WatchManagerDemo();
//          demo.isWatchSystemOk(); //判断手表管理对象是否初始化
//注册事件监听器
demo.registerOnWatchCallback(new OnWatchCallback() {
   @Override
   public void onWatchSystemInit(int code) {
      super.onWatchSystemInit(code); //TODO: 系统初始化结果回调
      isSystemInit = code == 0;
      if (isSystemInit) {//系统初始化成功
          //TODO: 可以操作其他操作，参考testWatchOp
      } else { //系统初始化失败

      }
   }
});

Note

用户需要等待杰理健康SDK返回初始化结果，才能操作其接口。

2.1.3 如何触发杰理健康SDK的初始化流程？

问题描述: 杰理健康SDK需要等待初始化结果才能操作接口，如何触发杰理健康SDK的初始化流程呢？
测试环境: 固件: AC695N_watch_SDK_Vxxx 或 JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: SDK接入
备注: 无

解答：杰理健康SDK是根据用户传输的设备状态进行处理，当用户传输 设备已连接 的状态时，触发杰理健康SDK的初始化流程。

SDK需要用户保证传入设备状态的准确性

不能重复传入相同的设备状态
注意设备状态的一致性，连接 -> 断开。 * 比如：设备断开，需要传输设备已断开的状态。因为SDK缺少断开状态，会少处理设备断开的情况，导致下一次设备连接的异常。 * 设备已连接的状态，可以在用户处理完设备连接的流程后再回调。比如：如果设备需要设备认证，需要连接成功后先通过设备认证流程，再回调设备已连接的状态
设备状态值转换，需要按照 库内定义的连接状态 进行传递

具体初始化流程，参考 1.3.4 SDK初始化流程

2.1.4 BLE实现蓝牙发送数据接口需要注意事项

问题描述：BLE方式实现蓝牙发送数据接口需要注意事项
测试环境: 固件: AC695N_watch_SDK_Vxxx 或 JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: SDK接入
备注: 无

解答：杰理健康SDK的蓝牙处理采用代理方式，把蓝牙部分功能交由外部实现，用户需要实现蓝牙代理部分完成杰理健康SDK的构建。

具体参考 1. SDK框架

发送数据接口，如果是 BLE实现 ，需要注意 MTU分包 和 队列式发数

BLE的MTU分包处理: BLE 连接会协商MTU值, 超出MTU的值, 会被系统抛弃。

为了避免数据丢失, 请按照MTU大小发送, 若发送数据长度超过MTU, 则需要进行MTU分包发送处理
BLE发送-队列式发数: BLE并发式发送容易导致手机系统BLE底层协议栈卡住。

建议发送数据后根据 BluetoothGattCallback#onCharacteristicWrite 回调的状态，进行 队列式发数 处理

2.2 表盘操作问题

2.2.1 插入表盘，返回错误码: WatchError#ERR_VERSION_NOT_MATCH

问题描述：插入表盘watch6时，返回错误码:WatchError#ERR_VERSION_NOT_MATCH，一直不成功
测试环境: 固件: AC695N_watch_SDK_Vxxx 或 JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: 表盘操作
备注: 无

解答: 错误码: WatchError#ERR_VERSION_NOT_MATCH，表示表盘版本不匹配。

这种情况可以按照以下步骤排查问题:

表盘文件重命名了，概率最大
- 在打印日志，搜索”PackResFormat”的关键词，可以看到解压文件的情况
- 目前版本，表盘文件不支持重命名，也不支持其他修改
表盘文件没有打包watchxxx.json文件或者 watchxxx.json内容错误，概率次之
- watchxxx.json的格式如下:
- json内容可以拓展，但是上述字段必须保留，位置不能改变
设备程序不支持表盘版本，概率最小
- 可以查询打印日志，确定设备的手表系统信息

2.2.2 插入表盘，返回错误码: WatchError#ERR_FAT_TOO_BIG

问题描述：插入表盘，返回错误码: WatchError#ERR_FAT_TOO_BIG， File size exceeds free space
测试环境: 固件: AC695N_watch_SDK_Vxxx 或 JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: 表盘操作
备注: 无

解答：错误码WatchError#ERR_FAT_TOO_BIG， 表示文件太大，手表剩余空间不足。

这种情况可以按以下排查:

插入的表盘文件不对
手表的内置Flash不足

2.2.3 插入自定义表盘背景，设备死机

问题描述：插入自定义表盘背景后，设备死机了。
测试环境: 固件: JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: 表盘操作
备注: 无

解答：这种情况大概率是自定义表盘背景有问题，请按以下排查

是否用对了转换方法
- 图像转换的示例，参考 2.3.14 图像转换

是否原图的尺寸超过设备屏幕限制

确认设备屏幕的宽高

获取缓存的手表系统信息

final WatchManager watchManager = WatchManager.getInstance();
//获取缓存的手表系统信息
ExternalFlashMsgResponse watchSysInfo = watchManager.getExtFlashMsg(watchManager.getConnectedDevice());
if(null == watchSysInfo) return;
int screenWidth = watchSysInfo.getScreenWidth();    //手表屏幕的宽度
int screenHeight = watchSysInfo.getScreenHeight();  //手表屏幕的高度

是否选择 跳过文件检验

//WatchManager是WatchOpImpl的子类，须在1.3配置好sdk
final WatchManager watchManager = WatchManager.getInstance();
//执行插入自定义表盘背景文件操作并等待结果回调
//是否跳过文件校验选项 -- 必须为true
watchManager.createWatchFile(bgFilePath, true, listener);

2.2.4 浏览手表文件列表，回调列表为空或表盘文件信息重复

问题描述：SDK初始化成功后，执行浏览手表文件列表接口，偶尔回调文件列表为空或表盘文件信息重复
测试环境: 固件: JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: 表盘操作
备注: SPP通讯方式

解答：这种情况可能与SPP收数实现有关，SPP发送数据量大，可能存在同时发数，数据粘包等情况。
建议用户实现接收数据传递时进行 队列化 的处理。保证收到数据的顺序是正确的。
因为错误的数据乱序，可能导致某些流程出现问题，出现上述情况。

2.2.5 插入表盘失败，设备一直卡在 `文件传输` 界面

问题描述：插入表盘失败，设备一直卡在"文件传输"界面
测试环境: 固件: AC695N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: 表盘操作
备注: 无

解答： 这个是因为AC695N_watch_SDK的实现方式，必须保证插入文件的完整性。所以插入表盘失败，设备的系统处于异常状态，所以设备一直卡在“文件传输中”界面。

解决方案:

客户需要通过APP连接设备，并进行恢复系统操作。恢复系统成功后，设备重启，就能正常使用了。参考 2.3.10 系统恢复
客户可以通过线刷的方式烧写设备固件。注意，线刷的方式需要添加参数, -format all 或者 -format vm 。

2.2.6 如果想显示表盘的名字不一样，怎样实现呢？

问题描述：如果想显示表盘的名字不一样，怎样实现呢？
测试环境: 固件: AC695N_watch_SDK_Vxxx 或 JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: 表盘操作
备注: 无

解答：提供两种思路:

本地拓展: 可以通过表盘的json文件进行拓展，增加对应的字段标识表盘信息，从而增加表盘昵称。
服务器拓展: 可以通过 prj_uuid 字段的uuid，在服务器上查询表盘信息，从而获取表盘昵称。

2.3 文件传输问题

2.3.1 能否把文件传输到Flash?

问题描述：能否把文件传输到Flash?
测试环境: 固件: AC695N_watch_SDK_Vxxx 或 JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: 文件传输
备注: 无

解答: 可以，但是需要固件支持

传输文件到Flash，文件名必须是短文件名(8+3结构)。比如：watch001。参考 2.1.3.1 文件下载(APP -> 设备)
传输文件到Flash2或者Flash3等存储器，固件分区Flash，专门存放资源文件的

选择设备句柄必须是Flash类型的。参考 2.1.3.1.1 TransferTask.Param

WatchManager watchManager = WatchManager.getInstance();
TransferTask.Param param = new TransferTask.Param();
param.devHandler = getOnlineFlash().getDevHandler();    //设置设备句柄 -- Flash句柄
param.useFlash = true;                                  //设置使用Flash
mTask = new TransferTask(watchManager, filePath, param);
mTask.setListener(this);
mTask.start();

2.3.2 关于文件传输的文件名长度问题解答

问题描述：关于文件传输的文件名长度问题解答
测试环境: 固件: AC695N_watch_SDK_Vxxx 或 JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: 文件传输
备注: 无

解答：文件传输的文件名长度于传递介质有关。

SD卡，U盘等: 支持长、短文件名
内置Flash, 外挂Flash等: 支持短文件名

2.4 健康数据/运动数据问题

2.5 资源更新问题

Important

OTA问题，请移步杰理OTA外接库开发文档(Android)

2.5.1 更新资源，返回错误码: WatchError#ERR_SPACE_TO_UPDATE

问题描述：更新手表资源失败，返回错误码: WatchError#ERR_SPACE_TO_UPDATE, Insufficient space for upgrade resources
测试环境: 固件: AC695N_watch_SDK_Vxxx 或 JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: 资源更新
备注: 无

解答:  错误码: WatchError#ERR_SPACE_TO_UPDATE，表示剩余空间不足以完成资源更新。
开始更新资源时，会有一个检测剩余空间的流程，主要是判断手表剩余空间是否足够完成资源更新。
如果剩余空间不足，则会返回错误码(WatchError#ERR_SPACE_TO_UPDATE)。

资源空间判断逻辑:
判断资源是否存在，主要是根据资源的名字进行判断。
判断资源是否需要更新，主要是对资源内容进行校验。

资源存在，而与需要更新的资源内容相同，不处理。
资源存在，但与需要更新的资源内容不相同，替换处理
资源不存在，插入需要更新的资源

2.5.2 资源更新与固件升级的区别

问题描述：资源更新与固件升级的区别
测试环境: 固件: AC695N_watch_SDK_Vxxx 或 JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: 资源更新
备注: 无

解答：资源更新，是替换或更新手表系统的资源文件，主要是通过文件传输等方式实现设备资源的更新。升级文件是upgrade.zip，以.zip结尾的压缩包。

固件升级，主要是升级固件程序，是代码的更新。升级文件是update.ufw，以.ufw结尾的文件。

upgrade.zip的结构

├ res.ori — 文件夹，主要存放资源更新的内容

└ update.ufw — 固件升级的文件
资源更新的策略:
- res.ori 和 update.ufw都存在：更新资源 –> 固件升级
- res.ori 存在, update.ufw不存在 : 更新资源
- res.ori 不存在，update.ufw存在：固件升级

更新资源, 参考 2.3.9 资源更新

2.5.3 资源更新失败，设备一直处于”文件传输”的界面

问题描述：资源更新失败，设备一直处于"文件传输"的界面
测试环境: 固件: AC695N_watch_SDK_Vxxx 或 JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: 资源更新
备注: 设备情况如下图

解答：这个情况是因为开始资源更新后，已经开始替换部分资源了，中途异常，导致资源更新失败。
设备重启也会因为部分资源损坏或者更新，导致手表系统跑不起来，所以一直卡在“文件传输”界面。

解决方案:

客户需要通过APP连接设备，并继续完成资源更新流程。资源更新完成后，设备重启后就可以正常使用了
客户可以通过线刷的方式烧写设备固件。注意，线刷的方式需要添加参数, -format all 或者 -format vm 。

2.6 其他问题

2.6.1 双模同地址支持CTKD(一键连接), 经典蓝牙连接不上的问题

问题描述：双模同地址支持CTKD(一键连接)的设备，如果先配对经典蓝牙，再去连接BLE，连接正常；但是先连接BLE后连接经典蓝牙，经典蓝牙连接不上
测试环境: 固件: JL701N_watch_SDK_Vxxx  软件: JieLi_Health_SDK_Android_Vxxx
问题标签: 其他问题
备注: 无

解答：这个情况是因为设备是BLE地址与经典蓝牙地址相同的双模设备(以下简称”双模设备”)，Android手机走的配对方式不同导致的。
双模设备连接流程，先配对，再连接BLE，连接正常，是因为配对方式优先走了经典蓝牙配对。

解决方案:

如果客户使用杰理蓝牙连接库实现蓝牙处理部分功能，替换 jl_bluetooth_connect_V1.0.8+ 的库开发即可
如果客户是自行实现蓝牙处理部分功能，需要指定双模设备的配对方式。参考代码如下

2.6.2 双模同地址支持CTKD(一键连接), 是否可以支持HID？

问题描述：双模同地址支持CTKD(一键连接), 是否可以支持HID
测试环境: 固件: AC6971N_watch_SDK_Vxxx  软件: JL_Health_SDK_Vxxx
问题标签: 其他问题
备注: 无

解答：可以支持的。但是部分安卓手机会出现不能连接经典蓝牙的情况。
因为大部分安卓手机虽然支持CTKD，但是没有完全支持，不能通过BLE的加密Link Key直接生成EDR的Auth Key，导致经典蓝牙连接不上。
具体可以参考 2.6.1 。
注意: 如果按照 2.6.1 的修改方法，则会导致HID不会被连接。
虽然谷歌官方没有说明，但是其他渠道和测试都可以知道，Android 11+的手机是支持CTKD。(三星手机是低版本也支持)
至于是否有兼容性问题，需要大量测试来验证。

资料参考:  交叉传输密钥派生-CTKD