Overview

---

The Gamepad SDK is a gamepad event listener library based on UDP communication, responsible for receiving gamepad operation data broadcast by the mobile App via UDP. Developers can use this SDK to obtain physical button trigger information and joystick values in real time for robot remote control scenarios.

Functional Positioning

The Gamepad SDK serves as the user input layer in the Lite3 development ecosystem, with the following responsibilities:

• Receiving button and joystick data from the gamepad App via UDP
• Parsing protocol frames (frame header, device ID, CRC16 checksum)
• Converting raw data into structured button states and normalized joystick values
• Supporting both Retroid (Lite3) and Skydroid gamepads

Upper-layer applications (e.g., lite3_transfer) reference the Gamepad SDK to obtain user gamepad input and publish it to ROS2 topics.

Supported Gamepads

Retroid Gamepad

Project Directory Structure

gamepad/
├── include/
│   ├── gamepad.h            # Gamepad template base class
│   ├── gamepad_keys.h       # Button/joystick data type definitions and protocol frame structure
│   ├── retroid_gamepad.h    # Retroid gamepad subclass interface
│   ├── skydroid_gamepad.h   # Skydroid gamepad subclass interface
│   └── udp_receiver.h       # UDP receiver
├── src/
│   ├── gamepad.cpp           # Gamepad base class implementation
│   ├── retroid_gamepad.cpp   # Retroid gamepad data parsing implementation
│   ├── skydroid_gamepad.cpp  # Skydroid gamepad data parsing implementation
│   └── udp_receiver.cpp      # UDP receiver implementation
├── example/
│   ├── fmt/                  # fmt formatting library (git submodule)
│   ├── example_retroid.cpp   # Retroid gamepad example program
│   ├── example_skydroid.cpp  # Skydroid gamepad example program
│   └── CMakeLists.txt        # Example build configuration
├── doc/                      # Documentation images
├── CMakeLists.txt            # Build configuration
├── LICENSE
└── controlapp.apk            # Mobile gamepad App

Communication Principle

The Gamepad SDK uses a UDP unidirectional receive model, where the mobile App acts as the sender and the SDK host acts as the receiver:

graph LR
    A["Gamepad App (Mobile)"] -->|"UDP Broadcast"| B["SDK (Development Host)"]

Direction	Port	Description
App → SDK	12121 (default, customizable)	App broadcasts gamepad data to this port

Protocol Frame Format

Each UDP data packet sent by the gamepad App follows a unified frame format:

Field	Size	Description
stx	2 bytes	Frame header, fixed at 0x55 0x66
ctrl	1 byte	Control byte
data_len	2 bytes	Data area length
seq	2 bytes	Sequence number for packet loss detection
id	1 byte	Device ID: 1 = Retroid, 2 = Skydroid
crc16	2 bytes	CRC-16 checksum (data area accumulation)
data	Variable	Button + joystick raw data

Data Verification

The SDK performs three-level verification on each received data packet:

1. Frame header verification: Check stx[0] == 0x55 and stx[1] == 0x66
2. Device ID verification: Check if the id field matches the target gamepad type
3. CRC-16 verification: Accumulate bytes in the data area and compare with the crc16 field

Only data packets that pass all three levels of verification are parsed as valid button data.

Code Resources

Resource	Description
gamepad	Gamepad SDK repository