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. 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 consistentlyexclusively 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.
• Generally,

IO References are generally tokenized using a combination of colons and forward slashes. Specifically, an IO Reference's basic type is always indicated by colon.a prefix that precedes the first colon in the string. If there's no coloncolon, isit's found, it’sconsidered a literal value (or rangea of)set thereof).

The sectionsdifferent below primarily refer to the first segment (index 0) of a string that has been divided, or tokenized, by a colon ":". When other indexes such as "Index 1", "Index 2"types are mentioned,outlined these refer to the respective positions within the IO Reference. For example, in the IO Reference "Behavior:Const:Input", the string "Behavior" is at Index 0, "Const" is at Index 1, and "Input" is at Index 2.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.

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]

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

Modifiers

If “:” is found right afterSee the lastGeneral trailingModifiers slash, the following will be used as 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

If “:” is found right afterSee the lastGeneral trailingModifiers slash, the following will be used as modifiers

...table

Examples

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

If “:” is found right afterSee the lastGeneral trailingModifiers slash, the following will be used as modifiers

...table

Examples

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

[] - Not adding any modifiers returns the values…
Name - Returns Name of the reference (like a parameter or variable name)
Mutable - Returns “true” if available for change
Assumed - Returns "true" if a parameter is assumed in the core
Exists - 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, else returns 1
CoarseSteps - For a DC this returns the recommended fine coarse, else returns 10
Current - Returns values (same as no modifier)
Current:Name - Returns names of values
Current:Normalized - Returns value normalized to value range 0-1000
Current:NormalizedInverted - Returns value normalized to inverted value range 1000-0
Current:Percent - Returns value normalized to value range 0-100
Current:Remap:[low int]:[high int]:[optional integer divisor, default to 1] - Returns value normalized to value range [low int]-[high int] divided by the divisor. Example: "Behavior:IOReference:Current:Remap:-70:70:10" remaps to a range from -7.0 to 7.0
Current:Index - Returns index of current value from option list, starting with zero
Current:Count - Returns number of values in the IOreference array
Current:Join:Token - Returns an IOreference with a single value being a concatenation of all values it had, separated by the Token string, Example: "....:Current:Join:, :" - will join with ", " as the separator string.
Current:Offset:[int] - Returns the value with [int] added to it. Example: "Behavior:IOReference:Current:Offset:1" - Increases values with one.
Current:BufferTimeToNow - Returns milliseconds from buffered value time out to current time.
Label - for constants, returns the label a given constant may have
All - Returns all option values for a parameter
Index:[int/HWC behaviour constant string ref] - Returns option value with index [int] or if its a string, the constant of the HWC Behavior (works only for HWC behaviours then) (starting with zero)
Index:[int/HWC behaviour constant string ref]:Name - Returns name of option value with index [int] (starting with zero)
Index:[int/HWC behaviour constant string ref]:Exists - Returns true if the index exists
Index:Last - Returns last option value
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)