API 文档

API 文档

基本概念

设备对象

根据通讯方式来区分，模组有以下几种通讯方式

• 蓝牙
• 局域网
• mqtt

对应的，在 SDK，设备就衍生出了三种能力

• bleCapability
• lanCapability
• mqttCapability

这三个能力都继承于 BaseCapability，都实现了控制、连接等功能。在开发的过程中您可以自由的选择连接某个通道，对某个通道下发指令。

// ble
await device.bleCapability.connect()
device.bleCapability.getDp()

// mqtt
await device.mqttCapability.connect()
device.mqttCapability.getDp()

BLE Wi-Fi 列表和时间同步（2.1.0-beta）

Android / iOS / HarmonyOS 可以从设备的 BLE 能力获取附近 Wi-Fi，或用手机当前时间独立校准设备时间：

const networks = await device.bleCapability.getWiFiList(30)
// 成功数据为 GizWiFiNetwork[]：{ ssid: string, signalStrength: number }
// signalStrength 是有符号的 dBm，SSID 可以重复，列表也可以为空。

const result = await device.bleCapability.syncTime(30)

// 取消对应设备的当前请求
await device.bleCapability.cancelGetWiFiList()
await device.bleCapability.cancelSyncTime()

四个接口均返回 Promise<GizResult<...>>，沿用 SDK 的成功和失败结果格式。 超时参数单位为秒，默认 30，范围为大于 0 且不超过 3600，可传小数。 同一设备同类操作同时只允许一个请求；取消会让原请求以 E_BLE_REQUEST_CANCELLED 结束；请求按设备与操作分别管理。

需要设备固件支持对应协议：Wi-Fi 列表支持 V2 / V5；独立时间同步支持 V5， V2 需要固件支持离线时间同步扩展。V5 时间同步成功表示数据已通过 GATT 写入， 协议没有额外的设备确认响应。安全通道由原生 SDK 按设备能力自动协商， 业务层无需显式启用 ECDH/AES-GCM。历史配网日志主动拉取已废弃，不提供接口。

HarmonyOS 同一设备的 Wi-Fi 列表和时间同步共用 BLE 会话，需要依次调用； 请求尚未完成时启动另一操作会返回 E_BLE_REQUEST_BUSY。 设备的 bleCapability.profile.support5GConfig（别名 supports5GConfig）和 supportsSecureChannel 表示其广播中的能力，实际使用仍需固件支持。 当前版本依赖 Android SDK 1.4.20、iOS SDK ~> 2.1.18、HarmonyOS SDK 1.1.3 系列。

连接的云服务

初始化 sdk 的时候，您可以手动选择连接的云

• api.gizwits.com 大陆
• euapi.gizwits.com 欧洲地区
• usapi.gizwits.com 美东地区

import RNGizSDKManagerModule from 'react-native-gizwits-sdk-v5'
let data = await RNGizSDKManagerModule.initSDK({
  appID: 'xxx',
  appSecret: 'xxx',
  productInfos: [
    {
      productKey: 'xxx',
      productSecret: 'xxx',
    },
  ],
  serverInfo: {
    openAPIInfo: 'api.gizwits.com',
  },
})

如果不填写，将会按照客户端所在的地区自动选择

HarmonyOS 支持

从本版本开始，Android、iOS 与 HarmonyOS 共用同一个 npm 包：

npm install react-native-gizwits-sdk-v5

HarmonyOS 入口由 Metro 自动解析为 index.harmony.js，Android/iOS 仍使用原有 index.js，无需在业务代码中按平台切换 import。HarmonyOS 当前以 React Native 0.82.1、RNOH 0.82.30 为基线，并通过 ArkTS TurboModule、Codegen 和 RNOH Autolinking 接入。

应用侧始终使用原有导入和 API，不需要增加 Platform.OS 分支：

import RNGizSDKManagerModule, {
  RNGizDeviceManagerModule,
  RNGizUserManagerModule,
} from 'react-native-gizwits-sdk-v5'

• 原有 Android/iOS App 不会加载 HarmonyOS 入口、HAR 或 OHPM 依赖，原生接入方式不变。
• 标准 RNOH App 安装同一个 npm 包后，只需执行原有 HarmonyOS 应用构建；Autolinking 会安装包内 HAR 并注册三个 TurboModule，业务 TS/JS 代码无需修改。
• 鸿蒙 TurboModule 同时保留 Android/iOS 已有的 options + callback NativeModules ABI； 已有业务若直接调用 NativeModules.RNGiz*ManagerModule，也无需改成 Promise 或 JSON 字符串参数。
• npm run build:harmony 只供本 SDK 的发布维护者在 npm 发布前生成桥接 HAR，应用开发者 不需要再次构建该 HAR。

