Skip to content

Function Block Library

Summary

This page contains a list of the most important function blocks of drag&bot. For each function block a detailed description is provided including input and produced output parameters.

Basic

Raise Custom Exception

Raises a Python exception with the entered name.

Name Data type Description
Inputs Error message String Name of the exception to be raised. If empty, a DEFAULT exception will be raised.
Outputs -

Stop Program

Aborts the currently running program.

Name Data type Description
Inputs -
Outputs -

User Dialog

Creates a message with text and one or several buttons to display to the user. The program execution is paused until the message is closed. One of the buttons of the message has to be clicked to continue the program execution. The result code of this button is returned as output of the function block.

Name Data type Description
Inputs Message String Text displayed in the message.
Button Text String The text on this button.
Button Result Code String The result code of this button.
Outputs Result String The result code of the clicked button.

User Text Input

Displays a message and request a text input by the user. The program execution is paused until the message is closed. The entered text is returned as output of the function block.

Name Data type Description
Inputs Message String Text displayed in the message.
Outputs Result String Text entered by user.

Wait

Waits a specified time before continuing in the program flow.

Name Data type Description
Inputs Time Float The time in seconds which the function block delays the program progress.
Outputs -

Control & Logic

And

Applies logic AND to two boolean input parameters.

Name Data type Description
Inputs Value 1 Boolean First boolean value.
Value 2 Boolean Second boolean value.
Outputs Result Integer Result of the logic operation.

Compare - Boolean

Compares two boolean values.

Name Data type Description
Inputs Operand 1 Boolean The first operand of the comparison.
Condition Select Select to test whether two variables are equal or unequal. Available are == and !=.
Operand 2 Boolean The second operand of the comparison.
Outputs Result Boolean The result of the comparison.

Compare - Float

Compares two float values.

Name Data type Description
Inputs Operand 1 Float The first operand of the comparison.
Condition Select Select one of the comparators. Available are: ==, !=, <, >, <=, >=
Operand 2 Float The second operand of the comparison.
Outputs Result Boolean The result of the comparison.

Compare - Integer

Compares two integer values.

Name Data type Description
Inputs Operand 1 Integer The first operand of the comparison.
Condition Select Select one of the comparators. Available are: ==, !=, <, >, <=, >=
Operand 2 Integer The second operand of the comparison.
Outputs Result Boolean The result of the comparison.

Compare - String

Compares two string values.

Name Data type Description
Inputs Operand 1 String The first operand of the comparison.
Condition Select Select one of the comparators. Available are: ==, !=, <, >, <=, >=
Operand 2 String The second operand of the comparison.
Outputs Result Boolean The result of the comparison.

Condition

Depending on a boolean value either the 'Then' or the 'Else' section is executed. A true input value will result in the execution of the 'Then' section of this function block. Otherwise the 'Else' section is executed.

Name Data type Description
Inputs Boolean Condition If true, is the 'Then' section executed, if false, is the 'Else' section executed.
Outputs -

Counter

Whenever the function block is called an internal counter is raised by one. Place the function block inside a loop to increase the value each cycle.

Name Data type Description
Inputs Boolean Reset Inverse Resets the counter on False and continues counting on True.
Outputs Integer Count The current count.

Loop Do While

Executes the contents of the function block at least once. After the initial loop the contents are repeated as long as the condition applies.

Name Data type Description
Inputs Boolean Condition While true, is the content of the block repeatedly executed.
Outputs -

Loop For

Repeats the contents of the function block until the given amount of cycles is reached.

Name Data type Description
Inputs Boolean Turns The number of times the content of the block is executed.
Outputs -

Not

Inverts a boolean value.

Name Data type Description
Inputs Input Boolean The boolean value to invert.
Outputs Result Boolean The inversion result.

Or

Applies logic OR to two boolean parameters.

Name Data type Description
Inputs Value 1 Boolean First boolean value.
Value 2 Boolean Second boolean value.
Outputs Result Boolean Result of the logic operation.

Parallel

Allows two program parts to be executed at the same time. The block is left when both parts are finished. It will wait for the slower block before continuing. It is not possible to have movement function blocks in more than one branch.

Name Data type Description
Inputs -
Outputs -

Switch Case - Direct Input

Executes one of multiple program branches depending on the given input 'Branch Index'. Select index 0 to execute the first program branch.

Name Data type Description
Inputs Branch Index Integer Index of the branch which will be executed.
Outputs -

Switch Case - Match String

Executes one of multiple program branches depending on the given string input. The string input is compared against 'Match Strings'. If a 'Match String' is identical to the input string then its linked branch is executed. If multiple 'Match Strings' are matching to the input string then only the first linked branch is executed.

Name Data type Description
Inputs String Match Input String This string input is compared against the 'Match Strings' of the cases to select one branch to execute.
Default Branch Integer If no 'Match String' of the Cases matches the 'String Match Input', then the branch with the here given index is executed; the first case has index 0, and so on.
Match String String String that has to match to the input string to execute the branch noted in the case.
Select Branch Integer Index of the branch to execute when the case is selected.
Outputs -

Datastore

The datastore is a persistent key-value database included on each Robot System. All programs can use the following function blocks for CRUD (Create, Read, Update, Delete) operations. See also Datastore for more information about the datastore.

Datastore - Counter

Increases the value of a datastore integer item and saves it back to the datastore. If the item does not exist yet it will be created with 0.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Increment Integer The increment to increase the integer value.
Outputs Incremented Value Integer The incremented resulting integer value.
Exceptions CAST_ERROR - The exception is raised, if the datastore value can not be casted to an integer value, e.g. because it is a different datatype.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Delete All Items

Deletes all datastore items.

Name Data type Description
Inputs -
Outputs -
Exceptions ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Delete Group

Deletes all items of a datastore group.

Name Data type Description
Inputs Namespace String The name of a datastore group whose members will be deleted.
Outputs -
Exceptions NAMESPACE_NOT_FOUND - The exception is raised, if the group does not exist on the datastore.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Delete Item

Deletes a datastore item.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Outputs -
Exceptions ID_NOT_FOUND - The exception is raised, if the item does not exist on the datastore.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Display All Items

Displays all items of the datastore in the ROS log.

Name Data type Description
Inputs -
Outputs -
Exceptions ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Get Value - Boolean

Returns the boolean value of a datastore item.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Outputs Value Boolean The boolean value of the datastore item.
Exceptions ID_NOT_FOUND - The exception is raised, if the item does not exist on the datastore.
CAST_ERROR - The exception is raised, if the datastore value can not be casted to a boolean value, e.g. because it is a different datatype.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Get Value - Float

Returns the float value of a datastore item.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Outputs Value Float The float value of the datastore item.
Exceptions ID_NOT_FOUND - The exception is raised, if the item does not exist on the datastore.
CAST_ERROR - The exception is raised, if the datastore value can not be casted to a float value, e.g. because it is a different datatype.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Get Value - Integer

Returns the integer value of a datastore item.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Outputs Value Integer The integer value of the datastore item.
Exceptions ID_NOT_FOUND - The exception is raised, if the item does not exist on the datastore.
CAST_ERROR - The exception is raised, if the datastore value can not be casted to an integer value, e.g. because it is a different datatype.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Get Value - Joints

Returns the 6 axes joints of a datastore item.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Outputs Value Joints The joint values of the datastore item.
Exceptions ID_NOT_FOUND - The exception is raised, if the item does not exist on the datastore.
INVALID_JOINTS - The exception is raised, if the entry is not a valid joints format for 6 axes.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Get Value - Pose

Returns the pose of a datastore item.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Outputs Value Pose The pose of the datastore item.
Exceptions ID_NOT_FOUND - The exception is raised, if the item does not exist on the datastore.
INVALID_POSE - The exception is raised, if the entry is not a valid pose format.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Get Value - String

Returns the string value of a datastore item.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Outputs Value String The string value of the datastore item.
Exceptions ID_NOT_FOUND - The exception is raised, if the item does not exist on the datastore.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Set Value - Boolean

Sets the value of a datastore item. If it does not exist yet it will be created.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Value Boolean The new boolean value of the datastore item.
Outputs -
Exceptions MISMATCHING_TYPE - The exception is raised, if the datatype of the existing entry does not match the new datatype.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Set Value - Float

Sets the value of a datastore item. If it does not exist yet it will be created.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Value Float The new float value of the datastore item.
Outputs -
Exceptions MISMATCHING_TYPE - The exception is raised, if the datatype of the existing entry does not match the new datatype.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Set Value - Integer

