UCI Controller [BETA]

UCI Controller is a User Control Interface (UCI) design feature that is an alternative method of building UCIs. The traditional method involves copying controls from design components into a UCI, which thus ties that UCI to the design. UCI Controller, however, allows you to build a UCI from a list of template control types (Toggle, Knob, etc.), link one or more controls to components in the design, and then write a dedicated Lua script for the UCI. The UCI, and its script, can then be easily copied, re-used, and modified as desired.

Note: This is a BETA feature. Though it is functional, it is not feature complete.

  1. Select a UCI name from the User Control Interfaces section of the left-side pane. (To learn how to create a UCI, see UCI Design.)

  2. Click the Toolbox tab. You'll see a list of control types:

  3. Drag a control type into the UCI.

  4. In the right-side Properties pane, assign a unique Control Name that can optionally be referenced in a UCI Script.

  5. Configure the rest of the control's properties as you would with any other control.

  6. Add more controls as desired.

Link a UCI control to a component control in your design, and then easily re-link (or un-link) the control later if the UCI's use case changes. You can thus build an entire UCI and link its controls to components without ever having to wire anything in the design itself. There are two methods to link controls.

Using Link Icon

  1. With your UCI selected, click the Layers tab.

  2. For the control you wish to link, click the Link icon. For example, here is a UCI control configured as a toggle:

  3. Select the component and control from that component to link to the UCI control. For example, here we have linked the toggle control to the Mute button of a Gain component:

Tip: If you later wish to link the UCI control to another component control, just click the Link icon again and select a different control for linking.

Using Drag and Drop

  1. In the schematic window, click and hold the desired component control you wish to link.

  2. Drag the control to the UCI tab/window.

  3. While hovering over the button/shape in the UCI, press and hold Ctrl on the keyboard.

  4. Release the mouse/trackpad while still holding Ctrl and a prompt will appear. Select from the following:

    • Link Control - Links the control to the current control design

    • Transfer Control Style - Links and overwrites with the original component control graphic

Tip: If you later wish to link the UCI control to another component control, just repeat the drag and drop process while selecting a different control for linking.

The UCI Script tab contains a familiar interface for authoring Lua code specific to the selected UCI. This makes it easy to duplicate a UCI and update the new one (i.e., modify the script) with different parameters. One use case, for example, is having multiple UCIs with differing Layer and Shared Layer visibility settings.

Note: A Q-SYS Scripting Engine feature license is not required for building and running scripts contained within the UCI Script tab. Some Lua methods are not supported – see Unsupported Lua methods for details.

Note: When referencing the Uci Lua methods in your UCI script, it is unnecessary to define the UCI_Name variable because the script is local to the UCI and its name.

Examples

Here is a simple UCI script that sets layer visibility.

Copy 
timer0 = Timer.New()
 
 
timer0.EventHandler = function()
  Uci.SetLayerVisibility('Page 1', 'Layer 1', false, 'fade')
  Timer.CallAfter(function()
      Uci.SetLayerVisibility('Page 1', 'Layer 1', true, 'fade')
    Uci.SetLayerVisibility('Page 1', 'Layer 2', false, 'left')
 
    Timer.CallAfter(function()
        Uci.SetLayerVisibility('Page 1', 'Layer 2', true, 'left')
    Uci.SetLayerVisibility('Page 1', 'Layer 3', false, 'right')
 
      Timer.CallAfter(function()
          Uci.SetLayerVisibility('Page 1', 'Layer 3', true, 'right')
    Uci.SetLayerVisibility('Page 1', 'Layer 4', false, 'top')
 
        Timer.CallAfter(function()
            Uci.SetLayerVisibility('Page 1', 'Layer 4', true, 'top')
    Uci.SetLayerVisibility('Page 1', 'Layer 5', false, 'bottom')
 
          Timer.CallAfter(function()
              Uci.SetLayerVisibility('Page 1', 'Layer 5', true, '')
 
          end,1)
        end,2)
      end,2)
    end,2)
  end,2)
end
 
 
timer0:Start(10)

This line instructs the a Shared Layer in a UCI to become hidden with a fade transition.

Copy 
Uci.SetSharedLayerVisibility('Shared Layer 1', false, 'fade')

Unsupported Lua methods

Some Lua methods are not supported in UCI scripts, including methods from the following libraries. If you use these methods in the UCI Script tab, you will see this error in the Debug Output window: "This feature is unavailable in UCI Controller."

Note: These Lua methods are not supported in the UCI Scripts tab even if a Q-SYS Scripting Engine feature license is installed on the Q-SYS Core processor.

  • Bonjour
  • Curl
  • dir
  • Email
  • http
  • HttpClient
  • icmp
  • imap
  • lua_reflect
  • loop_player
  • Midi
  • Notifications
  • Ping
  • Serial
  • Snapshot
  • socket
  • snmp
  • Ssh
  • TcpSocket
  • udp
  • usb
  • UdpSocket

You can optionally expose control pins for each control that you have added to the UCI from the Toolbox, and then wire those control pins as you would with other components. Use the UCI Controller component to view and wire Toolbox control pins.

  1. In your UCI, select a Toolbox control and configure the Control Pin property. You choose to expose Input, Output, Both, or no (None) control pins.

  2. From the User Control Interfaces left-side menu, drag the UCI Controller component for your UCI into the schematic.

  3. Wire the control pins as you would with other components.

Standard Control Pins

The UCI Controller component includes the same standard script control pins as other scripting components, selectable from the Control Pins section of the right-side pane.

Pin Name

Value

String

Position

Pins Available

Code

(text)

Allows you to enter code.

Input / Output

Script Start

(trigger)

Starts the script running.

Input / Output

Script Status

(text)

Current status of the script.

Output

Script Stop

(trigger)

Stops the script.

Input / Output

Export and import UCIs to facilitate easy sharing between system designers. You can also download and import UCIs from Asset Manager.

Export a UCI

  1. From the User Control Interfaces section of the left-side pane, select the UCI you want to export.

  2. Click Tools > Export UCI.

  3. Select a location on your computer and click Save. The UCI is saved with the .uci file extension.

Import a UCI

  1. Click Tools > Import UCI.

  2. Select the .uci file to import, and then click Open.

  3. From the User Control Interfaces section of the left-side pane, select the imported UCI.

  4. Link or remap the UCI's controls to schematic components, depending on the control type:

    • Toolbox controls – Controls that were added from the Toolbox will appear in the Layers tab with a icon. Follow the instructions in the "Link Controls" section above to link each control to a component control in your design.

    • Unmapped controls – Controls that were originally added to the UCI from the schematic are indicated with a ? icon. Follow the instructions in Transferring Settings from one Control to Another to remap the UCI control from a control in the schematic.