From 328ed3650dd8abbdb138f629b4e5aa622f172cae Mon Sep 17 00:00:00 2001 From: Romain Vimont Date: Fri, 14 Jul 2023 23:29:09 +0200 Subject: [PATCH] Extract device connection to a separate doc page Create a new "Connection" documentation page. --- README.md | 3 +- doc/connection.md | 125 +++++++++++++++++++++++++++++++++++++++++ doc/device.md | 139 ++-------------------------------------------- 3 files changed, 132 insertions(+), 135 deletions(-) create mode 100644 doc/connection.md diff --git a/README.md b/README.md index 9e49a15ddb..412c186b9c 100644 --- a/README.md +++ b/README.md @@ -68,10 +68,11 @@ mode](doc/hid-otg.md#otg). The application provides a lot of features and configuration options. They are documented in the following pages: - - [Device](doc/device.md) + - [Connection](doc/connection.md) - [Video](doc/video.md) - [Audio](doc/audio.md) - [Control](doc/control.md) + - [Device](doc/device.md) - [Window](doc/window.md) - [Recording](doc/recording.md) - [Tunnels](doc/tunnels.md) diff --git a/doc/connection.md b/doc/connection.md new file mode 100644 index 0000000000..90ced010c0 --- /dev/null +++ b/doc/connection.md @@ -0,0 +1,125 @@ +# Connection + +## Selection + +If exactly one device is connected (i.e. listed by `adb devices`), then it is +automatically selected. + +However, if there are multiple devices connected, you must specify the one to +use in one of 4 ways: + - by its serial: + ```bash + scrcpy --serial=0123456789abcdef + scrcpy -s 0123456789abcdef # short version + + # the serial is the ip:port if connected over TCP/IP (same behavior as adb) + scrcpy --serial=192.168.1.1:5555 + ``` + - the one connected over USB (if there is exactly one): + ```bash + scrcpy --select-usb + scrcpy -d # short version + ``` + - the one connected over TCP/IP (if there is exactly one): + ```bash + scrcpy --select-tcpip + scrcpy -e # short version + ``` + - a device already listening on TCP/IP (see [below](#tcpip-wireless)): + ```bash + scrcpy --tcpip=192.168.1.1:5555 + scrcpy --tcpip=192.168.1.1 # default port is 5555 + ``` + +The serial may also be provided via the environment variable `ANDROID_SERIAL` +(also used by `adb`): + +```bash +# in bash +export ANDROID_SERIAL=0123456789abcdef +scrcpy +``` + +```cmd +:: in cmd +set ANDROID_SERIAL=0123456789abcdef +scrcpy +``` + +```powershell +# in PowerShell +$env:ANDROID_SERIAL = '0123456789abcdef' +scrcpy +``` + + +## TCP/IP (wireless) + +_Scrcpy_ uses `adb` to communicate with the device, and `adb` can [connect] to a +device over TCP/IP. The device must be connected on the same network as the +computer. + +[connect]: https://developer.android.com/studio/command-line/adb.html#wireless + + +### Automatic + +An option `--tcpip` allows to configure the connection automatically. There are +two variants. + +If the device (accessible at 192.168.1.1 in this example) already listens on a +port (typically 5555) for incoming _adb_ connections, then run: + +```bash +scrcpy --tcpip=192.168.1.1 # default port is 5555 +scrcpy --tcpip=192.168.1.1:5555 +``` + +If _adb_ TCP/IP mode is disabled on the device (or if you don't know the IP +address), connect the device over USB, then run: + +```bash +scrcpy --tcpip # without arguments +``` + +It will automatically find the device IP address and adb port, enable TCP/IP +mode if necessary, then connect to the device before starting. + + +### Manual + +Alternatively, it is possible to enable the TCP/IP connection manually using +`adb`: + +1. Plug the device into a USB port on your computer. +2. Connect the device to the same Wi-Fi network as your computer. +3. Get your device IP address, in Settings → About phone → Status, or by + executing this command: + + ```bash + adb shell ip route | awk '{print $9}' + ``` + +4. Enable `adb` over TCP/IP on your device: `adb tcpip 5555`. +5. Unplug your device. +6. Connect to your device: `adb connect DEVICE_IP:5555` _(replace `DEVICE_IP` +with the device IP address you found)_. +7. Run `scrcpy` as usual. +8. Run `adb disconnect` once you're done. + +Since Android 11, a [wireless debugging option][adb-wireless] allows to bypass +having to physically connect your device directly to your computer. + +[adb-wireless]: https://developer.android.com/studio/command-line/adb#wireless-android11-command-line + + +## Autostart + +A small tool (by the scrcpy author) allows to run arbitrary commands whenever a +new Android device is connected: [AutoAdb]. It can be used to start scrcpy: + +```bash +autoadb scrcpy -s '{}' +``` + +[AutoAdb]: https://github.com/rom1v/autoadb diff --git a/doc/device.md b/doc/device.md index 32b5ebc11a..988ad4175a 100644 --- a/doc/device.md +++ b/doc/device.md @@ -1,137 +1,9 @@ # Device -## Selection - -If exactly one device is connected (i.e. listed by `adb devices`), then it is -automatically selected. - -However, if there are multiple devices connected, you must specify the one to -use in one of 4 ways: - - by its serial: - ```bash - scrcpy --serial=0123456789abcdef - scrcpy -s 0123456789abcdef # short version - - # the serial is the ip:port if connected over TCP/IP (same behavior as adb) - scrcpy --serial=192.168.1.1:5555 - ``` - - the one connected over USB (if there is exactly one): - ```bash - scrcpy --select-usb - scrcpy -d # short version - ``` - - the one connected over TCP/IP (if there is exactly one): - ```bash - scrcpy --select-tcpip - scrcpy -e # short version - ``` - - a device already listening on TCP/IP (see [below](#tcpip-wireless)): - ```bash - scrcpy --tcpip=192.168.1.1:5555 - scrcpy --tcpip=192.168.1.1 # default port is 5555 - ``` - -The serial may also be provided via the environment variable `ANDROID_SERIAL` -(also used by `adb`): - -```bash -# in bash -export ANDROID_SERIAL=0123456789abcdef -scrcpy -``` - -```cmd -:: in cmd -set ANDROID_SERIAL=0123456789abcdef -scrcpy -``` - -```powershell -# in PowerShell -$env:ANDROID_SERIAL = '0123456789abcdef' -scrcpy -``` - - -## TCP/IP (wireless) - -_Scrcpy_ uses `adb` to communicate with the device, and `adb` can [connect] to a -device over TCP/IP. The device must be connected on the same network as the -computer. - -[connect]: https://developer.android.com/studio/command-line/adb.html#wireless - - -### Automatic - -An option `--tcpip` allows to configure the connection automatically. There are -two variants. - -If the device (accessible at 192.168.1.1 in this example) already listens on a -port (typically 5555) for incoming _adb_ connections, then run: - -```bash -scrcpy --tcpip=192.168.1.1 # default port is 5555 -scrcpy --tcpip=192.168.1.1:5555 -``` - -If _adb_ TCP/IP mode is disabled on the device (or if you don't know the IP -address), connect the device over USB, then run: - -```bash -scrcpy --tcpip # without arguments -``` - -It will automatically find the device IP address and adb port, enable TCP/IP -mode if necessary, then connect to the device before starting. - - -### Manual - -Alternatively, it is possible to enable the TCP/IP connection manually using -`adb`: - -1. Plug the device into a USB port on your computer. -2. Connect the device to the same Wi-Fi network as your computer. -3. Get your device IP address, in Settings → About phone → Status, or by - executing this command: - - ```bash - adb shell ip route | awk '{print $9}' - ``` - -4. Enable `adb` over TCP/IP on your device: `adb tcpip 5555`. -5. Unplug your device. -6. Connect to your device: `adb connect DEVICE_IP:5555` _(replace `DEVICE_IP` -with the device IP address you found)_. -7. Run `scrcpy` as usual. -8. Run `adb disconnect` once you're done. - -Since Android 11, a [wireless debugging option][adb-wireless] allows to bypass -having to physically connect your device directly to your computer. - -[adb-wireless]: https://developer.android.com/studio/command-line/adb#wireless-android11-command-line - - -## Autostart - -A small tool (by the scrcpy author) allows to run arbitrary commands whenever a -new Android device is connected: [AutoAdb]. It can be used to start scrcpy: - -```bash -autoadb scrcpy -s '{}' -``` - -[AutoAdb]: https://github.com/rom1v/autoadb - - -## Actions - Some command line arguments perform actions on the device itself while scrcpy is running. - -### Stay awake +## Stay awake To prevent the device from sleeping after a delay **when the device is plugged in**: @@ -147,7 +19,7 @@ If the device is not plugged in (i.e. only connected over TCP/IP), `--stay-awake` has no effect (this is the Android behavior). -### Turn screen off +## Turn screen off It is possible to turn the device screen off while mirroring on start with a command-line option: @@ -175,7 +47,7 @@ scrcpy -Sw # short version ``` -### Show touches +## Show touches For presentations, it may be useful to show physical touches (on the physical device). Android exposes this feature in _Developers options_. @@ -191,7 +63,7 @@ scrcpy -t # short version Note that it only shows _physical_ touches (by a finger on the device). -### Power off on close +## Power off on close To turn the device screen off when closing _scrcpy_: @@ -199,11 +71,10 @@ To turn the device screen off when closing _scrcpy_: scrcpy --power-off-on-close ``` -### Power on on start +## Power on on start By default, on start, the device is powered on. To prevent this behavior: ```bash scrcpy --no-power-on ``` -