controller-sdk-integration.md

ControllerSDK 集成指南

项目定位

ControllerSDK 是山猫M20的独立手柄控制组件，封装云卓 G20 手柄输入，通过 JoystickData 暴露摇杆实时数据，供 RobotSDK 的摇杆指令发送使用。它不依赖 RobotSDK 及其底层协议栈，可按需单独集成。

兼容性：ControllerSDK 仅支持山猫 M20 标配的云卓 G20 手柄，不兼容其他型号。本仓库仅提供源码，不提供预编译 AAR，需自行编译后集成。

核心能力

• 手柄即插即用：支持山猫 M20 标配的云卓 G20 手柄
• 摇杆数据实时暴露：通过 joystickDataLive 提供左右摇杆原始值与归一化值（-1.0 ~ 1.0）
• 物理按键状态：通过 physicalKeyStatesLive 提供当前按下的按键列表
• 手柄连接状态：通过 d2dConnectStateLive 和 d2dSignalLive 监控连接与信号

架构说明

ControllerSDK 是独立于 RobotSDK 及其底层协议栈的 Android Library：

Your App
    ↓
ControllerSDK  →  通过 rcsdk 直连手柄
    ↓
rcsdk.aar  （云卓手柄 SDK，需自行获取）

ControllerSDK 不依赖 RobotProtocol、RobotConnectUDP 与 RobotSDK，可按需单独集成。

环境要求

• Android Studio 最新稳定版
• minSdk 21 (Android 5.0)
• Kotlin 1.8+
• 山猫 M20 标配的云卓 G20 手柄
• 兼容性：ControllerSDK 仅支持山猫 M20 标配的云卓 G20 手柄，不兼容其他型号

获取 SDK

方式一：先编译 AAR 再引入（推荐）

由于 ControllerSDK 依赖第三方库，即云卓官方手柄SDK rcsdk.aar(≥v1.8.1)，该库 不随本项目发布，需要开发者自行从手柄官方代码仓库获取并集成到 ControllerSDK 中进行编译。

下载步骤：

1. 访问云卓 RCSDK 示例项目：https://gitee.com/skydroid/rcsdk-demo
2. 找到 libs/rcsdk-v1.9.1.aar 文件
3. 将该文件复制到ControllerSDK/libs

编译

./gradlew :ControllerSDK:buildSdkAar

产物：ControllerSDK/build/outputs/sdk/ControllerSDK-1.0.0.aar

在你的新项目中调用ControllerSDK的封装库时需要将以下文件放到/app/libs目录下，并在 build.gradle 中引入相关依赖：

• ControllerSDK-1.0.0.aar（主体）
• rcsdk-v1.9.1.aar（云卓手柄 SDK，不随本项目发布）

在 build.gradle 中：

dependencies {
    // fileTree 会自动引入 libs/ 下的 ControllerSDK-1.0.0.aar 和 rcsdk-v1.9.1.aar
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])

    // ControllerSDK 的外部依赖（AAR 不含以下依赖，需显式声明）
    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
    implementation 'androidx.lifecycle:lifecycle-livedata-ktx:2.8.7'
    implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.5.1'
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.1'
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1'
}

依赖说明：ControllerSDK AAR 本身不包含 rcsdk-v1.9.1.aar，两者必须同时放入 libs/ 目录。kotlin-stdlib、lifecycle、coroutines 为 ControllerSDK 的运行时外部依赖，需由集成方显式声明。

方式二：以源码 Module 依赖（开发调试推荐）

将 ControllerSDK 模块作为本地 Module 引入你的项目，适合需要调试 SDK 源码的场景。

在项目的 settings.gradle 中：

include ':ControllerSDK'
project(':ControllerSDK').projectDir = new File('/path/to/M20_AndroidSDK/ControllerSDK')

在根项目的 build.gradle（或 allprojects 块）中配置 flatDir，使 Gradle 能解析 ControllerSDK/libs/ 下的 rcsdk-v1.9.1.aar：

allprojects {
    repositories {
        google()
        mavenCentral()
        // 必须配置 flatDir，否则无法解析 rcsdk-v1.9.1.aar
        flatDir { dirs "${rootDir}/ControllerSDK/libs" }
    }
}

