3. 接口说明
3.1 蓝牙扫描相关接口
bluetooth.ts 中的 BTScan 命名空间实现蓝牙扫描, ScanImpl 为蓝牙扫描操作类(实现 IScan 接口),提供接口如下:
方法名 |
功能 |
参数 |
返回值 |
|---|---|---|---|
addScanCallback |
添加扫描回调 |
ScanCallback -> callback |
void |
removeScanCallback |
移除扫描回调 |
ScanCallback -> callback |
void |
startScan |
开始扫描 |
number -> scanTimeOut |
void |
refreshScan |
刷新扫描 |
无 |
void |
stopScan |
停止扫描 |
无 |
void |
getScanSettingConfigure |
获取扫描配置 |
无 |
ScanSettingConfigure |
setScanSettingConfigure |
设置扫描配置 |
ScanSettingConfigure -> config |
void |
isScanning |
是否正在扫描 |
无 |
boolean |
蓝牙扫描实现类 ScanImpl 的监听回调 ScanCallback , 当蓝牙状态发生改变、扫描状态发生改变、发现设备时进行回调。
属性 |
参数 |
描述 |
|---|---|---|
onScanStart |
无 |
开始扫描 |
onScanFailed |
BTBean.BluetoothError -> error |
扫描失败 |
onScanFinish |
无 |
扫描结束 |
onFound |
BTBean.BluetoothDevice[] -> devices |
扫描发现设备 |
3.2 蓝牙连接相关接口
bluetooth.ts 中的 BTConnect 命名空间实现蓝牙连接和调整MTU, ConnectImpl 为蓝牙连接操作类(实现 IConnect 接口),提供接口如下:
方法名 |
功能 |
参数 |
返回值 |
|---|---|---|---|
setConnectSettingConfigure |
设置连接配置 |
ConnectSettingConfigure -> config |
void |
addConnectCallback |
添加连接回调 |
ConnectImplCallback -> callback |
void |
removeConnectCallback |
移除连接回调 |
ConnectImplCallback -> callback |
void |
connect |
连接设备 |
{device, success, fail} -> option |
void |
disconnect |
断开设备 |
BTBean.BluetoothDevice -> device |
void |
getConnectedDevice |
获取已连接设备列表 |
无 |
Array<BTBean.BluetoothDevice> | null |
getMTU |
获取设备MTU |
BTBean.BluetoothDevice -> device |
number | undefined |
isConnecting |
是否正在连接 |
BTBean.BluetoothDevice -> device |
boolean |
isConnected |
是否已连接 |
BTBean.BluetoothDevice -> device |
boolean |
蓝牙连接实现类 ConnectImpl 的监听回调 ConnectImplCallback , 当蓝牙连接状态发生改变、MTU发生改变时进行回调。
属性 |
参数 |
描述 |
|---|---|---|
onMTUChange |
BTBean.BluetoothDevice -> device number -> mtu |
MTU改变 |
onConnectSuccess |
BTBean.BluetoothDevice -> device |
连接成功 |
onConnectFailed |
BTBean.BluetoothDevice -> device BTBean.BluetoothError -> error |
连接失败 |
onConnectDisconnect |
BTBean.BluetoothDevice -> device |
连接断开 |
connect() 方法的连接选项参数:
属性 |
参数 |
描述 |
|---|---|---|
device |
BTBean.BluetoothDevice |
需要连接的设备 |
success |
(info: BluetoothDeviceInfo | undefined) => void |
连接成功回调 |
fail |
(e: BTBean.BluetoothError) => void |
连接失败回调 |
3.3 数据收发相关接口
ble-data-handler.ts 实现连接状态通知、数据接收和分包发送数据。
BleDataHandler 数据接收处理器(单例对象),处理器会把连接状态和接收到的数据回调给所有的Callback。提供接口如下:
方法名 |
功能 |
参数 |
返回值 |
|---|---|---|---|
init |
初始化 |
无 |
void |
addCallbacks |
添加回调 |
BleDataCallback -> callback |
void |
removeCallbacks |
移除回调 |
BleDataCallback -> callback |
void |
BleSendDataHandler 数据发送处理器(单例对象),处理器的机制是:队列式发送数据,发送失败的数据会进行重发(重发次数:3),
发送失败时处理器会继续把缓存队列中的数据全部发送,直到缓存队列清空。提供接口如下:
方法名 |
功能 |
参数 |
返回值 |
|---|---|---|---|
setMtu |
设置设备MTU |
string -> deviceId number -> mtu |
void |
sendData |
发送数据 |
string -> deviceId string -> serviceId string -> characteristicId Uint8Array -> data |
boolean |
数据接收处理器 BleDataHandler 的监听回调 BleDataCallback , 当蓝牙连接状态发生改变、接收到数据时进行回调。
属性 |
参数 |
描述 |
|---|---|---|
onReceiveData |
WechatMiniprogram.OnBLECharacteristicValueChangeCallbackResult -> res |
接收到数据回调 |
onConnectStateChange |
WechatMiniprogram.OnBLEConnectionStateChangeCallbackResult -> res |
连接状态改变回调(已废弃) |
3.4 设备认证相关接口
JlRcsp 库中的 Auth 实现了设备认证流程,由 RCSPFactory 或 OTAWrapper 内部管理。
关于认证需要特别注意以下几点:
在使用RCSP协议进行交互时,若设备端开启认证,小程序端要在RCSP交互之前进行设备认证,否则设备端是不会回复RCSP协议命令。
不可重复认证,大多数设备(仅有少量手表设备支持重复认证)只能一次连接进行一次认证。
Auth 设备认证操作类,提供接口如下:
方法名 |
功能 |
参数 |
返回值 |
|---|---|---|---|
startAuth |
开始认证 |
string -> deviceId AuthListener -> callback boolean -> supportResetFlag |
void |
stopAuth |
停止认证 |
无 |
void |
handlerAuth |
接收认证回复数据 |
string -> deviceId Uint8Array -> data |
void |
设备认证实现类 Auth 的监听回调 AuthListener , 当发送认证数据、认证结束时进行回调。
属性 |
参数 |
描述 |
|---|---|---|
onSendData |
string -> deviceId ArrayBuffer -> data |
发送数据 |
onAuthSuccess |
string -> deviceId |
认证成功 |
onAuthFailed |
string -> deviceId |
认证失败 |
3.5 OTA流程相关接口
JlOta 库实现了OTA流程,包括单备份升级和双备份升级。主入口为 OTAWrapper ,示例工程通过 bluetoothOTAManager.ts 中的 BluetoothOTAManager 进一步封装。
3.5.1 OTA配置
OtaConfig :OTA配置。 在 OTAWrapper.startOTA() 时, 作为参数对 OTAWrapper 进行配置
属性 |
类型 |
描述 |
|---|---|---|
communicationWay |
number |
通讯方式(0-BLE, 1-SPP, 2-USB) |
isSupportNewRebootWay |
boolean |
是否支持新的回连方式 |
3.5.2 OTAWrapper配置
OTAWrapperOption :OTAWrapper 配置。 在创建 OTAWrapper 时作为构造参数传入,用于将蓝牙操作能力注入到OTA流程中。
属性 |
类型 |
描述 |
|---|---|---|
isUseAuth |
() => boolean |
是否需要认证(上层已认证则返回false) |
isInnerReconnect |
() => boolean |
是否需要内部回连(上层回连则返回false) |
sanDevice |
() => void |
扫描设备(一定是BLE设备) |
connectDevice |
(device: BluetoothDevice) => void |
连接设备 |
disconnectDevice |
(device: BluetoothDevice) => void |
断开设备 |
sendData |
(device: BluetoothDevice, data: Uint8Array) => void |
发送数据(可选,内部管理RCSP或需认证时必须实现) |
getRCSPImpl |
(device: BluetoothDevice) => RcspImpl | undefined |
获取RCSP实现(可选,上层管理RCSP时实现) |
3.5.3 设备升级流程回调
OTAUpgradeCallback :设备升级流程回调。 升级过程中的进度和结果都将从这里回调出去。
属性 |
参数 |
描述 |
|---|---|---|
onStartOTA |
无 |
OTA开始 |
onExecuteDisconnectDevice |
无 |
执行断开设备(Spp设备需实现,Ble设备可不实现) |
onNeedReconnect |
ReconnectInfo -> reConnectMsg OnResultCallback<string> -> reconnectCallback |
需要回连设备 |
onProgress |
UpgradeType -> type number -> progress |
进度回调 |
onStopOTA |
无 |
OTA结束 |
onCancelOTA |
无 |
OTA取消(只有双备份有OTA取消) |
onError |
number -> error string -> message |
OTA失败 |
onReadData |
number -> offset number -> size |
读取升级文件数据 |
onRCSPInit |
string -> deviceId boolean -> isInit |
RCSP初始化结果 |
3.5.4 回连信息
ReconnectInfo :回连信息
属性 |
类型 |
描述 |
|---|---|---|
isSupportNewReconnectADV |
boolean |
是否支持新回连方式 |
deviceBleMac |
string |
rcsp协议中的BLE_Mac地址 |
deviceSppMac |
string |
rcsp协议中的SPP_Mac地址 |
Note
当 isSupportNewReconnectADV = false时,回连设备可直接通过deviceId比对判断是不是正在升级的设备,然后进行回连操作。 当 isSupportNewReconnectADV = true时,公版程序回连设备是通过比对设备广播包中的携带的OTA标识和MAC地址进行判断是不是正在升级的设备,然后进行回连操作。
Important
当打开设备Auth的时候,回连设备时也要进行认证才可以进行通讯。
3.5.5 设备升级阶段类型
UpgradeType : 升级阶段类型, OTAUpgradeCallback.onProgress 回调进度时需进行区分。当类型=0时,说明在下载BootLoader(校验文件),当类型=1时,说明在固件升级。
枚举值 |
数值 |
描述 |
|---|---|---|
UPGRADE_TYPE_UNKNOWN |
-1 |
未知 |
UPGRADE_TYPE_CHECK_FILE |
0 |
下载BootLoader(校验文件) |
UPGRADE_TYPE_FIRMWARE |
1 |
固件升级 |
Note
单备份有类型=0和类型=1,双备份只有类型等于1
3.5.6 OTA接口
OTAWrapper OTA实现类,负责管理整个OTA流程(包含RCSP管理、认证、回连和OTA调度)
方法名 |
功能 |
参数 |
返回值 |
|---|---|---|---|
isRCSPInit |
是否初始化成功 |
BluetoothDevice -> device |
Promise<boolean> |
isNeedMandatoryUpgrade |
是否需要强制升级 |
BluetoothDevice -> device |
Promise<boolean> |
startOTA |
开始OTA |
BluetoothDevice -> device OtaConfig -> otaConfig OTAUpgradeCallback -> callback |
void |
cancelOTA |
取消OTA(仅双备份支持) |
BluetoothDevice -> device |
void |
isOTA |
是否正在升级 |
BluetoothDevice -> device(可选) |
boolean |
sendCustomCmd |
发送自定义命令 |
BluetoothDevice -> device Uint8Array -> data CommandCallback<Command> -> callback |
boolean |
getDeviceInfo |
获取设备信息 |
BluetoothDevice -> device |
DeviceInfo | undefined |
registerRcspCallback |
注册RCSP事件回调 |
OTAWrapperListener -> callback |
void |
unregisterRcspCallback |
注销RCSP事件回调 |
OTAWrapperListener -> callback |
void |
release |
释放 |
无 |
void |
OTAWrapper 内部使用 OTAImpl 管理整个OTA业务流程,由 RcspOTAManager 基于RCSP命令实现OTA流程中的命令收发, 供上层实现 IOtaOp 协议时参考。
IOtaOp OTA流程操作的协议实现接口, JLChipOtaOp 实现该接口(非RCSP通道时实现)。
export interface IOtaOp {
/** 是否已连接设备 */
isDeviceConnected(): boolean
/** 切换通讯方式 */
changeCommunicationWay(communicationWay: number, isSupportNewRebootWay: boolean, callback: OnResultCallback<number>): void
/** 读取文件头信息偏移 */
readUpgradeFileFlag(callback: OnResultCallback<FileOffsetInfo>): void;
/** 查询设备是否可升级 */
inquiryDeviceCanOTA(data: Uint8Array, callback: OnResultCallback<number>): void;
/** 非RCSP库不用实现该方法————调整RCSP库的设备收数据的MTU(App的缓存),让数据可以成功发出 */
changeReceiveMtu(): void
/** 进入升级模式 */
enterUpdateMode(callback: OnResultCallback<number>): void;
/** 退出升级模式 */
exitUpdateMode(callback: OnResultCallback<number>): void;
/** 读取设备升级状态 */
queryUpdateResult(callback: OnResultCallback<number>): void;
/** 重启或关闭设备 */
rebootDevice(callback: OnResultCallback<boolean> | null): void;
/** 设置TWS设备通知 */
stopNotifyADV(callback: OnResultCallback<boolean>): void;
/** 回复发送升级固件数据块 */
receiveFileBlock(offset: number, len: number, data: Uint8Array, callback: OnResultCallback<boolean>): void
/** 释放 */
release(): void
}
3.5.7 OTA错误码
OtaError 整个OTA流程的错误回调,继承 RCSPErrorCode。
export class OtaError extends RCSPErrorCode {
/*
* 0x1000 ~ 0x1FFF: 通用错误码
* 0x2000 ~ 0x2FFF: 连接错误码
* 0x3000 ~ 0x3FFF: 通讯错误码
* 0x4000 ~ 0x4FFF: 文件操作错误码
* 0x5000 ~ 0x5FFF: 网络模块错误码
* 0x6000 ~ 0x6FFF: OTA错误码
*/
public static readonly ERR_OTA_DEVICE_LOW_VOLTAGE = 24577; //0x6001 设备低电压
public static readonly ERR_OTA_FIRMWARE_INFO_ERROR = 24578; //0x6002 升级固件信息错误
public static readonly ERR_OTA_FIRMWARE_VERSION_NO_CHANGE = 24579; //0x6003 升级文件的固件版本一致
public static readonly ERR_OTA_TWS_NOT_CONNECT = 24580; //0x6004 TWS未连接
public static readonly ERR_OTA_HEADSET_NOT_IN_CHARGING_BIN = 24581; //0x6005 耳机未在充电仓
public static readonly ERR_OTA_DATA_CHECK_ERROR = 24582; //0x6006 升级数据校验出错
public static readonly ERR_OTA_FAIL = 24583; //0x6007 升级失败
public static readonly ERR_OTA_ENCRYPTED_KEY_NOT_MATCH = 24584; //0x6008 加密key不匹配
public static readonly ERR_OTA_UPGRADE_FILE_ERROR = 24585; //0x6009 升级文件出错
public static readonly ERR_OTA_UPGRADE_TYPE_ERROR = 24586; //0x600A 升级类型出错
public static readonly ERR_OTA_LENGTH_OVER = 24587; //0x600B 升级过程中出现长度错误
public static readonly ERR_OTA_FLASH_IO_EXCEPTION = 24588; //0x600C 出现flash读写错误
public static readonly ERR_OTA_CMD_TIMEOUT = 24589; //0x600D 升级过程中指令超时
public static readonly ERR_OTA_IN_PROGRESS = 24590; //0x600E 正在OTA
public static readonly ERR_OTA_COMMAND_TIMEOUT = 24591; //0x600F 等待升级命令超时
public static readonly ERR_OTA_RECONNECT_DEVICE_TIMEOUT = 24592; //0x6010 回连设备超时
public static readonly ERR_OTA_USE_CANCEL = 24593; //0x6011 用户取消升级
public static readonly ERR_OTA_SAME_FILE = 24594; //0x6012 升级文件相同
public static getErrorDesc(errorCode: number, prefix?: string, explain?: string): string;
}
3.6 RCSP协议库相关接口
JlRcsp RCSP协议库,负责rcsp命令打包命令和解析命令。 RcspImpl 为实现类(继承 RcspImplBase ),可通过 RCSPFactory 静态工厂创建。
3.6.1 RCSP数据发送回调
OnSendDataCallback RCSP数据发送回调, RCSP库将协议数据打包后,从此接口回调给上层发数。
Important
使用RCSP协议库时,该接口必须实现。实现该接口时,上层需要根据mtu进行分包发送处理
/** 数据发送回调 */
interface OnSendDataCallback {
/**
* 向设备发送RCSP数据包
*
* @param device 操作设备
* @param data RCSP数据包
* @return 结果
* <p>
* 说明:
* 1. 该方法需要用户自行实现
* 2. 该方法会回调完整的一包RCSP数据, 用户实现需要根据实际发送MTU进行分包处理
* </p>
*/
sendDataToDevice: (device: BtDevice, data: Uint8Array) => boolean;
}
3.6.2 Rcsp事件回调
OnRcspCallback Rcsp事件回调, 当收到设备主动发送的RCSP命令回复或者RCSP初始化都从此接口回调。
/** Rcsp事件回调*/
declare class OnRcspCallback {
/** Rcsp协议初始化回调 */
onRcspInit(device: BtDevice | null, isInit: boolean): void;
/** 设备主动发送的rcsp命令回调 */
onRcspCommand(device: BtDevice | null, command: Command): void;
/** 设备回复的rcsp命令回调 */
onRcspResponse(device: BtDevice | null, command: Command): void;
/** 设备主动发送的数据命令回调 */
onRcspDataCmd(device: BtDevice | null, dataCmd: Command): void;
/** RCSP错误事件回调 */
onRcspError(device: BtDevice | null, error: number, message: string): void;
/** 需要强制升级回调 */
onMandatoryUpgrade(device: BtDevice | null): void;
/** 设备连接状态 */
onConnectStateChange(device: BtDevice | null, status: ConnectState): void;
}
3.6.3 设备信息
DeviceInfo 设备信息。具体使用请查阅d.ts的DeviceInfo相关属性
3.6.4 Rcsp协议操作接口
RcspImplBase Rcsp协议操作接口(RcspImpl 继承并实现)
方法名 |
功能 |
参数 |
返回值 |
|---|---|---|---|
getUsingDevice |
获取当前使用设备 |
无 |
BtDevice | null |
setOnSendDataCallback |
设置RCSP数据发送回调 |
OnSendDataCallback -> callback |
void |
isDeviceConnected |
是否已连接设备 |
无 |
boolean |
getDeviceInfo |
获取设备信息 |
BtDevice -> device |
DeviceInfo | undefined |
addOnRcspCallback |
添加Rcsp事件回调 |
OnRcspCallback -> callback |
void |
removeOnRcspCallback |
移除Rcsp事件回调 |
OnRcspCallback -> callback |
void |
transmitDeviceState |
传输设备状态 |
BtDevice -> device ConnectState -> status |
void |
transmitDeviceData |
传输设备发送的数据 |
BtDevice -> device Uint8Array -> data |
void |
sendDataToDevice |
发送数据给设备 |
BtDevice -> device Uint8Array -> data |
boolean |
sendRCSPCommand |
发送RCSP命令给设备 |
BtDevice -> device Command -> command number -> timeoutMs CommandCallback<Command> -> callback |
void |
syncDeviceInfo |
异步获取设备信息 |
BtDevice -> device ParamTargetInfo -> param OnResultCallback<ResponseTargetInfo> -> callback |
void |
destroy |
销毁 |
无 |
void |
RCSPFactory RCSP工厂类,用于创建和管理 RcspImpl ,以及统一的认证、设备状态和数据分发处理。
方法名 |
功能 |
参数 |
返回值 |
|---|---|---|---|
init |
初始化工厂 |
OnSendDataCallback -> callback boolean -> isAuth |
void |
create |
创建RcspImpl实例 |
BtDevice -> device |
RcspImpl |
transmitDeviceData |
处理设备数据 |
BtDevice -> device Uint8Array -> data |
void |
transmitDeviceState |
处理设备状态 |
BtDevice -> device ConnectState -> status |
void |
releaseRCSPImpl |
释放指定设备的RcspImpl实例 |
BtDevice -> device |
void |
destroy |
销毁所有RcspImpl实例 |
无 |
void |
isConnectedDeviceId |
检查设备ID是否已连接 |
string -> deviceId |
boolean |
CommandCallback 设备命令回调,发送带回复的RCSP命令后,设备回复时回调。
属性 |
参数 |
描述 |
|---|---|---|
onCmdResponse |
BtDevice -> device Command -> command |
命令回复 |
onError |
BtDevice -> device number -> code string -> message |
命令错误 |