Integration Guide Universal Robots LS

Note: It is strongly recommended to read the Robot communication overview prior to this integration guide.

Note 2: It is strongly recommended to use the latest version of the integration guide included in the latest available version of the robot module. To download the robot module, please visit the official Photoneo website.

Contents

• 1 Prerequisites

• 2 Robot controller setup

  • 2.1 Network configuration

  • 2.2 Enabling Real-Time Data Exchange (RTDE)

  • 2.3 Loading of Robot Module Files

  • 2.4 Tool TCP Setup

• 3 Robot module

  • 3.1 Connection procedures

  • 3.2 Request List

  • 3.3 Pick related functions

  • 3.4 Example programs

  • 3.5 Error handling

• 4 Runtime

  • 4.1 Set approach, deapproach offset parameters

  • 4.2 Teach positions

  • 4.3 Prerequisites

  • 4.4 Running the pho_main_basic_loc program

• 5 Robot module update

1 Prerequisites

Prior to the setup, please ensure that your robot controller meets the following criteria:

• E-Series controller, software version 5.10 or higher

• UR-Series controller, software version is yet to be determined

• CB-Series is not officially supported anymore

This version of the robot interface was developed and tested using Universal Robots E-Series v5.22 and v5.11.

To check the system version on your robot, go to Menu -> About:

The UR software version is listed on the first line:

2 Robot controller setup

2.1 Network configuration

The first step is to configure the IP address of the Robot Controller port used for communication with the Photoneo Vision Controller. Navigate to Menu -> Settings:

Open System -> Network. Select Static Address as the network method and type the IP address and Subnet Mask for the Robot Controller. The configuration used in this manual is 192.168.1.2 and 255.255.255.0. Click Apply to confirm the changes.

NOTE: Subnet Mask 255.255.255.0 equals a 24 bit subnet mask representation. See this table for more combinations.

An example of matching network configuration on the Vision Controller side:

• Vision Controller IPv4 Address: 192.168.1.1 / 24

• Robot Controller IPv4 Address: 192.168.1.2 / 24 (as configured in the previous step)

You can also use the Test Connection button on the Photoneo Vision Controller Network page to ping the Universal Robot Controller from the Photoneo Vision Controller.

Based on the result of Test Connection (ping command) you will get a Robot Available or Robot Unavailable popup message. If the robot is unavailable, double check the cabling and network configuration.

2.2 Enabling Real-Time Data Exchange (RTDE)

The State Server functionality (Calibration & Visualization) requires the Real-Time Data Exchange (RTDE) service to be enabled and running on the robot side.

In order to verify this service is running, go to Settings -> Security -> Services and make sure RTDE is enabled.

2.3 Loading of Robot Module Files

The Photoneo UR robot interface consists of a single script file and several URP template programs:

• photoneo_scripts

  • photoneo_locator.script

• photoneo_examples

  • pho_calibration_basic_loc.urp

  • pho_calibration_auto_loc.urp

  • pho_main_basic_loc.urp

  • pho_main_basic_hand_eye_loc.urp

  • pho_main_basic_multi_vs_loc.urp

  • pho_main_change_solution_loc.urp

  • pho_main_get_status_loc.urp

  • pho_main_multiview_dynamic_loc.urp

  • pho_main_multiview_static_loc.urp

  • pho_main_reuse_scan_loc.urp

  • pho_main_change_bounding_box.urp

Only URP programs need to be copied - the script is already included in the URP templates!

There are 2 ways to copy files to the robot controller:

• USB flash drive

• File transfer protocols such as SCP, FTP or SFTP

USB flash drive approach

Copy the folders from the downloaded module archive onto a USB flash drive and plug the drive into the pendant or into the robot controller USB port.

Click Open -> Program:

Select usbdisk -> Photoneo UR Module -> LS 1.5 -> photoneo_examples:

To copy pho_main_basic_loc.urp to the robot controller, select the file from the list and click Copy.

Navigate to the target folder on the robot controller and click Paste to copy pho_main_basic_loc.urp.

Repeat for all template URP programs you plan to use in your project.

