Uci

Use the Uci API functions to programmatically control and modify user control interfaces in Q-SYS.

UCI Script Overview

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: Some Lua methods are not supported – see Unsupported Lua Methods for details. When referencing the Uci Lua methods in your UCI script, it will not work if you define the UCI_Name variable because the script is local to the UCI and its name.

Note: When using the Uci.SetLayerVisibility within a UCI script, do not use the UCI_Name argument.

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, 'none')
 
          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')

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.

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

Uci.Get Methods

Retrieves the value of a variable that has been set in the UCI.

Syntax

Uci.GetVariable( UCI_Name, Variable_Name )

Arguments

UCI_Name : The UCI from which you want to retrieve the variable.

Variable_Name : The name of the variable you want to retrieve from the specified UCI.

Uci.LogOff Methods

Enable the ability to log off from a specified TSC touchscreen controller or UCI Viewer.

Note: Uci.LogOff can log out only if PIN security is enabled in Q-SYS Core Manager. For more information, see User Control Interfaces.

Syntax

Uci.LogOff( TSC_Name )

Arguments

TSC_Name : The name of the TSC touchscreen controller or UCI Viewer.

Example

Copy 
-- Control Alias
TSC = Controls.TSC_Name -- This textbox should contain the name of the TSC or UCI Viewer Inventory instance

-- UCI Log Off
Controls["Log Me Out"].EventHandler = function()
  print("Uci.LogOff() can only log out if PIN security is enabled on the panel")
  Uci.LogOff(TSC.String)
end

Uci.Set Methods

Set whether and how a layer is made visible within a specified UCI name and page.

Note: When using Uci.SetLayerVisibility within a UCI script, do not use the UCI_Name argument. For an example, see Setting UCI Layer Visibility.

Syntax

Uci.SetLayerVisibility( UCI_Name, Page_Name, Layer_Name, Visibility, Transition_Type )

Arguments

UCI_Name : String. The name of the UCI.

Page_Name : String. The name of the UCI page.

Layer_Name : String. The name of the UCI layer.

Visibility : true | false

Transition_Type : "none" | "fade" | "left" | "right" | "bottom" | "top"

Example

Copy 
--Set Layer Visibility
trans = Controls.Transition
trans.Choices = {"none","fade","left","right","bottom","top"}
if #trans.String==0 then trans.String = "none" end
for ix,layer in ipairs{"The Top Layer","The Middle Layer","The Bottom Layer"} do
  Controls[layer].EventHandler = function(ctl) 
    Uci.SetLayerVisibility( "Main UCI", "Page 1", layer, ctl.Boolean, trans.String )
  end
  Uci.SetLayerVisibility( "Main UCI", "Page 1", layer, Controls[layer].Boolean, trans.String )
end

Set which UCI page to display on a TSC touchscreen controller or UCI Viewer.

Syntax

Uci.SetPage( TSC_Name, Page_in_UCI )

Arguments

TSC_Name : The name of the TSC touchscreen controller or UCI Viewer.

Page_in_UCI : The UCI page to show.

Example

Copy 
-- Control Alias
TSC = Controls.TSC_Name -- This textbox should contain the name of the TSC or UCI Viewer Inventory instance

-- Set UCI Page
for key,ctl in ipairs(Controls.Page) do
  ctl.EventHandler = function()
    local TSC_Name = TSC.String
    Uci.SetPage(TSC_Name,"Page "..key)
  end
end

Set the screen status of a TSC touchscreen controller or UCI Viewer.

Syntax

Uci.SetScreen( TSC_Name, State )

Arguments

TSC_Name : The name of the TSC touchscreen controller or UCI Viewer.

State : "On" | "Off" | "Dim"

Example

Copy 
-- Control Alias
TSC = Controls.TSC_Name -- This textbox should contain the name of the TSC or UCI Viewer Inventory instance

