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

Raise 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 -

User Dialog

Create 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

Display 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

Wait 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

Apply 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

Compare two boolean values.

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

Compare - Float

Compare two float values.

Name Data type Description
Inputs Operand 1 Float The first operand of the comparison.
Condition - Select one of the comparisons.
Operand 2 Float The second operand of the comparison.
Outputs Result Boolean The result of the comparison.

Compare - Integer

Compare two integer values.

Name Data type Description
Inputs Operand 1 Integer The first operand of the comparison.
Condition - Select one of the comparisons.
Operand 2 Integer The second operand of the comparison.
Outputs Result Boolean The result of the comparison.

Compare - String

Compare two string values.

Name Data type Description
Inputs Operand 1 String The first operand of the comparison.
Condition - Select one of the comparisons.
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 the internal counter is raised by one. Place the Counter 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

Execute 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

Repeat 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

Invert a boolean value.

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

Or

Apply 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

Execute 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 branch which shall be executed.
Outputs -

Switch Case - Match String

Execute 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 is its linked branch executed. If multiple 'Match Strings' are matching the input string then is only the first linked branch executed.

Name Data type Description
Inputs String Match Input String This string input is compaired 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 the input string to execute the branch noted in the case.
Select Branch Integer Index of 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.

Datastore - Delete All Items

Delete all datastore items. The datastore is permanently deleted on the robot system.

Name Data type Description
Inputs -
Outputs -

Datastore - Delete Item

Delete a datastore item. The datastore item is permanently deleted on the robot system.

Name Data type Description
Inputs ID String The identifier of a datastore item.
Outputs -

Datastore - Delete Namespace

Delete all items of a datastore namespace. Namespaces are defined as the namespaces name before an items identifier, separated by a slash, e.g. 'ns/id'. The datastore namespace is permanently deleted on the robot system.

Name Data type Description
Inputs Namespace String The name of a datastore namespace whose members shall be deleted.
Outputs -

Datastore - Display All Items

Display all items of the datastore in the ROS log.

Name Data type Description
Inputs -
Outputs -

Datastore - Get Value - Integer

Get the integer value of a datastore item.

Name Data type Description
Inputs ID String The identifier of the datastore item.
Outputs Value Integer The integer value of the datastore item.

Datastore - Get Value - String

Get the string value of a datastore item.

Name Data type Description
Inputs ID String The identifier of the datastore item.
Outputs Value String The string value of the datastore item.

Datastore - Get Value - Boolean

Get the boolean value of a datastore item.

Name Data type Description
Inputs ID String The identifier of the datastore item.
Outputs Value Boolean The boolean value of the datastore item.

Datastore - Get Value - Float

Get the float value of a datastore item.

Name Data type Description
Inputs ID String The identifier of the datastore item.
Outputs Value Float The float value of the datastore item.

Datastore - Get Value - Pose

Get the pose of a datastore item.

Name Data type Description
Inputs ID String The identifier of the datastore item.
Outputs Value Pose The pose of the datastore item.
Exceptions INVALID_POSE - The exception is raised, if the entry is not a valid pose format.

Datastore - Get Value - Joints

Get the 6 axes joints of a datastore item.

Name Data type Description
Inputs ID String The identifier of the datastore item.
Outputs Value Joints The joints value of the datastore item.
Exceptions INVALID_JOINTS - The exception is raised, if the entry is not a valid joints format for 6 axes.

Datastore - Set Value - Integer

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

Name Data type Description
Inputs ID String The identifier of the datastore item.
Value Integer The new integer value of the datastore item.
Outputs -

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 ID String The identifier of the datastore item.
Value String The new string value of the datastore item.
Outputs -

Datastore - Set Value - Boolean

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

Name Data type Description
Inputs ID String The identifier of the datastore item.
Value Boolean The new boolean value of the datastore item.
Outputs -

Datastore - Set Value - Float

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

Name Data type Description
Inputs ID String The identifier of the datastore item.
Value Float The new float value of the datastore item.
Outputs -

Datastore - Set Value - Pose

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

Name Data type Description
Inputs ID String The identifier of the datastore item.
Value Pose The new pose value of the datastore item.
Outputs -

Datastore - Set Value - Joints

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

Name Data type Description
Inputs ID String The identifier of the datastore item.
Value Joints The new joints value with 6 axes of the datastore item.
Outputs -

Datastore - Set Type

Set the type of an existing datastore item.

Name Data type Description
Inputs ID String The identifier of the datastore item.
Type - The new type of the datastore item. Possible values are string, int, float and bool.
Outputs -

Datastore - Set Display Title

Set the display title of an existing datastore item.

Name Data type Description
Inputs ID String The identifier of the datastore item.
Display Title String The new display title of the datastore item.
Outputs -

Datastore - Counter

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

