Skip to main content

IO References

IO References

In this article we explain the internal structure, of the IOReference string.
This will help you, if you to find the correct modifiers to use in Configuration tab, and when using the JSON editor

What is an IO Reference (aka IOref)?

An IO Reference is a unified text reference to a data point that can be read and/or written. This data point might represent a device parameter, a variable within the Reactor, or a read-only constant. A device parameter allows users to both set and fetch its value. In contrast, a variable within Reactor can also be adjusted and retrieved, whereas a constant can only be read.

Reactor employs IO References extensively to facilitate data-driven configurations. These configurations are used for a range of functions, including enabling or disabling features, displaying information, defining button colors in response to data, and identifying the next value for a parameter.

In many ways, IO References are similar to URLs as encountered on websites, providing a consistent method for accessing and manipulating data.

Examples
Example Comment
DC:bmd-atem/1/ProgramInputVideoSource/2/ This IO Reference points to the "Program Input Video Source" parameter in an ATEM switcher from Blackmagic Design, accessed through the device core labeled "bmd-atem". The segment "/1" identifies the specific ATEM switcher with ID=1 in the system, and "/2" refers to the dimension of the parameter, in this case, the Mix Effect row for the program video input. A comprehensive list of parameters for ATEM switchers can be found at: https://cloud.skaarhoj.com/coremanual/core-bmd-atem/pre.
Var:MyMenu This IO Reference pertains to the nearest variable named "MyMenu" in Reactor's tree. It's a read/write reference, meaning it can be both modified and retrieved.
Behavior:Const:Input This IO Reference refers to the read-only value of the constant "Input" from the behavior of a specific context (as most IO References are utilized within a Behavior context). This reference is read-only, indicating it can only be fetched but not modified.
Datatypes

IO References can encapsulate different types of data such as strings, integers, floating point numbers, and booleans. For booleans, the values are represented as the strings "true" or "false".

In essence, every IO Reference is treated as a one-dimensional array, allowing for the possibility of holding multiple values or even none at all. For instance, a constant might contain anywhere from zero to many values, though typically it holds a single value. When interacting with Device Cores, single values are exclusively employed. Variables usually operate with single values too but may occasionally use multiple values. This multi-value support is inherently built into the IO Reference system.

IO Reference characters and structure
  • IO Reference strings shall only contain the characters [a-zA-Z0-9_,\.-:/{}] where 
    • ":" and "/" are generally used to tokenize the IO Reference
    • Curly braces, {}, are used to nest other IO References where allowed. Encapsulation is not always necessary, but if the nested IO Reference contains the same characters as used for tokenization, it will be necessary. The safe and consistent choice would be to always encapsulate. 
    • [] is a part of literal values when they contain multiple values in the set.

IO References are generally tokenized using a combination of colons and forward slashes. Specifically, an IO Reference's basic type is always indicated by a prefix that precedes the first colon in the string. If there's no colon, it's considered a literal value (or a set thereof). The different types are outlined below.

Literal values

Literal values, such as "3", "true", or "page1", are utilized to assign a fixed value instead of referencing another data source.

Frequently, it may be desirable to define literal values as sets with multiple elements. In such cases, these values are enclosed in brackets, with individual values separated by commas, for example, "[red, green, blue]".

Format: Any IO Reference without a colon is categorized as a literal value.

Example Comment
3 The value "3"
red The value "red"
[red,blue] The values "red" and "blue" (two values in the array)
[] No values (empty array)
(empty string) No values (empty array)

['']

[""]

A single empty string


Strings ("String")

The "String:" prefix allows complex strings to be treated as literal values, particularly when they contain special characters. Without this prefix, these strings might otherwise be parsed due to the presence of such characters.

Format: String:[Value]

Example Comment
String:{"Outputs": [{"ID": \d1,"Action": \d2}]} Strings such as JSON code must be embedded in an IO Reference using the "String:" prefix. Without this prefix, the string would be parsed, and the presence of colons could lead to unexpected outcomes.

Variables ("Var")

Variables in Reactor are used to hold data that can be manipulated. You can think of them as containers that store information. Their value can be changed, and they can be reused many times at different places in a configuration. The purpose of a variable is never predefined by Reactor but depends on how it's being used in the configuration. 

