外付け多指ハンド

本ページは、お客様側で Revo2 多指ハンドを Elf3 に導入するための手順です。配線、依存関係のインストール、ビルド、実行、受け入れ確認を中心に説明します。SDK の API やカスタム開発については、サンプルリポジトリおよびハンド SDK を参照してください。

Elf3 向け Revo2 サンプルパッケージ（bxi_revo2_example）：（導入ユーザー様に HumansX より提供します）
ハンド公式 SDK：brainco-hand-sdk

安全上の注意

58 V 電圧に対応しているのは Revo2 の Advanced 版および Haptic 版のみです。ベーシック版はロボットに接続しないでください。

デモでは、指の開き、握り、つまみ、単指動作、速度／電流／PWM 制御などのジェスチャーを実行します。ハンドの可動範囲内に身体の一部、ケーブル、壊れやすい物がないことを確認してください。ハンドが物体を把持している状態でフルデモを実行しないでください。

動作環境

項目	要件
ロボット	ロボットのハードウェアノードが稼働している Elf3
多指ハンド	Revo2 PRO && TOUCH
通信	ロボットコントローラの CANFD
ROS バージョン	ROS 2 Humble
サンプルパッケージ	`bxi_revo2_example`
Python SDK	`bc-stark-sdk==1.5.1`

サンプルパッケージは communication/msg/CANFDPacket を介してロボットの CANFD ハードウェアノードと通信するため、事前に bxi_ros2_pkg の環境を source しておく必要があります。

配線

デフォルトの配線であれば、ソースコードの変更は不要です。

ハンド	ロボットコントローラのポート	デフォルト ID	プロトコル	`master_id`
左手	CAN5	126 / `0x7E`	CANFD	1
右手	CAN6	127 / `0x7F`	CANFD	1

配線後、通常どおりロボットを起動します。ハードウェアノードが正常に起動すると、通常 Revo2 ハンドは自動的に開きます。これをハードウェア接続の最初の確認としてください。

クイック導入

1. サンプルパッケージの取得

ロボットコントローラまたは ROS 2 ホスト上で次を実行します（リポジトリは導入ユーザー様に HumansX より提供します）。

cd ~/bxi_ws
git clone <provided-repo-url>

現場でネットワークに接続できない場合は、事前にリポジトリを入手し、~/bxi_ws/bxi_revo2_example にコピーしてください。

2. C++ SDK ファイルのダウンロード

C++ デモをビルドする前に、公式 SDK の共有ライブラリとヘッダーファイルが必要です。

cd ~/bxi_ws/bxi_revo2_example
./download-lib.sh

スクリプトにより次が作成されます。

dist/include/
dist/shared/linux/libbc_stark_sdk.so
VERSION

3. Python SDK のインストール

Python デモを実行する前に、指定バージョンの SDK をインストールします。

pip install bc-stark-sdk==1.5.1 --index-url https://pypi.org/simple/

4. パッケージのビルド

cd ~/bxi_ws/bxi_revo2_example
source /opt/ros/humble/setup.bash
source /opt/bxi/bxi_ros2_pkg/setup.bash
colcon build
source install/setup.bash

ヒント：communication パッケージを別のワークスペースでビルドしている場合は、colcon build を実行する前にそのワークスペースを source してください。

実行と検証

1. CANFD 用 ROS 2 環境の設定

ハンドのデモは /canfd_packet/rx と /canfd_packet/tx を介してロボットのハードウェアノードと通信します。ハードウェアノードは通常 root 権限で動作しているため、root シェルで同じ ROS 2 Domain と CycloneDDS のネットワーク設定を行い、そのシェルからデモを実行してください。

sudo su
export ROS_DOMAIN_ID=ROBOT_DOMAIN_ID
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
export ROS_LOCALHOST_ONLY=0
export CYCLONEDDS_URI='<CycloneDDS><Domain Id="any"><General><Interfaces><NetworkInterface name="lo" multicast="true"/></Interfaces><AllowMulticast>true</AllowMulticast></General></Domain></CycloneDDS>'

ROBOT_DOMAIN_ID は、ロボットで使用している Domain ID の数値に置き換えてください。一般ユーザーのシェルでのみ変数を設定してから root に切り替えることは避けてください。sudo su では ROS の環境変数が確実には引き継がれません。