Name Data type Description
Inputs ID String The identifier of the datastore item.
Increment Integer The increment to increase the datastore item number.
Outputs Integer The incremented resulting value.

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.

Close a gripper controlled with two digital IOs. 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.

Control a gripper controlled with two digital IOs. 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.

Open a gripper controlled with two digital IOs. 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

Basic Logic

Perform 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 - The chosen logic operation.
Operand 2 Boolean The second operand of the operation.
Outputs Result Boolean The result of the operation.

Basic Math - Float

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

Name Data type Description
Inputs Operand 1 Float The first operand of the operation.
Operation - The chosen arithmetic operation.
Operand 2 Float The second operand of the operation.
Outputs Result Float The result of the operation.

Basic Math - Integer

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

Name Data type Description
Inputs Operand 1 Integer The first operand of the operation.
Operation - The chosen arithmetic operation.
Operand 2 Integer The second operand of the operation.
Outputs Result Integer The result of the operation.

Cast - Boolean

Cast 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.

Cast - Float

Cast 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.

Cast - Integer

Cast 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.

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.

To String - Boolean

Convert a boolean to string.

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

To String - Float

Convert 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.

To String - Integer

Convert 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.

Get Transformation

Calculate the transformation between two given poses.

Name Data type Description
Inputs Pose 1 Pose The first pose.
Pose 2 Pose The second pose.
Outputs Result Pose Pose The calculated transformation pose.

Pose Transformation

Transform an offset to a given pose.

Name Data type Description
Inputs Origin Pose Pose The origin pose.
Offset Pose Pose The offset pose.
Outputs Result Pose Pose The calculated transformation pose.

Joints Transformation

Add an offset to a given joint state.

Name Data type Description
Inputs Origin Joints The original joint states.
Offset Joints The offset joint states.
Outputs Result Joints The resulting joint states.

Robot

Change Robot TCP

Enter the name of a tool from the tool manager to switch to this tool.

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.
Outputs -

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.

Request 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.

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.

Set 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 -

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.

Pause 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 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 -

Digital I/O Device - Get

Request 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

Set 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

Pause 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.

Compare - Joints

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

Name Data type Description
Inputs
Joints 1 Joints Angles of the first joint states in degrees.
Joints 2 Joints Angles of the second joint states 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

Compare 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.

Get Flange Pose

Request the pose of the robot flange.

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

Get TCP Pose

Request the pose of the currently selected TCP.

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

Get Joint States

Request 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

Move 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 -

Move Cartesian Relative

Move the robot relative to the current position by entering a delta pose relative to the current position. It depends on the tool frame coordinate system and not on the bases.

Name Data type Description
Inputs Pose Delta Pose Relative change between points.
Speed Float Movement speed of robot in m/s.
Acceleration Float Acceleration of robot in m/s² or percent of maximum acceleration.(Percent: 0-100)
Add to Waypoint Queue Boolean When enabled the waypoint of the function block is buffered into the Waypoint Queue instead of being executed at once. The function block returns immediately. See Waypoint Queue for more information.
Outputs -

Move Joints

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

Name Data type Description
Inputs Joints Joints Angles of the goal joint state in degrees.
Speed Float Robot speed in deg/s or percent of maximum speed (Percent: 0-100).
Acceleration Float Acceleration of the robot in percent of maximum acceleration (Percent: 0-100).
Blending Float 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 -

Move Joints - 7 Axes

Move 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 joint robots.

Name Data type Description
Inputs Joints Joints Angles of the goal joint state in degrees.
Speed Float Robot speed in deg/s or percent of maximum speed (Percent: 0-100).
Acceleration Float Acceleration of the robot in percent of maximum acceleration (Percent: 0-100).
Blending Float 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 -

Waypoint Queue - Move

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

Name Data type Description
Inputs -
Outputs -

Waypoint Queue - Clear

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

Name Data type Description
Inputs -
Outputs -

Pose Checker - Box - Absolute Faces

Checks, whether a given position is inside a defined simple box. The faces of the simple box are 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 test.
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 Faces

Checks, whether a given position is inside a defined simple box. The faces of the simple box are 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 test.
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.

Vision

Vision - Localize Pattern 2D

Localize 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/.
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: 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.

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 in JPEG format. The file can be found later in the directory ~/.dnb/data/vision/images_saved/
Outputs -

Vision - Localize Rectangle 2D

Localize 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 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.

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

The function block 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 registred grids. Using the same grid id on multiple grids will overwrite the first grid.
Outputs -
Exceptions INVALID_GRID_CONTENT_DATA - 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.
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

The function block 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 and Empty Cell
Outputs -
Exceptions INVALID_GRID_ID - The exception is raised if the stated grid id can not be found among the registered grids.
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

The function block 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, 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, 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_GRID_CONTENT_DATA - 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

The function block 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 and Empty 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_GRID_CONTENT_DATA - 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

The function block 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.

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 Faces

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 Faces

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 -