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

命令错误