Unfolded Circle ADB and Fire TV Integration Driver

This repository contains the server code for hosting an integration driver that uses ADB for communication for the Unfolded Circle Remotes. It exposes a Remote Entity that can be used to control TVs or any other device based on Android with support for ADB.

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/updating the integration when it is hosted on the remote. This is because the public and private keys are removed when the integration is uninstalled.
• The power states are dumb, it only tracks on or off when triggered via the integration. This is a limitation of the ADB protocol, where it is not possible to query the power state without turning on the device.

Prerequisites

• IP and MAC address of the device you want to control.
• When installing on the remote, the remote must be on firmware version 2.6.3 or later or the driver will crash because it can't start adb.
• 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 binary is self-contained and doesn't require any additional software. It's compiled for Linux ARM64 and is meant to be running on the remote.
• Use the Docker Image in the Core Simulator
• Other Operating Systems - Linux, macOS, Windows - are supported. Requires that you have ADB installed.

Network

Service	Port	Protocol	Location
Server	Random*	HTTP (TCP)	Remote/other computer
ADB	5555**	TCP	Device to control
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. ** ADB port can be adjusted during configuration if your device uses a different port.

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

• dotnet 10 SDK.
• or Docker.

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

• License
• richardschneider/net-dns
• richardschneider/net-mdns
• jdomnitz/net-dns
• jdomnitz/net-mdns