Usually variable either spans an integer range (eg. from -10 to 10) or has specific options with names (eg. "page1", "page2", "page3" with the names "Home", "Setup", "Color")

Format: Var:[Variable reference]:[Mod 1]:[Mod 2]:...:[Mod n]

Examples
Examples Comment
Var:Shift Value of variable "Shift"
Var:Shift:Current:Name Label of variable "Shift"
Modifiers

See the General Modifiers table

Device Cores ("DC")

IO References that are prefixed with "DC:" correspond to parameters in devices that are managed by device cores. These are the devices that have been added to Reactors current project for control purposes and/or to serve as data sources.

Format: DC:[Seg 0]/[Seg 1]/[Seg 2]/[Seg 3]/[Seg 4]/[Seg 5]/:[Mod 1]:[Mod 2]:...:[Mod n]

The string following "DC:" is divided by "/", with each resulting segment signifying the following:

  • Segment 0: Device Core reference, eg "bmd-atem"
  • Segment 1: Device Index, aka Device ID (IO Reference, optionally encapsulated in {})
  • Segment 2: Parameter reference
  • Segment 3-5: Parameter Dimensions (0-3 , depends on parameter). (IO References, optionally encapsulated in {})
Modifiers

See the General Modifiers table

Examples
Examples Comment
DC:bmd-atem/4/AuxSource/2/ Reference to the current source on AUX Channel 2 on the ATEM switcher with Device ID 4.
DC:bmd-atem/4/AuxSource/2/:Current:Name Name of the current source on AUX Channel 2 on the ATEM switcher with Device ID 4.

DC:bmd-atem/Var:DeviceIndex/AuxSource/Var:AuxChannel/

DC:bmd-atem/{Var:DeviceIndex}/AuxSource/{Var:AuxChannel}/

Reference to AUX sources on the ATEM switcher with Device ID found in "Var:DeviceIndex" (idiomatic) and in the AUX Channel denoted by "Var:AuxChannel".
Both examples provided are identical. In this scenario, encapsulating the nested IO Reference is not required, as there are no forward slashes included that might interfere with the parsing process.
DC:dreamchip-cam/Var:DeviceIndex/PlayAtSpeed/{DC:dreamchip-cam/Var:DeviceIndex/CurrentBuffer/}/:Current:Name This complex IO Reference extracts the formatted "Name" (suitable for display) of the play speed in a Dream Chip camera. The camera's ID is derived from "Var:DeviceIndex", and the buffer is retrieved from another IO Reference pointing to the CurrentBuffer parameter from the same camera. This is an example of an embedded IO Reference, encapsulated in curly braces, required because the reference itself contains the character ("/") used for tokenization.


Constant Sets ("Const")

Reactor's constants are unchangeable values embedded in the configuration code, used for various purposes within the configuration. Unlike variables, constants can only be modified by altering the configuration.

Constant Sets in Reactor are essentially tables of related constants. Each row forms a set of constant values, and columns represent different constants within these sets. They can be utilized for a variety of functions, from setting switcher inputs to configuring a PTZ controller's camera selector. Even simpler uses might include single-row constant sets for configuring specific aspects of a configuration, such as the number of cameras on a page.

Format: Const:[Seg 0]/[Seg 1]/[Seg 2]/

The string following "Const:" is divided by "/", with each resulting segment signifying the following:

  • Segment 0: Constant Set reference. The name of the closest constant set in the layer tree.
  • Segment 1: Constant Set row index (IO Reference, optionally encapsulated in {})
  • Segment 2: Constant Name
Modifiers

See the General Modifiers table

Examples
Examples Comment
Const:CameraSelector/0/CameraName
Returns the value of the constant called "CameraName" in the first row (index 0) of the constant set "CameraSelector".
Const:CameraSelector/{Var:CameraIndex:Current:Offset:-1}/CameraName
This retrieves the value of the constant "CameraName" from the row in the "CameraSelector" constant set, as indicated by the "CameraIndex" variable. If the "CameraIndex" variable is set to 1, it refers to the first row (index 0). This occurs because the variable's value is reduced by one when inserted as the value for Segment 1. (:Current:Offset:-1)

