Skip to main content
Electronic Theatre Controls Inc

QSC Q-SYS Unison Mosaic Plugin Help

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 four *.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
  • 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 three 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
  • 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
    • 10.101.120.101 (default)
  • HTTP Port
    • HTTP = 80 (default)
    • HTTPS = 443
    • The assigned port can be changed if needed
  • HTTP Mode 
    • HTTP (default)
    • HTTPS
  • 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 V5 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
      • Every 290 seconds Q-SYS will retrieve another token from Mosaic to maintain connectivity

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)
  • 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
  • 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
      • 250ms-60 seconds (default 500ms)
  • 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
  • Exposes or hides the plugin's debug window
    • No (default)
    • Yes

Control Pins

  • See Disable
  • Release All Timeline's & Scene's in Group
  • Timeline/Scene Start
    • Direction
      • Input & Output
    • Values
      • Momentary/true/false
  • Timeline Pause, Release, Resume, Toggle
    • Direction
      • Input & Output
    • Values
      • Trigger/true
  • Scene Release & Toggle
    • Direction
      • Input & Output
    • Values
      • Trigger/true
  • Timeline Position
    • Direction
      • Output
    • Values
      • 0-100%
  • 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
      • The trigger will only fire when either a button is pressed or a 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

  • Enqueue Trigger Quantity
    • Choices
      • 1-100 (default 1)
  • See Plugin Group ID
  • See Sync Time Delay
  • See Released Button State
    • The control will immediately set to this color when a user releases the button
  • See Pushed Button State
    • The control will immediately set to this color when a user triggers the control
  • See Show Debug

Control Pins

  • See Disable
  • Enqueue Trigger Fire
    • Direction
      • Input & Output
    • Values
      • Momentary/true/false
  • Enqueue Trigger Variable 1-6
    • Direction
      • Input
    • Values
      • String Text/Numeric
  • Was this article helpful?