クイックスタート

はじめに

ROS 2 アプリケーションを接続する場合は、デバイスの安全準備と物理的な接続を完了したうえで、ROS 2 との統合に従ってください。SDK を直接使用する場合は、このページを続けてお読みください。統合ページには、ROS 2 の環境およびインストール要件が記載されています。

始める前に

Linux および Apple シリコン搭載の Mac に対応しています。SDK のシステム要件を参照してください。サンプルでは Python 3.10 以降を使用します。ハードウェアを扱う前に、ご使用上の注意をお読みください。

シミュレーション確認

このセクションでは Git、Python、MuJoCo が必要です。デバイスは不要です。

MuJoCo をインストールし、右手モデルを読み込みます。

git clone --depth 1 https://github.com/wuji-technology/wuji-description.git
cd wuji-description
pip install mujoco

python -m mujoco.viewer --mjcf=hand2/hand2_2/body/mjcf/right.xml

ウィンドウが開いたら、メッシュの欠落がなくモデルが完全であること、および 20 個の関節があることを確認してください。

どちらのモデルにもアームフランジマウントが含まれています。左手モデルや URDF、ROS 2、Isaac Sim での読み込みについては、モデルアセットと読み込みを参照してください。手のひら取付インターフェースの STEP データおよび A3 図面については、機構的な統合を参照してください。

完了条件：20 個の回転関節すべてを含むモデルが正しく描画されること。

モデルが読み込めれば、アセットと可視化の経路が正常に機能していることが確認できます。ファームウェア、ネットワーク、実機制御の検証にはデバイスが必要なため、次のセクションへ進んでください。

実機での実行

このセクションでは、Wuji Hand 2 を 1 台、付属の電源および各種ケーブル、SDK のシステム要件を満たすコンピューターが必要です。

ステップ 1：開梱時の確認

箱の中身を同梱品と照らし合わせて確認してください：電源アダプター、AC ケーブル、RJ45 ケーブル、XT30 延長ケーブル、アダプターマウント、アダプターフランジ。不足しているものがある場合は、作業を続ける前に HumansX（日本正規代理店）までお問い合わせください。

ステップ 2：ソフトウェアのインストール

pip install wuji-sdk

インストールの詳細と環境要件については、Wuji SDK クイックスタートを参照してください。

初回の実行時には、Wuji CLI もインストールしてください。ターミナルからデバイスのスキャンと接続、パラメーターの読み書き、デバイスの状態確認、ファームウェアのアップグレードを行えます。

ステップ 3：ケーブルの接続と電源投入

1. 付属の RJ45 ケーブルで、デバイスのネットワークポートとコンピューターのネットワークポートを接続します。
2. 付属の XT30 延長ケーブルで、デバイスと電源アダプターを接続します。先にデバイス側を接続し、その後アダプターを差し込んでください。
3. 電源投入後、手の甲のステータスランプを確認します：青色の呼吸点灯（セルフチェック）→ 白色の呼吸点灯（準備完了）。

インターフェースの位置については、製品紹介を参照してください。30 秒経過してもランプが白色の呼吸点灯にならない場合は、トラブルシューティングを参照してください。

ステップ 4：ホストのネットワークアダプターの設定

本デバイスは固定 IP を使用し、DHCP には対応していません。工場出荷時のアドレスは次のとおりです。

コンピューターのネットワークアダプターに、同一サブネット内の固定 IP（例：192.168.1.50）とサブネットマスク 255.255.255.0 を設定します。その後、疎通を確認します。

ping 192.168.1.110 # 左手。右手は 192.168.1.111

ステップ 5：デバイスのオンライン確認

wuji devices
wuji ping

wuji devices は同一サブネット上のデバイスを一覧表示し、wuji ping はデバイスの種類、シリアル番号、ファームウェアバージョン、IP を返します。一覧が空の場合は、電源、ネットワークケーブル、アダプターの設定を確認してから再度実行してください。

同一サブネット上に複数のデバイスがある場合は、--sn を指定して対象デバイスを特定し、誤ったデバイスへの接続を防いでください。

ステップ 6：デバイスの接続

from wuji_sdk import SdkManager

manager = SdkManager.instance()
hand = manager.auto_connect(device_name="wuji_hand_2")

サブネット上に複数のデバイスがある場合は、代わりに manager.connect(sn="<serial number>") を使用してください。アドレスや左右の別による接続など、その他の接続方法については、Wuji SDK のデバイス接続を参照してください。

ステップ 7：状態の確認

20 個の関節すべてがオンラインで、アクティブなエラーコードがないことを確認します。

from wuji_sdk import WujiHand2

print(hand.online_joints_count().get()) # 20 になるはずです

sub = hand.joint_diagnostics().subscribe()
frame = None
while frame is None:
    frame = sub.recv()
for j in frame.joints:
    if j.error_code_current:
        print(j.nid, WujiHand2.describe_error(j.error_code_current))
sub.close()

オンラインの関節が 20 個未満の場合、またはエラーコードがアクティブな場合は、作業を続ける前にトラブルシューティングに従って対処してください。

ステップ 8：関節の有効化

import time

hand.enable()

# オンラインの全関節が Enabled 状態になるまで待機します
sub = hand.joint_diagnostics().subscribe()
deadline = time.monotonic() + 5.0
while time.monotonic() < deadline:
    frame = sub.recv()
    if frame is not None and frame.joints and all(
        j.status_word.ext_state == 2 for j in frame.joints
    ):
        break
else:
    sub.close()
    raise TimeoutError("Joint enable timed out")
