Juqiao Glove ソフトウェア: ドライバー、Python API、ROS2

ステップ 1 — インストール

juqiao-glove パッケージをインストールする

グローブは、カーネルモジュールやカスタムドライバーを使用せず、USB CDC シリアル経由で通信します。 Python パッケージのラップパイシリアルバイナリフレームプロトコルを処理します。

あらゆるOSをサポート グローブは標準の CDC-ACM シリアルデバイスとして表示されます。 Windows、macOS、Linux はすべて、インボックスドライバーを使用して自動的に列挙します。ベンダードライバーのインストーラーは必要ありません。

# Python 3.10+ recommended
pip インストール juqiao-glove

# Or with optional visualization extras (matplotlib, numpy)
pip インストール「juqiao-glove[viz]」

# Or with ROS2 bridge extras (requires ROS2 Humble or later)
pip インストール「juqiao-glove[ros2]」

インストールを確認します。

python -c "juqiao_gloveをインポート; print(juqiao_glove.__version__)"
# Expected: 0.4.x or later

ステップ 2 — ポートの検出

USBポートの検出

1.5 m USB-C ケーブルを介してグローブを接続します。デバイスは CDC-ACM シリアルポートとして列挙されます。

OS	一般的なポート名	注意事項
Linux	/dev/ttyACM0	ユーザーを追加ダイヤルアウト許可が拒否された場合のグループ化
macOS	/dev/tty.usbmodem*	使用 ls /dev/tty.usb* 正確な名前を見つけるには
窓	COM3 (さまざま)	デバイスマネージャー → ポート (COM および LPT) を確認します。

Python から手袋を自動検出します。

from juqiao_glove import JuqiaoGlove

# Auto-scan all serial ports and return the first Juqiao device found
グローブ = JuqiaoGlove.find() プリント(グローブ.ポート)   # → '/dev/ttyACM0' or 'COM3' etc.
print(glove.info()) # → firmware version, node count, sample rate

または、ポートを明示的に指定します。

グローブ = JuqiaoGlove(port="/dev/ttyACM0", baudrate=3000000)

Linuxの権限エラー？ 走る sudo usermod -aG ダイヤルアウト $USER ログアウトしてから再度ログインします。または、次の方法を使用します。 sudo chmod 666 /dev/ttyACM0 1 セッションで回避できる場合。

ステップ 3 — ストリーミング API

Python ストリーミング API

グローブは 200 Hz でストリーミングします。各フレームには、64 要素の圧力配列 (16 ビット ADC、正規化された 0.0 ～ 1.0) とタイムスタンプが含まれています。

from juqiao_glove import JuqiaoGlove インポート時間 グローブ = JuqiaoGlove.find() グローブ.connect()

# Single-frame read
フレーム = glove.read_frame() print(フレーム.タイムスタンプ)          # float, seconds since epoch
print(フレーム.圧力)          # np.ndarray shape (64,), float32, range 0.0-1.0
print(frame.pressures.reshape(8, 8)) # 8×8 spatial grid

# Continuous callback stream
def on_frame(フレーム): max_node = フレーム.圧力.argmax() print(f"t={frame.timestamp:.4f}peak_node={max_node} val={frame.pressures[max_node]:.3f}") glove.stream(callback=on_frame、duration=5.0)  # stream for 5 seconds

# Or use as an iterator
glove.stream() をフレームとして使用: フレーム内のフレームの場合: プロセス(フレーム) 完了した場合: 休憩 グローブ.切断()

フレームオブジェクトリファレンス

属性	タイプ	説明
フレーム.タイムスタンプ	フロート	ホスト側の受信時間 (秒、Unix エポック)
フレームの圧力	np.ndarray (64,)	ノードごとの正規化された圧力、0.0 (なし) ～ 1.0 (最大)
フレーム.圧力_生	np.ndarray (64,)	生の 16 ビット ADC カウント (0 ～ 65535)
フレーム.コンタクトマスク	np.ndarray (64,) ブール値	圧力がしきい値を超える場合は True (デフォルトは 0.05)
フレーム.contact_nodes	リスト[int]	現在接続しているノードのインデックス
フレーム.grasp_region	str または None	ヒューリスティック領域: 「ヤシ」, "親指", "索引", "真ん中", "指輪", "ピンキー", なし
フレーム.シーケンス	整数	フレームカウンター (65535 でラップ)。ドロップされたフレームを検出するために使用します

