ur.hand package

Submodules

ur.hand.robotiq_hand module

Robotiq グリッパ固有の低レベル制御クラス。

このモジュールは、Universal Robots 上で動作する Robotiq Grippers URCap が 公開する TCP ソケットへ接続し、Robotiq の ASCII コマンドを送受信する。

本モジュールが扱う position、speed、force は、すべて Robotiq 固有のデバイス値である。値域は原則として 0 から 255 であり、 mm、N、% などの物理量ではない。

ロボット共通 I/F、COBOTTA 互換 I/F、物理単位からデバイス値への変換、 および使用するハンドメーカーの選択は上位の UrCtrl が担当する。 このクラスは Robotiq 固有プロトコルの通信と状態取得だけを担当する。

基本的な使用順序は次のとおりである。

1. connect() で Robotiq URCap の TCP ポートへ接続する。

2. activate() でグリッパを起動状態へ移行する。

3. open()、close()、move() でグリッパを動作させる。

4. disconnect() でソケットを閉じる。

同一ソケット上のコマンド送受信は内部ロックで直列化される。ただし、 複数スレッドから同時に高レベル動作命令を発行した場合の動作順序までは 保証しないため、呼び出し側で動作シーケンスを管理すること。

class RobotiqGripperStatus(*values)

Bases: Enum

Robotiq グリッパの起動状態を表す列挙型。

STA 変数の値を Python 側で扱いやすくするために使用する。 Robotiq プロトコルで未使用の値は列挙していない。

ACTIVATING = 1

ACTIVE = 3

RESET = 0

class RobotiqHand(robot_ip, config=None, logger=None, log_level=None)

Bases: object

Robotiq グリッパ固有プロトコルを扱う低レベル制御クラス。

position、speed、force はすべて Robotiq のデバイス値 0 から 255 で扱う。単位変換や他ロボットとの互換処理は行わない。

接続先は Robotiq Grippers URCap が動作する Universal Robots 本体であり、 グリッパへ直接 TCP 接続するクラスではない。

Notes

• connect() 前に動作命令を実行すると RuntimeError となる。

• activate() の既定値では自動校正を実行しない。

• auto_calibrate() は開閉動作を伴うため、周囲に障害物がないことを 確認してから明示的に実行する。

• open() と close() は低レベル API であり、speed と force を Robotiq デバイス値で指定する必要がある。

Parameters:

• robot_ip (str)

• config (RobotiqHandConfig | None)

• logger (Any | None)

• log_level (str | None)

ACT = 'ACT'

ADR = 'ADR'

ATR = 'ATR'

DEFAULT_PORT = 63352

ENCODING = 'UTF-8'

FLT = 'FLT'

FOR = 'FOR'

GTO = 'GTO'

MAX_FORCE = 255

MAX_FORCE_N = 235.0

MAX_POSITION = 255

MAX_POSITION_MM = 85.0

MAX_SPEED = 255

MAX_SPEED_MM_S = 150.0

MIN_FORCE = 0

MIN_FORCE_N = 20.0

MIN_POSITION = 0

MIN_POSITION_MM = 0.0

MIN_SPEED = 0

MIN_SPEED_MM_S = 20.0

OBJ = 'OBJ'

POS = 'POS'

PRE = 'PRE'

SPE = 'SPE'

STA = 'STA'

_require_socket()

接続済みソケットを返す。

Returns:

現在保持している接続済み TCP ソケット。

Raises:

RuntimeError – connect() が完了していない場合。

Return type:

socket

activate(auto_calibrate=False)

グリッパを起動状態へ移行する。

すでに起動済みの場合は activation シーケンスを再実行しない。 auto_calibrate を True にした場合だけ、起動後に全開・全閉・ 再全開の校正動作を実行する。

Parameters:

auto_calibrate (bool) – True の場合は起動後に auto_calibrate() を 実行する。既定値は False。

Returns:

起動処理が完了した場合は True。ACT=1 の設定が acknowledge されなかった場合は False。

Return type:

bool

Notes

自動校正は実際の開閉動作を伴う。通常の起動では既定値の False を使用し、校正が必要な場合だけ明示的に有効化する。

auto_calibrate()

全開・全閉動作からデバイス値の可動範囲を校正する。

全開、全閉、再全開の順に動作させ、実際に到達した位置を _min_position と _max_position に保存する。

Returns:

校正が完了した場合は True。

Raises:

RuntimeError – 各校正動作が目標位置へ到達しなかった場合。

Return type:

bool

Warning

このメソッドはグリッパを実際に開閉する。指や治具、試料が 可動範囲内にないことを確認してから実行すること。

