View source for Link and Share

The SOUND4 Link&Share (L&S) is a simple and open protocol that allow users to remotely control SOUND4 processors through a network connection.

SOUND4 offers a tool that manage sending L&S commands to your processors: the Link&Share Transmitter; but you can easily write your own tools in you preferred programming language (C,C#, VB, Java, PHP, ...).

The protocol is based on a standard telnet layer, so it can be joined by simply opening a TCP socket.

The Sound4Server opens TCP ports 3003 by default to access L&S.

'''Warning:''' the commands listed here may change depending on the product, its version, and the authorized login access level. To have a list of what you can do, either download the XML documentation from SOUND4 Remote Control in About->Download L&S Doc, or connect with a telnet client, login and type help.

See also: [[Link and Share HDFM Examples]], [[Link and Share Transmitter]], [[Link And Share Panel|Link&Share Panel]]

==Introduction==

===Security Concerns===
Telnet protocol is not secured but has been chosen for ease-of-use. There are many ways to get a secured connection, for example:

#Use a VPN (Virtual Private Network), and allow only connections from this VPN.
#Use SSH, with port forwarding technique, and allow only local connections.

===Session example===
When connexion is established the server sends a prompt message:<blockquote><code>READY</code></blockquote>It is now possible to type commands.

First you have to login:<blockquote><code>LOGIN admin,admin</code></blockquote>The server will confirm that you are logged :<blockquote><code>OK</code></blockquote>You may then change, for example, the Backup mode Main Source:<blockquote><code>BK.SRC[1]=Analog</code></blockquote>The server will confirm that the command was executed :<blockquote><code>OK</code></blockquote>You may also request the second Backup Source:<blockquote><code>BK.SRC[2]?</code></blockquote>And the server will reply for example:<blockquote><code>Digital</code></blockquote>

===Tools===
You can use [[Link and Share Transmitter|Link&Share Transmitter]] to create and execute scripts.

You can use [[Link And Share Panel|SOUND4 L&S Panel]] to create a panel which uses L&S.

==Protocol==
The protocol was designed to be easily and directly used by human user, via Telnet, or to be used by a program.

*Commands and Replies are always on individual lines.
*Commands are executed sequentially, and Replies are returned in the same Command order.
*Commands are not case sensitive : you may type <code>LOGIN</code> or <code>LogIn</code>.

The server has a built-in online help, called with <code>HELP</code> command. The Help page will be uncomplete when the user is not logged in, because Help page depends on the Process type.

You may request for more help on a particular topic, for example <code>HELP IN</code> to request help on Source setup, or <code>HELP BK.SRC</code> to get help on <code>BK.SRC</code> function.

The Server will accept simplified commands when there is no ambiguity. For example:<blockquote><code>Bk.Src[Main]=Ana</code></blockquote>is equivalent to<blockquote><code>Bk.Src[Main Source]=Analog</code></blockquote>because there is only one possible value for the index and for the source name.

'''Remark''': special chars (non-ANSI) must be coded with '''UTF8''' standard.

===Server Replies===
First char of a line gives an information on the type of reply:

#A line starting with <code>*</code> means that the command failed. Rest of line gives more details
#A line starting with <code>+</code> gives extra information. It continues the reply that can be split on several lines.
#A line starting with <code>!</code> is an asynchronous notification, with no relation to last command. In this case the line contains the notification identifier followed by an operator (<code>=</code>, <code>+=</code>, <code>-=</code>,...) and a value.
#A line starting with <code>?</code> is a Server Request : the server is asking a question and is waiting for an answer. This case is rare, and happens for example for <code>LOGIN</code> command when many Sound Processors are present and the target is unknown.
#A line starting with another char is a direct reply to a command. The line usually starts with <code>OK</code> when it was a simple command. It may also be a value for a request command.

When connection is established the server sends a welcoming message followed by <code>READY</code>.

It is common to send all commands at a time, after connection is established, and to close the connection without waiting for replies. The server will stack the commands and execute them in right order. If the connection is not closed, the replies will arrive in the same order after <code>READY</code>.

===Operators===
Commands are in general made of the command name followed by an operator, except for basic commands.

====<code>?</code> operator====
Request a variable value. The Server will simply reply with the value.

Example:<blockquote><code>RDS.PS?</code></blockquote>

====<code>=</code> operator====
Affectation of a value to a variable.

Example:<blockquote><code>RDS.PS=Top Radio</code></blockquote>

====<code>+=</code> operator====
Add a value to a variable. Only supported by a reduced command subset.

Example:<blockquote><code>RDS.AF+=107.7</code></blockquote>

====<code>-=</code> operator====
Remove a value to a variable. Only supported by a reduced command subset.

Exemple:<blockquote><code>RDS.AF+=107.7</code></blockquote>

====<code>!</code> operator====
This requests an asynchronous notification on a variable's value change. VUmeter type variables usually don't support this because they change too fast and may saturate TCP link.

Example:<blockquote><code>PRESET.ONAIR!</code></blockquote>The server will reply OK if command request was successful, and will then send asynchronously a line starting with ! every time the value change.

Example: Asynchronous Server reply<blockquote><code>!PRESET.ONAIR=My new preset</code></blockquote>

====<code>*</code> operator====
Request to stop receiving asynchronous notifications

Example:<blockquote><code>PRESET.ONAIR*</code></blockquote>

====<code>'</code> operator====
Request the setting range of a variable.

Example:<blockquote><code>BK.SRC'</code></blockquote>

===Variable format===
Variables may have many dimensions and/or many channels. For example, the variable for Backup Sources (<code>BK.SRC)</code> contains 4 values.

Multidimensional variables are arrays. To reach an particular value, use [] signs around the index number, or use : sign separator between values across dimensions. First dimension is always numbered from 1 (and not from 0). It is sometimes possible to use names instead of numbers: see help on the considered variable for more details.

Example: Request the value of the second Backup Source<blockquote><code>Bk.Src[2]?</code></blockquote>Example: Direct affectation of the 4 values<blockquote><code>Bk.Src=Analog:Digital:PCI:IP</code></blockquote>For variables with many channels (left/right for example), the operator is () and separator is ;

Example: Request the peak value of the 1 st analog output<blockquote><code>Out.Ana_PkHold(1)?</code></blockquote>Example: Same, but using the channel short name<blockquote><code>Out.Ana_PkHold(L)?</code></blockquote>Example: Request the peak value of the 1 st analog output<blockquote><code>Out.Ana_PkHold?</code></blockquote>Will return for example<blockquote><code>-0.3;-0.1</code></blockquote>

==Main commands==

===LOGIN===
Used to log on Sound Processor. This command is required before server accept any other command.

If many Sound Processors are present on a single computer, you have to choose which target will be accessed by giving either the Processor Serial Number (preferred method), or the Processor name.

Syntax:<blockquote><code>LOGIN user,password</code></blockquote><blockquote><code>LOGIN target,user,password</code></blockquote>Users and passwords are the same as the one used and defined in the Sound4 Remote Control.

===LOGOUT, EXIT, QUIT===
Close the session and quits.

Remark: this command is not mandatory, as the connexion automatically closes when the TCP socket is closed.

===HELP===
Gives a detailed help on possible commands and variables.

To get more details, add a command or a group name.

Syntax: General help, lists the groups<blockquote><code>HELP</code></blockquote>Syntax: Help on commands for a particular group<blockquote><code>HELP group</code> </blockquote>Syntax:  Detailed help on particular command<blockquote><code>HELP command</code></blockquote>

===VER?===
Returns the Sound4Server version.

=Products specific documentations=
For HD/FM product, see [[Link_and_Share_HDFM_Examples]]