Skip to main content

Roku smart home integration, free and open source

Roku integration for Gladys Assistant

Control your Roku players and Roku TVs locally: power, apps, playback, remote keys, inputs.

View on GitHubAll external integrations

Control your Roku streaming players (Express, Streaming Stick, Ultra…) and your Roku TVs (TCL, Hisense, onn., Sharp, Philips, Westinghouse, Roku-made TVs…) from Gladys: power, the app on screen, playback, remote keys, volume and inputs, on the dashboard and in your scenes.

Everything stays on your home network: Gladys talks to the Roku with the External Control Protocol (ECP) Roku documents for its devices. No Roku account, no cloud, no API key.

Developed without the hardware: feedback welcome. This integration was built from Roku's documentation and from real answers of Roku devices recorded by other open-source projects, not on a Roku in a living room. If something does not work as described here, please open an issue (see Reporting a problem): it will get fixed fast.

Before you start: allow control from your network​

Recent versions of Roku OS block control from other devices by default. On each Roku:

  1. Press Home on the Roku remote, open Settings > System > Advanced system settings > Control by mobile apps.
  2. Open Network access and choose Enabled.
    • Limited (the default on recent Roku OS versions) only allows launching apps and typing text: the remote keys are refused, and depending on the Roku OS version, so is what Gladys reads.
    • Disabled refuses everything.
    • Permissive works too, but opens the Roku to any device, even outside your network: Enabled is enough for Gladys.

On a Roku TV, also turn on Settings > System > Power > Fast TV start. Without it, a TV in standby goes deaf to the network: Gladys can neither turn it on nor tell that it is off rather than unplugged.

Give each Roku a fixed address in your router (a "DHCP reservation"): Gladys finds a Roku that changed address again, but it takes a scan.

Installation​

  1. Install the Roku integration from the integration store of Gladys.
  2. Open its Discovery tab and run a scan: every Roku on the same network as Gladys answers within a few seconds.
  3. Click Add to Gladys on each Roku you want. Done.

A Roku the scan does not find (another subnet or VLAN, a mesh network that filters discovery…)? In the Configuration tab, type its IP address in Roku addresses (several addresses separated by commas), save, and scan again. The Test the connection to a Roku action takes an address too: it tells you right away whether the Roku answers and accepts control, and adds it to the Discovery tab when it does.

The address of a Roku is shown on the Roku in Settings > Network > About.

What you get​

Each Roku becomes one Gladys device:

FeatureRoku playersRoku TVs
Powerstate (on / standby)on / off, and its state
Applicationthe app on screen, and a list to open another one (or Home)same
Input–HDMI 1-4, antenna (Live TV), AV, or Roku streaming, with the names you gave them on the TV
Playbackplaying or notplaying or not
Remote keysHome, Back, arrows, OK, Options (*), Play/Pause, Rewind, Fast forward, Instant replaysame, plus Volume up, Volume down, Mute, Channel up/down (with a tuner)

States are refreshed every 10 seconds. The list of apps is read again every 15 minutes, and as soon as an app the list did not have comes to the screen.

What a Roku cannot do (and so Gladys neither)​

  • No volume level. Roku's protocol only has the Volume up, Volume down and Mute keys: there is no "set the volume to 20", no way to read the current level, nor to know whether the sound is muted. Gladys offers the keys, and tells nothing it cannot know.
  • Roku players cannot be turned off. A Roku Express, Stick or Ultra has no real power state: Gladys shows whether it is active or in standby, but only a Roku TV can be turned on and off.
  • Turning on a TV in deep standby needs Fast TV start (see above). When the TV does not answer, Gladys sends it a Wake-on-LAN packet first: whether the TV wakes up depends on the model, and works more often over Ethernet than over Wi-Fi.
  • Volume and power keys of a player (Roku Voice Remote buttons that drive your TV through HDMI-CEC or infrared) are not reachable over the network.
  • Typing text goes through a scene only (see Typing a text): no dashboard field can send text to an integration yet.

Dashboard​

Four widgets come with the integration (Gladys 5.1 or later). Each one shows the Roku picked in its settings, or the first one.

  • Roku remote — power and app on screen, then Power (Roku TV) or Play/Pause (player), Home, Back and OK.
  • Roku navigation — the four arrows: Up, Down, Left, Right.
  • Roku playback — the icon and name of the app on screen, playing or paused, the position in the video while one is open, and Play/Pause, Rewind, Fast forward.

