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

```text
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.

```python
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.