Skip to main content
Electronic Theatre Controls Inc

QSC Q-SYS Unison Mosaic Plugin Help

  1. Last updated
  2. Save as PDF
Introduction 

Thank you for choosing to integrate with ETC's Unison Mosaic architectural lighting control system. Please click here to learn more about Mosaic'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 six *.qplugx files and an example Q-SYS Designer file. The modular design of the plugins allow you to have virtually unlimited scalability for your project design. Directly control Mosaic timelines, scenes and triggers. Each control plugin has the capacity to control up to 100 Mosaic objects. 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.1
      • Mosaic V2.11.0 (API V7)
    • Moved Help page tab to the far right so the plugin controls are the first to be exposed when the plugin is opened
    • Fixed issue with I/O Handler timing out while trying to re-authenticate
    • Password field data within I/O Handler wasn't encapsulated which caused the Mosaic web server to reject alphanumeric passwords
    • I/O Handler prevents multiple subscriptions from the same control plugin
    • Added Login/Logout button to I/O Handler
    • Padlock icon will show locked when logged out and unlocked when logged in if authentication is enabled
    • Added option to attempt to reconnect for a designated number of times set within the I/O Handler properties after a failed connection (default: disabled)
    • Queries will not send from the core once the connection is detected missing
    • Modified sync time delay property limits for timeline, scene and universe control
    • Increased pin count for release all objects control within timeline & scene plugins
    • Exposed pins on all plugin controls
    • Added timer to force trigger object plugin to retrieve triggers 5 seconds after load
    • Trigger plugin was sending a total of two commands (e.g. push and release) now is limited to sending a single command on push
    • Added Park plugin
    • Added Color Override plugin
  • V1.0
    • Initial Release
    • Tested with the following firmware versions
      • Q-SYS V9.5.0
      • Mosaic V2.8.6 (compatible with V5.0 API only)
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 TCP/IP HTTP communication to/from the other control object plugins and Mosaic. 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 TCP port numbers for each I/O Handler used within the Q-SYS Design
  • Mosaic timeline and scene object numbers to control
  • Mosaic trigger type to control
I/O Handler Setup

Screenshot_Mosaic_IoHandler.png  

Runtime Elements UDP/IP (preferred)

  • Mosaic IP
    • IP address of the Mosaic controller
    • 0.0.0.0 (default)
  • HTTP Port
    • HTTP = 80
    • HTTPS = 443  (default)
    • The assigned port can be changed if needed
  • HTTP Mode 
    • HTTP
    • HTTPS (default)
  • Test API
    • Send/receive to/from Mosaic to verify bidirectional communication is occurring
    • Commands can be sent to Mosaic using the following format
      • Method;Path;Body Data;Query Data
    • Command Examples
      • GET Mosaic system information
        • GET;/api/system;{}
      • POST toggle timeline 101
        • POST;/api/timeline;{"action":"toggle","num":101,"fade": 2}
    • Please refer to the Mosaic API V7 help guide for a complete list of commands
  • HTTP Status (read only)
    • Displays communication errors and successful command execution
  • Authentication
    • If authentication is enabled on the Mosaic controller you will need to obtain the username and password to gain access
    • Once the correct username and password is entered Mosaic will send an auth token to Q-SYS
      • By default the Mosaic controller authentication timeout is set to 5 minutes
      • The Mosaic controller authentication timeout can be changed from 1-60 minutes by the ETC Mosaic Integrator
      • Be sure to set the Auth. Timeout (Mins) property within the I/O Handler to the same authentication timeout as the Mosaic controller (default 5 mins)
        • The I/O Handler has a built in 10 second grace period
          • If the auth. timeout is set to 5 minutes the I/O Handler will request a new token from Mosaic every 4 minutes and 50 seconds as long as the user has not manually logged out of the session
  • Login/Logout Button
    • The I/O Handler will automatically login to the Mosaic controller provided the correct username and password have been entered 
    • The user can login/logout to/from the Mosaic controller by pressing the button or triggering the appropriate pin 
    • It is reccommended to logout from the Mosaic controller during a Mosaic configuration upload/download

