CreateVariable (beta feature)#

This command creates a variable that is saved on the robot and optionally persists even after a reboot. A variable is defined by its case-sensitive name, a value (supporting various types) and an optional cyclic ID.

For more information, see Variable management commands (beta).

Syntax#

CreateVariable(name, value, cyclicId, override, volatile)

Arguments#

  • name:

    • A unique name for this variable (e.g., “myVar”);

    • Variable names are case sensitive;

    • May include several case-sensitive prefixes (e.g., “myGroup.mySubgroup.mainWrf”);

    • If the name already exists, the behavior of CreateVariable depends on the override argument.

  • value:

    • The value to assign to the variable;

    • The value can be any basic JSON type: boolean, number, string, or array (but not a JSON object). Remember that in JSON syntax, boolean values must be lowercase (i.e., true or false).

    • Examples:

      • a boolean: CreateVariable(myBoolVar, true)

      • a number: CreateVariable(myIntVar, -0.153)

      • a string: CreateVariable(myStringVar, "Hello world!")

      • an array: CreateVariable(myArrayVar, [190.0, 0.0, 308.9, 0, 90, 0])

  • cyclicId (optional, 0 by default):

    • The unique ID used to refer to this variable in cyclic protocols in the range [10000,19999] or 0;

    • When 0 (or omitted), no cyclic ID is associated with the variable;

    • If the provided cyclic ID is already in use, CreateVariable will fail with error [1552];

    • If a non-zero cyclic ID is used, the value must be a number or an array of numbers, otherwise CreateVariable will fail with error [1552].

  • override (optional, 0 by default):

    • Specifies how CreateVariable behaves when a variable with the same name already exists:

      • 0 to return the error [1552] if the existing variable has a different type or cyclic ID; otherwise do nothing and leave the variable unchanged;

      • 1 to update the existing variable’s value and cyclic ID with the new ones.

  • volatile (optional, 0 by default):

    • Specifies whether the variable is volatile (1) or persistent (0):

      • 0: the variable is persistent and saved on the robot disk. It remains available after a reboot;

      • 1: the variable is volatile and is not saved on the robot disk. It is discarded on reboot.

Responses#

  • [2552] [name, value, cyclicId, override, volatile]

  • [1552] [errorMsg]

    • errorMsg:

      • An error message explaining why variable creation failed;

      • e.g., “Cyclic ID 100001 is already used by variable myOtherVar”.

Usage restrictions#

This command can be executed in any robot state.

Cyclic protocols#

This command is not available in cyclic protocols. See Managing variables with cyclic protocols.