MERIDIAN AUDIO Control: user

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

tel: [phone]

Sooloos Crestron® Module Guide

Overview

This Crestron module will control a Sooloos system using any 2-Series Crestron processor with

Ethernet capability. Each instance of the module will control one audio zone of a Sooloos sys­tem. The intended use of this module is for display on a Crestron touch panel. The module pro­vides standard transport controls as well as a browsing interface which allows navigation and
selection of media within the Sooloos system.

Hardware Requirements

• Crestron 2-Series processor w/ Ethernet capability

Table of Contents:

• Sooloos Source

• Ethernet connectivity between Crestron processor

and Sooloos Source

• Windows® PC with Microsoft® .NET 2.0 connected

to Ethernet network with Sooloos system

Software Requirements

• Crestron VT Pro-e v3.8 or greater

• Crestron SIMPL™ Windows

®

• Sooloos DumpZoneIDs utility (included with module)

Required Installation Information

• Sooloos Source IP address

1. Overview

2. Module Connection

3. Finding Zone
Identifiers

4. Zone Selection
Behavior

5. Touch Panel
Connection

6. External Program
Integration

7. Page Selection
Behavior

8. Module Glossary

• Sooloos zone identifier (see pg. 2)

Network Information

The Crestron processor must be configured to access the Sooloos Source either via IP address

or by host name if a name server is being employed. For most installations, it is suggested to
configure the Sooloos Source with a static IP address.

Standard module operation requires access from the Crestron processor to TCP/IP port 9011
on the Sooloos Source IP address. Dynamic graphics support for cover art requires access
from the Crestron processor to TCP

/

IP port 80. All cover art is served from the Sooloos Source

and the Crestron processor does not need to access the Internet. All Sooloos components
require access to the Internet.

© 2008 Sooloos L LC

Page 1

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

Sooloos Crestron® Module Guide

tel: [phone]

Module Connection

®

The Sooloos Media Server module is a SIMPL

gram. Drag the Sooloos Media Server module into the SIMPL program and set the ip_address
parameter to the IP address of the Sooloos server. This IP address is found on the Information
page located on the home screen of the Sooloos Control:One™.

+

module that can be added to any SIMPL pro-

After adding the module to the program, double-click to edit its parameters and joins. One in­stance of the module will be needed for each independent touch panel which requires access
to the Sooloos system. Multiple touch panels can share the same module, but their displays will
be synchronized and will not allow independent browsing.

© 2008 Sooloos L LC

Page 2

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

Sooloos Crestron® Module Guide

tel: [phone]

Finding Zone Identifiers

A standard Sooloos Source contains five discreet zones of audio output. The Sooloos module
allows for a single instance to control up to five zones by using digital inputs to select the zone.

Zones in a Sooloos system are identified by 36 character strings comprising of letters and num-

bers. Zone identifiers are unique between every zone in every Sooloos system, so the identifiers
must be retrieved from the Sooloos installation the module will be connecting to.

To retrieve the zone identifiers from a Sooloos system, a Windows based computer must be con-

nected to the same network as the Sooloos system. The Windows computer must have at least
Microsoft .NET 2.0 installed in order to run the executable DumpZoneIDs.exe which is included
with the Sooloos module.

If necessary, the Microsoft .NET 2.0 runtime can be installed by following the instructions here:

http://www.microsoft.com/downloads/details.aspx?FamilyID=0856EACB-4362-4B0D-8EDD-AAB15C5E04F5&displaylang=en

The DumpZoneIDs executable does not take any parameters and can be run directly from the

Windows desktop without opening a command window. The output from the utility will look like
this:

In the above example, the zone identifier is the 36 character alphanumeric string, a73e9d53­5cfc-4edd-974b-6918f4932205. This value must be copied to the clipboard and pasted as the
desired zone#_id module parameter.

© 2008 Sooloos L LC

Page 3

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

Sooloos Crestron® Module Guide

tel: [phone]

Zone Selection Behavior

The Sooloos module will connect to the Sooloos server when the open_connection input is

pulsed and will attempt to connect to the first zone#_id module parameter. The Crestron pro­gram can switch the zone the module is currently controlling by pulsing the corresponding
select_zone# input. If at any time the module can’t connect to the server or the supplied zone
identifier is not valid, the zone_valid output will be low. This output is intended to be used to
display a subpage in any touch panel project which indicates to the user that the touch panel is
waiting for the zone to exist before giving the user control. In order to join this output to a sub­page, it is necessary to negate it by using a NOT symbol. The resulting zone_not_valid output
from the NOT symbol can be used as the subpage join in the VT Pro-e project.

