API 与版本说明

适用版本：1.4.12。

SDK 管理

接口	返回值 / 用途
`GizSDKManager.getConfiguration()`	`GizConfiguration`，读取当前配置
`GizSDKManager.isRegistered()`	`Boolean`，检查初始化状态
`GizSDKManager.deregister()`	`Unit`，注销并释放 SDK 资源
`GizSDKManager.setDebug(debug)`	`Unit`，设置调试日志
`GizSDKManager.getRegisteredDevice(id)`	`GizDevice?`，按 SDK 设备 ID 查找
`GizSDKManager.getProductDataPointConfig(productKey)`	挂起函数，返回 `String?`；失败时可为 `null`
`GizSDKManager.cleanCache()`	挂起函数，返回 `Result<Unit>`；离线产品配置缓存也会清理

设备列表与扫描

以下接口是扩展函数，需要导入对应模块。

import com.gizwits.smart.sdk.GizSDKManager
import com.gizwits.smart.sdk.mqtt.queryBoundDevices
import com.gizwits.smart.sdk.mqtt.refreshBoundDeviceList
import com.gizwits.smart.sdk.bluetooth.subscribeBleScanError
 
// 在协程中获取最新绑定列表；请求失败时回退到缓存，无有效登录会话时返回空列表。
val boundDevices = GizSDKManager.queryBoundDevices()
// 触发异步刷新，通过 subscribeBoundDeviceList() 接收结果。
GizSDKManager.refreshBoundDeviceList()

subscribeBleScanError() 返回 Flow<GizConnectException>。详细订阅方式见事件监听。

能力、设备与用户

bleCapability、lanCapability、mqttCapability 分别来自 com.gizwits.smart.sdk.bluetooth、.lan、.mqtt 下的 Kotlin 扩展属性。公共能力实现 BaseCapability。

接口	说明
`capability.connectAsync()`	无挂起返回值；使用状态流观察连接
`capability.getStatus()` / `subscribeStatus()`	`CapacityStatus` 枚举，不能直接与整数比较
`capability.getIsLogin()` / `subscribeIsLogin()`	握手状态
`capability.getDp(dps)`	`dps` 为必传的 `JsonArray?`；返回 `Result<JsonObject>`
`device.subscribeProductName()` / `subscribeDeviceId()`	产品名 / 云端 DID 的 `StateFlow`
`device.subscribeDataPointConfig()` / `subscribeDevicePasscode()` / `subscribeBoundState()`	数据点配置、设备口令与绑定状态
`device.startMusicalRhythm(sensitivity, mode, callback)`	挂起函数，返回 `Result<Unit>`；需具备录音权限和设备能力
`device.stopMusicalRhythm()`	返回 `Result<Unit>`
`userManager.subscribeUserState()` / `getUserTokenStream()`	登录状态和授权信息流
`userManager.bindDevice(mac, productKey, devAlias, remark)`	不依赖设备对象的绑定入口，返回 `Result<Unit>`
`userManager.bindDeviceWithPasscode(deviceId, passcode)`	DID + passcode 绑定，返回 `Result<Unit>`
`userManager.unbindDevice(deviceId)` / `updateDeviceInfo(did, devAlias, remark)`	按云端 DID 解绑或修改信息

其中 userManager = GizSDKManager.getUserManager()。挂起函数需在协程中调用，使用 result.isSuccess、onSuccess 或 onFailure 处理结果。

配网与模组信息

BLE 配网和 AP 配网的 timeout 单位为秒，bindWithUid 必须显式传入。
AI 模组自行与云端建立绑定关系时，必须开启 bindWithUid，并预先完成用户授权。
ProductInfoStruct.cmbDeviceTypeId 用于移动爱家 CMB 模组识别。
GizBleModuleProfile 增加 bleModuleVariant、support5GConfig；SDK 根据广播自动选择协议，不能假定所有模组都支持 5 GHz 配网。
AirLink 入口为 GizESPTouchSmartConfig.provideWiFiCredentialsWithAirLink(context, ssid, password, timeout, productKeys, processHandler)，返回 Result<DeviceRegistrationInfo?>；timeout 也是秒，productKeys 用于云端确认筛选。取消使用 stopProvideWiFiCredentialsWithAirLink()。该 API 位于 com.gizwits.smart.sdk.esptouch，不接收 bindWithUid。

初始化事件监听