Roku SoundBridge M1000 Quick start guide

Copyright© 2006 Roku, LLC Page 1 www.rokulabs.com
Roku
Functional Specification
Roku Control Protocol
Date: 13-July-06
Document Version: 2.0
Software versions: SoundBridge 2.5.171
WMM 2.6.6

Copyright© 2006 Roku, LLC Page 2 www.rokulabs.com
Table of Contents
Overview..............................................................................................................5
What is RCP?....................................................................................................5
An Example: ..................................................................................................5
Wi-Fi Media Module ..........................................................................................5
RCP Sessions...................................................................................................6
Terminology.......................................................................................................7
Protocol Summary..............................................................................................8
Synchronous Commands..................................................................................8
Transacted Commands.....................................................................................9
Transaction Initiation....................................................................................10
Transaction Cancellation .............................................................................10
Subscription Commands.................................................................................10
List Results......................................................................................................11
Partial-Results Mode ...................................................................................12
User-Interface Models ......................................................................................13
Client-Generated UI ........................................................................................13
RCP Host-Generated UI..................................................................................13
RCP Limitations and Future Directions ..........................................................15
Getting Information About the Connected Server............................................15
Standby Mode.................................................................................................16
RCP Host Configuration..................................................................................17
Software Versions and Software Upgrading....................................................17
Other Areas For Improvement.........................................................................18
Command Reference........................................................................................19
Listing and Connecting to Media Servers........................................................20
Overview......................................................................................................20
ListServers...................................................................................................22
SetServerFilter.............................................................................................24
SetServerConnectPassword........................................................................26
ServerConnect.............................................................................................27
ServerLaunchUI...........................................................................................29
ServerDisconnect ........................................................................................31
GetConnectedServer...................................................................................33
Content Selection And Playback.....................................................................35
Overview......................................................................................................35
ListSongs.....................................................................................................37
ListAlbums...................................................................................................38
ListArtists.....................................................................................................39
ListComposers.............................................................................................40
ListGenres ...................................................................................................41
ListLocations................................................................................................42
ListMediaLanguages....................................................................................43
ListPlaylists..................................................................................................44

Copyright© 2006 Roku, LLC Page 3 www.rokulabs.com
ListPlaylistSongs..........................................................................................45
ListContainerContents.................................................................................46
GetCurrentContainerPath............................................................................48
ContainerEnter.............................................................................................49
ContainerExit...............................................................................................50
SearchSongs...............................................................................................51
SearchArtists ...............................................................................................52
SearchAlbums .............................................................................................53
SearchComposers.......................................................................................54
SearchAll .....................................................................................................55
SetBrowseFilterArtist...................................................................................56
SetBrowseFilterAlbum.................................................................................57
SetBrowseFilterComposer...........................................................................58
SetBrowseFilterGenre .................................................................................59
SetBrowseFilterLocation..............................................................................60
SetBrowseFilterMediaLanguage..................................................................61
Getting Detailed Song Info..............................................................................62
Overview......................................................................................................62
GetSongInfo.................................................................................................63
GetCurrentSongInfo.....................................................................................64
Managing the Now Playing (ad-hoc) Playlist...................................................65
NowPlayingClear.........................................................................................66
ListNowPlayingQueue .................................................................................67
Initiating Media Playback.................................................................................68
PlayIndex.....................................................................................................69
NowPlayingInsert.........................................................................................70
NowPlayingRemoveAt.................................................................................71
QueueAndPlay.............................................................................................72
QueueAndPlayOne......................................................................................73
Transport.........................................................................................................74
Play..............................................................................................................75
Pause ..........................................................................................................76
PlayPause....................................................................................................77
Next.............................................................................................................78
Previous.......................................................................................................79
Stop.............................................................................................................80
Shuffle .........................................................................................................81
Repeat.........................................................................................................82
GetTransportState.......................................................................................83
GetElapsedTime..........................................................................................84
GetTotalTime...............................................................................................85
GetCurrentNowPlayingIndex .......................................................................86
IR Demod/Dispatch.........................................................................................87
IrDispatchCommand....................................................................................88
IrDemodSubscribe.......................................................................................89
IrDemodUnsubscribe...................................................................................89

