Skip to content

Display and control your Android device

Add gamepad user documentation

Romain Vimont0ba430a462f7
diff --git a/README.md b/README.md
index 67fdf364..0d44228e 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,7 @@ Its features include:
- [camera mirroring](doc/camera.md) (Android 12+)
- [mirroring as a webcam (V4L2)](doc/v4l2.md) (Linux-only)
- physical [keyboard][hid-keyboard] and [mouse][hid-mouse] simulation (HID)
+ - [gamepad](doc/gamepad.md) support
- [OTG mode](doc/otg.md)
- and more…
@@ -111,6 +112,13 @@ Here are just some common examples.
scrcpy --otg
```
+ - Control the device using gamepad controllers plugged into the computer:
+
+ ```bash
+ scrcpy --gamepad=uhid
+ scrcpy -G # short version
+ ```
+
## User documentation
The application provides a lot of features and configuration options. They are
@@ -122,6 +130,7 @@ documented in the following pages:
- [Control](doc/control.md)
- [Keyboard](doc/keyboard.md)
- [Mouse](doc/mouse.md)
+ - [Gamepad](doc/gamepad.md)
- [Device](doc/device.md)
- [Window](doc/window.md)
- [Recording](doc/recording.md)
diff --git a/doc/gamepad.md b/doc/gamepad.md
new file mode 100644
index 00000000..f78fb828
--- /dev/null
+++ b/doc/gamepad.md
@@ -0,0 +1,53 @@
+# Gamepad
+
+Several gamepad input modes are available:
+
+ - `--gamepad=disabled` (default)
+ - `--gamepad=uhid` (or `-G`): simulates physical HID gamepads using the UHID
+ kernel module on the device
+ - `--gamepad=aoa`: simulates physical HID gamepads using the AOAv2 protocol
+
+
+## Physical gamepad simulation
+
+Two modes allow to simulate physical HID gamepads on the device, one for each
+physical gamepad plugged into the computer.
+
+
+### UHID
+
+This mode simulates physical HID gamepads using the [UHID] kernel module on the
+device.
+
+[UHID]: https://kernel.org/doc/Documentation/hid/uhid.txt
+
+To enable UHID gamepads, use:
+
+```bash
+scrcpy --gamepad=uhid
+scrcpy -G # short version
+```
+
+
+### AOA
+
+This mode simulates physical HID gamepads using the [AOAv2] protocol.
+
+[AOAv2]: https://source.android.com/devices/accessories/aoa2#hid-support
+
+To enable AOA gamepads, use:
+
+```bash
+scrcpy --gamepad=aoa
+```
+
+Contrary to the other mode, it works at the USB level directly (so it only works
+over USB).
+
+It does not use the scrcpy server, and does not require `adb` (USB debugging).
+Therefore, it is possible to control the device (but not mirror) even with USB
+debugging disabled (see [OTG](otg.md)).
+
+Note: On Windows, it may only work in [OTG mode](otg.md), not while mirroring
+(it is not possible to open a USB device if it is already open by another
+process like the _adb daemon_).
diff --git a/doc/otg.md b/doc/otg.md
index 93002f14..7d31c0a7 100644
--- a/doc/otg.md
+++ b/doc/otg.md
@@ -9,13 +9,15 @@ device (see [keyboard](keyboard.md) and [mouse](mouse.md)).
[physical mouse]: mouse.md#physical-mouse-simulation
A special mode (OTG) allows to control the device using AOA
-[keyboard](keyboard.md#aoa) and [mouse](mouse.md#aoa), without using _adb_ at
-all (so USB debugging is not necessary). In this mode, video and audio are
-disabled, and `--keyboard=aoa and `--mouse=aoa` are implicitly set.
+[keyboard](keyboard.md#aoa), [mouse](mouse.md#aoa) and
+[gamepad](gamepad.md#aoa), without using _adb_ at all (so USB debugging is not
+necessary). In this mode, video and audio are disabled, and `--keyboard=aoa` and
+`--mouse=aoa` are implicitly set. However, gamepads are disabled by default, so
+`--gamepad=aoa` (or `-G` in OTG mode) must be explicitly set.
-Therefore, it is possible to run _scrcpy_ with only physical keyboard and mouse
-simulation, as if the computer keyboard and mouse were plugged directly to the
-device via an OTG cable.
+Therefore, it is possible to run _scrcpy_ with only physical keyboard, mouse and
+gamepad simulation, as if the computer keyboard, mouse and gamepads were plugged
+directly to the device via an OTG cable.
To enable OTG mode:
@@ -32,6 +34,13 @@ scrcpy --otg --keyboard=disabled
scrcpy --otg --mouse=disabled
```
+and to enable gamepads:
+
+```bash
+scrcpy --otg --gamepad=aoa
+scrcpy --otg -G # short version
+```
+
It only works if the device is connected over USB.
## OTG issues on Windows
@@ -50,9 +59,9 @@ is enabled, then OTG mode is not necessary.
Instead, disable video and audio, and select UHID (or AOA):
```bash
-scrcpy --no-video --no-audio --keyboard=uhid --mouse=uhid
-scrcpy --no-video --no-audio -KM # short version
-scrcpy --no-video --no-audio --keyboard=aoa --mouse=aoa
+scrcpy --no-video --no-audio --keyboard=uhid --mouse=uhid --gamepad=uhid
+scrcpy --no-video --no-audio -KMG # short version
+scrcpy --no-video --no-audio --keyboard=aoa --mouse=aoa --gamepad=aoa
```
One benefit of UHID is that it also works wirelessly.