HarmonyOS 能力边界

| 功能 | BLE | LAN | MQTT | | ---------------------------------------- | --------- | ------ | ------ | | 连接、断开、收发数据、设备信息、检查升级 | 支持 | 支持 | 支持 | | Wi-Fi 配网及停止配网 | BLE V2/V5 | 支持 | 不支持 | | 启动 OTA 升级 | 支持 | 不支持 | 不支持 | | 取消 OTA 升级 | 支持 | 不支持 | 不支持 | | Wi-Fi 列表、独立时间同步及取消 | BLE V2/V5 | 不支持 | 不支持 |

HarmonyOS 权限

宿主应用按实际使用能力声明网络、网络/Wi-Fi 信息、蓝牙和近似位置权限：

{
  requestPermissions: [
    { name: 'ohos.permission.INTERNET' },
    { name: 'ohos.permission.GET_NETWORK_INFO' },
    { name: 'ohos.permission.GET_WIFI_INFO' },
    { name: 'ohos.permission.ACCESS_BLUETOOTH' },
    { name: 'ohos.permission.APPROXIMATELY_LOCATION' },
  ],
}

更新日志

BLE/LAN 配网的最后一个可选参数 bindWithUid 默认为 false。传入 true 时需要先登录，并通过绑定列表中匹配且在线的设备确认配网成功；BLE V5 同时向支持的固件附带当前用户 UID。V2 和 LAN 仍需固件或业务流程先完成用户关联。

await device.bleCapability.provideWiFiCredentials(
  ssid, password, 60, onProvisionEvent, true
)

2.1.9

• iOS SDK 升级至 ~> 2.1.15，HarmonyOS 桥接 HAR 配套原生 SDK 1.0.8，Android SDK 继续使用 1.4.17。
• 修复 iOS LAN 透传上报及 HarmonyOS MQTT 数据上报可能乱序的问题。
• iOS 透传接收日志改为汇总输出，减少连续数据上报时的日志开销。

2.1.8-beta

• Android SDK 升级至 1.4.17，iOS SDK 升级至 ~> 2.1.14，HarmonyOS 桥接包配套原生 SDK 1.0.7。
• HarmonyOS 的 BLE/LAN 配网支持现有可选参数 bindWithUid；启用后通过在线绑定设备确认配网成功，BLE V5 同时附带当前用户 UID。
• Android/iOS 的 LAN 配网也会传递该参数；默认值保持 false，既有调用兼容。
• 改善 BLE 透传连续上报、LAN 数据接收、心跳与断连状态。

2.1.3-beta

• HarmonyOS 原生 SDK 升级至 1.0.6，同步更新 core、Bluetooth、LAN 和 MQTT 四个 HAR。

2.1.2-beta

• iOS SDK 升级至 ~> 2.1.10，使用包含真机 arm64 和模拟器 arm64 / x86_64 的 XCFramework。
• 可在 Apple Silicon 的 iPhone 模拟器运行；BLE 和设备配网仍需真机验证。
• 更新后运行 pod update GizwitsiOSSDK，并移除应用中为旧 SDK 设置的模拟器 arm64 排除项。
• Android SDK 升级至 1.4.15，修复 V5 配网元数据重复追加，改善纯文本反馈上传和 HTTP 错误处理。
• HarmonyOS HAR 内置的四个原生 SDK 模块同步至 1.0.5 基础版本；桥接 API 保持不变。

2.1.1-beta

• HarmonyOS 接入 Wi-Fi 列表、独立时间同步和对应取消接口，补齐 5 GHz 与安全通道能力标记。
• 内置四个本地原生 SDK HAR，不依赖尚未发布的 OHPM 版本；补充超时、取消和桥接销毁测试。

2.1.0-beta

• 增加 BLE Wi-Fi 列表、独立时间同步及对应取消接口；补齐 TypeScript 类型和设备事件对象上的方法。
• Android SDK 升级至 1.4.14，iOS SDK 升级至 2.1.9；修复 Android 发布包 Kotlin 顶层扩展索引缺失问题。
• Android/iOS 支持新增接口；HarmonyOS 支持在 2.1.1-beta 补齐。

2.0.0-beta

新增 HarmonyOS/RNOH 支持

1.4.31

修正 ios 修改名称无效