3. 接口说明

3.1 蓝牙代理类

IBluetoothManager是用户必须实现的接口类, 需要通过该接口类获取用户SDK的蓝牙控制接口, 蓝牙传输数据等重要内容。

方法名

参数

返回

描述

作用方式

onBtDeviceConnection
device: 蓝牙设备对象
status: 连接状态
注意: 需要转换为StateCode的连接状态

void

传递蓝牙连接状态
用户调用
实现状态传递

onReceiveDeviceData
device: 蓝牙设备对象
data: 原始数据

void

传递接收到的蓝牙数据
用户调用
实现数据传递

onMtuChanged
gatt: BluetoothGatt控制对象
mtu: 协商的BLE的mtu
status: 状态

void

传递协商的BLE的MTU
用户调用
可以不实现

onError
error: 错误事件

void

传递错误事件
用户调用
可以不实现

getConnectedDevice
BluetoothDevice - 已连接的蓝牙设备对象
备注: 没有设备连接时, 返回null

获取已连接的蓝牙设备对象

需要用户实现

getConnectedBluetoothGatt
BluetoothGatt - 已连接的BLE的GATT控制对象
备注: 没有设备连接时, 返回null

获取已连接的BLE的GATT控制对象
需要用户实现
可以不实现, SPP不实现

connectBluetoothDevice

device: 蓝牙设备对象

void

连接蓝牙设备

需要用户实现, 方便库内实现回连设备

disconnectBluetoothDevice

device: 蓝牙设备对象

void

断开蓝牙设备的连接

需要用户实现, 方便库内断开蓝牙设备

sendDataToDevice
device: 蓝牙设备对象
data: 数据包

boolean - 操作结果

向蓝牙设备发送数据

用户必须实现

queryMandatoryUpdate

IActionCallback<TargetInfoResponse> - 结果回调

void

查询设备升级状态

直接调用

Important

1. connectBluetoothDevice 必须保证单独连接, 不会影响到其他连接
- BLE方式, 只连接BLE, 不连接经典蓝牙
- 传递的连接状态需要转换为 3.5.2 状态码 的连接状态
2. sendDataToDevice 需要保证数据完整的发送
- BLE方式, 需要根据 MTU分包 和 队列式发数 。API会通知发送的数据, 不考虑MTU。
可以参考Demo的 SendBleDataThread 的实现
- SPP方式, 无需特殊处理
3. BLE方式实现 sendDataToDevice 接口需要注意以下几点
- 需要根据BLE的MTU值, 进行MTU分包
- 不能并发式发数, 需要队列式发数
- 因为OTA功能需要发送大量数据, 需要队列式发数, 保证数据完整的正确的发送

Note

参考 2.1 OTA库初始化

3.2 OTA操作接口

IUpgradeManager 主要是实现OTA的流程功能的, 由OTA库实现, 用户调用对应接口即可实现OTA升级。

方法名

参数

返回

描述

configure

BluetoothOTAConfigure - OTA参数

void

配置OTA的实现参数

startOTA

3.3 OTA流程回调 - OTA的状态回调

void

开始OTA流程

cancelOTA

void

void

取消OTA流程

release

void

void

释放资源

isOTA

void

boolean

是否进行OTA

getDeviceInfo

void

2.4.1 设备信息
获取缓存的设备信息,
可以作为初始化是否完成标志

Important

  1. cancelOTA : 如果是单备份方案, API无效; 如果是双备份方案, API才有效

BluetoothOTAConfigure

BluetoothOTAConfigure必须在OTA前配置。

属性名

类型

描述

参考值

priority

int

OTA的通讯方式
0 - BluetoothOTAConfigure#PREFER_BLE
1 - BluetoothOTAConfigure#PREFER_SPP

isUseReconnect

boolean

是否使用自定义回连方式

默认是不使用

isUseAuthDevice

boolean

是否启用设备认证

默认是开启

firmwareFilePath

String

固件升级文件存放路径

默认为空，升级前需要设置

firmwareFileData

byte[]

固件升级文件数据
默认为空，升级前需要设置
与firmwareFilePath一样, 两者选其一即可

mtu

int

调节后的BLE的MTU值

默认为20, 范围: 20-509

isNeedChangeMtu

boolean

是否需要调节MTU

默认不调节MTU

snGenerator

ICmdSnGenerator

命令SN生成器
若为null,则采用默认SN生成器,
适用于杰理多库联合使用

3.3 OTA流程回调