sub.close()

ステップ 9：最初の安全な動作の実行

現在の姿勢からゼロ位置へ滑らかに戻します。このサンプルでは、まず各関節の現在位置を読み取り、ゼロ位置をステップ入力として送るのではなく、1.5 秒間の線形補間で目標位置を徐々に小さくしていきます。

import time
from wuji_sdk import JointCommand

# 現在の姿勢を読み取ります。nid は 5 スロット単位のグループで、関節は先頭の 4 つに割り当てられます
sub = hand.joint_states().subscribe()
frame = None
while frame is None:
    frame = sub.recv()
start = [0.0] * 20
for j in frame.joints:
    bus, node_index = divmod(j.nid - 1, 5)
    if bus < 5 and node_index < 4:
        start[bus * 4 + node_index] = float(j.position)
sub.close()

# 最新の SDK サンプルの控えめなパラメーターを使用します
hand.effort_limit().set(1.5)
hand.mit_params().set((3.0, 0.05))

pub = hand.joint_command().publish()
steps = 300 # 1.5 秒 × 200 Hz
for i in range(1, steps + 1):
    ratio = i / steps
    positions = [position * (1.0 - ratio) for position in start]
    pub.send([JointCommand(position, 0.0, 0.0) for position in positions])
    time.sleep(1.0 / 200)
pub.close()

期待される動作：すべての関節が、跳ね返りや衝突なく、現在の姿勢からゼロ位置へ滑らかに戻ります。

単位の規約、MIT 制御モード、パラメーターの安全制限については、制御ガイドを参照してください。

動作を直接確認するには、wuji viz を実行してブラウザーで表示します。3D の手モデルが関節の状態に追従します。コマンドの詳細については、ライブ可視化を参照してください。

ステップ 10：停止と電源オフ

hand.disable() # 全関節を無効化します。ステータスランプは白色の呼吸点灯になります
manager.disconnect_all() # 接続を切断します

電源オフの手順：デバイスが静止していることを確認 → 電源を切断 → ケーブルを取り外します。

緊急時には、いつでも hand.emergency_stop() を呼び出せます。手全体が即座に停止し、この呼び出しにマスクは不要です。

ステップ 11：ファームウェアのアップグレード

最初の動作が正常に完了したら、ファームウェアを最新バージョンにアップグレードしてください。Wuji CLI はデバイスのハードウェア型式に合ったファームウェアパッケージを送信するため、パッケージを手動で選ぶ必要はなく、構造化されたレポートが出力されます。Wuji CLI のファームウェアアップグレードを参照してください。

アップグレード中は電源を切らないでください。ファームウェアと SDK のバージョンの対応関係については、バージョンの識別と相違点を参照してください。

完了条件：20 個の関節すべてがオンラインでアクティブなエラーコードがなく、ゼロ位置への滑らかな復帰が 1 回完了し、ファームウェアが最新であること。

製品間の遠隔操作

このセクションでは、実機での実行を完了した Wuji Hand 2 を 1 台と、キャリブレーション済みでデータを送信できる Wuji Glove を 1 台使用します。両デバイスは同一サブネット上にあり、左右が一致している必要があります。

グローブを装着すると、手のキーポイントが継続的に送信されます。リターゲティングによってそれらが 20 個の関節角度に変換されてハンドへ送られ、ハンドが指の動きにリアルタイムで追従します。

両デバイスのオンライン確認

wuji devices
wuji ping

一覧に wuji_hand_2 と wuji_glove の両方が表示されるはずです。シリアル番号、ファームウェアバージョン、左右の別を確認してください。サブネット上に同じ種類の他のデバイスがある場合は、次のステップのために対象のシリアル番号を控えておいてください。

遠隔操作サンプルの実行

リターゲティングと遠隔操作の完全な実装は Wuji SDK リポジトリのサンプルに含まれており、インターフェースと合わせて更新されます。

git clone https://github.com/wuji-technology/wuji-sdk.git
cd wuji-sdk/examples/python/retargeting
pip install wuji-sdk numpy

python 1.teleop_real.py

サンプルを実行すると、まず SDK ユーザーの一覧が表示されます。初回の実行時は、Enter キーを押してデフォルトのユーザーのまま進めてください。この選択がハンドモデルにどう影響するかについては、遠隔操作用の SDK ユーザーの選択を参照してください。

サンプルはデフォルトで右手アセンブリを対象に動作します。左手アセンブリの場合は、スクリプト冒頭の SIDE 定数を変更してください。

サンプルはデバイスをスキャンし、検出したデバイスに接続します。サブネット上に複数のハンドがある場合は、他の人が使用中のデバイスを動かしてしまわないよう、事前に対象デバイスを確認してください。

製品間の動作の実行

1. ハンドの動作範囲から障害物を取り除き、誰も触れていないことを確認します。
2. 指の力を抜き、軽く曲げた状態でグローブを装着します。
3. サンプルを実行し、まずはゆっくりと小さな動作から始めます。
4. 動作が途切れず連続しているか、方向が一致しているか、エラーコードが発生していないかを確認します。
5. Ctrl+C を押して停止します。終了時に、サンプルはハンドを無効化して接続を切断します。

異常な姿勢、通信の途絶、エラーコードが発生した場合は直ちに停止し、トラブルシューティングに従って対処してください。

リターゲティングのパラメーター、入力形式、座標系の規約については、Wuji SDK のハンドリターゲティングを参照してください。

完了条件：グローブのデータが継続的に更新され、ハンドが指の動きに制御された状態で追従すること。