Copyright© 2006 Roku, LLC Page 4 www.rokulabs.com
Setup Commands............................................................................................90
GetLanguage...............................................................................................91
SetLanguage ...............................................................................................92
ListLanguages .............................................................................................93
Volume Commands.........................................................................................94
GetVolume...................................................................................................95
SetVolume...................................................................................................96
Protocol Control Commands ...........................................................................97
CancelTransaction.......................................................................................98
SetListResultType........................................................................................99
GetListResult.............................................................................................100
SetDataResultType....................................................................................101
Display Control Commands...........................................................................102
SetVisualizer..............................................................................................103
VisualizerMode..........................................................................................104
ListVisualizers............................................................................................105
GetVizDataVU ...........................................................................................106
GetVizDataFreq.........................................................................................107
GetVizDataScope......................................................................................108
DisplayUpdateEventSubscribe ..................................................................109
DisplayUpdateEventUnsubscribe ..............................................................109
GetDisplayData..........................................................................................110
Commands For Using Presets ......................................................................112
Usage Scenario: Testing an Internet Radio URL.......................................112
Usage Scenario: Playing a Music File on the Local Network.....................113
ListPresets.................................................................................................115
GetPresetInfo.............................................................................................116
PlayPreset .................................................................................................117
SetPreset...................................................................................................118
GetWorkingSongInfo .................................................................................119
SetWorkingSongInfo..................................................................................120
ClearWorkingSong.....................................................................................122
Socket Commands for Generalized Network Communication.......................123
SocketStreamOpen ...................................................................................124
SocketClose...............................................................................................126
SocketReceiveBytes..................................................................................127
SocketSendBytes ......................................................................................128
UPnP Searching Commands.........................................................................130
UPnPSearch..............................................................................................131
UPnPGetDeviceInfo...................................................................................133
UPnPGetDeviceDescription.......................................................................134

Copyright© 2006 Roku, LLC Page 5 www.rokulabs.com
Overview
What is RCP?
This document describes the Roku Control Protocol (RCP). RCP is a control
protocol implemented by the Roku SoundBridge line of digital audio players with
software version 2.3 or later, and the Roku Wi-Fi Media Module (WMM), a drop-
in hardware solution for implementing digital audio functionality targeted for
OEMs. Remote applications can use RCP to access the digital-media
functionality of those device to automate repetitive tasks, initiate and control
media playback, or expand the user-interface to other network-connected
devices. OEMs can use RCP to control a WMM embedded in their own product
and incorporate it into their existing user-interface.
An Example:
RCP uses simple text-based commands to communicate client queries and
commands. The following short sequence shows how an RCP client with a
connected music server can list the songs from the album, “Presence,” and then
initiate playback of those songs starting with the first one. Note that commands
sent by the client are italicized, and RCP results are in normal text.
SetBrowseFilterAlbum Presence
SetBrowseFilterAlbum: OK
ListSongs
ListSongs: TransactionInitiated
ListSongs: ListResultSize 7
ListSongs: Achilles Last Stand
ListSongs: For Your Life
ListSongs: Royal Orleans
ListSongs: Nobody’s Fault But Mine
ListSongs: Candy Store Rock
ListSongs: Hots On For Nowhere
ListSongs: Tea For One
ListSongs: ListResultEnd
ListSongs: TransactionComplete
QueueAndPlay 0
QueueAndPlay: OK
Wi-Fi Media Module
The Roku Wi-Fi Media Module (WMM) allows consumer electronics device
manufacturers to quickly and easily integrate networked media playback
functionality into their products. WMM is based on the award-winning Roku

