Download Altitude32 - Trinnov Audio
Transcript
Trinnov Altitude Processor Automation Protocol Version 1.9 Rémy Bruno November 19, 2015 Contents 1 Introduction 1 2 General description of the protocol 1 3 TCP/IP protocol 3.1 Network configuration . . . . 3.2 TCP/IP protocol parameters 3.3 Connection . . . . . . . . . . 3.4 Power on using network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 2 2 2 4 RS232 protocol 2 5 Commands 3 6 Messages 5 7 Power control 6 8 Example 7 9 Conclusion 8 1 Introduction The Trinnov Altitude processor may be remotely controlled using tcp/ip or rs232 serial link. Both communication modes work very similarly using a bidirectional link, where the client sends commands and the Altitude answers these commands and sends messages providing its current state. In both modes, the recommended use is to connect to the Altitude, possibly request its current state (see § 5), then alternately send commands and read back data it replies. As the Altitude sends a message for each state change (volume, loaded profile and preset, etc.), the client can know the state of the Altitude at each time. 2 General description of the protocol Communication is achieved using ascii characters. Each communication (command or message) consists of a text line ending with a return character. Each line begins with a keyword consisting of alphanumerical characters and indicating the command or the message type, possibly followed with arguments separated by spaces.. The Altitude recognizes the three following return characters: \n (or 0x0A), \r (or 0x0D), and both characters \r\n (or 0x0D 0x0A). This allows compatibility with Unix-like, Mac and Windows systems. Commands and their arguments are case sensitive, so you have to respect uppercase and lowercase (command and COMMAND are two different commands). Each command is followed by an answer message from the Altitude, which is either OK if the command succeeded, or ERROR followed by a description of the error that occurred. The processor may also send other messages, indicating for example a state change, depending on the effects of the command. You should note that the answer does not necessarily occur before the other possible messages from the Altitude. 3 TCP/IP protocol This communication mode uses the available tcp/ip network connections of the Altitude. November 19, 2015 Trinnov Altitude Processor Automation Protocol 1 3.1 Network configuration The user manual explains how to configure the network in a detailed way, so details will not be considered here. RJ45 network configuration of the Altitude is done using dhcp during the boot. The dhcp client of the Altitude sends an identifier (dhcp-client-identifier option of dhclient), which is TRINNOV-SRP-<id> where <id> is the identifier of the processor. This allows for example to automatically give it a specific ip address using an appropriate dhcp server configuration. It is also possible to specify manual network settings in the Network (or System Status depending on the version) sub-menu of the Setup page of the Altitude. 3.2 TCP/IP protocol parameters The communication uses tcp on port 44100. This protocol is very similar to smtp, ftp, or even http. A first approach of this protocol may consist in connecting to the processor using a program like telnet in order to type command lines using the keyboard. 3.3 Connection When a tcp connection is established on port 44100, the Altitude sends a welcome message, also providing the Altitude version and its unique identifier. This identifier (ID or SRPID) is a number which allows to get the serial number of the machine (provided by the 20 least significant bits of this identifier), and the machine type (provided by the most significant bits). The format of this line is as follows: Welcome on Trinnov Optimizer (Version 4.0.0, ID 10485761) This identifier 10485761 is written 0xA00001 in hexadecimal, so the machine type is 10 (corresponding to the type Altitude) and the serial number is 1. The Altitude then waits an identification from the client. This is achieved by sending an id command with an argument identifying the client. This identification is not an authentication, and only allows a possible specific behavior with certain clients. For example: id my_automation_system Communication is then achieved according to the commands and messages mode presented in the preceding section 2 and detailed in the following section 5. You should note command processing only starts after the client has identified itself using the id command. 3.4 Power on using network The Altitude supports the Wake on LAN standard so as to be switched on through ethernet network. We invite you to read the available online documentation on this subject, such as the Wikipedia page http://en.wikipedia.org/wiki/Wake-on-LAN. The MAC address of the Altitude, which is required for using this functionality, is displayed on the network information page of the graphical user interface. Please note that, for Wake on LAN to work, you need to have the automation server and the Altitude on the same sub-network. Typically, this means that the IPv4 adresses of both devices must start with the same three numbers (such as 192.168.0). 4 RS232 protocol The Altitude can also be controlled using an rs232 link with a 9-pin null modem cable. The rs232 serial port parameters are as follows: • 19200 bauds • 1 stop bit November 19, 2015 Trinnov Altitude Processor Automation Protocol 2 • 8 data bits • no parity As soon as a client is connected to the serial port, the Altitude is in the commands and messages mode presented in the preceding section 2 and detailed in the following section 5. You should not identify yourself, contrary to the tcp/ip protocol. Please note that not all machines have an rs232 connector. Check the available connectors on your machine. 5 Commands Here is a list of recognized commands. This list is not comprehensive but includes all commands useful for a normal use of the Altitude. Arguments for each command are represented between <...>. • volume <volume> This command allows to change the main volume to the value <volume> dB. This is the master level as it appears in the GUI of the Altitude. • dvolume <delta> This command allows to add <delta> dB to the main volume. This value may be positive or negative. • volume ramp <target> <duration> This command allows to apply a volume ramp starting from current volume and reaching <target> volume (in dB) after <duration> milliseconds. This command is available since version 3.7.3 of the Altitude. • mute <action> This command allows to change mute state: – if <action> is 0, mute is disabled (sound is enabled), – if <action> is 1, mute is enabled (sound is disabled), – if <action> is 2, mute state is inverted. • dim <action> This command allows to change dim state: – if <action> is 0, dim is disabled, – if <action> is 1, dim is enabled, – if <action> is 2, dim state is inverted. • bypass <action> This command allows to change bypass state: – if <action> is 0, bypass is disabled, – if <action> is 1, bypass is enabled, – if <action> is 2, bypass state is inverted. • send volume This command requests that the Altitude send messages providing current state information related to the volume, in particular messages VOLUME, MUTE, DIM and BYPASS (see these messages in paragraph 6). This command is available since version 3.5 of the Altitude. • remapping mode <mode> This command allows to change remapping mode: – if <mode> is none, remapping is disabled, – if <mode> is 2D, 2D remapping is enabled, November 19, 2015 Trinnov Altitude Processor Automation Protocol 3 – if <mode> is 3D, 3D remapping is enabled, – if <mode> is autoroute, autorouting mode is enabled, – if <mode> is manual, manual remapping is enabled. • use acoustics correction <action> This command allows to change acoustic correction state : – if <action> is 0, acoustic correction is disabled, – if <action> is 1, acoustic correction is enabled, – if <action> is 2, acoustic correction state is inverted. • use level alignment <action> This command allows to change level alignment state : – if <action> is 0, level alignment is disabled, – if <action> is 1, level alignment is enabled, – if <action> is 2, level alignment state is inverted. • use time alignment <action> This command allows to change time alignment state : – if <action> is 0, time alignment is disabled, – if <action> is 1, time alignment is enabled, – if <action> is 2, time alignment state is inverted. • quick optimized <action> This command allows to change optimization state : – if <action> is 0, optimization is disabled, – if <action> is 1, optimization is enabled, – if <action> is 2, optimization state is inverted. • change page <delta> This command changes the menu page currently displayed on the GUI. The value of <delta> indicates the number of pages to change, and may be positive or negative (1 for going to the next page, −1 for going to the previous page). • loadp <preset|file> This command allows to load the preset number <preset>. User presets start with number 1 and preset 0 corresponds to the built-in preset. This syntax is available since version 3.3.4 of the Altitude. For older versions, you have to use the <file> syntax described below, where you provide a file name instead of a preset number. For compatibility with versions before 3.3.4, newer versions also support this <file> syntax. The <file> argument is the name of a file depending on the preset number to load and is formed as follows: Config n.xml where n must be replaced with the preset number. For example, in order to load preset number 1, you should send the following command line: loadp Config_1.xml As command lines are case sensitive, you should use an upper case letter in the file name Config 1.xml. Note: this second syntax does not allow to load the built-in preset. • get current preset This command sends back the current preset number. This command is available since version 3.3.4 of the Altitude. November 19, 2015 Trinnov Altitude Processor Automation Protocol 4 • get label <n> This command sends back the name of preset number <n>. This command is available since version 3.3.4 of the Altitude. • get all label This command sends back the list of all presets available on the machine, along with their numbers and names. This command is available since version 3.3.4 of the Altitude. • profile <source> This command allows to change the current source (also knwon as profile) and thus select the active audio input. The argument is the source number, where the first source is number 0. This command is available since version 3.4. • tac preset <source> This is an old alias for command profile. • upmixer <mode> This command allows to get and set the upmixer mode of the Altitude, depending on the <mode> argument provided : – without argument, the command returns the current upmixer mode, – + or 1 allows to switch to the next upmixer mode, – − or 0 allows to switch to the previous upmixer mode, – auro3d, dts, dolby, auto, native and legacy allow to switch to the corresponding upmixer mode (refer to the manual for more information about upmixer modes). • fav light This command is the equivalent of the Light button of the remote control. • get current profile This command sends back the current source number (also known as profile). This command is available from version 3.5.0rc8 of the Altitude. • get profile name <n> This command sends back the name of the source (or profile) number <n>. This is the name as it appears in the source selection page of the GUI. This command is available from version 3.5.0rc8 of the Altitude. • bye This command requests the server to close the connection. The server then replies BYE (instead of OK) and closes the connection. Commands exit and quit are synonyms. This command has no effect on the operation of the Altitude itself (no shutdown nor sound vanishing), but only on the client-server connection. This command must not be used with the rs232 protocol. • power off SECURED FHZMCH48FE This command allows to switch off the Altitude. 6 Messages Here is a list, non-comprehensive too, of the main messages sent by the Altitude to connected clients: • VOLUME <vol > This message provides the current main volume (in dB). • DIM <dim> This message indicates whether dim is active (if <dim> is 1) or not. • MUTE <mute> This message indicates whether mute is active (if <mute> is 1) or not. November 19, 2015 Trinnov Altitude Processor Automation Protocol 5 • BYPASS <bypass> This message indicates whether bypass is active (if <bypass> is 1) or not. • META PRESET LOADED <profile> This message provides the active profile (or source). • SRATE <srate> This message provides the current sampling rate of the Altitude. • AUDIOSYNC STATUS <status> This message indicates whether the Altitude is correctly synchronized with the audio source (if <status> is 1) or not. • AUDIOSYNC <mode> This message provides the current audio synchronization mode of the Altitude, which can be Master or Slave. • SPEAKER INFO <spk number > <r> <θ> <φ> This message is sent for each calibrated loudspeaker when a preset is loaded. The argument <spk number > indicates which loudspeaker the following information relate to (loudspeaker numbers begin here with 0). Arguments <r>, <θ> and <φ> give the corresponding loudspeaker’s position in spherical coordinates. (r in meters, θ in degrees from the ceiling (north pole), φ in degrees from the front and positive towards the left). • START RUNNING This message is sent when the Altitude is ready to make sound. This is the case for example short after a loadp command is sent (typically a few tenth of seconds after). • LABELS CLEAR This message indicates that the whole list of available presets will be sent by the Altitude just after this message. This tells the client that it should clear its internal preset list that it maintains, in case the client maintains such a list, and that a new list of available presets will follow right after this message. This message is typically sent after the get all label command and just before the presets list. • LABEL <n>: <name> This message indicates that the preset number <n> exists and that its name is <name>. This message is typically sent as an answer to commands get label and get all label. It should be noted that connected clients must be ready to receive a message from the Altitude at any time. For example, when a user changes the current volume, whatever the way he does it, the Altitude sends a message indicating the new volume to all its connected clients. Also, when a calibration is started using the GUI, the Altitude sends loudspeaker coordinates to connected clients, as after the loadp command. This allows the Altitude to interact with its connected clients. This is therefore more a ”dialog” between the client and the server than a ”request/answer” protocol. In other words, the stream is constantly bidirectional rather than unidirectional alternately in each way. Also, it is highly recommended not to poll the Altitude, namely regularly reading the state of the Altitude, a fortiori if this is done using frequent connections and disconnections to the machine. As the Altitude sends all state changes to the clients, it is useless and deleterious to constantly request the state of the machine. The recommended approach consists in connecting only once to the Altitude, read all state variables which are relevant for the client, and then remain connected, waiting for possible changes sent by the Altitude (such as the volume, for example). However, occasional connections and disconnections of a client to the machine are fine. 7 Power control Power on automation may be achieved using one of the following methods: • using the Wake on LAN standard as described in section 3.4, • supplying between 5 and 12 V on the trigger input of the Altitude. November 19, 2015 Trinnov Altitude Processor Automation Protocol 6 Power on is not possible through the regular rs232 or tcp/ip protocols described above, since these functions are powered off together with the processor. Power off automation may be achieved using one of the following methods: • using the power off SECURED FHZMCH48FE command of the rs232 or tcp/ip protocols, as described in section 5, • switching the trigger input of the Altitude from 5–12 V to 0 V. 8 Example Here is a communication example using tcp/ip between the Altitude and a client. The client used here is simply the telnet program, that can be found for example on all Unix systems (including Linux). The first line is the shell command line used to start the client, lines starting with ”>” are the lines input by the user (without ”>”), the other lines are the answers of the Altitude or of the telnet client. This example is transposable almost as is for the case of rs232 protocol, by replacing telnet with a program providing serial port communication and by removing the first three lines (namely the Welcome message from the Altitude, the id command, and the OK answer) as well as the last two lines of this communication (the bye command and the BYE answer). $ telnet srp 44100 Trying 192.168.77.10... Connected to srp. Escape character is ’^]’. Welcome on Trinnov Optimizer (Version 3.8.7, ID 123456) >id Trinnov Audio automation system OK >loadp config_1.xml ERROR: non-existing or inaccessible config file >loadp Config_1.xml OK SPEAKER_INFO 0 1.36485 102.091 -43.3817 SPEAKER_INFO 1 1.21479 100.781 28.5073 START_RUNNING >volume -12 OK VOLUME -12.000000 >dvolume 1 OK VOLUME -11.000000 >mute 2 OK MUTE 1 >mute 2 OK MUTE 0 >volume_ramp -20 50 OK VOLUME -11.000000 VOLUME -11.960000 VOLUME -12.920000 VOLUME -13.880000 VOLUME -14.840000 VOLUME -15.800000 VOLUME -16.760000 VOLUME -17.720000 VOLUME -18.680000 VOLUME -20.000000 November 19, 2015 Trinnov Altitude Processor Automation Protocol 7 >bye BYE Connection closed by foreign host. 9 Conclusion This communication protocol is subject to changes, but, in case this happens, the evolutions will always remain compatible with the previous behaviour. This compatibility approach explains why some command names seem inconsistent regarding their nomenclature (for example tac preset and get current profile). Questions are welcome, and should be addressed to [email protected]. November 19, 2015 Trinnov Altitude Processor Automation Protocol 8