# m20-android-sdk

**Repository Path**: codepool_admin/m20-android-sdk

## Basic Information

- **Project Name**: m20-android-sdk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-01
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# M20_APP_SDK

本项目是面向行业开发者与生态合作伙伴交付的 **山猫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 框架上修改迭代自己的业务功能。

---

## SDK 架构简介

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/](./docs/sdk-docs/) |
| **SDK 开发者** | 修改、编译、打包 SDK 源码，理解内部架构，扩展协议或通信层 | 📗 [sdk-source-docs/](./docs/sdk-source-docs/) |

---

## 路径一：App 开发者（集成 SDK 开发应用）

如果你希望：
- 快速将机器人遥控能力集成到自己的 Android 项目中
- 基于 SimpleDemo 的 UI 框架进行二次开发
- 从源码编译 AAR 后集成到你的 App 项目中

**推荐阅读顺序**：

1. [RobotSDK 集成指南](./docs/sdk-docs/robot-sdk-integration.md) — 环境要求、AAR 编译与 Gradle 集成、初始化、状态监听、遥控指令、生命周期管理
2. [RobotSDK API 参考](./docs/sdk-docs/robot-sdk-api-reference.md) — 完整 API 说明，含可直接 Copy 的代码片段、状态判断速查、异常处理
3. [RobotSDK 协议自定义扩展](./docs/sdk-docs/robot-sdk-protocol-extension.md) — 如何发送/接收自定义协议指令（如上装补光灯控制）
4. [ControllerSDK 集成指南](./docs/sdk-docs/controller-sdk-integration.md) — 云卓 G20 手柄接入（仅限山猫 M20 标配手柄）
5. [ControllerSDK API 参考](./docs/sdk-docs/controller-sdk-api-reference.md) — 手柄接入 SDK 的完整 API 说明
6. [SimpleDemo 指南](./docs/sdk-docs/simpledemo-guide.md) — 功能特性、代码结构、运行步骤、自定义开发场景
7. [常见问题](./docs/sdk-docs/faq.md) / [故障排查](./docs/sdk-docs/troubleshooting.md) — 快速排错

---

## 路径二：SDK 开发者（修改源码）

如果你希望：
- 修改 SDK 内部协议、通信或业务逻辑
- 从源码编译出 AAR 包
- 理解四层架构设计（Protocol → Communication → Business → Application）
- 扩展新的通信方式或协议字段

**推荐阅读顺序**：

1. [RobotSDK 构建指南](./docs/sdk-source-docs/robot-sdk-build-guide.md) — 源码编译、Fat AAR 打包、本地/远程依赖切换
2. [ControllerSDK 构建指南](./docs/sdk-source-docs/controller-sdk-build-guide.md) — 源码编译、rcsdk 依赖获取
3. [RobotSDK 架构设计](./docs/sdk-source-docs/robot-sdk-architecture.md) — 协议层、通信层、业务层架构，各模块职责与扩展点
4. [ControllerSDK 架构设计](./docs/sdk-source-docs/controller-sdk-architecture.md) — 手柄层架构、核心类、归一化与死区机制、rcsdk 外部依赖
5. [异常系统技术文档](./docs/sdk-source-docs/robot-error-system.md) — 异常上报数据流、枚举匹配机制、UI 展示文本解析链、国际化注意事项
6. [更新日志](./docs/sdk-source-docs/changelog.md) — 版本迭代记录

---

## 技术栈

- Language: Kotlin
- Build Tool: Gradle + Android Gradle Plugin
- Communication: UDP / JSON
- Protocol: [机器人控制协议文档](https://alidocs.dingtalk.com/i/p/OlnXRl7ed542DGLp/docs/qnYMoO1rWxDL7r6LHbad2kA9W47Z3je9)
- Minimum Android API: 24 (Android 7.0)

---

## 开源许可

本项目采用 **Apache License 2.0** 开源。详见 [LICENSE](./LICENSE) 文件。

---

## 支持与反馈

- 使用问题：请先查阅 [常见问题](./docs/sdk-docs/faq.md) 和 [故障排查](./docs/sdk-docs/troubleshooting.md)
- SDK 源码问题：请参阅 [sdk-source-docs/](./docs/sdk-source-docs/) 相关模块文档
- 上装设备协议：由各自设备厂家定义，与机器人控制协议独立，需自行实现通信与编解码