3. 接口说明

3.1 蓝牙扫描相关接口

scan.ts 实现蓝牙扫描， ScanImpl 蓝牙扫描操作类，提供接口如下：

方法名	功能	参数	返回值
setCallback	添加扫描回调	ScanCallback -> callback//蓝牙扫描事件回调	void
startScan	开始扫描	无	void
stopScan	停止扫描	无	void

蓝牙扫描实现类 ScanImpl 的监听回调 ScanCallback , 当蓝牙状态发生改变、扫描状态发生改变、发现设备时进行回调。

属性	参数	描述
onAdapter	WechatMiniprogram.OnBluetoothAdapterStateChangeCallbackResult-> res	蓝牙适配器发生变化
onSuccess	无	启动扫描成功
onFailed	无	启动扫描失败
onFound	WechatMiniprogram.BlueToothDevice[]-> devices	扫描发现设备

3.2 蓝牙连接相关接口

connect.ts 实现蓝牙连接和调整MTU， ConnectImpl 蓝牙连接操作类，提供接口如下：

方法名	功能	参数	返回值
connect	连接设备	WechatMiniprogram.BlueToothDevice -> device	void
disconnect	断开设备	无	void
setCallback	设置回调	ConnectCallback -> callback//蓝牙连接事件回调	void
getConnectedDevice	获取已连接设备	无	WechatMiniprogram.BlueToothDevice \| null
getCommunicationService	获取通讯服务	无	WechatMiniprogram.BLEService \| null
getCommunicationWriteCharacteristic	获取通讯特征值	无	WechatMiniprogram.BLECharacteristic \| null
getMTU	获取MTU	无	number \| undefined
isConnectedOrConnecting	是否正在连接或已连接	无	boolean
isConnecting	是否正在连接	无	boolean
isConnected	是否已连接	无	boolean

蓝牙连接实现类 ConnectImpl 的监听回调 ConnectCallback , 当蓝牙连接状态发生改变、MTU发生改变时进行回调。

属性	参数	描述
onDisconnect	WechatMiniprogram.BlueToothDevice-> result	设备断开
onFailed	WechatMiniprogram.BlueToothDevice-> result	连接失败
onSuccess	WechatMiniprogram.BlueToothDevice-> result	连接成功
onMTUChange	WechatMiniprogram.BlueToothDevice-> result number->mtu	设备MTU改变

3.3 数据收发相关接口

ble-data-handler.ts 实现连接状态通知、数据接收和分包发送数据。 BleDataHandler 数据接收处理器(单例)，处理器会把连接状态和接收到的数据回调给所有的Callback。提供接口如下：

方法名	功能	参数	返回值
init	初始化	无	void
addCallbacks	添加回调	BleDataCallback-> callback//数据接收器回调	void
removeCallbacks	移除回调	BleDataCallback-> callback//数据接收器回调	void

BleSendDataHandler 数据发送处理器(单例)，处理器的机制是：队列式发送数据，发送失败的数据会进行重发（重发次数：3），

发送失败时处理器会继续把缓存队列中的数据全部发送，直到缓存队列清空。提供接口如下：

方法名

功能

参数

返回值

setMtu

设置设备MTU

string->deviceId//设备mac地址

number->mtu//设备MTU大小

void

sendData

发送数据

string-> deviceId//设备mac地址

string->serviceId//服务UUID

string->characteristicId//特征值UUID

Uint8Array->data//数据

void

数据接收处理器 BleDataHandler 的监听回调 BleDataCallback , 当蓝牙连接状态发生改变、接收到数据时进行回调。

属性	参数	描述
onReceiveData	WechatMiniprogram.OnBLECharacteristicValueChangeCallbackResult-> res	接收到数据回调
onConnectStateChange	WechatMiniprogram.OnBLEConnectionStateChangeCallbackResult-> res	连接状态改变回调

3.4 设备认证相关接口

jl_auth_vxxx-release 实现了设备认证流程。

关于认证需要特别注意以下几点：

在使用RCSP协议进行交互时，若设备端开启认证，小程序端要在RCSP交互之前进行设备认证，否则设备端是不会回复RCSP协议命令。
不可重复认证，大多数设备（仅有少量手表设备支持重复认证）只能一次连接进行一次认证。

