Rally URCap User manual

Pally URCap
User Manual
Version 2.9.1

Table of Contents
1 - Document Revision Information 6
2 - License 7
3 - Requirements 8
3.1 - Software Requirements 8
3.2 - Hardware Requirements 8
3.2.1 - Supported external hardware 8
3.3 - Compatibility notes 8
3.3.1 - Compatibility notes for version 2.6 and above 9
3.3.1.1 - Path planning 9
3.3.1.2 - ProductCount 9
3.3.2 - Compatibility notes for version 2.7.1 and above 9
3.3.2.1 - Pallet confirmation variables 9
3.3.3 - Compatibility notes for version 2.8 and above 9
3.3.3.1 - Execution of beforeZone and afterZone callbacks 9
3.3.3.2 - Execution of beforeGrab callback 9
3.3.3.3 - Waiting time at pickup and release positions 10
3.3.4 - Compatibility notes for version 2.9 and above 10
3.3.4.1 - URCap API 1.12 10
3.3.4.2 - Definition of multi-zone grippers (gripper.json) 10
3.3.4.3 - Multi-pick fewer boxes 10
3.3.4.4 - Optional posData in zones.json 10
3.3.4.5 - New callback onNextTask 10
3.4 - Compatibility with CB 3.0 robots 11
3.4.1 - Memory usage limitations on CB 3.0 11
3.4.2 - Computational limitations on CB 3.0 11
4 - Functional description 12
4.1 - The palletizer workflow 12
4.2 - Pallet patterns 12
4.3 - Pallet completion state 13
4.4 - Pickup position 13
4.4.1 - Single pick and multi-pick 14
4.4.2 - Gripper alignment at the pickup position - offset grip 14
4.4.3 - Gripper rotation at the pickup position - gripper optimization 15
4.4.4 - Grip quality value - smart acceleration 15
4.5 - Path planning 16
4.5.1 - The path planning algorithm 16
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
2

4.5.2 - Approaching the target position 18
4.5.3 - Pallet lip 20
4.5.4 - Return path 20
4.5.5 - User-defined path 20
4.6 - Shim papers 20
4.7 - Lifting column 20
4.7.1 - Positioning the lifting column for each layer 21
4.7.2 - Positioning the lifting column for each box - dynamic positioning 21
4.7.3 - Custom positioning - zones 22
4.8 - Zones 22
4.9 - User extensions - Callbacks 24
5 - Physical Installation - Best Practice 26
5.1 - Robot installation 26
5.1.1 - Check joint positions first 26
5.1.2 - Robot position on the base column 26
5.1.3 - Attach the gripper properly 27
5.1.4 - Lifting column 28
5.2 - Layout 29
5.2.1 - Supported pickup positions 30
5.2.2 - Suggested sensor placements 33
5.3 - Dimensions 34
5.3.1 - Pallet 34
5.3.2 - Pickup from Conveyor 34
5.3.3 - Important parameters to be measured 37
5.4 - Gripper 37
5.5 - I/O Connections 38
6 - Installing and Configuring the URCap 39
6.1 - Installation settings 39
6.1.1 - Overview 39
6.1.2 - License 40
6.1.3 - Gripper 41
6.1.4 - Lifting column 46
6.1.5 - Input/Output 50
6.1.5.1 Using MODBUS or General Purpose Boolean Registers 50
6.1.5.2 Input/Outputs in Pally 51
6.1.6 - Patterns 53
6.1.7 - Advanced 54
6.2 - Program settings 56
6.2.1 - Pickup 57
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
3

6.2.1.1 Calibration Box 57
6.2.1.2 Primary Pickup 58
6.2.1.3 Secondary Pickup 62
6.2.2 - Pallet 63
6.2.3 - Movement 65
6.2.4 - Advanced 69
6.3 - Callbacks 76
6.4 - Examples: typical configuration scenarios 79
6.4.1 - Classic setup with one optimal pickup position 79
6.4.2 - One pickup position with products coming in from the side 79
6.4.3 - One pallet position and one pickup position on the opposite side 81
6.4.4 - Two parallel pickup positions 82
6.4.5 - Two opposite pickup positions 85
6.4.6 - Limited space, walls other object 86
7 - Using the palletizer program 87
7.1 - Creating the main program 87
7.2 - Starting the program 87
7.3 - Using the program 88
7.3.1 - Single Product Mode 88
7.3.2 - Dual Product Mode 90
7.3.3 Partial Pallet 95
7.3.3.1 Edit Total Boxes 96
7.3.3.2 Edit Start Conditions 97
7.4 - Recovery from error 98
7.5 - Shutting down the robot 98
8 - Creating Patterns 98
8.1 - The pallet pattern definition file 98
8.2 - Project overview 99
8.3 - Layer types 100
8.3.1 - Box position 101
8.3.2 - Box rotation 101
8.3.3 - Box order 101
8.3.4 - Enforced single/multi-grip 101
8.3.5 - Gripper rotation at pickup 102
8.3.6 - Left and right pallet layout 102
8.3.7 - Inverse approach 103
8.3.8 - Shim paper 103
8.4 - Layers 103
8.5 - Zones 103
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
4