Copyright© 2006 Roku, LLC Page 6 www.rokulabs.com
SoundBridge Network Media Player platform, and includes full support of its
user-friendly media selection and playback functionality.
WMM (like SoundBridge) automatically discovers and communicates with media
servers (like Microsoft’s Windows Media Connect) running on a user’s home
network with no other configuration, allowing immediate access to a customer’s
media library with no additional software required. Internet radio stations are
also fully supported, with on-board radio presets that can be stored and recalled
by the user at the touch of a button. WMM implements a complete UPnP-AV
media renderer, allowing third-party devices to control it using the open UPnP
protocol, and it also exposes an on-board web page allowing full control from any
web browser on the local network.
In short, WMM offers a ready-to-use solution for supporting network media
playback in your custom consumer electronics application. The Roku Control
Protocol allows a microcontroller or microprocessor in the target device to
interactively access any of the WMM’s built-in functionality and to retrieve the
results of those actions in a synchronous or asynchronous manner. The WMM
can additionally render a user interface suitable for sending to a bitmapped or
character-based display, or the client can use the content enumeration and
selection primitives in the WMM Control Protocol to create their own custom UI.
RCP Sessions
The RCP command protocol does not define a required physical transport for
communication between an RCP-capable device and the client controller. Any
communication medium that can transmit full-duplex byte stream data could be
utilized. In practice, Roku devices expose RCP via the following types of
connections:
1. Serial (RS232 or I2S) – The Wi-Fi Media Module (WMM) exposes RS232
and I2S ports via its physical connectors, and host devices can access
either RCP or the SoundBridge shell console over this direct physical
connection.
2. Telnet (TCP port 5555) – SoundBridge and WMM devices listen on TCP
port 5555 at their configured IP address for incoming connections, and
expose the RCP shell directly on this connection. Once connected, the
device will answer with the RCP initiation sequence, “roku: ready”,
indicating that the connection is ready for commands.
3. Telnet (TCP port 4444) – SoundBridge and WMM devices listen on TCP
port 4444 at their configured IP address for incoming connections,
exposing the SoundBridge shell on this connection. The SoundBridge
shell is a command-line interface for executing simple commands, and
presents this prompt string when ready for input: “SoundBridge> ”. Clients
can initiate RCP sessions over this connection by executing the “mmc”
shell command.

Copyright© 2006 Roku, LLC Page 7 www.rokulabs.com
NOTE: Technically speaking, the “telnet” connections listed above do not
implement the telnet protocol, but are actually just basic TCP/IP connections.
Any telnet client application can connect successfully to these connections at the
specified TCP ports, however, and operate without difficulty.
Terminology
When this document refers to the RCP host, it refers to the device that exposes
the RCP interface and processes RCP commands. The RCP host can be any
Roku SoundBridge device running software version 2.3 or later, or it can be a
Roku Wi-Fi Media Module (WMM).
The RCP client is the client application or device that connects to the RCP host
and sends RCP commands to the host for execution. The RCP client can be an
application running on a PC or other device, a human user connected via a telnet
session running commands interactively, or a microcontroller in an OEM device
communicating with an embedded WMM.
An RCP session is a connection between an RCP host and an RCP client that
lasts as long as the communications medium allows for a distinct connection.
For example, a telnet (TCP) connection to a SoundBridge or WMM on port 5555
is a distinct RCP session that lasts as long as the telnet (or TCP) connection
lasts. As soon as this network connection is terminated, the RCP session ends.
A host microcontroller with a direct serial connection to a WMM also has one
RCP session that lasts as long as the power to the WMM is connected (although
it will end and restart if the WMM reboots). It is possible for a single RCP host to
have several active RCP sessions at the same time.

Copyright© 2006 Roku, LLC Page 8 www.rokulabs.com
Protocol Summary
RCP was designed with simplicity and completeness as primary requirements.
Commands and results are exchanged as short transmissions across a high-
speed interface like a serial port, telnet connection, or parallel interface. Each
command is composed of a short ASCII command id string, generally just zero or
one parameters, and the two-byte terminator CRLF. All command results from
the RCP host are composed of the command-id of the client command that
caused this result followed by a result string and the two-byte CRLF terminator.
(An exception to this rule exists for subscription commands, when the command
result is composed of an identifier that doesn’t exactly match the subscription
command id. See the entries for the various subscription commands for details.)
RCP commands can be loosely categorized by the way in which they execute:
synchronous commands, transacted commands, and subscription commands.
Synchronous commands return their results immediately, and do not block the
host device during execution. Transacted commands are commands that might
require a long extent of time to complete, some as long as ten seconds or more!
These commands generally depend on sending and receiving data from the
network, which is why their completion time is non-deterministic. Transacted
commands run asynchronously, or “in the background,” in an RCP session, and
allow the client to issue other commands or cancel the command while it is in
process. Subscription commands are also asynchronous in nature, but rather
than performing one atomic action, return state changes to the RCP client until
the subscription is canceled.
RCP commands can also be categorized by the type of results they generate. A
class of RCP commands generates a set of results returned in a list format, for
example a list of music servers, or a list of music artists, or a list of songs. List
results are discussed as a separate topic below. Note that the set of commands
generating list results is not dependent on their categorization as synchronous,
transacted, or subscription commands.
Synchronous Commands
The most basic type of synchronous command can be illustrated by the following
example of the command GetTransportState, which is a command that takes no
parameters and returns a single status result:
GetTransportState
GetTransportState: Stop
The RCP client sends the command id (“GetTransportState”) followed by a line
terminator sequence of CRLF (i.e., “\r\n” or “0d 0a” in hex), and the RCP host