Sets the value of a datastore item. If it does not exist yet it will be created.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Value Integer The new integer value of the datastore item.
Outputs -
Exceptions MISMATCHING_TYPE - The exception is raised, if the datatype of the existing entry does not match the new datatype.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Set Value - Joints

Sets the value of a datastore item. If it does not exist yet it will be created.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Value Joints The new joint values with 6 axes of the datastore item.
Outputs -
Exceptions MISMATCHING_TYPE - The exception is raised, if the datatype of the existing entry does not match the new datatype.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Set Value - Pose

Sets the value of a datastore item. If it does not exist yet it will be created.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Value Pose The new pose value of the datastore item.
Outputs -
Exceptions MISMATCHING_TYPE - The exception is raised, if the datatype of the existing entry does not match the new datatype.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Set Value - String

Set the value of a datastore item. If it does not exist yet it will be created.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Value String The new string value of the datastore item.
Outputs -
Exceptions MISMATCHING_TYPE - The exception is raised, if the datatype of the existing entry does not match the new datatype.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Set Type

Sets the datatype of an existing datastore item.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Type - The new type of the datastore item. Possible values are string, int, float and boolean.
Outputs -
Exceptions ID_NOT_FOUND - The exception is raised, if the item does not exist on the datastore.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Set Display Title

Sets the display title of an existing datastore item.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Display Title String The new display title of the datastore item.
Outputs -
Exceptions ID_NOT_FOUND - The exception is raised, if the item does not exist on the datastore.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Datastore - Set Operator Lock

Set the operator_can_edit option of an existing datastore item.

Name Data type Description
Inputs Datastore ID: Group String The identifying group of the datastore item.
Datastore ID: ID String The identifying id of the datastore item within the group.
Operator Can Edit Boolean The operator can /can not edit the datastore entry in the KPI panel of the dashboard in the Operator Cockpit.
Outputs -
Exceptions ID_NOT_FOUND - The exception is raised, if the item does not exist on the datastore.
ACCESS_ERROR - The exception is raised, if the datastore can not be accessed.

Gripper

2Pin I/O-Gripper - Close

Deprecated

This function block is deprecated and should not be used any more. Use the Digital I/O Gripper component with its function blocks instead.

Closes a gripper controlled with two digital I/Os. A rising flank at the digital I/O pin 'Pin Open' triggers opening/releasing of the gripper. A rising flank at the digital I/O pin 'Pin Close' triggers closing/grasping of the gripper.

Name Data type Description
Inputs Pin Open Integer Number of digital I/O pin which opens the gripper. A rising flank at the pin triggers the opening.
Pin Close Integer Number of digital I/O pin which closes the gripper. A rising flank at the pin triggers the closing.
Outputs -

2Pin I/O-Gripper - Control

Deprecated

This function block is deprecated and should not be used any more. Use the Digital I/O Gripper component with its function blocks instead.

Controls a gripper controlled with two digital I/Os. A rising flank at the digital I/O pin 'Pin Open' triggers opening/releasing of the gripper. A rising flank at the digital I/O pin 'Pin Close' triggers closing/grasping of the gripper.

Name Data type Description
Inputs Pin Open Integer Number of digital I/O pin which opens the gripper. A rising flank at the pin triggers the opening.
Pin Close Integer Number of digital I/O pin which closes the gripper. A rising flank at the pin triggers the closing.
Close Boolean Control whether to open or close the gripper. True closes the gripper.
Outputs -

2Pin I/O-Gripper - Open

Deprecated

This function block is deprecated and should not be used any more. Use the Digital I/O Gripper component with its function blocks instead.

Opens a gripper controlled with two digital I/Os. A rising flank at the digital I/O pin 'Pin Open' triggers opening/releasing of the gripper. A rising flank at the digital I/O pin 'Pin Close' triggers closing/grasping of the gripper.

Name Data type Description
Inputs Pin Open Integer Number of digital I/O pin which opens the gripper. A rising flank at the pin triggers the opening.
Pin Close Integer Number of digital I/O pin which closes the gripper. A rising flank at the pin triggers the closing.
Outputs -

Math

Combine - Strings

Merges an arbitrary number of strings into one string.

Name Data type Description
Inputs String List List of String The string values to merge into one string.
Outputs Result String The result of the merge.

Convert - Binary To Integer

Converts a list of boolean values to an integer value.

Name Data type Description
Inputs Boolean Values List of Boolean List of boolean values from Least Significant Bit (LSB) as first element to Most Significant Bit (MSB) as last element.
Outputs Integer Value Integer The resulting integer value.

Convert - Boolean To String

Converts a boolean to string.

Name Data type Description
Inputs Value Boolean The boolean to convert into a string.
Outputs Text String The resulting string.

Convert - Float To String

Converts a float number to string.

Name Data type Description
Inputs Number Float The float number to convert into a string.
Outputs Text String The resulting string.

Convert - Float To Acceleration

Converts a float number to an acceleration value with unit.

Name Data type Description
Inputs Float Number Float The float number to convert into an acceleration value.
Acceleration Unit Select The acceleration unit for the acceleration value. Available are % and M/S^2.
Outputs Acceleration Value Acceleration The resulting acceleration.

Convert - Float To Blending

Converts a float number to a blending value with unit.

Name Data type Description
Inputs Float Number Float The float number to convert into a blending value.
Blending Unit Select The blending unit for the blending value. Available are % and M.
Outputs Blending Value Blending The resulting blending.

Convert - Float To Integer

Converts a float number to an integer.

Name Data type Description
Inputs Value Float The float number to convert into an integer.
Outputs Cast Result Integer The resulting integer.

Convert - Float To Speed

Converts a float number to a speed value with unit.

Name Data type Description
Inputs Float Number Float The float number to convert into a speed value.
Speed Unit Select The speed unit for the speed value. Available are M/S, DEG/S and %.
Outputs Speed Value Speed The resulting speed.

Convert - Integer To String

Converts an integer number to string.

Name Data type Description
Inputs Number Integer The integer number to convert into a string.
Outputs Text String The resulting string.

Convert - String to Boolean

Casts a string variable to a boolean.

Name Data type Description
Inputs Value String The string value to cast into boolean. The input string is case insensitive. The strings true, on, high, active, enabled and closed are converted to True. The strings false, off, low, inactive, disabled and open are converted to False. For other values an exception is thrown.
Outputs Cast Result Boolean The result of the type casting.
Exceptions E_CAST - The exception is raised, if the string can not be converted to a boolean.

Convert - String to Float

Casts a string variable to an integer.

Name Data type Description
Inputs Value String The string value to cast into integer.
Outputs Cast Result Integer The result of the type casting.
Exceptions E_CAST - The exception is raised, if the string can not be converted to a float.

Convert - String to Integer

Casts a string variable to an integer.

Name Data type Description
Inputs Value String The string value to cast into integer.
Outputs Cast Result Integer The result of the type casting.
Exceptions E_CAST - The exception is raised, if the string can not be converted to an integer.

Joints Transformation

Adds an offset to a given joint state.

Name Data type Description
Inputs Origin Joints The original joints state.
Offset Joints The offset joints state.
Outputs Result Joints The resulting joints state.

Logic

Performs a basic logic operation on two boolean values. The operations are: AND, OR and XOR.

Name Data type Description
Inputs Operand 1 Boolean The first operand of the operation.
Operation Select The chosen logic operation. Available are AND, OR and XOR.
Operand 2 Boolean The second operand of the operation.
Outputs Result Boolean The result of the operation.

Math - Float

Performs a basic arithmetic operation on two float values. The operations are: Addition, Subtraction, Multiplication, Division and Modulo.

Name Data type Description
Inputs Operand 1 Float The first operand of the operation.
Operation Select The chosen arithmetic operation. Available are +, -, *, / and modulo.
Operand 2 Float The second operand of the operation.
Outputs Result Float The result of the operation.
Exceptions DIVISION_BY_ZERO - The exception is raised, if a division by zero is attempted.

Math - Integer

Performs a basic arithmetic operation on two integer values. The operations are: Addition, Subtraction, Multiplication, Division and Modulo.

Name Data type Description
Inputs Operand 1 Integer The first operand of the operation.
Operation Select The chosen arithmetic operation. Available are +, -, *, / and modulo.
Operand 2 Integer The second operand of the operation.
Outputs Result Integer The result of the operation.
Exceptions DIVISION_BY_ZERO - The exception is raised, if a division by zero is attempted.

Pose Transformation

Transforms an offset to a given pose.

