# 設計思想

## 主目的

`URCtrl` の主目的は、COBOTTA から UR への最小移植ではない。

主目的は、研究者が複数の協働ロボットを同じ操作感で扱うための、ロボット共通 I/F を提供することである。

COBOTTA 互換は重要である。しかし、それは既存コードを活かすための手段であって、設計の最終目的ではない。`URCtrl` で妥当な API 設計が明確になれば、`cobotta_ctrl` 側を修正して共通 I/F に寄せることもある。

## ロボット共通 I/F の考え方

本プロジェクトでは、ロボットを「メーカー固有 API の集合」として扱わない。研究装置の一要素として、以下の共通操作に整理する。

・接続する  
・現在位置を取得する  
・現在関節角を取得する  
・位置を教示する  
・位置へ移動する  
・複数点を移動する  
・IO を読む / 書く  
・TCP / Tool を設定する  
・状態を読む  
・エラーを表示する  
・安全停止から復旧を試みる  
・接続を閉じる  

これらは COBOTTA でも UR でも必要になる。違うのは内部実装である。

## 共通 I/F と実装の分離

共通 I/F は、研究者が直接使う層である。実装層は、各ロボット固有 API を呼ぶ層である。

```text
共通 I/F
    move()
    teach()
    get_current_position()
    set_IO()
    reset_error()

UR 実装
    RTDEControlInterface
    RTDEReceiveInterface
    RTDEIOInterface
    DashboardClient

COBOTTA 実装
    ORiN2 / b-CAP / RC8
    Controller
    Variable
    IO
```

この分離により、上位実験コードは `UR` か `COBOTTA` かを意識しない。

## COBOTTA は基準ではなく既存実装の一つ

過去の `cobotta_ctrl` は重要な先行実装である。ただし、共通 I/F の絶対基準ではない。

たとえば COBOTTA には RC8 変数 `P1` があるが、UR にはない。したがって、共通 I/F では `P1` を「ロボット内部変数」と定義しない。`P1` は「共通 I/F の教示点名」と定義し、各実装がそれをどう保存するかを決める。

UR では `RobotVarManager` により JSON 保存する。COBOTTA 側は RC8 変数を利用してもよいし、将来的には共通管理へ寄せてもよい。

## BL774 型・SPring-8 互換

本 I/F は、単にロボット単体を動かすためのものではない。SPring-8 のビームライン実験、自動測定、試料交換、治具操作、カメラ・検出器・測定器との連携を前提にする。

したがって、API は以下を満たす必要がある。

・実験スクリプトから短く呼べる。  
・失敗時に状態が読める。  
・非専門家でも mm / degree / % で扱える。  
・ロボットごとの差分をドキュメント化する。  
・サーバー化、遠隔操作、自動測定に接続しやすい。  
・SPring-8 互換の装置制御層に置ける。  

## 単位の方針

研究者向け I/F では SI 単位だけをそのまま露出しない。

UR RTDE は m / rad を使うが、実験現場では mm / degree の方が直感的である。そのため `URCtrl` の公開 I/F は次の単位に統一する。

| 種類 | 公開 I/F |
|---|---|
| P 座標位置 | mm |
| P 座標姿勢 | degree 表記の rotation vector |
| J 座標 | degree |
| speed / accel / decel | % |

RTDE 境界では m / rad へ変換する。

## 成功・失敗の方針

共通 I/F では、多くの操作は `True` / `False` を返す。失敗時には内部で例外と状態を記録し、`error_description` や `get_current_error_info()` で取得する。

これは研究者が実験スクリプト内で簡潔に制御できるようにするためである。

```python
ok = robot.move("P1")

if not ok:
    print(robot.error_description)
```

## 未対応機能の方針

ロボット固有機能は、共通 I/F に入れるべきものと入れるべきでないものを分ける。

COBOTTA 固有の PacScript、専用ハンド、RC8 ファイル転送は、UR 共通 I/F には入れない。UR 側では未対応として False を返し、エラー情報に明示する。

逆に、UR で自然に整理できた状態監視・安全状態取得は、COBOTTA 側へ逆輸入する対象になり得る。