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 aka Parameter)?

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)

Registers related to accessing constants in a behavior

Sub Behaviors ("Sub" sub-type)

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

Registers related to the execution of a sequence of sub behaviors, what may be referred to as a Multi Behavior or Multi Action.

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 March 25)
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
Index:[integer comma list incl. "Last" keyword / HWC behavior constant ref]:Raw	Returns the raw index value of the option value with index [int].	Yes	Yes	No
DimensionName (some changes January 24)
DimensionName:[int]:[optional int]	Returns the name of the specified diemsion (0 index) if 2 ints are specified returns the name of the specified Element	Yes	No	No
Index (some changes March 24)
ID:[integer / HWC behavior constant ref]	Return an option by its value ID (different than index on some cores) also supports :Name and :Exists	Yes	Yes	No