概述

---

Gamepad SDK 是一个基于 UDP 通信的手柄事件监听库，负责接收手机端 App 通过 UDP 广播的手柄操作数据。开发者可以通过该 SDK 实时获取物理按键触发信息和摇杆数值，用于机器人遥控等场景。

功能定位

Gamepad SDK 在整个 Lite3 开发生态中处于用户输入层，其职责包括：

• 通过 UDP 接收手柄 App 上报的按键和摇杆数据
• 解析协议帧（帧头、设备 ID、CRC16 校验）
• 将原始数据转换为结构化的按键状态和摇杆归一化数值
• 支持 Retroid（Lite3）和 Skydroid 两款手柄

上层应用（如 lite3_transfer）通过引用 Gamepad SDK 获取用户手柄输入，再发布到 ROS2 话题。

支持的手柄

Retroid 手柄

项目目录结构

gamepad/
├── include/
│   ├── gamepad.h            # 手柄模板基类
│   ├── gamepad_keys.h       # 按键/摇杆数据类型定义与协议帧结构
│   ├── retroid_gamepad.h    # Retroid 手柄子类接口
│   ├── skydroid_gamepad.h   # Skydroid 手柄子类接口
│   └── udp_receiver.h       # UDP 接收器
├── src/
│   ├── gamepad.cpp           # 手柄基类实现
│   ├── retroid_gamepad.cpp   # Retroid 手柄数据解析实现
│   ├── skydroid_gamepad.cpp  # Skydroid 手柄数据解析实现
│   └── udp_receiver.cpp      # UDP 接收器实现
├── example/
│   ├── fmt/                  # fmt 格式化库（git submodule）
│   ├── example_retroid.cpp   # Retroid 手柄示例程序
│   ├── example_skydroid.cpp  # Skydroid 手柄示例程序
│   └── CMakeLists.txt        # 示例编译配置
├── doc/                      # 文档图片
├── CMakeLists.txt            # 编译配置
├── LICENSE
└── controlapp.apk            # 手机端手柄 App

通信原理

Gamepad SDK 采用 UDP 单向接收模式，手机端 App 作为发送方，SDK 所在主机作为接收方：

graph LR
    A["手柄 App (手机端)"] -->|"UDP 广播"| B["SDK (开发主机)"]

方向	端口	说明
App → SDK	12121（默认，可自定义）	App 向此端口广播手柄数据

协议帧格式

手柄 App 发送的每个 UDP 数据包遵循统一的帧格式：

字段	大小	说明
stx	2 字节	帧头，固定为 0x55 0x66
ctrl	1 字节	控制字节
data_len	2 字节	数据区长度
seq	2 字节	序列号，用于丢包检测
id	1 字节	设备 ID：1 = Retroid，2 = Skydroid
crc16	2 字节	CRC-16 校验和（数据区累加）
data	可变	按键 + 摇杆原始数据

数据校验

SDK 对每个接收到的数据包执行三级校验：

1. 帧头校验：检查 stx[0] == 0x55 且 stx[1] == 0x66
2. 设备 ID 校验：检查 id 字段是否匹配目标手柄类型
3. CRC-16 校验：对 data 区逐字节累加，与 crc16 字段比对

只有三级校验全部通过的数据包才会被解析为有效按键数据。

代码资源

资源	说明
gamepad	Gamepad SDK 代码仓库