QSC Q-SYS Unison Echo Plugin Help

Contents

• Introduction
• Summary
• Release Notes
• Getting Started
• General Setup
• Coordination
• Plugin Setup Details
  • I/O Handler
  • Preset Control
  • Level Zone Control
  • Level Channel Control
  • Sequence Control
  • Space Control (ET)
  • Space Control (EII)

Introduction

Thank you for choosing to integrate with ETC's Unison Echo architectural lighting control system. Please click here to learn more about Echo's product offerings. Please contact aesupport@etcconnect.com with any technical questions you may have regarding this Q-SYS plugin package.

Summary

The Q-SYS plugin package consists of five *.qplugx files and an example Q-SYS Designer file. The modular design of the plugins allow you to have virtually unlimited scaling ability for your project design. Directly control Echo presets, zones, channels, spaces and sequences. Each control plugin has the capacity to control up to 16 Echo objects with the exception of channels which has an 80 object limit. If you need more controls of a specific type simply drag in another control plugin instance into your schematic.

Release Notes

• V2.0
  • Tested with the following firmware versions
    • Q-SYS V9.9.0
    • Echo Integration Interface (EII) V3.3.6
    • EchoTouch (ET) V3.3.0
  • Added support for EchoTouch string interface
    • Channel set intensity
    • Space raise/lower
    • Space lockout
  • Changed Zone object plugin description to Level to encompass Zone (EII & ET) and Channel (ET only) objects
  • Added ability to import Echo object data into plugins from a spreadsheet (standard CSV format supported-[non-UTF])
  • Added connection status output pin to I/O Handler
  • I/O Handler plugin will now auto detect available NICs on the Core
  • I/O Handler protection implemented if the CORE reboots faster than the Ethernet switch in the system if the entire system reboots
  • I/O Handler will keep on retrying Ethernet connection until max retries have been obtained at the interval set within the plugin properties
  • Moved Help page tab to the far right so the plugin controls are the first to be exposed when the plugin is expanded
  • Fixed redundant subscriptions
  • Fixed nil arithmetic issue within level display selection drop-down
  • Set pin style to none for object level/space display, lower and raise containers
  • Set read only for object level/space display, lower and raise containers
• V1.0
  • Initial Release
  • Tested with the following firmware versions
    • Q-SYS V9.4.0
    • Echo Integration Interface (EII) V3.3.6

Getting Started

There are two ways to install the plugin package. Either double click each *.qplugx file or install through Q-SYS Designer's Asset Manager.

Once the plugins are properly installed drag in an instance of the I/O Handler plugin into your schematic. There must be at least one I/O Handler present within your schematic as this plugin is responsible for UDP/IP communication to/from the other three control object plugins and Echo. Next, drag in the desired control plugins into your schematic. Feel free to drag in multiple control plugin instances of the same type. The control plugins will automatically connect to the I/O Handler that have the same Plugin Group ID assigned...more on this below.

General Setup

Configuration of elements within the plugin UI can be done in runtime by either entering emulation mode (F6) or loading the design to the core (F5). Plugin properties that can be found within Designer located near the top right of the window can only be configured in designtime (e.g. not in emulation mode or connected to the core).

Coordination

Please coordinate with the ETC Field Service Engineer(s) assigned to the project to coordinate system details

• Device IP addresses
• Device port numbers 
  • Use unique UDP port numbers for each I/O Handler used within the Q-SYS Design
• Echo space numbers
• Echo control object numbers

I/O Handler Setup

Runtime Elements UDP/IP

• Output IP
  • IP address of the Echo Integration Interface (EII) or EchoTouch (ET)
• Output Port
  • Echo UDP port to send commands to
• Input Port 
  • Q-SYS UDP to receive status updates on
• Core NIC
  • Select the core NIC that is connected to the Echo control system
  • Not Selected (default)
• Test String
  • Send/receive to/from Echo to verify bidirectional communication is occurring
  • Send E$help to Echo to verify bidirectional communication
    • Echo will send a reply with all commands within the API
• Socket Status (read only)
  • Indicates OK when the proper IP, UDP ports and NIC  have been properly entered/selected and the core's hardware is operating properly
  • Indicates when in emulation mode
  • Indicates when a fault has occurred

Designtime Properties

• End of Message Char
  • Carriage return end of message byte is Echo's default 
  • Choices
    • CR (default)
    • CR+LF
    • LF
• Plugin Group ID
  • Assign all control plugins and the I/O Handler that need to communicate with each other to the same ID
  • The Plugin Group ID makes it possible to control many independent Echo systems from a single Q-SYS design
  • All plugins with the same group ID will play in their own control "sandbox" together
  • Most projects will only require the use of a single Plugin Group ID
  • Choices
    • 1-65535 (default 1)
