3. 接口说明

3.1 手表操作对象

3.1.1 目录浏览

目录浏览接口 IOperateDirectoryBrowse

接口名	参数	返回值	描述
removeAllEventCallback	无	void	移除全部事件监听回调
registerEventCallback	OperaterEventCallbackDirectoryBrowse: 目录事件回调	void	注册回调
unregisterEventCallback	OperaterEventCallbackDirectoryBrowse: 目录事件回调	void	注销回调
loadMore	file: 目标文件夹 readPageSize?: 读取子文件数量	Promise<File>	加载该文件夹下更多文件列表
appendBrowse	file: 目标文件夹 readPageSize?: 读取子文件数量 maxDepth?: 最大文件夹层数(默认:8)	Promise<File>	该文件进入下一级
backBrowse	file: 目标文件夹	Promise<File>	该文件返回上一级
getOnLineStorageDevs	无	File[]	获取在线存储设备列表
getFileByPath	path:文件绝对路径	File	根据路径获取文件
deleteFile	files: 删除文件数组	Promise<any>	删除文件
reloadFolder	file: 目标文件夹	Promise<File>	重读文件夹

目录事件 OperaterEventDirectoryBrowse 。目录事件回调(OperaterEventCallbackDirectoryBrowse)在 onEvent 方法回调目录事件 OperaterEventDirectoryBrowse

事件类型	参数	描述
NONE	无	没有事件发生
onDirectoryChange	onDirectoryChange.folder:发生改变的文件夹	目录发生变化

3.1.2 存储设备管理

存储设备管理接口 IOperateDirectoryBrowse。通常情况下，是只通过这个接口获取在线存储设备，该接口主要是给SDK内部使用。

接口名	参数	返回值	描述
removeAllEventCallback	无	void	移除全部事件监听回调
registerEventCallback	OperaterEventCallbackFile: 存储设备事件回调	void	注册回调
unregisterEventCallback	OperaterEventCallbackFile: 存储设备事件回调	void	注销回调
getSdCardBeans	无	SDCardBean[]	获取支持的存储设备(含不在线设备)
getOnLineSdCardBeans	无	SDCardBean[]	获取在线的存储设备
notifySdCardBeanDirectoryUpdate	sdCardBean:目录更新变化的存储设备	void	通知存储设备的目录更新

存储设备事件 OperaterEventFile 。目录事件回调(OperaterEventCallbackFile)在 onEvent 方法回调存储设备事件 OperaterEventFile

事件类型	参数	描述
NONE	无	没有事件发生
onSdCardChange	onSdCardChange.sdCardBeans:发生改变后的存储设备列表	存储设备状态发生变化
onSdCardDirectoryChange	onSdCardDirectoryChange.sdCardBean:目录改变的存储设备	存储设备目录发生变化

3.1.3 文件下载

文件下载接口 IOperateLargeFileTrans。

接口名	参数	返回值	描述
removeAllEventCallback	无	void	移除全部事件监听回调
registerEventCallback	OperaterEventCallbackLargeFileTrans: 大文件传输事件回调	void	注册回调
unregisterEventCallback	OperaterEventCallbackLargeFileTrans: 大文件传输事件回调	void	注销回调
excuteTransferTask	param:文件传输任务参数	boolean	执行传输
cancelTransfer	无	void	取消传输
isFree	无	boolean	是不是空闲

文件传输任务参数

事件类型	描述
fileBuffer	文件数据
sdCardBean	存放的存储设备
isSupportPackageCrc16	是否支持包crc校验（默认支持）
fileName	文件名
lastModifyTime	文件最新更改时间
fileNameEncodeFormat	文件名编码格式（ 0:没有指定编码方式，1：gbk，2：utf-16e ）

3.1.4 文件读取

文件读取接口 IOperateLargeFileGet。

接口名	参数	返回值	描述
removeAllEventCallback	无	void	移除全部事件监听回调
registerEventCallback	OperaterEventCallbackLargeFileGet: 文件读取事件回调	void	注册回调
unregisterEventCallback	OperaterEventCallbackLargeFileGet: 文件读取事件回调	void	注销回调
excuteGetTaskByFileName	param:文件传输任务参数(文件名方式)	boolean	执行传输-文件名（已弃用）
excuteGetTaskByFileCluster	param:文件传输任务参数(簇号方式)	boolean	执行传输-簇号
excuteGetTaskByFileNameAndDevHandle	param:文件传输任务参数(文件名指定设备方式)	boolean	执行传输-文件名指定设备方式
cancelGet	无	void	取消获取
isFree	无	boolean	是不是空闲

文件传输任务参数(文件名方式)

事件类型	描述
offset	偏移地址(默认填0)
fileName	文件名
callback	传输回调

文件传输任务参数(簇号方式)

