User Guide for LIGHTWARE models including: Biamp TesiraFORT DSP Driver for LARA, TesiraFORT DSP Driver for LARA, DSP Driver for LARA, Driver for LARA, LARA
Biamp TesiraFORTÉ DSP driver for LARA v1.0.0
Lightware Advanced Room Automation (LARA)
File Info : application/pdf, 14 Pages, 568.84KB
DocumentDocumentBiamp TesiraFORTÉ DSP driver for LARA v1.0.0 Page 2 TABLE OF CONTENTS 1. INTRODUCTION .......................................................................................................................................... 3 1.1. REFERENCES .......................................................................................................................................... 3 2. SOLUTION OVERVIEW ............................................................................................................................... 3 2.1. EVENTS DEFINED IN THE DRIVER ............................................................................................................... 3 2.2. METHODS DEFINED IN THE DRIVER........................................................................................................... 3 2.3. SUBSCRIBE TYPE METHODS..................................................................................................................... 4 2.3.1. subscribeUSBStatus...................................................................................................................... 4 2.3.2. subscribeMute ............................................................................................................................... 5 2.3.3. subscribeLevel............................................................................................................................... 5 2.4. GET TYPE METHODS ............................................................................................................................... 5 2.4.1. getMute.......................................................................................................................................... 5 2.4.2. getLevel ......................................................................................................................................... 6 2.4.3. getFirmware................................................................................................................................... 6 2.4.4. getSerial......................................................................................................................................... 6 2.5. SET TYPE METHODS................................................................................................................................ 6 2.5.1. setLevel ......................................................................................................................................... 6 2.5.2. setMute .......................................................................................................................................... 6 2.6. OTHER METHODS .................................................................................................................................... 6 2.6.1. recallPreset.................................................................................................................................... 6 2.6.2. incLevel.......................................................................................................................................... 7 2.6.3. decLevel ........................................................................................................................................ 7 2.6.4. toggleMute ..................................................................................................................................... 7 2.6.5. unsubscribeLevel........................................................................................................................... 7 2.6.6. unsubscribeMute ........................................................................................................................... 7 2.6.7. unsubscribeUSBStatus.................................................................................................................. 7 2.6.8. sendFrame .................................................................................................................................... 7 3. INSTALLATION AND CONFIGURATION ................................................................................................... 8 3.1. PREREQUISITES....................................................................................................................................... 8 3.2. INSTALLATION.......................................................................................................................................... 8 3.2.1. Uploading the Tesira driver module .............................................................................................. 8 3.2.2. Create an instance for a particular Tesira device to control .......................................................... 8 3.2.3. Configuring the instance.............................................................................................................. 10 4. SAMPLE CONFIGURATION...................................................................................................................... 11 4.1. USING THE SAMPLE CONFIGURATION...................................................................................................... 12 4.1.1. Upload the sample configuration to the Tesira DSP ................................................................... 12 4.1.2. Upload the sample LARA configuration to the Lightware UCX/MMX2 device ............................ 12 4.1.3. Modify the IP address settings of testinstance to match your actual Tesira device .................... 12 4.1.4. Operation of the configuration ..................................................................................................... 13 5. APPENDIX.................................................................................................................................................. 14 5.1. FURTHER INFORMATION ......................................................................................................................... 14 Biamp Tesira DSP driver for LARA v1.0.0 Page 3 1. Introduction The scope of this document is to help integrators understand and configure the Biamp Tesira driver for LARA. The driver supports Tesira control over Telnet (TCP/IP). Firmware and software versions used and tested during the development: Biamp Tesira Designer Software v4.5.0.23124 Biamp Tesira Firmware v4.5 Lightware UCX firmware v2.4.0b1 The downloadable package contains: Tesira driver module: Biamp_TesiraFORTE_driver_module_v1.0.0.zip Sample configuration: Sample_config_Tesira_control_v1.0.0.zip Documentation: LARA_Biamp_TesiraFORTE_DSP_driver_module_v1.0.0.pdf TesiraFORTE X 400 config file: sample_config_FORTEX400.tmf 1.1. References Lightware LARA Users Manual Lightware UCX series Users Manual Biamp Tesira Text Protocol 3.0 Biamp Tesira Text Protocol Cornerstone Biamp Tesira Command String Calculator 2. Solution Overview Biamp Tesira DSP driver module for LARA provides the ability to control selected parameters of the Tesira DSP installed beside a Lightware Universal Matrix Switcher (either UCX or MMX2). In order to have a working solution the UCX/MMX2 has to be connected to the Tesira DSP through a local network. The main feature of this solution is to provide DSP control functions for integrators, to be able to use the same user interface for controlling video, shades, lights as well as audio. Functions provided by the driver module are introduced in the following chapters. 2.1. Events defined in the driver Event TTP connected Subscribed parameter changed Parameter query response received Description The Tesira DSP is ready for receiving and executing commands Fires, when any subscribed parameter is changed Fires, when a response is received for a get command. Response for getSerial and getFirmware does not activate the event. There are other events in the driver, but they originate from the base module, so those are not listed here. Biamp Tesira DSP driver for LARA v1.0.0 Page 4 2.2. Methods Defined in the Driver Methods are used to realize functions in the DSP, e.g. setting values, querying parameters, etc. The methods can be called from other modules e.g. Logic module, or User panel module. The implemented methods can be found below: · recallPreset · getLevel · subscribeLevel · getMute · subscribeMute · getSerial · subscribeUSBStatus · getFirmware · setLevel · unsubscribeLevel · incLevel · unsubscribeMute · decLevel · unsubscribeUSBStatus · setMute · sendFrame · toggleMute 2.3. Subscribe Type Methods These methods are used to subscribe to parameter changes of different processing blocks. When a subscribed parameter is changed, the "Subscribed parameter changed" event getting triggered and the unique name (custom label for feedback in Tesira) and the new value of the parameter is being stored/updated in a json object called dspData. The unique name is generated automatically, for details of the unique name, see the particular method's description. With the event, the actual state of all the subscribed parameters are handed over with the dspData json object. Below you can see the content of the json object logged to the console. For more detailes please check the sample configuration. 2.3.1. subscribeUSBStatus Subscribes to changes of the connection status of the given USB input/output block. Parameter instanceTag refreshRate Description Instance tag of the USB input/output block Time in milliseconds, describes how often the DSP will send updates The update sent by the DSP is processed by the driver module and it stores the latest values in a json object. The property of each item is the unique name, what is calculated automatically according to the followings: unique name: FB-USB-x-connected where FB-USB- is fixed x is the instance tag -connected is fixed. Biamp Tesira DSP driver for LARA v1.0.0 Page 5 2.3.2. subscribeMute Subscribe to changes of a mute button change. Parameter instanceTag channel refreshRate Description Instance tag of the level/mute block Channel number Time in milliseconds, describes how often the DSP will send updates The unique name is calculated automatically according to the followings: unique name: FB-x-chy-mute where FB- is fixed x is the instance tag -ch is fixed y is the number of the channel inside the processing block -mute is fixed. 2.3.3. subscribeLevel Subscribe to changes of a level parameter. Parameter instanceTag channel refreshRate Description Instance tag of the level block Channel number Time in milliseconds, describes how often the DSP will send updates The unique name is calculated automatically according to the followings: unique name: FB-x-chy-level where FB- is fixed x is the instance tag y is the number of the channel inside the processing block -level is fixed 2.4. Get Type Methods These methods are used to query the actual value of a parameter. When the DSP sends its response to a get command, the "Parameter query response received" event getting triggered, and the unique name of the parameter and it's value are stored in variables (qrVariable, qrValue). Those variables are handed over as event parameters. The unique name is generated automatically, for details of the unique name, see the particular method's description. 2.4.1. getMute Queries the actual state of a mute button. Parameter instanceTag channel Description Instance tag of the level/mute block Channel number The unique name is calculated automatically according to the followings: unique name: QR-x-chy-mute where QR- is fixed x is the instance tag -ch is fixed y is the number of the channel inside the processing block -mute is fixed. Biamp Tesira DSP driver for LARA v1.0.0 Page 6 The value is a Boolean type, can be true or false. 2.4.2. getLevel Queries the actual value of a level parameter. Parameter instanceTag channel Description Instance tag of the level block Channel number The unique name is calculated automatically according to the followings: unique name: QR-x-chy-level where QR- is fixed x is the instance tag -ch is fixed y is the number of the channel inside the processing block -level is fixed. The value is a number in dB 2.4.3. getFirmware Queries the firmware version of the connected Tesira DSP device. The driver automatically queries the firmware version at startup, and shows it on the Status Board. The method does not have any parameters. 2.4.4. getSerial Queries the serial number of the connected Tesira DSP device. The driver automatically queries the serial number at startup, and shows it on the Status Board. The method does not have any parameters. 2.5. Set Type Methods These methods are used to set parameters to an absolute value. 2.5.1. setLevel Sets the level to an absolute value. Parameter instanceTag channel value Description Instance tag of the level block Channel number The required value of the level parameter in dB 2.5.2. setMute Sets a mute button to on or off. Parameter instanceTag channel value Description Instance tag of the level/mute block Channel number The required state of the mute button (true for mute on, false for mute off) 2.6. Other Methods 2.6.1. recallPreset Used for recalling presets set up in Tesira software by the preset's ID number. Parameter presetNumber Description ID number of the preset, you want to recall Biamp Tesira DSP driver for LARA v1.0.0 Page 7 2.6.2. incLevel Increases the value of a level parameter by the specified value. Parameter instanceTag channel value Description Instance tag of the level block Channel number Value in dB by which you want to increase the original value 2.6.3. decLevel Decreases the value of a level parameter by the specified value. Parameter instanceTag channel value Description Instance tag of the level block Channel number Value in dB by which you want to decrease the original value 2.6.4. toggleMute Toggles between the on and off state of a mute button. Parameter instanceTag channel Description Instance tag of the level/mute block Channel number 2.6.5. unsubscribeLevel Stops the Tesira DSP device to send updates regarding the specified level parameter. Parameter instanceTag channel Description Instance tag of the level block Channel number 2.6.6. unsubscribeMute Stops the Tesira DSP device to send updates regarding the specified mute parameter. Parameter instanceTag channel Description Instance tag of the level/mute block Channel number 2.6.7. unsubscribeUSBStatus Stops the Tesira DSP device to send updates regarding the USB connection status. Parameter instanceTag Description Instance tag of the USB input or output block 2.6.8. sendFrame Sends a custom command to the Tesira DSP device. With the help of this method it is possible to send commands to the DSP, which are not yet implemented in the driver. Parameter message Description Command string to send to the DSP Biamp Tesira DSP driver for LARA v1.0.0 Page 8 3. Installation and Configuration of the Driver 3.1. Prerequisites In order to use the Tesira driver for LARA, you must have a configured Biamp DSP. To do that please refer to the user manual of the Biamp device/software. There are settings that has to be set at Biamp side in order to let the control system work: In case of Telnet control, Telnet must be enabled in Tesira-Network Settings Tesira device must be unprotected Instance tags must not contain spaces for proper operation 3.2. Installation This section assumes that you are familiar with your Biamp Tesira DSP, and Lightware Taurus UCX, MMX2 devices, and you know their IP address and you have enabled LARA functionality. Further, you have your computer connected to the same IP subnet, where your devices located. 3.2.1. Uploading the Tesira driver module You can upload the Tesira DSP driver module to a new/existing LARA configuration by clicking on the Upload module icon shown below. Browse and open the module as a ZIP archive. You have to enter a name for the module. When uploaded successfully it has to appear on the Browse Modules tab as it is shown below. 3.2.2. Create an instance for a particular Tesira device to control In order to be able to communicate with a device, an instance has to be created from the module, what is called "Biamp_Tesira" in the example above. To create an instance, you have to select the module and click on the "Create new instance from the selected module" shown below. Biamp Tesira DSP driver for LARA v1.0.0 Page 9 Instances have to have a unique name, let's call it "testinstance". Configuration can be done at the time of creation, right from the window shown below, but those settings can be modified later as well. Please note that instance names cannot be modified after creation! When the instance has been created successfully, it is indicated by the green instance indicator next to the module's name, on the Browse Modules tab. When an instance is created it appears on the Status Board as well, as it is shown below. Biamp Tesira DSP driver for LARA v1.0.0 Page 10 3.2.3. Configuring the instance The instance has to be configured by its parameters. Most of the parameters can be selected using dropdown lists. Parameters can be edited by clicking the "Edit instance parameters" button as shown below: Editable parameters and its possible values can be find in the table below. Parameter Control type Enable console logging IP address or hostname Possible values Description CONTROL PARAMETERS Telnet To control the DSP by Telnet over Ethernet false Messages regarding the operation will not be logged to the console. true Messages regarding the operation will be logged to the console. TELNET RELATED SETTINGS x.x.x.x IP address or hostname to use when connecting The Edit instance parameters window is shown below. Biamp Tesira DSP driver for LARA v1.0.0 Page 11 4. Sample Configuration The downloaded package contains the driver module itself, and a sample configuration package. The sample configuration is provided to let you study how the driver module interacts with other modules in a configuration. The sample configuration package contains the followings: Tesira configuration file (prepared for TesiraFORTÉ X 400) LARA configuration file What you need to test the sample configuration: Lightware Taurus UCX/MMX2 series universal matrix switcher Biamp TesiraFORTÉ X 400 Instead of the X 400 you can use other TesiraFORTÉ DSP units, but you might have to recreate the Tesira configuration file for yourself. The screenshot below shows the design of the sample configuration, with the instance tags of the blocks used in the LARA configuration. Biamp Tesira DSP driver for LARA v1.0.0 Page 12 4.1. Using the Sample Configuration 4.1.1. Upload the sample configuration to the Tesira DSP For the method, please refer to the Biamp documentation. 4.1.2. Upload the sample LARA configuration to the Lightware UCX/MMX2 device Click upload configuration on your main LARA window. Browse and select the sample configuration file. 4.1.3. Modify the IP address settings of testinstance to match your actual Tesira device Refer to section 3.2.3. After you've finished the configuration, you should see something like this: Biamp Tesira DSP driver for LARA v1.0.0 Page 13 4.1.4. Operation of the configuration At startup the configuration subscribes to the following parameters: Instance tag Level1 Mute1 Level2 USBXOutput1 USBXInput1 Attribute level mute mute level mute connected connected Channel nr. 1 1 1 1 2 1 2 N/A N/A Automatically generated unique name for feedback FB-Level1-ch1-level FB-Level1-ch1-mute FB-Mute1-ch1-mute FB-Level2-ch1-level FB-Level2-ch2-level FB-Level2-ch1-mute FB-Level2-ch2-mute FB-USB-USBXOutput1-connected FB-USB-USBXInput1-connected When there are changes to the parameters above in Tesira, the new value is stored in the json object named dspData. The property will be the automatically generated unique name and the value is the new value of the particular parameter. In the Logic module there is a rule (Subscribed parameter changed) what is triggered when any subscribed parameter changed in Tesira. The rule logs the content of dspData to the console and simultaneously write the actual values to the debug panel. The pictures below are showing the console, and the user panel output. Biamp Tesira DSP driver for LARA v1.0.0 5. Appendix 5.1. Further Information Document Revision History Rev. 1.0.0 Release date 21.07.2023 Initial version Changes Page 14 Editor Péter Krischneider Biamp Tesira DSP driver for LARA v1.0.0