Name Data type Description
Inputs Origin Pose Pose The origin pose.
Offset Pose Pose The offset pose.
Difference Boolean If true, the difference between the two poses is calculated: result = origin - offset in 3D.
If false, the offset pose is appended to the origin pose: result = origin + offset in 3D.
Outputs Result Pose Pose The calculated transformation pose.

Robot

Change Robot TCP

Changes the selected TCP at the Tool Manager.

Name Data type Description
Inputs Tool Name String Enter the name of the tool created in the drag&bot tool manager. As a default tool the 'flange' is always selected.
Reattach Simulated Objects Boolean If true, attached simulated objects change their parent frame to avoid jumping when the tool is changed.
Outputs -
Exceptions ERROR_UNKNOWN_TOOL - The exception is raised, if the respective tool does not exist.

Compare - Joints

Compares two joints states to be equal up to a given limit.

Name Data type Description
Inputs
Joints 1 Joints Angles of the first joints state in degrees.
Joints 2 Joints Angles of the second joints state in degrees.
Allowed Joint Error Float The maximum allowed difference between two respective joint angles in degrees.
Ignore Joints 4-6 Boolean If set, joints 4, 5 and 6 are ignored for comparation.
Outputs Success Boolean True, if all tested differences of respective joints are within the allowed joint error. False otherwise.

Compare - Pose

Compares two poses to be equal up to a given limit.

Name Data type Description
Inputs
Pose 1 Pose The first pose to compare.
Pose 2 Pose The second pose to compare.
Compare Position Boolean If set, the translational offset is used for the result.
Compare Orientation Boolean If set, the rotational offset is used for the result.
Maximum Translation Distance Float The maximum allowed translational difference between the two positions in meters.
Maximum Rotation Distance Float The maximum allowed rotational difference between the two orientations in meters.
Outputs Success Boolean True, if the translational and/or (depending on the given setting) rotational distance are within the given limits. False otherwise.
Translation Distance Float The calculated translational offset between both poses.
Rotational Distance Float The calculated rotational offset between both poses (angle shortest path).

Digital I/O - Get

Deprecated

This function block is deprecated and should not be used any more (Exceptions: Denso, KUKA IIWA). Use the Digital I/O Device - Get function block instead.

Requests the value of a digital I/O pin of the robot.

Name Data type Description
Inputs Pin Number Integer Number of a digital I/O pin.
Outputs Value Boolean The value of the digital I/O pin.
Exceptions ERROR_NO_DIGITAL_IO - The exception is raised, if the respective digital I/O does not exist.
TIMEOUT - The exception is raised, if the digital I/O state can not be requested from the robot.

Digital I/O - Set

Deprecated

This function block is deprecated and should not be used any more (Exceptions: Denso, KUKA IIWA). Use the Digital I/O Device - Set function block instead.

Sets the value of one of the I/O pins of the robot.

Name Data type Description
Inputs Pin Number Integer Number of a digital I/O pin.
Value Boolean Value of the digital I/O pin.
Outputs -
Exceptions ERROR_NO_DIGITAL_IO - The exception is raised, if the respective digital I/O does not exist.
ERROR_NO_DIGITAL_OUTPUT - The exception is raised, if the respective digital I/O does exist, but is no digital output.
TIMEOUT - The exception is raised, if the digital I/O state can not be set at the robot.

Digital I/O - Wait For

Deprecated

This function block is deprecated and should not be used any more (Exceptions: Denso, KUKA IIWA). Use the Digital I/O Device - Wait For function block instead.

Pauses the program execution until the desired value is read on the given digital I/O pin. A timeout can be specified to throw an exception.

Name Data type Description
Inputs Pin Number Integer Number of a digital I/O pin.
Desired Value Boolean The value which has to be read on the digital I/O pin to continue program execution.
Timeout Float Timeout in seconds to wait for the signal before a TIMEOUT exception is thrown. A value of zero waits infinitely.
Outputs -
Exceptions ERROR_NO_DIGITAL_IO - The exception is raised, if the respective digital I/O does not exist.
TIMEOUT - The exception is raised, if the digital I/O state can not be requested from the robot.

Digital I/O Device - Get

Requests the value of a digital I/O pin of a device.

Name Data type Description
Inputs I/O Device String ID of a digital I/O device. This is usually the robot, but can be also a supported PLC. The default value is robot.
I/O Group String The digital I/O group for the given device. This is usually an abbreviation, which is also used in the respective controller, like DI for Digital Input or DO for Digital Output. See the respective robot setup or usage page for more information on which groups are available.
I/O Pin Number Integer The digital I/O pin number within the given group for the given device. This follows the same numbering as the respective controller. See the respective robot setup or usage page for more information on which pins are available.
Outputs Digital I/O Value Boolean The value of the digital I/O pin.
Exceptions ERROR_UNKNOWN_DEVICE - The exception is raised, if no I/O device can be found for the given device id.
ERROR_NO_DIGITAL_IO - The exception is raised, if the device can not find the defined group-pin-number combination.

Digital I/O Device - Set

Sets the value of one of the I/O pins of a device.

Name Data type Description
Inputs I/O Device String ID of a digital I/O device. This is usually the robot, but can be also a supported PLC. The default value is robot.
I/O Group String The digital I/O group for the given device. This is usually an abbreviation, which is also used in the respective controller, like DI for Digital Input or DO for Digital Output. See the respective robot setup or usage page for more information on which groups are available.
I/O Pin Number Integer The digital I/O pin number within the given group for the given device. This follows the same numbering as the respective controller. See the respective robot setup or usage page for more information on which pins are available.
Digital I/O Value Boolean Value of the digital I/O pin.
Outputs -
Exceptions ERROR_UNKNOWN_DEVICE - The exception is raised, if no I/O device can be found for the given device id.
ERROR_NO_DIGITAL_IO - The exception is raised, if the device can not find the defined group-pin-number combination.
ERROR_NO_DIGITAL_OUTPUT - The exception is raised, if it is tried to set an other type than a digital output.
ERROR_SET_FAILED - The exception is raised, if setting the pin to the new value failed in the controller.

Digital I/O Device - Wait For

Pauses the program until the desired value is read on the given digital I/O pin. A timeout can be specified to throw an exception.

Name Data type Description
Inputs I/O Device String ID of a digital I/O device. This is usually the robot, but can be also a supported PLC. The default value is robot.
I/O Group String The digital I/O group for the given device. This is usually an abbreviation, which is also used in the respective controller, like DI for Digital Input or DO for Digital Output. See the respective robot setup or usage page for more information on which groups are available.
I/O Pin Number Integer The digital I/O pin number within the given group for the given device. This follows the same numbering as the respective controller. See the respective robot setup or usage page for more information on which pins are available.
Desired Value Boolean The value which has to be read on the digital I/O pin to continue program execution.
Timeout Float Timeout in seconds to wait for the signal before a TIMEOUT exception is thrown. A value of zero waits infinitely.
Outputs Digital I/O Value Boolean The value of the digital I/O pin.
Exceptions ERROR_UNKNOWN_DEVICE - The exception is raised, if no I/O device can be found for the given device id.
ERROR_NO_DIGITAL_IO - The exception is raised, if the device can not find the defined group-pin-number combination.
TIMEOUT - The exception is raised, if the waited time exceeds the given duration.

Get Flange Pose

Requests the pose of the robot flange.

Name Data type Description
Inputs -
Outputs Pose Pose The current pose of the robot flange.

Get TCP Pose

Requests the pose of the currently selected TCP.

Name Data type Description
Inputs -
Outputs Pose Pose The current pose of the robot TCP.

Get Joints

Requests the current joint values of the robot.

Name Data type Description
Inputs -
Outputs Joints Joints The current joint values of the robot in degrees.

Move Cartesian

Moves the robot to one or more waypoints. Each waypoint consists of a position, orientation and movement type, velocity, acceleration and blending parameters. Further each waypoint can be set absolute or relative to a reference pose.