Behaviors ("Behavior")

Behaviors dictate how a controller's hardware component typically interacts, including the actions it can execute on devices and other IO References, as well as how system feedback is displayed on its screens and LEDs.

IO References of the "Behavior" type facilitates reading and writing of the behavior aspects, which are often the context of an IO Reference.

Format: Behavior:[Seg 0]/[Seg 0a]:[Seg 1]:...[Seg n]

The string following "Behavior:" is divided by ":", with each resulting segment signifying the following:

  • Segment 0: The sub-type. This string value is further divided by "/" to provide a further refinement of the sub-type.
  • Segment 1-n: Depends on the sub-type. See the overview below

Basic Info

This is basic info about the behavior:

IO Reference I/O Comment
Behavior:Path Read Returns the "path" of the behavior in the layer tree. Eg. "0/3/0/A3"

Behavior:Name

Read Returns the name of the behavior (value of the Name field)

Behavior:Id

Read Returns the behaviors main mapping to a panel, for example "_p4.32" (panel Id 4, Hardware Component (HWC) 32)

Behavior:Panels

Read An array of all Panel Ids this behavior is mapped to

Access to the Behaviors IO Reference ("IOReference" sub-type)

Behaviors usually modify a single parameter - a single IO Reference - in a device or within Reactor. To simplify this, behaviors have a master IO Reference field set by the user, which can be referred to throughout the behavior's configuration as "Behavior:IOReference". For example, if the behavior's IO Reference is set as "DC:bmd-atem/4/AuxSource/2/", "Behavior:IOReference" can be used as a substitute anywhere within the behavior where IO References are applicable. If the label of a value is needed instead, "Behavior:IOReference:Current:Name" serves the same function as "DC:bmd-atem/4/AuxSource/2/:Current:Name".

With "Behavior:IOReference", the "main" IO Reference is derived from the master IO Reference, while modifiers in segments 1-n are taken from "Behavior:IOReference".

Examples

For these example, assume that the IO Reference of the behavior is "Var:Menu" with the name "Page" and with the current value being "page1" with the label "Background"

Examples Comment

Behavior:IOReference

Behavior:IOReference:Current

Returns the current value of Var:Menu ("page1")

Behavior:IOReference:Name

Returns what corresponds to "Var:Menu:Name" which is the name of the variable ("Page")

Behavior:IOReference:Current:Name

Returns what corresponds to "Var:Menu:Current:Name" which is the label of the current value ("Background")

Script State ("Script" sub-type)

These are read and write registers of a behaviors script.

IO Reference I/O Comment
Behavior:Script Read Returns "true" if there is an event script defined.

Behavior:Script:IsRunning

Read Returns "true" if there is a script and if script is running.

Behavior:Script:Stop

Write Trigger action to stop a script if it's running.

Last Event ("LastEvent" sub-type)

These are read registers of the last event received by the behavior.

IO Reference I/O Comment
Behavior:LastEvent:Type Read Type of last event.
Options: Binary, Pulsed, Analog, Speed

Behavior:LastEvent:TimeToNow:[Limit]

Read

This returns the time in milliseconds that has passed since the last event. Although setting a limit is optional, it's recommended to set it at or above the comparison value for performance efficiency. If a limit is set, it designates the maximum returned value.


Examples:
Behavior:LastEvent:TimeToNow < 500

Behavior:LastEvent:TimeToNow:500 < 500 (better)

Behavior:LastEvent/Binary:Pressed

Read Returns whether the last binary trigger was pressed (ActDown) or not (ActUp).
Options: true, false

Behavior:LastEvent/Binary:Edge

Read

Returns which edge the last binary trigger sent.

Options: NoEdge, Top, Left, Bottom, Right, Encoder

Behavior:LastEvent/Pulsed:Direction

Read

Returns the direction of the last pulsed trigger received

Options: Up, Down

Behavior:LastEvent/Pulsed:Value

Read

Returns the value of the last pulsed trigger

Behavior:LastEvent/Analog:Value

Read

Returns the value of the last analog trigger (0 to 1000)

Behavior:LastEvent/Speed:Value

Read

