uj947nxmrqv2nrawshkthztvckuupd / ethernally

Your scrcpy companion for Android wireless screen mirroring

ethernally

Your scrcpy companion for Android wireless screen mirroring

Features

• Mirrors your screen wirelessly with scrcpy
• New! Support for non-rooted devices
• New! Supports Android 14
• Automatically adds Wi-Fi adb connection capability at boot [root only]
• Connects through adb via Wi-Fi or USB cable
• Remembers last known working Wi-Fi IP for fast connection
• Works even when authorization was revoked due to expiration (Android 11)
• Drops you to a wireless shell on the device
• Works in Linux and in Windows via cygwin or WSL (Windows Subsystem for Linux)
• Tackles all scenarios that could get you into issues. It even finds a way when Wi-Fi is turned off!
• POSIX compatible

Requirements

• scrpy must be installed or set to system PATH (clone from: https://github.com/Genymobile/scrcpy)
• To permanently set Android props to allow Wi-Fi adb connections at all times, it is required to have the device rooted (you can use magisk).
• You need an USB cable for first time setup and eventually later for fixing other potential connectivity issues - in USB debugging mode. If the tool asks for it, just plug it between your device and your PC while having USB debugging enabled.
• To unlock the hidden Developer tools/options menu, go to Android Settings > About > Press on 'build number' 7 times. Then go to android settings > developer tools/options and enable USB debugging
• Also, under developer tools -> default USB configuration -> set to 'No data transfer' (Genymobile/scrcpy#597)
• Note: perl is required (should be installed by default on most linux systems, but needs to be installed if using cygwin)
• Warning: live wallpapers might decrease mirroring performance
• Warning: lock screen and app lock will show black in the mirrored screen (Android 12+) (Genymobile/scrcpy#3413)
• Warning: if you encounter any bug, it might be actually related to scrcpy rather than ethernally
• Warning: if device gets locked, connection might be killed (Genymobile/scrcpy#3334)

How To Run

• On first time attempt, you should turn on 'disable adb authorization timeout' under android developer settings. This disables automatic revocation of adb authorizations for systems that have not reconnected within the default (7 days) or user-configured (minimum 1 day) amount of time. However this could lower the security of your device!
• To launch ethernally, simply run the script from its folder (cd ethernally) and follow the intuitive wizard guide

chmod +x ethernally.sh # make the script executable (run only once)
dos2unix ethernally.sh # situational: might be needed to convert line endings to unix format (eg. when using Github for Desktop) (run only once)
./ethernally.sh

• Note: Wireless debugging is not needed to be enabled under developer options
• On first time attempt, USB cable will be required and you must set cable in transfer mode to enable debug mode. Afterwards, authorize the device and check the box to remember
• You could also add ethernally folder to system path (linux) or to the environment variable PATH (windows), and call it from terminal (eg. ethernally.sh)
• Alternatively, you could create a symlink in your preferred location (eg. on your Linux Desktop)
• You could even add a shortcut on Windows (cygwin) to launch screen mirroring upon execution. To do that, set shortcut's target similar to this:

C:\cygwin\bin\mintty.exe /usr/bin/bash --login "/cygdrive/c/GitHub/ethernally/ethernally.sh"

• See also scrcpy shortcuts (using ALT key) to manage your mirrored device: https://github.com/Genymobile/scrcpy/blob/master/doc/shortcuts.md

USEFUL ACTION SHORTCUTS
#MOD = alt key
HOME	MOD+h | Middle-click
BACK	MOD+b | Right-click²
APP_SWITCH	MOD+s
Switch fullscreen mode	MOD+f
Rotate device screen	MOD+r
Turn device screen off (keep mirroring)	MOD+o
Turn device screen on	MOD+Shift+o
Power on	Right-click (if previously locked)
POWER BUTTON	MOD+p (aka lock/unlock OR long press for power menu OR very long press for power off)
Click on VOLUME_UP	MOD+↑ (up)
Click on VOLUME_DOWN	MOD+↓ (down)
Resize window to remove black borders	MOD+w

How To Update

• To update the script, simply pull latest changes from the git repository:

git pull

• Alternatively you could just copy/paste the code into your script or download it again (eg. with wget)

Feel free to contribute

ethernally's Issues

sndcpy integration

integrate with sndcy to forward sound

remote via android hotspot possibility ?

Hey can we make scrcpy work via android shared wifi/hotspot ??

android phone >> share wifi/hotspot >> pc connected to that wifi

everytime I connect to gateway always got refused (expected), I wonder if we can root and install magisk module to allow adb debug over hotspot

Super Fast Startup

should attempt straight mirroring first and only if it fails the extra logic should be taken in consideration

right now, it does some prechecks before mirroring even if the device is already ready for it

Fails to mirror if device was not unauthorized

TBD .. the circumstances when this bug occurs

LOG BELOW:

Attempting to discover any attached devices..

• daemon not running; starting now at tcp:5037
• daemon started successfully
  List of devices attached

Disconnecting adb and killing adb server..
There are no WiFi devices automatically detected/attached - as reported by ADB.

Trying last known working device..
Last known working socket: :

• daemon not running; starting now at tcp:5037
• daemon started successfully
  Connected via ADB to last known WiFi device:
  :
  Manufacturer:
  Android Version:
  SDK Version:
  Product Name:
  Model:

socket: :
connected: 1

Checking root..
adb.exe: device unauthorized.
This adb server's $ADB_VENDOR_KEYS is not set
Try 'adb kill-server' if that seems wrong.
Otherwise check for a confirmation dialog on your device.
Your device needs to be rooted for allowing permanent WiFi connectivity through ADB
Device not rooted. Will skip setting permanent props to allow WiFi connectivity through ADB unnatended

adb.exe: device unauthorized.
This adb server's $ADB_VENDOR_KEYS is not set
Try 'adb kill-server' if that seems wrong.
Otherwise check for a confirmation dialog on your device.
adb.exe: device unauthorized.
This adb server's $ADB_VENDOR_KEYS is not set
Try 'adb kill-server' if that seems wrong.
Otherwise check for a confirmation dialog on your device.
adb.exe: device unauthorized.
This adb server's $ADB_VENDOR_KEYS is not set
Try 'adb kill-server' if that seems wrong.
Otherwise check for a confirmation dialog on your device.
adb.exe: device unauthorized.
This adb server's $ADB_VENDOR_KEYS is not set
Try 'adb kill-server' if that seems wrong.
Otherwise check for a confirmation dialog on your device.
adb.exe: device unauthorized.
This adb server's $ADB_VENDOR_KEYS is not set
Try 'adb kill-server' if that seems wrong.
Otherwise check for a confirmation dialog on your device.

stay awake error when connecting

[server] ERROR: Could not change "stay_on_while_plugged_in"
com.genymobile.scrcpy.SettingsException: Could not access settings: put global stay_on_while_plugged_in 7
at com.genymobile.scrcpy.Settings.execSettingsPut(Settings.java:24)
at com.genymobile.scrcpy.Settings.putValue(Settings.java:59)
at com.genymobile.scrcpy.Settings.getAndPutValue(Settings.java:78)
at com.genymobile.scrcpy.Server.initAndCleanUp(Server.java:63)
at com.genymobile.scrcpy.Server.lambda$startInitThread$2(Server.java:168)
at com.genymobile.scrcpy.Server$$ExternalSyntheticLambda3.run(Unknown Source:2)
at java.lang.Thread.run(Thread.java:920)
Caused by: java.io.IOException: Command [settings, put, global, stay_on_while_plugged_in, 7] returned with value 255
at com.genymobile.scrcpy.Command.exec(Command.java:16)
at com.genymobile.scrcpy.Settings.execSettingsPut(Settings.java:22)
... 6 more

perl dependency

cygwin for example does not have perl by default

Device selection

allow device selection at script start (if multiple were saved as working devices) . This implies saving all the working devices, besides the last working one.

Auto reconnect

if connection dropped/ phone reboooting, then wait for reconnection

setup ADB

Automatically install/download adb in case it is missing.
Might require user confirmation.

EDIT: scrcpy comes with it's own copy of adb. could use that one

adb connect returns "no route to host"

Describe the bug
Hi, I tried your script as I was having trouble at the 'adb connect IP:5555' stage of connecting scrcpy wirelessly (I was receiving error message "no route to host"). Your script didn't work for me, but I'm hoping you might be able to decipher the error message I've received and be able to tell me what the issue might be on my end?

To Reproduce
Steps to reproduce the behavior:
'./ethernally.sh'

Expected behavior
Was expecting/hoping scrcpy would open and I could disconnect USB.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: Linux
• Version Ubuntu 20.04.5 LTS

Smartphone (please complete the following information):

• Device: Onyx NoteAir 2
• OS: Android
• Version 10

Additional context
Here is the full log I receive in the terminal after executing the script

$ ./ethernally.sh
Running script from /opt/ethernally
touch: cannot touch '/opt/ethernally/last_working_device.conf': Permission denied
./ethernally.sh: 29: cannot create /opt/ethernally/debug.log: Permission denied
Attempting to discover any attached devices..
List of devices attached
B6B0D475 device usb:3-2 product:NoteAir model:NoteAir device:NoteAir transport_id:3

Disconnecting adb devices..
DEBUG> killing adb server..
There are no WiFi devices automatically detected/attached - as reported by ADB.
connected: false

Trying last known working device. Please have patience... (max 1 minute)
There is no last known working device.
./ethernally.sh: 462: cannot create /opt/ethernally/debug.log: Permission denied

socket: null
connected: 0

Wi-Fi seems to be turned off or ADB debugging not enabled on device.
Could not connect via WiFi, switching to USB mode

!!! READ CAREFULLY !!!

1. Please plug USB cable and enable USB debugging (To unlock the hidden Developer tools/options menu, go to Android Settings > About > Press on 'build number' 7 times. Then go to android settings > developer tools/options and enable 'USB debugging')

2. You should also check 'Disable adb authorization timeout' so that the adb authorization for systems that have not reconnected within the default (7days) is not revoked, thus to be able to reconnect in the future without interaction.

3. If asked, allow USB debugging on your Android device by allowing your computer's RSA key fingerprint. Also check the 'Always allow from this computer' checkbox to allow future connections

Checking if USB cable is connected and USB debugging enabled and authorized..
......
DEBUG> killing adb server..
restarting in USB mode

device(s) connected via USB cable: NoteAir
usb_device_serial: B6B0D475

Checking root..
/system/bin/sh: su: inaccessible or not found
Your device needs to be rooted for allowing permanent WiFi connectivity through ADB
./ethernally.sh: 100: cannot create /opt/ethernally/debug.log: Permission denied
Device is not rooted. Moving on..
restarting in TCP mode port: 5555
Attempting to start Wi-Fi on the device..
new socket: 10.248.24.86:5555
./ethernally.sh: 218: cannot create /opt/ethernally/debug.log: Permission denied
Connecting via wifi..
unable to connect to 10.248.24.86:5555: No route to host
connected: true
./ethernally.sh: 127: cannot create /opt/ethernally/last_working_device.conf: Permission denied
error: device '10.248.24.86:5555' not found
./ethernally.sh: 130: cannot create /opt/ethernally/last_working_device.conf: Permission denied
error: device '10.248.24.86:5555' not found
./ethernally.sh: 134: cannot create /opt/ethernally/last_working_device.conf: Permission denied
error: device '10.248.24.86:5555' not found
./ethernally.sh: 138: cannot create /opt/ethernally/last_working_device.conf: Permission denied
error: device '10.248.24.86:5555' not found
./ethernally.sh: 142: cannot create /opt/ethernally/last_working_device.conf: Permission denied
error: device '10.248.24.86:5555' not found
./ethernally.sh: 146: cannot create /opt/ethernally/last_working_device.conf: Permission denied
Device ready!

./ethernally.sh: 250: cannot create /opt/ethernally/debug.log: Permission denied
./ethernally.sh: 127: cannot create /opt/ethernally/last_working_device.conf: Permission denied
error: device '10.248.24.86:5555' not found
./ethernally.sh: 130: cannot create /opt/ethernally/last_working_device.conf: Permission denied
error: device '10.248.24.86:5555' not found
./ethernally.sh: 134: cannot create /opt/ethernally/last_working_device.conf: Permission denied
error: device '10.248.24.86:5555' not found
./ethernally.sh: 138: cannot create /opt/ethernally/last_working_device.conf: Permission denied
error: device '10.248.24.86:5555' not found
./ethernally.sh: 142: cannot create /opt/ethernally/last_working_device.conf: Permission denied
error: device '10.248.24.86:5555' not found
./ethernally.sh: 146: cannot create /opt/ethernally/last_working_device.conf: Permission denied

Connect wirelessly [non-root]

I still can't connect to wifi

POSIX migration

-lint code via github actions
-posix compatible

Auto setup scrcpy

Give an option to setup scrcpy:

Eg. ethernally --setup (-s) OR ethernally --install (-i)

This will:

install/download scrcpy
set to env PATH (windows env vars)
option to update scrcpy : ethernally --update (-u) . This involves comparing already installed version with official one

Setup should automatically attempt to run on first use, giving user option to skip it (if already installed). (Could try automatically detect scrcpy location and only try to download a portable version in case it is missing.)

Note: for Windows, exe binaries must be downloaded instead (for using with cygwin)

This involves detecting host OS and saving the installation state to a config file.

Option to disable live wallpaper

Live wallpaper slows screen mirroring. Give an option to disable it.
Related to #3

Updater

--update = for updating the script via cli
--updateall = for updating scrcpy, adb and sndcpy

Configure scrcpy options

Interactive menu:

1. a configuration menu for setting different scrcpy parametrs. eg. resolution, screen off, fps, bit rate
2. save this configuration
3. allow reconfigure
4. reset to default values

Called with:

ethernally.sh --reconfigure (-r) OR --configure

This involves saving the configuration parameters to a config file.