Name Data type Description
Inputs Pose Pose Goal pose.
Pose Reference Pose If set, the goal pose will be relative to this pose.
Movement Type - LIN: Linear movement, robot moves in a straight line.
PTP: Robot chooses path between the points, not always a straight line.
Speed Float Movement speed of the robot in m/s or percent of maximum speed (Percent: 0-100).
Acceleration Float Acceleration of the robot in m/s² or percent of maximum acceleration (Percent: 0-100).
Blending Float The positional blending between waypoints, how precise the waypoint has to be reached.
In meters or percent (Percent: 0-100), actual movement trajectory depends on the robot manufacturer.
Add to Waypoint Queue Boolean When enabled all waypoints of the function block are buffered into the Waypoint Queue instead of being executed at once. The function block returns immediately. See Waypoint Queue for more information.
Outputs -
Exceptions COMMAND_FAILED - The exception is raised if the given target pose is not valid or an unspecified internal error happened during the process.
COMMUNICATION_ERROR - The exception is raised if the movement failed, because the communication to the robot was interrupted.
POSE_NOT_REACHABLE - The exception is raised if the movement failed, because the pose can not reached by the robot.
SAFETY_STOP - The exception is raised if the movement failed, because the safety system was triggered, usually by pressing the emergency stop button.
ROBOT_NOT_READY - The exception is raised if the movement failed, because the controller reported that the robot was no ready to move.
COLLISION_DETECTED - The exception is raised if the movement failed, because a real or forecasted collision was detected.
COMMAND_ERROR - The exception is raised if the movement failed for an unknown reason.

Move Cartesian - Advanced

Moves the robot to one or more waypoints. Each waypoint consists of a position, orientation and movement type, velocity, acceleration and blending parameters. Further each waypoint can be set absolute or relative to a reference pose. The function block includes a field for additional motion control or driver extended functionalities e.g. break motion when input is set.

Name Data type Description
Inputs Pose Pose Goal pose.
Pose Reference Pose If set, the goal pose will be relative to this pose.
Movement Type - LIN: Linear movement, robot moves in a straight line.
PTP: Robot chooses path between the points, not always a straight line.
Speed Float Movement speed of the robot in m/s or percent of maximum speed (Percent: 0-100).
Acceleration Float Acceleration of the robot in m/s² or percent of maximum acceleration (Percent: 0-100).
Blending Float The positional blending between waypoints, how precise the waypoint has to be reached.
In meters or percent (Percent: 0-100), actual movement trajectory depends on the robot manufacturer.
Control Command String Additional commands to the driver. Usually robot-specific and depending on available software and hardware.
Add to Waypoint Queue Boolean When enabled all waypoints of the function block are buffered into the Waypoint Queue instead of being executed at once. The function block returns immediately. See Waypoint Queue for more information.
Outputs -
Exceptions COMMAND_FAILED - The exception is raised if the given target pose is not valid or an unspecified internal error happened during the process.
COMMUNICATION_ERROR - The exception is raised if the movement failed, because the communication to the robot was interrupted.
POSE_NOT_REACHABLE - The exception is raised if the movement failed, because the pose can not reached by the robot.
SAFETY_STOP - The exception is raised if the movement failed, because the safety system was triggered, usually by pressing the emergency stop button.
ROBOT_NOT_READY - The exception is raised if the movement failed, because the controller reported that the robot was no ready to move.
COLLISION_DETECTED - The exception is raised if the movement failed, because a real or forecasted collision was detected.
COMMAND_ERROR - The exception is raised if the movement failed for an unknown reason.

Move Cartesian Relative

Moves the robot relative to the current position by entering a delta pose relative to the current position.

Name Data type Description
Inputs Coordinate System Select Coordinate system in which the relative pose is given.
Pose Delta Pose Relative offset to the current pose in the given coordinate system.
Speed Speed Movement speed of the robot.
Acceleration Float Acceleration of the robot.
Outputs -
Exceptions COMMAND_FAILED - The exception is raised if the given target pose is not valid or an unspecified internal error happened during the process.
COMMUNICATION_ERROR - The exception is raised if the movement failed, because the communication to the robot was interrupted.
POSE_NOT_REACHABLE - The exception is raised if the movement failed, because the pose can not reached by the robot.
SAFETY_STOP - The exception is raised if the movement failed, because the safety system was triggered, usually by pressing the emergency stop button.
ROBOT_NOT_READY - The exception is raised if the movement failed, because the controller reported that the robot was no ready to move.
COLLISION_DETECTED - The exception is raised if the movement failed, because a real or forecasted collision was detected.
COMMAND_ERROR - The exception is raised if the movement failed for an unknown reason.

Move Joints

Moves the robot to one or more waypoints. Each waypoint consists of a joints state and velocity, acceleration and blending parameters.

Name Data type Description
Inputs Joints Joints Angles of the goal joint state in degrees.
Speed Speed Robot speed in deg/s or percent of maximum speed (Percent: 0-100).
Acceleration Acceleration Acceleration of the robot in percent of maximum acceleration (Percent: 0-100).
Blending Blending The positional blending in percent (Percent: 0-100) between waypoints, how precise the waypoint has to be reached.
Add to Waypoint Queue Boolean When enabled all waypoints of the function block are buffered into the Waypoint Queue instead of being executed at once. The function block returns immediately. See Waypoint Queue for more information.
Outputs -
Exceptions COMMAND_FAILED - The exception is raised if the given target pose is not valid or an unspecified internal error happened during the process.
COMMUNICATION_ERROR - The exception is raised if the movement failed, because the communication to the robot was interrupted.
POSE_NOT_REACHABLE - The exception is raised if the movement failed, because the pose can not reached by the robot.
SAFETY_STOP - The exception is raised if the movement failed, because the safety system was triggered, usually by pressing the emergency stop button.
ROBOT_NOT_READY - The exception is raised if the movement failed, because the controller reported that the robot was no ready to move.
COLLISION_DETECTED - The exception is raised if the movement failed, because a real or forecasted collision was detected.
COMMAND_ERROR - The exception is raised if the movement failed for an unknown reason.

Move Joints Relative

Moves the robot relative to the current joints values by entering a delta joints relative to the current joints.

Name Data type Description
Inputs Joints Delta Joints Relative change between joints.
Speed Speed Robot speed in deg/s or percent of maximum speed (Percent: 0-100).
Acceleration Acceleration Acceleration of the robot in percent of maximum acceleration (Percent: 0-100).
Outputs -
Exceptions COMMAND_FAILED - The exception is raised if the given target pose is not valid or an unspecified internal error happened during the process.
COMMUNICATION_ERROR - The exception is raised if the movement failed, because the communication to the robot was interrupted.
POSE_NOT_REACHABLE - The exception is raised if the movement failed, because the pose can not reached by the robot.
SAFETY_STOP - The exception is raised if the movement failed, because the safety system was triggered, usually by pressing the emergency stop button.
ROBOT_NOT_READY - The exception is raised if the movement failed, because the controller reported that the robot was no ready to move.
COLLISION_DETECTED - The exception is raised if the movement failed, because a real or forecasted collision was detected.
COMMAND_ERROR - The exception is raised if the movement failed for an unknown reason.

Move Joints - Advanced

Moves the robot to one or more waypoints. Each waypoint consists of a joint state and velocity, acceleration and blending parameters. The function block includes a field for additional motion control or driver extended functionalities e.g. break motion when input is set.

Name Data type Description
Inputs Joints Joints Angles of the goal joints state in degrees.
Speed Speed Robot speed in deg/s or percent of maximum speed (Percent: 0-100).
Acceleration Acceleration Acceleration of the robot in percent of maximum acceleration (Percent: 0-100).
Blending Blending The positional blending in percent (Percent: 0-100) between waypoints, how precise the waypoint has to be reached.
Control Command String Additional commands to the driver. Usually robot-specific and depending on available software and hardware.
Add to Waypoint Queue Boolean When enabled all waypoints of the function block are buffered into the Waypoint Queue instead of being executed at once. The function block returns immediately. See Waypoint Queue for more information.
Outputs -
Exceptions COMMAND_FAILED - The exception is raised if the given target pose is not valid or an unspecified internal error happened during the process.
COMMUNICATION_ERROR - The exception is raised if the movement failed, because the communication to the robot was interrupted.
POSE_NOT_REACHABLE - The exception is raised if the movement failed, because the pose can not reached by the robot.
SAFETY_STOP - The exception is raised if the movement failed, because the safety system was triggered, usually by pressing the emergency stop button.
ROBOT_NOT_READY - The exception is raised if the movement failed, because the controller reported that the robot was no ready to move.
COLLISION_DETECTED - The exception is raised if the movement failed, because a real or forecasted collision was detected.
COMMAND_ERROR - The exception is raised if the movement failed for an unknown reason.

Move Joints - 7 Axes

Moves the robot to one or more waypoints. Each waypoint consists of a joint state and velocity, acceleration and blending parameters. This function block is for 7 joints robots.