For basic installation, where one touch panel uses one module instance to control one zone, the
select_zone# digital inputs should be set to 0, the zone1_id module parameter should contain
the zone identifier, and all other zone#_id module parameters should be commented out.

The Crestron program can switch the active zone by pulsing a select_zone# input high. After

switching to controlling the new zone, the module will update its relevant outputs with the cur­rently playing song information for the new zone.

The zone#_id module parameters do not correspond to the physical zone order on any Sooloos

device. This is done to allow the maximum flexibility in configuring touch panels. Crestron pro­grammers can decide up to 5 zones out of any total number that one physical touch panel can
control.

© 2008 Sooloos L LC

Page 4

Sooloos Crestron® Module Guide

Touch Panel Connection

Once the Sooloos module has been properly connected to a

TCP/IP Client which connects to a Sooloos Source, the mod-

ule can be connected to a touch panel instance which will
control it. Sooloos offers pre-built VT Pro-e projects which
come fully assembled with branded graphics. Each template
provides a navigational button which Crestron programmers
should use to bring the user back to rest of their Crestron
control program when clicked. In addition, the volume con­trols (up/down), mute, and volume level are intended to be
connected by the Crestron programmer to the volume con­trols the Crestron panel would normally control. The Sooloos
itself does not allow for volume modification within the de­vice. Volume should be controlled within the external sound
system to which the Sooloos is connected.

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

tel: [phone]

Sooloos aims to provide high quality Crestron
touch panel templates that are graphically inten­sive and aim to have the same general theme as
the Control:One. There are currently a number of
pre-built projects which are in common touch pan­el resolutions (800x600, 320x240, 240x320, etc)
which cover a large range of Crestron touch panel
products. If there is a touch panel resolution which
does not have a custom Sooloos project available,
please contact Sooloos so that we may generate
the appropriate project and make it available to all
integrators.

© 2008 Sooloos L LC

After selecting the appropriate touch pan-

el which will control the Sooloos module,
add it to the SIMPL program. The example
Sooloos program contained with each avail­able VT Pro-e project shows how to config­ure the touch panel joins for proper module

behavior. Since join numbers may change

in real-world integration projects, it is the in­tegrator’s responsibility to properly connect
all joins documented by each VT Pro-e proj-

ect to the appropriate joins on the Sooloos
module. Failure to do so will cause the touch
panel project to behave abnormally.

Page 5

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

Sooloos Crestron® Module Guide

tel: [phone]

External Program Integration

Each VT Pro-e template project contains both volume controls and a special green Crestron
Home button. It is intended that the green home button be used to bring the user back to the
main page of their control program. If the touch panel is only being used to control the Sooloos,
the home button can be omitted.

The available volume controls are volume up/down buttons and a mute toggle button. It is in-

tended that the integrator tie these buttons into the main volume control that the Crestron sys­tem controls. There is no volume control on the Sooloos device itself. In addition to handling
these button clicks and providing the volume_muted feedback, an analog volume_level must
be supplied to the button between volume up/down buttons to properly display the volume
ramp. The analog value must be between the values 0d (completely silent/muted) to 18d (100%
volume).

© 2008 Sooloos L LC

Page 6

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

Sooloos Crestron® Module Guide

tel: [phone]

Page Selection Behavior

The Sooloos module controls three logical pages of data which every touch panel project should

implement.

• Now Playing Page

The “Now Playing” page is where the system transport controls live. These allow the user to pause,

play, stop, change to the next or previous track, etc. The “Now Playing” page is displayed when the
page_transport output is pulsed high.

• Browse Page

The “Browse” page is where the system allows the user to navigate through the various data within

the system and to perform actions on the data. The module refers to the data displayed on this
page as items within the various join names. Data is represented generically so that the user can
use the same interface for selecting songs, adding a playlist to the queue, deleting a collection,
swimming within a genre, or any other action the server exposes now and in the future. For each
data item, there are potentially actions which can be performed on that item, or the item itself can
be selected. Selecting an item is referred to as refining in the join nomenclature. The module in­structs the touch panel what state each item is in (e.g. does not exist, exists, exists with actions) so
that the appropriate interface can be displayed to the user. This state is in the form of analog joins
named item#_button_state which is used in the Sooloos VT Pro-e projects to directly control but­ton modes. The “Browse” page is displayed when the page_browse output is pulsed high.