Returns the value of the last intensity trigger (-500 to 500)

Event Handlers ("Event" sub-type)

These registers are associated with the various event handlers that can be established for a behavior. The term "eventHandlerKey" in the subsequent table refers to the specific event handler's name being referred to.

IO Reference I/O Comment
Behavior:Events/[eventHandlerKey]:TimeToNow:[Limit] Read

This returns the time in milliseconds that has passed since the last accepted trigger for this event handler. Although setting a limit is optional, it's recommended to set it at or above the comparison value for performance efficiency. If a limit is set, it designates the maximum returned value.

 

Example: 
Behavior:Events/myTrigger:TimeToNow < 500

Behavior:Events/myTrigger:TimeToNow:500 < 500 (better)

Behavior:Events/[eventHandlerKey]:SequenceStep Read The current sequence step being executed

Behavior Constants ("Const" sub-type)

IO Reference I/O Comment
Behavior:Const:[constant] Read Value of constant (one or more values)
Behavior:Const:[constant]:Name Read Provides the name of the constant.
Behavior:Const:[constant]:Label Read Offers the label of the constant value(s). If no labels are defined, it will return the values.
Behavior:Const:[constant]:ASCIIOnly Read (Refer to detailed description below.)
Behavior:Const:[constant]:Index:[index number] Read Provides the value at a specific index. Index numbers are integers, starting from zero. Negative numbers like -1 point to the last element, -2 to the second last, and so on. The special index value "Last" equates to "-1" (the last element).
Behavior:Const:[constant]:Index:[index number]:Exists Read Returns true or false, depending on whether the constant value exists for this index
Behavior:Const:[constant]:Index:[index number]:Label Read Returns the value label if it differs from an empty string; otherwise, it returns the value itself.
Behavior:Const:[constant]:Offset:[int] Read Returns the value with [int] added to it. For example, "Behavior:Const:[constant]:Offset:1" increases values by one.

Sub Behaviors ("Sub" sub-type)

(Future - may not be in Reactor yet or ever...)

IO Reference I/O Comment
Behavior:Sub:TotalSteps Read Total number of steps in a multi-behavior sequence.
Behavior:Sub:TotalTime Read Total time (in milliseconds) required for the multi-behavior sequence.
Behavior:Sub:CurrentStep Read Current execution step in the multi-behavior sequence. Zero indicates no execution, while the first step is denoted as 1.
Behavior:Sub:CurrentDelay Read Delay duration for the current step.
Behavior:Sub:CurrentName Read Name of the behavior being executed in the current step.

Presets ("Preset")

String after "Preset:” is split by “/“ and the parts will mean this:
- Index 0: Preset reference (like variables)
- Index 1: Command
- Index 2: Preset number (IOreference, (Optionally encapsulated in {}))
- Index 3: Device Index (IOreference, (Optionally encapsulated in {}))
- Index 4-…: Dimensions
(After the last trailing slash, if “:” is found the following will be used as modifiers)

Flags ("Flag")

(TODO)

System

System:Lock
System:IPAddress

Reactor

Reactor:ProjectTitle - Current Project title
Reactor:ConfigTitle - Current name of root layer
Reactor:CurrentProject - Allows to trigger a change of projects using SetValue
Reactor:RestartEngine - Perform a restart of reactors engine, like switching projects
Reactor:UptimeFormatted - Uptime since Reactor was started

Reactor:Panels:Connected - Number of connected panels 
Reactor:Panels:Warnings - Number of panels with warnings
Reactor:Panels:Unconnected - Number of unconnected panels (errors)
Reactor:Panels:LastEvent - Last event as a string, eg. "Down (T)" if a four way buttons top edge was pressed down.
Reactor:Panels:LastEventSource - The HWC source of last event, including panel ID, on form "P[panel id]#[HWC id]", for example "P1#43"

Reactor:Devices:Connected - Number of connected devices
Reactor:Devices:Warnings - Number of devices with warnings
Reactor:Devices:Unconnected - Number of unconnected devices (errors)
Reactor:Devices/[idx]:Name - Name of devices. idx is just an index.

Reactor:Warnings - Total number of warnings in Reactor
Reactor:Errors - Total number of errors in Reactor

