3.2 Application and global Logic Program Variables

This section describes the topics and services used to read and modify application (shared) variables, and to receive variable updates.

The topics and services described here are listed together with the other topics and services in Topics and Services.

3.2.1 Variable data format

All variable data is exchanged as a JSON string, wrapped in a VariableUpdate message. The message has a header field with the timestamp of the update, and a data.json_string.data field with the JSON string.

A variable update has the following structure:

{
  "update_type": "full",
  "shared_variables": {
    "counter": 123,
    "name": "abc",
    "temperature": 33.334455,
    "waypoint": {"_ur_pose": [0.1, 0.5, 0, 3.14, 0, 0]}
  }
}

Key	Description
`update_type`	`full` if the message contains all variables, `diff` if it only contains the variables that changed
`shared_variables`	The shared (application) variables as `name: value` pairs
`global_variables`	The global variables of the logic programs, see global_variable_update

Variable values are encoded as follows:

URScript type	JSON representation
int	Number without a decimal point (signed 32 bit)
float	Number with a decimal point
bool	`true` / `false`
string	String
list	Array, e.g. `[1, 2, 3]`
list with capacity	`{"_ur_list": [1, 2, 3], "_ur_capacity": 10}`
pose	`{"_ur_pose": [x, y, z, rx, ry, rz]}`

3.2.2 shared_variable_update topic

Topic that publishes the shared (application) variables. The message is published periodically, at most every 500 ms. Shared variables can be changed by a robot program, a logic program or by the set_shared_variables service.

The data.json_string.data field of the message contains the JSON variable update, with the variables under shared_variables.

To read the variables on demand, use the get_variables service.

3.2.3 global_variable_update topic

Topic that publishes changes of the global variables of the logic programs. A message is published when the global variables of a logic program change, and when a logic program is started or stopped.

The data.json_string.data field of the message contains the JSON variable update. The variables are grouped by logic program name under the global_variables key:

{
  "update_type": "diff",
  "global_variables": {
    "logic_program_id": 1,
    "my_program": {"global2": 5, "global4": 7}
  }
}

Key	Description
`logic_program_id`	Id of the logic program the update belongs to
`<program name>`	The global variables of that logic program as `name: value` pairs

When a logic program is started, an initial full update is published in which the variables that are not yet assigned have the value null.

3.2.4 set_shared_variables service

Service that creates, modifies or deletes shared variables.

Request

Field	Description
`request.json_string.data`	JSON string with the new values. The variables must be given under the `shared_variables` key

A variable that does not exist is created.
A variable that exists is assigned the new value.
Setting a variable to null deletes it. Deleting a variable stops all running programs.
The request is validated before anything is changed. If the request is invalid, no variable is modified.

Response

Field	Description
`response.success`	`true` if the variables were updated
`response.result_message.data`	`OK` on success, otherwise a description of the error

Example, set counter to 42 and delete temperature:

ros2 service call /UR20225300015/set_shared_variables urinterfaces/srv/SharedVariablesEditor \
  "{request: {json_string: {data: '{\"shared_variables\": {\"counter\": 42, \"temperature\": null}}'}}}"

3.2.5 get_variables service

Service that returns the current values of all variables as a full update (update_type is full).

Note

There must be at least 500 ms between two calls of this service. Use it only to get the initial state, for example in clients that join late. To follow later changes, subscribe to the shared_variable_update and global_variable_update topics instead. Polling this service continuously puts a high load on the system, and one client that calls it too often can starve all other clients.

Request

The request is empty.

Response

Field	Description
`response.header`	Timestamp of the update
`response.data.json_string.data`	JSON variable update with all variables

If the variables cannot be read, json_string.data contains a JSON error description instead, for example {"error" : "Too many requests made"} when the minimum interval between calls was not kept.

Example:

ros2 service call /UR20225300015/get_variables urinterfaces/srv/VariablesViewer "{}"