8.5.1 - Conditions 104
8.5.2 - Position transformation 105
8.5.3 - Location of the zone definitions 105
8.6 - Uploading new patterns 105
9 - Advanced configuration variables 106
9.1 - Naming conventions 106
9.2 - Changing configuration variables at startup 106
9.3 - Changing configuration at runtime 106
9.4 - List of available configuration variables 106
9.4.1 - Speed and acceleration 107
9.4.2 - Calibration points 107
9.4.3 - Path planning 108
9.4.4 - Gripper 110
9.4.5 - Lifting column 110
9.4.6 - Other/Special 111
10 - PalletManager daemon process 114
10.1 - Using the PalletManager daemon 114
10.2 - Pallet dimensions 114
10.3 - Product dimensions 114
10.4 - Pallet completion state 115
11 - Troubleshooting 116
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
5

1 - Document Revision Information
Date
Description
Author
15.11.2018
Initial draft
CM,LÅ,AL
08.02.2019
Checklist for new robot setup
CM
12.02.2019
Functional description, typical setup examples
CM
25.02.2019
Comments resolved, screenshots updated
CM
24.05.2019
Lifting column, shim paper, updated screenshots
CM
29.08.2019
Gripper and TCP configuration rewritten
CM
04.10.2019
Added gripper optimization, grippers with offset
CM
19.10.2019
Adding description of ‘Partial Pallet’-feature
ME
27.03.2020
Installation process with new GUI
ME
18.05.2020
Description of json format, new functions in 2.5.0
CM
26.05.2020
New Advanced tab in installation node
ME
28.09.2020
New functions in 2.6.0
CM
11.01.2021
Updates related to 2.6.1
CM
29.01.2021
Dual product mode updated for v2.7.0
ME
26.04.2021
Updates related to 2.7.1, new illustrations
CM
14.06.2021
Updates related to 2.8.0
CM
01.09.2021
Explanation of Smart Exit parameters, v2.8.1
CM
25.10.2021
v2.9.0, new gripper.json format, automatic single pick,
updated screenshots.
CM
22.12.2021
Vention MachineMotion V2 added
CM
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
6

2 - License
© Rocketfarm AS 2021. All rights reserved.
Disclaimer
The information contained herein is the property of Rocketfarm AS and shall not be
reproduced in whole or in part without prior written approval of Rocketfarm AS. The
information herein is subject to change without notice and should not be construed as a
commitment by Rockerfarm AS. Rocketfarm AS assumes no responsibility for any errors or
omissions in this document.
The Pally logo is a registered trademark of Rocketfarm AS.
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
7

3 - Requirements
3.1 - Software Requirements
URCap API version 1.12 or higher is required.
CB-series: Polyscope version 3.15 or higher is required.
E-series: Polyscope version 5.10 or higher is required.
3.2 - Hardware Requirements
Due to size limitations, the palletizer URCap requires a UR10 robot.
On CB-series robots, only CB-series version 3.1 is fully supported.
CB 3.0 robots may be used with some limitations, see Compatibility with CB 3.0 robots
3.2.1 - Supported external hardware
Lifting columns
● Ewellix LiftKit
● Vention MachineMotion V1 and V2
● Custom lifting column with 24V digital Up/Down signal
Grippers
● UniGripper CoLight
● Schmalz FXCB - Foam
● Schmalz FXCB - Suction cups
● Custom vacuum gripper with 24V digital signal
● Custom gripper
● Grippers with one or more individually controllable grip areas
3.3 - Compatibility notes
!
Please read the following compatibility notes carefully before upgrading an
existing Pally installation in production. Some changes in the recent versions may
require new customer acceptance tests and/or modifications in the main robot
program. Always make a full backup before upgrading.
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
8

