Telephone Tech Sales 1.800.283.5936 1.801.974.3760 1.800.705.2103 FAX 1.801.974.3669 E-mail tech.support@clearone.com techsales@clearone.com support@netstreams.com On the Web www.clearone.com www.netstreams.com www.streamnetpartners.com StreamNet Integration & Programmer’s Guide CLEARONE PART NO. 800-000-017 APRIL 16, 2011 (REV. 1.0) © 2011 ClearOne and NetStreams - All rights reserved.
Table of Contents Chapter 1: Introduction Document Purpose................................................................................................................... 1 Document Organization......................................................................................................... 1 Chapter 2: Controlling A StreamNet System Connecting to the StreamNet System.............................................................................. 3 StreamNet TCP Portal. ...........................
Table of Contents Interrogatives................................................................................................................................................... 12 Declaratives..................................................................................................................................................... 12 Menus..............................................................................................................................................................
Table of Contents Command: #MENU_LIST m, n, sources........................................................................................................ 26 Responses Received....................................................................................................................................... 26 Command: #MENU_SEL {{path}}................................................................................................................ 27 Command: #MULTIAUDIO.................................
Table of Contents
Chapter 1: Introduction Document Purpose The intent of the StreamNet Integration & Programmer’s Guide is to define the StreamNet software command structures necessary for Integrators to build interfaces. The interfaces can then be used by StreamNet System Controllers to control StreamNet Ready devices.
2 Technical Sales: 1.800.705.
Chapter 2: Controlling A StreamNet System StreamNet is designed such that a very large number of networked devices behave as a single coordinated system. The integrator does not need to know about the underlying network complexity; StreamNet completely handles it all. With StreamNet you get all of the advantages of an IP based system without the complexity. The third party control device only needs to know a single IP address and through this one address can control an unlimited number of StreamNet devices.
TCP Control Any StreamNet ASCII control message may be sent using TCP to the IP address of any StreamNet device at port number 15000. Responses from the StreamNet system will be returned on the TCP connection which initiated the request. See chapter on ASCII Protocol. TCP Monitoring Unsolicited status messages may be received by the third party controller using TCP through the StreamNet mechanism of Registration. See section on Registration.
StreamNet Concepts There are few concepts that must be understood to properly understand StreamNet. Services A StreamNet service is an abstraction. It is a functional software module but it can be thought of as a virtual device. A service performs a single function such as capturing analog audio and streaming that audio onto the network. Another service may perform the function of converting the network audio stream to analog and amplifying it.
Controlling Legacy AV Devices Driver Pass Through (Serial or IP) Generally, when controlling an AV source device such as a media server or Sirius tuner the integrator will want to use the drivers which already exist for their third party controller. StreamNet makes this simple and convenient. The serial ports on any StreamNet device can be configured to transparently pass serial traffic to/ from any controller.
Subscription Receiving System Status StreamNet Subscription allows third party controllers to receive unsolicited status messages from StreamNet services. During configuration, the Integrator may subscribe to a StreamNet Service’s status message by entering the controller’s IP address and the port to which the status messages are to be sent. If a subscription exists, the StreamNet service will send status messages over UDP protocol to the specified IP address and port number.
Registration When controlling the system through a TCP connection the TCP client may “register” to receive status from individual services. Registration is performed by sending a “#REGISTER” ASCII command to the StreamNet device acting as the TCP server. This registration will time out after 30 seconds unless it is renewed by sending another “#REGISTER” command. A TCP client of a StreamNet device may “register” to receive status from a specific service.
Chapter 3: ASCII Overview The basic mechanism for control and status reporting of the services in StreamNet is the ASCII protocol. This protocol consists of various command messages and their parameters represented by strings of ASCII characters. Messages also have associated routing and administrative information which informs recipients of the destination and origin of the messages or provides other supplemental information.
Subnode A subnode address is part of the ASCII command address. It can be part of the TO or FROM address. A subnode address is a special address modifier which instructs the node where to forward the command once it is received. Sometimes the subnode address indicates that the service should forward the command to a non-StreamNet device. Examples: • ~IRMOD: forwards the command to the device which is providing the IR I/O functions to the StreamNet service. • ~UDP192.168.5.
Arguments have the following formats: • Meaningful Strings – These are labels which represent some value, case, or function. Examples of meaningful strings are ON and OFF. Meaningful strings are not enclosed in quotation marks and must begin with an alphabetic character – not a numeral. • Character Literals – These character strings do not need any special delimiters if they contain no blanks, spaces, commas, or other special characters. (A special character is other than alpha/ numeric).
ASCII Message Types There are three types of ASCII messages - Imperative, Interrogative and Declarative. Imperatives Some messages are commands which initiate an action or directly cause a change of state. For example, commands that change volume level, select an audio source, or send an IR code. Example: #@CD PLAYER:~UDP192.168.5.3_5000#PLAY The message will be routed to the StreamNet Service named CD PLAYER. This service may transmit an IR code for PLAY to the actual CD player being controlled.
#MENU_RESP {{tier2>etc” disppath=”TierName” display=”Item ID” otherData=”123456” moreData=”xyz” />}} The StreamNet service will respond to a #MENULIST message with a series of menu response messages, one for each menu item requested. The payload of the menu response message is XML-like, items may or may not be present and the order of the listed items may change.
Menu Navigation The menu navigation process begins with the controller or user interface device requesting the top level of a menu. Menus can be very long so it is recommended that requests specify a small range of menu items to be returned. The controller must then repeat the #MENU_LIST command changing the specified range until it has all of the menu items desired.
#REPORT Messages The primary mechanism for a StreamNet service to convey its current state and status is by sending #REPORT ASCII messages. #REPORT messages may be sent in response to a #QUERY command or they may be sent unsolicited. A #REPORT sent in response to a #QUERY will be routed as an ordinary ASCII message. However, an unsolicited #REPORT will not be routed as an ASCII command. The “FromAddress” of the #REPORT message will indicate which service sent the #REPORT.
Unsolicited #REPORT Unsolicited #REPORT messages are sent periodically and when the status of the service changes. The unsolicited #REPORT messages are sent through any of several mechanisms. Most commonly the unsolicited #REPORT message is sent using UDP on the multicast IP address which has been assigned to the service for that purpose. This multicast address is referred to as the service’s “Status Multicast Address” (See Multicast Addresses section).
ASCII Character Escape Sequences Sometimes characters which have a special meaning in an ASCII-based protocol will occur within text strings; therefore, there must be a way to indicate that the character in a particular instance does NOT convey its special meaning. This situation arises for StreamNet menu responses and status reports which have an XML style format.
18 Technical Sales: 1.800.705.
Chapter 4: Overview of Services The scope of this manual is to provide details on how to integrate a 3rd Party Controllers with a StreamNet IPBased Media Distribution system. It is assumed that the user understands User Datagram Protocol (UDP), TCP and Unicast and Multicast addressing. It is also assumed that the user has used the StreamNet Dealer Setup tool to configure the StreamNet system.
Common Services by Device The following is not a comprehensive list of services available. To determine the services available for a specific StreamNet application, consult the appropriate device documentation. Amplifier / Player Device (ie.: SpeakerLinX SL220, SL250, SL251, SL254, SL9250-CS) • Audio Renderer • Audio Source • Audio-only Stream Proxy • User Interface (UI) • Intercom • Root Touch Panel (ie.
Chapter 5: Services Described Audio/Video Renderer Service Overview A Renderer Service (Audio/Video) is responsible for playing audio and/or video from network sources. It is also responsible for controlling any attached amplifier or display device. Renderers may support various combinations of the possible media stream types. Some of the media streams currently supported are: 1. Stereo Audio (44.1KHz, 16bit, stereo, linear PCM) 2. S/PDIF Digital Audio (transparent pass-through of S/PDIF bit stream) 3.
Examples Audio/Video Renderer Command Details The following pages detail the functions of many StreamNet ASCII commands. The format of the text is as follows: • A brief description of what the command does. • Command name and format. • An example of the ASCII message syntax for the command. • Notes specific to the command and explanation of possible responses generated. Command: #ACTIVE OFF Sets the Active Audio Renderer Service to OFF (InActive). Example: #@Room 1 Player:~UDP10.15.0.
Command: #AMP ON Commands a Renderer Service to turn an Amplifier ON. Example: #@Room 1 Player:~UDP10.15.0.11_5000#AMP ON The amplifier associated with the Audio Renderer service Room 1 Player is set to the ON state. ff NOTE: #AMP OFF and #AMP ON have no effect on the renderer settings. Levels To control, report, and display analog (i.e., continuous) quantities such as Volume, Balance, Brightness, and so on, the level construct was established.
Command: #LEVEL_SET BALANCE, x Commands a Renderer Service to Set the Balance Level. Example: #@Room 1 Player:~UDP10.15.0.11_5000#LEVEL_SET BALANCE, x Set the Balance Level of Audio Renderer service Room 1 Player based on the value x. • x is a number between 0 – 100. • x = 50 will set the balance to equal for both channels. • x < 50 will shift the balance toward the left channel (by decreasing the right channel).
Command: #LEVEL_UP BALANCE Commands a Renderer Service to Shift the Balance Level to the Right Channel. Example: #@Room 1 Player:~UDP10.15.0.11_5000#LEVEL_UP BALANCE Shifts the Balance Level of the Audio Renderer service Room 1 Player towards the Right Channel (by decreasing the Left Channel.) Command: #LEVEL_UP BAND_x Increases the device Equalizer Band Level. • x is the band indicator (1 through 5). Example: #@Room 1 Player:~UDP10.15.0.
Command: #MENU_LIST m, n, sources Gets a List of Audio Sources available to the specified Renderer Service. Example: #@Room 2 Player:~UDP10.15.0.11_5000#MENU_LIST 1,6,SOURCES ff NOTE: m,n specifies the range of items to be listed from the list of sources. m = item number of the first item on the menu list to be listed, through n = the last item in the range. Example: m=1 and n=6, will show the first through the sixth item, or m=3 and n=5 will show the third through the fifth items in the menu list.
Sixth Response #@TL3800538001161007532_1~UDP10.15.0.11_2141:Room 2 Player#MENU_RESP {{}} ff NOTE: itemnum=”-1”. The “-“ sign indicates that there are no more audio sources. If itemnum = a positive number, then there are more audio sources assigned to this Service and the command needs to be re-issued until itemnum=”-x” is received. Example: #@Room 2 Player:~UDP10.15.0.
Command: #MUTE OFF Commands a Renderer Service to set Mute to the OFF state. Example: #@Room 1 Player:~UDP10.15.0.11_5000#MUTE OFF Command: #MUTE ON Commands a Renderer Service to set Mute to the ON state. Example: #@Room 1 Player:~UDP10.15.0.11_5000#MUTE ON Command: #MUTE TOGGLE Commands a Renderer Service to Toggle the state of Mute. Example: #@Room 1 Player:~UDP10.15.0.11_5000#MUTE TOGGLE Command: #QUERY renderer Query the settings for current Audio Source being Rendered.
Command: #SLEEP Commands a Renderer Service to set a specific device to the Sleep state. Example: #@Room 1 Player:~UDP10.15.0.11_5000#SLEEP Sets the Room 1 Player device to Sleep. Command: #SRC_SEL De-selects all Audio Sources from Renderer. Example: #@Room 2 Player:~UDP10.15.0.11_5000#SRC_SEL “ “ ff NOTE: If no Audio Source is specified between the “ “, the current Audio Source will be deselected resulting in no Audio Source being rendered by the service: Room 2 Player.
Audio/Video Source and Source Proxy Service Overview An Audio/Video Source service is responsible for taking in audio and video from some source and encoding them into IP-based data packets and transmitting these packets over the network. The Source service may also provide some control over the source device. All current StreamNet AV Source services are controlled in more less the the same way.
Second Response #@SL22004285001161000172_4~TCP10.15.0.11_4750:Stream 1#MENU_RESP {{ }} The next level menu path for this list is established by concatenating the item’s idpath and ID separated by the “>” symbol. Example: {{media>Artists}} becomes the next menu path. • itemnum = “2” indicates this is the second item on this menu list. • display = “Artists” is the display name for this list.
Command: #MENU_LIST m, n, {{path}} This command allows the user to traverse down a Menu List. As explained above, the next level menu path is established by concatenating the item’s idpath and its id separated by a “>” character. Example: {{media>All Songs}} becomes the next menu path: #@Stream 1:~UDP10.15.0.11_5000#menu_list 1,5,{{media>All Songs}} The command is requesting menu items 1 to 5 of the menu list below the list All Songs, which was the first item on the previous menu list.
The “All Songs” menu had shown it had 1078 children of which the command #menu_list 1,5,{{media>All Songs}} requested a list of items 1-5. Similarly, if the integrator wanted to see the list under the second item, “Artists”, the command syntax would be: #@Stream 1:~UDP10.15.0.11_5000#menu_list 1,5,{{media>Artists}} Command: #QUERY source Gets details on the current Media being played. Example: #@Stream 1:~UDP10.15.0.11_5000#QUERY source Response Received #@SL22004285001161000172_4~UDP 10.15.0.
User Interface (UI) Service Overview A UI service handles all of the configuration and control for a particular user interface. Some common functionality provided by UI services are: 1. Converting key press commands to other ASCII commands. 2. Converting IR codes to key press commands or other ASCII commands. 3. Forwarding commands to a subordinate UI component such as a keypad or Flash GUI. Unlike most other service types, UI services tend to have differing functionality from device to device.
To turn on the microphone for a particular zone send the following command addressed to the zone: #INTERCOM PTT This command will turn on the microphone and keep it on for 300ms. This command must be repeated at 100ms intervals to keep the microphone on. When the user is done speaking the following command should be sent: #INTERCOM PTT OFF This will immediately turn off the microphone. This is better than waiting for the time out.
An intercom room may be forced out of a Door Session by sending a Leave command: #INTERCOM LEAVE [, ENTRY] #INTERCOM LEAVE [, tag] If “ENTRY” or “tag” is left off the LEAVE command, all intercom sessions in the addressed room will be terminated.
General Purpose IO (GPIO) Service Overview The General Purpose IO (GPIO) service can be thought of as a “Miscellaneous Function” or a catch-all type Service. Services that don’t neatly fit into any of the other services described may often be found under this umbrella service type. Some of the common I/O types associated with GPIO services are IR, RS232 serial, and relay contact closures. Many GPIO services have LUA interpreters associated with them.
38 Technical Sales: 1.800.705.
Appendix: SpeakerLinX The following SpeakerLinX devices will respond only to the specified commands as outlined below. Commands must be issued to the appropriate serviceType specifying the serviceName in the :toAddress field.
SpeakerLinX Audio Renderer Service Commands ASCII STRING COMMENTS SL220 SL250 SL251 SL254 SL9250-CS SN1001 Device #SRC_SEL {{source id}} Select a specific source to be rendered ü ü ü ü ü ü #SRC_SEL NEXT Choose next available source to be rendered ü ü ü ü ü ü ü ü ü ü ü ü #TEMPSRC A-2 Technical Support: 800-283-5936
Index Symbols B /0 (null byte)............................................................. 11 3rd Party IP Address............................................................... 7 @toAddress............................................................... 9 Balance Setting LEVEL_SET BALANCE, x............................. 24, A-1 Shifting LEVEL_DN BALANCE.................................. 23, A-1 LEVEL_UP BALANCE.................................. 25, A-1 Band Setting LEVEL_DN BAND_X.......................
LEVEL_SET VOL, x............................................ 24, A-1 LEVEL_UP BALANCE........................................ 25, A-1 LEVEL_UP BAND_x........................................... 25, A-1 LEVEL_UP BASS............................................... 25, A-1 LEVEL_UP TREB............................................... 25, A-1 LEVEL_UP VOL........................................... 23, 25, A-1 M Menu Commands MENU_LIST m,n,{{path}}.................................. 30 MENU_LIST m,n,SOURCES.......
Addressing.............................................................. 5 ASCII Command.................................................... 22 ASCII Messages...................................................... 5 Devices.................................................................... 5 Status Messages..................................................... 7 Subscribing............................................................. 7 Subnode Address..........................................................
I-4 Technical Support: 800-283-5936
Glossary of Terms A Argument - Most often an optional fields that proceed keywords. When used, there are one or more spaces between the keyword and the first argument and a comma is used to separate each successive argument. Arguments can be in the format of Meaningful Strings, Character Literals, Numeric Scalars or XML or other Special Formats. ASCII Protocol - The basic control and status reporting mechanism of the services in StreamNet.
D Declarative - A StreamNet ASCII message command used to report information requested from an unsolicited status report (periodic or caused by a change in a device’s state) or via a response to an interrogative message. The most common StreamNet declarative is the #REPORT message. E F Flash - A storage method/device for digital media. fromAddress - Indicates which entity sent the message and is used to address any response that may be generated by the message.
K KEY - A UI/Keypad/IR service command used to identify the specific function key that was pressed in order to initiate an action based on the depressed key. Keyword - The keyword is a required field in all ASCII command statements and specifies the action to be executed. The keyword field must be preceded by the ”#“ symbol with no intervening spaces. The keyword is one word and contains no spaces, commas or other special characters except the underline ”_“ character.
S serviceName - A unique name assigned to each service in a StreamNet system. The serviceName is then used to address ASCII messages. Each physical StreamNet device may be configured to have some or all of its specific services enabled. StreamNet - A technology that provides elegant solutions for streaming media & control applications such as digital signage, distribution of HD video and audio, LAN Cloud Matrix Switching™, and audio paging over data networks.
X Y Z Glossary G-5