リファレンス — センサーのレイアウト

64 ノードのセンサーレイアウト

64 個のタクセルは、手のひらと 5 本の指の部分すべてを覆う織られた繊維マトリックスとして配置されています。ノードインデックスは、背側ビューの行優先の一貫した順序に従います。

0–12

手のひら（中央パッド）

13–23

親指 (3 セグメント)

24–34

人差し指

35–45

中指

46–54

薬指

55–63

小指

# Access region slices by name
juqiao_glove.layout から REGION_SLICES をインポート Palm_nodes = Frame.pressures[REGION_SLICES["palm"]] thumb_nodes = Frame.pressures[REGION_SLICES["thumb"]] Index_nodes = Frame.pressures[REGION_SLICES["index"]]

# Reshape to 8×8 spatial grid (dorsal view, row-major)
グリッド = フレーム.圧力.reshape(8, 8)

オプション — 視覚化

圧力ヒートマップの視覚化

の [つまり] 追加では、キャリブレーションとデバッグに役立つライブ matplotlib ヒートマップレンダラーがインストールされます。

# Requires: pip install "juqiao-glove[viz]"
from juqiao_glove import JuqiaoGlove juqiao_glove.viz から圧力ヒートマップをインポート グローブ = JuqiaoGlove.find() グローブ.connect() viz = PressureHeatmap(title="Juqiao グローブ — ライブプレッシャー") viz.show(グローブ)  # Opens a matplotlib window; press Q to quit

ヘッドレス環境またはデータレビューの場合は、フレームをビデオとして保存します。