3.3.1 - Compatibility notes for version 2.6 and above
3.3.1.1 - Path planning
The path planning algorithm has significantly changed in version 2.6. It is recommended to
test existing projects with full pallets of all products after upgrading to version 2.6.
3.3.1.2 - ProductCount
Since version 2.6 the "ProductCount" variable is now properly initialized to 0. In earlier
versions it was initialized to -1 incorrectly. It is necessary to update custom code in callbacks
that rely on the ProductCount variable.
3.3.2 - Compatibility notes for version 2.7.1 and above
3.3.2.1 - Pallet confirmation variables
From version 2.7.1 the pallet confirmation variables "rf_PS1_ok" and "rf_PS2_ok" should be
updated with the following script command:
palletmanager_daemon.write_key_value_static(name, value)
The old method palletmanager_daemon.write_key_value(0, name, value) has
no longer effect on the pallet confirmation state.
Programs that directly update the pallet confirmation variables should be verified.
3.3.3 - Compatibility notes for version 2.8 and above
3.3.3.1 - Execution of beforeZone and afterZone callbacks
From version 2.8.0 the beforeZone callback will be invoked when the lifting column has
already reached the specified position but palletizing has not yet started. Similarly, the
afterZone callback will be invoked after palletizing the last box has finished but the lifting
column is still in the position as specified by the current zone. Programs that use a lifting
column and have user code in beforeZone and afterZone callbacks should be verified.
3.3.3.2 - Execution of beforeGrab callback
From version 2.8.0 the pipeline architecture for all path planning calculations has been
redesigned such that all calculations are already done when the program enters the
beforeGrab callback. Changing some path-planning related internal rf_-variables in
beforeGrab for smart exit or collision radius calculations will no longer have any effect on the
next movement. Programs that modify internal (rf_) path planning variables directly in
beforeGrab should be verified.
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
9

3.3.3.3 - Waiting time at pickup and release positions
From version 2.8.0 the waiting time at pickup and release positions has been optimized, in
order to minimize the occurrence of protective stops caused by too early or too late change
in the payload and center of gravity. The waiting time may become shorter or longer than in
previous versions. Projects that are sensitive to the waiting times at pickup and release
positions should be verified. For further information, see the new variables
rf_joint_deviation_max and rf_joint_deviation_err under 9.4.6 - Other/Special
3.3.4 - Compatibility notes for version 2.9 and above
3.3.4.1 - URCap API 1.12
From version 2.9.0 the minimum required URCap API version is 1.12. which may require the
robot to be upgraded to a significantly newer version of Polyscope. Always make a full
backup before upgrading.
3.3.4.2 - Definition of multi-zone grippers (gripper.json)
From version 2.9.0 the structure of gripper.json has been changed. The zone positions are
now defined in accordance with the tool coordinate system, which means the X and Y
directions are inverted. This applies to all new gripper.json files that have the new format
with the "properties" structure included, otherwise the old behavior is kept for compatibility
reasons.
3.3.4.3 - Multi-pick fewer boxes
From version 2.9.0 the optimizer will try to pick fewer boxes when the specified (maximum)
amount of boxes cannot be palletized for some reasons, including out of reach issues and
too small gripper size. In contrast to older versions that failed immediately with "This position
cannot be palletized" the program will now retry with fewer boxes. This may introduce
unpredictable behavior when the calibration of an existing system is modified.
3.3.4.4 - Optional posData in zones.json
From version 2.9.0 the "posData" values in zones.json are made optional. This makes it
possible to use zones in combination with lifting column dynamic positioning.
3.3.4.5 - New callback onNextTask
From version 2.9.0 a new callback "onNextTask" will be automatically generated into the
existing program tree when the Pally program node is opened in the Program Robot menu
for the first time. The program has to be saved in order to keep the new structure.
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
10

