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)

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)

Behaviors ("Behavior")

Behavior:LastEvent:Type == [Binary/Pulsed/Analog/Speed]

Behavior:LastEvent:TimeToNow:[Limit] < 500 (milliseconds); Limit is optional, but for performance reasons, please set it to the same value or higher as the one you compare with.
Behavior:LastEvent/Binary:Pressed == [true/false]
Behavior:LastEvent/Binary:Edge != NoEdge [NoEdge, Top, Left, Bottom, Right, Encoder]
Behavior:LastEvent/Pulsed:Direction == [Up/Down]
Behavior:LastEvent/Pulsed:Value == [Encoder return value]
Behavior:LastEvent/Analog:Value == [Absolute component return value]
Behavior:LastEvent/Speed:Value == [Intensity component return value]
(Behavior:LastEvent/x for Pulsed, Speed and Analog was added in Reactor v1.0.5-pre9)

Behavior:Events/[the eventHandlerKey]:TimeToNow:[Limit] < 500 (milliseconds) Last accepted event. Limit is optional, but for performance reasons, please set it to the same value or higher as the one you compare with.
Behavior:Events/[the eventHandlerKey]:SequenceStep == [Sequence step currently executing]

Behavior:IOreference[:modifiers added to IO reference]
for example:
Behavior:IOreference:Name
Behavior:IOreference:Current
Behavior:IOreference:Current:Name

Behavior:Path
Behavior:Name
Behavior:Id
Behavior:Panels - provides all panel IDs this behavior is mapped to.

Behavior:Const:[constant] - Value of constant (one or more values)
Behavior:Const:[constant]:Name - Name of constant
Behavior:Const:[constant]:Label - Label of constant value(s) (one or more)
Behavior:Const:[constant]:ASCIIOnly - (see below)
Behavior:Const:[constant]:Index:[index number] - Value of specific index, where Index Number is an integer starting with zero. Negative numbers starting with -1 will point to last element, -2 to second last element etc. Special index value "Last" will be equal to "-1" (last element)
Behavior:Const:[constant]:Index:[index number]:Exists - true or false depending on whether constant exists
Behavior:Const:[constant]:Index:[index number]:Label - returns value label if different from empty string, otherwise it will return the value itself.
Behavior:Const:[constant]:Offset:[int] - Returns the value with [int] added to it. Example: "Behavior:Const:Offset:1" - Increases values with one.

Behavior:Script - returns "true" if there is an event script defined
Behavior:Script:IsRunning - returns "true" if there is a script and if script is running.
Behavior:Script:Stop - Trigger action to stop a script if it's running.

System

System:Lock
System:IPAddress

Reactor

Reactor:ProjectTitle - Current Project title
Reactor:ConfigTitle - Current name of root layer
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

Modifier	Comment	DC	Var	Const
(no modifiers)

[] - Not addingWithout any modifiersmodifiers, returns the values…values. Yes
Yes Yes Name - Returns Namethe name of the referencereference, (likesuch as a parameter or variable name)name. Yes
Mutable -Yes Yes Default Returns “true”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.
Notice, if availablethe forparameter changedoesn't have options but a range instead, the returned value will be an empty array. 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
Existscore. -Yes N/A N/A FineSteps Returns “true” if exists
Default - Returns default values of IO reference
Default:Name - Returns names of default values of IO reference
FineSteps - For a DC this returns the recommended fine steps,steps elsefor a Device Core; otherwise, returns 1
1. Yes N/A N/A CoarseSteps - For a DC this returnsReturns the recommended finecoarse coarse,steps elsefor a Device Core; otherwise, returns 10
Current10. -Yes N/A N/A ASCIIOnly Returns valuestrue (sameif only ASCII characters are found in the return value. Yes
Yes Yes Current



Current Returns the current values. Same as nonot modifier)using "Current" modifier. Yes
Yes Yes Current:Name -Returns Returnsthe names of valuesthe current values. Yes
Yes Yes Current:Normalized -Returns Returnsthe normalized value in the range of 0-1000. Yes
Yes No Current:NormalizedInverted Returns the normalized to value in the inverted range 0-1000of 1000-0. Yes
Yes No Current:NormalizedInvertedPercent -Returns Returnsthe normalized value normalizedin to inverted valuethe range 1000-0
Current:Percent - Returns value normalized to value rangeof 0-100100. Yes
Yes No Current:Remap:[low int]:[high int]:[optional integer divisor, default to 1] -Returns Returnsthe value normalized to valuethe range [low int]-[high int], divided by the divisor. Example:Yes
"Behavior:IOReference:Current:Remap:-70:70:10"Yes remapsNo to a range from -7.0 to 7.0
Current:Index -Returns Returnsthe index of the current value from the option list, starting with zerozero.
Works only for parameters and variables with Option Lists, not ranges. Yes
Yes No Current:Count -Returns Returnsthe number of values in the IOreferenceIO arrayreference array. Yes
Yes Yes Current:Join:Token - Returns an IOreferenceIO reference with a single value beingvalue, a concatenation of all values it had, separated by the Token string,string. Example:Yes
"....:Current:Join:,Yes :"Yes - will join with ", " as the separator string.
Current:Offset:[int] - Returns the value with [int] added to it. Example:Yes
"Behavior:IOReference:Current:Offset:1"Yes -Yes Increases values with one.
Current:BufferTimeToNow -Returns Returnsthe time in milliseconds from the buffered value time out to the current time.

LabelYes -N/A N/A Confirm:[int] Changes the value only locally, waiting to be confirmed for constants,[int] returnsmilliseconds. Yes N/A N/A Wait:[int] Similar to Confirm, but the labelchange ais givenautomatically constantaccepted mayafter havethe time expires. Yes N/A N/A Index
All -
Returns
all
option values for a parameter
Index:[int/HWC behaviour constant string ref] - Returns option value with index [int] or if itsit's a string, the constant of the HWC BehaviorBehavior. (works
only
for
HWC behaviours then) (starting with zero)
Index:[int/HWC behaviour constant string ref]:Name -Returns Returnsthe name of the option value with index [int]. (starting
with
zero)
Index:[int/HWC behaviour constant string ref]:Exists - Returns true if the index existsexists.


Index:Last -Returns Returnsthe last option valuevalue.
Confirm:[int] -
If
added to a setting,

 stepping or mapping values, it will change the value only locally and waiting to be confirmed for [int] milliseconds after which it will fall back. Confirmation happens if a trigger (valueless value setting) happens. (works only for Device Cores)
Wait:[int] - like Confirm, but the change is automatically accepted on the expiry of the time. (works only for Device Cores)
ASCIIOnly - Returns true if only ascii characters are found in string (<127). Works also for Behavior:Const:[ConstantName]:ASCIIOnly
FineSteps - For Device Cores: Step size for fine steps (an integer value)
CoarseSteps - For Device Cores: Step size for coarse steps (an integer value)