Trinnov Amethyst Automation Protocol
Contents
1. e AUDIOSYNC lt mode gt This message provides the current audio synchronization mode of the Amethyst which can be Master or Slave e SPEAKER_INFO lt spk_number gt lt r gt lt 0 gt lt gt This message is sent for each calibrated loudspeaker when a preset is loaded The argument lt spk_number gt indicates which loudspeaker the following information relate to loudspeaker numbers begin here with 0 Arguments lt r gt lt 0 gt and lt gt give the corresponding loud speaker s position in spherical coordinates r in meters 6 in degrees from the ceiling north pole in degrees from the front and positive towards the left e START_RUNNING This message is sent when the Amethyst 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 e LABELS_CLEAR This message indicates that the whole list of available presets will be sent by the Amethyst 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 e LABEL lt n gt lt name gt This message indicates that the preset number lt n gt exists and that its name is lt name gt This message is typically sent as an answer to commands get_la2. E 17 720000 VOLUME 18 680000 VOLUME 20 000000 gt bye BYE Connection closed by foreign host 8 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 May 19 2015 Trinnov Amethyst Automation Protocol 6 T2NNOV some command names seem inconsistent regarding their nomenclature for example tac_preset and get_current_profile Questions are welcome and should be addressed to remy bruno trinnov com May 19 2015 Trinnov Amethyst Automation Protocol 7
3. High Performance Digital Acoustics since 2003 Trinnov Amethyst Automation Protocol Version 1 7 R my BRUNO May 19 2015 www T2INNOMvcom 4 TINNOY 1 Introduction The Trinnov Amethyst 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 com mands and the Amethyst answers these commands and sends messages providing its current state In both modes the recommended use is to connect to the Amethyst possibly request its current state see 5 then alternately send commands and read back data it replies As the Amethyst sends a message for each state change volume loaded profile and preset etc the client can know the state of the Amethyst at each time 2 General description of the protocol Communication is achieved using ASCII characters Each communication command or mes sage consists of a text line ending with a return character Each line begins with a keyword consisting of alphanumerical characters and indicating the com mand or the message type possibly followed with arguments separated by spaces The Amethyst 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 Com mands and their arguments are case sensitive so you have to respect uppercase and lowercase comma
4. as follows e 19200 bauds e 1 stop bit e 8 data bits e no parity As soon as a client is connected to the serial port the Amethyst 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 Amethyst Arguments for each command are represented between lt gt e volume lt volume gt This command allows to change the main volume to the value lt volume gt dB This is the master level as it appears in the GUI of the Amethyst e dvolume lt delta gt This command allows to add lt delta gt dB to the main volume This value may be positive or negative e volume_ramp lt target gt lt duration gt This command allows to apply a volume ramp starting from current volume and reaching lt target gt volume in dB after lt duration gt milliseconds This command is available since version 3 7 3 of the Amethyst e mute lt action gt This command allows to change mute state if lt action gt is 0 mute is disabled sound is enabled if lt action gt is 1 mute is enabled sound is disabled if lt action gt is 2 mute state is inverted e dim lt a
5. bel and get_all_label It should be noted that connected clients must be ready to receive a message from the Amethyst at any time For example when a user changes the current volume whatever the way he does it the Amethyst sends a message indicating the new volume to all its connected clients Also when a calibration is started using the GUI the Amethyst sends loudspeaker coordinates to connected clients as after the loadp command This allows the Amethyst to interact with its connected clients This is therefore more a dialog between the client and the server than a request an swer 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 Amethyst namely regularly reading the state of the Amethyst a fortiori if this is done using frequent connections and disconnections to the machine As the Amethyst 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 Amethyst read all state variables which are relevant for the client and then remain connected waiting for possible changes sent by the Amethyst such as the volume for example However occasional connections and disconnections of a client to the machine are fine May 19 2015 Trinnov Amethyst Automation Protocol 5 TINNOY 7 Example H
6. ction gt This command allows to change dim state if lt action gt is 0 dim is disabled May 19 2015 Trinnov Amethyst Automation Protocol 2 if lt action gt is 1 dim is enabled if lt action gt is 2 dim state is inverted e bypass lt action gt This command allows to change bypass state if lt action gt is 0 bypass is disabled if lt action gt is 1 bypass is enabled if lt action gt is 2 bypass state is inverted e send_volume This command requests that the Amethyst 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 Amethyst e remapping mode lt mode gt This command allows to change remapping mode if lt mode gt is none remapping is disabled if lt mode gt is 2D 2D remapping is enabled if lt mode gt is 3D 3D remapping is enabled if lt mode gt is autoroute autorouting mode is enabled if lt mode gt is manual manual remapping is enabled e use_acoustics_correction lt action gt This command allows to change acoustic correction state if lt action gt is 0 acoustic correction is disabled if lt action gt is 1 acoustic correction is enabled if lt action gt is 2 acoustic correction state is inverted e use_level_alignment lt action gt This command allows to change level a
7. ends back the name of the source or profile number lt n gt 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 Amethyst 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 Amethyst itself no shutdown nor sound vanishing but only on the client server connection This command must not be used with the RS232 protocol Messages Here is a list non comprehensive too of the main messages sent by the Amethyst to connected clients e VOLUME lt vol gt This message provides the current main volume in dB May 19 2015 Trinnov Amethyst Automation Protocol 4 e DIM lt dim gt This message indicates whether dim is active if lt dim gt is 1 or not e MUTE lt mute gt This message indicates whether mute is active if lt mute gt is 1 or not e BYPASS lt bypass gt This message indicates whether bypass is active if lt bypass gt is 1 or not e META_PRESET_LOADED lt profile gt This message provides the active profile or source e SRATE lt srate gt This message provides the current sampling rate of the Amethyst e AUDIOSYNC STATUS lt status gt This message indicates whether the Amethyst is correctly synchronized with the audio source if lt status gt is 1 or not
8. ere is a communication example using TCP IP between the Amethyst 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 gt are the lines input by the user without gt the other lines are the answers of the Amethyst 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 Amethyst 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 gt id Trinnov Audio automation system OK gt loadp config_1 xml ERROR non existing or inaccessible config file gt loadp Config_1 xml OK SPEAKER_INFO O 1 36485 102 091 43 3817 SPEAKER_INFO 1 1 21479 100 781 28 5073 START_RUNNING gt volume 12 OK VOLUME 12 000000 gt dvolume 1 OK VOLUME 11 000000 gt mute 2 OK MUTE 1 gt mute 2 OK MUTE 0 gt 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 VOLUM
9. ions also support this lt file gt syntax The lt file gt 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 Amethyst get_label lt n gt This command sends back the name of preset number lt n gt This command is available since version 3 3 4 of the Amethyst 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 Amethyst profile lt source gt This command allows to change the current source also knwon as profile The argument is the source number where the first source is number 0 This command is available since version 3 4 tac_preset lt source gt This is an old alias for command profile 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 Amethyst get_profile_name lt n gt This command s
10. ke telnet in order to type command lines using the keyboard 3 3 Connection When a TCP connection is established on port 44100 the Amethyst sends a welcome message also providing the Amethyst 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 3 8 7 ID 8388609 May 19 2015 Trinnov Amethyst Automation Protocol 1 T2NNOV This identifier 8388609 is written 0x800001 in hexadecimal so the machine type is 8 corre sponding to the type Amethyst and the serial number is 1 The Amethyst 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 4 RS232 protocol The Amethyst can also be controlled using an RS232 link with a 9 pin null modem cable The RS232 serial port parameters are
11. lignment state if lt action gt is 0 level alignment is disabled if lt action gt is 1 level alignment is enabled if lt action gt is 2 level alignment state is inverted e use_time_alignment lt action gt This command allows to change time alignment state if lt action gt is 0 time alignment is disabled if lt action gt is 1 time alignment is enabled if lt action gt is 2 time alignment state is inverted e quick_optimized lt action gt This command allows to change optimization state if lt action gt is 0 optimization is disabled if lt action gt is 1 optimization is enabled if lt action gt is 2 optimization state is inverted e change_page lt delta gt This command changes the menu page currently displayed on the GUI The value of lt delta gt 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 May 19 2015 Trinnov Amethyst Automation Protocol 3 TINNOY 6 loadp lt preset file gt This command allows to load the preset number lt preset gt 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 Amethyst For older versions you have to use the lt file gt syntax described below where you provide a file name instead of a preset number For compatibility with versions before 3 3 4 newer vers
12. nd and COMMAND are two different commands Each command is followed by an answer message from the Amethyst 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 Amethyst 3 TCP IP protocol This communication mode uses the available TCP IP network connections of the Amethyst 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 Amethyst is done using DHCP during the boot The DHCP client of the Amethyst sends an identifier dhcp client identifier option of dhclient which is TRINNOV SRP lt id gt where lt id gt 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 depend ing on the version sub menu of the Setup page of the Amethyst 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 li
Download Pdf Manuals
Related Search