### Q-Sys NamedControl Examples

Source: https://help.qsys.com/Content/Control_Scripting/Using_Lua_in_Q-Sys/NamedControl.htm

Demonstrates setting an integer control's value with a ramp time, getting a text display control's string value, and triggering a control button.

```lua
NamedControl.SetValue("CustomControlsInteger1",	7,	15)		--	Set	value	of	a	named	integer	control	to	7,	ramp	15	seconds
NamedControl.GetString("CustomControlsTextdisplay1")		--Get	string	value	of	a	control
NamedControl.Trigger("CustomControlsTrigger1")		--Triggers	a	controlled	trigger	button
```

--------------------------------

### List Media Resources Request URL

Source: https://help.qsys.com/Content/Management_APIs/Management_APIs_Overview.htm?TocPath=Local+Management%7CManagement+APIs%7C_____0

Example URL for listing folders and files in the root '/media' directory of a Q-SYS Core processor. This is a GET request.

```url
https://core-ip-address/api/v0/cores/self/media
```

--------------------------------

### Example Media Resources Response

Source: https://help.qsys.com/Content/Management_APIs/media_resources.htm

This is an example JSON response showing details of media resources, including folders and files.

```json
[
  {
    "created": 1613479883289,
    "ext": null,
    "name": "example folder 0",
    "path": "Audio/example folder 0",
    "size": null,
    "type": "folder",
    "updated": 1613479883289
  },
  {
    "created": 1613477726987,
    "ext": "mp3",
    "name": "example file 0",
    "path": "Audio/example file 0.mp3",
    "size": 764176,
    "type": "file",
    "updated": 1613477727015
  }
]
```

--------------------------------

### Lua Function Definitions for Parameter and Vararg Examples

Source: https://help.qsys.com/Content/Control_Scripting/Lua_5.3_Reference_Manual/3_-_The_Language.htm

Provides example function definitions used to illustrate parameter and vararg behavior.

```lua
     function f(a, b) end
			function g(a, b, ...) end
			function r() return 1,2,3 end
		

```

--------------------------------

### SSH Client Configuration and Connection Example

Source: https://help.qsys.com/Content/Control_Scripting/Using_Lua_in_Q-Sys/Ssh.htm

Demonstrates setting up an SSH client object, configuring timeouts, and establishing a connection using provided credentials. Includes callback functions for connection events.

```lua
-- Aliases  
IPAddress = Controls.IPAddress  
UserName = Controls.UserName  
Password = Controls.Password  


-- Constants  
SSH = Ssh.New()  -- create new SSH object  
SSH.ReadTimeout = 5  -- set read timeout to 5 seconds  
SSH.WriteTimeout = 5  -- set write timeout to 5 seconds  
SSH.ReconnectTimeout = 5  -- set reconnect timeout to 5 seconds  
Port = 22  -- port of the SSH server  


-- Functions  
function CredentialsEntered()  -- returns true if ip, user name and password have been entered  
  return IPAddress.String~="" and UserName.String~="" and Password.String~=""  
end  

function Connect()  -- function to start the SSH session  
  if SSH.IsConnected then SSH:Disconnect() end  -- if SSH is connected disconnect  
  if CredentialsEntered() then SSH:Connect(IPAddress.String,Port,UserName.String,Password.String) end  -- if all credentials are entered attempt to connect  
end  

function Initialization()  -- function called at start of runtime  
  print("Initializing plugin")  
  Connect()  
end  

--Parsers  
function ParseResponse()  -- function that reads the SSH TCP socket  
  local rx=SSH:Read(SSH.BufferLength)  -- assign the contents of the buffer to a variable  
  print("RX: "..rx)  
end  


-- SSH socket callbacks  
SSH.Connected=function()  -- function called when the TCP socket is connected  
  print("Socket connected")  
end  

SSH.Reconnect=function()  -- function called when the TCP socket is reconnected  
  print("Socket reconnecting...")  
end  

SSH.Closed=function() -- function called when the TCP socket is closed  
  print("Socket closed")  
end  

SSH.Error=function()  -- function called when the TCP socket has an error  
  print("Socket error")  
end  

SSH.Timeout=function()  -- function called when the TCP socket times out  
  print("Socket timeout")  
end  

SSH.LoginFailed=function()  -- function called when SSH login fails  
  print("SSH login failed")  
end  

SSH.Data=ParseResponse  -- ParseResponse is called when the SSH object has data  


-- EventHandlers  
IPAddress.EventHandler = Connect  
UserName.EventHandler = Connect  
Password.EventHandler = Connect  


-- Start at runtime  
Initialization()  -- calls the Initialization function at the start of runtime
```

