Skip to content

General Interfaces

This page describes all interfaces, which all or most robots have in common. Still, there are some minor differences between robots, even for this common interfaces. See here for a list of differences between robots in the common interfaces.

Overview

Robot Status Interfaces

Current Robot Joint States

Description

This message indicates the current robot joint states. The message is published constantly as long as a robot driver is defined in the robot system and connected correctly to a robot.

Message Values

  • header: json object, contains general information about the message.
  • header/seq: int, contains the sequence number of the message. Currently not used.
  • header/stamp: unix timestamp, contains the timestamp of creation time of the message.
  • header/frame_id: string, contains the reference frame for coordinates in this message. Currently not used.
  • name: string array, contains the names of all joints of the robot.
  • position: float array, contains the current joint position for all joints (order is according to name). Rotational joints are in rad, linear joints are in m.
  • velocity: float array, contains the current joint velocities for all joints (order is according to name). Rotational joints are in rad/s, linear joints are in m/s. The values are only set when available and are zero otherwise.
  • effort: float array, contains the current joint efforts for all joints (order is according to name). Rotational joints are in Nm, linear joints are in N. The values are currently not used and are all set to zero.

Message Examples

{
    "op": "publish",
    "topic": "joint_states",
    "msg": {
        "header": {
            "seq": 0,
            "stamp": 1675238389.811244687,
            "frame_id": ""
        },
        "name": ["joint_1", "joint_2", "joint_3", "joint_4", "joint_5", "joint_6"],
        "position": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
        "velocity": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
        "effort": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
    }
}

Current Robot Flange Pose (Position + Quaternion)

Description

This message indicates the current robot flange pose communicated by the robot controller. The orientation is described as a quaternion. The message is published constantly as long as a robot driver is defined in the robot system and connected correctly to a robot.

Message Values

  • position: json object, contains the positional part of the robot flange pose.
  • position/x: float, contains the x coordinate of the robot flange position in m.
  • position/y: float, contains the y coordinate of the robot flange position in m.
  • position/z: float, contains the z coordinate of the robot flange position in m.
  • orientation: json object, contains the orientational part of the robot flange pose as a quaternion.
  • orientation/x: float, contains the quaternion x coordinate of the robot flange orientation.
  • orientation/y: float, contains the quaternion y coordinate of the robot flange orientation.
  • orientation/z: float, contains the quaternion z coordinate of the robot flange orientation.
  • orientation/w: float, contains the quaternion w coordinate of the robot flange orientation.

Message Examples

{
    "op": "publish",
    "topic": "pose_state",
    "msg": {
        "position": {
            "x": 0.0,
            "y": 0.0,
            "z": 0.0
        },
        "orientation": {
            "x": 0.0,
            "y": 0.0,
            "z": 0.0,
            "w": 1.0
        }
    }
}

Current Robot Flange Pose (Position + Euler Angles)

Description

This message indicates the current robot flange pose communicated by the robot controller. The orientation is described as euler angles following the euler intrinsic zyx convention. The message is published constantly as long as a robot driver is defined in the robot system and connected correctly to a robot.

Message Values

  • x: float, contains the x coordinate of the robot flange position in m.
  • y: float, contains the y coordinate of the robot flange position in m.
  • z: float, contains the z coordinate of the robot flange position in m.
  • alpha: float, contains the z coordinate of the robot flange orientation (rotation around z in rad).
  • beta: float, contains the y coordinate of the robot flange orientation (rotation around y in rad).
  • gamma: float, contains the x coordinate of the robot flange orientation (rotation around x in rad).

Message Examples

{
    "op": "publish",
    "topic": "tool_frame",
    "msg": {
        "x": 0.0,
        "y": 0.0,
        "z": 0.0,
        "alpha": 0.0,
        "beta": 0.0,
        "gamma": 0.0,
    }
}

Current Robot Status

Description

This message indicates the current robot state communicated by the robot controller. The message is published constantly as long as a robot driver is defined in the robot system and connected correctly to a robot.