3.4 - Compatibility with CB 3.0 robots
Due to hardware limitations in the CB 3.0 control boxes, the Pally URCap may not run as
smoothly as expected. Consider the following steps before installing Pally URCap on these
robots.
3.4.1 - Memory usage limitations on CB 3.0
Out of memory exceptions may occur during installation and configuration of the Pally
URCap unless the following modification is made in the operating system.
● Find the file run_gui.sh under /root
● Find the line RUN_GUI="java …
● Add the following option: -XX:MaxPermSize=128m
After the modifications, the line should look like this:
RUN_GUI="java -XX:MaxPermSize=128m
-Djava.library.path=/root/GUI/lib -jar bin/*.jar"
Note: Make sure all whitespaces are inserted properly as shown above.
Note: Make sure all capital letters and small letters are properly written. The operating
system is case sensitive and requires the parameter names to be written exactly as shown
above.
Note: Repeat the above steps every time after upgrading Polyscope.
If you are not familiar with operating system parameter tuning, follow the steps below:
● Connect a keyboard to the Teach Pendant or an USB connector in the control box
● Press Control+Alt+F1 to enter the console
● Log in with username root and password easybot
● Go to the /root folder by entering cd /root
● Type nano run_gui.sh to edit the file
● Make the above described modifications, then press Ctrl+X to save the changes
● Press Ctrl+Alt+F7 to return to the Polyscope screen
● Disconnect the keyboard
● Restart the robot
3.4.2 - Computational limitations on CB 3.0
In order to reduce calculation times and avoid lagging, keep the following rules in mind when
creating pallet patterns.
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
11

● Use "lock direction" for all boxes wherever possible.
● Disable 2-ways and 4-ways gripper optimization and only add the enforced gripper
orientation at positions where it is needed.
● Use the "inverse approach" option for all layers except the highest layers.
4 - Functional description
4.1 - The palletizer workflow
The typical use case for a palletizing robot is described as follows:
● The operator starts the robot and the palletizer software,
● The operator enters the product name to be palletized,
● The robot starts palletizing on an empty pallet,
● When the pallet is full, the operator must replace it with an empty pallet,
● Palletizing continues until the operator stops the program.
In addition to the above described default use case, the following scenarios are also
available in Pally:
● Build a partial pallet, i.e. palletize fewer boxes and/or layers than usual,
● Continue an incomplete pallet, i.e. specify the starting layer/box position,
● Palletize from 2 pickup positions,
● Palletize 2 different products from 2 pickup positions on 2 pallets simultaneously.
Note: Every pallet is built of one specific product type. Thus, it is not possible to palletize
different products on the same pallet.
4.2 - Pallet patterns
Every product has its own pallet layout, depending on the box dimensions and the label
position on the boxes. Some products have to be palletized using interlocking layers, which
means that every second layer is mirrored or rotated in order to improve pallet stability.
Other products have to be palletized so that the boxes are put exactly on the top of each
other. The palletizer software can handle these requirements by defining the pallet patterns.
Note: A pallet pattern is the logical representation of a pallets layout, which can be
dynamically loaded into the program. The number of supported patterns is only limited by the
available disk space.
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
12

4.3 - Pallet completion state
While pallet patterns define the expected layout of the pallet as a static model, the pallet
completion state follows the actual status of the pallet currently being stacked. The pallet
completion state keeps track of which exact box positions are already done, and which are
waiting to be filled. The completion state is updated every time the robot has successfully
moved a box from the pickup position and released it at the target position on the pallet.
Note: The robot will not be aware of any boxes that are moved to, on or from the pallet by
the operator.
4.4 - Pickup position
The pickup position is at the end of the conveyor belt, where the boxes stop and wait until
the robot picks them up.
Note: The pickup position must be stationary, i. e. the conveyor should be fixed to the floor.
One side of the conveyor should have a fixed side-guide, which the boxes can be aligned to.
The other side-guide should be adjustable for different product sizes where needed, see
figure 1. Depending on the box weight and dimensions, the robot can lift up multiple boxes
at the same time. When multi-grip is available, the robot will align the gripper equally
between the boxes to maximize gripping stability, as illustrated in figure 2.
Figure 1: Pickup position with one product.
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
13

4.4.1 - Single pick and multi-pick
Depending on the actual pallet pattern and gripper dimensions, it is possible to pick one or
more boxes at the pickup position. To pick multiple boxes, the positions in the pattern file
must follow each other by product length. The pick and place positions are automatically
calculated for the given number of boxes.
The program will automatically retry with fewer boxes when the specified number of boxes
cannot be palletized:
- when the gripper is too small to pick all boxes
- the pick position is out of reach
- the target position is out of reach
- collision-free path planning is not possible
Figure 2: Pickup position with two products. Notice that the tool coordinate system is
aligned to the conveyor direction.
4.4.2 - Gripper alignment at the pickup position - offset grip
To avoid accidental multi-picking, the front edge of the gripper is always aligned with the rear
edge of the (last) product being picked. This is especially important when boxes are smaller
than the gripper. In this case the gripper is not aligned centered above the box, which is a
common misunderstanding when using Pally at the first time.
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
14

Figure 3: gripper alignment at pickup
4.4.3 - Gripper rotation at the pickup position - gripper optimization
In order to get better reach or performance, the program can automatically recalculate and
use the gripper rotated by +90, -90, 180 degrees at the pickup position. This may be
necessary to reach the pallet corners or avoid collision with the base frame. The allowed
rotations can be configured.
Figure 4: gripper rotation at pickup
4.4.4 - Grip quality value - smart acceleration
Based on the actual product and gripper dimensions and the number of boxes being picked,
the program estimates the risk of dropping boxes due to high acceleration with insufficient
grip strength. The parameters of this algorithm can be configured, see 6.2.3 - Movement.
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
15

4.5 - Path planning
The path planning algorithm is an essential part of the palletizer software. It calculates the
optimal movement from the pickup position to the pallet position. These calculations are
performed dynamically when the robot moves one or more boxes from the pickup to the
pallet position.
The path starts with a position above the pickup point, to ensure the gripper moves vertically
down against the box surface. After picking the products, the robot moves vertically up until
the box is removed from between the side guides. Depending on the current pickup and
target positions, this is followed by one or more waypoints in order to move and rotate the
box(es) without collision to the robot base or the existing boxes on the pallet. The approach
position is the last waypoint in the proximity of the final target position. The robot uses lower
acceleration and speed from the approach to the final target position to improve the pallet
accuracy.
Note: To ensure a smooth palletizer experience, some properties of the production line
should be carefully measured.
4.5.1 - The path planning algorithm
The primary goal of the path planning algorithm is to move the box on a linear path
whenever possible, see figure 5 and figure 6. After the box is taken from the pickup
position, the algorithm tries to find one waypoint - called smart exit position - from where the
shortest, direct linear movement is possible.
Figure 5: The primary path planning algorithm on lower layers.
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
16

Figure 6: The primary path planning algorithm on higher layers.
When it is not possible to find a smart exit position from where a direct linear movement is
possible, one or more waypoints are being inserted. In this case the program evaluates the
pallet completion state (position of the already palletized boxes) and finds a collision-free
path to the target position. It is often necessary to move the box above all other boxes, and
then lower vertically to the target position, see figure 7. This path is normally longer than a
direct linear movement, and hence more time demanding.
Figure 7: Path planning with an extra waypoint. Boxes on the same layer define a collision
area to be avoided.
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
17

4.5.2 - Approaching the target position
In order to improve precision, the last section of the movement is being performed with lower
speed and acceleration.
Normally the robot moves the box into its final position by using the "Approach" distance,
which is shown on figure 8.
Figure 8: Approaching the target position with lower speed and acceleration
Note: To keep the necessary distance from the existing boxes on the pallet, the approach
position may be recalculated dynamically if rotation occurs between the pickup and the
target position. This default behavior can be changed by selecting 'fixed' approach, see 6.2.3
- Movement
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
18

Figure 9: Dynamically calculated approach distance for rotating boxes.
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
19

Figure 10: Difference between dynamically calculated and fixed approach distance.
Please note the extra waypoint added to complete rotation before approaching.
4.5.3 - Pallet lip
When pallets have an outer edge lip, the robot can enforce a vertical movement on the first
layer to avoid collision with the pallet lip, see figure 11.
Figure 11: Vertical movement from above the pallet lip
4.5.4 - Return path
After releasing the box at the target position, the robot visits the path waypoints in reverse
order, to return from the pallet position and pick the next box(es) from the conveyor.
In a typical setup, the robot waits above the pickup position until the required amount of
boxes are available, but in special configurations (e.g. with 2 pickup positions, where the
next pickup point is not known in advance) the robot waits at a default waiting position.
It is possible to modify the return path by removing one or more waypoints or implementing a
user-defined path.
4.5.5 - User-defined path
It is possible to override the default Pally path planning by implementing custom movement
for one or more specific box positions, or even replace the default path planning in the entire
project. It is also possible to implement custom code to sort out boxes from the conveyor that
should not be palletized, based on a project-specific signal or quality check. Refer to
callbacks for further details.
4.6 - Shim papers
Shim papers are considered as special layers with no products. These layers have their own
height - i.e. the thickness of the shim paper itself. Pally does not include a default
implementation for shim paper placement - this has to be implemented for each project by
using callbacks.
4.7 - Lifting column
Lifting columns extend the robot reach by adding a virtual 7th axis to the robot. The current
position of the lifting column is a parameter in all calculations in the Pally path planning.
Version 2.9.1
© Rocketfarm AS 2021. All rights reserved.
20