# Common Interface and BL774-Style Systems

## Not Merely a Standalone Robot API

`URCtrl` is not simply an API for conveniently operating a standalone UR robot. It treats a collaborative robot as one controlled device within an experimental system.

```text
Experiment plan
    ↓
Measurement sequence
    ↓
Instrument-control layer
    ↓
Common robot interface
    ↓
UR / COBOTTA / other robots
```

## Meaning of the BL774-Style Architecture

BL774-style refers to the research and beamline control architecture envisioned by this project.

In this architecture, the robot is not merely a machine replacing manual work. It is an automation component connected to instruments, detectors, stages, cameras, servers, logging, and job management.

The robot API must therefore have the following properties:

- Express operations in concise Python code.  
- Provide readable status.  
- Provide error-recovery procedures.  
- Support deployment through a remote-control server.  
- Integrate with a common device framework.  
- Avoid exposing excessive robot-specific APIs to higher layers.  

## SPring-8 Compatibility

In synchrotron experiments such as those at SPring-8, robot operations form part of the measurement sequence.

Example:

```text
Place sample
    ↓
Retract robot
    ↓
Prepare shutter and detector
    ↓
Measurement
    ↓
Exchange sample
    ↓
Next measurement
```

In this workflow, robot-control APIs must be reliable as measurement-sequence commands, rather than merely substitutes for manual operation.

## Scope of the Common API

The common interface directly covers:

- Connection  
- Current position  
- Current joint angles  
- Taught-point management  
- Single-point motion  
- Multi-point motion  
- Joint-axis motion  
- IO  
- TCP / Tool  
- Status retrieval  
- Error Information  
- Recovery assistance  

The following are instead treated as robot-specific extensions:

- Manufacturer-specific scripts  
- Robot-specific hands/grippers  
- Manufacturer-specific file transfer  
- Specialized UI operations  
- Teach Pendant-specific functions  

## Relationship to Device Servers

The common interface is designed for eventual deployment through a device-server layer such as `ese774_frame`.

The important constraint is that UR-specific implementation details must not enter the framework layer.

```text
ese774_frame
    Generic framework

URCtrl
    UR-specific implementation

CobottaCtrl
    COBOTTA-specific implementation
```

The server layer exposes the common interface and selects `URCtrl` or `CobottaCtrl` as the concrete implementation.