Message Values

  • header: json object, contains general information about the message.
  • header/seq: int, contains the sequence number of the message. Currently not used.
  • header/stamp: unix timestamp, contains the timestamp of creation time of the message.
  • header/frame_id: string, contains the reference frame for coordinates in this message. Currently not used.
  • mode/val: int, contains the current robot mode. Possible value are: -1 = unknown, 0 = undefined, 1 = manual mode, 2 = auto mode
  • e_stopped/val: int, contains the current emergency stopped state. Possible value are: -1 = unknown, 0 = false/off/disabled/low/open, 1 = true/on/enabled/high/closed
  • drives_powered/val: int, contains the current drives powered state. Possible value are: -1 = unknown, 0 = false/off/disabled/low/open, 1 = true/on/enabled/high/closed
  • motion_possible/val: int, contains the current motion is possible state. Possible value are: -1 = unknown, 0 = false/off/disabled/low/open, 1 = true/on/enabled/high/closed
  • in_motion/val: int, contains the current motion state. Possible value are: -1 = unknown, 0 = false/off/disabled/low/open, 1 = true/on/enabled/high/closed
  • in_error/val: int, contains the current error state. Possible value are: -1 = unknown, 0 = false/off/disabled/low/open, 1 = true/on/enabled/high/closed
  • error_code: int, contains the current error code sent by the robot controller. Depending on the robot the codes depiction might differ from the depiction on the robots teach pendant or robots internal depiction.

Message Examples

{
    "op": "publish",
    "topic": "robot_status",
    "msg": {
        "header": {
            "seq": 0,
            "stamp": 1675238389.811244687,
            "frame_id": ""
        },
        "mode": {
            "val": 0
        },
        "e_stopped": {
            "val": 0
        },
        "drives_powered": {
            "val": 0
        },
        "motion_possible": {
            "val": 0
        },
        "in_motion": {
            "val": 0
        },
        "in_error": {
            "val": 0
        },
        "error_code": 0
    }
}

Robot Command Interfaces

Stop Robot

Description

This command immediately stops the robot, stops all currently executed and discards all pending movements in the robot controller and robot driver. Depending on the robot, it will be waited until the robot is fully stopped before the response message is sent.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

nothing

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "stop_robot_right_now",
    "args": []
}

Response Values

  • success: bool, indicates if the request could be executed.
  • message: string, optional message containing information about the result.

Response Example

{
    "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "stop_robot_right_now",
    "values": {
        "success": true,
        "message": ""
    },
    "result": true
}

Command List

Description

The command list message can be sent to the robot driver to start a movement of the robot.

Message Values

  • header: json object, contains general information about the message.
  • header/seq: int, contains the sequence number of the message. Currently not used.
  • header/stamp: unix timestamp, contains the timestamp of creation time of the message.
  • header/frame_id: string, contains the reference frame for coordinates in this message. Currently not used.
  • commands: array of Command json elements as described below. Each command describes one waypoint of robot movement.
  • replace_previous_commands: bool, indicates if pending commands should be discarded and the robot is stopped before the new commands are added.