Copyright© 2006 Roku, LLC Page 9 www.rokulabs.com
responds with the result string composed of the originating command id, a colon
and space separator, the status result (“Stop”), and terminating newline
sequence. The results of synchronous commands are returned immediately
(typically within 1 ms) by the RCP host before processing any further client
commands (or returning any other RCP results).
Transacted Commands
There is another class of commands called transacted commands that can take
some time to complete execution, and therefore use a slightly different execution
convention. For example, one command might query a media server for a list of
songs, which will require a network transaction with the server device that can
take as long as several seconds to either complete or time out.
Transacted commands can return results asynchronously over the command
interface throughout the lifetime of the command, so the RCP client must be
designed to parse the results of these commands for some time after they are
issued. The RCP client can also cancel a pending transacted command at any
time during its lifetime if some user action (or other event) requires it.
In the following example, a client uses the transacted command ListArtists to get
the list of media artists from a connected media server. Note the elapsed time
column to the left of each transmission, which suggests a possible timing
scenario for this command (although the actual timing of this command will be
different and unpredictable in practice).
Elapsed Time
(ms) Transmissions
0 ListArtists
1 ListArtists: TransactionInitiated
400 ListArtists: ListResultSize 3
400 ListArtists: Counting Crows
400 ListArtists: Dire Straits
401 ListArtists: Led Zeppelin
401 ListArtists: ListResultEnd
401 ListArtists: TransactionComplete
NOTE: The RCP client can issue multiple transacted commands at once,
however, it cannot execute multiple instances of the same command at the same
time. In other words, an RCP client could issue the GetSongInfo transacted
command, and while this command is still executing, it could also issue the
ListArtists transacted command, and both could be pending simultaneously.
However, an RCP client could not have two instances of the GetSongInfo
command executing at the same time. (Try it, you’ll get the following error:
“ErrorTransactionPending”.) Also, since most transacted commands return list

