This repository contains the server code for hosting an integration driver that uses ADB for communication for the Unfolded Circle Remotes, Linux, macOS, Windows and Docker Images. It exposes a Media Player Entity, Remote Entity as well as a Select Entity for quickly launching apps. The integration is compatible with any device that allows ADB over a network.
Tested on Panasonic Z95B
- The integration relies on ADB (Android Debug Bridge) to communicate with the device. This is useful for devices that don't expose other APIs. The downside is that this protocol is very slow, as such, you should use Bluetooth for as many commands as possible.
- Reauthorization of the ADB connection is required when reinstalling the integration when it is hosted
on the remote. This is because the private key is removed when the integration is uninstalled. You can avoid having to reauthorize by restoring the config during the setup process, or ticking the
Update installed integrationoption. - Wireless-debugging pairing (Android 11+, see below) has been validated against Android Emulator — pairing, connecting, and controlling a "real" device have all succeeded in testing. On macOS specifically, pairing works but the subsequent connection does not: the wireless-debug connect service requires TLS 1.3, and .NET's
SslStreamclient cannot negotiate TLS 1.3 on macOS for a mutual-TLS/client-certificate connection regardless of configuration (an OS-level limitation, not something this driver can work around — see the SharpAdb README for the full explanation). Use Linux or Windows for the actual connection; macOS can still be used to perform the pairing step itself. This limitation does not apply to the standard IP/Developer Settings flow on any platform.
- IP and MAC address of the device you want to control.
- Developer Settings enabled on the device you want to control. This is usually done by taping 7 times on your device name. Please search for device specific instructions on how to enable Developer Settings.
- The published binaries are self-contained and doesn't require any additional software.
- Use the Docker Image.
- Other Operating Systems - Linux, macOS, Windows - are supported. Exception: connecting to a wirelessly-paired device (Android 11+ pairing flow below) does not work on macOS — see Limitations.
| Service | Port | Protocol | Location |
|---|---|---|---|
| Server | 9001 * | HTTP (TCP) | Remote/other computer |
| ADB | 5555** | TCP | Device to control |
| ADB pairing | Shown on-device*** | TCP | Device to control |
| ADB (wireless debugging) | Dynamic/ephemeral*** | TCP | Device to control |
| mDNS | 5353 | UDP | LAN (multicast) |
| Wake on Lan | 7 and 9 | UDP | Device to control |
* Server port can be adjusted by specifying the desired port with the UC_INTEGRATION_HTTP_PORT environment variable. Port can't be controlled when running on the remote.
** ADB port can be adjusted during configuration, but only applies to the standard IP/Developer Settings flow.
*** If pairing via wireless debugging (see below): the pairing port is shown on the device's pairing screen and is only used once, during initial setup. The port entered during configuration is not used with wireless debugging — after pairing, the integration resolves the real, dynamic ADB port via mDNS before every connection, and that port changes across reboots/toggles of wireless debugging. If you have a firewall between the integration and the device, it must allow the device's full ephemeral port range, not a single fixed port. mDNS (5353/UDP) is only needed for this path — not used at all with the standard IP/Developer Settings flow.
Instead of enabling USB/network debugging and approving the on-device prompt, you can pair via Developer Options → Wireless debugging → "Pair device with pairing code": enter the 6-digit code and the pairing port shown on that screen into the corresponding optional fields during setup. The ADB port field is ignored for this flow. On success, the integration remembers the device's pairing ID and, from then on, resolves its current ADB port automatically via mDNS before each connection — that port is dynamic (it changes across reboots and each time wireless debugging is toggled), so no port needs to be kept up to date manually, but any firewall between the integration and the device must allow its ephemeral port range rather than a single fixed port.
As noted under Limitations, this path has been validated against an Android Emulator, but is not supported on macOS for the connection step itself (pairing works fine there).
The integration lists the apps installed on the device (third-party apps from pm list packages -3).
The list is shown in two places:
- The App select entity (Select Entity). Add it to a page or activity to choose an app from a dropdown. It supports select option, first, last, next and previous.
- The source list of the Media Player entity.
Select an option to start the app on the device.
- Apps are shown with their application name, for example
YouTube, and not with the package name, for examplecom.google.android.youtube.tv. - The application names are read from the device with a small helper that is uploaded to the device on first use. Until the names are ready, or if the helper fails, the package name is shown instead.
- The list is loaded when the device is on.
- Select option accepts the application name, the package name or
Application name (package.name). - Apps that are not in the list can be started with the
APP:command, see below.
You can send any input keyevent command with the remote entity if it's added to an activity.
A list of commands can be found in the official docs at Android KeyEvent
and here. Make sure to only use the digits in the commands.
You can send any adb shell command with the integration. Use the following prefixes to send commands:
RAW:YOUR_COMMAND- Sends the command as is, without any modifications.APP:YOUR_COMMAND- Starts an application by sendingshell monkey --pct-syskeys 0 -p {YOUR_COMMAND} 1.ACT:YOUR_COMMAND- Starts an activity by sendingshell am start -n {YOUR_COMMAND}.INP:YOUR_COMMAND- Switches input by sendingshell am start -a android.intent.action.VIEW -d content://android.media.tv/passthrough/com.mediatek.tvinput%2F.hdmi.HDMIInputService%2FHW{YOUR_COMMAND} -n org.droidtv.playtv/.PlayTvActivity -f 0x10000000.INP_TCL:YOUR_COMMAND- Switches input by sendingshell am start -a android.intent.action.VIEW -d content://android.media.tv/passthrough/com.tcl.tvinput%2F.TvPassThroughService%2FHW{YOUR_COMMAND} -f 0x10000000. Make sure to not include theadb shellpart of the command, device IP, ports and similar, as it is already included by the integration. Also make sure that you do not have any spaces between the prefix and the command.
- dotnet 11 SDK.
- or Docker.
- Download
unfolded-circle-adbtv-[version]-remote.tar.gzfrom the release page - Open the remote's Web Configurator
- Click on
Integrations - Click on
Add newand thenInstall custom - Choose the file in step 1 (
unfolded-circle-adbtv-[version]-remote.tar.gz) - Make sure that your device is turned on
- Click on the newly installed integration and follow the on-screen instructions
The application can be configured using the appsettings.json file or environment variables.
Additionally, the application saves configured entities to the configured_entities.json file, which will be saved to the directory specified by the UC_CONFIG_HOME environment variable.
By default, the application logs to stdout.
You can customize the log levels by either modifying the appsettings.json file or by setting environment variables.
TraceDebugInformationWarningError
Trace log level will log the contents of all the incoming and outgoing requests and responses.
{
"Logging": {
"LogLevel": {
"UnfoldedCircle.Server": "Information",
"UnfoldedCircle.AdbTv": "Information",
"Makaretu.Dns": "Warning"
}
}
}Same adjustments to log levels can be made by setting environment variables.
Logging__LogLevel__UnfoldedCircle.Server=InformationLogging__LogLevel__UnfoldedCircle.AdbTv=InformationLogging__LogLevel__Makaretu.Dns=Warning
Execute publish.sh script to build the application for the remote. This will produce a tar.gz file in the root of the repository.
Execute the following from the root of the repository:
docker build -f src/UnfoldedCircle.AdbTv/Dockerfile -t adbtv .dotnet publish ./src/UnfoldedCircle.AdbTv/UnfoldedCircle.AdbTv.csproj -c Release --self-contained -o ./publishThis will produce a self-contained binary in the publish directory in the root of the repository.