Command JSON element

  • header: json object, contains general information about the message.
  • header/seq: int, contains the sequence number of the message. Currently not used.
  • header/stamp: unix timestamp, contains the timestamp of creation time of the message.
  • header/frame_id: string, contains the reference frame for coordinates in this message. Currently not used.
  • command_id: int, unique id number to identify the command later. The number can be used again after it has been completely processed.
  • command_type: string, type of the movement. Currently are available for all robots: LIN, PTP. Other, more specialized commands might be available depending on the robot.
  • pose_reference: string, reference frame of the target pose. This should be left empty as commands sent directly to the robot are assumed to be in the robot coordinate system.
  • pose_reference_frame: reference pose of the target pose. This should be left a zero pose as commands sent directly to the robot are assumed to be absolute coordinates.
  • pose_reference_frame/x: float, contains the x coordinate of the reference position of the target pose in m. Should be left zero as described above.
  • pose_reference_frame/y: float, contains the y coordinate of the reference position of the target pose in m. Should be left zero as described above.
  • pose_reference_frame/z: float, contains the z coordinate of the reference position of the target pose in m. Should be left zero as described above.
  • pose_reference_frame/alpha: float, contains the z coordinate of the reference orientation of the target pose (rotation around z in rad). Should be left zero as described above.
  • pose_reference_frame/beta: float, contains the y coordinate of the reference orientation of the target pose (rotation around y in rad). Should be left zero as described above.
  • pose_reference_frame/gamma: float, contains the x coordinate of the reference orientation of the target pose (rotation around x in rad). Should be left zero as described above.
  • pose_type: string, format of the pose. Currently are available for all robots: JOINTS, EULER_INTRINSIC_ZYX. Further for most robots is available: QUATERNION. Note that there might be restrictions depending on the robot, which representation is allowed with which command_type. E.g. some robots don't allow JOINTS with LIN movements.
  • pose: float array, contains the target pose. If pose_type is JOINTS all values are rad for rotational joints and m for translational joints. If pose_type is EULER_INTRINSIC_ZYX order is x, y, z, rz, ry, rx and units are m for position and rad for orientation values. If pose_type is QUATERNION, order is x, y, z, qx, qy, qz, qw and units are m for position.
  • velocity_type: string, defines the unit of the velocity parameter. Which units are available depends on the robot. Usually the units M/S are used for LIN movements, and PERCENT (0 to 100) is used for PTP movements. Depending on the robot other values can be used like MM/S instead of M/S or factor(%, 0.0 to 1.0) instead of percent. The values are then converted into the necessary units for the robot. The recommended unit is M/S or MM/S for LIN and PERCENT for PTP movements.
  • velocity: float array, defines the velocity of the movement described by the velocity_type. Only the first element of the array is used.
  • acceleration_type: string, defines the unit of the acceleration parameter. Which units are available depends on the robot. Usually the units M/S^2 or PERCENT (0 to 100) are used for LIN movements, and PERCENT is used for PTP movements. Depending on the robot and movement type other values can be used like MM/S^2 instead of M/S^2 or factor(%, 0.0 to 1.0) instead of percent. The values are then converted into the necessary units for the robot. The recommended unit is PERCENT for all types of movement.
  • acceleration: float array, defines the acceleration of the movement described by the acceleration_type. Only the first element of the array is used.
  • effort_type: string, defines the unit of the effort parameter. This is currently not used.
  • effort: float array, defines the effort of the movement described by the effort_type. This is currently not used.
  • blending_type: string, defines the unit of the blending parameter. Which units are available depends on the robot. Usually the units M or PERCENT (0 to 100) are used for LIN movements, and PERCENT is used for PTP movements. Depending on the robot and movement type other values can be used like MM instead of M or factor(%, 0.0 to 1.0) instead of percent. The values are then converted into the necessary units for the robot. The recommended unit is PERCENT for all types of movement. Note that the actual behavior of blending highly depends on the definition of blending of the manufacturer of the used robot.
  • blending: float array, defines the blending of the movement described by the blending_type. Only the first element of the array is used.
  • additional_parameters: string array, might contain additional parameters to configure special behavior in the robot. Which features are available depends on the used robot.
  • additional_values: float array, might contain additional values to configure special behavior in the robot. Which features are available depends on the used robot.

Message Example 1 (LIN, Euler)

{
    "op": "publish",
    "topic": "command_list",
    "msg": {
        "header": {
            "seq": 0,
            "stamp": 1675238389.811244687,
            "frame_id": ""
        },
        "commands": [
            {
                "header": {
                    "seq": 0,
                    "stamp": 1675238389.811244687,
                    "frame_id": ""
                },
                "command_id": 123456789,
                "command_type": "LIN",
                "pose_reference": "",
                "pose_reference_frame": {
                    "x": 0.0,
                    "y": 0.0,
                    "z": 0.0,
                    "alpha": 0.0,
                    "beta": 0.0,
                    "gamma": 0.0,
                },
                "pose_type": "EULER_INTRINSIC_ZYX",
                "pose": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6],
                "velocity_type": "M/S",
                "velocity": [0.1],
                "acceleration_type": "PERCENT",
                "acceleration": [50],
                "effort_type": "",
                "effort": [],
                "blending_type": "PERCENT",
                "blending": [50],
                "additional_parameters": [],
                "additional_values": []
            }
        ],
        "replace_previous_commands": true
    }
}