-- Set Screen
for _,state in pairs{"On","Off","Dim"} do
  Controls[state].EventHandler = function()
    local TSC_Name = TSC.String
    Uci.SetScreen(TSC_Name,state)
  end
end

Set whether and how a shared layer is made visible within a specified UCI name and page.

Uci.SetSharedLayerVisibility is similar to UciSetLayerVisibility, but because Shared Layers can exist on multiple UCI pages, there is no argument for Page_Name. For more information about Shared Layers, see User Control Interface (UCI) Design Overview.

Note: When using Uci.SetSharedLayerVisibility within a UCI script, do not use the UCI_Name argument. For details and sample code, see Setting UCI Shared Layer Visibility.

Syntax

Uci.SetSharedLayerVisibility( 'UCI_Name', 'Layer_Name', Visibility, Transition_Type )

Arguments

UCI_Name : String. The name of the UCI.

Layer_Name : String. The name of the UCI layer.

Visibility : true | false

Transition_Type : "none" | "fade" | "left" | "right" | "bottom" | "top"

Set which UCI to display on a TSC touchscreen controller or UCI Viewer.

Note: To avoid errors when using the Uci.SetUCI function, the UCI Assignment property for the TSC touchscreen controller or UCI Viewer must be set to "Dynamic". For more information, see Status/Control (Touch Screen) and Status/Control (UCI Viewer).

Syntax

Uci.SetUCI( TSC_Name, UCI_Name )

Arguments

TSC_Name : The name of the TSC touchscreen controller or UCI Viewer.

UCI_Name : String. The name of the UCI.

Example

Copy 
-- Control Alias
TSC = Controls.TSC_Name -- This textbox should contain the name of the TSC or UCI Viewer Inventory instance

-- Set UCI
Controls["Main UCI"].EventHandler = function() local
  TSC_Name = TSC.String 
  Uci.SetUCI(TSC_Name,"Main UCI")
end
Controls["Other UCI"].EventHandler = function()
  local TSC_Name = TSC.String
  Uci.SetUCI(TSC_Name,"Other UCI")
end

Sets the Value of a Variable within a UCI.

Syntax

Uci.SetVariable( UCI_Name, Variable_Name, Value )

Arguments

UCI_Name : The name of the UCI where the variable is defined.

Variable_Name : The name of the variable you want to set.

Value : The value to assign to the variable.

Uci.Show Methods

Display a dialog in a UCI that contains a title, message, and button selection list.

Syntax

Uci.ShowDialog( UCI_Name, DialogTable )

Arguments

UCI_Name : String. The name of the target UCI for which to display the dialog.

DialogTable : A table consisting of the following elements

Title = "UCI dialog titlebar string",

Message = "Dialog message string",

Buttons = { "Button_String", "Button_String", "Button_String", "etc." }

The button list is a table consisting of strings – one string per desired response button.

Handler = EventHandler_Function

The EventHandler Function receives an integer index of which button was pressed. The EventHandler argument is zero-based, so add 1 to the integer to match a Lua table entry. See example.

Example

In this example, the ShowDialog control and event handler activates the dialog. The UCIDialogHandler event handler function calls the WhichButton control to provide feedback of which button was pushed, defined by a list of strings (ButtonText).

Copy 
ButtonText = {
  "Button 1 was pushed",
  "Button 2 was pushed",
  "Button 3 was pushed",
}

function UCIDialogHandler(choiceInt)
  print(choiceInt,ButtonText[choiceInt+1])
  Controls.WhichButton.String = ButtonText[choiceInt+1]
end

function ShowDialog()
  Uci.ShowDialog( 
    "Main UCI",
    {
      Title = "UCI Dialog Titlebar",
      Message = "Which button would you like to push?",
      Buttons = {
        "Button 1",
        "Button 2",
        "Button 3",
      },
      Handler = UCIDialogHandler,
    }
  )
end

Controls.ShowDialog.EventHandler = ShowDialog