close(speed, force, wait=True)

Robotiq の全閉位置へ移動する。

Parameters:

• speed (int) – 閉動作速度の Robotiq デバイス値 0 から 255。

• force (int) – 把持力の Robotiq デバイス値 0 から 255。

• wait (bool) – True の場合は停止または目標到達まで待機する。

Returns:

wait=True の場合は (current_position, object_status)。 wait=False の場合は (acknowledged, requested_position)。

Return type:

Tuple[bool, int] | Tuple[int, RobotiqObjectStatus]

connect()

Robotiq Grippers URCap の TCP ソケットへ接続する。

すでに接続済みの場合は新しいソケットを作成せず True を返す。

Returns:

接続済み、または接続に成功した場合は True。

Raises:

OSError – TCP ソケットの作成または接続に失敗した場合。

Return type:

bool

disconnect()

Robotiq Grippers URCap との TCP ソケット接続を閉じる。

未接続の場合も正常終了として扱う。shutdown() が失敗した場合でも ソケットを閉じ、内部の接続参照を解除する。

Returns:

切断処理が完了した場合は True。

Return type:

bool

emergency_release(direction_open, wait=True)

Robotiq の auto-release を実行する。

Parameters:

• direction_open (bool) – True の場合は開方向、False の場合は 閉方向へ auto-release する。

• wait (bool) – True の場合は OBJ が MOVING 以外になるまで待つ。

Returns:

コマンドが acknowledge され、必要な待機処理が完了した場合は True。コマンドが拒否された場合は False。

Return type:

bool

Warning

auto-release は非常時の解放動作である。通常の開閉命令の代用には 使用しないこと。

get_closed_position()

全閉として使用するデバイス位置を返す。

Return type:

int

get_current_position()

グリッパの現在位置 POS を取得する。

Return type:

int

get_fault_status()

Robotiq の fault status FLT を整数値で取得する。

Return type:

int

get_max_position()

現在設定されている閉側の最大デバイス位置を返す。

Return type:

int

get_min_position()

現在設定されている開側の最小デバイス位置を返す。

Return type:

int

get_object_status()

物体検出状態 OBJ を列挙型で取得する。

Return type:

RobotiqObjectStatus

get_open_position()

全開として使用するデバイス位置を返す。

Return type:

int

get_requested_position()

グリッパが保持する要求位置 PRE を取得する。

Return type:

int

get_status()

Robotiq 固有の主要状態を辞書で返す。

Returns:

active、position、object_status、fault_status、 is_open、is_closed を含む辞書。

Return type:

Dict[str, int | bool | RobotiqObjectStatus]

get_variable(variable)

Robotiq 変数を1個取得する。

Parameters:

variable (str) – 取得する Robotiq プロトコル変数名。

Returns:

応答に含まれる整数値。

Raises:

• RuntimeError – TCP 接続されていない場合。

• ValueError – 応答形式または応答変数名が期待と一致しない場合。

• OSError – ソケット送受信に失敗した場合。

Return type:

int

is_active()

グリッパが起動済みか確認する。

Returns:

STA が ACTIVE の場合は True。

Return type:

bool

is_closed()

現在位置が全閉位置以上か判定する。

Return type:

bool

is_connected()

TCP ソケットの参照を保持しているか返す。

Returns:

connect() 後かつ disconnect() 前であれば True。

Return type:

bool

is_open()

現在位置が全開位置以下か判定する。

Return type:

bool

move(position, speed, force)

Robotiq のデバイス値を指定して移動を開始する。

指定値は許容範囲へクリップした後、POS、SPE、FOR、 GTO を1回の SET コマンドで送信する。このメソッドは動作完了を 待機しない。

Parameters:

• position (int) – 目標位置のデバイス値。小さい値が開側、大きい値が閉側。

• speed (int) – 動作速度のデバイス値 0 から 255。

• force (int) – 把持力のデバイス値 0 から 255。

Returns:

(acknowledged, resolved_position)。第1要素はコマンドが acknowledge されたか、第2要素はクリップ後に送信した目標位置。

Raises:

RuntimeError – TCP 接続されていない場合。

Return type:

Tuple[bool, int]

move_and_wait_for_position(position, speed, force)

移動を開始し、停止または目標到達まで待機する。

move() の acknowledge を確認した後、要求位置 PRE が 送信位置へ更新されるまで待機する。その後、OBJ が MOVING 以外に なるまで監視する。

Parameters:

• position (int) – 目標位置の Robotiq デバイス値。

• speed (int) – 動作速度の Robotiq デバイス値。

• force (int) – 把持力の Robotiq デバイス値。

Returns:

(current_position, object_status)。現在位置と停止理由を返す。

Raises:

RuntimeError – 移動コマンドが acknowledge されなかった場合。

Return type:

Tuple[int, RobotiqObjectStatus]

open(speed, force, wait=True)

Robotiq の全開位置へ移動する。

Parameters:

• speed (int) – 開動作速度の Robotiq デバイス値 0 から 255。

• force (int) – 開動作時の力の Robotiq デバイス値 0 から 255。

• wait (bool) – True の場合は停止または目標到達まで待機する。

Returns:

wait=True の場合は (current_position, object_status)。 wait=False の場合は (acknowledged, requested_position)。

Return type:

Tuple[bool, int] | Tuple[int, RobotiqObjectStatus]

property port: int

Robotiq URCap へ接続する TCP ポート番号を返す。

reset()

Robotiq の activation と auto-release を解除する。

ACT=0 および ATR=0 を設定し、グリッパ状態が RESET に 遷移するまで待機する。これは activate() の前処理として使用する。

Returns:

リセット状態への移行が完了した場合は True。

Raises:

• RuntimeError – TCP 接続されていない場合。

• ValueError – Robotiq から不正な応答を受信した場合。

Return type:

bool

property robot_ip: str

Robotiq URCap が動作する Universal Robots の IP アドレスを返す。

set_variable(variable, value)

Robotiq 変数を1個設定する。

Parameters:

• variable (str) – Robotiq プロトコルの変数名。

• value (int | float) – 送信する数値。

Returns:

ack を受信した場合は True。

Return type:

bool

set_variables(variables)

Robotiq 変数を1コマンドでまとめて設定する。

OrderedDict の順序で SET コマンドを組み立てる。同一ソケット上の 送受信は _command_lock で排他制御する。

Parameters:

variables (OrderedDict[str, int | float]) – 変数名と値を保持する OrderedDict。

Returns:

応答が厳密に b"ack" である場合は True。

Raises:

• RuntimeError – TCP 接続されていない場合。

• OSError – ソケット送受信に失敗した場合。

Return type:

bool

class RobotiqHandConfig(port=63352, socket_timeout=2.0)

Bases: object

Robotiq ハンド固有の通信設定。

Parameters:

• port (int)

• socket_timeout (float)

port

Robotiq Grippers URCap が公開する TCP ポート番号。 通常は 63352 を使用する。

Type:

int

socket_timeout

TCP 接続および送受信のタイムアウト秒数。

Type:

float

port: int = 63352

socket_timeout: float = 2.0

class RobotiqObjectStatus(*values)

Bases: Enum

Robotiq グリッパの物体検出状態を表す列挙型。

OBJ 変数は、移動中、外側から物体へ接触した状態、内側から物体へ 接触した状態、目標位置へ到達した状態を表す。

AT_DESTINATION = 3

MOVING = 0

STOPPED_INNER_OBJECT = 2

STOPPED_OUTER_OBJECT = 1

ur.hand.robotiq_hand_interface module

RobotiqHand 用の共通ハンド I/F 引数変換。

class RobotiqHandInterface(hand)

Bases: object

共通ハンド I/F の引数を RobotiqHand 用の値へ変換する。

このクラスはハンドの通信や制御を行わない。 共通 I/F の position [mm]、force [N]、speed [%] を、 対応する RobotiqHand が受け取る raw 値へ変換する。

DEFAULT_FORCE_RAW = 255

DEFAULT_SPEED_PERCENT = 100.0

_convert_force(force)

把持力 [N] を Robotiq raw 値へ変換する。

force が指定されていない位置指令では、Robotiq の通信上必要な force 値として内部既定値を使用する。

_convert_position(position)

開口幅 [mm] を Robotiq raw 位置へ変換する。

_convert_speed(speed)

動作速度 [%] を Robotiq raw 値へ変換する。

convert(pos=None, *, position=None, force=None, direction=True, relative=False, speed=None)

共通 I/F の引数を RobotiqHand 用に一括変換する。

Parameters:

• pos – 開口幅 [mm]。position の互換引数。

• position – 開口幅 [mm]。

• force – 把持力 [N]。指定時は力による開閉指令として扱う。

• direction – force 指定時の方向。 True は閉方向、False は開方向。

• relative – 相対位置指定かどうか。 現在は RobotiqHand では未対応。

• speed – 動作速度 [%]。

Returns:

RobotiqHand の move() または move_and_wait_for_position() に渡す辞書。

Raises:

ValueError – 引数または変換範囲が不正な場合。

property max_position

完全に開いたときの開口幅 [mm] を返す。

property min_position

完全に閉じたときの開口幅 [mm] を返す。