IUpgradeCallback 是OTA流程的状态回调, 用于更新UI。

public interface IUpgradeCallback {

   /**
    * OTA开始
    */
   void onStartOTA();

   /**
    * 需要回连的回调
    *
    * <p>注意: 1.仅连接BLE通讯通道
    * 2.用于单备份OTA</p>
    *
    * @param addr 回连设备的MAC地址
    * @param isNewReconnectWay 是否使用新回连方式
    */
   void onNeedReconnect(String addr, boolean isNewReconnectWay);

   /**
    * 进度回调
    *
    * @param type     类型
    *                 <p>0 -- 下载loader
    *                 or 1 -- 固件升级</p>
    * @param progress 进度
    */
   void onProgress(int type, float progress);

   /**
    * OTA结束
    */
   void onStopOTA();

   /**
    * OTA取消
    */
   void onCancelOTA();

   /**
    * OTA失败
    *
    * @param error 错误信息
    */
   void onError(BaseError error);
}

3.4 蓝牙事件回调

IBluetoothCallback

public interface IBluetoothCallback {
   /**
    * 蓝牙适配器开关回调
    *
    * @param bEnabled 开关
    * @param bHasBle  是否支持BLE功能
    */
   void onAdapterStatus(boolean bEnabled, boolean bHasBle);

   /**
    * 搜索蓝牙设备的状态回调
    *
    * @param bBle 是否搜索BLE
    * @param bStart 搜索状态
    */
   void onDiscoveryStatus(boolean bBle, boolean bStart);

   /**
    * 发现蓝牙设备的回调
    *
    * @param device 蓝牙设备对象
    */
   @Deprecated
   void onDiscovery(BluetoothDevice device);

   /**
    * 发现蓝牙设备的回调
    * @param device 蓝牙设备对象
    * @param bleScanMessage BLE扫描数据
    */
   void onDiscovery(BluetoothDevice device, BleScanMessage bleScanMessage);

   /**
    * 蓝牙设备配对状态回调
    *
    * @param device 蓝牙设备对象
    * @param status 配对状态
    */
   void onBondStatus(BluetoothDevice device, int status);

   /**
    * BLE数据缓冲区送数据设置回调
    *
    * @param device: BLE设备
    * @param block 缓冲区大小
    * @param status： 0 - 成功, 其他失败
    */
   void onBleDataBlockChanged(BluetoothDevice device, int block, int status);

   /**
    * 蓝牙设备连接回调
    *
    * @param device 蓝牙设备对象
    * @param status 连接状态
    */
   void onBtDeviceConnection(BluetoothDevice device, int status);

   /**
    * 连接回调
    *
    * @param device 蓝牙设备对象
    * @param status 连接状态
    */
   void onConnection(BluetoothDevice device, int status);

   /**
    * 从蓝牙设备接收到的数据
    *
    * @param device 蓝牙设备对象
    * @param data   原始数据
    */
   void onReceiveData(BluetoothDevice device, byte[] data);

   /**
    * 经典蓝牙的A2DP服务连接状态
    *
    * @param device 经典蓝牙设备对象
    * @param status 连接状态
    */
   void onA2dpStatus(BluetoothDevice device, int status);

   /**
    * 经典蓝牙的HFP服务连接状态
    *
    * @param device 经典蓝牙设备对象
    * @param status 连接状态
    */
   void onHfpStatus(BluetoothDevice device, int status);

   /**
    * 错误事件回调
    *
    * @param error 错误事件
    */
   void onError(BaseError error);
}

3.5 常量定义

3.5.1 错误码

错误码参考 ErrorCode

主错误码

错误码

名称

描述

-1

ErrorCode#ERR_UNKNOWN

未知错误

0

ErrorCode#ERR_NONE

没有错误

1

ErrorCode#ERR_COMMON

通用错误

2

ErrorCode#ERR_STATUS

状态错误

3

ErrorCode#ERR_COMMUNICATION

通讯错误

4

ErrorCode#ERR_OTA

OTA错误

5

ErrorCode#ERR_OTHER

其他错误

详细错误码: (格式: 0x[主码值][序号])

错误码

名称

描述

0x1001

ErrorCode#SUB_ERR_PARAMETER

参数错误

0x1012

ErrorCode#SUB_ERR_REMOTE_NOT_CONNECTED

远端设备未连接

0x3002

ErrorCode#SUB_ERR_SEND_FAILED

发送数据失败

0x3003

ErrorCode#SUB_ERR_PAIR_TIMEOUT

配对超时

