Skip to content

About

Control your TV and other devices via ADB on the Unfolded Circle remotes

Resources

Code of conduct

Contributing

Security policy

Stars

7 stars

Watchers

1 watching

Forks

Repository files navigation

Unfolded Circle ADB and Fire TV Integration Driver

Release CI Sonar Quality Gate Qodana Docker

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

Limitations

  • 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 integration option.
  • 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 SslStream client 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.

Prerequisites

  • 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.

Running

  • 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.

Network

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.

Wireless debugging pairing (Android 11+)

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).

Launching apps

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 example com.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.

Additional commands

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.

Advanced 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 sending shell monkey --pct-syskeys 0 -p {YOUR_COMMAND} 1.
  • ACT:YOUR_COMMAND - Starts an activity by sending shell am start -n {YOUR_COMMAND}.
  • INP:YOUR_COMMAND - Switches input by sending shell 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 sending shell 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 the adb shell part 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.

Development

Installing on the remote

  1. Download unfolded-circle-adbtv-[version]-remote.tar.gz from the release page
  2. Open the remote's Web Configurator
  3. Click on Integrations
  4. Click on Add new and then Install custom
  5. Choose the file in step 1 (unfolded-circle-adbtv-[version]-remote.tar.gz)
  6. Make sure that your device is turned on
  7. Click on the newly installed integration and follow the on-screen instructions

Configuration

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.

Logging

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.

Log levels

  • Trace
  • Debug
  • Information
  • Warning
  • Error

Trace log level will log the contents of all the incoming and outgoing requests and responses.

appsettings.json

{
    "Logging": {
        "LogLevel": {
          "UnfoldedCircle.Server": "Information",
          "UnfoldedCircle.AdbTv": "Information",
          "Makaretu.Dns": "Warning"
        }
    }
}

Environment variables

Same adjustments to log levels can be made by setting environment variables.

  • Logging__LogLevel__UnfoldedCircle.Server = Information
  • Logging__LogLevel__UnfoldedCircle.AdbTv = Information
  • Logging__LogLevel__Makaretu.Dns = Warning

Building from source code

Building for the remote

Execute publish.sh script to build the application for the remote. This will produce a tar.gz file in the root of the repository.

Building for Docker

Execute the following from the root of the repository:

docker build -f src/UnfoldedCircle.AdbTv/Dockerfile -t adbtv .

dotnet CLI

dotnet publish ./src/UnfoldedCircle.AdbTv/UnfoldedCircle.AdbTv.csproj -c Release --self-contained -o ./publish

This will produce a self-contained binary in the publish directory in the root of the repository.

Licenses / Copyright

About

Control your TV and other devices via ADB on the Unfolded Circle remotes

Resources

Code of conduct

Contributing

Security policy

Stars

7 stars

Watchers

1 watching

Forks

Releases

Sponsor this project

Used by

Contributors

Languages