Establishing Connections

COMMUNICATION PROTOCOL

ESTABLISHING CONNECTIONS

The iHome Suite has a separate player/browser “service” running for each sound zone. A connection is established by opening a socket or telnet session using the hostname or IP address of the iHome followed by the port number corresponding to each service. The following table shows how to connect to the sound zone services:

Zone / Port# / Telnet Command
1 / 1234 / telnet <iHome IP Address> 1234
2 / 1235 / telnet <iHome IP Address> 1235

PROTOCOL DESCRIPTION

UNICODE

The service communicates using the UTF-8 Unicode character set. For systems that do not support Unicode character sets, this protocol is a binary protocol as each character is 2 bytes long. The following table shows text and corresponding hex codes:

Text / ASCII hex codes / UTF-8 hex codes
Get / 0x47,0x65,0x74 / 0x00,0x47,0x00,0x65,0x00,0x74

For standard ascii characters from 0x00 – 0x7F, UTF-8 is simply a 2-byte version of the same code, i.e. ‘G’ = 0x0047. Therefore, to convert from ascii to Unicode when writing, write out a leading 0x00 byte before the ascii character. To convert when reading, read 2 bytes at a time. All Unicode characters in the range of 0x0000-0x007F can be converted to ascii by simply dropping the leading 0x00. Any characters above this range can either be discarded or used as special delimiters.

From this point forward in the document, assume that all characters and character strings are double byte UTF-8 character strings.

COMMAND FORMAT

<Termination Character> is 0x0000

<Unicode Command String> See table below

Unicode Command String / Example (All chars are Unicode UTF-8) / Example Response (All chars are Unicode UTF-8)
Get <category>.Count / Get Artists.Count //get the total count of artists / Artists.Count=9
Get <category>(<start index>,<end index>) / Get Genres(0,3) //get the names of the first 3 genres / Genres(0,3)=Alternative<0x001D>0<0x001E>Jazz<0x001D>1<0x001E>Classical<0x001D>2<0x001E> //where 0x001D and 0x001E are Unicode versions of ascii group separator and ascii record separator characters.
Get <category>( <index> ).Count / Get Albums(3).Count //get the number of tracks in the 4th album. / Albums(3).Count=5
Get <category>.<index>(<start index>, <end index>) / Get Playlists.3(0,2) //get the names of the first 2 tracks of the 4th playlist. / Playlists.3(0,2)=My Immortal<0x001D>0<0x001E>Bounce<0x001D>1<0x001E>
Get Current.<property> / Get Current.Path //get the path of the currently playing track. / Current.Path=Albums.3.2 //the 3rd track of the 4th album
SelectMedia <category>.<index> / SelectMedia Playlists.4 //start playing the 5th playlist / //it starts playing the 1st track in the 5th playlist and sends back the following unsolicited responses:
Current.Track=Hey Mama<0x001D>0 //Name of song and its index in the playlist
Current.Artist=Black Eyed Peas
Current.Album=Hey Mama
Current.Playlist=Top 25 Most Played
Current.Path=Playlists.5.0
Current.Playstate=Play
SelectMedia <category>.<index>.<index> / SelectMedia Genres.2.1 //play the 2nd track in the 3rd genre / //it starts playing the specified track and sends unsolicited status as above
Stop / Stop / //stops the player and sends the following unsolicited response
Current.Playstate=Stopped
Pause / Pause / //pauses the player and sends the following unsolicited response:
Current.Playstate=Paused
Play / Play / //restarts the player on the current track. If paused, it actually starts playing where it was paused. If stopped, restarts the current track.
Current.Playstate=Play
Next / Next / //skips to the next track and sends the following unsolicited responses:
Current.Track=Hey Mama<0x001D>0 //Name of song and its index in the playlist
Current.Artist=Black Eyed Peas
Current.Album=Hey Mama
Current.Playlist=Top 25 Most Played
Current.Path=Playlists.5.0
Current.Playstate=Play
Previous / Previous / //skips to the previous track and sends the following unsolicited responses:
Current.Track=Hey Mama<0x001D>0 //Name of song and its index in the playlist
Current.Artist=Black Eyed Peas
Current.Album=Hey Mama
Current.Playlist=Top 25 Most Played
Current.Path=Playlists.5.0
Current.Playstate=Play
Playmode and shuffle mode commands / ToggleShuffle
ShuffleOn
ShuffleOff
RepeatPlaylist
RepeatTrack
RepeatOff / //sets shuffle and repeat modes of the player as indicated. Responds with the following unsolicited responses:
Current.PlayMode=RepeatPlaylist
Current.Shuffle=On

RESPONSE FORMAT

<Unicode Request String> is the echo of the data portion of the Get command or the Current state being reported if response is unsolicited.

<Unicode Response String> is depends on the request. See table in COMMAND FORMAT section.

<Termination Character> is 0x0000

KEYWORD TABLE

Keyword Type / Keyword / Keyword Description
Command / Get / Instructs the sound zone service to respond to the specified request
SelectMedia / Instructs the sound zone service to begin playing the specified playlist, artist, album, genre, or track
Stop / Stops the player – subsequent play will restart the current track
Pause / Pauses the player – subsequent play will continue playing where paused
Play / Restarts the player
Next / Goes to next track in the current playlist, artist, album, or genre
Previous / Goes to previous track in the current playlist, artist, album, or genre
ToggleShuffle / Toggles the current shuffle mode
ShuffleOn / Turns on shuffle
ShuffleOff / Turns off shuffle
RepeatPlaylist / Sets playmode to repeat current playlist, artist, genre, or album
RepeatTrack / Sets playmode to repeat current track
RepeatOff / Turns off repeat
Category / Playlists / All playlists in database
Artists / All artists in database
Albums / All albums in database
Genres / All genres in database
Property //as in Current.<Property> or Album.4.5.<Property> / Track / Current.Track=Hey Mama<0x001D>0 //Name of song and its index in the playlist
Name / Playlist.1.Name=Top 25 Most Played
//Name of specified item
Artist / Curren.Artist=Black Eyed Peas
//Name of artist associated with current track
Album / Current.Album=Hey Mama
//Name of album associated with current track
Path / Current.Path=Playlist.3.2
//Path associated with current track
Playlist / Current.Playlist=Top 25 Most Played
//Name of playlist associated with current track
PlayState / Current.PlayState=Play
Current.PlayState=Stop
Current.PlayState=Pause
PlayMode / Current.PlayMode=RepeatOff
Current.PlayMode=RepeatPlaylist
Current.PlayMode=RepeatTrack
Shuffle / Current.Shuffle=On
Current.Shuffle=Off

SPECIAL CHARACTERS/DELIMITERS

Character Type / Character Code / Description
<termination character> / 0x0000 / Delimits a complete command or response
<record separator> / 0x001E / Delimits a line in a list in responses that involve lists of items as in Get Playlists(0,5).
<group separator> / 0x001D / Separates the name from it’s index. The response to Playlists(0,5) is of the form Name1<group separator>Index1<record separator>…