Back to Projects Index

Back to Roku Index

Roku Plug-in

Overview

The Roku plug-in provides an interface to Roku streaming devices.

The main purpose of this plug-in is to enable HomeVision and other related plug-ins to change channels/applications on a Roku streaming device.

The rest of this plug-in’s features are there “just for fun”!

This plug-in was tested with a Roku 3 streaming device. Some commands for Roku TVs have been included but not tested.

Configuration

Settings Tab

• "Roku IP address" and "Roku port number" should be set to the Roku's IP address and port. If "Use discovered Roku IP" is checked, the plug-in will search for a Roku device and automatically populate the IP address and port.
• "Netio string", "Serial string prefix string", and "Serial string terminator character(s)" are set to reasonable defaults and probably don't need to be changed, except in the rare case that they conflict with other plug-ins.
• If you want to use MQTT, add a topic. You must have the MQTT plug-in enabled. See MQTT Setup for details.

Apps Tab

This tab shows the current Applications installed on the Roku and the currently active Application.

The list is populated when “Update” is clicked or an Apps query is received via serial, NetIO, or MQTT.

You can “tune” to an Application by right-clicking on an App and clicking “Tune”. A command will be sent to the Roku to launch that App.

Serial Commands

You can send serial commands to the Roku plug-in from your schedule or from other plug-ins.

    roku: *command*;

command can be any of the following:

An App ID:

The numeric Application id.

A Keypress:

One of: Home, Rev, Fwd, Play, Select, Left, Right, Down, Up, Back, InstantReplay, Info, Backspace, Search, Enter, FindRemote, VolumeDown, VolumeMute, VolumeUp, PowerOff, ChannelUp, ChannelDown, InputTuner, InputHDMI1, InputHDMI2, InputHDMI3, InputHDMI4, InputAV1

A Query:

One of: apps, active-app, media-player, device-info, icon/{id}, tv-channels, tv-active-channel

Notes:

• Keypress and Query payloads are case sensitive.
• Of the queries, only "apps" and "active-app" currently return a response. See MQTT State.

Examples:

Launch the NetFlix channel (12):

    roku: 12;

Query for the active app:

    roku: active-app;

NetIO Commands

    netioaction roku *command*

command is the same as for serial.

MQTT

The Roku plug-in can be controlled by MQTT and can send MQTT status messages for the active App and the App list.

MQTT Setup

Setup is done in the Settings tab. Enter the desired topic in the “MQTT Topic:” field. If you place “<>” in the topic (e.g., <topic>), the standard MQTT format will be used. This is the preferred way to enter topics, since this topic is used for both receiving command messages and sending state messages.

    cmnd/roku/POWER *command*
    stat/roku/POWER *state info*

In fact, if “POWER” seems an odd postfix for a streaming device, then you can define a postfix explicitly while preserving the standard prefixes. A topic defined like this:

    <roku/State

would receive commands like this:

    cmnd/roku/State *command*

and send state responses like this:

    stat/roku/State *state info*

MQTT commands

    cmnd/roku/POWER *command*

Command payloads take the same format as serial and NetIO.

MQTT State

State information is sent in response to reception of the App list or the Active App.

The App List is NOT automatically queried, so the response comes only when the plug-in receives an App List query, or the user clicks “Update” in the Apps tab.

The plug-in queries for the active app in response to other commands, so it will send Active App responses at those times.

State information is sent in JSON format.

Active App response (formatted for readability):

{
    "active-app": {
        "NetFlix": {
            "id": 12
        }
    }
}

App list response (formatted for readability):

{
    "apps": {
        "Vudu Movie & TV Store": 
            "id": 31012,
            "type": "menu"
        },
        "Prime Video": {
            "id": 13,
            "type": "appl"
        },
        "Netflix": {
            "id": 12,
            "type": "appl"
        },
        "HBO Max": {
            "id": 61322,
            "type": "appl"
        }
    }
}