Design Philosophy

Primary Objective

The primary objective of URCtrl is not a minimal port from COBOTTA to UR.

Its primary objective is to provide a common robot interface through which researchers can operate different collaborative robots consistently.

COBOTTA compatibility matters, but it is a way to reuse existing code rather than the ultimate design goal. If URCtrl establishes a better API design, cobotta_ctrl may be updated to align with the common interface.

Concept of a Common Robot Interface

This project does not treat a robot as merely a collection of manufacturer-specific APIs. As a component of a research instrument, it is organized around these common operations:

Connect
Read the current position
Read the current joint angles
Teach a position
Move to a position
Move through multiple points
Read/write I/O
Configure TCP/tool
Read status
Display errors
Attempt recovery from a safety stop
Close the connection

These operations are required for both COBOTTA and UR; only their internal implementations differ.

Separation of the Common Interface and Implementations

The common interface is the layer directly used by researchers. The implementation layer invokes each robot’s manufacturer-specific APIs.

Common interface
    move()
    teach()
    get_current_position()
    set_IO()
    reset_error()

UR implementation
    RTDEControlInterface
    RTDEReceiveInterface
    RTDEIOInterface
    DashboardClient

COBOTTA implementation
    ORiN2 / b-CAP / RC8
    Controller
    Variable
    IO

This separation allows higher-level experiment code to remain independent of whether the robot is UR or COBOTTA.

COBOTTA Is an Existing Implementation, Not the Standard

The existing cobotta_ctrl is an important predecessor, but not the definitive standard for the common interface.

For example, COBOTTA has an RC8 variable P1, while UR does not. The common interface therefore defines P1 as a named taught point, not an internal robot variable. Each implementation determines how it is stored.

UR stores it in JSON through RobotVarManager. COBOTTA may continue using RC8 variables or eventually adopt common variable management.

BL774-Style and SPring-8 Compatibility

This interface is not intended solely to operate an individual robot. It assumes integration with SPring-8 beamline experiments, automated measurements, sample exchange, fixture manipulation, cameras, detectors, and measuring instruments.

Accordingly, the API must meet the following requirements:

Support concise calls from experiment scripts.
Expose status when an operation fails.
Use mm, degrees, and percentages accessible to non-specialists.
Document differences between robots.
Integrate readily with device servers, remote control, and automated measurements.
Fit into a SPring-8-compatible instrument-control layer.

Unit Conventions

The researcher-facing interface does not expose SI units exclusively.

UR RTDE uses meters and radians, but millimeters and degrees are more intuitive in experimental work. The public URCtrl interface therefore uses these units:

Quantity	Public Interface
P position	mm
P orientation	Rotation vector expressed in degrees
J coordinates	degree
speed / accel / decel	%

Convert to meters and radians at the RTDE boundary.

Success and Failure Conventions

Most operations in the common interface return True or False. On failure, the exception and status are recorded internally and can be retrieved via error_description or get_current_error_info().

This keeps experiment-control scripts concise.

ok = robot.move("P1")

if not ok:
    print(robot.error_description)

Policy for Unsupported Features

Robot-specific functions are separated into those appropriate for the common interface and those that are not.

COBOTTA-specific PacScript, dedicated hands, and RC8 file transfer are excluded from the UR common interface. The UR implementation reports these as unsupported, returns False, and records an error.

Conversely, UR’s status monitoring and safety-state reporting may inform improvements to COBOTTA.