Roku HD1000 - PhotoBridge - Digital AV Player User manual

Roku External Control Protocol
for the HD1000
Revision 1.5 | November 23, 2003
For custom installers, developers, and technical users

Roku External Control Protocol for the HD1000 1
© 2003 Roku, LLC
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Roku wants your feedback! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
ECP basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
ECP command syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
About Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Script File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
An example ECP script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
ECP status feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Running a script from the Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Appendix A: A longer script example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Appendix B: Image Viewer (“Photo”) ECP commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Table B1: Commands valid in both modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Table B2: Commands valid in Slideshow mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Table B3: Commands valid in manual mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Appendix C: Music player (“Listen”) ECP commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Table C1: Commands for Listen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Appendix D: Background music player (“mp3player”) ECP commands . . . . . . . . . . . . . . . . . . . . . . . 15
Table D1: Commands for mp3player. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Appendix E: System ECP Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Table E1: Commands for the system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Table of Contents
© 2003 Roku, LLC. All rights reserved. ROKU and the ROKU logo are trademarks of Roku, LLC
in the United States and other countries.

Roku External Control Protocol for the HD1000 1
© 2003 Roku, LLC
Introduction
The features of the Roku™ HD1000 can be controlled externally (“scripted”) via a protocol
called the External Control Protocol (ECP).
HD1000 users and third-party developers can use the ECP to control HD1000 applications (and
other applications implementing the Roku ECP APIs). This document covers the basics of using
the ECP. The appendices in this document contain a complex sample script and a complete
listing of the ECP commands supported by the HD1000’s built-in applications. For purposes of
this document, the image viewer will be used as the primary example.
Roku wants your feedback!
The ECP commands are provided to make life easier for third parties. If you have suggestions
for enhancements or additions to ECP support on the HD1000 (or if you find an error in this
document), please don’t hesitate to write to us at [e-mail]. Requests will be
considered for inclusion in later software releases.
ECP basics
ECP commands are issued from the shell by way of a helper program called (appropriately)
“ecp.” There are three basic ways to issue these commands:
1. The commands may be grouped together in a standard Linux shell script. This is the
most convenient way to issue a sequence of commands that you may want to repeat
multiple times. Shell scripts may be stored on any media source accessible to the
HD1000, including the built-in storage, a flash card, or a shared folder on a networked
computer.
2. The commands may be issued at the command prompt, via the serial port. Connecting
a computer to the HD1000’s serial port with a standard serial cable gives you a Linux
command shell, at which ECP commands may be entered. (The port is 9600bps, 8-N-1,
no flow control.)
3. If the HD1000 is on a network, the commands may be issued at the command prompt,
via a telnet connection. Simply use a telnet program on a networked computer to
connect as “guest” with no password. The IP address of the HD1000 can be found at
the top of the screen in the Setup feature.
Note: In order for an ECP command to be successfully processed, the program that handles
the command must first be running. For example, in order for the command ‘photoApp’ to be
processed, the program “photo” must be running.
Additionally, third-party developers may also issue ECP commands directly from within
their applications via the CascadeInput::DispatchECPCommand API. See the developer
documentation for more information.

Roku External Control Protocol for the HD1000 2
© 2003 Roku, LLC
Roku External Control Protocol for the HD1000 3
© 2003 Roku, LLC
ECP command syntax
The syntax for ecp is as follows:
ecp <app identifier> <command> [optional arguments]
For example:
ecp photoApp IMAGEDIR “/tmp/Volumes/CompactFlash”
ecp photoApp DISPLAY_IMAGE “/tmp/Volumes/CompactFlash/myphoto.jpg”
ecp photoApp QUIT
About Paths
The various media sources available to the HD1000 appear in /mnt where flash0 is the built-
in storage, flash1 is Compact Flash, flash2 is SD/MMC, flash3 is Memory Stick and flash4 is
SmartMedia. Mounted network shares can be found in /mnt/smb/.
For your convenience, all currently-mounted media sources can be found with better names
in /tmp/Volumes . For readability, this is how media sources these scripts below will refer to
media sources, with a few exceptions.
Script File Formats
Scripts are simply text files. However, the format of the files is slightly different than that to
which most Windows users may be used. Scripts must be saved with unix-style line endings. If
you use Linux to edit your script files, the format will be correct. However, if you use Windows
or MacOS to edit your script files, the format of the files may be incorrect, resulting in the
HD1000 being unable to execute the files. There are text-editors available for Windows that
are able to save text files with Unix-style line endings. Among these is “TextPad”. There is a
command-line utility called “dos2unix” that will convert files from Windows line endings to
Unix line endings.
An example ECP script
The following brief example script is a trivial playlist, using the faceless music player to provide
background music for a four-image slideshow. A longer, more complex example appears in
the Appendix of this document, and is available for download from the Roku web site.
#!/bin/sh
# Launch the Photo app in "playlist" mode.
# Be sure to launch in background (with &), or the
# script will not continue past this line!
photo –p &
# Wait a bit to make sure Photo has launched.

Roku External Control Protocol for the HD1000 2
© 2003 Roku, LLC
Roku External Control Protocol for the HD1000 3
© 2003 Roku, LLC
sleep 2
# Launch the music player (also in the background)
# --obeyphoto means that it will quit when Photo does
mp3player --obeyphoto "/tmp/Volumes/CompactFlash/"*.mp3 &
# Play the images I like
# Using quotes around the path is a good habit,
# because paths with spaces must have quotes.
ecp photoApp IMAGEDIR "/tmp/Volumes/CompactFlash"
ecp photoApp DISPLAY_IMAGE "/tmp/Volumes/CompactFlash/Image1.jpg"
sleep 9
ecp photoApp DISPLAY_IMAGE "/tmp/Volumes/CompactFlash/Image3.jpg"
sleep 9
ecp photoApp DISPLAY_IMAGE "/tmp/Volumes/CompactFlash/Image5.jpg"
sleep 9
ecp photoApp DISPLAY_IMAGE "/tmp/Volumes/CompactFlash/Image9.jpg"
sleep 9
# All done. Quit Photo (which will tell the
# music player to quit).
ecp photoApp QUIT
ECP status feedback
Applications provide feedback on command success or failure via text status messages.
$ ecp photoApp IMAGEDIR "/tmp/Volumes/CompactFlash"
photoApp: invalid path
$ ecp photoApp IMAGEDIR "/tmp/Volumes/CompactFlash"
photoApp: ok
$ ecp fakecommand
fakecommand: unknown ecp command
In the case of the last command, the result “unknown ecp command” indicates one of the
following:
• The program that handles the specified command is not running. In the case of
photoApp, it means that “photo” is not running.
• The command was mis-typed. Check your spelling
• The command is an invalid command.
These status messages can be useful when initially authoring and testing a script. Scripts can
also check the status messages of commands that may fail to be sure that they should continue
to run:
#!/bin/sh
# Adding /usr/local/bin to the path allows the script
# to call “photo” and “ecp” instead of
# “/usr/local/bin/photo” and “/usr/local/bin/ecp”