在 App 模块的 build.gradle 中：

dependencies {
    implementation project(':ControllerSDK')

    // ControllerSDK 的外部依赖（需显式声明）
    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
    implementation 'androidx.lifecycle:lifecycle-livedata-ktx:2.8.7'
    implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.5.1'
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.1'
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1'
}

注意：以 Module 方式依赖时，rcsdk-v1.9.1.aar 的解析通过 flatDir 仓库完成（由 ControllerSDK/build.gradle 中的 implementation(name: 'rcsdk-v1.9.1', ext: 'aar') 引用）。因此必须在根项目的 repositories 中配置对应的 flatDir 路径，否则编译时会报 Could not find :rcsdk-v1.9.1:。

详细编译步骤见 ControllerSDK 构建指南。

集成步骤

1. 初始化

在 Application.onCreate() 中初始化：

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        ControllerManager.init(this)
    }
}

init() 必须先于 connect() 执行，否则无法正确识别设备型号。

2. 连接手柄

在需要接收手柄输入的 Activity 中：

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

    ControllerManager.connect(this, lifecycleScope) { e ->
        Log.e("M20", "手柄连接异常: ${e.message}")
    }
}

3. 观察摇杆数据

ControllerManager.joystickDataLive?.observe(this) { joy ->
    val leftX  = joy.leftXNorm   // 左摇杆左右（-1.0 ~ 1.0）
    val leftY  = joy.leftYNorm   // 左摇杆上下
    val rightX = joy.rightXNorm  // 右摇杆左右
    val rightY = joy.rightYNorm  // 右摇杆上下
}

4. 观察物理按键

ControllerManager.physicalKeyStatesLive?.observe(this) { keys ->
    keys?.forEach { key ->
        when (key.name) {
            "G20_KEY_STOP" -> { /* 急停 */ }
            "G20_KEY_HOME" -> { /* HOME */ }
            else -> { /* 其他按键 */ }
        }
    }
}

5. 生命周期管理

override fun onResume() {
    super.onResume()
    ControllerManager.onResume()
}

override fun onPause() {
    super.onPause()
    ControllerManager.onPause()
}

override fun onDestroy() {
    super.onDestroy()
    ControllerManager.disconnect()
}

与 RobotSDK 配合使用

ControllerSDK 本身不直接发送机器人指令，它只负责将手柄输入转换为 JoystickData。你需要将 JoystickData 手动映射为 RobotSDK 的 AxisData，并通过 axisDataProvider 提供给 RobotSdkManager：

ControllerManager.joystickDataLive?.observe(this) { joy ->
    RobotSdkManager.axisDataProvider = {
        AxisData(
            x = joy.leftYNorm,
            y = -joy.leftXNorm,
            z = -joy.rightYNorm,
            yaw = -joy.rightXNorm,
            roll = 0f,
            pitch = 0f
        )
    }
}

摇杆数据映射

JoystickData 到 AxisData 的推荐映射方式：

JoystickData 字段	映射到 AxisData	说明
leftYNorm	x	前后移动
-leftXNorm	y	左右移动
-rightYNorm	z	升降（暂不支持）
-rightXNorm	yaw	旋转

注意：当前基础步态和楼梯步态下，仅 x、y、yaw 三个轴生效，z、roll、pitch 暂不支持。

注意事项

1. 兼容性：ControllerSDK 仅支持山猫 M20 标配的云卓 G20 手柄，不兼容其他型号。
2. 依赖获取：rcsdk-v1.9.1.aar 不随本项目发布，需从云卓官方获取。
3. 权限：部分手柄需要 USB 连接权限，确保在 AndroidManifest.xml 中声明 USB 权限。
4. 生命周期：建议在 Activity.onResume() 中调用 onResume()，Activity.onPause() 中调用 onPause()，onDestroy() 中调用 disconnect()。
5. 异常处理：connect() 提供了 onException 回调，用于处理连接异常。

开源许可

本项目采用 Apache License 2.0 开源。

下一步

• 查阅完整 API：controller-sdk-api-reference.md
• RobotSDK 集成指南：robot-sdk-integration.md