Add Support for 12ID Beamline robot

[Dozgulbas]

The interface and REST node needs to include new methods for 12ID beamline robots.

• Go over the following repo to investigate the important functions

https://gcc02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FByeongdulee%2FUR_12idb%2Fblob%2Fmain%2Frobot12idb.py&data=05%7C02%7Cdozgulbas%40anl.gov%7C7380c9a6e333408456c308de0db67d50%7C0cfca18525f749e38ae7704d5326e285%7C0%7C0%7C638963274590270932%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=EegbX80E%2FnzGpJswY7n%2BUanm2Cp64iWf%2FsZeGHXbSto%3D&reserved=0

• Some important methods:
  -get_sample
  -returnsample
  -auto_align_12idb_remote_heater,
  -auto_align_12idb_standard_holder for automatic alignment of the target position

• Add new actions in to REST Node for corresponding methods

Notes on these methods:

Ultimately, ‘get_sample’ and ‘returnsample’ are what used the most.
Whenever it transports a sample, it updates ini file to keep track all operation parameters and samples.

[Dozgulbas]

@byeongdu I am looping you in for updates.

[Dozgulbas]

Hi @byeongdu I am currently working on this task. It seems that we can handle get_sample and return_sample steps with gripper transfer methods that already exist. I am working on bringing some of your functionality that helps to calibrate the robot with the targeted location based on the force feedback.

[Dozgulbas]

@byeongdu I have transfer your methods into the ur_module. However, I suspect we would need to run tests and debugging sessions before we can make sure everything is working as expected. Below is the description on what has been updated.

Branch: 12id-robot

Implementation Summary: AprilTag Alignment & Pallet Transfer Methods

Overview

This update adds automatic alignment capabilities for the 12IDB beamline and generalized pallet transfer methods to the UR robot interface. The implementation follows a modular architecture with self-contained modules and minimal changes to the core UR class.

---

New Features

1. AprilTag-Based Automatic Alignment

Two new alignment methods for 12IDB beamline sample holders:

• auto_align_12idb_remote_heater(camera_index=0, test_run=True)

  • Uses AprilTag vision detection to precisely align to remote heater
  • Includes force-based contact detection for final positioning
  • Measures and compensates for tilt (up to sub-degree accuracy)
  • Returns aligned position and tilt compensation angle

• auto_align_12idb_standard_holder(test_run=True)

  • Uses force-guided positioning (no camera required)
  • Bumps to find X and Z positions precisely
  • Returns aligned position

Key Implementation Details:

• Camera automatically managed (connect/disconnect) within methods
• Force-based "bump" detection using tool_contact() in URScript
• Exact logic ported from original robot12idb.py and robUR.py
• All camera coordinate transformations handled internally

2. Pallet/Grid Transfer Methods

Generalized methods for working with pallets, grids, and magazines:

• transfer_from_pallet(...)

  • Pick from any position in a pallet grid and transfer to target
  • Calculates grid position from reference point and index

• transfer_to_pallet(...)

  • Transfer from source to any position in a pallet grid

Parameters:

• pallet_reference: Reference position (index 0)
• pallet_index: Which grid position (0 to num_x*num_y - 1)
• pallet_x_gap_mm, pallet_y_gap_mm: Grid spacing in millimeters
• pallet_num_x, pallet_num_y: Grid dimensions
• Standard approach distance/axis parameters

---

Architecture

ur_interface/
├── ur.py                          # Minimal bridge methods added (4 new methods)
├── scripts/
│   ├── apriltag_alignment.py      # Complete AprilTag alignment logic
│   ├── force_calibration.py       # Force-based positioning (bump)
│   ├── checkdistance.script       # URScript for tool_contact()
│   └── pallet_position_calculator.py  # Grid position calculations

---

Changes to Core Files

ur.py (UR Class)

Added 4 new methods (thin bridges to modules):

def transfer_from_pallet(...)      # Bridge to pallet_position_calculator
def transfer_to_pallet(...)        # Bridge to pallet_position_calculator  
def auto_align_12idb_remote_heater(...)  # Bridge to apriltag_alignment
def auto_align_12idb_standard_holder(...) # Bridge to apriltag_alignment

Added 1 import:

from ur_interface.scripts import apriltag_alignment
from ur_interface.scripts.pallet_position_calculator import calculate_pallet_position
from ur_interface.scripts.apriltag_alignment import AprilTagCamera, auto_align_12idb_remote_heater, auto_align_12idb_standard_holder

ur_rest_node.py (URNode REST API)

Added 4 new action endpoints:

@action(name="transfer_from_pallet", ...)
@action(name="transfer_to_pallet", ...)  
@action(name="auto_align_12idb_remote_heater", ...)
@action(name="auto_align_12idb_standard_holder", ...)

---

New Module Files

1. apriltag_alignment.py (~600 lines)

• AprilTagCamera class (camera interface)
• _move_toward_camera() - Camera coordinate system movement (from robUR.py)
• _get_camera_vector() - Camera orientation calculations
• auto_align_12idb_remote_heater() - Main alignment function
• auto_align_12idb_standard_holder() - Force-only alignment
• All configuration (waypoints, tag sizes, camera angles)

2. force_calibration.py (~250 lines)

• bump() - EXACT urxe implementation for force-guided positioning
• Auto-loads checkdistance.script
• Test and calibration functions
• All self-contained

3. checkdistance.script

• URScript for real-time force monitoring via tool_contact()
• Used by bump() for precise contact detection

4. pallet_position_calculator.py (~200 lines)

• calculate_pallet_position() - Grid position calculations
• Row-major indexing (left-to-right, top-to-bottom)
• Supports X/Y offsets in millimeters

---

Technical Implementation Details

AprilTag Alignment Sequence (Remote Heater)

1. Move to waypoint for camera view
2. Detect and center on AprilTag
3. Move to calibrated distance from tag
4. Close gripper
5. Bump to confirm X distance
6. Move to bar center and rotate -90°
7. Bump to align along beam (Y)
8. Bump to find Z height
9. Measure tilt at two points
10. Apply tilt compensation
11. Set final pickup position
12. Optional: Test pickup/dropoff

Force-Based "Bump" Detection

• Uses URScript's tool_contact() for real-time force monitoring
• Calculates exact contact point from joint position history
• Precise directional backoff after contact
• Force threshold: 40 (configurable)

Camera Coordinate System

• Camera mounted at: 60° tilt, -30° north (from robUR.py)
• Transforms pixel offsets → physical distances → robot coordinates
• Handles camera-to-robot coordinate transformation automatically

Gripper Integration

• Uses FingerGripperController via callback pattern
• Gripper created and connected within alignment methods
• Automatic cleanup even on errors (try/finally)

---

Testing Required

These changes have NOT been tested on actual hardware yet. This is a direct port from the original codebase with architectural improvements, but bugs are expected. Testing should cover:

• AprilTag detection and camera connection
• Force-based bump detection with actual hardware
• Pallet position calculations (verify indexing)
• Gripper operation during alignment
• Camera coordinate transformations
• Error handling and recovery
• Integration with existing workflows

---

Credits

Implementation based on original code from:

• robot12idb.py - Alignment sequences
• robUR.py - Camera coordinate transformations
• urxe/robot.py - Force-based bump detection