2. ロボットのハードウェアノードの起動

通常のロボット起動手順で Elf3 を起動します（必要に応じて「モーション制御開発ガイド」の「ロボットプログラムの起動」を参照してください）。

CANFD トピックが存在することを確認します。

source /opt/ros/humble/setup.bash
source /opt/bxi/bxi_ros2_pkg/setup.bash
ros2 topic list | grep canfd_packet

期待されるトピック：

/canfd_packet/rx
/canfd_packet/tx

3. デモの実行

C++ デモを実行する場合：

cd ~/bxi_ws/bxi_revo2_example
source /opt/ros/humble/setup.bash
source /opt/bxi/bxi_ros2_pkg/setup.bash
source install/setup.bash
ros2 run bxi_revo2_example bxi_revo2_example

Python デモを実行する場合：

cd ~/bxi_ws/bxi_revo2_example
source /opt/ros/humble/setup.bash
source /opt/bxi/bxi_ros2_pkg/setup.bash
source install/setup.bash
ros2 run bxi_revo2_example bxi_revo2_example.py

4. 受け入れ確認

ターミナルにデバイス情報、各指の位置、速度、電流、設定値が表示されます。ハンドは次の動作を実行します。

基本的な位置制御：握る、手を開く、単指動作
速度、電流、PWM 制御
Revo2 の高度な制御：単位モード、時間指定の位置制御、速度指定の位置制御、複数指の動作
内蔵ジェスチャー：Open、Fist、Pinch、Point など
デバイス情報およびパラメータの照会

デフォルトのデモは左手から先に実行し、次に右手を実行します。両手ともこれらの動作を連続的なエラーなく完了すれば、基本的な導入は完了です。

デフォルトのバスまたは ID の変更

現場の配線やハンドの ID がデフォルト設定と異なる場合は、サンプルソースのバスと ID を変更してください。

Python サンプル：

~/bxi_ws/bxi_revo2_example/src/bxi_revo2_example.py

デフォルト設定：

left_ctx = await init_bxipci_device(5, 126, master_id=1, is_canfd=True, ...)
right_ctx = await init_bxipci_device(6, 127, master_id=1, is_canfd=True, ...)

C++ サンプル：

~/bxi_ws/bxi_revo2_example/src/bxi_revo2_example.cpp

デフォルト設定：

init_bxipci_device(&left_ctx_, 5, 126, true);
init_bxipci_device(&right_ctx_, 6, 127, true);

ソースを変更した後は再ビルドしてください。

cd ~/bxi_ws/bxi_revo2_example
colcon build
source install/setup.bash

トラブルシューティング

`stark-sdk.h` または `libbc_stark_sdk.so` が見つからない

C++ SDK ファイルがダウンロードされていません。次を実行してください。

cd ~/bxi_ws/bxi_revo2_example
./download-lib.sh

その後、パッケージを再ビルドしてください。

`No module named bc_stark_sdk`

Python SDK がインストールされていないか、別の Python 環境にインストールされています。次を実行してください。

pip install bc-stark-sdk==1.5.1 --index-url https://pypi.org/simple/

`communication.msg.CANFDPacket not found`

ロボットの ROS 2 メッセージパッケージの環境が source されていません。

source /opt/bxi/bxi_ros2_pkg/setup.bash
source ~/bxi_ws/bxi_revo2_example/install/setup.bash

応答がない、または読み取りタイムアウト

次の点を確認してください。

左手が CAN5 に接続され、ID 126 を使用しているか
右手が CAN6 に接続され、ID 127 を使用しているか
ロボットのハードウェアノードが稼働しており、/canfd_packet/rx と /canfd_packet/tx の両方が存在するか
ケーブル接続と電源が正常か
他のプロセスが同じハンドを同時に制御していないか
工場出荷時にインストールされたハードウェアノードの場合、ROS_DOMAIN_ID が一致しているか

開発の入り口

お客様側での導入では、通常、低レベルの CAN ブリッジを変更する必要はありません。独自の ROS 2 ノードからハンドを制御する場合は、サンプルリポジトリの README にある「Use In Your Own ROS 2 Node class」の節を参照してください（リポジトリは導入ユーザー様に HumansX より提供します）。