Android TV

Android TV / Google TV streaming devices and televisions — Nvidia Shield, Chromecast with Google TV, the Sony / TCL / Hisense Google TVs, the AT&T / DIRECTV streaming box, and most set-tops running Android TV — are controlled over Google's Android TV remote protocol, the same LAN protocol the official Google TV phone app uses. One device on the network becomes one GEM device, and commands target the device directly (this driver creates no zones).

Two layers of control are available:

• Remote control (available as soon as the device is paired): the full on-screen-remote key set — D-pad, transport, channel, color, and number/letter keys — plus app deep-links and on-screen text entry.
• App launching and channel sync (optional, requires ADB): launch installed apps by name and turn the TV's installed apps into a browsable channel lineup with fetched icons.

What's controlled

• Power — sleep / wake / toggle
• Full D-pad and navigation: up/down/left/right/select, home, back, exit, menu
• Media transport: play, pause, play/pause, stop, fast-forward, rewind, record
• Channel up/down, direct channel entry, guide / info / DVR screens
• Color buttons (red/green/yellow/blue) and the apps button
• On-screen text entry and number/letter keys
• App deep-links, and — with ADB — launching installed apps by name
• YouTube TV shortcuts and direct YouTube TV channel tuning
• A browsable app/channel grid when the device is used as an AV source

This driver does not expose direct volume or mute commands — see "Known limitations".

Prerequisites

• An Android TV / Google TV device on the same LAN as GEM, reachable by IP.
• The TV powered on the first time you pair, so it can display the 6-digit pairing code.
• For app launching and the app-to-channel sync only: Developer options and Network debugging (ADB) enabled on the TV, and the adb command-line tool installed on the GEM host (resolvable on the system PATH).

Give the TV a static IP or a DHCP reservation so its address never moves — a moved address means GEM can no longer reach a paired device.

Setup — pairing

1. Open Devices, add a device, and choose the Android TV driver.
2. Set the TV IP Address field to the device's LAN IP. Leave Pairing Port (6467) and Remote Port (6466) at their defaults unless your device remaps them. Save and enable the device.
3. With the TV powered on, open the device's Commands tab and run pair. The TV shows a 6-digit pairing code, and GEM pops up a prompt reading "Enter pairing code on screen."
4. Type the 6-digit code shown on the TV into the prompt and confirm. GEM completes the handshake and stores a pairing certificate on the device (encrypted and read-only — do not edit it by hand).

Pairing usually takes a few seconds. Once paired, GEM reconnects on its own using the stored certificate; you only pair again if the certificate is cleared or the TV is factory-reset.

tip

If pairing times out (default two minutes, set by Pairing Timeout (ms)), just run pair again — the code on the TV refreshes each time.

App launching and channel sync (ADB)

Plain pairing gives you the remote. To launch apps by name and build a browsable app lineup, enable ADB on the TV and connect GEM to it:

1. On the TV, unlock Developer options: Settings → System → About (or Device Preferences → About on older builds) → scroll to Build and click it seven times until "You are now a developer" appears.
2. In Settings → System → Developer options (or Device Preferences → Developer options) turn ON USB debugging and Network debugging (labeled "ADB debugging" or "Wireless debugging" on some builds). Network debugging exposes ADB on TCP port 5555 so GEM can reach it over the LAN.
3. In GEM, run the pair_adb command on the device. The first time, the TV shows an "Allow USB debugging from this computer?" prompt — check "Always allow from this computer" and tap OK.
4. If pair_adb returns "approve adb connection on tv screen, then reload device," you missed the on-screen prompt — approve it on the TV, then reload the device.

On a successful ADB connection GEM turns on the Enable ADB device attribute and, from then on, connects ADB automatically and syncs the TV's installed apps into a channel lineup: it builds a channel lineup named after the device, adds one channel per launchable app (using friendly names for the major streaming apps), fetches each app's icon from the Google Play Store, and disables channels for apps that have been uninstalled. Run sync_apps any time to refresh that lineup by hand.

note

ADB is optional. Everything except launch_app, get_apps, and the app-to-channel sync works without it. If the adb tool is not installed on the GEM host, those three commands return "adb not connected".

Using the TV as an AV source

To put the TV on a touchpanel as a selectable source with an on-screen app/channel grid, create an AV source for it:

1. Open AV Sources and add a source whose Device is this Android TV.
2. Set the Component field to one of:
   • android_tv — the installed-apps grid (uses the app lineup built by the ADB sync above).
   • youtube_tv — the YouTube TV channel grid.
3. Save. When a user selects that source in a room, GEM draws the matching panel — tapping an app launches it; tapping a YouTube TV channel tunes it.

GEM links the source to the matching channel lineup automatically when that lineup syncs (the app lineup on an ADB sync, the YouTube TV lineup on connect), so for these two components you do not have to set the Channel Provider field by hand. See Channels for how channel lineups and the on-screen browser work.

YouTube TV lineup

When the first Android TV device connects, GEM syncs a YouTube TV channel lineup automatically (once per server run). The lineup is keyed to a ZIP/DMA market; the built-in default URL covers a common market, but for correct local channels set the YouTube TV Lineup URL device attribute to your market's lineup endpoint. The youtube_tv_home and youtube_tv_live commands jump to YouTube TV's home and live screens, and set_youtubetv_channel tunes a specific YouTube TV channel by its channel id.

Attributes

Device — required

Attribute	Type	Description
ip	string	The TV's LAN IP address.

Device — optional