Designtime Properties

  • 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 Mosaic 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)
  • Auth. Timeout (mins)
    • Default is set to 5 minutes and needs to match the authentication timeout set within the Mosaic Controller 
  • I/O Max. Retries (default: disabled)
    • Number of times the core will try to reconnect if there is an interruption with the HTTP connection
    • The core will stop trying to reconnect once the maximum retries set within properties has been met or an HTTP connection has been established
    • Choices
      • 0-100 retries (default 0)
  • I/O Retry Interval (secs)
    • Delay time between retries
    • Choices
      • 30-300 retries (default 60)
  • On, Off & Pushed Button State
  • 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)

Control Pins

  • Disable
    • Direction
      • Input & Output
    • Values
      • 0/false
      • 1/true
  • Login/Logout
    • Direction
      • Input & Output
    • Values
      • Momentary/true/false
  • HTTP Mode
  • Status
    • Direction
      • Output
    • Values
      • string/text
  • HTTP Port
  • IP Address
  • Password
  • Username
  • Test API
    • Direction
      • Input & Output
    • Values
      • string/text
Timeline/Scene Control Setup 

Screenshot_Mosaic_Timelines.png    Screenshot_Mosaic_Timelines.png

Runtime Elements

  •  Load Timeline/Scene Range 
    • Enter the range of timelines/scenes to import into Q-SYS and then click the Load Timeline/Scene Data button to execute
      • This can be a combination of ranges and comma separated values (e.g. 1-5,10,23,80-85)
  • Name, Number, Group & Position (timeline only)
    • Read only fields that are populated by Mosaic's response to Q-SYS
  • Start Mode
    • Release All in Group Before Start (default)
      • When the start button is pressed down all timelines & scenes within the group will be released
      • When the start button is released the timeline/scene will start to play
    • Start Only
      • When the start button is pressed down the timeline/scene will start to play
  • LED Indicator
    • Indicates the started, released and paused status of the timeline
    • Indicates the started and released status of the scene
  • Start
  • Release
    • Releases the timeline/scene with the default fade time set within Mosaic
  • Toggle
    • Toggles the timeline/scene between the started and released states
  • Pause
    • Pauses the timeline at its current position
  • Resume
    • If the timeline was previously paused the timeline will start from the current position
  • Release All In Group
    • Releases all timelines and scenes within the group
    • If the group is set to None all timelines and scenes will be released in ALL groups

Designtime Properties

  • Timeline/Scene Quantity
    • Choices
      • 1-100 (default 1)
  • See Plugin Group ID
  • Sync Time Delay
    • The amount of time the plugin waits before requesting status updates from Mosaic
    • Increase the time delay if status is not properly updating or the system becomes unstable
    • Choices
      • 500ms-3600 seconds (default 1s)
  • OnStage Button/LED State
    • When the associated Mosaic timeline/scene is in control of levels 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)
      • clipboard_e09addd253d420c7b613fa80f24c98328.png
    • Alternatively the color can be set by entering any basic color name supported by Q-SYS (e.g. Red, Blue, Black, etc...)
  • Released Button/LED State
    • When the associated Mosaic timeline/scene has been fully released (wait for fade) the control will turn this color
  • Paused Button/LED State
    • When the associated Mosaic timeline has been paused (not moving) the control will turn this color
  • Pushed Button State
    • The control will immediately set to this color when a user triggers the control
    • Once Mosaic returns status the control will either be set to the on or off state color
  •  Show Debug
    • Exposes or hides the plugin's debug window
      • No (default)
      • Yes

