Controls¶

Overview¶

The Controls API is used to access the control signal Input and Output pins of the DSP module. The pins start at index 1.

The modules connections to other modules are updated at the sample rate, but any module may access or modify the signals at a lower rate. The script modules typically do not execute any faster than 4 Hz so that is the maximum rate at which the control pins will be read.

Note that the Controls I/O API is generally only useful Online. This is because the connections between modules only work when online. When offline, you can read inputs and set output values, but the data won’t be passed to and from the connected modules.

Controls.Inputs¶

Controls.Inputs[input].Value¶

This is used to read the value of the signal attached to the corresponding control input pin.

Pin1 = Controls.Inputs[1].Value --Pin1 = 0.78

All Symetrix Control modules output values in a 0-1 range, so the Input pins typically receive floating-point values in this range. But the architecture supports values of any 32-bit floating-point number and another Intelligent module could be created to output values in a different range which could then be connected to an Intelligent Module input. In general, though, we recommend you output the range 0-1 if possible to ensure your intelligent module correctly interfaces with the built in Composer Control Modules.

Controls.Inputs[input].EventHandler¶

The Value could be called in a timer loop, but for inputs that won’t change regularly, this will be inefficient. The EventHandler allows you to handle a change from a Control Input Pin, only when it occurs, instead of polling and checking for a change at a regular interval.

The EventHandler is assigned a function that will be called whenever the corresponding control input changes. This will be updated at a maximum of 4 Hz when running on Symetrix hardware.

This can be done in two ways. It can be assigned a dedicated function:

function PinChanged()

pin[1] = Controls.Inputs[1].Value

end

Controls.Inputs[1].EventHandler = PinChanged --pin[1] = 0.78

Alternately, you can use an anonymous function:

Controls.Inputs[1].EventHandler = function()

Pin[1] = Controls.Inputs[1].Value

end

In both examples, the internal Pin table is updated when Pin1 is changed. You would have event handler functions for any other Input Control Pins; they may be similar or completely different depending on the need.

Controls.Outputs¶

Controls.Outputs[output].Value¶

This is used to write a float value to the corresponding Control Output Pin.

Controls.Outputs[1].Value = 10.5 --Output Pin1 = 10.5

As noted above, the value can be any float as needed by the module(s) you will connect to the output pin. All Symetrix Control modules expect input values in a 0-1 range, so the Intelligent Module output pins typically send floating-point values in this range. But another Intelligent module could be created to receive values in a different range which could then be connected to an Intelligent Module output. In general, though, it is recommended to output the range 0-1 if possible, to ensure your intelligent module correctly interfaces with the built in Composer Control Modules.

Usage Examples¶

The following examples illustrate how these can be used:

Example 1 - Compare two pins¶

The following example shows how the value of two input pins can be compared when they change, and an output pin value set based on the result of the comparison.

function PinChanged()

state1 = Controls.Inputs[1].Value

state2 = Controls.Inputs[2].Value

if (state1 > .5) and (state2 > .5) then

output = 1.0

else

output = 0.0

end

Controls.Outputs[1].Value = output

end

Controls.Inputs[1].EventHandler = PinChanged

Controls.Inputs[2].EventHandler = PinChanged

Example 2 - Polling¶

While the Event handler is most often used, if you expect the pins to change regularly and/or your script already contains a timer for polling Named.Controls in your UI, you may want to also poll the Control Pins.

The example below converts Example 1 to use polling.

function TimerClick ()

state1 = Controls.Inputs[1].Value

state2 = Controls.Inputs[2].Value

if (state1 > .5) and (state2 > .5) then

output = 1.0

else

output = 0.0

end

Controls.Outputs[1].Value = output

end

MyTimer = Timer.New()

MyTimer.EventHandler = TimerClick

MyTimer:Start(.25)

Example 3 - Iterate Through Many Inputs/Outputs¶

If you have many inputs and/or outputs that require similar handling and are using polling, you can iterate through them using the following code:

function TimerClick ()

for pin, state in ipairs(Controls.Inputs) do --iterate through each input pin

print("Input pin " .. pin .. " value: " .. state.Value) --print the pin and value

--Do processing for outputs using "pin" variable as index

Controls.Outputs[pin].Value = state.Value/2

end

MyTimer = Timer.New()

MyTimer.EventHandler = TimerClick

MyTimer:Start(1)