• I/O Max. Retries
  • Number of times the core will try to open the UDP port after a reboot or design load
  • The core will stop trying to open the UDP port once the maximum retries set within properties has been met or the UDP opens
  • Utilize this feature if the Ethernet switch takes longer to boot than the Q-SYS core to avoid having to reboot the core
  • Choices
    • 0-100 retries (default 0)
• I/O Retry Interval (secs)
  • Delay time in between retries to open the UDP port
  • Choices
    • 0-100 retries (default 0)
• Sync Status on Boot
  • Exposes or hides the Sync Time Delay property
  • Polls Echo for status on boot when set to yes 
    • Choices
      • Yes (default)
      • No
• Sync Time Delay
  • Visible when Sync Status on Boot is set to Yes
  • The amount of time the core waits after a reboot before polling the Echo system for status
  • Increase the polling time if status is not properly updating on boot or when forcing sync status
  • Choices
    • 1-60 seconds (default 1 second)
• Print to Event Log
  • Sends received/transmitted data details to the core's webserver event log
  • After troubleshooting be sure to set this property to NO and reload the design to the core
  • Choices
    • No (default)
    • Yes
• Show Debug
  • Exposes or hides the plugin's debug window
    • No (default)
    • Yes (exposes Debug Print property)
• Debug Print
  • When Show Debug is set to Yes this property is visible
  • After troubleshooting be sure to set this property to NO and reload the design to the core
  • Choices
    • Show All(default)
      • Logs all of the below debug messages within the plugin's debug window
    • Show None
      • Turns off all debug logging
    • Show Errors
      • Logs errors the plugin produces
    • Show Function Calls
      • Logs when functions within the plugin are called
    • Show Rx
      • Logs received status updates from Echo
    • Show Rx/Tx
      • Logs sent/received commands/update to/from Echo
    • Show Tx
      • Logs sent commands to Echo

Control Pins

• Disable
  • Direction
    • Input & Output
  • Values
    • 0/false
    • 1/true
• Status
  • Direction
    • Output
  • Values
    • string/text
• Test String
  • Direction
    • Input & Output
  • Values
    • string/text

Preset Control Setup

Runtime Elements

• Force Sync Status
  • When triggered the plugin will poll the Echo system for ALL object's status
  • The plugin will update UI elements to reflect the proper on/off states of the objects they control within Echo based on the status returned
• CSV Object Import
  • Allows plugin data to be imported via CSV file for fast setup
  • CSV files must reside on the core
  • Non-UTF CSV format is supported
  • Here are examples of how to format the CSV files
• Preset Index
  • Select the Echo preset to control
• Space Index
  • Select the Echo space to control
• LED Indicator
  • Indicates the on/off status of the preset
  • If an associated zone level changes from the recorded preset look the preset status will change from on to off 
• On
  • Activates the preset
• Off
  • Deactivates the preset
• Toggle
  • Toggles the preset between the activated and deactivated states

Designtime Properties

• Preset Quantity
  • Choices
    • 1-16 (default 1)
