The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Roku-ECP-1.0.0
River stage zero No dependents
++
/ Roku::ECP

NAME

Roku::ECP - External Control Protocol for Roku

SYNOPSIS

  use Roku::ECP;

  my $r = new Roku::ECP
        hostname => "my-settop-box.dom.ain";

  my @apps = $r->apps();

  # Key and string input functions:
  $r->keydown(Roku::ECP::Home);
  $r->keyup(Roku::ECP::Down);
  $r->keypress(Roku::ECP::Info,
               Roku::ECP::Search,
               Roku::ECP::Select);
  $r->keydown_str("x");
  $r->keyup_str("x");
  $r->keydown_str("Hello world");

  $r->launch($app_id);
  $r->launch($app_id, "12345abcd");
  $r->launch($app_id, "12345abcd", "movie");

  my $icon = $r->geticonbyid("12345");
  my $icon = $r->geticonbyname("My Roku Channel");

  $r->acceleration($x, $y, $z);
  $r->orientation($x, $y, $z);
  $r->rotation($x, $y, $z);
  $r->magnetic($x, $y, $z);

DESCRIPTION

Roku::ECP implements the Roku External Control Guide, which permits callers to query and control a Roku over the network.

KEY NAMES

The &key* functions keypress, keyup, and keydown take symbolic key names. They are:

KEY_Home
KEY_Rev
KEY_Fwd
KEY_Play
KEY_Select
KEY_Left
KEY_Right
KEY_Down
KEY_Up
KEY_Back
KEY_InstantReplay
KEY_Info
KEY_Backspace
KEY_Enter

METHODS

new

  my $r = new Roku::ECP([I<var> => I<value>, ...])
  my $r = Roku::ECP->new

Create a new object with which to communicate with a Roku. For example:

  my $r = new Roku::ECP hostname => "my-settop-box.dom.ain";
  my $r = new Roku::ECP addr => "192.168.1.10",
        port => 1234;

Possible vars:

hostname

Name of the Roku.

addr

IP(v4) address of the Roku.

port

TCP port on which to communicate with the Roku.

Only one of hostname and addr needs to be specified. If both are given, the address takes precedence.

apps

  my @apps = $r->apps();
        # $apps[0] ==
        # {
        #       id      => '12345',     # Can include underscores
        #       type    => 'appl',      # 'appl'|'menu'
        #       name    => "Channel Name",
        #       version => '1.2.3',
        # }

Returns a list of ref-to-hash entries listing the channels installed on the Roku.

launch

    $r->launch($app_id);
    $r->launch($app_id, $contentid);
    $r->launch($app_id, $contentid, $mediatype)

Launch an app on the Roku, optionally giving it an argument saying what to do.

The app ID can be obtained from apps.

The optional $contentid and $mediatype arguments can be used to implement deep linking, if the channel supports it. For instance, $contentid might be the ID number of a movie that the channel will then automatically start playing. Likewise, $mediatype can be used to tell the channel what sort of entity $contentid refers to.

geticonbyid

  my $icon = $r->geticonbyid("12345_67");
  print ICONFILE $icon->{data} if $icon->{status};

Fetches an app's icon. Most users will want to use geticonbyname instead.

Takes the ID of an app (usually a number, but sometimes not). Returns an anonymous hash describing the app's icon:

status

True if the icon was successfully fetched; false otherwise.

error

If status is false, then error gives the HTTP error code (e.g., 404).

message

If status is false, then message gives the HTTP error message (e.g., "not found").

Content-Type

The MIME type of the image. Usually image/jpeg or image/png.

data

The binary data of the icon.

geticonbyname

  my $icon = $r->geticonbyid("My Roku Channel");
  print ICONFILE $icon->{data} if $icon->{status};

Fetches an app's icon.

Takes the name of an app (a string).

Returns an anonymous hash describing the app's icon, in the same format as geticonbyid.

Keypress functions

These functions use predefined key names. See "KEY NAMES".

All of these functions take any number of arguments, and send all of the keys to the Roku in sequence.

These functions all return 1 if successful, or undef otherwise. In case of error, the return status does not say which parts of the request were successful; the undef just means that something went wrong.

keypress

  my $status = $r->keypress(key, [key,...]);

Sends a keypress event to the Roku. This is equivalent to releasing a key on the remote, then releasing it.

keypress_str

  my $status = $r->keypress_str($string, [$string...]);

Takes a string, breaks it up into individual characters, and sends each one in turn to the Roku.

keydown

  my $status = $r->keydown(key, [key...]);

Sends a keydown event to the Roku. This is equivalent to pressing a key on the remote. Most people will want to use keypress instead.

keydown_str

  my $status = $r->keydown_str($string, [$string...]);

Takes a string, breaks it up into individual characters, and sends each one in turn to the Roku. Most people will want to use keypress_str instead.

keyup

  my $status = $r->keyup(key, [key,...]);

Sends a keyup event to the Roku. This is equivalent to releasing a key on the remote. Most people will want to use keypress instead.

keyup_str

  my $status = $r->keyup_str($string, [$string...]);

Takes a string, breaks it up into individual characters, and sends each one in turn to the Roku. Most people will want to use keypress_str instead.

Vector input methods

The following methods send three-dimensional vectors to the currently-running application. They each take three arguments: $x, $y, $z.

These functions use one of two coordinate systems: relative to the remote, or relative to the Earth. See the "External Control Guide" in the Roku documentation for details.

These functions all return 1 if successful, or undef if not.

acceleration

  my $status = $r->acceleration($x, $y, $z);

Send an acceleration event to the currently-running application, indicating motion in space.

orientation

  my $status = $r->orientation($x, $y, $z);

Send an orientation event to the currently-running application, indicating tilting or displacement from lying flat.

rotation

  my $status = $r->rotation($x, $y, $z);

Send a rotation event to the currently-running application, indicating rotation around an axis.

magnetic

  my $status = $r->magnetic($x, $y, $z);

Send a magnetometer event to the currently-running application, indicating the strength of the local magnetic field.

SEE ALSO

External Control Guide

http://sdkdocs.roku.com/display/sdkdoc/External+Control+Guide

AUTHOR

Andrew Arensburger, <arensb+pause@ooblick.com>

COPYRIGHT AND LICENSE

Copyright (C) 2014 by Andrew Arensburger

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.