Message Example 2 (PTP, Joints)

{
    "op": "publish",
    "topic": "command_list",
    "msg": {
        "header": {
            "seq": 0,
            "stamp": 1675238389.811244687,
            "frame_id": ""
        },
        "commands": [
            {
                "header": {
                    "seq": 0,
                    "stamp": 1675238389.811244687,
                    "frame_id": ""
                },
                "command_id": 123456789,
                "command_type": "PTP",
                "pose_reference": "",
                "pose_reference_frame": {
                    "x": 0.0,
                    "y": 0.0,
                    "z": 0.0,
                    "alpha": 0.0,
                    "beta": 0.0,
                    "gamma": 0.0,
                },
                "pose_type": "JOINTS",
                "pose": [0.6, 0.5, 0.4, 0.3, 0.2, 0.1],
                "velocity_type": "PERCENT",
                "velocity": [10],
                "acceleration_type": "PERCENT",
                "acceleration": [50],
                "effort_type": "",
                "effort": [],
                "blending_type": "PERCENT",
                "blending": [50],
                "additional_parameters": [],
                "additional_values": []
            }
        ],
        "replace_previous_commands": true
    }
}

Command Result

Description

This message indicates that a previously sent movement command has been finished or aborted by the robot driver.

Message Values

  • header: json object, contains general information about the message.
  • header/seq: int, contains the sequence number of the message. Currently not used.
  • header/stamp: unix timestamp, contains the timestamp of creation time of the message.
  • header/frame_id: string, contains the reference frame for coordinates in this message. Currently not used.
  • command_id: int, contains the last processed command_id from the command_list message which was processed from the driver.
  • result_code: int, contains a result code indicating the outcome of the latest command. A list of possible values is listed below.
  • additional_information: string, may contain additional information about the command result.

Result Values

  • SUCCESS: 0
  • FAILURE_EXECUTION: 3000
  • FAILURE_COMPONENT_NOT_READY: 3010
  • FAILURE_TARGET_NOT_REACHABLE: 3020
  • FAILURE_OUT_OF_REACH: 3021
  • FAILURE_ROBOT_CONFIGURATION: 3022
  • FAILURE_JOINT_LIMIT: 3023
  • FAILURE_CROSSING_SINGULARITY: 3024
  • FAILURE_EMERGENCY_STOP: 3030
  • FAILURE_COMMUNICATION: 3040
  • FAILURE_POSSIBLE_COLLISION: 3050
  • FAILURE_IK: 3051
  • FAILURE_COLLISION_CHECKING: 3052

Message Examples

{
    "op": "publish",
    "topic": "command_result",
    "msg": {
        "header": {
            "seq": 0,
            "stamp": 1675238389.811244687,
            "frame_id": ""
        },
        "command_id": 123456789,
        "result_code": 3020,
        "additional_information": ""
    }
}

Robot Speed Scale Interfaces

Set Robot Speed Scale

Description

This commands allows the user to set the global speed scale factor for all movement commands executed by the robot. This factor is applied to the absolute speed values of each individual movement command. Note that the factor usually acts cumulative to the speed override in the robot controller. E.g. assuming both to be set to 10% results in 1% of the defined speed from the movement command.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

  • value: float, speed factor (0 to 1) for the scaling.

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "scale_speed",
    "args": {
        "value": 0.4
    }
}

Response Values nothing

Response Example

{
    "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "scale_speed",
    "values": {},
    "result": true
}

Current Robot Speed Scale

Description