File transfer protocol approach

It is possible to copy files to the UR Controller using remote access directly from your PC. Use WinSCP, FileZilla or another SFTP client. When creating the connection use the following configuration:

• Protocol: SFTP

• Host: Robot IP address

• Port: 22

• User: root

• Password: easybot

Alternatively, for situations where a command line interface is needed, use the following scp command to copy files:

$ scp -r Photoneo root@XXX.XXX.XXX.XXX:/programs/LS 1.5

2.4 Tool TCP Setup

TCP setup - Locator Studio reads the UR TCP pose during calibration and hand-eye scanning requests. What is reported by the robot to the vision system is the position of the tool according to the TCP configuration on the Installation TCP tab. Locator Studio prefers an “all zeros” tool configuration, as it compensates for the TCP offset directly on the vision system side. A zero tool configuration is also recommended for the calibration process.

If it is necessary to use a non-zero tool, it is recommended to use the set_tcp command from the UR Scripting language manual and switch between the zeroed and non-zeroed tool.

3 Robot module

The Robot module is designed to be easily integrated into existing applications.

Note: It is strongly recommended to read the Photoneo robotic API and Action requests documentation prior to this section (user login: customer, password: Ready2LearnHow2Pick).

3.1 Connection procedures

Warning: This procedure is contained in the photoneo_locator.script API section and must not be edited!

This procedure establishes the connection to the Action Request Server running on the Vision Controller, at the beginning of the program. Requests can only be sent after a successful connection has been established.

Connection procedure

Description / Usage

Connect to Action Request Server pho_wait_for_server ( server_ip, port = PHO_LOCATOR_PORT_DEFAULT, max_attempt = 1 )

Description Function to establish a new connection to the Action Request Server (Vision Controller). Input parameters: server_ip - string defining the IP of the Action Request Server (Vision Controller) port - port on which the Action Request Server is running [optional parameter - it is recommended to omit it - the default value 11003 will be used] max_attempt - number of connection attempts [optional parameter - the default value is 1] Usage The procedure should be called only once at the beginning of the program. Only after the connection has been established it is possible to send requests. pho_wait_for_server("192.168.1.1") Populates PHO_ERR_CODE - error code [global variable]

3.2 Request List

This section describes available API calls provided by the Robot module. These procedures are intended for high-level control of the Locator Studio application.

Note: These procedures are defined in the photoneo_locator.script API section and must not be edited!

Note: Procedures with optional parameter timeout have its default value set to -1. This means the timeout for receiving packets is infinite. Since the UR script has no means for detection of closing socket the robot program may be left hanging on this procedure when this situation occurs. Procedures without this parameter have hardcoded infinite timeout for receive.

Calibration requests

Request	Input variables	Output variables
Calibration start request pho_calib_start ( solution_id, vision_sys_id )	solution_id - solution ID vision_sys_id - vision system ID	PHO_ERR_CODE - error code [global variable]
Calibration add point request pho_calib_add_point ( tcp_pose )	tcp_pose - TCP (flange) pose	PHO_ERR_CODE - error code [global variable]
Calibration save request pho_calib_save ( )	—	PHO_ERR_CODE - error code [global variable] pho_calib_acc - resulting calibration accuracy [global variable] pho_camera_pose - resulting camera pose [global variable]
Calibration stop request pho_calib_stop ( )	—	PHO_ERR_CODE - error code [global variable]

Locator requests