Name Data type Description
Inputs Joints Joints Angles of the goal joint state in degrees.
Speed Speed Robot speed in deg/s or percent of maximum speed (Percent: 0-100).
Acceleration Acceleration Acceleration of the robot in percent of maximum acceleration (Percent: 0-100).
Blending Blending The positional blending in percent (Percent: 0-100) between waypoints, how precise the waypoint has to be reached.
Add to Waypoint Queue Boolean When enabled all waypoints of the function block are buffered into the Waypoint Queue instead of being executed at once. The function block returns immediately. See Waypoint Queue for more information.
Outputs -
Exceptions COMMAND_FAILED - The exception is raised if the given target pose is not valid or an unspecified internal error happened during the process.
COMMUNICATION_ERROR - The exception is raised if the movement failed, because the communication to the robot was interrupted.
POSE_NOT_REACHABLE - The exception is raised if the movement failed, because the pose can not reached by the robot.
SAFETY_STOP - The exception is raised if the movement failed, because the safety system was triggered, usually by pressing the emergency stop button.
ROBOT_NOT_READY - The exception is raised if the movement failed, because the controller reported that the robot was no ready to move.
COMMAND_ERROR - The exception is raised if the movement failed for an unknown reason.

Pose Checker - Box - Absolute

Checks, whether a given position is inside a defined simple box. The faces of the simple box are orientated along the worlds coordinate systems main axes. All faces of the box have to be defined.

Name Data type Description
Inputs Position Position The position to check.
X min float Position of the box face facing towards the negative x axis of the world coordinate system in meters.
X max float Position of the box face facing towards the positive x axis of the world coordinate system in meters.
Y min float Position of the box face facing towards the negative y axis of the world coordinate system in meters.
Y max float Position of the box face facing towards the positive y axis of the world coordinate system in meters.
Z min float Position of the box face facing towards the negative z axis of the world coordinate system in meters.
Z max float Position of the box face facing towards the positive z axis of the world coordinate system in meters.
Outputs Success Boolean True, if the given position is inside the defined box. False otherwise.

Pose Checker - Box - Relative

Checks, whether a given position is inside a defined simple box. The faces of the simple box are orientated along the worlds coordinate systems main axes. All faces of the box have to be defined by stating a reference point for the box and a distance for each direction.

Name Data type Description
Inputs Position Position The position to check.
Box Position Offset: X float Offset of the box in x axis of the world coordinate system in meters.
Box Position Offset: Y float Offset of the box in y axis of the world coordinate system in meters.
Box Position Offset: Z float Offset of the box in z axis of the world coordinate system in meters.
Box Dimension Negative Direction: X float Position of the box face relative to the offset facing towards the negative x axis of the world coordinate system in meters.
Box Dimension Negative Direction: Y float Position of the box face relative to the offset facing towards the negative y axis of the world coordinate system in meters.
Box Dimension Negative Direction: Z float Position of the box face relative to the offset facing towards the negative z axis of the world coordinate system in meters.
Box Dimension Positive Direction: X float Position of the box face relative to the offset facing towards the positive x axis of the world coordinate system in meters.
Box Dimension Positive Direction: Y float Position of the box face relative to the offset facing towards the positive y axis of the world coordinate system in meters.
Box Dimension Positive Direction: Z float Position of the box face relative to the offset facing towards the positive z axis of the world coordinate system in meters.
Outputs Success Boolean True, if the given position is inside the defined box. False otherwise.

Quick Access Move - Get Joints

Returns the joints of a given Quick Access Move joints waypoint.

Name Data type Description
Inputs Quick Access Move Name String The name of the Quick Access Move to return the joints for.
Waypoint Index Integer The index of the waypoint in the Quick Access Move to return the joints for.
Outputs Joints Joints The joints of the stated Quick Access Move waypoint.
Exceptions INVALID_QUICK_ACCESS_MOVE - The exception is raised if the given Quick Access Move is not known.
INVALID_INDEX - The exception is raised if the stated index is invalid for the Quick Access Move.
INVALID_JOINTS - The exception is raised if the Quick Access Move waypoint is not joints, e.g because it is a pose.

Quick Access Move - Get Pose

Returns the pose of a given Quick Access Move pose waypoint.

Name Data type Description
Inputs Quick Access Move Name String The name of the Quick Access Move to return the pose for.
Waypoint Index Integer The index of the waypoint in the Quick Access Move to return the pose for.
Outputs Pose Pose The pose of the stated Quick Access Move waypoint in world coordinate system. It may be only partially set depending on the definition of the waypoint.
Is Pose Boolean True if both position and orientation are set. False otherwise.
Has Position Boolean True if position is set. False otherwise.
Has Orientation Boolean True if orientation is set. False otherwise.
Exceptions INVALID_QUICK_ACCESS_MOVE - The exception is raised if the given Quick Access Move is not known.
INVALID_INDEX - The exception is raised if the stated index is invalid for the Quick Access Move.
INVALID_POSE - The exception is raised if the Quick Access Move waypoint is not a pose, e.g because it is joints.

Waypoint Queue - Clear

Discards all waypoints buffered in the Waypoint Queue. See Waypoint Queue for more information.

Name Data type Description
Inputs -
Outputs -

Waypoint Queue - Move

Executes all waypoints buffered in the Waypoint Queue. See Waypoint Queue for more information.

Name Data type Description
Inputs -
Outputs -
Exceptions COMMAND_FAILED - The exception is raised if the given target pose is not valid or an unspecified internal error happened during the process.
COMMUNICATION_ERROR - The exception is raised if the movement failed, because the communication to the robot was interrupted.
POSE_NOT_REACHABLE - The exception is raised if the movement failed, because the pose can not reached by the robot.
SAFETY_STOP - The exception is raised if the movement failed, because the safety system was triggered, usually by pressing the emergency stop button.
ROBOT_NOT_READY - The exception is raised if the movement failed, because the controller reported that the robot was no ready to move.
COMMAND_ERROR - The exception is raised if the movement failed for an unknown reason.

Simulation (Attaching and Detaching)

Object Simulation - Attach

Attaches movable objects to a given frame, if they are in range.

Name Data type Description
Inputs Frame String The frame to attach the objects to. All objects closer than their attach range are attached to this frame.
Snap Object Boolean True: Objects attached to the gripper are snapped to the tool center point. This means each offset transformation from the attaching frame to the respective object becomes zero.
False: Attached objects keep their relative transformations to the attaching frame.
Outputs -

Object Simulation - Attach by ID

Attaches all stated movable objects to a given frame, ignoring their individual attach range.

Name Data type Description
Inputs Frame String The frame to attach the objects to.
Object List List of Strings List of Object IDs, which are going to be attached to the given frame.
Outputs -

Object Simulation - Detach

Detaches all movable objects from a given frame.

Name Data type Description
Inputs Frame String The frame to detach all the attached objects from.
Outputs -

Object Simulation - Get Attached Object ID

Returns the Object ID of the first object attached to a given frame.

Name Data type Description
Inputs Frame String The frame to check for attached objects.
Outputs Found Object Boolean True, if at least one object is attached to the given frame. False otherwise.
Object ID String The Object ID of the first object attached to the frame. Empty string if no object is attached.

Object Simulation - Reattach All

Attaches all objects currently attached to one source frame to a different target frame.

Name Data type Description
Inputs Source Frame String The frame to detach all the attached objects from.
Target Frame String The frame to attach all the detached objects from the source frame.
Outputs -

Simulation (Manipulation of Objects Poses)

Object Simulation - Get Object Pose

Returns the pose of an object in world coordinate system.

Name Data type Description
Inputs Object ID String The Object ID of the object to get the pose for.
Outputs Pose Pose The pose of this object in world coordinate system.
Exceptions ERROR_ID_NOT_FOUND - The exception is raised if the given Object ID is not known.

Object Simulation - Move Object

Places a given object at a given pose relative to its parent frame.

Name Data type Description
Inputs Object ID String The Object ID of the object to set the pose.
Pose Pose The new pose of the object relative to its parent frame.
Outputs -
Exceptions ERROR_UNKNOWN_OBJECT - The exception is raised if the given Object ID is not known.

Object Simulation - Set Object Frame

Changes the parent frame of a given object.

Name Data type Description
Inputs Object ID String The Object ID of the object to change the parent frame.
Frame String The new parent frame of the object.
Keep World Transform Boolean True: The pose of the object in its parent frame is recalculated such that the absolute pose in world coordinate system does not change. False: The pose is not recalculated. In this case the object might jump as the pose stays constant while the parent frame changes.
Outputs -
Exceptions ERROR_UNKNOWN_OBJECT - The exception is raised if the given Object ID is not known.
ERROR_RECALCULATING_TRANSFORMATION - The exception is raised if the recalculation could not be performed, usually because the original frame has no connection to the new frame in the frame tree.