Copyright© 2006 Roku, LLC Page 10 www.rokulabs.com
results, the usefulness of running them simultaneously is limited at best. (See
the detailed description of list results below for more details.)
Transaction Initiation
Parsing the results of a transacted command requires some attention to detail.
Transacted commands, when successfully issued, will enter the transacted state
by issuing the “TransactionInitiated” result string. Once this occurs, the
transaction continues processing in the background, and the RCP client can
issue additional RCP commands while waiting for the results.
It is important to note that transacted commands do not always enter the
transacted state. Sometimes, there are errors that can be sensed at the moment
the transacted command is executed, in which case an error is returned
immediately and “TransactionInitiated” is never sent! For example, the ListArtists
command requires that the RCP session have an active music server
connection. If there is no active server connection, ListArtists immediately
returns the error result, “ErrorDisconnected”, and sends nothing further.
Transaction Cancellation
All transacted commands can be canceled once the transaction has been
initiated by using the CancelTransaction command. The parameter to the
CancelTransaction command is the command name of the transacted command.
I.e., if the RCP client in the example above decided that at 200 elapsed
milliseconds it did not want to wait for the results of the ListArtists command, it
could cancel it by issuing “CancelTransaction ListArtists”.
Note that the success of the CancelTransaction command is non-deterministic
and depends on the nature of the communications medium. For example, the
RCP client could send the CancelTransaction command down a TCP connection,
but the transmission of this data across the network could take a fraction of a
second to complete, during which time the actual transaction could complete and
send its results back! The RCP client must handle this scenario robustly.
However, once a transaction has been successfully canceled (indicated by an
OK result returned from the CancelTransaction command), the RCP host
guarantees that it will not send any additional results from that transaction.
Subscription Commands
In some cases an RCP client may want status updates on state changes in the
RCP host for a long period of time, spanning the interaction of many
synchronous and transacted commands. For example, a client may wish to have
the WMM notify it automatically every time there is a change in the transport
state, e.g. when the currently playing track changes, or when there is a buffer
underrun during playback. (On the other hand, some clients may prefer to poll

Copyright© 2006 Roku, LLC Page 11 www.rokulabs.com
for these status changes by requesting the current transport state with a
synchronous command issued every 500 ms, e.g.)
To accommodate this kind of long-term status notification, there is a set of
commands called subscription commands that causes the RCP host to
asynchronously publish status updates over the control interface whenever a
related change in state occurs. (Note that these status updates can interleave
with results from transacted commands and in-between issuances of
synchronous commands.) Subscriptions last the lifetime of the RCP session or
until the RCP client explicitly cancels the subscription.
In the following example, the client subscribes to TransportState update events,
and then issues the Next command (to skip to the next track) during playback.
Elapsed Time
(ms) Transmission
0 SubscribeTransportUpdateEvents
1 SubscribeTransportUpdateEvents: OK
1 TransportEvent: Stop
1000 Next
1001 Next: OK
1010 TransportEvent: TrackChange
1020 TransportEvent: Buffering
2000 TransportEvent: Play
NOTE: Unfortunately, the SubscribeTransportUpdateEvents command is un-
implemented in the current version of RCP. It will be implemented in a future
software update to the SoundBridge and WMM, however.
List Results
Several commands (like the aforementioned ListArtists) return a list of results.
Different commands return lists of different types of objects, but each instance of
a list of results is composed of the same type of object. For example, ListServers
returns a list of music servers, ListAlbums returns a list of album titles, and
ListSongs returns a list of songs.
Each RCP session keeps a persistent copy of the last set of list results returned
by any command. This persistent set of list results can be used in future RCP
commands. For example, after getting a list of music servers from the
ListServers command, the RCP client can connect to one of these servers with
the ServerConnect command by indicating the zero-based list position of the
desired server in the list results.

Copyright© 2006 Roku, LLC Page 12 www.rokulabs.com
It is important to note that there is only one set of list results per RCP session.
So as soon as the next RCP command returning list results completes, the
previous set of list results is deleted and cannot be referenced again.
Partial-Results Mode
Sometimes, these lists can be unwieldy in size, approaching 10,000 items in the
most extreme cases (listing all songs in a large media library). If the entire set of
10,000 song titles was sent over a serial connection running at 115kbps and the
average result string was 20 characters long, it would take 17 seconds of
constant transmission to return the entire list of results! RCP includes a method
for retrieving partial list results from these commands to alleviate this problem.
The client can toggle the current list result type (on a per-RCP session basis)
between full and partial by issuing the SetListResultType command, which
causes all subsequent commands returning list results to return results in the
specified manner. When in partial result mode, commands returning list results
do not return the results on completion, but just return the number of items in the
list, and the client uses the command GetListResult to browse a subset of these
results, specified by zero-based numeric indices. In the following example, the
RCP client uses partial results to browse all songs on a media server. Note that
the parameters to the GetListResult command are the starting and ending (zero-
based) indices of the results in the list to display.
Elapsed Time
(ms) Transmissions
0 SetListResultType partial
1 SetListResultType: OK
2 ListSongs
2 ListSongs: TransactionInitiated
5000 ListSongs: ListResultSize 5123
5000 ListSongs: TransactionComplete
5001 GetListResult 0 2
5002 GetListResult: ListResultSize 3
5002 GetListResult: Ace Of Spades
5002 GetListResult: Alison
5002 GetListResult: All Mixed Up
5003 GetListResult: ListResultEnd

