Aqara Camera SDK 集成文档

版本：v1.0.5 更新日期：2025年12月
适用平台：Android

目录

• 1. 概述
• 2. 功能特性
• 3. 环境要求
• 4. 快速集成
  • 4.1 添加 Maven 仓库
  • 4.2 添加依赖
  • 4.3 配置 AndroidManifest
  • 4.4 配置混淆规则
• 5. SDK 初始化
  • 5.1 Application 初始化
  • 5.2 核心 SDK 初始化
• 6. 功能接口
  • 6.1 设备配网
  • 6.2 摄像机控制页面
• 7. 支持设备列表
• 8. 服务器域名配置
• 9. 常见问题

1. 概述

Aqara Camera SDK 是绿米联创提供的智能摄像机解决方案，帮助开发者快速集成 Aqara 系列摄像机的配网、实时预览、回放、云存储等功能到您的 Android 应用中。

架构图

┌─────────────────────────────────────────────────────────┐
│                    您的应用 (Host App)                    │
├─────────────────────────────────────────────────────────┤
│                   Aqara Camera SDK                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │   配网模块    │  │  摄像机控制   │  │   云存储     │   │
│  │   Access     │  │   Camera     │  │   Cloud      │   │
│  └──────────────┘  └──────────────┘  └──────────────┘   │
├─────────────────────────────────────────────────────────┤
│                    Aqara Core SDK                        │
│         (网络通信 / 用户管理 / 设备管理)                   │
└─────────────────────────────────────────────────────────┘

2. 功能特性

3. 环境要求

支持的 CPU 架构

• arm64-v8a ✅
• armeabi-v7a ✅

4. 快速集成

4.1 添加 Maven 仓库

在项目根目录的 settings.gradle 中添加 Aqara Maven 仓库：

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        // Aqara Maven 仓库
        maven {
            url 'https://public-maven.aqara.com/repository/lumi-release/'
            credentials {
                username = 'aqara_guest'
                password = 'tMQ_BNN!z54W.2S'
            }
        }
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
        // Aqara Maven 仓库
        maven {
            url 'https://public-maven.aqara.com/repository/lumi-release/'
            credentials {
                username = 'aqara_guest'
                password = 'tMQ_BNN!z54W.2S'
            }
        }
    }
}

在项目根目录的 build.gradle 中添加插件依赖：

buildscript {
    dependencies {
        // Aqara SDK 统一初始化插件（必需）
        classpath "com.lumi.plugin:module-init:3.0.0"
    }
}

plugins {
    id 'com.android.application' version '7.4.2' apply false
    id 'org.jetbrains.kotlin.android' version '2.1.0' apply false
}

4.2 添加依赖

在 app/build.gradle 中添加依赖：

plugins {
    id 'com.android.application'
    id 'kotlin-android'
}

// 应用 Aqara SDK 统一初始化插件（必需）
apply plugin: 'lumi-module-init'

android {
    namespace 'com.your.package.name'
    compileSdk 34

    defaultConfig {
        minSdk 26
        targetSdk 34
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }

    kotlinOptions {
        jvmTarget = '11'
    }

    // 解决 so 库冲突
    packagingOptions {
        pickFirst 'lib/arm64-v8a/libc++_shared.so'
        pickFirst 'lib/armeabi-v7a/libc++_shared.so'
    }
}

dependencies {
    // ==================== Aqara SDK 核心依赖 ====================

    // Core SDK（必需）- 提供基础网络、用户管理等功能
    implementation 'com.lumi.external:core:2.2.9'

    // ==================== 配网 SDK（按需引入）====================

    // 设备配网 SDK
    implementation 'com.lumi.module.smart_connect:connect:3.4.129'
    implementation 'com.lumi.module.access:access:3.4.129'
    implementation 'com.lumi.api:access:3.4.129'

    // ==================== 摄像机 SDK（必需）====================

    // Camera SDK
    implementation 'com.lumi.sdk:camera:3.2.448.10'
    implementation 'com.lumi.api:camera:3.2.448.10'

    // ==================== 其他必需依赖 ====================

    // 路由模块
    implementation 'com.lumi.module.router:router:1.0.24'
    implementation 'com.lumi.sdk:device-router:1.0.5'

    // 设备控制插件
    implementation 'com.lumi.sdk:rmextra:1.1.66.2'

    // 系统属性
    implementation 'com.lumi.lib.sysprop:sysprop:1.0.0'

    // 设备管理
    implementation 'com.lumi.module:devicekit:1.0.22'

    // ARouter（页面路由，必需）
    implementation 'com.alibaba:arouter-api:1.5.2'
}

