Variable management commands (beta)#

Warning

Please note that this feature is in beta and may undergo changes, including potential API changes.

We also provide an API to manage variables stored on the robot. These variables can persist after the robot is rebooted. They can be used in programs that control the robot (via the TCP API or cyclic protocols).

Variables are well suited for storing information that may vary between robots or setups running the same program, such as reference positions, desired velocities, or delays. This allows a single program to automatically adapt to each robot on which it is executed.

Variables may also be used to store temporary information on the robot that is discarded after a reboot. This is useful, for example, to pass temporary information from one program to another.

Variables can be used as values when calling robot commands (for example MoveJoints(*vars.myJointPos)). They can also be used as command arguments by a PLC using cyclic protocols. Finally, they can be read and/or written by Python programs.

The complete list of variables management commands is:

Summary#

The following provides a summary of important details regarding variables in the robot:

  • Persistence Variables are always saved on the robot, but hey can be configured to either persist after a robot reboot or not.

  • Access and modification Variables can be accessed, created, modified, or deleted in any robot state (robot activated, robot deactivated, robot in recovery mode, etc.).

  • Data types Variables can store a variety of JSON-supported values, including booleans, numbers, strings, and arrays.

The variable type is deduced by the value provided to CreateVariable. Command SetVariable will be refused if the provided value is of a different type. No automatic type conversion is performed by the robot.

Managing variables in the MecaPortal#

The robot’s MecaPortal web interface has a configuration panel to view, edit, create and delete variables.

For more information, please refer to MecaPortal configuration menus.

Managing variables in robot programs (text API)#

In robot programs, you can use CreateVariable, DeleteVariable or SetVariable commands to manage your variables.

We suggest to create a program responsible for variables creation (using CreateVariable) that is called once, then refer to (or modify) these variables in your robot programs.

You can refer to these variables by using vars.myGroup.myVar when calling robot API functions, where myGroup is the case-sensitive name of the group (you can have subgroups as well) and myVar is the case-sensitive name of the variable. There are two ways to use variables in the robot text API commands:

Single-value variables

Unrolling array variables

  • An unrolling array variable holds an array and has the prefix *vars. The asterisk (*) unrolls the array to pass individual elements to the function.

  • Example: MoveJoints(*vars.myGroup.myJointPos)

Managing variables with Mecademicpy (Python API)#

The Python API provides a simplified API for managing variables. All robot variables are synchronized and stored in the robot class as attributes of robot.vars.

Creating or deleting a robot variable#

The robot Python class provides the same functions to manage variables:

  • robot.CreateVariable

  • robot.SetVariable

  • robot.DeleteVariable

  • robot.GetVariable

  • robot.ListVariables

Please refer to Mecademicpy’s documentation for details on these function calls.

Directly accessing robot variables through Python attributes#

While a Python script can access a variable using robot.GetVariable and modify it with robot.SetVariable or robot.CreateVariable, our Python API offers a more convenient approach: variables are available as attributes of robot.vars.

To access a variable, use: robot.vars.myGroup.myVar

or: robot.vars.get("myGroup.myVar"), which returns an object of type RegisteredVariable

To modify a variable, assign a new value: robot.vars.myGroup.myVar = [1, 2, 3, 4, 5, 6]

Warning

Setting a variable value is a blocking operation, as it involves sending a TCP request to the robot and waiting for confirmation. Additionally, the robot must write the new value to persistent storage. For optimal performance, Python program should use local variables (and not robot variables) for values that change frequently during runtime.

Managing variables with cyclic protocols#

In cyclic protocols (see Section 4), variables are accessed by their cyclic ID, which is defined when the variable is created.

The cyclic ID of a variable must be in the range [10000,19999].

By referring to this cyclic ID, cyclic protocols can modify variables and use to their values as arguments for motion commands.

Note

Cyclic protocols do not support creating, deleting, getting, or listing variables.

Setting a variable#

A variable is modified by using its cyclic ID as the command ID in a sent cyclic command. For more information on how to send a command using cyclic protocols, see Section 4.2.

The six floating-point values of the motion command are used to set the new value of the variable as follows:

  • Cyclic protocols support only setting variables of type number or array of numbers;

  • For a variable of type number, the first argument of the cyclic command is used as the new value;

  • For a variable of type array of numbers, the corresponding number of cyclic command arguments are used to update the array. The size of the array remains unchanged and cannot be modified through cyclic protocols;

Note

Remember that the variable type is defined when the variable is created (CreateVariable) and cannot be changed afterward. The robot also does not perform any automatic type conversion. Therefore, boolean or string variables cannot be assigned through cyclic protocols.

Reading a variable#

All variables with an assigned cyclic ID are reported in the cyclic dynamic data, using their cyclic ID as the DynamicDataTypeID. See Dynamic data configuration for details on reading dynamic data —including variables— via cyclic protocols.

Referencing a variable#

To use a variable (or multiple variables) as arguments for cyclic protocol motion commands, proceed as follows:

  • Set the desired command ID (example: 2 for MovePose);

  • Set the UseVariables bit in cyclic motion control data (see Section 4.4.2);

  • Set the variable ID(s) to use as the float arguments of the motion parameters structure (see Section 4.4.3).

As a result:

  • The chosen variable value(s) will be used in place of the inline motion command arguments;

  • The values of the selected variables will be concatenated and used as (up to six) arguments for the motion command. This allows you to combine the values from multiple variables for a single motion command.

Warning

Although the Meca500 robot’s EtherCAT stack supports setting variables, it does not support referencing variables as arguments for motion commands. As an alternative, you can create a robot program that uses the variable and call this program from EtherCAT (see StartProgram, called using command ID 100, see Table 8).

Example#

In this example, we create a variable that is defined as an array of 6 float values, then use it to call the MovePose command.

Note

It is also possible to pass multiple variables to the function, for example, one array of three floats for [x, y, z] and another for [alpha, beta, gamma], or six separate variables each holding a single float. However, for simplicity, the following example uses a single variable containing all six float values.

Assuming we have previously created the following variable (using the MecaPortal or the text API):

  • myCartPos

    • Array of six floating-point values, representing [x, y, z, alpha, beta, gamma]

    • Cyclic ID: 10000

The PLC can modify the variable myCartPos as shown below:

  • Send motion command with ID 10000 (referring to myCartPos), using motion command arguments [190.0, 0.0, 308.9, -1, 75, -2] (see Section 4.4.3);

The PLC then selects the variable to be used in a MovePose command as follows:

  • Set motion command with ID 2 (MovePose)

  • With the UseVariables bit set (see Section 4.4.2);

  • And as command arguments, the cyclic ID of the variable to use: [10000,0, 0, 0, 0, 0];

  • Note that here up to 6 variables could be used for calling the command, in this example we refer to a single variable that contains an array of 6 float.

As a result: