クイックスタート

はじめに

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

始める前に

Linux および Apple シリコン搭載の Mac に対応しています。SDK のシステム要件を参照してください。サンプルでは Python 3.10 以降を使用します。

シミュレーション確認

このセクションでは Git、Rust/Cargo、urdf-viz が必要です。デバイスは不要です。

Wuji Glove には、座標系、関節、データマッピングを確認するための 21 自由度の手の骨格モデルが付属しています。

cargo install を実行する前に Rust/Cargo をインストールしてください。urdf-viz のインストールガイドを参照してください。

git clone https://github.com/wuji-technology/wuji-description.git
cd wuji-description
cargo install urdf-viz

urdf-viz glove/body/urdf/right.urdf

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

左手モデルおよび EMF モジュールの STL ファイルについては、モデルアセットと読み込みを参照してください。送信機カバーの STEP ファイルと 3 種類の取り付けアタッチメントについては、機械的統合を参照してください。

完了条件：骨格モデルが正しく描画され、21 個の回転関節がすべて表示されていること。

モデルが読み込めれば、アセットと可視化の経路が正常に動作していることが確認できます。触覚、EMF、IMU のデータにはデバイスの接続が必要なため、次のセクションに進んでください。

実機での実行

このセクションでは、Wuji Glove 1 台、データ収集ボード、付属のケーブル、および SDK のシステム要件を満たすコンピューターが必要です。

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

同梱品をすべて同梱物一覧と照合してください。USB-C to USB-C ケーブル、USB-C to Ethernet 電源アダプター、USB-A to USB-C ケーブル、Ethernet ケーブルが含まれています。

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

pip install wuji-sdk
curl -fsSL https://get.wuji.tech/cli | bash

Wuji SDK はコードからグローブのデータを読み取り、Wuji CLI はターミナルからデバイスのスキャン、キャリブレーション、ヘルスチェックを実行します。インストールと環境要件については、Wuji SDK クイックスタートおよび Wuji CLI のインストールを参照してください。

ステップ 3：データ収集ボードの接続

USB-C to USB-C ケーブルを使用して、データ収集ボードを USB-C to Ethernet 電源アダプターに接続します。

ステップ 4：Ethernet と電源の接続

USB-C to Ethernet 電源アダプターを使用して、Ethernet ケーブルと電源ケーブルを接続します。電源ケーブルには USB-A to USB-C ケーブルを推奨します。接続後、データ収集ボードのインジケーターが正常であることを確認してください。

ステップ 5：コンピューターのネットワーク設定

コンピューターとグローブが同じネットワークセグメント上にあることを確認してください（デフォルトのセグメントは 192.168.1.x です）。IP アドレスの最初の 3 つのオクテットを一致させ、サブネットマスクを 255.255.255.0 に設定してください。デフォルトの IP は、左手が 192.168.1.100、右手が 192.168.1.101 です。競合を避けるため、これらのアドレスをコンピューターに割り当てないでください。

macOS 13 以降では、System Settings › Network › Ethernet › Details › TCP/IP（システム設定 › ネットワーク › Ethernet › 詳細 › TCP/IP）を開きます。macOS 11〜12 では、System Preferences › Network › Ethernet › Advanced › TCP/IP（システム環境設定 › ネットワーク › Ethernet › 詳細 › TCP/IP）を開きます。Configure IPv4（IPv4 の構成）を Manually（手入力）に設定し、同じサブネット上の IP と上記のサブネットマスクを入力します。ネットワークの権限については、デバイスの検出と接続を参照してください。

Ubuntu では、次のいずれかの方法を選択してください。

方法 1：グラフィカルインターフェース

1. Settings（設定）を開き、Network（ネットワーク）に移動します
2. Wired（有線）の行にある歯車アイコンをクリックします
3. IPv4 タブに切り替え、IPv4 Method（IPv4 メソッド）で Manual（手動）を選択します
4. Addresses（アドレス）で、Address に 192.168.1.50、Netmask に 255.255.255.0 を入力します
5. Apply（適用）をクリックします
6. ターミナルで ping 192.168.1.101 を実行し、疎通を確認します

方法 2：コマンドライン

コマンド内のインターフェース名は、実際のインターフェース名に置き換えてください。この方法で設定したアドレスは、システムの再起動後に失われます。

1. ネットワークインターフェース名を確認する

ip link show

Ethernet インターフェース名（例：eth0、enp3s0、eno1）を確認します。

2. Ethernet ケーブルが接続されていることを確認する

ethtool eth0 | grep "Link detected"

出力に Link detected: yes と表示されるはずです。

3. 既存の IP アドレスを消去する

sudo ip addr flush dev eth0

4. 固定 IP とサブネットマスクを設定する

sudo ip addr add 192.168.1.50/24 dev eth0

5. インターフェースを有効化する

sudo ip link set eth0 up

6. IP とサブネットマスクを確認する

ip addr show eth0

出力に inet 192.168.1.50/24 が含まれていることを確認します。

7. 疎通をテストする

# 右手グローブの例
ping 192.168.1.101

左手グローブに接続する場合は、代わりに ping 192.168.1.100 を使用してください。応答があれば接続は成功です。

ステップ 6：Wuji Glove の装着

Wuji Glove を装着し、アームストラップでデータ収集ボードの位置を調整します。

ステップ 7：Tracker の取り付け（任意）

