mini_program_gizwits_sdk 3.7.3-cozev5 → 3.7.3-gefeier

package/README.md

@@ -2,6 +2,7 @@
 
 # 机智云小程序 SDK
 
+
 ## ⚠️ 重要
 
 使用小程序 sdk 前，请在微信开发者后台-开发管理-开发设置-服务器域名添加以下请求地址。
@@ -11,7 +12,6 @@
 ```txt
 https://api.gizwits.com
 https://site.gizwits.com
-https://agent.gizwitsapi.com
 ```
 
 - socket 合法域名
@@ -21,16 +21,17 @@ wss://wxstage.gizwits.com
 wss://wxm2m.gizwits.com
 ```
 
-- 关于 services
+- 关于services
 
-为了搜索效率，sdk 会根据`services `过滤蓝牙设备。默认 ['ABF8', 'ABF0', 'F0AB', 'F8AB']。
+为了搜索效率，sdk会根据`services `过滤蓝牙设备。默认  ['ABF8', 'ABF0', 'F0AB', 'F8AB']。
 如果有特殊情况，不想用`services `过滤设备，可以
 
 ```js
-sdk.scanBleDevice(3000, []);
-sdk.startAutoScan([]);
+sdk.scanBleDevice(3000, [])
+sdk.startAutoScan([])
 ```
 
+
 ## 🔧 安装
 
 ```bash
@@ -71,6 +72,8 @@ export default class Index extends Component {
           productSecret: 'productSecret',
         },
       ],
+      uid: 'giz_uid', // 必填
+      token: 'giz_token', // 必填
     });
   }
 
@@ -81,474 +84,106 @@ 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: 令牌过期时间（仅微信登录返回）
-
-#### 注意事项
-
-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);
-}
-```
+## 📖 API
 
-## 蓝牙相关
+小程序相关 API。
 
-### 初始化蓝牙
+### 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);
-}
-```
-
-#### 参数说明
+#### 参数
+- services: 过滤services的条件，不传默认 ['ABF8', 'ABF0', 'F0AB', 'F8AB']
 
-| 参数       | 类型    | 必填 | 说明                            |
-| ---------- | ------- | ---- | ------------------------------- |
-| mac        | string  | 是   | 设备的 MAC 地址                 |
-| productKey | string  | 是   | 产品 Key，用于标识设备类型      |
-| alias      | string  | 否   | 设备别名，用于自定义设备名称    |
-| beOwner    | boolean | 否   | 是否作为设备所有者，默认为 true |
+### sdk.deviceSafetyRegister(Object object)
 
-#### 注意事项
+安全注册目标设备，蓝牙设备绑定前，需要调用这个接口，否则无法发起设备绑定。返回值中可以拿到注册结果。
 
-1. 绑定前需要确保设备已经注册到机智云平台
-2. 绑定成功后，设备会自动添加到设备列表中
-3. 一个设备只能被一个用户绑定为所有者，但可以被多个用户共享
+#### 参数
 
-#### 错误处理
+- Object object
 
-```typescript
-try {
-  const result = await sdk.bindRemoteDevice({
-    mac: 'device_mac',
-    productKey: 'product_key',
-  });
+| 属性       | 类型   | 描述               |
+| ---------- | ------ | ------------------ |
+| mac        | string | 待注册设备 mac     |
+| productKey | string | 待注册设备所属产品 |
 
-  if (!result.success) {
-    // 处理绑定失败
-    console.error('绑定失败:', result.err);
-    return;
-  }
+### sdk.bindRemoteDevice(Object object)
 
-  // 绑定成功，可以开始使用设备
-  const device = result.data;
-} catch (error) {
-  // 处理异常
-  console.error('绑定异常:', error);
-}
-```
+绑定远程设备，否则无法发起设备订阅。返回值中可以拿到绑定结果。
 
-### 解绑设备
+### sdk.unbindDevice({devices: [IDevice]})
 
-```typescript
-sdk.unbindDevice({ devices: [{ mac: string, productKey: string }] });
-```
+解绑设备
 
 #### 参数
 
+- Object object
+
 | 属性       | 类型   | 描述               |
 | ---------- | ------ | ------------------ |
 | mac        | string | 待绑定设备 mac     |
 | productKey | string | 待绑定设备所属产品 |
 
-### 获取设备状态
+### sdk.subscribe(device:[IDevice](#IDevice),connectType:[TConnectType](#TConnectType))
 
-查询目标设备当前状态，attrNames 不传则查询所有数据
+订阅目标设备，订阅成功后可控制设备。返回值中可以拿到订阅结果。
 
-```typescript
-sdk.getDeviceStatus(device:[IDevice], attrNames?: string[])
-```
+### sdk.getDeviceStatus(device:[IDevice](#IDevice), attrNames?: string[])
 
-### 下发控制指令
+查询目标设备当前状态，attrNames 不传则查询所有数据
+
+### sdk.write(device:[IDevice](#IDevice),cmd:{[key]:value})
 
 向目标设备发送指令。 其中`key`为数据点名称，value 为数据点的值。
 