• See Plugin Group ID
• See End of Message Char
• On Button/LED State
  • When the associated Echo object is on/active the control will turn this color
  • This overrides the colors set within the UCI editor
  • Enter the color by using the 6 character hex format omitting the alpha channel byte (e.g. #005696)
    • 
  • Alternatively the color can be set by entering any basic color name supported by Q-SYS (e.g. Red, Blue, Black, etc...)
• Off Button/LED State
  • When the associated Echo object is off/deactivated the control will turn this color
• Pushed Button State
  • The control will immediately set to this color when a user triggers the control
  • Once Echo returns status the control will either be set to the on or off state color
  • Echo status updates can take up to 1-5 seconds to be sent from the EII
• Import File Location
  • When the CSV Object Import button is pressed this path will be searched on the core for the desired CSV file
  • Default
    • media/etc/[object type].csv
• See Show Debug

Control Pins

• See Disable
• Preset Index
• Space Index
  • Direction
    • Input & Output
  • Values
    • string/text
• Preset Off
• Preset On
• Preset Toggle
• Preset Status
  • Direction
    • Output
  • Values
    • 0/false
    • 1/true
• Preset Sync Status
  • Direction
    • Input
  • Values
    • Trigger/true

Level Zone Control Setup

Runtime Elements

• See Force Sync Status
• See CSV Object Import
• Zone Index
  • Select the Echo zone to control
• See Space Index
• LED Indicator
  • Indicates the on/off status of the zone
• On
  • Activates the zone
• Off
  • Deactivates the zone
• Toggle
  • Toggles the zone between the on and off states
• Raise
  • Tap or press/hold to raise the zone level
  • Click the value above the raise button to change the value
  • Choices
    • 0-100% (default 5%)
• Lower
  • Tap or press/hold to lower the zone level
  • Click the value above the lower button to change the value
  • Choices
    • 0-100% (default 5%)
• Level Display
  • Displays the real time zone level in Echo
  • Click the dropdown above the display to change how the zone level is displayed
    • Choices
      • Percent (default)
      • 0-255
• Slider
  • Linear control of the zone level
  • Will update position based on zone status level updates from Echo
    • Status level updates from Echo are disabled on THIS slider while under manual control and will enable 5 seconds after releasing the slider

Designtime Properties

• Echo Device
  • Select the Echo device the core is connecting to
  • Choices
    • Echo Integration Interface
    • EchoTouch (must be selected to expose level type)
• Level Quantity
  • Choices
    • 1-80 (default 1)
      • When Echo Device type Echo Integration Interface is selected the maximum number of object instances will be limited to 16 when the number entered  is >= 16
      • When Echo Device type EchoTouch is selected and Level type is set to Zone the maximum number of object instances will be limited to 16 when the number entered  is >= 16
• See Plugin Group ID
• See End of Message Char
• See On Button/LED State
• See Off Button/LED State
• See Pushed Button State
• Raise/Lower Delay
  • The amount of time in seconds a user needs to hold the button before the level will repeatedly move
  • Choices
    • 0-60 seconds (default 1)
• Raise/Lower Interval
  • The amount of time in seconds the level is automatically applied while the user is holding the button
  • Choices
    • .250-60 seconds (default .500)
• See Import File Location
• See Show Debug

Control Pins

• See Disable
• See Space Index
• Zone Index
• Zone Level Display
  • Direction
    • Output
  • Values
    • 0-100% or 0-255
• Zone Raise Intensity
• Zone Lower Intensity
  • Direction
    • Input & Output
  • Values
    • Momentary Held/1/true
    • Momentary Release/0/false
• Zone Raise Value
• Zone Lower Value
  • Direction
    • Input & Output
  • Values
    • 0-100%
• Zone  Off
• Zone  On
• Zone  Toggle
  • Direction
    • Input & Output
  • Values
    • Trigger/true
• Zone Slider Level
  • Direction
    • Input & Output
  • Values
    • 0-255
• Zone Status
  • Direction
    • Output
  • Values
    • 0/false
    • 1/true
• Zone Sync Status
  • Direction
    • Input
  • Values
    • Trigger/true

Level Channel Control Setup

Runtime Elements

• See Force Sync Status
• See CSV Object Import
• Channel Index
  • Select the Echo channel to control
• LED Indicator
  • Indicates the on/off status of the channel 
• On
  • Activates the channel 
• Off
  • Deactivates the channel 
• Toggle
  • Toggles the channel  between the on and off states
• Raise
  • Tap or press/hold to raise the channel level
  • Click the value above the raise button to change the value
  • Choices
    • 0-100% (default 5%)
• Lower
  • Tap or press/hold to lower the channel level
  • Click the value above the lower button to change the value
  • Choices
    • 0-100% (default 5%)
• Level Display
  • Displays the real time channel level in Echo
  • Click the dropdown above the display to change how the channel level is displayed
    • Choices
      • Percent (default)
      • 0-255
• Slider
  • Linear control of the channel level
  • Will update position based on channel status level updates from Echo
    • Status level updates from Echo are disabled on THIS slider while under manual control and will enable 5 seconds after releasing the slider

Designtime Properties

• See Echo Device
• Level Type
  • Only exposed when EchoTouch is selected within the Echo Device property
  • Control either Echo Zone or Channel object per Level plugin instance/id
    • Choices
      • Zone (default)
      • Channel
• See Level Quantity
• See Plugin Group ID
• See End of Message Char
• See On Button/LED State
• See Off Button/LED State
• See Pushed Button State
• Raise/Lower Delay
  • The amount of time in seconds a user needs to hold the button before the level will repeatedly move
  • Choices
    • 0-60 seconds (default 1)
• Raise/Lower Interval
  • The amount of time in seconds the level is automatically applied while the user is holding the button
  • Choices
    • .250-60 seconds (default .500)
• See Import File Location
• See Show Debug

Control Pins

• See Disable
• Channel Index
  • Direction
    • Input & Output
  • Values
    • string/text
• Channel Level Display
  • Direction
    • Output
  • Values
    • 0-100% or 0-255
• Channel Raise Intensity
• Channel Lower Intensity
  • Direction
    • Input & Output
  • Values
    • Momentary Held/1/true
    • Momentary Release/0/false
• Channel Raise Value
• Channel Lower Value
  • Direction
    • Input & Output
  • Values
    • 0-100%
• Channel Off
• Channel On
• Channel Toggle
  • Direction
    • Input & Output
  • Values
    • Trigger/true
• Channel Slider Level
  • Direction
    • Input & Output
  • Values
    • 0-255
• Channel Status
  • Direction
    • Output
  • Values
    • 0/false
    • 1/true
• Channel Sync Status
  • Direction
    • Input
  • Values
    • Trigger/true

Sequence Control Setup

Runtime Elements

• See Force Sync Status
• See CSV Object Import
• Sequence Index
  • Select the Echo sequence to control
• See Space Index
• LED Indicator
  • Indicates the on/off status of the sequence
• On
  • Starts the sequence
• Off
  • Stops the sequence
• Toggle
  • Toggles the sequence between starting and stopping

Designtime Properties

• Sequence Quantity
  • Choices
    • 1-16 (default 1)
• See Plugin Group ID
• See End of Message Char
• See On Button/LED State
• See Off Button/LED State
• See Pushed Button State
• See Import File Location
• See Show Debug

Control Pins

• See Disable
• Sequence Index
• See Space Index
• Sequence Off
• Sequence On
• Sequence Toggle
  • Direction
    • Input & Output
  • Values
    • Trigger/true
• Sequence Status
  • Direction
    • Output
  • Values
    • 0/false
    • 1/true
• Sequence Sync Status
  • Direction
    • Input
  • Values
    • Trigger/true

Space Control (ET) Setup

Runtime Elements

• See Force Sync Status
• See CSV Object Import
• See Space Index
• LED Indicator
  • Indicates the on/off status of the space
• Lockout On
  • Lockout space
• Lockout Off
  • Unlock space
• Lockout Toggle
  • Toggle between locking and unlocking the space
• On
  • Activates all levels within space to 100%
• Off
  • Deactivates all levels within space to 0%
• Toggle
  • Toggles all levels within space between 0% and 100%
• Raise
  • Tap or press/hold to raise all space levels
  • Click the value above the raise button to change the value
  • Choices
    • 0-100% (default 5%)
• Lower
  • Tap or press/hold to lower all space levels
  • Click the value above the lower button to change the value
  • Choices
    • 0-100% (default 5%)

Designtime Properties

• See Echo Device
• Space Quantity
  • Choices
    • 1-16 (default 1)
• See Plugin Group ID
• See End of Message Char
• See On Button/LED State
• See Off Button/LED State
• Lockout On Button State
  • When the associated Echo space is locked out the control will turn this color
  • This overrides the colors set within the UCI editor
  • Enter the color by using the 6 character hex format omitting the alpha channel byte (e.g. #005696)
    • 
  • Alternatively the color can be set by entering any basic color name supported by Q-SYS (e.g. Red, Blue, Black, etc...)
• Lockout Off Button State
  • When the associated Echo space is unlocked the control will turn this color
• See Pushed Button State
• Raise/Lower Delay
  • The amount of time in seconds a user needs to hold the button before the level will repeatedly move
  • Choices
    • 0-60 seconds (default 1)
• Raise/Lower Interval
  • The amount of time in seconds the level is automatically applied while the user is holding the button
  • Choices
    • .250-60 seconds (default .500)
• See Import File Location
• See Show Debug

Control Pins

• See Disable
• See Space Index
• Space Raise Intensity
• Space Lower Intensity
  • Direction
    • Input & Output
  • Values
    • Momentary Held/1/true
    • Momentary Release/0/false
• Space Raise Value
• Space Lower Value
  • Direction
    • Input & Output
  • Values
    • 0-100%
• Space Lockout Off
• Space Lockout On
• Space Lockout Toggle
• Space Off
• Space On
• Space Toggle
  • Direction
    • Input & Output
  • Values
    • Trigger/true
• Space Status
  • Direction
    • Output
  • Values
    • 0/false
    • 1/true
• Space Sync Status
  • Direction
    • Input
  • Values
    • Trigger/true

Space Control (EII) Setup

Runtime Elements

• See Force Sync Status
• See CSV Object Import
• See Space Index
• Off
  • Deactivates all levels within space to 0%

Designtime Properties

• See Echo Device
• See Space Quantity
• See Plugin Group ID
• See End of Message Char
• See Off Button State
• See Pushed Button State
• See Import File Location
• See Show Debug

Control Pins

• See Disable
• See Space Index
• See Space Off
• See Space Sync Status