Request	Input variables	Output variables
Scan request pho_request_scan ( vision_sys_id, tcp_pose = PHO_NO_POSE )	vision_sys_id - vision system ID tcp_pose - TCP pose [optional parameter - used only for hand-eye vision systems]	Note: The response is received by the procedure Wait for scan completion.
Meshing scan request pho_request_trigger_scan ( vision_sys_id, tcp_pose = PHO_NO_POSE )	vision_sys_id - vision system ID tcp_pose - TCP pose [optional parameter - for hand-eye systems use get_actual_tool_flange_pose()]	Note: The response is received by the procedure Wait for scan completion.
Reuse last scan request pho_run_loca_on_last_scan ( vision_sys_id )	vision_sys_id - vision system ID	Note: The response is received by the procedure Wait for scan completion.
Change bounding box request pho_request_change_bbox ( vision_sys_id, bbox_id )	vision_sys_id - vision system ID bbox_id - bounding box ID	PHO_ERR_CODE - error code [global variable]
Get objects request pho_request_get_objects ( vision_sys_id, num_of_req_objects )	vision_sys_id - vision system ID num_of_req_objects - number of requested object poses	PHO_ERR_CODE - error code [global variable] pho_object_poses - array containing received object poses as pose variables (p[x,y,z,ax,ay,az]), starts indexing from 0 [global variable] pho_number_of_objects - number of received object poses [global variable] pho_dimensions_x - object width [non-CAD solutions, global variable] pho_dimensions_y - object length [non-CAD solutions, global variable] pho_dimensions_rot - object rotation [non-CAD solutions, global variable] pho_nn_label - detected object label [AI solutions, global variable] pho_max_height - object height [Layer solutions, global variable] pho_angle - object angle [Layer solutions, global variable]
Get vision system status request pho_request_get_vs_status ( vision_sys_id )	vision_sys_id - vision system ID	PHO_ERR_CODE - error code [global variable] pho_num_localized - number of objects localized [global variable] pho_num_ready - number of objects ready for picking [global variable] pho_process_state - current state of the vision system [global variable]

Solution requests

Request	Input variables	Output variables
Change solution request pho_request_change_solution ( solution_id )	solution_id - solution ID	PHO_ERR_CODE - error code [global variable]
Start solution request pho_request_start_solution ( solution_id )	solution_id - solution ID	PHO_ERR_CODE - error code [global variable]
Stop solution request pho_request_stop_solution ( )	—	PHO_ERR_CODE - error code [global variable]
Get running solution request pho_request_running_solution ( )	—	PHO_ERR_CODE - error code [global variable] pho_running_solution - solution ID [global variable]

Response receiving procedures

Response receiving procedures	Input variables	Output variables
Wait for scan completion pho_wait_for_scan_completion ( )	—	PHO_ERR_CODE - error code [global variable]

Communication check

Request	Input variables	Output variables
Communication check request pho_request_comm_check ( )	—	PHO_ERR_CODE - error code [global variable]

3.3 Pick related functions

Get approach offset pose is an extra function that calculates an approach offset pose based on the selected method and axis.

Function	Input parameters	Returns
Get approach offset pose pho_get_approach_offset_pose ( pho_object_pose, pho_offset_value, pho_method = PHO_METHOD_DEFAULT, pho_axis_name = PHO_AXIS_NAME_DEFAULT )	pho_object_pose - target object pose pho_offset_value - offset magnitude, in meters pho_method - offset calculation method [optional parameter, one of 'Tool Offset', 'Tool Plane', 'Base Offset', 'Base Plane'] pho_axis_name - axis along which the offset is applied [optional parameter, one of 'X', 'Y', 'Z']	pose p[x,y,z,ax,ay,az]

Method options:

• 'Base Offset' - adds the offset along the selected axis in the base coordinate system

• 'Base Plane' - overrides the value along the axis in the base coordinate system

• 'Tool Offset' - adds the offset along the axis in the tool coordinate system (TCP)

• 'Tool Plane' - computes the intersection between the offset plane (base system) and the TCP along the selected axis

Usage of this function for setting up the approach/deapproach offset is described in more detail in 4.1 Set approach, deapproach offset parameters.

3.4 Example programs

There are several URP template programs available in the Photoneo UR module that demonstrate how to properly use the requests listed in 3.2 Request List for various use cases:

URP example	Description
pho_main_basic_loc pho_main_basic_hand_eye_loc	This simple example demonstrates the basic workflow: it shows how to connect to a vision controller, send a scan request, request object poses, receive the object poses, and execute picks. The example also illustrates error handling, as each function returns an error value assigned to PHO_ERR_CODE.
pho_calibration_basic_loc pho_calibration_auto_loc	The basic calibration examples. Requirements: the initial calibration of the Vision System must be started and confirmed manually by the user on the Locator Studio side. Calibration steps: Teach all 9 calibration poses - points can be added to the calibration table manually by clicking Add Calibration Point on the Locator Studio side, or by using pho_calib_add_point(tcp_pose) requests directly from the program without any manual pose teaching. Calibration accuracy - the calibration error should generally remain below 3 mm; a higher error typically indicates a systematic issue in the calibration setup. Automatic recalibration (optional) - once the first calibration is successful and automatic recalibration is enabled in the Vision System settings, use pho_calib_start(), pho_calib_stop() and pho_calib_save() to manage the recalibration cycle. Important: the calibration object (ball or marker pattern) must remain in its original position to ensure successful automatic recalibration.
pho_main_basic_multi_vs_loc	Same as pho_main_basic_loc, but switches between two Vision Systems. The VISION_SYS_ID variable determines which Vision System is activated or queried for trajectory data. Vision System switching is handled in the Changing Vision System folder, located at the bottom of the Photoneo Pick and Place loop folder.
pho_main_change_solution_loc	Same as pho_main_basic_loc, but with all solution-switching related requests. It shows how to activate different solutions using pho_request_start_solution() or pho_request_change_solution(), with the SOLUTION_ID variable determining which solution is triggered. Solution switching logic is organized in the Changing solution folder, located at the bottom of the Photoneo Pick and Place loop folder.
pho_main_get_status_loc	Same as pho_main_basic_loc, but with pho_request_get_vs_status request calls. pho_request_get_vs_status() can be called repeatedly at short intervals during the localization phase and returns: pho_num_localized - number of objects localized pho_num_ready - number of objects ready for picking pho_process_state - current state of the vision system These variables are commonly used for advanced decision-making, particularly to determine the optimal timing for starting the pick procedure.
pho_main_multiview_static_loc	Static meshing example. Demonstrates stitching multiple scans together before localization, which is useful for complex scenes or large objects. The robot pauses at each scanning position to trigger and capture a scan. Requirements: the State Server must be operational throughout the process, and MESH_DYNAMIC must be set to False to disable dynamic meshing. Procedure: The robot stops at each designated scanning location to trigger and capture a scan. After each scan, pho_request_trigger_scan() must be followed by pho_wait_for_scan_completion() to properly complete the scan request. After the capturing sequence is complete, initiate localization with a regular pho_request_scan() - this does not perform an actual scan, it only starts the localization process. Keep the total number of scans below 10 to ensure optimal performance.
pho_main_multiview_dynamic_loc	Dynamic meshing example. Uses the LS 1.5 integration of Photoneo Instant Meshing together with the Parallel Structured Light technique of the MotionCam-3D. Dynamic meshing cannot be used with standard PhoXi 3D Scanners. Requirements: MESH_DYNAMIC must be set to True to enable dynamic meshing; CAPTURE_GAP should be around 500 ms to regulate the scanning frequency and prevent system oversaturation; system_status monitors the state of the capturing process. Procedure: Capturing begins, letting the MotionCam-3D trigger scans at intervals set by CAPTURE_GAP (recommended 500 ms) while the robot moves through the predefined start/end waypoints. The robot’s position during the first scan is important for correctly orienting the final point cloud - robot movement is temporarily paused by the Photoneo interface until system_status transitions to PHO_MESHING after the first scan is received. During dynamic capturing, only the final pho_request_trigger_scan() is followed by pho_wait_for_scan_completion(). The capturing sequence is concluded with a regular pho_request_scan() to start localization - this does not emit light, it only triggers localization. Keep the scanning trajectory smooth, avoiding abrupt rotations, and keep the scanned area within the field of view to prevent tracking loss. Keep the total number of scans at 60 or below to maintain optimal performance.
pho_main_reuse_scan_loc	Same as pho_main_basic_multi_vs_loc, but introduces pho_run_loca_on_last_scan(). This is useful when the scene has not changed since the last scan, but localization needs to run again with a different configuration - for example different objects, bounding boxes, or settings. Procedure: perform a regular scan for VS1 to capture the scene, then for VS2 use pho_run_loca_on_last_scan() to reuse the scan data from VS1, repeating localization with a different configuration without a new scan.
pho_main_change_bounding_box	Same as pho_main_basic_multi_vs_loc, but introduces the new LS 1.5 feature pho_request_change_bbox(). This is useful when the scene has not changed since the last scan, but localization needs to run again over a different region of interest. Procedure: prepare the Vision System with at least 2 bounding boxes and switch between them using pho_request_change_bbox(vision_sys_id, bbox_id).

