Add gamepad user documentation

Mainly copied and adapted from HID keyboard and mouse documentation.

PR #5270 <https://github.com/Genymobile/scrcpy/pull/5270>
This commit is contained in:
Romain Vimont 2024-09-09 18:25:50 +02:00
parent 91d40c7548
commit 0ba430a462
3 changed files with 80 additions and 9 deletions

View File

@ -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)

53
doc/gamepad.md Normal file
View File

@ -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_).

View File

@ -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.