mini_program_gizwits_sdk 3.7.8-cozev5 → 3.7.8-kuka

package/README.md

@@ -2,6 +2,14 @@
 
 # 机智云小程序 SDK
 
+
+## 🔴 破坏性更新
+
+- 3.2.4（含）开始蓝牙广播包过滤增加了 `['ABF8', 'ABF0', 'F0AB', 'F8AB']` 四个过滤字段，为了兼容部分低端手机不过滤，长时间挂机会假死的问题。
+- 乐鑫_0ESP32C3_0403000G 和 博流_00BL602L_0403000B 之后的版本都支持这个特性。
+- 如果您使用的是更早期的固件，请联系我们。
+
+
 ## ⚠️ 重要
 
 使用小程序 sdk 前，请在微信开发者后台-开发管理-开发设置-服务器域名添加以下请求地址。
@@ -11,7 +19,6 @@
 ```txt
 https://api.gizwits.com
 https://site.gizwits.com
-https://agent.gizwitsapi.com
 ```
 
 - socket 合法域名
@@ -21,16 +28,6 @@ wss://wxstage.gizwits.com
 wss://wxm2m.gizwits.com
 ```
 
-- 关于 services
-
-为了搜索效率，sdk 会根据`services `过滤蓝牙设备。默认 ['ABF8', 'ABF0', 'F0AB', 'F8AB']。
-如果有特殊情况，不想用`services `过滤设备，可以
-
-```js
-sdk.scanBleDevice(3000, []);
-sdk.startAutoScan([]);
-```
-
 ## 🔧 安装
 
 ```bash
@@ -43,13 +40,13 @@ yarn add mini_program_gizwits_sdk
 
 > 采用小程序代码片段，安装新版小程序开发工具，点击链接即可打开
 
-### 蓝牙配网
+### 蓝牙和 softAp 配网
 