3.5 Error handling

If an error occurs during the execution of the operation requested by the sent request the global variable informing about an error occurrence is set to true (PHO_OCCURED_ERR) and the error code is stored in the global variable PHO_ERR_CODE. It is recommended to implement adequate error handling for your particular application after each synchronous request and response receiving procedure.

Error codes together with their description and troubleshooting can be found here.

4 Runtime

Once the solution is fully configured on the Vision Controller side, finish the remaining steps on the robot side and run the Locator Studio program.

4.1 Set approach, deapproach offset parameters

The Locator Studio example programs provide a way to set up the approach and deapproach offset parameters, which are used by the pho_get_approach_offset_pose() function described in 3.3 Pick related functions.

Input parameters for pho_get_approach_offset_pose():

• pho_object_pose - target object pose

• pho_offset_value - offset magnitude

• pho_method - offset calculation method

• pho_axis_name - axis along which the offset is applied

Approach offset configuration

The following variables define the approach behavior:

Variable	Description
APPR_OFFSET	Sets the offset distance, in meters
APPR_AXIS	Specifies the approach axis ('X', 'Y', 'Z')
APPR_METHOD	Selects the approach method, as a string

Available approach methods:

• 'Base Offset' - adds the offset along the selected axis in the base coordinate system

• 'Base Plane' - overrides the value along the axis in the base coordinate system

• 'Tool Offset' - adds the offset along the axis in the tool coordinate system (TCP)

• 'Tool Plane' - computes the intersection between the offset plane (base system) and the TCP along the selected axis

Deapproach settings are configured separately, in the Deapproach Offset Parameters folder.

4.2 Teach positions

After opening pho_main_basic_loc.urp (or another template), touch up the following 4 local poses before running the program:

• Scanning

• Before_place

• Place

• deapproach_place

4.3 Prerequisites

Final pre-deployment checklist before running the Locator Studio interface from the robot side. Make sure that:

1. The Locator Studio solution is properly configured on the Vision Controller side

2. Network setup on the robot side is completed and the State Server is working

3. All Vision Systems defined in the solution are calibrated

4. All local poses in the main program have been touched up properly

5. Gripper procedures are prepared and working

4.4 Running the pho_main_basic_loc program

Deploy your solution. The Action Request Client (Robot) status on the Deployment page should be DISCONNECTED from the Action Request Server, if the communication has not been established yet.

NOTE: It is strongly recommended to reduce the override speed to 20% before running the program for the first time.

Once the connection has been established, the Action Request Client status changes to CONNECTED. At this point the sensor should capture the first scan and localization should start localizing objects.

If there is a pickable object in the scene and the robot controller has received its Cartesian pose, the robot should start moving towards the first object.

If the robot movement looks correct, continue moving the robot towards the first target and verify that the path is correct. If the robot is too far from the object or pushes the object too deep, adjust the object origin or the tool TCP setup.

Once the robot movement looks correct, set up your own placing routine and gradually ramp the speed back up to 100%.

At this point, the robot should be successfully picking and placing objects using the Photoneo Universal Robots interface. Refer to the example programs in 3.4 Example programs as a guideline while further tuning your application.

5 Robot module update

To update an existing robot module to a version compatible with the Locator Studio you are using, please follow these steps:

1. Load the new script - copy the new version of photoneo_locator.script to the robot controller and replace the old one.

2. Review API changes - carefully read through the API changes introduced in the new version of the robot module and update your existing API calls in the main program as necessary to align with these changes.

To check the version of the photoneo_locator.script, check the script’s header and look for the library version.