ROS 2 連携

ハードウェアおよびソフトウェアの統合

wuji_glove_driver は、Wuji Glove の関節角度、トラッキング姿勢、手のひら IMU データ、触覚データを ROS 2 トピックとしてパブリッシュします。このドライバーはモデルの読み込み、TF のパブリッシュ、制御サービスやキャリブレーションサービスの提供は行いません。開始する前に、装着と接続、および必要なキャリブレーションを完了してください。

インストール

ROS 2 Lyrical がインストールされた Ubuntu 26.04 (resolute) を、x86_64 または aarch64 環境で使用してください。以下のコマンドでソースの取得、ROS の読み込み、依存関係と Hand 2 ディスクリプションのインストール、ワークスペースのビルドを行います。ビルド時には、ホストアーキテクチャに対応した Wuji SDK C パッケージがダウンロードされ、検証されます。

# ソースを取得し、ROS 2 を読み込む
git clone https://github.com/wuji-technology/wuji-ros2.git "$HOME/wuji-ros2"
cd "$HOME/wuji-ros2"
source /opt/ros/lyrical/setup.bash
# ビルドツールと依存関係をインストールする
sudo apt-get update
sudo apt-get install -y ros-dev-tools
rosdep update
# Hand 2 ディスクリプションとワークスペースの依存関係をインストールする
scripts/install_hand2_descriptions.sh
rosdep install --from-paths . --ignore-src -r -y
# ワークスペースをビルドする。SDK C パッケージは自動的にダウンロード・検証される
colcon build --cmake-args -DBUILD_TESTING=OFF
# ビルドしたワークスペースを読み込む
source install/setup.bash

ディスクリプションのインストーラーには /etc/apt/sources.list.d/ros2.sources が必要です。このファイルが存在しない場合は、ROS 2 公式のインストール手順に従って Lyrical のパッケージソースを設定してから、スクリプトを再実行してください。
そのコンピューターで rosdep を一度も初期化していない場合は、rosdep update の前に sudo rosdep init を一度実行してください。sudo コマンドには管理者権限が必要です。
SDK のダウンロードに失敗した場合は、Wuji SDK v2026.10.12 から、ホストアーキテクチャに合った wuji-sdk-c-2026.10.12-x86_64-linux-gnu.tar.gz または wuji-sdk-c-2026.10.12-aarch64-linux-gnu.tar.gz をダウンロードして展開してください。展開したディレクトリに include/wuji_sdk.h、lib/libwuji_sdk_c.so、LICENSE が含まれていることを確認します。/path/to/sdk をそのディレクトリの絶対パスに置き換え、デフォルトのビルドコマンドの代わりに、wuji-ros2 から次のコマンドを実行してください。
```
colcon build --cmake-args -DBUILD_TESTING=OFF -DWUJI_SDK_ROOT=/path/to/sdk
```
WUJI_SDK_ROOT を設定した場合、CMake は SDK のバージョンを検証しません。上記で指定したリリースパッケージを使用してください。

新しいターミナルを開くたびに、ワークスペースに移動し、ROS とビルド済みパッケージを読み込んでください。

cd "$HOME/wuji-ros2"
source /opt/ros/lyrical/setup.bash
source install/setup.bash

デバイスの選択

グローブを装着して接続した後、デバイスをスキャンします。

ros2 run wuji_tools wuji_list

対象グローブのシリアル番号を控えておいてください。ドライバーは起動時に以下のセレクターを受け付けます。

パラメーター	用途
`serial_number`	スキャンで取得したシリアル番号でグローブを選択します。`endpoint` が設定されている場合は、デバイスの識別情報を検証します
`hand_side`	単独で使用した場合、左右いずれか一意のグローブを選択します。`serial_number` または `endpoint` と組み合わせた場合は、左右の別を検証します。`left` または `right` を使用してください
`endpoint`	必要に応じて、スキャンで取得した `IP:port` アドレスに直接接続します