Auth 设备认证操作类，提供接口如下：

方法名

功能

参数

返回值

startAuth

开始认证

WechatMiniprogram.BlueToothDevice->deviceId//设备

AuthListener->callback//设备认证监听回调

void

handlerAuth

接收认证回复数据

string-> deviceId//设备mac地址

ArrayBuffer->data//回复数据

void

设备认证实现类 Auth 的监听回调 AuthListener , 当发送认证数据、认证结束时进行回调。

属性	参数	描述
onSendData	WechatMiniprogram.BlueToothDevice-> device data-> ArrayBuffer	发送数据
onAuthSuccess	WechatMiniprogram.BlueToothDevice-> device	认证成功
onAuthFailed	WechatMiniprogram.BlueToothDevice-> device	认证失败

3.5 OTA流程相关接口

jl_ota_vxxx-release 实现了OTA流程，包括单备份升级和双备份升级。

3.5.1 OTA配置

OTAConfig ：OTA配置。在 OTAImpl.startOTA() 时，作为参数对 OTAImpl 进行配置

属性	类型	描述
communicationWay	number	通讯方式(目前只支持BLE)
isSupportNewRebootWay	boolean	是否支持新的回连方式
updateFileData	Uint8Array	固件升级文件数据

3.5.2 设备升级相关信息

DeviceUpgradeInfo ：设备升级相关信息。设备连接成功后，需要将设备的升级相关信息同步给 OTAImpl ，可以通过 OTAImpl.onDeviceInit() 进行同步

属性	类型	描述
isSupportDoubleBackup	boolean	是否支持双备份
isNeedBootLoader	boolean	是否需要下载Loader
isMandatoryUpgrade	boolean	是否需要强制升级

3.5.3 设备升级流程回调

OnUpgradeCallback ：设备升级流程回调。升级过程中的进度和结果都将从这里回调出去。

属性	参数	描述
onStartOTA	无	OTA开始
onNeedReconnect	ReConnectMsg-> reConnectMsg // 回连信息	需要回连设备
onProgress	UpgradeType-> type // 设备升级阶段类型 number-> progress //进度值0-100	进度回调
onStopOTA	无	OTA结束
onCancelOTA	无	OTA取消（只有双备份有OTA取消）
onError	number->error // OTA错误码 string->message // 错误信息描述	OTA失败

3.5.4 回连信息

ReconnectMsg ：回连信息

属性	类型	描述
isSupportNewReconnectADV	boolean	是否支持新回连方式

Note

当 isSupportNewReconnectADV = false时，回连设备可直接通过deviceId比对判断是不是正在升级的设备，然后进行回连操作。当 isSupportNewReconnectADV = true时,公版程序回连设备是通过比对设备广播包中的携带的OTA标识和MAC地址进行判断是不是正在升级的设备，然后进行回连操作。

Important

当打开设备Auth的时候，回连设备时也要进行认证才可以进行通讯。

3.5.4 设备升级阶段类型

UpgradeType : 升级阶段类型， OnUpgradeCallback.onProgress 回调进度时需进行区分。当类型=0时，说明在ubootloader下载，当类型=1时，说明在固件升级。

Note

单备份有类型=0和类型=1，双备份只有类型等于1

3.5.5 OTA接口

OTAImpl OTA实现类，负责管理整个OTA流程

方法名	功能	参数	返回值
constructor	初始化构建	IOTAOp->iOTAOp // IOTAOp	void
release	释放缓存	无	void
isOTA	是否正在升级	无	boolean
startOTA	开始OTA	OtaConfig->otaConfig // OTA配置 OnUpgradeCallback->callback//设备升级流程回调	void
cancelOTA	取消OTA	无	boolean
onDeviceInit	设备初始化	DeviceUpgradeInfo->deviceUpgradeInfo//设备升级相关信息 boolean->isInit//RCSP是否初始化成功	void
onDeviceDisconnect	设备断开通知	无	void
notifyUpgradeSize	设备通知文件大小	number->totalSize//总大小 number->currentSize//当前升级大小	void
gainFileBlock	设备获取升级文件块	number->offset//文件偏移 number->len//文件块长度	void