Gladys limits a widget to four buttons: place Roku remote and Roku navigation one under the other to get a full remote. Every other key (volume, mute, Instant replay…) is on the device page and in the "Press a Roku remote key" scene action.

In the menus of the apps (a profile, a film, a setting), OK selects. Play/Pause only acts while a video plays, and how depends on the app: in Arte, for instance, Play does not start the film you picked, OK does.

  • Roku apps — four app shortcuts at most per widget, with their icons (a limit of the Gladys dashboard). Left empty, the settings show the first four apps installed; type the names you want in the widget settings (e.g. Disney+, KiKA, YouTube: case and accents do not matter). For more, add a second Roku apps widget with four other names. The app on screen is marked.

Every installed app, without limit, is in the Application feature of the device: add the device to a regular Devices box to pick any app from a list, or use it in a scene with "Set device value" (the TV inputs are in the Input feature of a Roku TV).

The features of the device can also be added to any regular dashboard box.

Scenes​

The integration adds its own cards to the scene editor, under the Integrations category:

  • Roku app changed (trigger) — starts the scene when an app comes to the screen, within about 10 seconds. Optionally pick the Roku and type the app name exactly as the Roku shows it (e.g. Netflix, or Home for the home screen). The next actions can use the app name and its Roku id. Example: when Netflix starts on the living room TV, dim the lights.

  • Open an app on a Roku (action) — opens an installed app by its name. Example: movie night: turn the TV on, open Netflix.

  • Press a Roku remote key (action) — any key, as many times as needed, including Turn on and Turn off for a Roku TV. Example: when the doorbell rings, press Play/Pause.

  • Type a text on a Roku (action) — types a text in the field shown on the Roku, see below.

The power and playback states are regular device features: a scene can start when the TV turns off, or check that something is playing.

Typing a text (search, login)​

Gladys has no text field on the dashboard that an integration can receive yet. The workaround:

  1. On the Roku, open the field (a search, the email of a login…).
  2. In Gladys, create a scene with the Type a text on a Roku action and the text to type (100 characters at most).
  3. Add a Scene box to your dashboard with that scene: one tap types the text.

Do not put a sensitive password in a scene: every Gladys user can read the scenes. The integration never writes the typed text in its logs.

Troubleshooting​

"… refuses remote control" (in the Configuration tab, a widget or an action): the Roku is set to Limited or Disabled. Set **Control by mobile apps

Network access** to Enabled (see Before you start), then run Test the connection to a Roku.

The scan finds nothing. Gladys and the Roku must be on the same network (same subnet, no guest Wi-Fi, no client isolation). Type the address of the Roku in Roku addresses, save, and scan again.

The Roku shows as off while it is on. It does not answer anymore: check its address (it may have changed), then run Test the connection to a Roku.

A Roku TV does not turn on. Turn on Fast TV start on the TV. If it is connected by Wi-Fi, Wake-on-LAN may not reach it while asleep.

An app is missing from the list. The list is read every 15 minutes: wait, or open the app once on the Roku.

Reporting a problem​

  1. In the Configuration tab, turn on Debug logs and save.
  2. Reproduce the problem, then copy the logs of the integration (Integration page > Logs).
  3. Open an issue on github.com/guim31/gladys-roku with the logs, your Roku model and its Roku OS version (Settings > System > About). The logs hold no password; they show the Roku model, its address on your network and its serial number.

Turn the debug logs off afterwards: they are verbose.

Not affiliated with Roku, Inc. Roku is a trademark of Roku, Inc.

Configuration settings​

These are the settings Roku asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Before you startsectionNoOn each Roku, open Settings > System > Advanced system settings > Control by mobile apps > Network access and choose "Enabled": recent Roku OS versions set it to "Limited", which blocks Gladys. Then run a device scan (Discovery tab): Rokus on the same network are found automatically. Type an address below only for a Roku the scan misses.
Roku addresses (optional)stringNoIP addresses of Rokus the device scan does not find, separated by commas. Give them a fixed address in your router (DHCP reservation).
Debug logsbooleanNoWrite every request sent to the Rokus and a summary of their answers in the integration logs. Turn it on before reporting a problem.

How to install Roku in Gladys​

  1. In Gladys, open Integrations: Roku appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-roku:1.1.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-roku.

Roku requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Roku is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on