This message indicates the currently configured global speed scale factor for all movement commands executed by the robot. The message is published constantly as long as a robot driver is defined in the robot system and connected correctly to a robot.

Message Values

  • data: 0-1 float, current speed factor of the scaling.

Message Example

{
    "op": "publish",
    "topic": "current_speed_scale",
    "msg": {
        "data": 0.4
    }
}

Digital Input / Output Interfaces

Management of digital inputs and outputs is available through two sets of interfaces. IO Interface v1 is the original interface, which is considered deprecated and should just be used if the new interface is not available for the respective robot. The second interface IO Interface v2 is available for most of the robots and provides more possibilities and a better understandable mapping of the provided IOs to the existing hardware IOs. The IO Interface v1 is still available for most robots for backward compatibility reasons, but should not be used any more. It could be removed any time from the robot drivers.

IO Interface v1

IO States

Description

This message indicates the current states of all digital inputs and outputs communicated by the robot controller. The message is published constantly as long as a robot driver is defined in the robot system and connected correctly to a robot.

Message Values

  • inputs: array of IOState json elements as described below.
  • outputs: array of IOState json elements as described below.

IOState JSON element: - pin_number: int, describes the drag&bot pin number of the digital io. This is usually not a 1-to-1 mapping to the controller io pin numbers, as there needs to be an internal mapping in the driver, e.g. in case of several io groups in the controller. - pin_value: bool, describes the signal level of the respective io pin.

Message Examples

{
    "op": "publish",
    "topic": "io_states",
    "msg": {
        "inputs": [
            {
                "pin_number": 1,
                "pin_value": true
            },
            {
                "pin_number": 2,
                "pin_value": false
            }
        ],
        "outputs": [
            {
                "pin_number": 3,
                "pin_value": false
            },
            {
                "pin_number": 4,
                "pin_value": true
            }
        ]
    }
}

Get IO

Description

This command allows the user to request the signal level of a specified digital io.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

  • number: int, describes the drag&bot pin number of the digital io to request the value from.

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "get_io",
    "args": {
        "number": 1
    }
}

Response Values

  • value: bool, describes the signal level of the respective io pin.
  • error: int, describes if there was any error requesting the io value. A value of 0 indicates success, a value of 1 indicates the io pin number is not known in the driver, a value of -1 indicates an unknown error.

Response Example

{
    "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "get_io",
    "values": {
        "value": true,
        "error": 0
    },
    "result": true
}

Set IO

Description

This command allows the user to request setting the signal level of a specified digital output to a given value.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

  • number: int, describes the drag&bot pin number of the digital output to request the value from.
  • value: bool, describes the signal level to set the respective output pin to.

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "set_io",
    "args": {
        "number": 1,
        "value": true
    }
}

Response Values

  • value: bool, describes the signal level of the respective io pin.
  • error: int, describes if there was any error setting the value. A value of 0 indicates success, a value of 1 indicates the io pin number is not known in the driver, a value of 2 indicates that it was attempted to set a digital input pin, a value of -1 indicates an unknown error.

Response Example

{
    "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "set_io",
    "values": {
        "error": 2
    },
    "result": true
}

IO Interface v2

The IO Interface v2 is designed such that it can be applied on any device, which can provide digital ios. As a result all services are namespaced. The namespace for robots is usually "robot". All examples provided for the new io interface are for this case. In case of another device the "robot" prefix in the service names has to be replaced by the namespace of the other device.

Further the new io interface is designed to distinguish better between different io groups on the controller. It tries to describe the io setup as close as it displays in the hardware setup to the user.

The interface is highly modular and messages are used in several services. These json elements are described in the following:

IOID JSON element

  • group_id: string, describes the group of the io. Common group ids are e.g. "DO" and "DI".
  • pin_number: int, describes the pin number within the group of the io.

Example

{
    "group_id": "DI",
    "pin_number": 1
}