--------------------------------

### Get Control Value Example (Empty)

Source: https://help.qsys.com/Content/External_Control_APIs/ECP/ECP_Commands.htm

Example of a 'cg' command response for a control with an empty string value.

```ECP
cv "ssload" "" 0 0
```

--------------------------------

### Full Ping Example (Continuous)

Source: https://help.qsys.com/Content/Control_Scripting/Using_Lua_in_Q-Sys/Ping.htm

A complete example demonstrating continuous pinging every 5 seconds to a live host, including event handlers for success and errors. Ensure Q-Sys Designer is run as administrator.

```Lua
myping = Ping.New("www.qsys.com")
myping:start(false)
myping:setPingInterval(5.0)
myping.EventHandler = function(response)
    print(response.HostName)
    print(response.ElapsedTime)
end
myping.ErrorHandler = function(response)
    print(response.HostName)
    print(response.Error)
end
```

--------------------------------

### Control Get Metadata Response (Value)

Source: https://help.qsys.com/Content/External_Control_APIs/ECP/ECP_Commands.htm

Example response for Control Get Metadata, showing control values and metadata.

```bash
cmv "load1" 6 "false" 0 0
```

--------------------------------

### Example File Path

Source: https://help.qsys.com/Content/Schematic_Library/binloop.htm

When specifying an audio file, ensure the complete path, including the directory and file extension, is provided. This example shows the correct format for a file named 'xyz.mp3' located in the 'Audio/Show' directory.

```text
Audio/Show/zyz.mp3
```

--------------------------------

### Get Control Value Example

Source: https://help.qsys.com/Content/External_Control_APIs/ECP/ECP_Commands.htm

Example of a 'cg' command response showing a control's current value and position.

```ECP
cv "slope" "48dB/Oct" 48 1
```

--------------------------------

### Control Get Response (Non-Vector, String Input)

Source: https://help.qsys.com/Content/External_Control_APIs/ECP/ECP_Commands.htm

Example response for Control Get command when the control ID is provided as a string.

```bash
cv "id4" "5.00dB" 5 0.75
```

--------------------------------

### Full Ping Example (Single Shot to Bad Host)

Source: https://help.qsys.com/Content/Control_Scripting/Using_Lua_in_Q-Sys/Ping.htm

An example demonstrating a single ping attempt to a non-existent host, triggering the error handler. Ensure Q-Sys Designer is run as administrator.

```Lua
myping = Ping.New("www.qsc.c")
myping:start(true)
myping:setPingInterval(5.0)
myping.EventHandler = function(response)
    print(response.HostName)
    print(response.ElapsedTime)
end
myping.ErrorHandler = function(response)
    print(response.HostName)
    print(response.Error)
end
```

--------------------------------

### Control Get Response (Non-Vector, String Input)

Source: https://help.qsys.com/Content/External_Control_APIs/ECP/ECP_Commands.htm

Example response for Control Get command when the control ID is provided as a string.

```bash
cv "id4" "6.20dB" 6.2 0.77
```

--------------------------------

### Example of package.searchpath usage

Source: https://help.qsys.com/Content/Control_Scripting/Lua_5.3_Reference_Manual/Standard_Libraries/2_-_Modules.htm

