Scripted Modules

Overview

Scripted Modules are a category of modules in the Toolkit that implement control logic using Lua scripts (a lightweight, embeddable scripting language). Unlike other control modules whose behavior is fixed, Scripted Modules expose their logic so you can view, modify, and combine it to create customized control solutions within a single module.

Scripted Modules are designed for Cognio's stream-oriented interface, where control logic is self-contained within a module that accepts defined inputs and produces defined outputs. You can use them to build complex control behaviors without connecting many separate modules together.

Because scripted modules run at a control rate rather than an audio sample rate, they are best suited for control logic that does not need to respond at audio rates. The update period is configurable, typically in the range of 1–50 ms. Audio inputs are supported — their levels are metered at the audio rate and made available as control values to the scripted logic.

Scripted Modules are distinct from scripted control panel groups. Control panel groups are designed for controlling specific third-party hardware devices and provide a broader set of Lua APIs suited to that purpose. Scripted Modules focus on combining and customizing signal-flow control logic within a design.

Preset Functions

When you place a Scripted Module from the Toolkit, you select from a set of preset functions. Each preset appears as its own named module in the Toolkit:

• Sequencer — Triggers a series of timed outputs in sequence. Equivalent to the Delay Logic module in Composer, with a variable number of outputs.
• Threshold Detector — Monitors an input and triggers an output when the value crosses a defined threshold. Equivalent to the Threshold Detector module in Composer.
• Ramp Processor — Applies slew limiting to a control value to produce a smoothly ramped output. Equivalent to the Ramp Processor in Composer.
• Counter — Counts trigger events. Equivalent to the Counter module in Composer.
• Scaler — Maps an input value from one range to another. Equivalent to the Scaler module in Composer.
• Custom — Allows you to write your own Lua startup and update scripts from scratch.

Module Height

Some Scripted Modules can be sized by the number of rows you select when placing them. The Sequencer takes advantage of this: each selected consecutive row produces one additional sequencer output signal.

TODO: Add screenshot showing Sequencer height sizing when placing the module.

Module Options

After placing a Scripted Module, open its properties to view and configure its options. The Custom function exposes the most options. The following options are available:

Audio Inputs — Enables or disables audio inputs on the module. When enabled, the module includes one audio input and a corresponding thru output, allowing audio to pass through consecutive modules. You can configure 1–64 audio channels (up to 64 total channels across all signals). When disabled, the audio I/O group is hidden. All audio inputs are metered, and their dB levels are available as control values in the script. You can change this option without forcing the function to Custom.

Control Inputs — Enables or disables control inputs. Most preset functions require control inputs and will re-enable this option automatically if you try to disable it. For the Custom function, you can disable control inputs freely.

Parameters — Scripted Modules have 64 parameters whose values are saved with the site and persist between sessions. Set this option to specify how many of the first N parameters appear as graphical controls in the module view. The script can also configure these controls directly — see Lua API Reference. Parameter values reset to defaults only when the module is first placed or when its function or script changes.

Control Outputs — Enables or disables control outputs. Preset functions typically leave this optional. You can disable control outputs without forcing the function to Custom.

Function — Changes the module to a different preset, or to Custom. Changing the function re-initializes the module and enforces any I/O requirements for the new preset. The signal count is not automatically adjusted — remove any unneeded I/O manually after changing the function. Changing the function also replaces the startup and update scripts.

Update Period — Sets the maximum rate at which the update script runs. The module may run slower depending on system load.

Lua Startup Script — The Lua script that runs when the module loads. For preset functions, this is set automatically. For the Custom function, you write this script yourself. The startup script runs when the module is placed, moved, or edited; when the site syncs or unsyncs from hardware; and when the site opens. Use the InitializeParameters global (see Lua API Reference) to set parameter default values only when needed.

Lua Update Script — The Lua script that runs on each update cycle at the rate set by Update Period. This script implements the main control logic of the module.

TODO: Add screenshot of module properties panel showing a preset function. TODO: Add screenshot of module properties panel showing the Custom function with all options visible.

Module Views

Each Scripted Module has a module view generated automatically from its configured I/O and parameters. The view updates dynamically when the script changes it.

The module view shows sections for control inputs, parameters, control outputs, and status. If audio inputs are enabled, they appear first. A status LED indicates whether the script is running:

• Green — The script is functioning normally.
• Red — An error has been detected.

The text next to the LED shows one of three states: Emulating (running in software), Running (running on hardware), or Failed (script error). If the script fails, the error details appear in the system log.

Sequencer

TODO: Add screenshot of Sequencer module view.

The Sequencer triggers a configurable sequence of outputs with individual delay and hold times per step. The module view shows the control inputs, parameters, control outputs, and status sections. The parameter controls and initial values are configured by the startup script.

Threshold Detector

TODO: Add screenshot of Threshold Detector module view.

The Threshold Detector monitors an input value and produces a binary output when the value crosses a configured threshold.

Ramp Processor

TODO: Add screenshot of Ramp Processor module view.

The Ramp Processor applies slew limiting to a control signal. The module view auto-layout packs shorter controls into available row space to make efficient use of the module height.

Counter

TODO: Add screenshot of Counter module view.

The Counter increments or decrements a value based on trigger inputs.

Scaler

TODO: Add screenshot of Scaler module view.

The Scaler maps an input value from one range to another.

Scripts

Each module has two scripts: a startup script and an update script. For preset functions, these are pre-written and set automatically. For the Custom function, you write them yourself. Both scripts are visible in the module's option properties.

Modifying either script automatically changes the function to Custom and immediately reloads and re-initializes the module — there is no separate apply step. There is no external Lua script file to manage.

TODO: Add screenshot of the script editor in module properties.