0x3004

ErrorCode#SUB_ERR_DATA_FORMAT

数据格式异常

0x3005

ErrorCode#SUB_ERR_PARSE_DATA

解包异常

0x3007

ErrorCode#SUB_ERR_SEND_TIMEOUT

发送数据超时

0x3008

ErrorCode#SUB_ERR_RESPONSE_BAD_STATUS

回复失败状态

0x300A

ErrorCode#SUB_ERR_RESPONSE_BAD_RESULT

设备回复错误结果

0x300B

ErrorCode#SUB_ERR_WAITING_COMMAND_TIMEOUT

等待命令超时

0x4001

ErrorCode#SUB_ERR_OTA_FAILED

OTA升级失败

0x4002

ErrorCode#SUB_ERR_DEVICE_LOW_VOLTAGE

设备低电压

0x4003

ErrorCode#SUB_ERR_CHECK_UPGRADE_FILE

升级文件错误

0x4004

ErrorCode#SUB_ERR_OFFSET_OVER

读取偏移量失败

0x4005

ErrorCode#SUB_ERR_CHECK_RECEIVED_DATA_FAILED

数据校验失败

0x4006

ErrorCode#SUB_ERR_UPGRADE_KEY_NOT_MATCH

加密key不匹配

0x4007

ErrorCode#SUB_ERR_UPGRADE_TYPE_NOT_MATCH

升级类型出错

0x4008

ErrorCode#SUB_ERR_OTA_IN_HANDLE

升级程序正在进行

0x4009

ErrorCode#SUB_ERR_UPGRADE_DATA_LEN

升级过程中出现长度错误

0x400A

ErrorCode#SUB_ERR_UPGRADE_FLASH_READ

flash读写错误

0x400B

ErrorCode#SUB_ERR_UPGRADE_CMD_TIMEOUT

命令超时

0x400C

ErrorCode#SUB_ERR_UPGRADE_FILE_VERSION_SAME

升级文件的固件版本一致

0x400D

ErrorCode#SUB_ERR_TWS_NOT_CONNECT

TWS未连接

0x400E

ErrorCode#SUB_ERR_HEADSET_NOT_IN_CHARGING_BIN

耳机未在充电仓

0x400F

ErrorCode#SUB_ERR_UPGRADE_SAME_FILE

相同文件

0x4010

ErrorCode#SUB_ERR_UPGRADE_UNKNOWN

未知升级错误

0x4011

ErrorCode#SUB_ERR_RECONNECT_TIMEOUT

回连设备超时

0x4012

ErrorCode#SUB_ERR_RECONNECT_FAILED

回连设备失败

0x5001

ErrorCode#SUB_ERR_AUTH_DEVICE

认证设备失败

0x5004

ErrorCode#SUB_ERR_FILE_NOT_FOUND

未找到升级文件

0x5005

ErrorCode#SUB_ERR_DATA_NOT_FOUND

未找到升级数据

0x5006

ErrorCode#SUB_ERR_IO_EXCEPTION

IO异常

3.5.2 状态码

StateCode

  1. 连接状态

状态码

名称

描述

0

StateCode#CONNECTION_DISCONNECT

断开连接

1

StateCode#CONNECTION_OK

连接成功

2

StateCode#CONNECTION_FAILED

连接失败

3

StateCode#CONNECTION_CONNECTING

连接中

4

StateCode#CONNECTION_CONNECTED

已连接(已弃用)

  1. 回复状态

状态码

名称

描述

0

StateCode#STATUS_SUCCESS

成功状态

1

StateCode#STATUS_FAIL

失败状态

2

StateCode#STATUS_UNKOWN_CMD

未知命令

3

StateCode#STATUS_BUSY

繁忙状态

4

StateCode#STATUS_NO_RESOURCE

没有资源

5

StateCode#STATUS_CRC_ERROR

CRC校验错误

6

StateCode#STATUS_ALL_DATA_CRC_ERROR

全部数据CRC错误

7

StateCode#STATUS_PARAMETER_ERROR

参数错误

8

StateCode#STATUS_RESPONSE_DATA_OVER_LIMIT

回复数据超出限制

3.6 命令生成器

public interface ICmdSnGenerator {

   /**
    * 获取Rcsp命令序列号
    *
    * @param device 蓝牙设备对象
    * @return 序列号
    * <p>
    * 范围：0-255<br>
    * 每调用一次就累加一次
    * </p>
    */
   int getRcspCmdSeq(BluetoothDevice device);
}