• Confirm Subpage

The “Confirm” page is used by the module whenever there is an action on an item which requires

confirmation due to its potential for unwanted side effects or loss of data (e.g. deleting a playlist).

The “Confirm” page is temporarily displayed whenever the page_confirm output is pulsed high.

When this output is high, the confirm_yes or confirm_no input is used to dismiss the page and
re-raise the page_browse output high. This subpage can be shown over the “Browse” page. The
module will only ever pulse page_confirm if page_browse was the last page to be pulsed high.

• Zone Waiting Subpage

The “Zone Waiting” subpage is intended to be displayed to the user whenever the zone_valid

output is dropped low. This indicates that the module lost connection to the Sooloos server for
some reason. After reconnecting, the zone_valid output will be raised high again and the subpage
should be hidden. It is recommended that the subpage simply be a black background full-screen
subpage stating “Waiting for Sooloos Zone…”. This subpage can be shown over the “Now Playing”
page. The module will always pulse page_transport high prior to lowering zone_valid.

In order to join the zone_valid output to a subpage, it is necessary to negate it by using a NOT

symbol. The resulting zone_not_valid output from the NOT symbol can be used as the subpage
join in the VT Pro-e project.

© 2008 Sooloos L LC

Page 7

Sooloos Crestron® Module Guide

Module Glossary

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

tel: [phone]

Module Parameters

ip_address

zone1_id
zone2_id

…
zone5_id

num_display_items

max_item_name_length

LEGEND: DIGITAL ANALOG STRING

The IP address of the Sooloos Source. This IP address is

available from the Information page accessible from the
home page on the Sooloos Control:One.

The zone identifier strings are 36 character strings which are

retrieved using the DumpZoneIDs.exe tool included with the
module. Zone identifiers which are not currently being used
should be commented out. For proper module operation,
at least one zone identifier must be assigned and selected.

The number of item related outputs to use. This value is used

to control the number of display items which will fit in the
current touch panel resolution. Up to 16 items can be
displayed at once by a single module. (Valid range: 1d-16d)

This number indicates the maximum number of characters

to display in any one given item name. This is provided mainly
for compatibility reasons with older touch panels which have
strange behavior if text exceeds the available on-screen space.
By default, this parameter is set to 0d, which indicates there is
no maximum length. (Valid range: 0d-127d)

Module Outputs

connected

zone_valid

page_transport

© 2008 Sooloos L LC

LEGEND: DIGITAL ANALOG STRING

Indicates the module is currently connected to the Sooloos
system specified in the ip_address module parameter. If
open_connection is pulsed and this output is not raised high,
it could indicate the module has been given an invalid IP ad­dress for the Sooloos system, the Sooloos server is currently
powered off, or there is a network connectivity problem.

Indicates the currently selected zone is valid. When low, touch
panels should display a full screen subpage stating “Waiting
for Sooloos Zone…”. No module outputs are valid while this
join is low.

Pulsed high when the “Now Playing”, or transport, page should
be displayed to the user.

Page 8

Crestron® Module Guide

-

Module Glossary

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

tel: [phone]

page_browse

page_confirm

playing

paused

stopped

shuffle_enabled

loop_enabled

swim_enabled

Pulsed high when the “Browse” page should be displayed to
the user.

Pulsed high when the “Confirm” subpage should be displayed
to the user. This join will only be raised high from the “Browse”
page, so it can be implemented as full screen subpage of the

“Browse” page. No module inputs other than confirm_yes or

confirm_no should be used while this join is high.

Indicates the current active song in the play queue is playing.

Indicates the current active song in the play queue is paused.

Indicates the current active song in the play queue is stopped.

Indicates the play queue has shuffle enabled. This should be
used as the digital feedback for a shuffle button.

Indicates the play queue has loop enabled. This should be
used as the digital feedback for a loop button.

Indicates the play queue is currently swimming. This should
be used as the digital feedback for a swim button. From the
transport controls, swim can only be disabled once it has been
enabled by another client or via the “Browse” page interface.

playing_elapsed

playing_elapsed_pct

playing_total

play_pause_button_
state

© 2008 Sooloos L LC

The elapsed number of seconds in the current active song in

the play queue. The value will be zero if there is no current ac­tive song.

The elapsed time of the current active song in the play queue

represented as a percentage scaled from 0d-65535d.

The total number of seconds in the current active song in the

play queue. The value will be zero if there is no current song.