Attribute	Type	Default	Description
pairing_port	int	6467	TCP port used during the initial pairing handshake.
remote_port	int	6466	TCP port used for ongoing remote-control traffic.
pairing_timeout	int	120000	How long (ms) to wait for the on-screen pairing code before giving up.
preset_channel_delay	int	200	Delay (ms) between digit key-presses when dialing a channel with set_channel.
youtubetv_lineup_url	string	(built-in)	JSON endpoint used to sync the YouTube TV channel lineup. Override to match your local market.
adb_enabled	bool	false	When on, GEM connects ADB automatically to query and launch apps. Set automatically after a successful pair_adb.

GEM also stores two values on the device that you do not set by hand:

• certificate — the pairing certificate, written after a successful pair and stored encrypted. Read-only; do not edit.
• current_app — the package name of the app currently on screen (for example com.netflix.ninja), updated as the TV reports it. Read-only, and handy as a trigger condition — for example, fire a macro when current_app becomes the Netflix package.

pairing_code is a temporary attribute GEM fills from the on-screen-code prompt during pairing and clears automatically afterward.

Commands

Driver-declared commands appear on the device's Commands tab and can be used in macros, triggers, and on UI buttons.

Power and navigation

Command	Action
power_on / power_off / power_toggle	Wake / sleep / toggle power.
up down left right select	D-pad navigation and select.
home back exit menu	Home screen, back, exit (sends Back), and menu.

Media transport

Command	Action
play pause play_pause stop	Transport controls.
fast_forward rewind record	Scan and record.

Channels and guide

Command	Action
channel_up / channel_down	Step channels.
set_channel (arg channel)	Dial a channel by number — GEM sends each digit, then Enter.
guide info dvr	Guide, info overlay, and DVR screens.

Color, apps, and feedback

Command	Action
red green yellow blue	Colored guide/app buttons.
apps	Open the all-apps screen.
refresh	Refresh key.
thumbs_up / thumbs_down	Rating keys.

Text and key entry

Command	Action
0–9, a–z	Send a single number or letter key.
send_text (arg text)	Type a string into the on-screen field, one character at a time.
append_text (arg text)	Append text to the current field (same behavior as send_text).
send_key (arg key)	Send any Android key by name — the part after KEYCODE_, lower-cased. For example volume_up, volume_down, volume_mute, media_next, media_previous, tv_input_hdmi_1. Use this for keys not in the lists above.

Apps and links

Command	Action
send_app_link (arg url)	Open a deep-link URL on the TV.
launch_app (arg package)	Launch an installed app by package name (requires ADB).
get_apps	List the TV's launchable apps (requires ADB).
sync_apps	Rebuild the app channel lineup and fetch icons (requires ADB).
youtube_tv_home / youtube_tv_live	Jump to YouTube TV's home / live screen.
set_youtubetv_channel (arg channel)	Tune a YouTube TV channel by its channel id.

Pairing

Command	Action
pair	Start the remote pairing handshake (prompts for the on-screen 6-digit code).
pair_adb	Connect ADB to the TV for app launching and channel sync.

Configurable app buttons

video_app_1 through video_app_5 are five empty preset slots with no built-in action. Assign each one a template to wire it to a favorite app or a key sequence. A template of macro=<key>,<key>,… sends a series of remote keys in order — each key is an Android key name without the KEYCODE_ prefix — with a short delay between them, for example macro=home,dpad_down,dpad_down,dpad_center to launch an app from a known home-screen position. Until you give one a template it does nothing.

note

A few keys in the lists above are placeholders that the current remote protocol does not map and that therefore have no effect: list, last, skip_forward, and skip_back. For skip-track behavior, use send_key with media_next or media_previous.

Known limitations

• No direct volume or mute commands. This driver does not expose volume-up / volume-down / mute as their own commands. Send volume_up, volume_down, or volume_mute through send_key, or — better — control room volume on the AV receiver or amplifier and leave the TV at a fixed level.
• App launching needs ADB. launch_app, get_apps, and the app-to-channel sync require ADB enabled on the TV and the adb tool installed on the GEM host. The remote, text entry, deep-links, and YouTube TV shortcuts all work without ADB.
• Network debugging can reset on reboot. Some TV firmware turns Network debugging back OFF after a power cycle; if ADB stops responding, re-enable it in Developer options.
• One YouTube TV market at a time. The YouTube TV lineup is shared across all Android TV devices and synced once per server run; set the lineup URL to your market.

Troubleshooting

Symptom	Check
Pairing never completes	The TV must be powered on to show the code, and you must enter the code before the Pairing Timeout elapses. Run pair again to get a fresh code.
Paired, but commands do nothing	Confirm the TV's IP hasn't changed and the device is enabled. Re-run pair to re-issue a certificate if the TV was factory-reset.
launch_app / get_apps / sync_apps return "adb not connected"	Enable USB + Network debugging on the TV, run pair_adb, approve the on-screen "Allow USB debugging" prompt, and make sure adb is installed on the GEM host.
The "Allow USB debugging" prompt never appeared	It only shows the first time a given host connects. Toggle Network debugging off and back on, then run pair_adb again.
Power on/off does nothing on an off-brand TV	Some TVs ignore the sleep/wake keys. Use power_toggle instead.
App icons or channel names look wrong	Re-run sync_apps to re-query installed apps and refetch icons.

See also

• AV Sources — add the TV as a selectable source and pick the android_tv or youtube_tv panel.
• Channels — how the app and YouTube TV channel lineups and the on-screen browser work.
• Commands — running and scripting device commands.
• Devices — adding and configuring devices.