Demonstrates how `package.searchpath` constructs file paths based on a module name and a search path. This is crucial for understanding how `require` locates Lua modules.

```lua
local path = "./?.lua;./?.lc;/usr/local/?/init.lua"
local name = "foo.a"
print(package.searchpath(name, path))
```

--------------------------------

### Q-Sys Mixer Control Script Example

Source: https://help.qsys.com/Content/Control_Scripting/Using_Lua_in_Q-Sys/Mixer.htm

Demonstrates creating a mixer object, setting cross-point gains, muting inputs, setting output gains, and retrieving cross-point information. Uses a mixer named 'my mixer'.

```lua
mixer = Mixer.New("my mixer")

-- set all crosspoint gains to -100 over 5 seconds
mixer:SetCrossPointGain("*", "*", -100, 5 )

-- mute inputs 3 - 6
mixer:SetInputMute("3-6", true )
-- set all output gains except 5 to 0dB
mixer:SetOutputGain("* !5", 0 )

-- print all mixer crosspoints
xpoints = mixer:GetMixerCrossPoints("3", "*" )
for k,v in pairs( xpoints ) do
print( v.Input, v.Output, v.Gain, v.Mute, v.Delay, v.Solo )
end
```

--------------------------------

### Control Get Response (Non-Vector)

Source: https://help.qsys.com/Content/External_Control_APIs/ECP/ECP_Commands.htm

Example response for Control Get command on a non-vector control, showing string, value, and position.

```bash
cv "gain1" "20.0dB" 20 1
```

--------------------------------

### List Media Resources Response Example

Source: https://help.qsys.com/Content/Management_APIs/Management_APIs_Overview.htm?TocPath=Local+Management%7CManagement+APIs%7C_____0

Example JSON response when requesting a listing of root files and folders within the '/media' directory. Includes file/folder details like path, type, size, and timestamps.

```json
[
    {
        "path": "01 My Special Song.mp3",
        "type": "file",
        "name": "01 My Special Song",
        "ext": "mp3",
        "size": 14048450,
        "created": 1619639517102,
        "updated": 1619639519030,
        "readOnly": false
    },
    {
        "path": "Audio",
        "type": "folder",
        "name": "Audio",
        "ext": null,
        "size": null,
        "created": 1511290661476,
        "updated": 1607549583274,
        "readOnly": true
    },
    {
        "path": "Messages",
        "type": "folder",
        "name": "Messages",
        "ext": null,
        "size": null,
        "created": 1511290661476,
        "updated": 1614978982166,
        "readOnly": true
    },
    {
        "path": "MyFolder",
        "type": "folder",
        "name": "MyFolder",
        "ext": null,
        "size": null,
        "created": 1619637060646,
        "updated": 1619637060646,
        "readOnly": false
    },
    {
        "path": "PageArchives",
        "type": "folder",
        "name": "PageArchives",
        "ext": null,
        "size": null,
        "created": 1511290661480,
        "updated": 1551282017795,
        "readOnly": true
    },
    {
        "path": "Preambles",
        "type": "folder",
        "name": "Preambles",
        "ext": null,
        "size": null,
        "created": 1511290661476,
        "updated": 1511290661684,
        "readOnly": true
    },
    {
        "path": "Ringtones",
        "type": "folder",
        "name": "Ringtones",
        "ext": null,
        "size": null,
        "created": 1511290661476,
        "updated": 1535728270992,
        "readOnly": true
    },
]
```

--------------------------------

### Control Get Metadata Response (Vector)

Source: https://help.qsys.com/Content/External_Control_APIs/ECP/ECP_Commands.htm

Example response for Control Get Metadata for a vector control, including string and value metadata.

```bash
cmvv "slope" 2 4 "12 dB/Oct" "24 dB/Oct" "36 dB/Oct" "48 dB/Oct" 0 0
```