Control Pins

  • See Disable
  • Release All in Group
  • Timeline/Scene Start
    • Direction
      • Input & Output
    • Values
      • Momentary/true/false
  • Timeline/Scene Load Data
  • Timeline/Scene Release
  • Timeline Resume
  • Timeline/Scene Toggle
  • Timeline Pause
    • Direction
      • Input & Output
    • Values
      • Trigger/true
  • Timeline/Scene Group
  • Timeline/Scene Name
  • Timeline/Scene Number
  • Timeline Position
  • Timeline/Scene Start Mode
    • Direction
      • Output
    • Values
      • string/text
  • Timeline/Scene Number Range
    • Direction
      • Input & Output
    • Values
      • string/text
  • Timeline/Scene Status
    • Direction
      • Output
    • Values
      • 0/false
      • 1/true
Enqueue Trigger Control Setup 

Screenshot_Mosaic_Timelines.png

Runtime Elements

  • Load Triggers 
    • Enter the trigger type (default is Soft) to import into Q-SYS and then click the Load Trigger Data button to execute
      • Unless the ETC integrator indicates a different trigger type to be used please leave the trigger type set to Soft
  • Name, Number and Description
    • Read only fields that are populated by Mosaic's response to Q-SYS
  • Pass Variables (optional)
    • Pass up to 6 optional variables with the trigger to be fired
    • Coordinate with the ETC integrator to verify what values/indices the receiving trigger is expecting
    • Values can be passed by directly typing the variable field or by input pin(s)
  • Enqueue Mode
    • Send Via Button/Pin Trigger (default)
      • The trigger will only fire when either a button is pressed or the pin is triggered
    • Send When Variables Change State
      • The trigger will fire when the optional variable state changes OR when either a button is pressed or a pin is triggered
  • Enqueue Trigger
    • Fires the trigger within Mosaic

Designtime Properties

Control Pins

  • See Disable
  • Enqueue Trigger Fire
  • Enqueue Trigger Load Data
    • Direction
      • Input & Output
    • Values
      • Momentary/true/false
  • Enqueue Trigger Number Range
  • Enqueue Trigger Variable 1-6
    • Direction
      • Input & Output
    • Values
      • string/text
  • Enqueue Trigger Description
  • Enqueue Trigger Mode
  • Enqueue Trigger Name
  • Enqueue Trigger Number
    • Direction
      • Output
    • Values
      • string/text
Override Control Setup 

Screenshot_Mosaic_Timelines.png

