Skip to main content

IO References

Structure

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

IOreferenceWhat 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

  • 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 consistently 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
  • IOreferenceIO Reference strings shall matchonly contain the characters [a-zA-Z0-9_\9_,\.-:/{}] where 
    • ":" and "/" are generally used to tokenize andthe IO Reference
    • Curly braces, {}, isare used to nest other IOreferencesIO inReferences designatedwhere places.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.values when they contain multiple values in the set.
  • GenerallyGenerally, IO References are tokenized by colon. If no colon is found, it’s a literal value (or range of).

The sections 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" are mentioned, 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.

Literal values

  • Literal values:values, Ifsuch 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 bracketsbrackets, with individual values separated by commas, for example, "[],red, it’sgreen, blue]".

    Format: Any IO Reference without a slicecolon withis multiplecategorized values.as Examples:a “literal value.

    =

    Index

    0= String
    • Index 1: Value
    ExampleComment
    3The value "3"
    redThe value "red"
    [red,green,blue]” The 3values values."red" “blue”and ="blue" (two values in the array)
    []No values (empty array)

    		No values (empty array)

    ['']

    [""]

    		A single valueempty string

    Example:

    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]

    ExampleComment
    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 waypurpose 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 use10) complexor stringshas asspecific literalsoptions whichwith otherwisenames would(eg. get"page1", parsed"page2", because"page3" ofwith theirthe contentsnames of"Home", special"Setup", characters.
    "Color")

    Index

    Format: 0 = Var

    • Index 1: Var:[Variable reference
      • reference]:[Mod
    • Index1]:[Mod 2-…2]:...:[Mod Modifiers
      • n]

    Examples

    Example:

    " = " =

    Index

    0=
    ExamplesComment
    Var:Shift"Shift Value of variable "Shift"
    Example:
    Var:Shift:Current:Name"Name Label of variable "Shift"
    DC
    Modifiers

    String afterIf “DC::” is splitfound byright “/“ and the parts will mean this:

    • Index 0: Device Core Key
    • Index 1: IOreference to device index (Optionally encapsulated in {})
    • Index 2: Parameter name
    • Index 3-…: Dimensions

    (Afterafter the last trailing slash, if “:” is found the following will be used as modifiers)modifiers

    Example: “DC:bmd-atem/Var:DeviceIndex/program/Var:MERow/:Current”
    Example: “DC:dreamchip-cam/Var:DeviceIndex/PlayAtSpeed/{DC:dreamchip-cam/Var:DeviceIndex/CurrentBuffer}”

    Index

    Device 0Cores = Const

    ("DC")

    StringIO afterReferences that are prefixed with "Const:”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 splitdivided by “"/“", andwith each resulting segment signifying the partsfollowing:

    will
      mean this:
      - Index
    • Segment 0: ConstantDevice SetCore referencereference, (likeeg variables)
      -"bmd-atem"
      • Index
    • Segment 1: ConstantDevice SetIndex, indexaka Device ID (IOreference,IO (OptionallyReference, optionally encapsulated in {}))
      -
      • Index
    • Segment 2: ConstantParameter Name
      reference
    • Segment 3-5: Parameter Dimensions (After0-3 , depends on parameter). (IO References, optionally encapsulated in {})
    Modifiers

    If “:” is found right after the last trailing slash, if “:” is found the following will be used as modifiers)modifiers

    ...

    Examples
    ExamplesComment
    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:NameName 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:NameThis 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

    If “:” is found right after the last trailing slash, the following will be used as modifiers

    ...

    Examples
    ExamplesComment
    Const:CameraSelector/0/CameraName
    		 
    Const:CameraSelector/{Var:CameraIndex:Current:Offset:1}/CameraName

    Index

    Presets 0 = Preset

    ("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)

    Index

    Flags 0 = Flag

    ("Flag")

    (TODO)

    Index

    Behaviors 0 = Behavior

    ("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.

    (Future:)
    Behavior:Sub:CurrentStep - Current step of multi behavior execution. Zero is not executing at all, first step is 1
    Behavior:Sub:TotalSteps - Total number of steps of a multi behavior
    Behavior:Sub:CurrentDelay - Delay for current step
    Behavior:Sub:TotalTime - Total time in ms for multi behavior
    Behavior:Sub:CurrentName - Name of behavior in current step.

    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.

    Index 0 =

    System

    System:Lock
    System:IPAddress

    Index 0 =

    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

    Index 0 =

    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)

Back to top