Lua API Reference

The following globals and functions are available inside Scripted Module scripts.

Logging

Log("message", <severity>) — Writes a message to the system log. severity is optional: 1 = info (default), 2 = warning, 3 = error.

Timing

GetTime() — Returns the elapsed time since startup as two 32-bit values: milliseconds elapsed and an epoch count. Combined, they represent a 64-bit elapsed time in milliseconds. Use this to measure elapsed time in control logic.

UpdatePeriod — The current update period in seconds. Read/write.

Initialization

InitializeParameters — A boolean that is true when the module is first placed or when its function or script changes. Check this in your startup script to set parameter default values only on first initialization, not on every reload.

Control Inputs

Inputs — The number of configured control inputs. Read-only.

Input[X] — The value of control input X. X can be 1–64 regardless of how many inputs are configured. Read-only.

Control Outputs

Outputs — The number of configured control outputs. Read-only.

Output[X] — The value of control output X. X can be 1–64 regardless of how many outputs are configured. Read/write.

Audio Inputs

Audios — The number of configured audio inputs. Read-only.

Audio[X] — The metered dB level of audio input X. X can be 1–64 regardless of how many audio I/O are configured. Read-only (values are refreshed from the audio meters each update cycle).

Parameters

Parameter[X] — The value of parameter X (1–64). Parameters exist regardless of whether they have module view controls. Read/write.

Parameters — The number of parameters displayed as controls in the module view. The first N parameters (where N equals Parameters) are visible. Read/write.

Parameter Controls

ParameterControl[X].property — Reads or writes configuration properties for the module view control of parameter X. Available properties:

SetParameterControl(<param>, <label>, <minValue>, <maxValue>, <width>, <type>, <function>) — Configures a parameter control in a single call.

Network — UDP

SendUDP(<idString>, <ipString>, <port>, <textToSend>) — Sends a string to a UDP address immediately.

Returns two values: a boolean indicating whether the call succeeded so far, and an error string if it did not. Monitor SendStatusText to confirm completion. Success is indicated by a SendStatusText value of "Send UDP '<idString>' success".

SendStatus — An integer indicating the status of the active send operation: 0 = idle, 1 = connecting, 2 = connected.

SendStatusText — A string describing the outcome of the most recent SendUDP or SendTCP call.

Network — TCP

SendTCP(<idString>, <ipString>, <port>, <textToSend>, <timeoutSeconds>) — Sends a string to a TCP address.

Returns two values: a boolean indicating whether the call succeeded so far, and an error string if it did not. Monitor SendStatus and SendStatusText to track progress. Success is indicated by a SendStatusText value of "Send TCP '<idString>' success".

Examples

Example 1 - Sequencer

The following scripts are the startup and update scripts used by the Sequencer preset function.

Startup Script

--Sequencer startup Lua script--
lastValue = Input[1]
state = 0
stateStart = 0
onLevel = 100
offLevel = 0
--Max sequencer outputs limited by max 64 parameters minus 4 fixed paraemters, divided by 2
maxSeqOuts = (64 - 4) / 2
if (Outputs > maxSeqOuts) then
    seqOuts = maxSeqOuts
else
    seqOuts = Outputs
end
--Inititalze parameter controls
Parameters = 4 + (seqOuts * 2)
--Threshold Parameter--
SetParameterControl(1, "Threshold", 0, 100, 4, "Fader")
--Trigger Parameter--
SetParameterControl(2, "Trigger", 0, 1, 3, "Button")
--Reset Parameter--
SetParameterControl(3, "Reset", 0, 1, 3, "Button")
--Loop Parameter--
SetParameterControl(4, "Loop", 0, 1, 3, "Button")
--Sequencer Parameters
for seq = 1, seqOuts do
    --Delay Parameter--
    SetParameterControl(3 + (seq *2), "Delay " .. seq, 0, 60 * 2, 3, "Fader")
    --Hold Parameter--
    SetParameterControl(4 + (seq *2), "Hold " .. seq, 0, 60 * 2, 3, "Fader")
end
--Only initialze parameter values if new module or function or script changes
if InitializeParameters then
    --Threshold Parameter--
    Parameter[1] = 50
    --Trigger Parameter--
    Parameter[2] = 0
    --Reset Parameter--
    Parameter[3] = 0
    --Loop Parameter--
    Parameter[4] = 0
    for seq = 1, maxSeqOuts do
        --Delay Parameter--
        Parameter[3 + (seq *2)] = 1
        --Hold Parameter--
        Parameter[4 + (seq *2)] = 2
    end
end

Update Script

--Sequencer update Lua script--
--Reset Logic--
if (Parameter[3] ~= 0) then
    state = 0
    Parameter[3] = 0
    Log("Sequence reset", 1)
end
--Threshold Logic--
threshold = Parameter[1]
if (state == 0) then
    if (Parameter[2] ~= 0) or ((Input[1] >= threshold) and (lastValue < threshold)) then
        Parameter[2] = 0
        state = 1
        stateStart = GetTime()
    Log("Sequence started", 1)
    end
else
    currentTime = GetTime()
    if ((currentTime - stateStart) / 1000) > Parameter[state + 4] then
        state = state + 1
        stateStart = GetTime()
    end
    if (state > (seqOuts * 2)) then
        --Loop or end
        if (Parameter[4] ~= 0) then
            state = 1
            Log("Sequence looped", 1)
        else
            state = 0
            Log("Sequence complete", 1)
        end
    end
end
--Output Logic--
for seq = 1, seqOuts do
    if ((state /2) == seq) and ((state % 2) == 0) then
        Output[seq] = onLevel
    else
        Output[seq] = offLevel
    end
end
lastValue = Input[1]