Object Simulation - Shift Object

Moves a given object relative to its current pose within its parent frame.

Name Data type Description
Inputs Object ID String The Object ID of the object to set the pose.
Pose Pose The pose of the object relative to its current pose within its parent frame.
Outputs -
Exceptions ERROR_UNKNOWN_OBJECT - The exception is raised if the given Object ID is not known.

Simulator Objects - Shift

Deprecated

This function block is deprecated and should not be used any more. Instead use the Object Simulation - Shift Object function block described above.

Moves a list of given objects relative to its current pose within its parent frame.

Name Data type Description
Inputs List of Object IDs List of Strings The Object ID of the object to set the pose.
Pose Pose The pose of the object relative to its current pose within its parent frame.
Outputs Success Boolean True if shifting all objects was successful. False otherwise

Simulation (Defining, Spawning and Despawning Objects)

All simulated objects created with drag&bot are defined in to steps: The first step is the model, which contains all the visual aspects of the object. The second step is the positional part, which is the pose and the parent frame of the object. By separating the model part from the object part it is possible to use the same model for several objects.

Models and objects created by function blocks are considered to be temporary. They are not saved in the scenario and are not listed in the Scenario Designer. In opposite to persistent objects they are deleted when the scenario is resetted by the function block or when the reset button in the 3D visualization is used.

Object Simulation - Define Basic Shape Model

Defines (creates or updates) a model for basic shapes, which can be used to spawn objects. Models created by functions blocks are not saved in the scenario.

Name Data type Description
Inputs Model ID String The ID of the new model.
Shape Select The shape of the new model. Available are: Cube, Cylinder Sphere
Size Float The size of the model in meters for each axis.
Color RGB Integer The color of the object for red, green and blue channel. Each value ranges from 0 to 255.
Moveable Boolean True: Specifies whether an object of this model can be moved or gripped. The attach range defines a sphere around the object frame in which the object can be gripped.
Attach Range Float The attach range defines a sphere around the object in which the object can be gripped.
Outputs -
Exceptions ERROR_INVALID_ID - The exception is raised if the given Model ID is invalid. The name must not be empty and must not contain spaces.

Object Simulation - Define CAD Shape Model

Defines (creates or updates) a model for a mesh shape, which can be used to spawn objects. Models created by functions blocks are not saved in the scenario.

Name Data type Description
Inputs Model ID String The ID of the new model.
Mesh File String The mesh file of the model located inside ~/.dnb/data/meshes, e.g. parts/part1.dae
Scale Factor Float The scale factor to scale the mesh.
Moveable Boolean True: Specifies whether an object of this model can be moved or gripped. The attach range defines a sphere around the object frame in which the object can be gripped.
Attach Range Float The attach range defines a sphere around the object in which the object can be gripped.
Outputs -
Exceptions ERROR_INVALID_ID - The exception is raised if the given Model ID is invalid. The name must not be empty and must not contain spaces.

Object Simulation - Hide/Show Object

Hides or shows an existing object.

Name Data type Description
Inputs Object ID String The Object ID of the object to hide or show.
Hide String True: The object is hided. False: The object is shown.
Outputs -
Exceptions ERROR_ID_NOT_FOUND - The exception is raised if the given Object ID is not found.

Object Simulation - Despawn Object

Removes an existing object from the scene.

Name Data type Description
Inputs Object ID String The Object ID of the object to despawn.
Outputs -
Exceptions ERROR_ID_NOT_FOUND - The exception is raised if the given Object ID is not found.

Object Simulation - Set Object Model

Changes the model of an existing object.

Name Data type Description
Inputs Object ID String The Object ID of the object to change the model.
Model ID String The new Model ID for the object.
Outputs -
Exceptions ERROR_ID_NOT_FOUND - The exception is raised if the given Object ID is not found.
ERROR_INVALID_MODEL - The exception is raised if the given Model ID is not found.

Object Simulation - Spawn Object

Creates a new object defined by a model and adds is to the scene at a specified pose. Objects spawned by functions blocks are not saved in the scenario.

Name Data type Description
Inputs Model ID String The used Model ID for the new object.
Parent Frame String The parent frame of the object.
Pose Pose The pose of the object within its parent frame.
Outputs Object ID String The autogenerated Object ID for the spawned object.
Exceptions ERROR_INVALID_MODEL - The exception is raised if the given Model ID is not found.

Simulation (Scenario)

Scenario - Reset and Reload

Resets the simulated robot to the initial joints and reloads the complete scenario.

Name Data type Description
Inputs -
Outputs -

Scenario - Reset Objects

Resets all movable objects to their initial state in the scenario. Deletes all temporary objects.

Name Data type Description
Inputs -
Outputs -

Vision

Vision - Localize Pattern 2D

Localizes the center of a given template image inside the current camera image. It is possible to define a region of interest (ROI) within the camera image to search for the object. The pixel positions U and V and the localized pose in world coordinates are returned. The function block uses homography based on the points obtained from SIFT algorithm.

Name Data type Description
Inputs Template Image String Template image of the object to be localized. The file needs to be placed in the directory ~/.dnb/data/vision/. Several files can be stated comma-separated.
ROI: X1 Integer X value of top left corner of the ROI in pixels.
ROI: Y1 Integer Y value of top left corner of the ROI in pixels.
ROI: X2 Integer X value of bottom right corner of the ROI in pixels. A value of -1 takes the image width.
ROI: Y2 Integer Y value of bottom right corner of the ROI in pixels. A value of -1 takes the image height.
Result: Minimum Match Points Integer Minimum number of matching points to return a success.
Result: Ignore Orientation Boolean True: The orientation of the detected pattern is ignored.
ROS Camera Topic String The name of the camera image stream.
Extrinsic Calibration Name String The name of the calibration file e.g. 'default'
Image Encoding String Encoding of the camera image.
Outputs Pixel U Integer Pixel coordinate U in the image of the camera topic.
Pixel V Integer Pixel coordinate V in the image of the camera topic.
Localized Position Pose World pose of the localized object.
Success Boolean True if detection was successful. False otherwise.
Image Found String The filename of the image for the case several template images have been configured.
Exceptions CALIBRATION_EXCEPTION - The exception is raised, if the Vision Module Component is not started or the calibration saved there is not valid.
TEMPLATE_FILE_NOT_FOUND - The exception is raised, if the template image file can not be found.
SCENE_ERROR - The exception is raised, if the observed scene could not be processed.

Vision - Save Camera Image

Saves the current camera image as JPEG file.

Name Data type Description
Inputs Camera Image Topic String The name of a ROS image stream topic.
Filename String The name of the filename. The file can be found later in the directory ~/.dnb/data/vision/images_saved/
File Format Select Format of the saved image file. Available are: jpeg, png
Outputs -

Vision - Localize Rectangle 2D

Localizes the center if a given rectangle inside the current camera image. It is possible to define a region of interest (ROI) within the camera image to search for the rectangle. The pixel positions U and V and the localized pose in world coordinates are returned.

Name Data type Description
Inputs Filter: Rectangle Length Integer Length of longer side of rectangle in mm.
Filter: Rectangle Width Integer Length of shorter side of rectangle in mm.
Filter: Lenghts Tolerance Integer Tolerance of rectangle length and width in ±mm.
Vision: Bright Background Boolean True: bright background; False: dark background
Vision: Gaussian Blur Kernel Size Integer Kernel size in pixels. The kernel size needs to be positive and odd.
Vision: Binary Threshold Integer Threshold within [0..255].
ROI: X1 Integer X value of top left corner of the ROI in pixels.
ROI: Y1 Integer Y value of top left corner of the ROI in pixels.
ROI: X2 Integer X value of bottom right corner of the ROI in pixels. A value of -1 takes the image width.
ROI: Y2 Integer Y value of bottom right corner of the ROI in pixels. A value of -1 takes the image height.
Result: Orientation Alignment Boolean Should orientation/angle be parallel to long edge? true: yes; false: no/short edge
Result: Favorite Angle Integer Close to which angle in degree the returned orientation should be.
ROS Camera Topic String The name of the camera image stream.
Extrinsic Calibration Name String The name of the calibration file e.g. 'default'
Image Encoding String Encoding of the camera image.
Outputs Pixel U Integer Coordinate U in pixels in the image of the camera topic.
Pixel V Integer Coordinate V in pixels in the image of the camera topic.
Localized Position Pose World pose of the localized rectangle.
Success Boolean True if detection was successful. False otherwise.
Exceptions CALIBRATION_EXCEPTION - The exception is raised, if the Vision Module Component is not started or the calibration saved there is not valid.