Copyright© 2006 Roku, LLC Page 13 www.rokulabs.com
User-Interface Models
Many RCP clients want to allow interactive access to all the digital-media
features of the RCP host device. That is, they want their users to be able to
interactively start and stop music playback, select songs by different categories,
even connect to different music servers. To implement this, the client device
needs to present a user-interface to their users that can display lists of options
for the user to choose from, and allow random-access to transport commands
like “play” and “pause”.
RCP offers two different models with which an RCP client can construct a user-
interface: client-generated UI, and RCP host-generated UI.
Client-Generated UI
In the client-generated UI model, the RCP client creates its own custom user-
interface using whatever type of display is available to it, be that a television
display, computer monitor, bitmapped or character-based LCD display, or other!
The RCP client issues RCP commands to list the options that it wants to present
to the user, and then issues further RCP commands to act on the user’s
selections. For example, to choose a song for playback, the RCP client would
issue the ListSongs command, then format the results into a list of songs on the
device’s display and let the user pick one, then it could send the QueueAndPlay
command to select one of those songs for playback.
RCP Host-Generated UI
In the host-generated UI model, the RCP client can take advantage of the
existing award-winning user interface of the SoundBridge network media player,
which is built-in to all RCP host devices, including WMM. The RCP host can
create and maintain the user interface, and the RCP client can just echo the
current contents of the “display data” on its own physical display, and route user
key presses back to the RCP host for it to take actions on.
In this model, the RCP host device creates the user-interface and exports it
through the GetDisplayData command, which returns the contents of the current
display in a bitmapped or character-based format, depending on the
configuration of the RCP host device. To interact with the user, the client device
issues the command IrDispatchCommand to notify the RCP host when the user
hits buttons like the arrow-left, arrow-right, and PLAY buttons.
To keep the physical display up to date with changes to the RCP host-generated
UI, you can subscribe to display-update events (to receive notification whenever

Copyright© 2006 Roku, LLC Page 14 www.rokulabs.com
the UI has changed), you can poll for a display-update counter, or you can simply
download the display data (using the command GetDisplayData) several times a
second.

Copyright© 2006 Roku, LLC Page 15 www.rokulabs.com
RCP Limitations and Future Directions
RCP is an evolving protocol, as is the software running on SoundBridge and
WMM devices. Roku is constantly adding features and expanding the
capabilities of its devices, and offers end-customers the ability to easily upgrade
the software over the internet. As new features are added to the software, new
commands and constructs are added to RCP to allow access to these features.
Additionally, Roku works closely with its OEM and retail customers to improve
RCP to meet their needs.
As such, there are known areas where the functionality of RCP is planned for
improvement in future software releases. Until then, we would like to mention
some of these known areas and discuss our future plans for them and possible
work-arounds that may be applied at the moment.
Getting Information About the Connected Server
There is a need for commands in RCP to get detailed information about the
currently connected server, for two reasons.
First, if the RCP host connects to a server outside the control of the RCP
session, then the RCP session must sync-up its active server using the
GetConnectedServer command. However, there is currently no way to tell what
the name of that server is. There is no known workaround to this problem,
unfortunately. To return to a state where the RCP client can know definitively
which server it is connected to, it must disconnect from that server and re-
connect to another one itself.
Second, once an RCP client does connect to a server, it would be desirable for
the RCP session to know the browse and search capabilities of that server. That
way the RCP client could expose only the types of content selection primitives
that the server actually supports to its clients. E.g., some servers support
browsing by containers, while others allow simple browse, while others allow full
browsing and searching.
By using the SetServerFilter command, the RCP client can identify the types of
the available music servers and make a few assumptions about their capabilities
from that. The RCP client can assume the browsing and searching capabilities
of the built-in server types, i.e., the AM and FM Radio server, the Internet Radio
server, and the flash card server. These capabilities are constant and don’t
change. (Although note that Roku may for example add a searching capability to
the Internet Radio server in a future software release, so even this is not a hard
and fast rule.) But the capabilities of servers from the local network are hard to
surmise. All RSP and DAAP servers we have encountered so far support
browsing and searching but not containers. All UPnP servers seem to support