Join directly controlling the mode of any play/pause momen-

tary button.

Values:
0 – Play/pause button is disabled
1 – Play state is active
2 – Pause state is active

Module Glossar y

|

Page 9

Crestron® Module Guide

Join directly controlling the mode of any stop momentary but-

ton.

stop_button_state

browse_back_button_
state

browse_page_up_but­ton_state

Values:
0 – Stop button is disabled
1 – Stop button is enabled

Join directly controlling the mode of the “Browse” page back or

return navigational button.

Values:
0 – Back/return button is disabled
1 – Back/return button is enabled

Join directly controlling the mode of the “Browse” page up

button.

Values:
0 – Page up button disabled
1 – Page up button enabled

-

Module Glossary

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

tel: [phone]

browse_page_down_but­ton_state

zone_name

playing_album

playing_artist

playing_song

Join directly controlling the mode of the

“Browse” page down button.

Values:
0 – Page down button disabled
1 – Page down button enabled

The name of the currently selected zone. This is not displayed

on touch panel projects which have limited space.

The title of the album of the current active song in the play

queue. This string value will be a blank string if there is no cur­rent.

The name of the artist of the current active song in the play

queue. The string value will be a blank string if there is no cur­rent song.

The title of the current active song in the play queue, or the text

“No Currently Playing Song” if there is no current song.

© 2008 Sooloos L LC Module Glossar y

|

Page 10

Crestron® Module Guide

The URL which should be used as a dynamic graphic serial

join to retrieve the current song’s album cover. The string value

playing_url

will be a blank string if there is no current active song or the
current active song does not have an album cover. Use of this
output requires a Crestron touch panel capable of dynamic
graphics (e.g. TPMC-8X, TPS-12G-QM).

-

Module Glossary

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

tel: [phone]

confirm_question

items_title

item_button_state[1]
item_button_state[2]
item_button_state[3]
item_button_state[4]
item_button_state[5]

…
item_button_state[16]

item_name[1]
…

item_name[16]

The question which should be displayed to the user when the

page_confirm output is pulsed high.

The display title for the current list of data items. This string

provides context to the user indicating what the data items
pertain to (e.g. songs in an album, years in a genre). This is not
displayed on touch panel projects which have limited space.

Join directly controlling the mode of buttons corresponding to

the data items on the “Browse” page. Each item has potentially

both a button to navigate to the “actions” for each item as well

as a button to select or refine each item itself. The same state
can be used for both buttons to select the appropriate graphi­cal display.

Values:
0 – Item is not currently active
1 – Item is active, does not have actions
2 – Item is active, has actions

String names for the current data items being browsed. These
values should be displayed to the user as the indirect button

text for each individual item on the browse page.

© 2008 Sooloos L LC Module Glossary

|

Page 11

Crestron® Module Guide

-

Module Glossary

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

tel: [phone]

Module Inputs

open_connection

close_connection

select_zone[1]
select_zone[2]

…
select_zone[5]

LEGEND: DIGITAL ANALOG STRING

When pulsed high, instructs the module to connect to the
Sooloos system specified in the ip_address module parameter.

This input should be pulsed high during program startup. It

is recommended that the Crestron processor stay connected

to the Sooloos system at all times to avoid user delays when

switching to control the Sooloos system. If multiple modules

are being used within a single processor, it is recommended

to stagger their startup by using a Stepper symbol. The
module will automatically re-connect to the Sooloos server
in case of disconnection caused by any reason other than
pulsing close_connection high.

When pulsed high, instructs the module to close the current
connection to the Sooloos system. This input is not normally
used in programs where the Crestron processor stays con­nected to the Sooloos system.

When pulsed high, instructs the module to switch to controlling

the Sooloos zone indicated by the corresponding zone#_id
module parameter. By default, the module controls zone1_id

after successfully connecting to a Sooloos system. Once
pulsed high, the module will request the information from the

server for the corresponding zone#_id module parameter and
will re-populate the relevant module outputs. If the correspond­ing zone identifier is not valid, the zone_valid output will be
pulled low.

When pulsed high, instructs the module to switch display to the

transport page. This action modifies internal state and pulses

show_transport

page_transport high. Pulsing this input while the module is
currently waiting for confirm_yes or confirm_no to be pulsed
has the same effect as first raising confirm_no.

When pulsed high, instructs the module to switch display to

the browse page. This action modifies internal state and pulses

show_browse

page_browse high. Pulsing this input while the module is cur­rently waiting for confirm_yes or confirm_no to be pulsed has