--------------------------------

### Lua HttpClient GET Request Example

Source: https://help.qsys.com/Content/Control_Scripting/Using_Lua_in_Q-Sys/HttpClient.htm

Demonstrates how to make an HTTP GET request using HttpClient.Get. It includes a custom event handler to process the response, printing the URL, return code, errors, headers, and HTML data.

```Lua
function done(tbl, code, data, err, headers)  
  print(string.format( "HTTP response from '%s': Return Code=%i; Error=%s", tbl.Url, code, err or "None" ) )  
  print("Headers:")  
  for hName,Val in pairs(headers) do  
    if type(Val) == "table" then  
      print(string.format( "\t%s : ", hName ))
      for k,v in pairs(Val) do  
        print(string.format( "\t\t%s", v ) )  
      end  
    else  
      print(string.format( "\t%s = %s", hName, Val ) )  
    end
  end  
  print( "\rHTML Data: "..data )
end  
HttpClient.Get { Url = "http://www.google.com", Headers = { ["Content-Type"] = "application/json" } , Timeout = 30, EventHandler = done }
```

--------------------------------

### TCP Server Setup and Event Handling

Source: https://help.qsys.com/Content/Control_Scripting/Using_Lua_in_Q-Sys/TcpSocketServer.htm

This snippet demonstrates how to create a TcpSocketServer, manage connected client sockets, and define event handlers for incoming connections and data. It's essential for establishing a listening port and processing client communications.

```Lua
server = TcpSocketServer.New()

-- table to store connected client sockets
-- this is required so the sockets don't
-- get garbage collected since there aren't
-- any other references to them in the script
sockets = {}

function RemoveSocketFromTable(sock)
  for k,v in pairs(sockets) do
    if v == sock then 
      table.remove(sockets, k) 
      return
    end
  end
end


function SocketHandler(sock, event) -- the arguments for this EventHandler are documented in the EventHandler definition of TcpSocket Properties
  print( "TCP Socket Event: "..event )
  if event == TcpSocket.Events.Data then
    print( sock, sock:Read(sock.BufferLength) )
  elseif event == TcpSocket.Events.Closed or 
         event == TcpSocket.Events.Error or 
         event == TcpSocket.Events.Timeout then
    -- remove reference of socket from table so
    -- it's available for garbage collection
    RemoveSocketFromTable(sock)
  end
end

server.EventHandler = function(SocketInstance) -- the properties of this socket instance are those of the TcpSocket library
  SocketInstance.ReadTimeout = 10
  print( "Got connect", SocketInstance )
  table.insert(sockets, SocketInstance)
  SocketInstance.EventHandler = SocketHandler
end

server:Listen(1720) -- This listen port is opened on all network interfaces
```

--------------------------------

### Retrieve All Cores in Organization

Source: https://help.qsys.com/Content/Reflect/API_Example.htm

This example demonstrates how to use Postman to send a GET request to the Reflect API to retrieve a list of all Q-SYS Cores within an organization. Ensure you have a valid API token and the correct base URL.

```json
[
    {
        "id": 855,
        "serial": "3-12345A9B98CDEF9G1234GHI123JK987L2",
        "name": "MyCore-510i",
        "model": "Core 510i",
        "modelNumber": "Core 510i",
        "firmware": "8.2.0",
        "accessMode": "open",
        "uptime": 1570090458039,
        "status": {
            "code": 0,
            "message": "Running",
            "details": ""
        },
        "redundancy": null
    },
    {
        "id": 858,
        "serial": "1-2ABC01D2EF1234ZH9876GH6I123I1234",
        "name": "MyCore-110f",
        "model": "Core 110f",
        "modelNumber": "Core 110f",
        "firmware": "8.2.0",
        "accessMode": "open",
        "uptime": 1570138527982,
        "status": {
            "code": 7,
            "message": "Offline",
            "details": ""
        },
        "redundancy": null
    }
]
```