diff --git a/README.md b/README.md index 67fdf364db..0d44228e59 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 0000000000..f78fb8283a --- /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 93002f1466..7d31c0a75f 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.