Copyright© 2006 Roku, LLC Page 16 www.rokulabs.com
containers, but some support browsing and searching while others don’t. One
possible workaround is to execute a browse or search with an unlikely browse or
search term and just see if the command succeeds (with hopefully an empty
results list) or fails, and deduce the capabilities from that.
Planned Server Description RCP Support
To alleviate these problems, Roku plans on adding new commands to provide
the name and content selection capabilities of the current active server. This will
most likely be with the addition of a single command like GetActiveServerInfo.
Standby Mode
Some RCP clients would like to know if the RCP host is in standby mode.
Standby mode is accessed when the RCP host-generated UI processes a power
button IR command. In this mode, the RCP host disconnects from any currently
connected music server and displays the current time on its display.
There is currently no way to detect standby mode as an RCP client. However, if
there is a currently connected server, the unit must not be in standby mode. So
an RCP client could use GetConnectedServer, and if it executes successfully,
the RCP client knows that the unit is not in standby.
But the unit could be not connected to a server and still not be in standby mode.
(For example, the unit could be at the server-selection menu or in the
configuration menus.) In these instances it is impossible to detect standby mode
from RCP. As a workaround, some clients will open a connection to the
SoundBridge shell (port 4444 via a telnet/TCP connection) and list current
processes using the “ps” shell command – if there is a process named
“StandbyApp”, then the unit is definitively in standby mode.
Many RCP clients will not have to worry about standby mode. For example, if
you connect to a server using ServerConnect then the RCP will automatically
take itself out of standby mode when it connects.
NOTE: There is a bug in software 2.5.171 where if the RCP host is in standby
mode and an RCP client executes the ServerLaunchUI command, then the unit
will connect to the server but it will get into a state where it cannot enter standby
mode again during that boot session.
If an RCP client just wants to ensure that the unit is not in standby mode, it can
dispatch the CK_POWER_ON command. However, the RCP client must be
aware that as a side-effect of coming out of standby mode in response to a
power button IR command, the RCP host will sometimes auto-reconnect to the
last connected server. (If the unit was connected to a server when it entered
standby, then it will attempt to re-connect when it comes out of standby.)

Copyright© 2006 Roku, LLC Page 17 www.rokulabs.com
Planned Standby Mode RCP Support
To alleviate these problems with controlling and detecting standby mode from
RCP, Roku plans to add additional commands in a future software release.
These commands will allow simple querying of the standby state, and will offer a
way to enter and exit standby mode programmatically. (And they will allow
suppression of the automatic server reconnect process when coming out of
standby if desired.)
RCP Host Configuration
There are several configuration settings that need to be set before a
SoundBridge or WMM from the factory is ready to do things like connect to music
servers. E.g., the unit needs to select a region and language, and if the unit is
connecting to a wi-fi network then the SSID and password of the network must
be provided.
This is generally not a limitation for RCP clients of SoundBridge devices,
because these devices are generally deployed as retail customer units, and the
end-customer is responsible for setting up the unit initially.
But for WMM users these setup commands will be necessary.
Planned Host Configuration RCP Support
Roku will add RCP commands to allow the setting of the wi-fi region, the user-
interface language, the wi-fi SSID and password, and manual IP configuration.
Additional commands will allow querying the network status (akin to the ifconfig
shell command), listing available wi-fi networks, resetting to factory defaults, and
rebooting the RCP host.
Note that the ifconfig shell command is available currently to check the current
network status from the SoundBridge shell. Also, it is possible to reset to factory
defaults with the clearsettings shell command and reboot the unit using the
reboot shell command.
Software Versions and Software Upgrading
It is not possible to query the current RCP host software version using RCP. It
can be queried instead using the SoundBridge shell version command. It is also
desirable to be able to check for software upgrade availability and to initiate a
software upgrade from an RCP session. This feature will be added in a future
software release.
Finally, safe-mode needs some minimal RCP support. Safe-mode is a software
version contained on a separate flash ROM chip on the SoundBridge / WMM that
is used to boot the unit when the software in the main program flash is detected
to be corrupted. This can happen, e.g., if there is a power failure during the

