Android TV integration for Remote Two/3

Using androidtvremote2, uc-integration-api, pychromecast and google-play-scraper.

The integration currently supports almost all features that the androidtvremote2 library provides. Button control and ON/OFF states are supported. With the optional Google Cast support, media playing information can be retrieved from supported apps.
The application source list is limited to a predefined list, as retrieving the installed apps is not possible.

This integration is included in the Remote Two and Remote 3 firmware, and no external service must be run to connect with Android TV devices. It can be run as an external integration for development.

Requirements and setting.
Multiple Android TV devices are supported with version 0.5.0 and newer.
A media player entity is exposed per Android TV device to the Remote.
Device profiles allow device-specific support and custom key bindings, for example, double-click or long-press actions.
See command mappings for more information.

Preview features:

Optional external metadata lookup using the Google Play Store for friendly application name and icon.
Google Cast support to retrieve media-playing information.
Google Cast volume control with configurable volume step.

The preview features are not enabled by default. They can be enabled in the device configuration of the setup flow.

Standalone Usage

Setup

Requires Python 3.11
Install required libraries:
(using a virtual environment is highly recommended)

pip3 install -r requirements.txt

For running a separate integration driver on your network for Remote Two/3, the configuration in file driver.json needs to be changed:

Set driver_id to a unique value, uc_androidtv_driver is already used for the embedded driver in the firmware.
Change name to easily identify the driver for discovery & setup with Remote Two/3 or the web-configurator.
Optionally add a "port": 8090 field for the WebSocket server listening port.
- Default port: 9090
- Also overrideable with environment variable UC_INTEGRATION_HTTP_PORT

Run

UC_CONFIG_HOME=./config UC_DATA_HOME=./data python3 src/driver.py

Environment variables:
- UC_CONFIG_HOME: configuration directory for device settings, certificates and profiles.
- UC_DATA_HOME: data directory to store metadata images.
See available environment variables in the Python integration library to control certain runtime features like listening interface and configuration directory.
The client name used for the client certificate can be set in ENV variable UC_CLIENT_NAME. The hostname is used by default.

Build distribution binary

After some tests, turns out Python stuff on embedded is a nightmare. So we're better off creating a binary distribution that has everything in it, including the Python runtime and all required modules and native libraries.

To do that, we use PyInstaller, but it needs to run on the target architecture as PyInstaller does not support cross compilation.

The --onefile option to create a one-file bundled executable should be avoided:

Higher startup cost, since the wrapper binary must first extract the archive.
Files are extracted to the /tmp directory on the device, which is an in-memory filesystem.
This will further reduce the available memory for the integration drivers!

x86-64 Linux

On x86-64 Linux we need Qemu to emulate the aarch64 target platform:

sudo apt install qemu binfmt-support qemu-user-static
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

Run PyInstaller:

docker run --rm --name builder \
    --platform=aarch64 \
    --user=$(id -u):$(id -g) \
    -v "$PWD":/workspace \
    docker.io/unfoldedcircle/r2-pyinstaller:3.11.12  \
    bash -c \
      "python -m pip install -r requirements.txt && \
      pyinstaller --clean --onedir --name intg-androidtv src/driver.py"

aarch64 Linux / Mac

On an aarch64 host platform, the build image can be run directly (and much faster):

docker run --rm --name builder \
    --user=$(id -u):$(id -g) \
    -v "$PWD":/workspace \
    docker.io/unfoldedcircle/r2-pyinstaller:3.11.12  \
    bash -c \
      "python -m pip install -r requirements.txt && \
      pyinstaller --clean --onedir --name intg-androidtv src/driver.py"

Versioning

We use SemVer for versioning. For the versions available, see the tags and releases in this repository.

Changelog

The major changes found in each new release are listed in the changelog and under the GitHub releases.

Contributions

Please read our contribution guidelines before opening a pull request.

License

This project is licensed under the Mozilla Public License 2.0. See the LICENSE file for details.

ItsHarper/integration-androidtv