-[点击打开微信开发者工具](https://developers.weixin.qq.com/s/Wk0aZlmg7jOR)
+[点击打开微信开发者工具](https://developers.weixin.qq.com/s/UQI8fpm87jDI)
 
 ### 设备控制
 
-[点击打开微信开发者工具](https://developers.weixin.qq.com/s/Kh0CMlmq77OA)
+[点击打开微信开发者工具](https://developers.weixin.qq.com/s/NZI5gpmX7qD1)
 
 ## 🏍 初始化 Sdk
 
@@ -62,7 +59,7 @@ export default class Index extends Component {
   private gizSdk: GizwitsSdk;
 
   componentDidMount() {
-    const sdkInitParams = {
+    this.gizSdk = new GizwitsSdk({
       appID: 'appID',
       appSecret: 'appSecret',
       productInfo: [
@@ -71,12 +68,9 @@ export default class Index extends Component {
           productSecret: 'productSecret',
         },
       ],
-    };
-    if (!this.gizSdk) {
-      this.gizSdk = new GizwitsSdk(sdkInitParams);
-    } else {
-      this.gizSdk.reInit(sdkInitParams);
-    }
+      uid: 'giz_uid', // 必填
+      token: 'giz_token', // 必填
+    });
   }
 
   render() {
@@ -86,492 +80,81 @@ export default class Index extends Component {
 ```
 
 ## 📋 日志
-
 sdk.setLogLevel("debug")
 
-## 用户相关
-
-SDK 提供了两种登录方式：匿名登录和微信登录。
-
-### 匿名登录
-
-```typescript
-// 使用 唯一ID 进行匿名登录
-// 适用于 已经有业务后台的场景
-const result = await sdk.login(openID);
-if (result.success) {
-  // 登录成功，可以获取到 token 和 uid
-  const { token, uid } = result.data;
-}
-```
-
-### 微信登录
-
-```typescript
-// 使用微信登录 直接登录到 Gizwits
-const result = await sdk.wxLogin();
-if (result.success) {
-  // 登录成功，返回数据包含：
-  // - token: 访问令牌
-  // - uid: 用户ID
-  // - expire_at: 令牌过期时间
-  const { token, uid, expire_at } = result.data;
-} else {
-  // 登录失败
-  console.error(result.message);
-}
-```
-
-### 登录结果说明
-
-登录成功后会：
-
-1. 自动保存 token 和 uid 到全局数据
-2. 更新 WebSocket 连接的认证信息
-3. 返回登录结果，包含：
-   - token: 访问令牌
-   - uid: 用户 ID
-   - expire_at: 令牌过期时间（仅微信登录返回）
+## 📖 BLE API
 
-#### 注意事项
+小程序 BLE 相关 API。
 
-1. 登录是使用其他功能的前提，建议在初始化 SDK 后立即进行登录
-2. 微信登录需要确保小程序已经获取了用户授权
-3. 登录成功后，SDK 会自动处理 token 的存储和更新
-
-#### 错误处理
-
-```typescript
-try {
-  const result = await sdk.wxLogin();
-  if (!result.success) {
-    // 处理登录失败
-    console.error('登录失败:', result.message);
-  }
-} catch (error) {
-  // 处理异常
-  console.error('登录异常:', error);
-}
-```
-
-## ota
-
-### 获取设备当前版本
-
-获取设备的软硬件版本信息。
-
-```typescript
-const result = await sdk.getDeviceVersion(deviceId);
-if (result.success) {
-  // 获取成功
-  const { soft_version, hard_version } = result.data;
-  console.log('软件版本:', soft_version);
-  console.log('硬件版本:', hard_version);
-} else {
-  // 获取失败
-  console.error('获取版本失败:', result.err);
-}
-```
-
-#### 参数说明
-
-| 参数     | 类型   | 必填 | 说明    |
-| -------- | ------ | ---- | ------- |
-| deviceId | string | 是   | 设备 ID |
-
-#### 返回值说明
-
-| 字段         | 类型   | 说明       |
-| ------------ | ------ | ---------- |
-| soft_version | string | 软件版本号 |
-| hard_version | string | 硬件版本号 |
-
-#### 注意事项
-
-1. 设备必须已经绑定
-2. 设备必须在线
-3. 版本号格式通常为 x.y.z 的形式
-
-#### 错误处理
-
-```typescript
-try {
-  const result = await sdk.getDeviceVersion(deviceId);
-
-  if (!result.success) {
-    // 处理获取失败
-    console.error('获取版本失败:', result.err);
-    return;
-  }
-
-  // 获取成功，可以开始使用版本信息
-  const { soft_version, hard_version } = result.data;
-} catch (error) {
-  // 处理异常
-  console.error('获取版本异常:', error);
-}
-```
-
-### 检查更新
-
-```typescript
-const result = await sdk.checkAvailableUpdates(deviceInfo.id, deviceInfo.soft_version);
-console.log('resultresultresult', result);
-if (result.success && result.data) {
-  setUpdateInfo(result.data);
-} else {
-  setUpdateInfo(null);
-  Taro.showToast({
-    title: '没有可用的更新',
-    icon: 'none',
-  });
-}
-```
-
-### 开始更新
-
-```typescript
-const sdk = getGlobalData('gizSdk');
-const result = await sdk.startUpdate(deviceInfo.id);
-console.log('resultresultresult', result);
-```
-
-### 查询进度
-
-获取设备 OTA 更新的当前进度。
-
-```typescript
-const result = await sdk.getOtaStatus(deviceId);
-if (result.success) {
-  if (result.data !== null) {
-    // 有进度信息，显示进度
-    console.log('OTA 更新进度:', result.data);
-  } else {
-    // 没有进度信息
-    console.log('暂无 OTA 更新进度');
-  }
-} else {
-  // 获取进度失败
-  console.error('获取 OTA 进度失败:', result.err);
-}
-```
-
-#### 参数说明
-
-| 参数     | 类型   | 必填 | 说明    |
-| -------- | ------ | ---- | ------- |
-| deviceId | string | 是   | 设备 ID |
-
-#### 返回值说明
-
-| 字段 | 类型           | 说明                                                  |
-| ---- | -------------- | ----------------------------------------------------- |
-| data | number \| null | 更新进度百分比（0-100），如果为 null 表示暂无进度信息 |
-
-#### 注意事项
-
-1. 设备必须已经绑定
-2. 设备必须在线
-3. 只有在进行 OTA 更新时才会返回进度信息
-4. 进度信息有 1 分钟的有效期，超过 1 分钟未更新则返回 null
-
-#### 错误处理
-
-```typescript
-try {
-  const result = await sdk.getOtaStatus(deviceId);
-
-  if (!result.success) {
-    // 处理获取失败
-    console.error('获取 OTA 进度失败:', result.err);
-    return;
-  }
-
-  // 获取成功，处理进度信息
-  if (result.data !== null) {
-    // 有进度信息
-    console.log('OTA 更新进度:', result.data);
-  } else {
-    // 没有进度信息
-    console.log('暂无 OTA 更新进度');
-  }
-} catch (error) {
-  // 处理异常
-  console.error('获取 OTA 进度异常:', error);
-}
-```
-
-## 蓝牙相关
-
-### 初始化蓝牙
+### sdk.initBle()
 
 初始化 sdk 蓝牙能力。使用其他`BLE API`前**必须**进行初始化。
 
-```typescript
-sdk.initBle();
-```
-
-### 搜索蓝牙
+### sdk.scanBleDevice(delay?:number, services?: string[])
 
 搜索蓝牙设备。搜索到的蓝牙设备会被 [onScanListChange](#onScanListChange) 事件监听。
 
-```
-// 参数
-// - delay: 超时时间。
-// - services: 过滤services的条件，不传默认 ['ABF8', 'ABF0', 'F0AB', 'F8AB']
-
-sdk.scanBleDevice(delay?:number, services?: string[])
-```
+#### 参数
 
-### 自动搜索
+- delay: 超时时间。
+- services: 过滤services的条件，不传默认 ['ABF8', 'ABF0', 'F0AB', 'F8AB']
 
-间隔 3s 搜索一次
+### sdk.startAutoScan(services?: string[])
 
 间隔自动搜索蓝牙设备 [onScanListChange](#onScanListChange) 事件监听。
 
-```typescript
-// 参数
-// - services: 过滤services的条件，不传默认 ['ABF8', 'ABF0', 'F0AB', 'F8AB']
-sdk.startAutoScan(services?: string[])
-```
-
-## 设备管理
-
-### 获取设备列表
-
-刷新设备列表(同时也会在 GizDeviceListNotifications 事件里推送)
-
-```typescript
-const data = await sdk.getDevices();
-console.log(data);
-```
-
-### 开始配网
-
-配网是将设备连接到 WiFi 网络的过程。SDK 支持多种配网方式：SoftAP、BLE 和 NFC（仅安卓）。
-
-```typescript
-const result = await sdk.setDeviceOnboardingDeploy({
-  ssid: 'wifi_ssid', // WiFi 名称
-  password: 'wifi_password', // WiFi 密码
-  mode: 3, // 配网模式：0-SoftAP, 3-BLE, 5-NFC
-  timeout: 60, // 配网超时时间（秒）
-  productKey: 'product_key', // 产品 Key
-  isBind: true, // 是否自动绑定设备
-  softAPSSIDPrefix: 'XPG-GAgent-', // SoftAP 模式下的设备热点前缀，蓝牙配网模式下的蓝牙设备名称
-  eventCallBack: event => {
-    // 配网过程事件回调
-    console.log('配网事件:', event);
-  },
-  mac: '123456', // BLE配网下使用mac对蓝牙设备进行过滤
-});
-
-if (result.success) {
-  // 配网成功，返回配网成功的设备列表
-  const devices = result.data;
-  console.log('配网成功:', devices);
-} else {
-  // 配网失败
-  console.error('配网失败:', result.err);
-}
-```
-
-#### 参数说明
-
-| 参数             | 类型     | 必填 | 说明                             |
-| ---------------- | -------- | ---- | -------------------------------- |
-| ssid             | string   | 是   | WiFi 网络名称                    |
-| password         | string   | 是   | WiFi 网络密码                    |
-| mode             | number   | 是   | 配网模式：0-SoftAP, 3-BLE, 5-NFC |
-| timeout          | number   | 否   | 配网超时时间，单位秒，默认 60    |
-| productKey       | string   | 否   | 产品 Key                         |
-| isBind           | boolean  | 否   | 是否自动绑定设备，默认 true      |
-| softAPSSIDPrefix | string   | 否   | SoftAP 模式下的设备热点前缀      |
-| eventCallBack    | function | 否   | 配网过程事件回调                 |
-
-#### 配网模式说明
-
-1. **SoftAP 模式 (mode: 0)**
-
-   - 设备会创建一个 WiFi 热点
-   - 手机需要先连接到设备热点
-   - 适用于大多数 WiFi 设备
-
-2. **BLE 模式 (mode: 3)**
-
-   - 通过蓝牙传输配网信息
-   - 设备需要支持蓝牙功能
-   - 适用于支持蓝牙的 WiFi 设备
-
-3. **NFC 模式 (mode: 5)**
-   - 通过 NFC 传输配网信息
-   - 仅支持安卓设备
-   - 设备需要支持 NFC 功能
-
-#### 注意事项
-
-1. 配网前确保设备处于配网状态
-2. 确保 WiFi 密码正确
-3. 配网过程中不要切换网络或关闭蓝牙
-4. 如果配网超时，可以调用 `stopDeviceOnboardingDeploy` 停止配网
-5. 配网成功后，设备会自动连接到指定的 WiFi 网络
-
-#### 错误处理
-
-```typescript
-try {
-  const result = await sdk.setDeviceOnboardingDeploy({
-    ssid: 'wifi_ssid',
-    password: 'wifi_password',
-    mode: 3,
-  });
-
-  if (!result.success) {
-    // 处理配网失败
-    console.error('配网失败:', result.err);
-    return;
-  }
-
-  // 配网成功，可以开始使用设备
-  const devices = result.data;
-} catch (error) {
-  // 处理异常
-  console.error('配网异常:', error);
-}
-```
-
-### 停止配网
-
-取消当前正在进行的配网过程。
-
-```typescript
-sdk.stopDeviceOnboardingDeploy();
-```
-
-### 绑定设备
-
-绑定设备到机智云平台，绑定成功后才能进行设备控制和数据交互。
-
-```typescript
-const result = await sdk.bindRemoteDevice({
-  mac: 'device_mac', // 设备 MAC 地址
-  productKey: 'product_key', // 产品 Key
-  alias: 'device_name', // 可选，设备别名
-  beOwner: true, // 可选，是否作为设备所有者
-});
-
-if (result.success) {
-  // 绑定成功
-  const device = result.data;
-  console.log('设备绑定成功:', device);
-} else {
-  // 绑定失败
-  console.error('设备绑定失败:', result.err);
-}
-```
-
-#### 参数说明
-
-| 参数       | 类型    | 必填 | 说明                            |
-| ---------- | ------- | ---- | ------------------------------- |
-| mac        | string  | 是   | 设备的 MAC 地址                 |
-| productKey | string  | 是   | 产品 Key，用于标识设备类型      |
-| alias      | string  | 否   | 设备别名，用于自定义设备名称    |
-| beOwner    | boolean | 否   | 是否作为设备所有者，默认为 true |
-
-#### 注意事项
+#### 参数
+- services: 过滤services的条件，不传默认 ['ABF8', 'ABF0', 'F0AB', 'F8AB']
 
-1. 绑定前需要确保设备已经注册到机智云平台
-2. 绑定成功后，设备会自动添加到设备列表中
-3. 一个设备只能被一个用户绑定为所有者，但可以被多个用户共享
+### sdk.deviceSafetyRegister(Object object)
 
-#### 错误处理
+安全注册目标设备，否则无法发起设备绑定。返回值中可以拿到注册结果。
 
-```typescript
-try {
-  const result = await sdk.bindRemoteDevice({
-    mac: 'device_mac',
-    productKey: 'product_key',
-  });
+#### 参数
 
-  if (!result.success) {
-    // 处理绑定失败
-    console.error('绑定失败:', result.err);
-    return;
-  }
+- Object object
 
-  // 绑定成功，可以开始使用设备
-  const device = result.data;
-} catch (error) {
-  // 处理异常
-  console.error('绑定异常:', error);
-}
-```
+| 属性       | 类型   | 描述               |
+| ---------- | ------ | ------------------ |
+| mac        | string | 待注册设备 mac     |
+| productKey | string | 待注册设备所属产品 |
 
-### 解绑设备
+### sdk.bindRemoteDevice(Object object)
 
-```typescript
-sdk.unbindDevice({ devices: [{ mac: string, productKey: string }] });
-```
+绑定远程设备，否则无法发起设备订阅。返回值中可以拿到绑定结果。
 
 #### 参数
 
+- Object object
+
 | 属性       | 类型   | 描述               |
 | ---------- | ------ | ------------------ |
 | mac        | string | 待绑定设备 mac     |
 | productKey | string | 待绑定设备所属产品 |
 
-### 获取设备状态
+### sdk.subscribe(device:[IDevice](#IDevice) )
 
-查询目标设备当前状态，attrNames 不传则查询所有数据
+订阅目标设备，订阅成功后可控制设备。返回值中可以拿到订阅结果。
 
-```typescript
-sdk.getDeviceStatus(device:[IDevice], attrNames?: string[])
-```
-
-### 下发控制指令
+### sdk.write(device:[IDevice](#IDevice),cmd:{[key]:value})
 
 向目标设备发送指令。 其中`key`为数据点名称，value 为数据点的值。
 
-```typescript
-sdk.write(device:[IDevice])
-```
+### sdk.unSubscribe(device:[IDevice](#IDevice))
 
-## 事件监听
+取消订阅目标设备。蓝牙设备会断开连接。返回值中可拿到取消订阅结果。
 
-### 注册事件监听
+### sdk.addEventListener(type,listener)
 
-```typescript
-sdk.addEventListener(type, listener);
-```
+#### 概览
 
-| 事件种类 type                | 回调参数类型                            | 回调参数描述         |
-| ---------------------------- | --------------------------------------- | -------------------- |
-| GizDeviceListNotifications   | [IDevice[]](#IDevice)                   | 设备列表变更         |
-| GizDeviceStatusNotifications | [IDeviceStatusNoti](#IDeviceStatusNoti) | 设备在线状态变更     |
-| GizDeviceAttrsNotifications  | [IDeviceAttrsNoti](#IDeviceAttrsNoti)   | 设备数据点变更通知   |
-| onScanListChange             | [IDevice[]](#IDevice)                   | 扫描设备列表变更通知 |
-| onBleHandleError             | [IError](#IError)                       | ble 错误通知         |
+| 事件种类 type               | 回调参数类型                          | 回调参数描述         |
+| --------------------------- | ------------------------------------- | -------------------- |
+| onScanListChange            | [IDevice[]](#IDevice)                 | 扫描设备列表变更通知 |
+| GizDeviceAttrsNotifications | [IDeviceAttrsNoti](#IDeviceAttrsNoti) | 设备数据点变更通知   |
+| onBleHandleError            | [IError](#IError)                     | ble 错误通知         |
 
-#### GizDeviceListNotifications
-
-```ts
-this.gizSdk.addEventListener('GizDeviceListNotifications', (deviceList: IDevice[]) => {
-  console.log('列表发生变化', deviceList);
-});
-```
-
-#### GizDeviceStatusNotifications
-
-```ts
-this.gizSdk.addEventListener('GizDeviceStatusNotifications', (e: IDeviceStatusNoti) => {
-  console.log('设备在线状态变化', e);
-});
-```
-
-#### onScanListChange
-
-蓝牙扫描的设备回调
+- <a id="onScanListChange">onScanListChange</a>
 
 ```ts
 const initBle = () => {
@@ -592,7 +175,7 @@ initBle();
 scanBle();
 ```
 
-#### GizDeviceAttrsNotifications
+- <a id="GizDeviceAttrsNotifications">GizDeviceAttrsNotifications</a>
 
 监听设备上报数据。
 
@@ -605,9 +188,9 @@ this.gizSdk.addEventListener(
 );
 ```
 
-## 类型定义
+#### 类型定义
 
-### IDevice
+- <a id="IDevice">IDevice</a>
 
 ```ts
 interface IDevice {
@@ -620,47 +203,210 @@ interface IDevice {
   isOnline: boolean; // 代表大循环在线
   isLanOnline: boolean; // 代表小循环在线
   isBleOnline: boolean; // 代表蓝牙在线
-  bleWorkStatus?: number; // 蓝牙设备状态 0 默认状态 1 配网状态
-  connectType: TConnectType; // 当前连接类型
 }
 ```
 
-### TConnectType
+- <a id="IDeviceAttrsNoti">IDeviceAttrsNoti</a>
 
 ```ts
-type TConnectType = 'BLE' | 'BLE_BROADCAST' | 'LAN' | 'WAN' | 'NONE';
+interface IDeviceAttrsNoti {
+  device: IDevice;
+  data: object; // 设备上报数据点
 }
 ```
 
-### IDeviceAttrsNoti
+- <a id="IError">IError</a>
 
 ```ts
-interface IDeviceAttrsNoti {
-  device: IDevice;
-  data: object; // 设备上报数据点
+interface IError {
+  errorCode: number;
+  errorMessage?: string; // 错误信息
 }
 ```
 
-### IDeviceStatusNoti
+### sdk.removeEventListener(type:K,func:TListenerType[K])
 
-```ts
-interface IDeviceStatusNoti {
-  device: IDevice;
-  connectType: TConnectType;
+销毁事件监听。
+
+# 机智云小程序 wifi SDK
+
+## 使用方法
+
+```javascript
+import GizwitsSdk, { errorCode } from 'mini_program_gizwits_sdk';
+
+const sdk = new GizwitsSdk({
+  appID: '8f187b1deb9e44b6aa1374b8f13bccb1',
+  appSecret: 'd73fa6d6d7c04d37b6b2cc13a18a9f37',
+  specialProductKeys: ['00e7e327afa74a3d8ff1cc190bad78c0'],
+  specialProductKeySecrets: ['aa3d301fa291466fbed20e4204609abc'],
+  token: token,
+  uid: uid,
+  cloudServiceInfo: null,
+});
+
+try {
+  const data = await sdk.setDeviceOnboardingDeploy({
+    ssid: SSID,
+    password: password,
+    mode: 3, // 蓝牙配网
+    // mode:0 // softAp
+    timeout: 60,
+    softAPSSIDPrefix: 'XPG-GAgent-',
+  });
+} catch (error) {
+  console.log(error);
 }
 ```
 
-### TConnectType
+其中`data`代表配网成功的设备。
+
+如果失败的话会返回数据
+
+```javascript
+{
+  success: false,
+  err: {
+    errorCode: 'code',
+    errorMessage: 'message',
+  }
+}
+```
+
+```ts
+const errorCode: IErrorCode = {
+  GIZ_OPENAPI_DEVICE_NOT_BOUND: {
+    errorCode: 9017,
+    errorMessage: 'not bind',
+  },
+  GIZ_SDK_HTTP_REQUEST_FAILED: {
+    errorCode: 8099,
+    errorMessage: '网络请求失败',
+  },
+  GIZ_SDK_SDK_NOT_INITIALIZED: {
+    errorCode: 8300,
+    errorMessage: 'not init',
+  },
+  CONFIG_TIME_OUT: {
+    errorCode: 8023,
+    errorMessage: 'Config Timeout',
+  },
+  WECHAT_ERROR: {
+    errorCode: 10000,
+    errorMessage: 'wechat error',
+  },
+  GIZ_SDK_ONBOARDING_STOPPED: {
+    errorCode: 8318,
+    errorMessage: '配网中断',
+  },
+  GIZ_SDK_DEVICE_CONFIG_IS_RUNNING: {
+    errorCode: 8022,
+    errorMessage: '配置正在进行中',
+  },
+  GIZ_OPENAPI_TOKEN_INVALID: {
+    errorCode: 9004,
+    errorMessage: 'token 失效',
+  },
+  GIZ_SDK_BIND_DEVICE_FAILED: {
+    errorCode: 8039,
+    errorMessage: '设备绑定失败',
+  },
+  GIZ_SDK_BLE_BLUETOOTH_FUNCTION_NOT_TURNED_ON: {
+    errorCode: 8281,
+    errorMessage: '蓝牙未启用',
+  },
+  GIZ_SDK_OTHERWISE: {
+    errorCode: 8100,
+    errorMessage: '',
+  },
+  GIZ_SDK_DEVICE_NOT_SUBSCRIBED: {
+    errorCode: 8029,
+    errorMessage: '设备还未订阅',
+  },
+  GIZ_SDK_PRODUCTKEY_NOT_IN_SPECIFY: {
+    errorCode: 8250,
+    errorMessage: '产品类型不在指定范围内',
+  },
+};
+```
+
+### 探趣 BLE 配网
+
+SDK 将 `name` / `localName` 以“探趣”开头的设备映射到
+`188c3f02286f472b898f9fadc8058372`，仍需在 `productInfo` 中配置该产品。
+广播不含 MAC，扫描阶段以 `bleDeviceID` 区分设备，不生成虚假 MAC。
 
 ```ts
-type TConnectType = 'BLE' | 'BLE_BROADCAST' | 'LAN' | 'WAN' | 'NONE';
+// 先初始化蓝牙并扫描，从设备列表选择探趣设备。
+const deviceId = device.bleDeviceID;
+// 选择设备时不用连接，输入 Wi-Fi 后直接调用统一配网接口。
+const result = await sdk.setDeviceOnboardingDeploy({
+  mode: 11,
+  bleDeviceID: deviceId,
+  ssid: '家庭WiFi',
+  password: 'your-password', // 开放网络可传空字符串
+  timeout: 60,
+  isBind: false,
+  softAPSSIDPrefix: '',
+});
+// result.success 表示设备报告网络配置成功，不代表云端注册或绑定完成。
+// SDK 自动连接、进入配网、发送凭据、查询状态，并在结束后清理连接。
 ```
 
-- <a id="IError">IError</a>
+直接调用 mode 11 即可完成配网。SDK 缓存已发现设备的身份，实时扫描列表过期不会阻止已选设备连接。
+`prepareTqOnboarding()` 仍可选用来读取设备 Wi-Fi 列表，但不再是 demo 的前置步骤。
+取消使用 `stopDeviceOnboardingDeploy()`，会中断请求并断开当前配网连接。
+SDK 销毁会清理探趣连接、通知监听和未完成请求。
+
+探趣设备也可通过统一接口查询信息，无需先绑定或进入配网模式：
 
 ```ts
-interface IError {
-  errorCode: number;
-  errorMessage?: string; // 错误信息
+const result = await sdk.getDeviceInfo({ device });
+if (result.success) {
+  console.log(result.data.deviceID, result.data.deviceHardVersion, result.data.deviceSoftVersion);
 }
 ```
+
+SDK 使用 L2 `ver=1, fun=0x01, cmd=0x01`，请求数据为空。发送失败、响应超时或
+响应长度不为 29 字节时，改用 `ver=2` 重试；成功后使用回复中的 `ver` 作为当前
+会话后续命令的协议版本。独立查询结束会断开连接；已有配网会话会保持连接。
+
+|返回字段|协议来源|格式|
+|---|---|---|
+|`deviceTypeID`|Byte[0–3]|8 位十六进制字符串，保留字节顺序|
+|`deviceID`|Byte[4–20]|UTF-8 文本，去掉末尾 NUL；无法解码时保留十六进制原值|
+|`deviceHardVersion`|Byte[21–24]|8 位十六进制字符串，保留字节顺序|
+|`deviceSoftVersion`|Byte[25–28]|8 位十六进制字符串，保留字节顺序|
+|`protocolVersion`|L2 回复的 `ver`|数字|
+
+协议未说明版本编码，暂保留原始十六进制值。没有分别提供模组、MCU 和业务版本，
+因此 `moduleHardVersion`、`moduleSoftVersion`、`mcuHardVersion`、`mcuSoftVersion`
+和 `businessVersion` 均为空字符串。
+
+仅探趣设备支持设置设备 ID，接口参数中的 `deviceId` 是要写入设备的新 ID，
+蓝牙连接仍使用 `device.bleDeviceID`：
+
+```ts
+const result = await sdk.setDeviceId({ device, deviceId: 'TQ123456789012345' });
+// result.success 为 true 表示设备返回 status code 0。
+// 有效的设备回复会在 result.data.statusCode 中保留原始单字节状态码。
+```
+
+ID 必须是字符串，UTF-8 编码后恰好 17 字节；长度不符不会连接或发送命令，
+不会自动截断、补零或去除空格。中文等多字节字符按编码字节数计算。
+SDK 先通过查询设备信息确定当前会话的协议版本，再发送 `fun=0x01, cmd=0x10`。
+回复必须为 1 字节，状态码非 0 返回失败。独立调用结束清理连接，已有配网会话保持连接。
+
+服务 `18FF`，写入 `2B02`，通知 `2B01`。L0 每包最多 20 字节，CRC8
+多项式 `0x07`、初始值 `0`，校验 Data；L2 长度为大端。每包匹配序号
+等待 ACK，超时 2 秒，最多发送 3 次。该实现依据 tq_ble_tools，未添加加密。
+收到开始配网确认后等待 2 秒，每秒查询状态，最多 20 次，外层 timeout
+限制整个配网过程。云端绑定及其他设备控制功能不在此接口支持范围内。
+
+协议及模拟设备测试（需要安装 TypeScript）：
+
+```sh
+node tests/tq-protocol.cjs
+node tests/tq-session.cjs
+node tests/tq-device-info.cjs
+```