Roku
Roku streaming players (Express, Streaming Stick, Ultra) and Roku TVs are controlled over Roku's External Control Protocol (ECP) — a simple HTTP service the player exposes on the LAN at port 8060. There is no pairing and no password: GEM just needs to reach the Roku's IP address with ECP turned on. One Roku becomes one GEM device, and commands target the device directly (this driver creates no zones).
Two things this gives you:
- Remote control — the full on-screen-remote key set: D-pad and select, Home, Back, the
Info (
*) button, instant replay, and play/pause/scan transport, plus on-screen text entry for typing into search and sign-in fields. - App launching, channel sync, and now-playing — GEM turns the Roku's installed apps into a browsable channel lineup with each app's own icon, launches any app on demand, and reports the app currently on screen so a touchpanel can show what's playing.
What's controlled
- Navigation: up / down / left / right / select, Home, Back, Info, instant replay
- Transport: play, pause, play/pause, rewind, fast-forward
- Launch any installed app by its Roku app id
- Live now-playing feedback (the app currently on screen)
- On-screen text entry (typing into a Roku search or login field)
- A browsable installed-apps grid when the Roku is used as an AV source
This driver does not expose dedicated power, volume, or mute commands — see "Power and volume" and "Known limitations" below.
Prerequisites
- A Roku player or Roku TV on the same LAN as GEM, reachable by IP (no NAT between them).
- Control by mobile apps enabled on the Roku. Network access = Permissive is the most reliable; Default also allows control from devices on the same local subnet.
- Give the Roku a static IP or a DHCP reservation so its address never moves — a moved address means GEM can no longer reach it.
Setup
- On the Roku, open Settings → System → Advanced system settings → Control by mobile apps → Network access and set it to Permissive (or leave it at Default if GEM is on the same subnet).
- Open Devices, add a device, and choose the Roku driver. Place it in the AV subsystem (the driver suggests AV).
- Set the Roku IP field to the player's LAN IP. Leave Port at 8060 — ECP only listens on 8060, and the driver forces that port on connect regardless of what you enter here. Save and enable the device.
- There is nothing to pair or log in to. Within a few seconds GEM connects, begins polling the current app, and syncs the Roku's installed apps into a channel lineup (see below).
Using the Roku as an AV source
To put the Roku on a touchpanel as a selectable source with an on-screen app grid, create an AV source for it:
- Open AV Sources and add a source whose Device is this Roku.
- Set the Component field to
roku. - Save. When a user selects that source in a room, GEM draws the Roku panel: the left side is a grid of the Roku's installed apps (tap one to launch it), the right side is a D-pad and transport keypad, and a search icon opens an on-screen keyboard for typing into the Roku. The now-playing area shows the icon and name of the app currently on screen.
GEM links the source to the Roku's app lineup automatically each time that lineup syncs, so you
do not have to set the Channel Provider field by hand for a roku source. See
Channels for how channel lineups and the on-screen browser (favorites,
press-and-hold to favorite, search) work.
How the app lineup and now-playing work
- App sync. On connect and then every Preset Sync Interval (default 5 minutes), GEM queries the Roku's installed apps and maintains a channel lineup named after the device — one channel per app, where the channel value is the Roku app id and the logo points at the Roku's own icon for that app. Apps you uninstall on the Roku drop out of the lineup on the next sync. To force a refresh immediately, reload the device.
- Now-playing. Every Active-App Poll Interval (default 5 seconds) GEM asks the Roku which app is open and records it on the device, which is what drives the now-playing display on the source panel and can be used as a trigger condition (for example, fire a macro when the Roku switches into a particular app).
Power and volume
Roku's ECP has no protocol-level "power on/off" or "volume" beyond its remote keys, so this
driver ships no dedicated power_on / power_off / volume / mute commands. Send those
keys through the generic keypress command with the Roku ECP key name in the key argument:
| What you want | Command | key argument |
|---|---|---|
| Sleep / wake (standby) | keypress | PowerOff / PowerOn |
| Volume up / down / mute (Roku TVs) | keypress | VolumeUp / VolumeDown / VolumeMute |
| Switch a Roku TV input | keypress | InputHDMI1 … InputHDMI4, InputTuner, InputAV1 |
| Channel up / down (Roku TV tuner) | keypress | ChannelUp / ChannelDown |
The volume, input, and tuner keys apply to Roku TVs (which have their own speakers, inputs, and tuner). A streaming player has no speakers — control room volume on the AV receiver or amplifier instead, and leave the Roku at a fixed level.
Attributes
Device — required
| Attribute | Type | Description |
|---|---|---|
ip | string | The Roku's LAN IP address. |
Device — optional
| Attribute | Type | Default | Description |
|---|---|---|---|
port | int | 8060 | ECP port. The driver forces 8060 on connect — Roku only listens there — so this is informational. |
status_interval | int | 5000 | How often (ms, minimum 1000) GEM polls the Roku for the app currently on screen. |
preset_interval | int | 300000 | How often (ms, minimum 30000) GEM re-syncs the installed-apps channel lineup. |
GEM also records current_media on the device — the app currently on screen, as reported by
the active-app poll. You do not set it by hand; it updates on its own and is useful as a trigger
condition. (Roku devices have no entries in the attribute autocomplete catalog, so type attribute
names exactly as shown when referencing them in triggers or macros.)
Commands
Driver-declared commands appear on the device's Commands tab and can be used in macros, triggers, and on UI buttons.
Navigation
| Command | Action |
|---|---|
up down left right select | D-pad navigation and select. |
home | Roku Home screen. |
back | Back. |
info | Info / options (the * button). |
instant_replay | Instant replay. |
Transport
| Command | Action |
|---|---|
play pause play_pause | Play / pause (Roku uses one Play key to toggle, so all three send Play). |
fast_forward / scan_forward | Scan forward. |
rewind / scan_back | Scan back. |
Apps and channels
| Command | Action |
|---|---|
launch_app (arg app_id) | Launch an installed app by its Roku app id. |
set_channel (arg channel) | Tune a "channel" — for a Roku the channel value is an app id, so this launches that app. This is how the channel system tunes a Roku. |
query_apps | List the installed apps (id, name). |
query_active_app | Report the app currently on screen. |
query_device_info | Read Roku model / serial / network details. |
query_icon (arg app_id) | Fetch an app's icon image. |
Text and key entry
| Command | Action |
|---|---|
keyboard (arg key) | Type one literal character into the focused Roku field (search, sign-in, etc.). |
backspace | Delete the last typed character. |
keypress (arg key) | Send any Roku ECP key by name — for example Home, Select, PowerOn, VolumeUp, InputHDMI1. Use this for any key not in the lists above. |
key_down / key_up (arg key) | Press and release a key separately, for press-and-hold behavior. |
query (arg query) | Run any ECP query/… path directly (advanced/diagnostic). |
search (arg search) | Opens Roku's search endpoint — but see the note below; for reliable searching, type into Roku Search with the on-screen keyboard instead. |
The most reliable way to search is to open Roku Search on the device, then type your term
with the on-screen keyboard — in the roku AV-source panel, tap the search icon and type; behind
the scenes that sends each character with the keyboard command. The standalone search command
hands the term to Roku's search URL in a way that does not pass the term as the search keyword, so
prefer the keyboard path above.
Known limitations
- No dedicated power / volume / mute commands. Use
keypresswith the Roku ECP key name (see "Power and volume"). Volume and input keys only do something on Roku TVs. - Port is always 8060. ECP only listens on 8060, so the driver forces it on connect; the
portattribute is informational. - Single device, no zones. A Roku is one device — it creates no GEM zones. Group rooms and multi-room behavior at the AV-zone / macro layer, not on the driver.
- App lineup follows the Roku. Channels in the lineup are the Roku's installed apps; install or remove an app on the Roku and the lineup catches up on the next sync (or immediately if you reload the device).
Troubleshooting
| Symptom | Check |
|---|---|
| Connection refused or timeouts | Control by mobile apps → Network access is set to Disabled on the Roku. Set it to Default or Permissive. Confirm the Roku's IP hasn't changed. |
| App grid / channel list is stale | The lineup re-syncs every Preset Sync Interval (default 5 minutes). To pick up an install/uninstall right away, reload the device. |
| Now-playing never updates | The active-app poll runs every Active-App Poll Interval (default 5 s). Confirm the device is enabled and reachable. |
keypress/launch_app do nothing | Confirm you are on the same LAN with no NAT, the Roku IP is correct, and Network access is not Disabled. |
| Volume / power keys ignored | These only act on Roku TVs. On a streaming player, control volume on the AV receiver and power via HDMI-CEC or the TV. |
See also
- AV Sources — add the Roku as a selectable source and pick the
rokupanel. - Channels — how the installed-apps lineup and the on-screen browser work.
- Commands — running and scripting device commands.
- Devices — adding and configuring devices.