Runtime Elements

  • Target Type
    • Group (default)
    • Fixture
  • Number
    • Group or Fixture object number to control
    • If group is selected for target type a group number of 0 will control ALL fixtures
  • Fade Time (secs.)
    • Fade time when setting or releasing the override in seconds (default 0)
  • Crossfade Path
  • Release Override
    • Releases the override
    • If a timeline or scene was previously playing prior to the override being set the timeline or scene will output upon the release of the override
  • Hex RGB Color
    • Intended to interface the Q-SYS Color Picker component to this plugin for color mixing capabilities 
    • The IRGB sliders will track the levels that the Color Picker component are set to
    • Entering a 3 byte RGB level into this field will also update the IRGB sliders as well (e.g. #FF7F40)
      • The Color Picker component will not update based on input to this control
    • The background color of this control will update based on Color Picker input or movement of the IRGB sliders
  • Color Parameter & Intensity Sliders
    • Allows for 0-255 level control of the parameters selected within the Parameter Selection dropdown menu
    • Levels will not be sent to Mosaic until the Send Parameter Selection Levels button/pin has been triggered
      • Levels output are limited to the Parameter Selection chosen within the Parameter Selection dropdown menu
        • For example, if IRGB is selected as the Parameter Selection only intensity, red, green and blue slider levels will be sent once the Send Parameter Selection Levels button/pin is triggered
  • Parameter Selection
    • Intensity (default)
      • Formats command with intensity levels of the selected target
    • Intensity + CCT
      • Formats command with intensity and color temperature levels of the selected target
    • CCT
      • Formats command with color temperature levels of the selected target
    • IRGB
      • Formats command with intensity, red, green and blue levels of the selected target
    • HSI
      • Formats command with hue, saturation and intensity levels of the selected target
    • IRGB + CCT
      • Formats command with intensity, red, green, blue and color temperature levels of the selected target
    • HSI + CCT
      • Formats command with hue, saturation, intensity and color temperature levels of the selected target
  • Send Parameter Selection Levels
    • When triggered the Parameter Selection levels will be sent based on the level the Parameter Sliders are set to and the Parameter Selection dropdown

Designtime Properties

Control Pins

  • See Disable
  • Override Fade Time
  • Override Hex RGB Color
  • Override Number
    • Direction
      • Input & Output
    • Values
      • string/text
  • Override Parameter Selection
  • Override Path
  • Override Target
    • Direction
      • Output
    • Values
      • string/text
  • Override Release
  • Override Send Selected Parameters
    • Direction
      • Input & Output
    • Values
      • Momentary/true/false
  • Override Blue Level
  • Override CCT Level
  • Override Green Level
  • Override Hue Level
  • Override Intensity Level
  • Override Red Level
  • Override Saturation Level
    • Direction
      • Input & Output
    • Values
      • 0-255
Universe Control Setup 

Screenshot_Mosaic_Timelines.png    

Runtime Elements

  •  Load Universe Data
    • Click the Load Universe Data button to load all patched/enabled universes associated with the Mosaic Controller up to the max Universe Quantity set within the properties
    • Supported Universe types
      • DMX
      • sACN
      • Rio DMX
        • Rio 80
        • Rio 44
        • Rio 08
      • Pathport
      • Art-Net
      • KiNET
  • Protocol Status 
    • Read only field that displays if the universe is enabled or disabled
  • Universe 
    • Read only field that displays the universe type patched/enabled within the Mosaic Controller
  • Channel Range
    • Enter the desired channels to park/unpark
    • The channel entry can be a combination of comma separated and range values (e.g. 2-6,512,504,500,100-300)
  • Park Level
    • Can be entered as 0-255 or 0%-100%
  • LED Indicator
    • Indicates if the universe is enabled or disabled
  • Park
    • Parks the universe channels at the park level set
  • UnPark
    • Releases park control 
    • Any timelines, scenes or overrides that are active will output on the univerese once unparked
  • Toggle
    • Toggles between the park level and unpark

Designtime Properties

  • Universe Quantity
    • Choices
      • 1-100 (default 1)
  • See Plugin Group ID
  • See Sync Time Delay
    • Choices
      • 5-3600 seconds (default 5s)
  • Park Button State
    • When the Park button/pin is triggered the park & toggle button will change to this color
    • Please keep in mind this status is maintained within the Q-SYS Core as there is not a provision for park status within the Mosaic API
  • UnPark Button State
    • When the UnPark button/pin is triggered the unpark & toggle button will change to this color
    • Please keep in mind this status is maintained within the Q-SYS Core as there is not a provision for park status within the Mosaic API
  • Pushed Button State
    • The control will immediately set to this color when a user triggers the control
  • Protocol Enabled LED State
    • The LED will change to this color when the universe is enabled
  • Protocol Disabled LED State
    • The LED will change to this color when the universe is disabled
  • See Show Debug

Control Pins

  • See Disable
  • Protocol Status
    • Direction
      • Output
    • Values
      • 0/false
      • 1/true
  • Universe Park
  • Universe Toggle
  • Universe UnPark
    • Direction
      • Input & Output
    • Values
      • Trigger/true
  • Universe Channels
  • Universe Park Level
    • Direction
      • Input & Output
    • Values
      • string/text
  • Load Universe Data
  • Protocol Status String
  • Universe
    • Direction
      • Output
    • Values
      • string/text
  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
  2. Tags
    This page has no tags.