IOInfo JSON element

  • id: IOID json element defining the io as described above.
  • type: int, describes the type of the io. Available values are: DIGITAL_INPUT = 1, DIGITAL_OUTPUT = 2, ANALOG_INPUT = 3, ANALOG_OUTPUT = 4. Analog ios are not officially supported yet by the interface and are just stated for future use. Still they might already be used by some robots.
  • display_title: string, describes the display title of the io. The display title can be configured by the user.
  • simulated: bool, indicates whether the io is set to be simulated. Simulated inputs can be set like outputs. As long an io is set to be simulated, the simulated value is used for all purposes of the io.

Example

{
    "id": {
        "group_id": "DI",
        "pin_number": 1
    },
    "type": 1,
    "display_title": "",
    "simulated": false
}

IOGroupInfo JSON element

  • id: string, describes the id identifying all ios within the group. Common group ids are e.g. "DO" and "DI".
  • name: string, describes the full name of the io group. Common group names are e.g. "Digital Outputs" and "Digital Inputs".
  • type: int, describes the type of ios this group provides. All ios within the group have to be of the same type. Available values are: DIGITAL_INPUT = 1, DIGITAL_OUTPUT = 2, ANALOG_INPUT = 3, ANALOG_OUTPUT = 4. Analog ios are not officially supported yet by the interface and are just stated for future use. Still they might already be used by some robots.
  • ios: array of all IOInfo json elements within this group as described above.

Example

{
    "id": "DI",
    "name": "Digital Inputs",
    "type": 1,
    "ios": [
        {
            "id": {
                "group_id": "DI",
                "pin_number": 1
            },
            "type": 1,
            "display_title": "",
            "simulated": false
        },
        {
            "id": {
                "group_id": "DI",
                "pin_number": 2
            },
            "type": 1,
            "display_title": "",
            "simulated": false
        }
    ]
}

Get IO Groups

Description

This command allows the user to request meta information about all registered io groups on the device.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

nothing

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/get_io_groups",
    "args": {}
}

Response Values

  • infos: array of IOGroupInfo json elements as described above.

Response Example

{
    "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/get_io_groups",
    "values": {
        "infos": [
            {
                "id": "DI",
                "name": "Digital Inputs",
                "type": 1,
                "ios": [
                    {
                        "id": {
                            "group_id": "DI",
                            "pin_number": 1
                        },
                        "type": 1,
                        "display_title": "",
                        "simulated": false
                    },
                    {
                        "id": {
                            "group_id": "DI",
                            "pin_number": 2
                        },
                        "type": 1,
                        "display_title": "",
                        "simulated": false
                    }
                ]
            },
            {
                "id": "DO",
                "name": "Digital Outputs",
                "type": 2,
                "ios": [
                    {
                        "id": {
                            "group_id": "DO",
                            "pin_number": 1
                        },
                        "type": 2,
                        "display_title": "",
                        "simulated": false
                    },
                    {
                        "id": {
                            "group_id": "DO",
                            "pin_number": 2
                        },
                        "type": 2,
                        "display_title": "",
                        "simulated": false
                    }
                ]
            }
        ]
    },
    "result": true
}

Get IO Group Info

Description

This command allows the user to request meta information about a specified registered io group on the device.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

  • id: string, describes the group id to request information about.

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/get_io_group_info",
    "args": {
        "id": "DI"
    }
}

Response Values

  • info: IOGroupInfo json element of the requested group as described above. The element is not filled out, if the group does not exist.
  • error: int, describes if there was any error requesting the information. A value of 0 indicates success, a value of 3 indicates the group id is not registered on the device.

Response Example

{
    "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/get_io_group_info",
    "values": {
        "info": {
            "id": "DI",
            "name": "Digital Inputs",
            "type": 1,
            "ios": [
                {
                    "id": {
                        "group_id": "DI",
                        "pin_number": 1
                    },
                    "type": 1,
                    "display_title": "",
                    "simulated": false
                },
                {
                    "id": {
                        "group_id": "DI",
                        "pin_number": 2
                    },
                    "type": 1,
                    "display_title": "",
                    "simulated": false
                }
            ]
        },
        "error": 0
    },
    "result": true
}