-```typescript
-sdk.write(device:[IDevice])
+### sdk.unSubscribe(device:[IDevice](#IDevice))
+
+取消订阅目标设备。蓝牙设备会断开连接。返回值中可拿到取消订阅结果。
+
+### sdk.getDevices()
+刷新设备列表(同时也会在 GizDeviceListNotifications 事件里推送)
+```ts
+const data = await sdk.getDevices()
+console.log(data)
 ```
 
-## 事件监听
+### sdk.stopDeviceOnboardingDeploy
+停止配网
 
-### 注册事件监听
+### sdk.setDeviceOnboardingDeploy
+开始配网
 
-```typescript
-sdk.addEventListener(type, listener);
-```
+详细参数请查阅类型定义
+
+### sdk.addEventListener(type,listener)
+
+#### 概览
 
-| 事件种类 type                | 回调参数类型                            | 回调参数描述         |
-| ---------------------------- | --------------------------------------- | -------------------- |
-| GizDeviceListNotifications   | [IDevice[]](#IDevice)                   | 设备列表变更         |
-| GizDeviceStatusNotifications | [IDeviceStatusNoti](#IDeviceStatusNoti) | 设备在线状态变更     |
-| GizDeviceAttrsNotifications  | [IDeviceAttrsNoti](#IDeviceAttrsNoti)   | 设备数据点变更通知   |
-| onScanListChange             | [IDevice[]](#IDevice)                   | 扫描设备列表变更通知 |
-| onBleHandleError             | [IError](#IError)                       | ble 错误通知         |
+| 事件种类 type               | 回调参数类型                          | 回调参数描述         |
+| --------------------------- | ------------------------------------- | -------------------- |
+| GizDeviceListNotifications | [IDevice[]](#IDevice) | 设备列表变更   |
+| GizDeviceStatusNotifications | [IDeviceStatusNoti](#IDeviceStatusNoti) | 设备在线状态变更   |
+| GizDeviceAttrsNotifications | [IDeviceAttrsNoti](#IDeviceAttrsNoti) | 设备数据点变更通知   |
+| onScanListChange            | [IDevice[]](#IDevice)                 | 扫描设备列表变更通知 |
+| onBleHandleError            | [IError](#IError)                     | ble 错误通知         |
 
-#### GizDeviceListNotifications
+- <a id="GizDeviceListNotifications"> GizDeviceListNotifications </a>
 
 ```ts
 this.gizSdk.addEventListener('GizDeviceListNotifications', (deviceList: IDevice[]) => {
@@ -556,7 +191,7 @@ this.gizSdk.addEventListener('GizDeviceListNotifications', (deviceList: IDevice[
 });
 ```
 
-#### GizDeviceStatusNotifications
+- <a id="GizDeviceStatusNotifications"> GizDeviceStatusNotifications </a>
 
 ```ts
 this.gizSdk.addEventListener('GizDeviceStatusNotifications', (e: IDeviceStatusNoti) => {
@@ -564,9 +199,7 @@ this.gizSdk.addEventListener('GizDeviceStatusNotifications', (e: IDeviceStatusNo
 });
 ```
 
-#### onScanListChange
-
-蓝牙扫描的设备回调
+- <a id="onScanListChange">onScanListChange</a>
 
 ```ts
 const initBle = () => {
@@ -587,7 +220,7 @@ initBle();
 scanBle();
 ```
 
-#### GizDeviceAttrsNotifications
+- <a id="GizDeviceAttrsNotifications">GizDeviceAttrsNotifications</a>
 
 监听设备上报数据。
 
@@ -600,9 +233,9 @@ this.gizSdk.addEventListener(
 );
 ```
 
-## 类型定义
+#### 类型定义
 
-### IDevice
+- <a id="IDevice">IDevice</a>
 
 ```ts
 interface IDevice {
@@ -620,14 +253,14 @@ interface IDevice {
 }
 ```
 
-### TConnectType
+- <a id="TConnectType">TConnectType</a>
 
 ```ts
 type TConnectType = 'BLE' | 'BLE_BROADCAST' | 'LAN' | 'WAN' | 'NONE';
 }
 ```
 
-### IDeviceAttrsNoti
+- <a id="IDeviceAttrsNoti">IDeviceAttrsNoti</a>
 
 ```ts
 interface IDeviceAttrsNoti {
@@ -636,7 +269,7 @@ interface IDeviceAttrsNoti {
 }
 ```
 
-### IDeviceStatusNoti
+- <a id="IDeviceStatusNoti">IDeviceStatusNoti</a>
 
 ```ts
 interface IDeviceStatusNoti {
@@ -645,7 +278,7 @@ interface IDeviceStatusNoti {
 }
 ```
 
-### TConnectType
+- <a id="TConnectType">TConnectType</a>
 
 ```ts
 type TConnectType = 'BLE' | 'BLE_BROADCAST' | 'LAN' | 'WAN' | 'NONE';
@@ -659,3 +292,111 @@ interface IError {
   errorMessage?: string; // 错误信息
 }
 ```
+
+### sdk.removeEventListener(type:K,func:TListenerType[K])
+
+销毁事件监听。
+
+# 配网相关
+
+## 使用方法
+
+```javascript
+import GizwitsSdk, { errorCode } from 'mini_program_gizwits_sdk';
+
+const configData = {
+  appID: "xxx",
+  appSecret: "xxx",
+  productInfo: [
+    {
+      productKey: "xxx",
+      productSecret: "xxx",
+    },
+  ],
+};
+const sdk = new GizwitsSdk(configData);
+
+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);
+}
+```
+
+其中`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: '产品类型不在指定范围内',
+  },
+};
+```