# 公開制御I/Fの実装境界と使用上の注意

このページは `src/dobot/dobot_ctrl.py` および `src/dobot/dobot_tcp.py` の実装を基準とする。**プロジェクト共通制御I/F**は COBOTTA・UR・MG400 の各実装で共用する操作体系であり、`DobotCtrl` はその **MG400向けアダプター**である。MG400のメーカーAPI自体を共通I/Fと呼ぶものではない。

## 公開クラスと実装クラス

`DobotCtrl.__init__(dobot_ip="192.168.1.6", instance_name="Ctrl", logger=None, log_level=None, auto_connect=True)` は内部に `DobotTcp` を作成する。`connect()`、`disconnect()`、`get_current_pose()` などは `DobotTcp` に委譲する。ローカル・リモートのいずれも制御対象は同じMG400であり、リモート構成は `ese774_frame` が呼出しを転送するだけである。

## 移動APIの引数を読み違えない

`move(target, *, motion_mode=None, coord_type=None, path_blend=None, offset=None, pose=None, speed=None, accel=None, decel=None, is_async=True)` は共通I/Fの形を保つ。MG400側の実装は **P+PTP→MovJ、P+LINE→MovL、J+PTP→JointMovJ** を対象とする。`path_blend`、`decel`、`pose`、`CIRCLE`、`SPLINE` は意味を保持した実装が確認できていない。引数が受理されることを、対応する動作が実装済みである証拠として扱わない。

`drive(target, *, relative=False, path_blend=None, speed=None, is_async=False)` は軸指定・相対移動・速度指定を扱うが、`path_blend` は未確定である。`dev(base, offset)` はMG400で表現できる **x/y/z/rz** の単純加算に限られ、**rx/ry および J5/J6** は4軸のMG400では実現できない。

`rotate(plane, angle, center, *, path_blend=None, speed=None, is_async=True)` は公開されていても軌道コマンドへの変換が未実装である。`halt()`、`stop()`、`task_stop()` は共通I/Fと同義の停止動作が保証されないため、非常停止の代用として使用してはならない。

## 同期・非同期の2つの意味

`SyncDobotClient` / `AsyncDobotClient` は **HTTP呼出し側**の同期方式を選ぶ。`move(..., is_async=...)` は **MG400の動作完了待ち**に関係する。HTTP要求の成功と、実機が安全に目標位置へ到達したことは同義ではない。`wait_for_complete()` の適用と、状態・アラームの確認を別途行う。

## メーカー資料との関係

メーカーのDobotStudio Proユーザーマニュアル（MG400 & M1 Pro）は接続・座標系・安全設定を説明する資料であり、本PythonライブラリのAPI仕様書ではない。MG400メンテナンスマニュアルV1.2（2026-04-23）は点検・安全・アラームの根拠資料である。メーカー資料の操作説明からPython APIの実装済み範囲を推定しない。

## 導入時の確認

1. メーカーの安全手順に従い、可動域・ツール・ペイロード・非常停止手段を確認する。
2. MG400の接続先IPと、HTTPサーバーの待受IP/ポートを別々に確認する。
3. まず読取系APIで接続と状態を検証し、移動命令は安全確認後に実行する。
4. 対応未確認の共通I/F操作は使用せず、実機のアラーム・動作完了を監視する。