Copyright© 2006 Roku, LLC Page 18 www.rokulabs.com
software upgrade procedure. Currently there is no RCP support at all in safe-
mode. In the future, there will be a minimal RCP host implementation in safe
mode with the ability to re-attempt a software upgrade and reboot the unit.
Other Areas For Improvement
RCP has only a limited ability to set the user presets. See the section
“Commands for Using Presets” for more information. Roku plans on adding
commands to let the RCP client set all types of user presets, not just internet
radio presets.
RCP support for socket commands only supports simple TCP sockets at present.
See the section “Socket Commands for Generalized Network Communication”.
Roku plans on adding full socket support including datagram (UDP) sockets and
listening stream (TCP) sockets.
RCP is planned to offer support for drawing on the display using drawing
primitive commands. This capability is currently available from the SoundBridge
shell command sketch, but we would like to roll this into RCP eventually.
RCP also needs to support sorting an album’s listing of songs into album order.
E.g., to list the songs on an album, the RCP client currently sets browse filters for
the desired artist and album name, then executes ListSongs. The correct songs
are returned, but they are in the order returned by the server, not necessarily in
album order. There is no current way to get around this limitation.
When connecting to servers that support a container hierarchy, it is possible
through the RCP-host user interface to queue for playback all the songs below a
certain container. E.g., the user can browse to an “Artists” container, highlight
the name of an artist, and then hit the PLAY button to play all the songs within
that container, even if it has album sub-containers within it. The only way to
duplicate this process in RCP is to manually recurse through all the sub-
containers and add all songs with the NowPlayingInsert command. This is
unnecessarily complex. We would like to add a command to handle this
procedure automatically.
There is also a need for an error-detection protocol for guaranteeing the delivery
of RCP transactions on a non-error-correcting connection, like RS232.
Telnet/TCP connections have error-detection built-in to the communication
protocol, so clients can assume the connection is dependable.

Copyright© 2006 Roku, LLC Page 19 www.rokulabs.com
Command Reference
SampleCommand
Syntax: The syntax of the command goes here. ‘n’ stands
for a numeric parameter, often a zero-based index
into previous list results. Optional parameters
are listed in [square brackets], and parameters
where one token can be chosen from a finite list
are|vertical-bar|delimited.
Classification:
Synchronous, Transacted, or Subscription.
Result Type:
If the function returns results that can be used
by subsequent commands during the RCP session,
like list results, they are listed here. Also,
if the function returns an object with many
fields, it is described here. Functions that
just return status tokens are considered to have
no result type.
Responses:
All possible response tokens are listed here,
with a short description of each. Note that
future software releases might add additional
failure responses, so assume unknown responses
indicate failure.
Example: A single invocation of the command is listed here
with an example result. For example:
SetServerFilter daap upnp
SetServerFilter: OK
Finally, additional description of the command goes here.

Copyright© 2006 Roku, LLC Page 20 www.rokulabs.com
Listing and Connecting to Media Servers
Overview
•ListServers
•SetServerFilter
•SetServerConnectPassword
•ServerConnect
•ServerLaunchUI
•ServerDisconnect
•GetConnectedServer
The commands in this section are used for listing, connecting to, and
disconnecting from music servers in the RCP session. The RCP host
automatically detects media servers on the local-area network that advertise
using the UPnP/AV, Bonjour (formerly Rendezvous), and SlimServer protocols.
Additional servers are added automatically to the list for accessing Internet Radio
and other media devices depending on the unit’s configuration. (E.g., the
SoundBridge Radio adds servers for AM and FM radio.) RCP clients may
specify what types of media servers to list by using the SetServerFilter
command.
RCP Session Active Server
Each RCP session has an active server, which you can visualize as a per-RCP
session member variable that can be pointed to one of the currently discovered
music servers. When a new RCP session begins, the active server is empty, and
must be initialized before use.
The design of the per-RCP session active server paradigm was motivated by the
eventual goal of allowing SoundBridge and WMM to connect to multiple music
servers at the same time, such that the user could actually create a playlist that
contained some songs from server A and some songs from server B. However,
the current implementation only allows the SoundBridge / WMM to connect to
one music server at a time, so some of the server-related RCP commands may
seem a little unwieldy.
The situation is further complicated by the fact that other clients outside of the
control of the RCP session can initiate server connections. E.g., a user using the
remote control can connect a SoundBridge unit to a music server before the RCP
session begins. Or, depending its user-settings, the SoundBridge / WMM might
automatically connect to a music server on bootup. (The RCP active server is
NOT initialized to point to this server automatically!)
If the unit is connected to a music server outside of the RCP session, the RCP
session must use the GetConnectedServer command to “attach” its active server
to the server that the unit has been connected to. Once the session has