4.3 配置 AndroidManifest

在 AndroidManifest.xml 中添加必要配置：

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- 网络权限 -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />

    <!-- 存储权限（用于视频截图、录像保存）-->
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

    <!-- 蓝牙权限（配网使用）-->
    <uses-permission android:name="android.permission.BLUETOOTH" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

    <!-- 定位权限（配网使用）-->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

    <!-- 麦克风权限（双向语音）-->
    <uses-permission android:name="android.permission.RECORD_AUDIO" />

    <application
        android:name=".YourApplication"
        android:allowBackup="false"
        android:networkSecurityConfig="@xml/network_security_config"
        android:usesCleartextTraffic="true"
        tools:replace="android:allowBackup,android:networkSecurityConfig">

        <!-- FileProvider 配置（用于文件分享）-->
        <provider
            android:name="androidx.core.content.FileProvider"
            android:authorities="${applicationId}.fileprovider"
            android:exported="false"
            android:grantUriPermissions="true">
            <meta-data
                android:name="android.support.FILE_PROVIDER_PATHS"
                android:resource="@xml/lm_rm_extra_file_paths" />
        </provider>

    </application>
</manifest>

创建网络安全配置文件 res/xml/network_security_config.xml：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
    </base-config>
</network-security-config>

创建文件路径配置 res/xml/lm_rm_extra_file_paths.xml：

<?xml version="1.0" encoding="utf-8"?>
<paths>
    <external-path name="external" path="." />
    <external-files-path name="external_files" path="." />
    <cache-path name="cache" path="." />
    <files-path name="files" path="." />
</paths>

4.4 配置混淆规则

在 proguard-rules.pro 中添加：

# ==================== Aqara SDK 混淆规则 ====================

# Core SDK
-keep class com.lumi.** { *; }
-keep class com.lumiunited.** { *; }
-dontwarn com.lumi.**
-dontwarn com.lumiunited.**

# ARouter
-keep public class com.alibaba.android.arouter.routes.**{*;}
-keep public class com.alibaba.android.arouter.facade.**{*;}
-keep class * implements com.alibaba.android.arouter.facade.template.ISyringe{*;}

# FastJSON
-keep class com.alibaba.fastjson.** { *; }
-dontwarn com.alibaba.fastjson.**

# RxJava
-keep class io.reactivex.** { *; }
-dontwarn io.reactivex.**

# 保留实体类
-keep class * implements java.io.Serializable { *; }
-keepclassmembers class * implements java.io.Serializable {
    static final long serialVersionUID;
    private static final java.io.ObjectStreamField[] serialPersistentFields;
    !static !transient <fields>;
    private void writeObject(java.io.ObjectOutputStream);
    private void readObject(java.io.ObjectInputStream);
    java.lang.Object writeReplace();
    java.lang.Object readResolve();
}

5. SDK 初始化

5.1 Application 初始化

在您的 Application 类中进行初始化：

import android.app.Application
import com.alibaba.android.arouter.launcher.ARouter
import com.lumi.api.camera.AppConfigManager
import com.lumi.arms.lifecycle.delegate.AppManager
import com.lumiunited.CameraSDKInit

class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        // 2. 初始化 ARouter（仅在 Debug 模式开启日志）
        if (BuildConfig.DEBUG) {
            ARouter.openLog()
            ARouter.openDebug()
        }
        ARouter.init(this)

        // 3. 初始化生命周期管理器
        AppManager.instance.init(this)

        // 4. 初始化 Camera SDK
        CameraSDKInit.init(this)
    }
}

5.2 核心 SDK 初始化

在使用 SDK 功能前，需要进行核心初始化（建议在启动页或首页进行）：

import com.lumi.external.LumiCoreManager
import com.lumi.external.manager.session.ILumiUserInfo
import com.lumi.module.camera.CameraSDKManager
import com.lumi.module.camera.utils.JumpToWebPageUtils
import com.lumiunited.CameraSDKInit
import io.reactivex.plugins.RxJavaPlugins

class SplashActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // 设置 SDK 模式
        CameraSDKManager.setSDKMode(true)

        // 设置 RxJava 全局异常处理
        RxJavaPlugins.setErrorHandler { it.printStackTrace() }

        // 初始化 SDK
        initAqaraSDK()
    }

    private fun initAqaraSDK() {
        // ==================== 配置参数 ====================
        // 以下参数需通过 Aqara 开发者平台获取
        // 文档：https://opendoc.aqara.com/docs/developmanual/addDevice/appSDK.html

        val appId = "您的AppId"              // 开发者平台申请
        val appKey = "您的AppKey"            // 开发者平台申请
        val appRequestDomain = "https://aiot-rpc.aqara.cn"  // API域名
        val baseH5Url = "https://cdn.aqara.com/cdn/app/mainland/h5/index.html#"
        val baseImageUrl = "https://cdn.aqara.com/cdn/common/mainland/prd/statics/default"

        // 用户信息（通过您的服务端获取）
        val userId = "用户ID"
        val token = "用户Token"
        val positionId = "位置ID"

        // 区域配置
        val area = "CHN"                     // 国家/地区代码
        val supportDeviceArea = "CHN"        // 设备支持区域
        val language = "zh"                  // 语言 (zh/en)

        // ==================== 扩展配置 ====================
        val extension = HashMap<String, String>().apply {
            // 使用本地设备插件资源
            put("RMSDK_K_LOCAL_RES", "true")
            put("RMExtraSDK_K_CONFIG_LOAD_TYPE", "0")
            put("BaseH5UrlV2", JumpToWebPageUtils.getH5UrlV2())
        }

        // 初始化 RN 扩展
        CameraSDKInit.initRnExtensions(extension)

        // ==================== 核心初始化 ====================
        LumiCoreManager.getInstance().init(
            application,
            true,  // 是否启用日志
            LumiCoreManager.LumiCoreSDKConfig.builder()
                .appId(appId)
                .appKey(appKey)
                .baseUrl(appRequestDomain)
                .baseImageUrl(baseImageUrl)
                .baseH5Url(baseH5Url)
                .sdkChannel("YourAppName")           // 您的应用名称
                .clientId(getDeviceUniqueId())       // 设备唯一标识
                .extensions(extension)
                .userInfo(object : ILumiUserInfo {
                    override fun getUserId(): String = userId
                    override fun getUserToken(): String = token
                    override fun getArea(): String = area
                    override fun getSupportDeviceArea(): String = supportDeviceArea
                    override fun getLanguage(): String = language
                })
                .build()
        )

        // ==================== 附加初始化 ====================
        CameraSDKInit.initLinkBridge()
        CameraSDKInit.initPosition(positionId)
        CameraSDKInit.initH5UrlParams(this, appRequestDomain)
    }

    private fun getDeviceUniqueId(): String {
        // 返回设备唯一标识，建议使用 AndroidId 或自定义 UUID
        return Settings.Secure.getString(contentResolver, Settings.Secure.ANDROID_ID)
    }
}

6. 功能接口

6.1 设备配网

提供带 UI 的设备配网流程：

import com.lumi.moudle.access.LumiAccessSDKManager
import com.lumi.moudle.access.callback.LumiResultCallBack
import java.lang.ref.WeakReference

/**
 * 启动设备配网页面
 * 
 * @param deviceModel 设备型号，如 "lumi.camera.agl002"
 * @param positionId 位置ID
 * @param coapServer CoAP 服务器地址
 */
fun startDeviceAccess(deviceModel: String, positionId: String, coapServer: String) {
    // 设置配网信息
    LumiAccessSDKManager.getInstance().setAccessInfo(positionId, coapServer)

    // 启动配网页面
    LumiAccessSDKManager.getInstance().gotoAccessConfigModule(
        this,
        deviceModel,
        object : LumiResultCallBack {

            override fun success(activity: WeakReference<Activity>, message: String?) {
                // 配网成功
                activity.get()?.finish()

                // 解析设备信息
                message?.let {
                    val deviceInfo = JSON.parseObject(it)
                    val did = deviceInfo.getString("did")          // 设备ID
                    val model = deviceInfo.getString("model")      // 设备型号
                    val deviceName = deviceInfo.getString("deviceName")  // 设备名称

                    // 配网成功后，可直接打开摄像机控制页面
                    openCameraPage(did, model, deviceName)
                }
            }

            override fun fail(errorCode: Int?, errorMessage: String?) {
                // 配网失败
                Log.e("Access", "配网失败: code=$errorCode, msg=$errorMessage")
                Toast.makeText(this@YourActivity, "配网失败: $errorMessage", Toast.LENGTH_SHORT).show()
            }
        }
    )
}

6.2 摄像机控制页面

打开摄像机实时预览和控制页面：

import com.lumi.module.camera.api.LumiCameraSDK

/**
 * 打开摄像机控制页面
 * 
 * @param deviceId 设备ID (did)
 * @param deviceModel 设备型号
 * @param deviceName 设备名称（用于页面标题显示）
 */