Get IO Info

Description

This command allows the user to request meta information about a specified registered io on the device.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

  • id: IOID json element defining the io as described above.

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/get_io_info",
    "args": {
        "id": {
            "group_id": "DI",
            "pin_number": 1
        }
    }
}

Response Values

  • info: IOInfo json element of the requested io as described above. The element is not filled out, if the io does not exist.
  • error: int, describes if there was any error requesting the information. A value of 0 indicates success, a value of 1 indicates the io is not registered on the device.

Response Example

{
    "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/get_io_info",
    "values": {
        "info": {
            "id": {
                "group_id": "DI",
                "pin_number": 1
            },
            "type": 1,
            "display_title": "",
            "simulated": false
        },
        "error": 0
    },
    "result": true
}

Get Digital IOs

Description

This command allows the user to request one or more digital io states for registered ios on the device.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

  • ios: array of IOID json elements of the requested ios as described above.

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/get_digital_ios",
    "args": {
        "ios": [
            {
                "group_id": "DI",
                "pin_number": 1
            },
            {
                "group_id": "DI",
                "pin_number": 3
            }
        ]
    }
}

Response Values

  • ios: array of DigitalIOValue json elements with the requested io values as described below. The element is not listed, if an error occurred for this io.
  • success: bool, indicates if the overall request was successful (true) or if there was any error (false).
  • errors: array of IOError json elements, describing errors requesting the io values as described below. Each entry contains error information about one io. There is no entry for an io, if no error occurred.

DigitalIOValue JSON element

  • id: IOID json element as described above.
  • value: bool, describes the digital io state of the io.

IOError JSON element

  • id: IOID json element as described above, describing which io failed.
  • error: int, error code describing what failed. The following error codes are possible for this service: ERR_INVALID_IO = 1
  • message: string, might contain more information about the error.

Response Example

{
    "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/get_digital_ios",
    "values": {
        "ios": [
            {
                "id": {
                    "group_id": "DI",
                    "pin_number": 1
                },
                "value": true
            }
        ],
        "success": false,
        "errors": [
            {
                "id": {
                    "group_id": "DI",
                    "pin_number": 3
                },
                "error": 1,
                "message": "INVALID_IO"
            }
        ]
    },
    "result": true
}

Set Digital IOs

Description

This command allows the user to request to set one or more digital io states for registered ios on the device. Digital input values can just be set, if they are simulated.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

  • ios: array of DigitalIOValue json elements of the requested ios as described in the Get Digital IOs service.

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/set_digital_ios",
    "args": {
        "ios": [
            {
                "id": {
                    "group_id": "DI",
                    "pin_number": 1
                },
                "value": true
            },
            {
                "id": {
                    "group_id": "DO",
                    "pin_number": 1
                },
                "value": true
            }
        ]
    }
}

Response Values

  • success: bool, indicates if the overall request was successful (true) or if there was any error (false).
  • errors: array of IOError json elements, describing errors requesting to set the io values as described below. Each entry contains error information about one io. There is no entry for an io, if no error occurred.

IOError JSON element

  • id: IOID json element as described above, describing which io failed.
  • error: int, error code describing what failed. The following error codes are possible for this service: ERR_INVALID_IO = 1, ERR_NO_OUTPUT = 2 (if it is attempted an unsimulated digital input), ERR_SETTING_FAILED = 4 (if the io value did not change to the desired level)
  • message: string, might contain more information about the error.

Response Example

{
    "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/set_digital_ios",
    "values": {
        "success": false,
        "errors": [
            {
                "id": {
                    "group_id": "DI",
                    "pin_number": 1
                },
                "error": 2,
                "message": "ERR_NO_OUTPUT"
            }
        ]
    },
    "result": true
}

Set IO Display Title

Description

This command allows the user to change the display title of a specified io.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

  • id: IOID json element as described above, describing which io to configure.
  • display_title: string, describing the new display title to set to the io.

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/set_io_display_title",
    "args": {
        "id": {
            "group_id": "DI",
            "pin_number": 1
        },
        "display_title": "Gripper Opened"
    }
}

