本项目是面向行业开发者与生态合作伙伴交付的 山猫M20 Android版 APP 开发 SDK，包含 SDK 源码（RobotSDK + ControllerSDK）及 SimpleDemo 示例应用，使其能够基于代码基底快速开发集成上装控制功能（如机械臂、云台、传感器等），无需从零搭建通信、遥控框架与 UI。
说明：本仓库仅提供 SDK 源码，不提供预编译 AAR。开发者需自行从源码编译 AAR 后集成到自己的项目中。
适配机型：山猫 M20 、 山猫 M20 Pro 。
-
RobotSDK 源码（含 RobotProtocol + RobotConnectUDP）
- 是什么：可直接编译的 Android Library 源码模块，包含协议编解码（RobotProtocol）、UDP 通信（RobotConnectUDP）以及机器人连接、状态管理与遥控指令发送（RobotSDK）。
- 作用：开发者从源码编译生成 AAR 后集成到自己的 App 项目中，实现机器人连接、实时状态获取和遥控指令发送。如需修改 SDK 内部逻辑（如新增协议字段、调整通信方式、扩展状态维度），直接改源码并重新编译即可。
-
ControllerSDK 源码
- 是什么：独立的 Android Library 源码模块，封装云卓 G20 手柄输入，暴露摇杆实时数据和物理按键触发状态。不依赖 RobotSDK 及其底层协议栈，可按需单独集成。
- 作用：编译 AAR 后集成到 App 项目中，为需要实体手柄操控的场景提供即插即用的手柄接入能力。
-
SimpleDemo 示例应用
- 是什么：一个完整的 Android App 示例，展示了如何引入 SDK 源码模块、初始化 SDK、监听机器人状态以及发送机器人遥控指令。
- 作用：作为开箱即用的演示程序和二次开发代码基底，你可以直接运行体验，或在其 UI 框架上修改迭代自己的业务功能。
M20_AndroidSDK 由 RobotSDK 与 ControllerSDK 两个独立的 Android Library 组成，可按需分别集成。整体架构由下到上依次为：
┌───────────────────────┐ ┌───────────────────────┐
│ RobotSDK │ │ ControllerSDK │
│ （源码编译 AAR） │ │ （源码编译 AAR） │
└────────────┬──────────┘ └────────────┬──────────┘
│ │
┌────────────▼────────────┐ ┌──────────▼────────────┐
│ RobotConnectUDP │ │ rcsdk-v1.9.1.aar │
│RobotConnectUDP-1.0.0.jar│ │ 云卓手柄 SDK │
│ (UDP+JSON) │ │ 需从 Gitee 下载 │
└────────────┬────────────┘ └───────────────────────┘
│
┌────────────▼──────────┐
│ RobotProtocol │
│ (协议/消息定义) │
└───────────────────────┘
各模块职责如下：
- RobotProtocol：纯 Kotlin 协议编解码库，定义消息帧头、
CommandType、消息工厂等。无 Android 依赖，可被非 Android 模块复用。 - RobotConnectUDP：UDP + JSON 通信实现，管理
DatagramSocket、心跳、收发线程，对外暴露IRobotConnection统一接口。 - RobotSDK：Android Library 源码，封装机器人连接、状态管理和指令发送。
RobotSdkManager单例是 App 层唯一入口。需从源码编译 AAR 后集成。 - ControllerSDK：独立的 Android Library 源码，封装云卓 G20 手柄输入，通过外部
rcsdk直接对接手柄，不依赖 RobotProtocol 与 RobotConnectUDP。需从源码编译 AAR 后集成。
M20_AndroidSDK/
├── RobotProtocol/ # 协议层源码：纯 Kotlin 协议编解码库，定义消息帧头、CommandType、消息工厂等，无 Android 依赖
├── RobotConnectUDP/ # 通信层源码：UDP + JSON 通信实现，管理 DatagramSocket、心跳、收发线程，对外暴露 IRobotConnection 接口
├── RobotSDK/ # 机器人控制 SDK 源码（Android Library），封装连接、状态管理和指令发送，RobotSdkManager 为 App 层唯一入口
├── ControllerSDK/ # 手柄 SDK 源码（Android Library），封装云卓 G20 手柄输入，通过 rcsdk 直接对接手柄，不依赖 RobotProtocol/RobotConnectUDP
├── SimpleDemo/ # 示例应用源码：演示如何集成 RobotSDK 源码模块，并构建机器人遥控 UI（不包含 ControllerSDK）
├── sdk-docs/ # 📘 SDK 集成文档（面向 App 开发者）
└── sdk-source-docs/ # 📗 SDK 源码文档（面向 SDK 开发者）
说明：本仓库仅提供 SDK 源码，不提供预编译 AAR。SimpleDemo 示例 App 通过源码模块依赖的方式集成 RobotSDK，可直接运行体验；开发者也可以先编译 SDK 生成 AAR，再集成到自己的 App 项目中使用。SDK 各模块（RobotProtocol、RobotConnectUDP、RobotSDK、ControllerSDK）均可独立编译。
| 你是谁 | 你的目标 | 应该看哪里 |
|---|---|---|
| App 开发者 | 在你的 Android App 中集成 SDK，实现机器人连接、遥控、状态获取，或基于 SimpleDemo 做二次开发 | 📘 sdk-docs/ |
| SDK 开发者 | 修改、编译、打包 SDK 源码，理解内部架构，扩展协议或通信层 | 📗 sdk-source-docs/ |
如果你希望：
- 快速将机器人遥控能力集成到自己的 Android 项目中
- 基于 SimpleDemo 的 UI 框架进行二次开发
- 从源码编译 AAR 后集成到你的 App 项目中
推荐阅读顺序：
- RobotSDK 集成指南 — 环境要求、AAR 编译与 Gradle 集成、初始化、状态监听、遥控指令、生命周期管理
- RobotSDK API 参考 — 完整 API 说明，含可直接 Copy 的代码片段、状态判断速查、异常处理
- RobotSDK 协议自定义扩展 — 如何发送/接收自定义协议指令（如上装补光灯控制）
- ControllerSDK 集成指南 — 云卓 G20 手柄接入（仅限山猫 M20 标配手柄）
- ControllerSDK API 参考 — 手柄接入 SDK 的完整 API 说明
- SimpleDemo 指南 — 功能特性、代码结构、运行步骤、自定义开发场景
- 常见问题 / 故障排查 — 快速排错
如果你希望：
- 修改 SDK 内部协议、通信或业务逻辑
- 从源码编译出 AAR 包
- 理解四层架构设计（Protocol → Communication → Business → Application）
- 扩展新的通信方式或协议字段
推荐阅读顺序：
- RobotSDK 构建指南 — 源码编译、Fat AAR 打包、本地/远程依赖切换
- ControllerSDK 构建指南 — 源码编译、rcsdk 依赖获取
- RobotSDK 架构设计 — 协议层、通信层、业务层架构，各模块职责与扩展点
- ControllerSDK 架构设计 — 手柄层架构、核心类、归一化与死区机制、rcsdk 外部依赖
- 异常系统技术文档 — 异常上报数据流、枚举匹配机制、UI 展示文本解析链、国际化注意事项
- 更新日志 — 版本迭代记录
- Language: Kotlin
- Build Tool: Gradle + Android Gradle Plugin
- Communication: UDP / JSON
- Protocol: 机器人控制协议文档
- Minimum Android API: 24 (Android 7.0)
本项目采用 Apache License 2.0 开源。详见 LICENSE 文件。
- 使用问题：请先查阅 常见问题 和 故障排查
- SDK 源码问题：请参阅 sdk-source-docs/ 相关模块文档
- 上装设备协议：由各自设备厂家定义，与机器人控制协议独立，需自行实现通信与编解码