fun openCameraPage(deviceId: String, deviceModel: String, deviceName: String) {
    LumiCameraSDK.getRouter().startCameraPage(
        deviceModel,    // 设备型号
        deviceId,       // 设备ID
        deviceName,     // 设备名称
        false           // 是否隐藏标题栏
    )
}

完整使用示例

class CameraListActivity : AppCompatActivity() {

    // 设备列表数据
    private val cameraList = mutableListOf<CameraDevice>()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_camera_list)

        // 配网按钮
        findViewById<Button>(R.id.btn_add_camera).setOnClickListener {
            // 打开 G4 门铃配网
            startDeviceAccess(
                deviceModel = "lumi.camera.agl002",
                positionId = "your_position_id",
                coapServer = "aiot-coap.aqara.cn"
            )
        }

        // 设备列表点击
        recyclerView.setOnItemClickListener { position ->
            val camera = cameraList[position]
            openCameraPage(
                deviceId = camera.did,
                deviceModel = camera.model,
                deviceName = camera.name
            )
        }
    }

    private fun startDeviceAccess(deviceModel: String, positionId: String, coapServer: String) {
        LumiAccessSDKManager.getInstance().setAccessInfo(positionId, coapServer)
        LumiAccessSDKManager.getInstance().gotoAccessConfigModule(
            this,
            deviceModel,
            object : LumiResultCallBack {
                override fun success(activity: WeakReference<Activity>, message: String?) {
                    activity.get()?.finish()
                    message?.let {
                        val info = JSON.parseObject(it)
                        // 添加到列表
                        cameraList.add(CameraDevice(
                            did = info.getString("did"),
                            model = info.getString("model"),
                            name = info.getString("deviceName")
                        ))
                        // 刷新列表
                        adapter.notifyDataSetChanged()
                    }
                }

                override fun fail(errorCode: Int?, errorMessage: String?) {
                    Toast.makeText(this@CameraListActivity, "添加失败", Toast.LENGTH_SHORT).show()
                }
            }
        )
    }

    private fun openCameraPage(deviceId: String, deviceModel: String, deviceName: String) {
        LumiCameraSDK.getRouter().startCameraPage(deviceModel, deviceId, deviceName, false)
    }

    data class CameraDevice(
        val did: String,
        val model: String,
        val name: String
    )
}

7. 支持设备列表

💡 如需支持更多设备型号，请联系 Aqara 商务获取对应的设备资源包。

8. 服务器域名配置

根据您的服务区域，选择对应的服务器域名：

8.1 API 请求域名 (appRequestDomain)

8.2 CoAP 服务器 (coapServer)

8.3 CDN 资源域名

⚠️ 重要提示：appRequestDomain 和 coapServer 必须配套使用，否则设备配网可能失败。

9. 常见问题

Q1: 初始化失败，提示 "appId invalid"

原因：AppId 或 AppKey 配置错误。

解决方案：

1. 确认 AppId 和 AppKey 是从 Aqara 开发者平台 正确获取
2. 检查是否与申请时的包名一致
3. 确认账号是否有对应设备型号的权限

Q2: 配网失败，设备找不到

原因：网络配置或权限问题。

解决方案：

1. 确保手机已连接 2.4GHz WiFi（部分设备不支持 5GHz）
2. 检查是否已授予定位权限
3. 确保设备已进入配网模式
4. 检查 coapServer 配置是否正确

Q3: 摄像机页面打开白屏

原因：RN 插件未正确加载。

解决方案：

1. 确保已正确调用 CameraSDKInit.initRnExtensions()
2. 检查 assets/deviceRes 目录下是否有对应设备型号的资源文件
3. 确认 RMSDK_K_LOCAL_RES 配置为 "true"

Q4: 实时预览无画面

原因：网络或设备问题。

解决方案：

1. 检查设备是否在线
2. 确认手机网络正常
3. 检查 userId 和 token 是否有效
4. 尝试重启设备

Q5: 编译报错 "Duplicate class"

原因：依赖库版本冲突。

解决方案： 在 build.gradle 中添加：

configurations.all {
    resolutionStrategy {
        force 'com.alibaba:arouter-api:1.5.2'
        // 其他冲突的库...
    }
}

Q6: Android 14 报错 "Receiver not allowed to receive"

原因：Android 14 对广播接收器有新的限制。

解决方案： 确保使用最新版本的 SDK，已修复此问题。

技术支持

如有问题，请通过以下方式联系我们：

• 📧 邮箱：developer@aqara.com
• 📖 开发文档：https://opendoc.aqara.com
• 🔧 开发者平台：https://developer.aqara.com

© 2025 Aqara. All rights reserved.