Display and control your Android device
Add gamepad user documentation
Romain Vimont0ba430a462f7
diff --git a/README.md b/README.mdindex 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 documentationThe 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.mdnew file mode 100644index 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.mdindex 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-simulationA 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=disabledscrcpy --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.