emulated_roku

This library is for emulating the Roku API. Discovery is tested with Logitech Harmony and Android remotes. Only key press / down / up events and app launches (10 dummy apps) are implemented in the RokuCommandHandler callback. Other functionality such as input, search will not work.

Features

• Emulates Roku External Control Protocol (ECP)
• SSDP/UPnP discovery support
• MQTT integration for key press events
• Customizable app list
• Docker deployment support

Quick Start

Docker Deployment (Recommended)

docker-compose up -d

See DOCKER.md for full Docker documentation.

Python Usage

See the example on how to use.

Custom Applications

Application list can be customized with a string in this format:

1:first-app,2:second-app,3:third-app

Which would generate this response:

<apps>
    <app id="1" version="1.0.0">first-app</app>
    <app id="2" version="1.0.0">second-app</app>
    <app id="3" version="1.0.0">third-app</app>
</apps>

MQTT Integration

The handler supports MQTT publishing for key press events with automatic reconnection handling. Configure MQTT settings when initializing:

handler = emulated_roku.EmulatedRokuCommandHandler(
    mqtt_address="192.168.1.100",
    mqtt_port=1883,
    mqtt_user="username",
    mqtt_password="password",
    mqtt_topic="roku/keypress",
    mqtt_reconnect_delay=5,           # Initial reconnection delay in seconds (default: 5)
    mqtt_max_reconnect_delay=300      # Maximum reconnection delay in seconds (default: 300)
)

Key press events are published as JSON:

{
  "event": "keypress",
  "device": "roku_name",
  "key": "VolumeUp"
}

MQTT Reconnection

The MQTT client automatically handles disconnections and reconnects using exponential backoff:

• Starts with initial delay (default: 5 seconds)
• Increases delay exponentially on subsequent connection failures
• Caps at maximum delay (default: 300 seconds / 5 minutes)
• Connection status is logged for monitoring