3.5.6 OTA错误码

OTAError 整个OTA流程的错误回调

export class OTAError {
  /*
  * -1  -- Unknown error
  * 0x0   -- Success
  * - 0x02 - 0x1F: Common error
  * - 0x20 - 0x3F: Device error
  * - 0x40 - 0x5F: Communication error
  */
  public static readonly ERROR_UNKNOWN = -0x01;             //未知错误
  public static readonly ERROR_NONE = 0x00;                 //没有错误

  public static readonly ERROR_INVALID_PARAM = -0x02;       //无效参数
  public static readonly ERROR_DATA_FORMAT = -0x03;         //数据格式错误
  public static readonly ERROR_NOT_FOUND_RESOURCE = -0x04;  //没有找到资源

  public static readonly ERROR_UNKNOWN_DEVICE = -0x20;      //未知设备
  public static readonly ERROR_DEVICE_OFFLINE = -0x21;      //设备下线
  public static readonly ERROR_IO_EXCEPTION = -0x23;        //IO异常
  public static readonly ERROR_REPEAT_STATUS = -0x24;       //重复状态

  public static readonly ERROR_RESPONSE_TIMEOUT = -0x40;    //等待回复命令超时
  public static readonly ERROR_REPLY_BAD_STATUS = -0x41;    //设备回复不好的状态
  public static readonly ERROR_REPLY_BAD_RESULT = -0x42;    //设备回复错误的结果
  public static readonly ERROR_NONE_PARSER = -0x43;         //没有对应的解析器
  /*
  * - 0x60 - 0x7F: OTA error
  */
  //设备低电压
  public static readonly ERROR_OTA_LOW_POWER = -0x61;
  //升级固件信息错误
  public static readonly ERROR_OTA_UPDATE_FILE = -0x62;
  //升级文件的固件版本一致
  public static readonly ERROR_OTA_FIRMWARE_VERSION_NO_CHANGE = -0x63;
  //TWS未连接
  public static readonly ERROR_OTA_TWS_NOT_CONNECT = -0x64;
  //耳机未在充电仓
  public static readonly ERROR_OTA_HEADSET_NOT_IN_CHARGING_BIN = -0x65;

  //升级数据校验出错
  public static readonly ERROR_OTA_DATA_CHECK_ERROR = -0x66;
  //升级失败
  public static readonly ERROR_OTA_FAIL = -0x67;
  //加密key不匹配
  public static readonly ERROR_OTA_ENCRYPTED_KEY_NOT_MATCH = -0x68;
  //升级文件出错
  public static readonly ERROR_OTA_UPGRADE_FILE_ERROR = -0x69;
  //升级类型出错
  public static readonly ERROR_OTA_UPGRADE_TYPE_ERROR = -0x6A;
  //升级过程中出现长度错误
  public static readonly ERROR_OTA_LENGTH_OVER = -0x6B;
  //出现flash读写错误
  public static readonly ERROR_OTA_FLASH_IO_EXCEPTION = -0x6C;
  //升级过程中指令超时
  public static readonly ERROR_OTA_CMD_TIMEOUT = -0x6D;

  //正在OTA
  public static readonly ERROR_OTA_IN_PROGRESS = -0x6E;
  //等待命令超时
  public static readonly ERROR_OTA_COMMAND_TIMEOUT = -0x6F;
  //回连设备超时
  public static readonly ERROR_OTA_RECONNECT_DEVICE_TIMEOUT = -0x70;
  //用户取消升级
  public static readonly ERROR_OTA_USE_CANCEL = -0x71;
}

3.5.7 IOTAOp

IOTAOp OTA流程操作的协议实现接口， RcspOTA 实现该接口。