セレクターを指定しない場合、ドライバーはディスカバリーで Wuji Glove が 1 台だけ見つかったときにのみ接続します。複数のグローブが見つかった場合は即座にエラーとなり終了します。1 台も見つからない場合は、connect_timeout まで待機してから終了します。ドライバーは排他的な接続を保持するため、他の SDK プログラムや wuji viz は同じグローブに同時に接続できません。複数のグローブを接続するには、ドライバープロセスごとに異なるシリアル番号とネームスペースを使用してください。

グローブデータの読み取り

動作検証の実行

1. ドライバーを起動する

GLOVE_SERIAL_NUMBER をデバイスの選択で控えたシリアル番号に置き換え、ドライバーを起動します。

ros2 launch wuji_bringup glove.launch.py \
  serial_number:=GLOVE_SERIAL_NUMBER namespace:=glove

ネットワークアドレスで接続する場合は、GLOVE_ENDPOINT をスキャンで取得した IP:port アドレスに置き換え、次のコマンドを使用します。

ros2 launch wuji_bringup glove.launch.py \
  serial_number:=GLOVE_SERIAL_NUMBER endpoint:=GLOVE_ENDPOINT namespace:=glove

左右の別を検証するには、launch コマンドに hand_side:=left または hand_side:=right を追加してください。

デフォルトでは、ドライバーはグローブの接続を最大 10 秒間待機します。待機時間を 20 秒に延長するには、launch コマンドに connect_timeout:=20.0 を追加してください。0.0 に設定すると、デバイスが接続されるまで待機し続けます。launch 引数は起動時にのみ読み込まれます。

2. データを確認する

ドライバーを実行したまま、新しいターミナルを開き、ROS とビルド済みパッケージを読み込んでから、ステータスデモを実行します。

cd "$HOME/wuji-ros2"
source /opt/ros/lyrical/setup.bash
source install/setup.bash
ros2 run wuji_bringup glove_status_demo --ros-args -r __ns:=/glove

デモはフレームごとに 5 本の指の関節角度と信頼度を出力します。デフォルトでは 10 秒間実行した後、トピックごとのフレーム数と平均受信レートを集計して表示します。joint_angles フレームを 1 つ以上受信できればチェックは合格です。オプションのストリームが欠落している場合は警告が表示されます。

フレームごとの出力を行わずに 30 秒間の受信レートを測定するには、次を実行します。

ros2 run wuji_bringup glove_status_demo \
  --duration 30 --rate-only --ros-args -r __ns:=/glove

--duration と --rate-only は --ros-args の前に指定してください。受信レートは最初のコールバックから最後のコールバックまでの間隔を基に算出されます。これはデモが処理した ROS メッセージを測定するものであり、デバイス側の出力レートではありません。

ドライバーは接続されているのにステータスデモがデータを受信しない場合は、まず各ターミナルでネームスペース、ROS_DOMAIN_ID が一致しているか、QoS に互換性があるかを確認してください。問題が解決しない場合は、別の ROS 2 ミドルウェアを試してください。Cyclone DDS をインストールします。

sudo apt-get install ros-lyrical-rmw-cyclonedds-cpp

現在の launch を停止します。ドライバーとステータスデモの両方のターミナルで次のコマンドを実行します。

export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

その後、手順 1 と 2 を繰り返します。後から新しいターミナルを開いた場合も、同じ ROS 2 ミドルウェアを設定してください。

3. ドライバーを停止する

ドライバーのターミナルで Ctrl+C を押します。ドライバーはサブスクリプションを閉じ、デバイスとの接続を切断します。

データトピック

10 個のトピックはすべて SensorDataQoS（best-effort、volatile、keep-last 5）を使用します。best-effort のサブスクライバーを使用してください。reliable のサブスクライバーでは、これらのパブリッシャーからデータを受信できません。

ドライバーは以下のトピックでグローブデータをパブリッシュします。記載のメッセージ型でサブスクライブしてください。トピック名は相対名です。namespace:=glove の場合、joint_angles は /glove/joint_angles に解決されます。

