Roku Implementation Options — Auto-load Welcome Screen (2026‑02‑05)

Goal: when a guest turns on the TV / Roku, a welcome screen appears automatically.

Roku differs from Fire TV in a key way: Roku is not a general web browser platform. You typically must build a Roku channel (SceneGraph/BrightScript) that renders UI and fetches data from your server.

Key constraints (Roku)

1. No arbitrary HTML webview
   • You can fetch JSON/images/video streams over HTTPS and render them with Roku UI components.
2. Auto-start on boot is not a standard consumer feature
   • To “force” a channel to launch automatically, you typically need a local network controller using Roku’s External Control Protocol (ECP), or accept that the guest launches it manually.

Option 1: Build a Roku Channel that renders a “welcome” UI (core building block)

What: A Roku channel that: - loads https://api.example.com/roku/<token>.json (or similar) - displays: - welcome text, Wi‑Fi QR (as image), rules - optional background slideshow - optional video (HLS recommended) - periodically refreshes

Pros - Best Roku-native UX (fast, reliable) - Full control over layout and remote navigation - Video playback is first-class on Roku

Cons - You now must maintain a Roku codebase + deployment process - Content pipeline must produce Roku-friendly assets (images/video streams)

Implementation notes (server) - Plan for two render targets: - Web TV page (Fire TV) - Roku JSON + image assets

Option 2: “Auto-launch” the Roku channel via ECP from a local controller (recommended if true auto-start is required)

Roku devices expose a LAN control interface called External Control Protocol (ECP).

Official Roku doc (reachable via proxy): - https://developer.roku.com/docs/developer-program/dev-tools/external-control-api.md

Key facts from Roku’s ECP documentation: - ECP is a REST-like API on port 8060 on the Roku device. - Devices can be discovered via SSDP. - /keypress and some queries require enabling Settings > System > Advanced system settings > Control by mobile apps (as of Roku OS 14.1).

Launching an app/channel via ECP

Roku’s ECP doc describes launching/deep linking with:

• POST http://<ROKU_IP>:8060/launch/<channelId>
• Deep link parameters are query params (contentID, mediaType, etc.)

(See the “Deep linking to an app” section of the ECP doc linked above.)

How this becomes “auto-start”

Because Roku itself doesn’t reliably launch a specific channel at power-on, you run a tiny always-on device on the same LAN (e.g., Raspberry Pi / mini router) that: - discovers the Roku (SSDP) - periodically checks if it’s reachable - sends /launch/<channelId> when it sees the Roku come online (or at scheduled times)

Pros - Closest to true “auto launch” without user interaction

Cons / risks - Requires an extra always-on box in each unit (or per network) - Depends on LAN topology (client isolation/VLAN rules can break discovery) - Guests or OTA updates could change ECP settings

Option 3: Roku Screensaver channel (good for “idle signage”, not “on startup”)

What: Build a Roku screensaver that shows welcome info when the Roku is idle.

Pros - Can keep the welcome visible if guests pause/leave Roku idle

Cons - Doesn’t guarantee showing on power-on - Limited interactivity expectations

Option 4: Accept manual launch (“Welcome” channel pinned) + Home screen positioning

What: Install the Welcome channel and attempt to make it easy to open: - pin it as first tile (where possible) - printed instruction: “Open ‘Welcome’ on the TV for Wi‑Fi and house guide”

Pros - No controller device

Cons - Doesn’t meet the “auto-load on startup” requirement

Inputs needed from James (Roku specific)

• Is it Roku TV or Roku streaming stick/box?
• Roku OS version (some ECP controls changed over time)
• Can we guarantee LAN access between a controller and the Roku?
• Is adding a small controller device acceptable?

Recommendation (pragmatic)

• Treat Roku as Phase 2.
• If true auto-start is mandatory on Roku, plan on Option 2 (ECP + local controller).
• Otherwise, do Option 1 and accept manual launch or screensaver behavior.