# 涂鸦智能 Android SDK 对接分析 ## 一、SDK 版本信息 | 项目 | 版本/内容 | |------|-----------| | SDK版本 | **ThingSmart Home SDK v7.5.1** (本地文件7.5.0, Maven最新7.5.1) | | Maven坐标 | `com.thingclips.smart:thingsmart:6.11.1` → 建议升级到 `7.5.1` | | 安全组件 | `security-algorithm-1.0.0-beta.aar` | | 最低Android版本 | Android 6.0 (API 23) | | 目标SDK | Android 14 (API 35) | | 构建要求 | 必须使用 AndroidX | | 支持ABI | armeabi-v7a, arm64-v8a | --- ## 二、SDK 核心能力分析 ### 2.1 功能模块清单(来自 module_app.json) | 模块 | 功能 | 对接优先级 | |------|------|-----------| | **家庭管理** | 家庭创建/切换/设置/成员管理/房间管理 | ⭐⭐⭐ 必须 | | **设备配网** | Wi-Fi配网/蓝牙配网/Mesh配网/Matter配网/Zigbee配网 | ⭐⭐⭐ 必须 | | **设备控制** | 设备面板/数据点控制/状态查询/指令下发 | ⭐⭐⭐ 必须 | | **设备详情** | 设备信息/网络信息/固件升级/设备移除 | ⭐⭐⭐ 必须 | | **场景智能** | 场景创建/编辑/执行/自动化/条件触发 | ⭐⭐ 重要 | | **消息中心** | 告警消息/设备消息/推送设置 | ⭐⭐ 重要 | | **设备分享** | 设备分享/群组分享/分享链接 | ⭐⭐ 重要 | | **群组管理** | 群组创建/编辑/WiFi群组/BLE群组/Mesh群组 | ⭐ 一般 | | **摄像头/IPC** | 实时视频/回放/云存储/门铃/对讲 | ⭐⭐ 重要 | | **定时任务** | 定时器/倒计时/闹钟 | ⭐⭐ 重要 | | **Matter设备** | Matter设备发现/配网/控制 | ⭐⭐⭐ 必须 | | **蓝牙Mesh** | Mesh网络/蓝牙设备管理 | ⭐ 一般 | | **OTA升级** | 固件升级/批量升级 | ⭐ 一般 | | **地图/地理围栏** | 位置设置/地理围栏 | ⭐ 一般 | | **社交账号** | Google/Amazon/WeChat绑定 | ⭐ 一般 | | **小程序** | MiniApp运行/调试 | ⭐ 一般 | ### 2.2 核心 API 清单 ```java // ===== 初始化 ===== ThingHomeSdk.init(application); // SDK初始化 ThingHomeSdk.setDebugMode(true); // 调试模式 ThingHomeSdk.onDestroy(); // 销毁连接 // ===== 用户管理 ===== ThingHomeSdk.getUserInstance(); // 用户实例 .loginWithPhonePassword() // 手机号登录 .loginWithEmail() // 邮箱登录 .registerAccountWithPhone() // 手机号注册 .registerAccountWithEmail() // 邮箱注册 .sendVerifyCodeWithUserName() // 发送验证码 .resetPasswordWithPhone() // 重置密码 .logout() // 退出登录 // ===== 家庭管理 ===== ThingHomeSdk.getHomeManagerInstance(); // 家庭管理实例 .createHome() // 创建家庭 .queryHomeList() // 查询家庭列表 .getHomeDetail() // 获取家庭详情 .updateHome() // 更新家庭 .dismissHome() // 解散家庭 .addRoom() // 添加房间 .updateRoom() // 更新房间 .removeRoom() // 删除房间 // ===== 设备配网 ===== ThingHomeSdk.getActivatorInstance(); // 配网实例 .newTuyaActivator() // Wi-Fi配网 .newTuyaSmartActivator() // 快连配网 .newTuyaQrActivator() // 二维码配网 .newTuyaBLEActivator() // 蓝牙配网 .newTuyaMeshActivator() // Mesh配网 .newTuyaMatterActivator() // Matter配网 // ===== 设备控制 ===== ThingHomeSdk.getDataInstance(); // 数据实例 .getDeviceBean() // 获取设备信息 .getDeviceStat() // 获取设备状态 .publishDps() // 下发控制指令 IThingDevice mDevice = ThingHomeSdk.newDeviceInstance(devId); mDevice.registerDeviceListener(); // 注册设备监听 mDevice.publishDps(); // 下发数据点 mDevice.unRegisterDeviceListener(); // 取消监听 // ===== 场景智能 ===== ThingHomeSdk.getSceneManagerInstance(); // 场景管理实例 .createScene() // 创建场景 .getSceneList() // 获取场景列表 .executeScene() // 执行场景 .modifyScene() // 修改场景 .deleteScene() // 删除场景 // ===== 设备详情 ===== ThingHomeSdk.getDeviceDetailInstance(); // 设备详情实例 .getDeviceDetail() // 获取设备详情 .removeDevice() // 移除设备 .renameDevice() // 重命名设备 .checkFirmwareUpgrade() // 检查固件升级 // ===== 群组管理 ===== ThingHomeSdk.getGroupManagerInstance(); // 群组管理实例 .createGroup() // 创建群组 .renameGroup() // 重命名群组 .dismissGroup() // 解散群组 ``` --- ## 三、与物联网平台的对接架构 ### 3.1 整体架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 移动端 APP (Android) │ │ ┌─────────────────────┐ ┌──────────────────────────────────┐ │ │ │ 涂鸦 Home SDK │ │ 你的 IoT 平台 SDK (自研) │ │ │ │ - 设备配网 │ │ - 规则引擎 │ │ │ │ - 设备控制 │ │ - 告警通知 │ │ │ │ - 家庭管理 │ │ - 数据分析 │ │ │ │ - 场景联动 │ │ - 权限管理 │ │ │ │ - Matter支持 │ │ - 多租户 │ │ │ └─────────┬───────────┘ └──────────┬───────────────────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ 统一数据桥接层 (Bridge Layer) │ │ │ │ - 设备数据同步 - 状态映射 - 事件转发 - 指令桥接 │ │ │ └─────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ │ ▼ ▼ ┌──────────────────────┐ ┌──────────────────────────────┐ │ 涂鸦云平台 │ │ 你的 IoT 后端服务 │ │ - 设备管理 │ │ - iot-device (设备管理) │ │ - 数据存储 │ │ - iot-data (数据采集) │ │ - 场景执行 │ │ - iot-rule (规则引擎) │ │ - OTA升级 │ │ - iot-alarm (告警服务) │ └──────────────────────┘ └──────────────────────────────┘ ``` ### 3.2 两种对接模式 #### 模式A:SDK直连模式(推荐,简单快速) ``` APP → 涂鸦SDK → 涂鸦云 → 设备 APP → IoT平台API → 你的后端 → 自有设备 ``` **适用场景**:涂鸦设备由涂鸦SDK直接管理,自有设备走你的IoT平台 #### 模式B:后端桥接模式(统一管理) ``` APP → 涂鸦SDK → 涂鸦云 → 设备 ↓ 数据同步 APP → IoT平台API → 你的后端 → 统一数据/告警/规则 ``` **适用场景**:需要统一的数据分析、告警、规则引擎 **推荐:先采用模式A快速上线,后续逐步迁移到模式B** --- ## 四、详细对接步骤 ### Step 1: 涂鸦平台准备(1天) 1. **登录涂鸦IoT平台** → https://iot.tuya.com 2. **创建智能App** → 获取 AppKey 和 AppSecret 3. **配置Android应用信息**: - 包名(必须与APP包名一致) - SHA256证书指纹 - 下载 security-algorithm.aar 4. **创建产品** → 定义设备功能(DP点) 5. **获取面板ID** → 用于设备控制面板渲染 ### Step 2: Android项目集成(2天) #### 2.1 创建Android项目 ```groovy // app/build.gradle android { defaultConfig { applicationId "com.yourcompany.iotsaas" // 必须与涂鸦平台一致 minSdkVersion 23 targetSdkVersion 35 ndk { abiFilters "armeabi-v7a", "arm64-v8a" } } packagingOptions { pickFirst 'lib/*/libc++_shared.so' } } dependencies { // 涂鸦核心SDK implementation 'com.alibaba:fastjson:1.1.67.android' implementation 'com.squareup.okhttp3:okhttp-urlconnection:3.14.9' implementation 'com.thingclips.smart:thingsmart:7.5.1' // 安全组件 implementation fileTree(include: ['*.aar'], dir: 'libs') // 你的IoT平台SDK implementation 'com.squareup.retrofit2:retrofit:2.9.0' implementation 'com.squareup.retrofit2:converter-gson:2.9.0' } ``` #### 2.2 根目录 build.gradle 配置Maven仓库 ```groovy allprojects { repositories { maven { url 'https://maven-other.tuya.com/repository/maven-releases/' } maven { url 'https://maven-other.tuya.com/repository/maven-commercial-releases/' } google() mavenCentral() } } ``` #### 2.3 AndroidManifest.xml 配置 ```xml ``` #### 2.4 混淆配置 ```proguard # fastJson -keep class com.alibaba.fastjson.**{*;} -dontwarn com.alibaba.fastjson.** # OkHttp3 -keep class okhttp3.** { *; } -dontwarn okhttp3.** # Tuya SDK -keep class com.thingclips.**{*;} -dontwarn com.thingclips.** ``` ### Step 3: SDK初始化与用户体系(2天) ```kotlin // IotApplication.kt class IotApplication : Application() { override fun onCreate() { super.onCreate() // 1. 初始化涂鸦SDK ThingHomeSdk.init(this) ThingHomeSdk.setDebugMode(BuildConfig.DEBUG) // 2. 初始化你的IoT平台SDK IoTPlatformSdk.init( baseUrl = "https://your-iot-api.com", apiKey = "your-api-key" ) } } ``` #### 用户登录流程 ``` ┌─────────────┐ ┌───────────────┐ ┌──────────────┐ │ 用户输入 │───→│ 你的认证服务 │───→│ 涂鸦用户系统 │ │ 手机号/邮箱 │ │ JWT Token生成 │ │ UID获取 │ └─────────────┘ └───────────────┘ └──────────────┘ │ │ ▼ ▼ ┌──────────────────────────────────┐ │ APP 本地存储 │ │ - IoT Platform Token │ │ - Tuya Session │ └──────────────────────────────────┘ ``` ```kotlin // 登录管理器 - 双平台登录 class LoginManager { // 涂鸦登录 fun loginWithPhone(countryCode: String, phone: String, password: String, callback: IResultCallback) { ThingHomeSdk.getUserInstance().loginWithPhonePassword( countryCode, phone, password, object : ILoginCallback { override fun onSuccess(user: User) { // 涂鸦登录成功,获取uid val tuyaUid = user.uid // 同步到你的IoT平台 syncToIoTPlatform(tuyaUid, phone, callback) } override fun onError(code: String, error: String) { callback.onError(code, error) } } ) } // 同步到IoT平台 private fun syncToIoTPlatform(tuyaUid: String, phone: String, callback: IResultCallback) { // 调用你的后端API,关联涂鸦账号 IoTPlatformApi.login(tuyaUid, phone, object : ApiCallback { override fun onSuccess(token: String) { // 保存双平台token TokenManager.saveIoTToken(token) callback.onSuccess() } override fun onError(code: String, msg: String) { callback.onError(code, msg) } }) } } ``` ### Step 4: 家庭与设备管理(3天) ```kotlin // 家庭管理 - 统一管理涂鸦家庭和你的平台家庭 class HomeManager { // 获取家庭列表(涂鸦) fun getHomeList(callback: (List) -> Unit) { ThingHomeSdk.getHomeManagerInstance() .queryHomeList(object : IThingHomeResultCallback { override fun onSuccess(homeBeans: MutableList?) { callback(homeBeans ?: emptyList()) } override fun onError(errorCode: String?, error: String?) { callback(emptyList()) } }) } // 创建家庭(涂鸦) fun createHome(name: String, rooms: List, callback: (Boolean) -> Unit) { val map = HashMap() map["name"] = name map["rooms"] = rooms map["lon"] = 0.0 map["lat"] = 0.0 ThingHomeSdk.getHomeManagerInstance() .createHome(map, object : IResultCallback { override fun onSuccess() { // 同步到IoT平台 syncHomeToPlatform(name, callback) } override fun onError(errorCode: String?, error: String?) { callback(false) } }) } } // 设备管理 class DeviceManager { // 获取家庭下的设备列表 fun getDeviceList(homeId: Long, callback: (List) -> Unit) { val homeDetail = ThingHomeSdk.getDataInstance().getHomeBean(homeId) callback(homeDetail?.deviceList ?: emptyList()) } // 设备控制 - 下发数据点 fun publishDps(devId: String, dps: Map, callback: (Boolean) -> Unit) { val device = ThingHomeSdk.newDeviceInstance(devId) device.publishDps(JSONObject(dps), object : IResultCallback { override fun onSuccess() { // 同步状态到IoT平台 syncDeviceState(devId, dps, callback) } override fun onError(errorCode: String?, error: String?) { callback(false) } }) } // 监听设备状态变化 fun registerDeviceListener(devId: String, listener: IDeviceListener) { val device = ThingHomeSdk.newDeviceInstance(devId) device.registerDeviceListener(listener) } } ``` ### Step 5: 设备配网(3天) ```kotlin // 配网管理器 - 支持多种配网方式 class ActivatorManager { // Wi-Fi EZ配网(快连) fun startEZActivator(ssid: String, password: String, homeId: Long, callback: (Boolean) -> Unit) { val activator = ThingHomeSdk.getActivatorInstance() .newTuyaActivator(ActivatorBuilder() .setSsid(ssid) .setPassword(password) .setHomeId(homeId) .setContext(context) .setActivatorModel(ActivatorModelEnum.TY_EZ) .setTimeOut(100) .setListener(object : ITuyaSmartActivatorListener { override fun onError(errorCode: String?, errorMsg: String?) { callback(false) } override fun onActiveSuccess(devId: String?) { // 配网成功,同步到IoT平台 syncNewDevice(devId!!, callback) } override fun onStep(step: String?, data: Any?) {} }) ) activator.start() } // Wi-Fi AP配网(热点) fun startAPActivator(ssid: String, password: String, homeId: Long, callback: (Boolean) -> Unit) { val activator = ThingHomeSdk.getActivatorInstance() .newTuyaActivator(ActivatorBuilder() .setSsid(ssid) .setPassword(password) .setHomeId(homeId) .setContext(context) .setActivatorModel(ActivatorModelEnum.TY_AP) .setTimeOut(100) .setListener(object : ITuyaSmartActivatorListener { override fun onError(errorCode: String?, errorMsg: String?) { callback(false) } override fun onActiveSuccess(devId: String?) { syncNewDevice(devId!!, callback) } override fun onStep(step: String?, data: Any?) {} }) ) activator.start() } // 蓝牙配网 fun startBLEActivator(homeId: Long, callback: (Boolean) -> Unit) { // BLE配网逻辑 } // Matter配网 fun startMatterActivator(homeId: Long, callback: (Boolean) -> Unit) { // Matter配网逻辑 } } ``` ### Step 6: 场景与联动(2天) ```kotlin // 场景管理器 - 对接涂鸦场景 + 你的规则引擎 class SceneManager { // 获取场景列表 fun getSceneList(homeId: Long, callback: (List) -> Unit) { ThingHomeSdk.getSceneManagerInstance() .getSceneList(homeId, object : IThingResultCallback { override fun onSuccess(result: SceneBean?) { callback(listOfNotNull(result)) } override fun onError(errorCode: String?, errorMsg: String?) { callback(emptyList()) } }) } // 执行场景 fun executeScene(homeId: Long, sceneId: String, callback: (Boolean) -> Unit) { ThingHomeSdk.getSceneManagerInstance() .executeScene(homeId, sceneId, object : IResultCallback { override fun onSuccess() { callback(true) } override fun onError(errorCode: String?, errorMsg: String?) { callback(false) } }) } // 同时触发你的规则引擎 fun executeSceneWithRule(sceneId: String, callback: (Boolean) -> Unit) { // 1. 执行涂鸦场景 executeScene(homeId, sceneId) { success -> if (success) { // 2. 同步到你的规则引擎 IoTPlatformApi.triggerRule(sceneId, callback) } else { callback(false) } } } } ``` ### Step 7: 数据同步桥接层(3天) ```kotlin // 数据桥接 - 将涂鸦设备数据同步到你的IoT平台 class DataBridge { private val scope = CoroutineScope(Dispatchers.IO) // 初始化设备监听 fun startDeviceMonitoring(homeId: Long) { val homeBean = ThingHomeSdk.getDataInstance().getHomeBean(homeId) homeBean?.deviceList?.forEach { device -> registerDeviceListener(device.devId) } } // 注册设备状态监听 private fun registerDeviceListener(devId: String) { val device = ThingHomeSdk.newDeviceInstance(devId) device.registerDeviceListener(object : IDeviceListener { override fun onDpUpdate(devId: String?, dpStr: String?) { // 设备数据点更新 → 同步到IoT平台 scope.launch { syncDeviceData(devId, dpStr) } } override fun onRemoved(devId: String?) { // 设备被移除 scope.launch { handleDeviceRemoved(devId) } } override fun onStatusChanged(devId: String?, online: Boolean) { // 设备在线状态变化 scope.launch { handleDeviceStatusChange(devId, online) } } override fun onNetworkStatusChanged(devId: String?, status: Boolean) {} override fun onDevInfoUpdate(devId: String?) {} }) } // 同步设备数据到IoT平台 private suspend fun syncDeviceData(devId: String?, dpStr: String?) { if (devId == null || dpStr == null) return val dataPoint = DeviceDataPoint( deviceId = devId, data = JSONObject(dpStr).toMap(), timestamp = System.currentTimeMillis(), source = "tuya" ) // 调用IoT平台数据采集API IoTPlatformApi.reportDeviceData(dataPoint) } // 同步设备在线状态 private suspend fun handleDeviceStatusChange(devId: String?, online: Boolean) { if (devId == null) return IoTPlatformApi.updateDeviceStatus(devId, online) } // 处理设备移除 private suspend fun handleDeviceRemoved(devId: String?) { if (devId == null) return IoTPlatformApi.removeDevice(devId) } } ``` ### Step 8: 告警通知对接(2天) ```kotlin // 告警桥接 - 涂鸦告警 + 你的告警服务 class AlarmBridge { // 监听涂鸦设备告警 fun startAlarmMonitoring(homeId: Long) { // 方式1:监听设备状态异常 val homeBean = ThingHomeSdk.getDataInstance().getHomeBean(homeId) homeBean?.deviceList?.forEach { device -> monitorDeviceAlarm(device) } // 方式2:轮询你的告警服务 startAlarmPolling() } // 监听设备告警 private fun monitorDeviceAlarm(device: DeviceBean) { val deviceInstance = ThingHomeSdk.newDeviceInstance(device.devId) deviceInstance.registerDeviceListener(object : IDeviceListener { override fun onDpUpdate(devId: String?, dpStr: String?) { // 检查是否触发告警规则 checkAlarmRules(devId, dpStr) } // ...其他方法 }) } // 检查告警规则 private fun checkAlarmRules(devId: String?, dpStr: String?) { scope.launch { // 调用IoT平台告警检测API val result = IoTPlatformApi.checkAlarm(devId, dpStr) if (result.hasAlarm) { showAlarmNotification(result) } } } // 显示告警通知 private fun showAlarmNotification(alarm: AlarmResult) { val notification = NotificationCompat.Builder(context, CHANNEL_ID) .setContentTitle("设备告警") .setContentText(alarm.message) .setSmallIcon(R.drawable.ic_alarm) .setAutoCancel(true) .build() NotificationManagerCompat.from(context) .notify(alarm.id.hashCode(), notification) } } ``` --- ## 五、项目目录结构 ``` app/ ├── src/main/ │ ├── java/com/iotsaas/ │ │ ├── IotApplication.kt # Application初始化 │ │ ├── bridge/ # 桥接层 │ │ │ ├── DataBridge.kt # 数据同步桥接 │ │ │ ├── AlarmBridge.kt # 告警桥接 │ │ │ └── DeviceSyncBridge.kt # 设备同步桥接 │ │ ├── tuya/ # 涂鸦SDK封装 │ │ │ ├── TuyaManager.kt # 涂鸦SDK管理器 │ │ │ ├── TuyaLoginHelper.kt # 登录帮助类 │ │ │ ├── TuyaHomeHelper.kt # 家庭管理帮助类 │ │ │ ├── TuyaDeviceHelper.kt # 设备管理帮助类 │ │ │ ├── TuyaActivatorHelper.kt # 配网帮助类 │ │ │ ├── TuyaSceneHelper.kt # 场景帮助类 │ │ │ └── TuyaMatterHelper.kt # Matter帮助类 │ │ ├── platform/ # IoT平台SDK封装 │ │ │ ├── IoTPlatformApi.kt # 平台API │ │ │ ├── IoTPlatformConfig.kt # 平台配置 │ │ │ └── model/ # 数据模型 │ │ ├── ui/ # UI层 │ │ │ ├── login/ # 登录页 │ │ │ ├── home/ # 首页 │ │ │ ├── device/ # 设备管理 │ │ │ ├── scene/ # 场景管理 │ │ │ ├── alarm/ # 告警管理 │ │ │ └── profile/ # 个人中心 │ │ └── util/ # 工具类 │ ├── res/ # 资源文件 │ └── assets/ # 涂鸦SDK资源 │ ├── configList.json # 涂鸦配置 │ ├── thing_plugin_config.json # 插件配置 │ └── module_app.json # 模块配置 ├── libs/ │ └── security-algorithm-1.0.0-beta.aar # 安全组件 └── build.gradle ``` --- ## 六、开发排期 | 阶段 | 内容 | 工期 | 优先级 | |------|------|------|--------| | **Phase 1** | 涂鸦平台准备 + SDK集成 + 初始化 | 3天 | ⭐⭐⭐ | | **Phase 2** | 用户登录 + 双平台账号关联 | 2天 | ⭐⭐⭐ | | **Phase 3** | 家庭管理 + 设备列表 | 3天 | ⭐⭐⭐ | | **Phase 4** | 设备配网(Wi-Fi/BLE) | 3天 | ⭐⭐⭐ | | **Phase 5** | 设备控制 + 状态监听 | 3天 | ⭐⭐⭐ | | **Phase 6** | 数据同步桥接层 | 3天 | ⭐⭐ | | **Phase 7** | 场景联动 + 规则引擎对接 | 2天 | ⭐⭐ | | **Phase 8** | 告警通知对接 | 2天 | ⭐⭐ | | **Phase 9** | Matter设备配网 | 2天 | ⭐⭐ | | **Phase 10** | UI优化 + 测试 | 3天 | ⭐ | | **合计** | | **26天** | | --- ## 七、注意事项与风险 ### 7.1 关键注意点 1. **包名一致性**:APP的 `applicationId` 必须与涂鸦平台配置完全一致 2. **SHA256指纹**:签名文件的SHA256必须在涂鸦平台配置 3. **安全组件**:`security-algorithm.aar` 必须与AppKey/AppSecret配套使用 4. **试用版限制**:试用版SDK启动时会弹出位置权限和Toast提示 5. **版本升级**:本地SDK 7.5.0 → 建议升级到 Maven 最新 7.5.1 ### 7.2 风险与应对 | 风险 | 可能性 | 应对措施 | |------|--------|----------| | 涂鸦SDK版本升级导致API变更 | 中 | 关注更新日志,锁定SDK版本 | | 涂鸦云服务不稳定 | 低 | 本地缓存 + 重试机制 | | 双平台数据同步延迟 | 中 | WebSocket实时推送 + 定时轮询 | | Matter设备兼容性 | 中 | 充分测试,关注官方更新 | | 安全组件校验失败 | 中 | 严格检查AppKey/包名/SHA256 | ### 7.3 参考资源 - 涂鸦官方文档: https://developer.tuya.com/cn/docs/app-development/preparation - 涂鸦Demo(Kotlin): https://github.com/tuya/tuya-home-android-sdk-sample-kotlin - 涂鸦论坛: https://www.tuyaos.com/ - 更新日志: https://developer.tuya.com/cn/docs/app-development/changelog --- **文档版本**: v1.0 **创建日期**: 2026-04-27 **作者**: IoT Platform Team