トピック	メッセージ型	内容	起動時スイッチ
`joint_angles`	`wuji_msgs/msg/HandJointAngles`	5 本の指の関節角度配列と信頼度	常に有効
`emf_poses`	`wuji_msgs/msg/TrackedPoseArray`	名前付きの EMF トラッキング姿勢と信頼度	`publish_emf_poses`
`tip_poses`	`wuji_msgs/msg/TrackedPoseArray`	名前付きの指先姿勢と信頼度	`publish_tip_poses`
`hand_skeleton`	`wuji_msgs/msg/TrackedPoseArray`	名前付きの手骨格姿勢と信頼度	`publish_skeleton`
`imu/palm`	`sensor_msgs/msg/Imu`	SDK の `imu_raw/palm` による手のひら IMU の生データ	`publish_imu`
`tactile`	`wuji_msgs/msg/TactileGrid`	グリッドの寸法と触覚データ配列	`publish_tactile`
`tactile/residual`	`wuji_msgs/msg/TactileGrid`	グリッドの寸法と触覚残差配列	`publish_tactile_residual`
`tactile/binary`	`wuji_msgs/msg/TactileGrid`	グリッドの寸法と触覚二値配列	`publish_tactile_binary`
`tactile/zones`	`wuji_msgs/msg/TactileZoneArray`	触覚ゾーンの名前と値	`publish_tactile_zones`
`tactile/points`	`sensor_msgs/msg/PointCloud2`	触覚点群	`publish_tactile_points`

Wuji メッセージのフィールドについては、wuji-ros2 リポジトリの wuji_msgs/msg/ ディレクトリにある、記載の型に対応する .msg ファイルを参照してください。ネストされたメッセージ型も同じディレクトリにあります。標準メッセージについては、ROS 2 の Imu.msg および PointCloud2.msg の定義を参照してください。

ワークスペースを読み込んだ後、次のコマンドを実行すると、インストールされているバージョンのメッセージフィールドを確認できます。

ros2 interface show wuji_msgs/msg/HandJointAngles
ros2 interface show wuji_msgs/msg/TrackedPoseArray
ros2 interface show wuji_msgs/msg/TactileGrid
ros2 interface show wuji_msgs/msg/TactileZoneArray

データの解釈

関節角度の単位は rad、姿勢の位置の単位は m です。各指の angles 配列は実際の長さに従って読み取ってください。親指は 5 要素、その他の指はそれぞれ 4 要素です。信頼度を正規化された確率として解釈しないでください。
メッセージには SDK のタイムスタンプ、フレーム識別子、ペイロード値がそのまま保持されます。ROS のネームスペースによってメッセージの frame_id の値が書き換えられることはありません。フレームの定義については座標系を参照してください。
ドライバーは SDK の IMU 生データのフィールドと共分散を、新たな姿勢推定を計算することなく imu/palm にコピーします。SDK で算出される imu_data/palm ストリームはパブリッシュしません。
触覚グリッドは rows × columns の行優先配列です。値の意味はトピックによって異なります。残差グリッドと二値グリッドは力の測定値ではありません。
触覚点群は、それぞれの fields、point_step、row_step を用いて解析してください。xyz のみのレイアウトであると仮定しないでください。

トピックパブリッシュの設定

必須の joint_angles を除き、表に記載の 9 つのデータストリームは launch 引数で制御できます。デフォルトではすべて有効です。たとえば、触覚点群を無効にするには次を実行します。

ros2 launch wuji_bringup glove.launch.py \
  serial_number:=GLOVE_SERIAL_NUMBER namespace:=glove \
  publish_tactile_points:=false

ブール型の launch 引数は小文字の true / false のみを受け付けます。その他のオプションストリームには、表に記載の対応する publish_* 引数を使用してください。joint_angles には無効化スイッチはありません。

ストリームの終了とエラーへの対処

必須の joint_angles が開始できない、終了した、またはエラーを報告した場合、ドライバーは 0 以外の終了ステータスで終了し、launch もシャットダウンされます。オプションストリームで障害が発生した場合は、そのストリームのみが停止し、ログメッセージが記録されます。他のストリームは継続します。

ドライバーは自動的に再接続しません。デバイスとネットワークを復旧してから、launch を再起動してください。この処理はストリームの終了イベントまたはエラーイベントによってトリガーされます。データが継続して届いているかを確認する必要があるアプリケーションでは、メッセージのタイムスタンプを監視してください。