the same effect as first raising confirm_no.

© 2008 Sooloos L LC Module Glossary

|

Page 12

Crestron® Module Guide

When pulsed high, instructs the server to play the current song.

play

play_pause

stop

This action is only valid if either the paused or stopped outputs

are high.

When pulsed high, instructs the server to toggle the current
playing or paused state. After being raised high, the module
will update the playing, paused, and stopped outputs to reflect

the appropriate state. The play_pause_button_state output

should be used as the analog join controlling button modes for

any button triggering this join.

When pulsed high, instructs the server to stop the current song.

This action is only valid if either the paused or playing outputs

are high. The stop_button_state output should be used as the

analog join controlling button modes for any button triggering

this join.

-

Module Glossary

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

tel: [phone]

next_track

prev_track

shuffle_toggle

loop_toggle

swim_disable

When pulsed high, instructs the server to advance the current

song to the next track in the play queue based upon the cur­rent play queue settings.

When pulsed high, instructs the server to advance the current

song the previous track in the play queue based upon the cur­rent play queue settings.

When pulsed high, instructs the server to toggle the current

shuffle setting of the play queue. The shuffle_enabled output
reflects the current state and should be used as button feed­back for any button triggering this join.

When pulsed high, instructs the server to toggle the current
loop setting of the play queue. The loop_enabled output re­flects the current state and should be used as button feedback
for any button triggering this join.

When pulsed high, instructs the server to disable the swim

setting of the play queue if it is currently enabled. If swim is not
enabled, there is no effect. The swim_enabled output reflects

the current state and should be used as button feedback for

any button triggering this join.

© 2008 Sooloos L LC Module Glossary

|

Page 13

Crestron® Module Guide

When pulsed high, instructs the module to return to the previ-

browse_back

browse_page_up

browse_page_down

ous level of data browsing (e.g. return from Albums to Artists).

This input is only valid while the browse_back_button_state

has a value of 1.

When pulsed high, instructs the module to scroll up one page
of data within the current level. This input is only valid while the
browse_page_up_button_state output has a value of 1.

When pulsed high, instructs the module to scroll down one
page of data within the current level. This input is only valid
while the browse_page_down_button_state output has a
value of 1.

-

Module Glossary

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

tel: [phone]

confirm_yes

confirm_no

item_refine[1]
item_refine[2]
item_refine[3]

…
item_refine[16]

After the page_confirm output has been pulsed high, this
input is used to signal that the user has confirmed the ques-

tion posed by the confirm_question string output. After being
pulsed high the module will perform the necessary action and
pulse the page_browse output to once again show the browse
page and return to displaying the previous level of data.

After the page_confirm output has been pulsed high, this input
is used to signal that the user has declined the question posed
by the confirm_question string output. After being pulsed
high, the module will pulse the page_browse output to once

again show the browse page.

When pulsed high, instructs the module that the user has

selected one of the currently displayed data items. The input
is only valid if the corresponding item_button_state[#] has

a non-zero value. Pulsing an item_refine[#] input will display

the next level of data for a particular data item. Once no longer
viewing the root level of data, the browse_back_button_state
output will be set to 1, indicating that the browse_back input
is valid to be used to return to the previous level of data. When

the refined data item is an action (e.g. Play Now), the module
will automatically return to displaying the previous level of data.

© 2008 Sooloos L LC Module Glossary

|

Page 14

Crestron® Module Guide

When pulsed high, instructs the module that the user has

item_actions[1]
item_actions[2]
item_actions[3]

…
item_actions[16]

Files

selected to view the actions corresponding to a currently dis­played data item. The input is only valid if the corresponding
item_button_state[#] has a value of 2, indicating actions are

available. Pulsing an item_refine[#] input on a leaf data item
(e.g. a song) has the same effect as pulsing the corresponding
item_actions[#] input.

-

Module Glossary

Sooloos LLC

110 Grene Street, Suite 608

New York, NY 10012

tel: [phone]

Sooloos Media Server.usp

Sooloos Media Server.ush

DumpZoneIDs.exe

Sooloos Media Server SIMPL+ module

Sooloos Media Server SIMPL+ module header

Utility for determining zone identifiers for module parameters

Support

Sooloos LLC

110 Greene Street, Suite 608

New York, NY 10012

9:00am – 7:00pm EST, Monday–Friday
Domestic: [phone]
International: [phone]

© 2008 Sooloos L LC Module Glossary

|

Page 15