adb-shell-wifi 0.5.0

Fork of adb-shell with ADB Wi-Fi (TLS) pairing, TLS transport, and mDNS discovery added.

This package is a fork of adb_shell that adds support for modern ADB Wi-Fi pairing — the 6-digit-code TLS pairing flow introduced in Android 11’s “Wireless debugging” feature, plus the post-pairing TLS data channel and mDNS-based service discovery.

It exists primarily as a testbed for verifying that Wi-Fi pairing support can be added to Home Assistant’s Android TV integration. If you do not need Wi-Fi pairing, install upstream adb-shell instead — the upstream package is the canonical home of all non-Wi-Fi functionality.

Original adb_shell documentation: https://adb-shell.readthedocs.io/

Origin

This Python package implements ADB shell and FileSync functionality. It originated from python-adb and was substantially rewritten by Jeff Irion in adb_shell; this fork adds Wi-Fi pairing on top.

Installation

pip install adb-shell-wifi

Async

To utilize the async version of this code, you must install into a Python 3.7+ environment via:

pip install adb-shell-wifi[async]

USB Support (Experimental)

To connect to a device via USB, install this package via:

pip install adb-shell-wifi[usb]

Wi-Fi Pairing Support (Experimental)

To pair with a modern Android device using a 6-digit pairing code (Android 11+ “Wireless debugging”), install this package via:

pip install adb-shell-wifi[wifi]

This pulls in spake2-cffi and pyOpenSSL. Note: spake2-cffi does not publish Windows wheels, so Windows users will need a C toolchain available at install time.

On the device, open Settings > System > Developer options > Wireless debugging > Pair device with pairing code. Note the IP address, port, and 6-digit code shown by the device, then:

from adb_shell_wifi.pairing import pair

adbkey = "path/to/adbkey"
with open(adbkey, "rb") as f:
    priv = f.read()
with open(adbkey + ".pub", "rb") as f:
    pub = f.read()

peer_info = pair(
    host="192.168.1.42",   # from device UI
    port=43811,            # from device UI
    pairing_code="515109", # from device UI
    private_key_pem=priv,
    public_key=pub,
)
print("device peer info:", peer_info.type, peer_info.data)

After pairing succeeds, the device records the host’s public key in its keystore. To actually run shell commands, push, pull, etc. over the post-pairing TLS channel, use AdbDeviceTls and pass the same adbkey PEM as tls_priv_pem:

from adb_shell_wifi.adb_device import AdbDeviceTls
from adb_shell_wifi.mdns import discover_connect_services

# Find the random port the device chose for its TLS data socket.
services = discover_connect_services(timeout_s=4.0)
svc = services[0]   # or pick the right device by name/host

device = AdbDeviceTls(svc.host, svc.port, default_transport_timeout_s=10.0)
device.connect(rsa_keys=[], tls_priv_pem=priv, auth_timeout_s=10.0)
print(device.shell("echo hello from adb_shell_wifi"))
device.close()

The mdns module also exposes discover_pairing_services() for finding devices that currently have a pairing dialog open, plus async equivalents (discover_connect_services_async, discover_pairing_services_async).

Example Usage

(Based on androidtv/adb_manager.py)

from adb_shell_wifi.adb_device import AdbDeviceTcp, AdbDeviceUsb
from adb_shell_wifi.auth.sign_pythonrsa import PythonRSASigner

# Load the public and private keys
adbkey = 'path/to/adbkey'
with open(adbkey) as f:
    priv = f.read()
with open(adbkey + '.pub') as f:
     pub = f.read()
signer = PythonRSASigner(pub, priv)

# Connect
device1 = AdbDeviceTcp('192.168.0.222', 5555, default_transport_timeout_s=9.)
device1.connect(rsa_keys=[signer], auth_timeout_s=0.1)

# Connect via USB (package must be installed via `pip install adb-shell-wifi[usb])`
device2 = AdbDeviceUsb()
device2.connect(rsa_keys=[signer], auth_timeout_s=0.1)

# Send a shell command
response1 = device1.shell('echo TEST1')
response2 = device2.shell('echo TEST2')

Generate ADB Key Files

If you need to generate a key, you can do so as follows.

from adb_shell_wifi.auth.keygen import keygen

keygen('path/to/adbkey')