Unlock Your Roku TV: The External Control Protocol (ECP)
Every Roku device, from standalone streaming sticks to integrated TCL, Hisense, and Sharp Roku TVs, quietly ships with a powerful, yet often overlooked, local HTTP API. This is Roku's External Control Protocol (ECP), a developer-facing interface that enables direct control over your television. It's not a new feature; it's been present by default on retail units for years, used by Roku's own mobile app, and is fully documented on developer.roku.com. The surprising detail here is not its existence, but its obscurity outside the dedicated Roku channel developer community. This API offers a straightforward way to turn any Roku TV into a scriptable device, controllable via simple HTTP requests from your local network.
The ECP operates on port 8060 of your Roku device and requires no cloud connection, API keys, or complex authentication. It's a pure, unadulterated local network interface. This direct access means faster response times, increased reliability, and the ability to automate TV functions without relying on third-party services or internet connectivity. For developers, system integrators, or even power users, this opens up a wealth of possibilities for custom home automation, media center integration, and device management.
Discovering Your Roku Device on the Network
Before you can control your Roku TV, you need to know its IP address on your local network. If you've already found this through the TV's settings menu (typically under Settings → Network → About), you can proceed. However, Roku devices broadcast their presence using SSDP (Simple Service Discovery Protocol), the same protocol used by devices like Chromecast. This allows for automatic discovery without manual IP configuration.
To find your Roku's IP address programmatically, you can send an SSDP M-SEARCH request to the multicast address 255.255.255.255 on port 1900. A common method involves using a UDP socket to broadcast the discovery packet. The Roku device will respond with an `HTTP/1.1 200 OK` message, containing details like the `LOCATION` header, which points to an XML file detailing the device's services and its IP address. This discovery mechanism is crucial for applications that need to find and control multiple Roku devices on a network without hardcoding their addresses.
Navigating the ECP: Key Endpoints and Functionality
The ECP is a remarkably simple, five-endpoint API. Each endpoint corresponds to a fundamental control action, accessible via standard HTTP GET or POST requests. These endpoints allow you to query the device's status, send remote control commands, launch applications, and even send text input.
1. Device Status (`/query/device-info`)
This GET endpoint provides comprehensive information about the Roku device. It returns an XML payload containing details such as the device's serial number, model name, software version, network IP address, MAC address, and the currently active application. This is invaluable for identifying specific devices and understanding their current state.
2. Remote Control Commands (`/keypress/`)
This is the core of the ECP's control capabilities. By sending a POST request to `/keypress/
Up,Down,Left,Right,Select,Back,HomeVolumeDown,VolumeUp,MutePower,InputTuner,ChannelDown,ChannelUpPlay,Pause,Stop,Reverse,ForwardInfo,Backslash,Ok
For example, to simulate pressing the 'Home' button, you would send a POST request to `/keypress/Home`.
3. Launching Applications (`/launch/`)
The `/launch/
4. Sending Text Input (`/input/`)
For applications that require text input (like search fields), the `/input/send-text` endpoint is available. This POST endpoint accepts a `text` parameter, allowing you to send strings to the active application. This is particularly useful for automating searches within streaming apps or logging into services. The API handles the character-by-character input, making it seamless.
5. User Device Information (`/query/user-device-info`)
This endpoint provides more detailed user-specific information, such as the device's friendly name, locale settings, and timezone. It complements the general device information by offering insights into the user's configuration of the device.
Using ECP with cURL and JavaScript
The simplicity of ECP makes it accessible from virtually any programming language or command-line tool that can make HTTP requests. Here's how you can interact with it using common developer tools:
cURL Examples
To get device information:
curl http://<ROKU_IP_ADDRESS>:8060/query/device-infoTo simulate a 'Power' button press:
curl -X POST http://<ROKU_IP_ADDRESS>:8060/keypress/PowerTo launch the Netflix app (assuming its `app_id` is `2`):
curl -X POST http://<ROKU_IP_ADDRESS>:8060/launch/2JavaScript Examples (Node.js or Browser)
Using Node.js with the `node-fetch` library:
const fetch = require('node-fetch');
const ROKU_IP = 'http://<ROKU_IP_ADDRESS>:8060';
async function pressKey(key) {
try {
const response = await fetch(`${ROKU_IP}/keypress/${key}`, {
method: 'POST'
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
console.log(`Keypress '${key}' sent successfully.`);
} catch (error) {
console.error(`Failed to send keypress '${key}':`, error);
}
}
async function getDeviceInfo() {
try {
const response = await fetch(`${ROKU_IP}/query/device-info`);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const xml = await response.text();
console.log('Device Info XML:', xml);
// Parse XML here if needed
} catch (error) {
console.error('Failed to get device info:', error);
}
}
// Example usage:
pressKey('Home');
getDeviceInfo();
In a browser environment, you would use the standard `fetch` API, being mindful of CORS policies if making requests from a different origin. However, for local development, direct `fetch` calls to the Roku's IP should work.
Beyond Basic Control: Automation and Integration
The ECP transforms the Roku TV from a passive display into an active participant in a smart home ecosystem. Imagine scripting your TV to turn on to a specific news channel at a set time each morning, or integrating it into a home theater system that dims the lights and powers on the TV with a single command. Developers can build custom remote apps with tailored interfaces, create dashboards to monitor device status, or even integrate Roku control into broader automation platforms like Home Assistant.
The lack of authentication and cloud dependency is a double-edged sword. While it simplifies integration immensely, it also means the API is only accessible on the local network. Anyone with access to your LAN could potentially control your Roku TV. This is a critical consideration for security-conscious users; ensuring your home network is secured is paramount. However, for most home users and developers building internal tools, this ease of access is a significant advantage.
What remains unaddressed is how this local API might evolve. As Roku continues to integrate more smart features and potentially push more content discovery through its platform, will the ECP remain a simple, direct interface, or will it become more sophisticated, perhaps incorporating cloud-based features or more stringent authentication? For now, it stands as a testament to direct, local device control—a valuable, accessible tool for anyone looking to automate their entertainment experience.