外部の Tracker を空間トラッキングに使用する場合は、グローブ背面の EMF 送信機モジュールのソフトカバーをめくり、露出した取り付けプレートに Tracker を取り付けます。

Tracker の機種によって必要なアダプターが異なります。アダプターの STEP ファイルと組み立ての注意事項については、アタッチメントの STEP ファイルを参照してください。

ステップ 8：デバイスがオンラインであることの確認

wuji devices
wuji ping
wuji doctor

wuji devices は同じサブネット上のデバイスを一覧表示し、wuji ping はデバイスの種類、シリアル番号、ファームウェアバージョン、IP を返します。wuji doctor はヘルスチェックを実行し、EMF の断線や、触覚センサーのデッドポイント、デッド行、デッド列を特定します。

一覧が空の場合は、デバイスに電源が供給されていること、およびホストがグローブと同じサブネット上にあることを確認してください。

ステップ 9：デバイスへの接続と状態の確認

from wuji_sdk import SdkManager

manager = SdkManager.instance()
glove = manager.auto_connect(device_name="glove")

print(glove.sn().get())         # シリアル番号
print(glove.version().get())    # ファームウェアバージョン
print(glove.hand_side().get())  # 左右の別

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

グローブに同時に接続できるクライアントは 1 つだけです。wuji viz や別の SDK スクリプトがすでに同じグローブに接続している場合、この接続は確立できないため、実行中のクライアントを終了してから再試行してください。使用中のデバイス接続の解放を参照してください。

データ収集ボードのインジケーターランプは接続状態を示します。黄色の非常にゆっくりとした点滅は、ホストは接続済みだがデータを取得していない状態、シアンのハートビート点滅はデータ送信中の状態を示します。赤の速い点滅は Ethernet リンクの切断、赤の点灯はセンサーのハードウェア故障を示します。各状態への対処方法については、接続状態とインジケーターランプを参照してください。

ステップ 10：キャリブレーションの実行

ハンドモデルのキャリブレーションはユーザーごとに分離されており、Default ユーザーでは実行できません。名前付きのプロファイルを作成して切り替えてから、キャリブレーションを行ってください。

wuji user create operator --switch
wuji calib hand-model

キャリブレーションの前に、指先モジュール同士を交差させたり拳を握ったりせず、指を軽く曲げてリラックスした状態を保ってください。キャリブレーション結果は現在のユーザープロファイルに保存されて直ちに有効になり、そのユーザーの左手および右手のモデルが生成されます。

キャリブレーションは、関節角度、骨格、指先姿勢の精度を左右します。接触検出を行う場合は、触覚キャリブレーションも実行してください。全パラメーターとエラー処理については、Wuji CLI のハンドモデルキャリブレーションを参照してください。

ステップ 11：最初のデータフレームの取得

wuji sub tactile --count 1
wuji sub emf_poses --count 1
wuji sub imu_data/palm --count 1

--count 1 を指定すると、完全なフレームを 1 つ受信した時点で終了します。アプリケーションでデータを読み取るには、Wuji SDK でグローブに接続し、tactile、emf_poses、または hand_skeleton をサブスクライブします。

触覚の値がすべて 0 または -1 になる、EMF の信頼度が低い、IMU が継続的にドリフトする、といった場合はトラブルシューティングを参照してください。

各ストリームの意味、構造、座標系、タイムスタンプについては、SDK データリファレンスを参照してください。

データを視覚的に確認するには、wuji viz を実行し、ブラウザーで手の骨格、EMF 受信機、触覚点群、生の触覚マトリクスを表示します。コマンドの詳細については、ライブ可視化を参照してください。

ステップ 12：停止とグローブの取り外し

読み取りが完了したら、接続を切断して他のクライアントがグローブを使用できるようにします。

manager.disconnect_all()

グローブを外す際は、指の腹の生地部分に力を加え、EMF モジュールや手の甲を引っ張らないでください。乾燥した涼しい場所に保管し、センサー部分を折り曲げないようにしてください。詳細な要件については、保管と環境を参照してください。

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

最初のデータフレームを受信できたら、ファームウェアを最新バージョンにアップグレードします。

wuji upgrade --check
wuji upgrade --type wuji_glove

--check は読み取り専用で、ファームウェアの更新があるデバイスを一覧表示します。--type wuji_glove は対象範囲内のすべてのグローブをそれぞれの最新バージョンにアップグレードし、書き込み完了後に各デバイスが新しいファームウェアで再起動します。対象範囲と操作オプションの詳細については、Wuji CLI のファームウェアアップグレードを参照してください。

キャリブレーション用インターフェースには、必要な最低限のファームウェアおよび SDK のバージョンがあります。対応関係については、リリースノートのコンポーネントバージョン表を参照してください。

完了条件：デバイスがオンラインで、ヘルスチェックに合格し、ハンドモデルのキャリブレーションが完了し、タイムスタンプと左右情報を含む有効なフレームを 1 つ以上受信し、ファームウェアが最新であること。

製品間の遠隔操作

このセクションでは、実機での実行を完了した Wuji Glove 1 台と、クイックスタートを完了して 20 個の関節がすべてオンラインになっている Wuji Hand 2 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 のハンドリターゲティングを参照してください。ハンドトラッキングの座標系の規約とタイムスタンプの同期については、SDK データリファレンスを参照してください。

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