Response Values

  • error: int, error code describing what failed. The following error codes are possible for this service: SUCCESS=0, ERR_INVALID_IO = 1

Response Example

{
    "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/set_io_display_title",
    "values": {
        "error": 0
    },
    "result": true
}

Set IO Simulated

Description

This command allows the user to change the simulation state of a specified io.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

  • id: IOID json element as described above, describing which io to configure.
  • simulated: bool, describing the new simulation state of the io.

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/set_io_simulated",
    "args": {
        "id": {
            "group_id": "DI",
            "pin_number": 1
        },
        "simulated": true
    }
}

Response Values

  • error: int, error code describing what failed. The following error codes are possible for this service: SUCCESS=0, ERR_INVALID_IO = 1, ERR_SETTING_FAILED = 4 (in case the device is set to simulate all ios and the request tries to unsimulate)

Response Example

{ "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/set_io_simulated",
    "values": {
        "error": 0
    },
    "result": true
}

Set All IOs Simulated

Description

This command allows the user to change the simulation state of all ios on the device.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

  • data: bool, describing the new simulation state of all ios.

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/set_all_ios_simulated",
    "args": {
        "data": true
    }
}

Response Values

  • success: bool, indicates if changing all ios to simulated succeeded or failed
  • message: string, additional information why changing all ios to simulated failed

Response Example

{
    "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/set_all_ios_simulated",
    "values": {
        "success": true,
        "message": ""
    },
    "result": true
}

Get All IOs Simulated

Description

This command allows the user to check the simulation state of all ios on the device.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

nothing

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/get_all_ios_simulated",
    "args": {}
}

Response Values

  • value: bool, indicates if all ios are set to be simulated.

Response Example

{
    "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "robot/get_all_ios_simulated",
    "values": {
        "value": false
    },
    "result": true
}

Error Code Interface

Clear Error

Description

This command allows the user to clear errors on the robot controller. This command is not available on all robots.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

nothing

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "clear_robot_error",
    "args": {}
}

Response Values

  • success: bool, indicates if clearing the error succeeded. This result is not always reliable, as the error may persist or an other error may arise. It just indicates if the attempt to clear the error was successful.
  • message: string, describing the reason why clearing the error failed.

Response Example

{
    "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "clear_robot_error",
    "values": {
        "success": true,
        "message": ""
    },
    "result": true
}

Get Error Code Information

Description

This command allows the user to receive more information about a given error code. This command is not available on all robots.

Hints

  • id: The id should be an auto generated unique id (guid/uuid) to reliably match a received response to the sent request.

Request Parameters

  • error_code: string, error code to request more information about, e.g. received from the robot status message.

Request Example

{
    "op": "call_service",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "get_error_code_information",
    "args": {
        "error_code": "1234"
    }
}

Response Values

  • error_code_information/code: string, the original error code from the robot manufactuerer. The drag&bot error code might differ a bit for representation reasons.
  • error_code_information/classification: string, classification string of the error, if available.
  • error_code_information/description: string, describes the error in more detail.
  • error_code_information/action_type: int, code, which indicates, whether more actions have to be performed. 0= no further actions have to be performed, 1=the position of the robot has to be confirmed.
  • error_code_information/required_time: int, estimated required time to reset the error before operation can be resumed. Some errors require a specific time to recover, e.g. because the controller has to be restarted.
  • result_code: int, descibes the result of the request. A value of 0 indicates success and the information is available in the error_code_information field. A value of 1 indicates the error code is not registered and no information was found.

Response Example

{
    "op": "service_response",
    "id": "02c02fd2-304e-43f7-b2f8-dc48a44f4f36",
    "service": "get_error_code_information",
    "values": {
        "error_code_information": {
            "code": "A1234",
            "classification": "some_classification",
            "description": "some description",
            "action_type": 0,
            "required_time": 0
        },
        "result_code": 0
    },
    "result": true
}