juqiao_glove.viz から Record_heatmap_video をインポート Record_heatmap_video( input_npy="セッション圧力.npy",  # shape (N, 64) saved during recording
    Output_mp4="ヒートマップ.mp4", fps=30、 カラーマップ="インフェルノ", ）

オプション — ROS2

ROS2インターフェース

の juqiao_glove_ros2 パッケージはカスタムを公開します触覚アレイ 200 Hz のメッセージ。 ROS2 Humble および Iron と互換性があります。

# Install the package (requires ROS2 to be sourced)
pip インストール「juqiao-glove[ros2]」

# Or build from source in your workspace
cd ~/ros2_ws/src git clone https://github.com/roboticscenter/juqiao_glove_ros2 cd ~/ros2_ws && コルコンビルド --packages-select juqiao_glove_ros2

ドライバーノードを起動します。

ソース/opt/ros/humble/setup.bash ソース ~/ros2_ws/install/setup.bash

# Auto-detect port
ros2 起動 juqiao_glove_ros2 glove.launch.py

# Specify port explicitly
ros2 起動 juqiao_glove_ros2 glove.launch.py​​ ポート:=/dev/ttyACM0

公開されたトピック:

トピック	メッセージの種類	レート	説明
/juqiao_glove/tactile_array	juqiao_glove_ros2/TactileArray	200Hz	フル 64 ノードの圧力アレイ
/juqiao_glove/contact_mask	std_msgs/UInt8MultiArray	200Hz	ノードごとのバイナリ接点 (0 または 1)
/juqiao_glove/grasp_region	std_msgs/文字列	200Hz	アクティブ領域ヒューリスティックまたは空の文字列
/juqiao_glove/status	Diagnostic_msgs/DiagnosticStatus	1Hz	ファームウェアバージョン、フレームドロップ率

オルカハンドとグローブの組み合わせ発射

同期録音のためにグローブを Orca Hand と一緒に使用する場合:

# Launch Orca Hand driver
ros2 起動 orca_ros2 orca_hand.launch.py​​ ポート:=/dev/ttyUSB0

# In a second terminal, launch Juqiao Glove driver
ros2 起動 juqiao_glove_ros2 glove.launch.py​​ ポート:=/dev/ttyACM0

# Verify synchronized topics
ros2トピックリスト | grep -E "シャチ|ジュチャオ" ros2 トピック hz /juqiao_glove/tactile_array ros2 トピック hz /orca_hand/joint_states

ステップ 4 — キャリブレーション

ベースライン校正

グローブは工場出荷時に校正済みです。ベースラインのドリフト (静止時のノードの読み取り値がゼロ以外) に気付いた場合、または拡張ストレージ後に再調整してください。

校正前に手袋を外してください キャリブレーションにより、ゼロ圧力のベースラインが取得されます。校正シーケンス中は手袋を着用したり触れたりしないでください。手袋を表面に平らに置きます。

# CLI calibration — lay glove flat, do not touch
python -m juqiao_glove.calibrate --port /dev/ttyACM0

# Or from Python
from juqiao_glove import JuqiaoGlove グローブ = JuqiaoGlove.find() グローブ.connect() glove.calibrate_baseline(期間=3.0)   # averages 3 seconds of idle frames
glove.save_calibration("~/.juqiao_glove_cal.json") グローブ.切断()

実行時のロードキャリブレーション:

グローブ = JuqiaoGlove.find() グローブ.connect() glove.load_calibration("~/.juqiao_glove_cal.json")

# Now frame.pressures reflects calibrated values
フレーム = glove.read_frame() print(frame.pressures.max())  # Should be ~0.0 at rest

しきい値の調整

デフォルトの接触しきい値は 0.05 (フルスケールの 5%) です。タスクごとに調整します。

# For delicate objects (lower threshold detects light touch)
glove.set_contact_threshold(0.02)

# For heavy manipulation tasks (reduce false positives)
glove.set_contact_threshold(0.10)

# Per-region thresholds
glove.set_contact_threshold({"手のひら": 0.08, "親指": 0.03, "インデックス": 0.03})

トラブルシューティング

よくある問題

SerialException: [Errno 13] アクセス許可が拒否されました: '/dev/ttyACM0'

走る sudo usermod -aG dialout $USER その後、ログアウトして再度ログインします。または、次のようにします。 sudo chmod 666 /dev/ttyACM0 (プラグを抜くとリセットされます)。

JuqiaoGlove.find() は None を返しました — デバイスが見つかりませんでした

USB接続を確認してください。走る dmesg | tail -20 (Linux) または ls /dev/tty.usb* (macOS) OS がデバイスを列挙したことを確認します。別の USB ポートまたはケーブルを試してください (コネクタは USB-C ですが、充電専用ではなくデータケーブルである必要があります)。

64 個のノードすべてが 0.0 を読み取りました - 圧力データなし

電話 glove.info() ファームウェアが応答することを確認します。含まれている場合は、キャリブレーションファイルが過度に減算していないか確認してください。消去 ~/.juqiao_glove_cal.json グローブを平らに置いた状態で再調整します。

ベースラインドリフト — 静止時のノードの読み取り値は 0.1 ～ 0.2

再調整: 圧力をかけずにグローブを平らに置き、実行します glove.calibrate_baseline()。温度変化や長期保管後に発生する可能性があります。手袋を平らにした状態でドリフト > 0.4 の場合、センシング生地の交換が必要になる可能性があります (Juqiao サポートにお問い合わせください)。

フレームドロップ — シーケンス番号がスキップされる

USB ケーブルの品質とポートを確認してください。 USB 3.0 ポートを使用します。 Linux では、他の高帯域幅デバイスを備えた USB ハブを避けてください。あなたの on_frame コールバックはすぐに戻ります。別のスレッドで重い処理を実行します。

ROS2 ノードは起動しますが、/juqiao_glove/tactile_array にメッセージがありません

ポート引数を確認します。 ros2 launch juqiao_glove_ros2 glove.launch.py port:=/dev/ttyACM0。ノードのログを確認します。 ros2 node info /juqiao_glove_driver。を確認してください。 dialout グループ修正は、ROS2 ノードを実行しているユーザーに適用されました。

ソフトウェアとドライバーのセットアップ