Vision - QR Code Reader

Localizes and decodes the barcodes (EAN-13/UPC-A, UPC-E, EAN-8, Code 128, Code 39, Interleaved 2 of 5) and QR Codes. It is possible to define a region of interest (ROI) within the camera image to search for the code. The pixel positions U and V and the localized pose in world coordinates are returned.

Name Data type Description
Inputs ROI: X1 Integer X value of top left corner of the ROI in pixels.
ROI: Y1 Integer Y value of top left corner of the ROI in pixels.
ROI: X2 Integer X value of bottom right corner of the ROI in pixels. A value of -1 takes the image width.
ROI: Y2 Integer Y value of bottom right corner of the ROI in pixels. A value of -1 takes the image height.
ROS Camera Topic String The name of the camera image stream.
Extrinsic Calibration Name String The name of the calibration file e.g. 'default'
Image Encoding String Encoding of the camera image.
Outputs Pixel U Integer Coordinate U in pixels in the image of the camera topic.
Pixel V Integer Coordinate V in pixels in the image of the camera topic.
Localized Position Pose World pose of the localized rectangle.
Success Boolean True if detection was successful. False otherwise.
Decoded Text String The text contained in the recognized barcode or QR Code.
Code Type String Type of the recognized code.
Exceptions CALIBRATION_EXCEPTION - The exception is raised, if the Vision Module Component is not started or the calibration saved there is not valid.

Visualization

Markers - Show Pose

Shows a coordinate cross at a specified pose with standard coloring with red for x-axis, green for y-axis and blue for z-axis.

Name Data type Description
Inputs ID String Unique ID to identify the marker among all other markers.
Pose Pose The pose the marker shall be shown for.
Outputs -

Markers - Show Box - Absolute

Shows a simple box by stating the box faces in absolute coordinates.

Name Data type Description
Inputs ID String Unique ID to identify the marker among all other markers.
X min float Position of the box face facing towards the negative x axis of the world coordinate system in meters.
X max float Position of the box face facing towards the positive x axis of the world coordinate system in meters.
Y min float Position of the box face facing towards the negative y axis of the world coordinate system in meters.
Y max float Position of the box face facing towards the positive y axis of the world coordinate system in meters.
Z min float Position of the box face facing towards the negative z axis of the world coordinate system in meters.
Z max float Position of the box face facing towards the positive z axis of the world coordinate system in meters.
Color: Red int Red part of the box color in range 0 to 255.
Color: Green int Green part of the box color in range 0 to 255.
Color: Blue int Blue part of the box color in range 0 to 255.
Color: Alpha float Alpha part of the box color in range 0 to 1. A value of 0 indicates full transparency, while a value of 1 indicates full opaqueness.
Outputs -

Markers - Show Box - Relative

Shows a simple box marker by stating an offset point and the box faces relative to it.

Name Data type Description
Inputs ID String Unique ID to identify the marker among all other markers.
Simple Box Box Position Offset: X float Offset of the box in x axis of the world coordinate system in meters.
Simple Box Box Position Offset: Y float Offset of the box in y axis of the world coordinate system in meters.
Simple Box Box Position Offset: Z float Offset of the box in z axis of the world coordinate system in meters.
Box Dimension Negative Direction: X float Position of the box face relative to the offset facing towards the negative x axis of the world coordinate system in meters.
Box Dimension Negative Direction: Y float Position of the box face relative to the offset facing towards the negative y axis of the world coordinate system in meters.
Box Dimension Negative Direction: Z float Position of the box face relative to the offset facing towards the negative z axis of the world coordinate system in meters.
Box Dimension Positive Direction: X float Position of the box face relative to the offset facing towards the positive x axis of the world coordinate system in meters.
Box Dimension Positive Direction: Y float Position of the box face relative to the offset facing towards the positive y axis of the world coordinate system in meters.
Box Dimension Positive Direction: Z float Position of the box face relative to the offset facing towards the positive z axis of the world coordinate system in meters.
Color: Red int Red part of the box color in range 0 to 255.
Color: Green int Green part of the box color in range 0 to 255.
Color: Blue int Blue part of the box color in range 0 to 255.
Color: Alpha float Alpha part of the box color in range 0 to 1. A value of 0 indicates full transparency, while a value of 1 indicates full opaqueness.
Outputs -

Markers - Delete Marker

Removes a previously created marker.

Name Data type Description
Inputs ID String Unique ID to identify the marker to delete.
Marker Type String Select the type of the marker to delete. If not matching to the marker id the marker might not be deleted correctly.
Outputs -

Advanced

Palletizing Position Producer

To create palletizing applications with drag&bot it is recommended to open the Palletizing Guide. The guide will lead you through each step necessary and will create a final program after finish. Advanced users can also create a program from scratch by using the Palletizing Position Producer function block directly in a new program.

Three point wizard plane

The palletizing position producer block produces two trajectories each time it is called. The trajectories consists of approach and retreat trajectories. The producer function block is moving through the pallet in a specified strategy starting in the Start position. The pallet plane is defined with three positions which calculate a start pose called Grid Frame. For all three positions the robot has to be placed in the same way in the respective cell, be it corner, center or any other relative position to the cell.

Recommended TCP: Use flange for teach-in

For simple use cases it is recommended to use the flange for the teach in of the Palletizing Position Producer function block. Using very large TCP transformations can lead to an inaccuracy of measurement. In this case it is hard to use the calculated Grid Frame as measurement errors have a high impact.

Name Datatype Description
Inputs Start position Position The column, row and layer numbers where to start when first entering the palletizing position producer. The Grid Store Load and Grid Store Save function block can be used to save and load this position from the datastore.
Grid Type Select Select between regular and hexagonal pallet types. A hexagonal pallet has each second row or column shifted by the half length of a cell.
Overhang Select The direction of the shift for hexagonal pallet types where a element should overhang after shifting it. Select between left and right.
Shift Select In which axis should the shift occur. Select between row and column.
Gird Frame Pose The Grid Frame defines the root of the palletizing position producer. The Grid Frame is a transformation and it is calculated out of 3 positions defined by the TCP of the robot. (See more in the later subsection "What is the Grid Frame?")
Grid Dimension Composed Define the length of column and row of the of the grid. Additionally when having multiple layers, the layer count and height can be set. Layer height can also be negative.
Grid trajectory assignment Matrix Define the dimension of the matrix by defining the number of cells. Moreover the Approach and Retreat group can be set by using the string of the trajectory defined in Trajectory Groups. (See more in the later subsection "How are the trajectories used?")
Trajectory Groups Trajectory[] A list of trajectories. Used for approaching and retreating the pick position or place position of the grid.
Pattern Settings > Pattern Type Select Choose the strategy for moving through the pallet. Select between col-first, row-first, col-first-snake, row-first-snake and individual. When choosing individual the Individual Pattern is considered as the order of the grid strategy.
Pattern Settings > Pattern Type Cell[] Choose the order of the cells consistent of row and column to iterate through the grid.

What is the Grid Frame?

Three point wizard plane

The Grid Frame is a transformation and it is calculated out of 3 positions defined by the TCP of the robot. It is used to define a start position of the first part in the pallet. The Grid Frame can be reteached by using the Three Point Wizard.

The Column Length and the Row Length is calculated and filled when using the Palletizing Guide of drag&bot. By reteaching the Grid Frame with the Three Point Wizard the Column Length and Row Length is not updated. The point 2 in the above picture is the default start corner of the palletizing application.

How are the trajectories used?

PPP Trajectories

The palletizing position producer produces an approach and a retreat trajectory on every call of the block e.g. by going through a loop. Usually starting at the Start position (Column 1, Row 1, Layer 1). Every cell of the matrix saves the related trajectory as a string in the matrix field. The string which is saved in a cell of the matrix must be available in the Trajectory Groups list. The default of the trajectory names is A and B.

PPP Trajectory Groups

Every trajectory usually consists of two waypoints. It consists of an approach and a final pick position waypoint. The order of the retreat trajectory B is the reversed order of trajectory A by default. It is possible to add more waypoints to the trajectory for a more complex path to pickup or retreat.

The poses of each trajectory inside the palletizing position producer are saved relatively to the Grid Frame. The Grid Frame is used as a reference coordinate system for the poses of all waypoints. This has the advantage when changing the pose of the Grid Frame, e.g. because the pallet is move, it will change the whole application pose. For the palletizing block it is necessary to set the Teached Grid Cell coordinate inside the trajectory, so the block is able to calculate all other grids of the pallet and its approach or retreat trajectory.