事件类型	描述
offset	偏移地址(默认填0)
sdCardBean	指定存储设备
cluster	簇号
callback	传输回调

文件传输任务参数(文件名指定设备方式)

事件类型	描述
offset	偏移地址(默认填0)
sdCardBean	指定存储设备
fileName	文件名
callback	传输回调

3.1.5 系统信息

系统信息接口 IOperateSystemInfo

接口名	参数	返回值	描述
removeAllEventCallback	无	void	移除全部事件监听回调
registerEventCallback	OperaterEventSystemInfo: 系统信息事件回调	void	注册回调
unregisterEventCallback	OperaterEventSystemInfo: 系统信息事件回调	void	注销回调
reloadSystemInfo	无	Promise<SystemInfo>	重新获取系统信息
getSystemInfo	无	Promise<SystemInfo>	获取系统信息(缓存)

系统信息事件 OperaterEventSystemInfo 系统信息事件回调(OperaterEventSystemInfo)在 onEvent 方法回调系统信息事件 OperaterEventSystemInfo

事件类型	参数	描述
NONE	无	没有事件发生
SystemInfoChange	SystemInfoChange.systemInfo:新的系统信息	系统信息变化

3.1.6 手表信息

手表信息接口 IOperateWatch

接口名	参数	返回值	描述
removeAllEventCallback	无	void	移除全部事件监听回调
registerEventCallback	OperaterEventCallbackWatch: 手表信息事件回调	void	注册回调
unregisterEventCallback	OperaterEventCallbackWatch: 手表信息事件回调	void	注销回调
reloadFlashInfo	无	Promise<ResponseReadExternalFlashInfo>	重新获取flash信息
getFlashInfo	无	Promise<ResponseReadExternalFlashInfo>	获取flash信息(缓存)

手表信息事件 OperaterEventWatch 手表信息事件回调(OperaterEventCallbackWatch)在 onEvent 方法回调手表信息事件 OperaterEventWatch

事件类型	参数	描述
NONE	无	没有事件发生
FlashInfoChange	FlashInfoChange.flashInfo:新的flash信息	flash信息变化

flash信息中包含了flash大小，以及屏幕宽高等信息。

3.1.7 表盘操作

表盘操作接口 IOperateWatchDial

接口名	参数	返回值	描述
removeAllEventCallback	无	void	移除全部事件监听回调
registerEventCallback	OperaterEventCallbackWatchDial: 表盘事件回调	void	注册回调
unregisterEventCallback	OperaterEventCallbackWatchDial: 表盘事件回调	void	注销回调
setIgnoreFileList	ignoreList:过滤列表	void	设置过滤文件列表
getWatchResourseFileList	无	Promise<Array<File>>	获取手表Flash资源文件列表
reloadWatchResourseFileList	无	Promise<Array<File>>	重新获取手表Flash资源文件列表
getUsingDial	无	Promise<File>	获取正在使用的表盘
cancelAddWatchResourseFile	无	void	取消添加手表Flash资源文件
addWatchResourseFile	fileData:文件数据 fileName:文件名 lastModifyTime:修改时间 refreshDirectory:是否刷新目录 callback:传输过程回调	Promise<File | string | undefined> //刷新目录回调File| undefined //不刷新目录回调string| undefined	添加手表Flash资源文件(表盘，背景)
setUsingDial	dial:表盘	Promise<boolean>	设置当前表盘
getDialVersionInfo	dial:表盘	Promise<string>	获取表盘版本信息
getDialCustomBackground	dial:表盘	Promise<File | null>	获取表盘背景
setDialCustomBackground	dialBackground:自定义表盘背景	Promise<boolean>	设置自定义表盘背景
deleteDial	dial:表盘	Promise<boolean>	删除表盘
deleteDialCustomBackground	dialBackground:自定义表盘背景	Promise<boolean>	删除自定义表盘背景

表盘事件 OperaterEventWatchDial 表盘事件回调(OperaterEventCallbackWatchDial)在 onEvent 方法回调表盘事件 OperaterEventWatchDial

事件类型	参数	描述
NONE	无	没有事件发生
UseDialChange	UseDialChange.dial:表盘	当前表盘变化
WatchResourseFileListChange	WatchResourseFileListChange.fileList	手表Flash资源文件列表变化

3.2 数据收发相关接口

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.3 设备认证相关接口

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.4 OTA流程相关接口

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

3.4.1 OTA配置

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

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

3.4.2 设备升级相关信息

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

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

3.4.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.4.4 回连信息

ReconnectMsg ：回连信息

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

Note

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

Important

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

3.4.5 设备升级阶段类型

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

Note

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

3.4.6 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.4.7 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.4.8 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.5 RCSP协议库相关接口

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

3.5.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.5.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.5.3 设备信息

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

3.5.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