export interface IOTAOp {
  /** 是否已连接设备 */
  isDeviceConnected(): boolean
  /** 切换通讯方式 */
  changeCommunicationWay(communicationWay: number, isSupportNewRebootWay: boolean, callback: OnResultCallback<number>): void
  /** 读取文件头信息偏移 */
  readUpgradeFileFlag(callback: OnResultCallback<FileOffset>): 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.6 RCSP协议库相关接口

jl_rcsp_ota_vxxx-release RCSP协议库，负责rcsp命令打包命令和解析命令。 RcspOpImpl 为实现类接口。

3.6.1 RCSP数据发送回调

OnSendDataCallback RCSP数据发送回调， RCSP库将协议数据打包后，从此接口回调给上层发数。

Important

使用RCSP协议库时，该接口必须实现。实现该接口时，上层需要根据mtu进行分包发送处理

/** 数据发送回调 */
interface OnSendDataCallback {
    /**
    * 向设备发送RCSP数据包
    *
    * @param device 操作设备
    * @param data   RCSP数据包
    * @return 结果
    * <p>
    * 说明:
    * 1. 该方法需要用户自行实现
    * 2. 该方法运行在子线程，允许阻塞处理
    * 3. 该方法会回调完整的一包RCSP数据, 用户实现需要根据实际发送MTU进行分包处理
    * </p>
    */
    sendDataToDevice: (device: Device, data: Uint8Array) => boolean;
}

3.6.2 Rcsp事件回调

OnRcspCallback Rcsp事件回调，当收到设备主动发送的RCSP命令回复或者RCSP初始化都从此接口回调。

/** Rcsp事件回调*/
declare abstract class OnRcspCallback {
    /**
    * Rcsp协议初始化回调
    *
    * @param device 已连接设备
    * @param isInit 初始化结果
    */
    onRcspInit(device?: Device | null, isInit?: boolean): void;
    /**
    * 设备发送的rcsp命令回调
    *
    * @param device  已连接设备
    * @param command RCSP命令
    */
    onRcspCommand(device: Device | null, command: CommandBase): void;
    /**
    * 设备发送的数据命令回调
    *
    * @param device  已连接设备
    * @param dataCmd 数据命令
    */
    onRcspDataCmd(device: Device | null, dataCmd: CommandBase): void;
    /**
    * RCSP错误事件回调
    *
    * @param device  设备对象
    * @param error   错误码 (参考{@link com.jieli.rcsp.data.constant.ErrorCode})
    * @param message 错误描述
    */
    onRcspError(device: Device | null, error: number, message: string): void;
    /**
    * 需要强制升级回调
    *
    * @param device 需要强制升级的设备
    */
    onMandatoryUpgrade(device: Device | null): void;
    /**
    * 设备连接状态
    *
    * @param device 蓝牙设备
    * @param status 连接状态
    */
    onConnectStateChange(device: Device | null, status: Connection): void;
}

3.6.3 设备信息

DeviceInfo 设备信息。具体使用请查阅d.ts的DeviceInfo相关属性

3.6.4 Rcsp协议操作接口

RcspOpImpl Rcsp协议操作接口

方法名	功能	参数	返回值
constructor	初始化构建	无	void
destroy	销毁	无	void
getUsingDevice	获取当前使用设备	无	Device
setOnSendDataCallback	设置RCSP数据发送回调	OnSendDataCallback->callback	void
isDeviceConnected	是否已连接设备	无	boolean
getDeviceInfo	获取设备信息	Device->device	DeviceInfo
addOnRcspCallback	添加Rcsp事件回调	OnRcspCallback->callback	void
removeOnRcspCallback	移除Rcsp事件回调	OnRcspCallback->callback	void
transmitDeviceStatus	传输设备状态	Device->device Connection->status	void
transmitDeviceData	传输设备发送的数据	Device->device Uint8Array->data	void
sendDataToDevice	发送数据给设备	Device->device Uint8Array->data	boolean
sendRCSPCommand	发送RCSP命令给设备	Device->device CommandBase->command number->timeoutMs //命令超时时间 RcspBase.CommandCallback<RcspBase.CommandBase>->callback//命令结果回调 OnUpgradeCallback->callback//设备升级流程回调	void
syncDeviceInfo	异步获取设备信息	Device->device ParamTargetInfo->param//设备信息参数 OnResultCallback<ResponseTargetInfo> ->callback//结果回调	void