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_HomeKEY_RevKEY_FwdKEY_PlayKEY_SelectKEY_LeftKEY_RightKEY_DownKEY_UpKEY_BackKEY_InstantReplayKEY_InfoKEY_BackspaceKEY_SearchKEY_Enter
METHODS
new
my $r = new Roku::ECP([I<var> => I<value>, ...])
my $r = Roku::ECP->newCreate 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
statusis false, thenerrorgives the HTTP error code (e.g., 404). - message
-
If
statusis false, thenmessagegives the HTTP error message (e.g., "not found"). - Content-Type
-
The MIME type of the image. Usually
image/jpegorimage/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
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.