What are pattern settings?

PPP Trajectory Groups

In the palletizing position producer a strategy can be chosen on how to iterate through the grid. Select between col-first, row-first, col-first-snake, row-first-snake and individual. When choosing individual the Individual Pattern is considered as the order of the grid strategy. There are multiple cells in the Pattern which hold coordinates of Column and Row.

Grid Function Blocks

The Grid function blocks are an alternative to the Palletizing Position Producer function block, which they extend by the ability to keep track of contents of each cell in the grid. The following figure shows how a simple pickup application is usually structured.

graph LR start(("Start")) init["Initialize Grid(s)"] reset["Reset Grid(s)"] next_cell["Get Next Cell (Raw Parts)<br>Changes to 'Empty Cell'"] found{"Found Cell<br>with Content?"} finished(("End")) approach["Approach<br>Trajectory"] pickup["Part Pickup"] retreat["Retreat<br>Trajectory"] start --> init init --> reset reset --> next_cell next_cell --> found found -->|No| finished found -->|Yes| approach approach --> pickup pickup --> retreat retreat --> next_cell style reset stroke-dasharray: 5 5 style pickup stroke-dasharray: 5 5

Grid - Initialize

Creates a grid with the given settings. The input parameters follow the structure of the Palletizing Position Producer function block described above. In opposite to the Palletizing Position Producer function block the grid is not defined by the size of the entire grid, but by the deltas between two cells. This makes it easier to resize the grid later, if necessary. Additionally a grid_id has to be stated to identify the grid later. If not already existing, the function block creates a parameter grid_id/content on the datastore, where later the contents of the grid will be saved persistently. Be aware that only the content of the grid is saved persistently across restarts of the robot system, not the definition of the grid.

Name Datatype Description
Inputs Start position Position The column, row and layer numbers where to start when searching the grid for a specified content.
Grid Type Select Select between regular and hexagonal pallet types. A hexagonal pallet has each second row or column shifted by the half length of a cell.
Overhang Select The direction of the shift for hexagonal pallet types where a element should overhang after shifting it. Select between left and right.
Shift Select In which axis should the shift occur. Select between row and column.
Gird Frame Pose The Grid Frame defines the root of the palletizing position producer. The Grid Frame is a transformation and it is calculated out of 3 positions defined by the TCP of the robot. (See more in the subsection above "What is the Grid Frame?")
Grid Dimension Composed Define the delta length between two cells in column and row direction of the grid. Additionally when having multiple layers, the layer count and height can be set. Layer height can also be negative.
Grid trajectory assignment Matrix Define the dimension of the matrix by defining the number of cells. Moreover the Approach and Retreat group can be set by using the string of the trajectory defined in Trajectory Groups. (See more in the subsection above "How are the trajectories used?")
Trajectory Groups Trajectory[] A list of trajectories. Used for approaching and retreating the pick position or place position of the grid.
Pattern Settings > Pattern Type Select Choose the strategy for moving through the pallet. Select between col-first, row-first, col-first-snake, row-first-snake and individual. When choosing individual the Individual Pattern is considered as the order of the grid strategy.
Pattern Settings > Pattern Type Cell[] Choose the order of the cells consistent of row and column to iterate through the grid.
Grid ID String ID which identifies the grid among all registered grids. Using the same grid id on multiple grids will overwrite the first grid.
Outputs -
Exceptions INVALID_DATASTORE_VALUE_FOR_GRID_ID - The exception is raised if the grid settings do not match to the datastore entry already existing for this Grid ID.
INVALID_TRAJECTORY_GROUP - The exception is raised if settings of the trajectory group are invalid.
INVALID_APPROACH_GROUP_MATRIX - The exception is raised if a stated approach group is no registered trajectory group.
INVALID_RETREAT_GROUP_MATRIX - The exception is raised if a stated retreat group is no registered trajectory group.
INVALID_INDIVIDUAL_PATTERN - The exception is raised if a stated individual pattern cell is not valid.
INVALID_START_CELL - The exception is raised if the configured start cell is invalid.
INVALID_GRID_DEFINITION - The exception is raised if defining the grid failed for an unknown reason.
MODULE_NOT_AVAILABLE - The exception is raised if the grid manager module is not available. Probably you use the new function blocks with an older version of drag&bot.

Grid - Reset

Resets the contents of all cells of a specified grid to a given content.

Name Datatype Description
Inputs Grid ID String ID of the grid, which has to be resetted.
Change Content To Select Content of the cell, where each cell of the grid is changed to. Available are: Raw Part, Processed Part, OK Part, NOK Part, Empty Cell and Deactivated Cell.
Layer Integer A value of 0 sets the entire grid. Other values do just set the respective layer.
Outputs -
Exceptions INVALID_GRID_ID - The exception is raised if the stated grid id can not be found among the registered grids.
INVALID_LAYER - The exception is raised if the stated layer id can not be found in the configured grid.
MODULE_NOT_AVAILABLE - The exception is raised if the grid manager module is not available. Probably you use the new function blocks with an older version of drag&bot.

Grid - Get Next Cell

Searches a given list of grids for a specified content. Afterwards it can change the content of this cell, if requested. If a cell was found, the function block returns the approach and retreat trajectory for this cell, the last pose of the approach trajectory, the grid_id and the position of the cell in the grid.

Name Datatype Description
Inputs Cell Content Select Content of the cell, which is searched for. Available are: Raw Part, Processed Part, OK Part, NOK Part, Empty Cell or any filled cell
Grid IDs String[] IDs of grids, which shall be searched for the specified content.
Change Content To Select Content of the cell, where the found cell is changed to. Available are: Raw Part, Processed Part, OK Part, NOK Part, Empty Cell and let the content of the cell unchanged.
Outputs Found Cell Boolean True if a cell was found for the specified content. False otherwise.
Grid ID String ID of the grid, where the content was found.
Cell Position Position Position of the found cell in the grid. This can be used to do further operations on the cell, like changing the content manually.
Approach Trajectory Trajectory Trajectory to move to the found cell.
Retreat Trajectory Trajectory Trajectory to retreat from the found cell.
Final Pose Pose Target pose of the cell (last pose of the approach trajectory), as an alternative to the trajectories.
Exceptions INVALID_DATASTORE_VALUE_FOR_GRID_ID - The exception is raised if contents of the found grid is not consistent with the respective data on the datastore. This can usually happen if the definition of the grid changes while the content is not adjusted respectively.
MODULE_NOT_AVAILABLE - The exception is raised if the grid manager module is not available. Probably you use the new function blocks with an older version of drag&bot.

Grid - Set Cell Content

Sets the content of a specified cell in a grid to a given content.

Name Datatype Description
Inputs Grid ID String ID of the grid, where the cell has to be set.
Cell Position Position Position of the cell in the grid, which has to be set.
Change Content To Select Content of the cell, where each cell of the grid is changed to. Available are: Raw Part, Processed Part, OK Part, NOK Part, Empty Cell and Deactivated Cell.
Outputs -
Exceptions INVALID_GRID_ID - The exception is raised if the stated grid id can not be found among the registered grids.
INVALID_CELL - The exception INVALID_CELL is raised if the stated cell can not be found in the given grid.
INVALID_DATASTORE_VALUE_FOR_GRID_ID - The exception is raised if contents of the found grid is not consistent with the respective data on the datastore. This can usually happen if the definition of the grid changes while the content is not adjusted respectively.
MODULE_NOT_AVAILABLE - The exception is raised if the grid manager module is not available. Probably you use the new function blocks with an older version of drag&bot.

Grid - Get Cell Trajectories

Returns the trajectories and the final pose of a specified cell in a grid.

Name Datatype Description
Inputs Grid ID String ID of the grid, where the cell has to be searched.
Cell Position Position Position of the cell in the grid.
Outputs Approach Trajectory Trajectory Trajectory to move to the specified cell.
Retreat Trajectory Trajectory Trajectory to retreat from the specified cell.
Final Pose Pose Target pose of the cell (last pose of the approach trajectory), as an alternative to the trajectories.
Exceptions INVALID_GRID_ID - The exception is raised if the stated grid id can not be found among the registered grids.
INVALID_CELL - The exception INVALID_CELL is raised if the stated cell can not be found in the given grid.
MODULE_NOT_AVAILABLE - The exception is raised if the grid manager module is not available. Probably you use the new function blocks with an older version of drag&bot.