Panels

String after Panels: is split by “/“ and the parts will mean this:

  • Index 0: Target of ID: "Canvas", "Panel", "CanvasOfPanel"
    • Canvas/[id]/ - forcing a given canvas id. Normally not used
    • Panel/[id]/ - forcing a particular panel only. May be used when canvas is not used to represent a coherent panel
    • CanvasOfPanel/[id]/ - normally the one used because Reactor knows the panel ID, but usually desires to target the canvas of the panel
      (Usual source of id is: Behavior:Panels)
  • Index 1: ID of target (IOreference, (Optionally encapsulated in {}))
  • Index 2: Parameter
    • SleepTime, minutes
    • DimTime, minutes
    • DisplayBrightness, 0-8
    • LEDBrightness, 0-8
    • GlobalBrightness, 0-8
    • Sleep (binary: "on", "off") - Is reset by the panel when it wakes up again. It's probed once a second, so it can feel a little like a "hold down" function
    • ResetSleepTimer (trigger)
    • Name (read only)
    • Model (read only)

General Modifiers

General modifiers are used by certain IO References due to their shared data source framework. However, not all IO Reference types support or need these modifiers. The table below indicates which primary types - Device Cores (DC), Variables (Var), and Constants (Const) - support these general modifiers.

Modifier Comment DC Var Const
(no modifiers) Without any modifiers, returns the values. Yes
Yes Yes
Name Returns the name of the reference, such as a parameter or variable name. Yes
Yes Yes
Default Returns the default values of the IO reference. Yes
Yes N/A
Default:Name Returns the names/labels of the default values of the IO reference. Yes
Yes N/A
All Returns all option values for a parameter.
For an integer range with less than 100 values, it will calculate and return that as an option list. (June 23)
Yes
Yes No
Exists Returns "true" if the reference exists. Yes
Yes Yes
Mutable Returns "true" if the reference can be changed. Yes
Yes Yes
Assumed Returns "true" if a parameter is assumed in the core. Yes N/A N/A
FineSteps Returns the recommended fine steps for a Device Core; otherwise, returns 1. Yes N/A N/A
CoarseSteps Returns the recommended coarse steps for a Device Core; otherwise, returns 10. Yes N/A N/A
ASCIIOnly Returns true if only ASCII characters are found in the return value. Yes
Yes Yes
Current



Current Returns the current values. Same as not using "Current" modifier. Yes
Yes Yes
Current:Name Returns the names of the current values. Yes
Yes Yes
Current:Normalized Returns the normalized value in the range of 0-1000. Yes
Yes No
Current:NormalizedInverted Returns the normalized value in the inverted range of 1000-0. Yes
Yes No
Current:Percent Returns the normalized value in the range of 0-100. Yes
Yes No
Current:Remap:[low int]:[high int]:[optional integer divisor, default to 1] Returns the value normalized to the range [low int]-[high int], divided by the divisor. Yes
Yes No
Current:Index Returns the index of the current value from the option list, starting with zero.
Works only for parameters and variables with Option Lists, not ranges.
Yes
Yes No
Current:Count Returns the number of values in the IO reference array. Yes
Yes Yes
Current:Join:Token Returns an IO reference with a single value, a concatenation of all values it had, separated by the Token string. Yes
Yes Yes
Current:Offset:[int] Returns the value with [int] added to it. Yes
Yes Yes
Current:BufferTimeToNow Returns the time in milliseconds from the buffered value time out to the current time.
Yes N/A N/A
Confirm:[int] Changes the value only locally, waiting to be confirmed for [int] milliseconds. Yes N/A N/A
Wait:[int] Similar to Confirm, but the change is automatically accepted after the time expires. Yes N/A N/A
Index (some changes June 23)



Index:[integer comma list incl. "Last" keyword / HWC behavior constant ref] Returns option value with index [int] or if it's a string, the constant of the HWC Behavior. Yes
Yes No
Index:[integer comma list incl. "Last" keyword / HWC behavior constant ref]:Name Returns the name of the option value with index [int]. Yes
Yes No
Index:[integer comma list incl. "Last" keyword/HWC behavior constant ref]:Exists Returns true if the index exists. Yes
Yes No