# URCtrl 制御マニュアル

`URCtrl` は、Universal Robots を Python から制御するための単独ラッパーではない。研究現場で複数の協働ロボットを同じ操作 API で扱うための、ロボット共通 I/F の UR 実装である。

本プロジェクトの目的は、COBOTTA から UR へ最小移植することではない。COBOTTA と UR を同程度の抽象度で扱える共通 API を定義し、研究者が装置制御・実験自動化・SPring-8 BL774 型の運用に利用できるシステムを提供することである。

したがって `URCtrl` は、COBOTTA 互換を参考にしつつも、COBOTTA を絶対基準とはしない。UR 実装で得られた妥当な設計は、逆に `cobotta_ctrl` 側へ反映され得る。

---
```{toctree}
:maxdepth: 2
:caption: Contents:

design_philosophy
common_interface_system
quickstart
units_and_pose
connection
variables
motion_api
state_api
io_tool_api
error_recovery
api_reference
tutorials
implementation_policy

```
---

## 目的

・研究者が使いやすい協働ロボット共通 API を提供する。  
・COBOTTA / UR などの機種差を上位実験コードから隠蔽する。  
・ロボット制御を、実験装置制御システムの一部として扱えるようにする。  
・BL774 型、SPring-8 互換の実験自動化構成に接続できる設計にする。  
・特定ロボットメーカーの API ではなく、研究用ロボット操作 API として整える。  

## `URCtrl` の位置づけ

```text
実験スクリプト
    ↓
ロボット共通 I/F
    ↓
URCtrl / CobottaCtrl / 将来の他ロボット実装
    ↓
各ロボット固有 API
    ↓
ロボット本体
```

`URCtrl` はこのうち、UR 用の実装である。`cobotta_ctrl` は COBOTTA 用の実装である。両者は上下関係ではなく、同じ共通 I/F に従う兄弟実装である。

## 目次

・ [設計思想](./design_philosophy.md)  
・ [共通 I/F と BL774 型システム](./common_interface_system.md)  
・ [クイックスタート](./quickstart.md)  
・ [単位と座標表現](./units_and_pose.md)  
・ [接続と初期化](./connection.md)  
・ [仮想変数 P/I/F/IO](./variables.md)  
・ [移動 API](./motion_api.md)  
・ [状態監視](./state_api.md)  
・ [IO と TCP](./io_tool_api.md)  
・ [エラー処理と復旧](./error_recovery.md)  
・ [API Reference](./api_reference.md)  
・ [チュートリアル](./tutorials.md)  
・ [実装差分と移植方針](./implementation_policy.md)  

## 最小例

```python
from ur.ur_ctrl import UrCtrl, MotionMode

ROBOT_IP = "10.170.10.56"

with UrCtrl(ROBOT_IP) as robot:
    current = robot.current_position

    if current is not False:
        target = list(current)
        target[2] += 10.0

        robot.move(
            target,
            motion_mode=MotionMode.LINE,
            speed=20,
            accel=20,
            is_async=False,
        )
```

公開 I/F の P 座標は `[x, y, z, rx, ry, rz]` であり、位置は mm、姿勢は degree 表記の rotation vector である。J 座標は degree である。speed / accel / decel は 0 < value <= 100 の百分率である。

---
## 作者
- Kengo NAKADA