ContactGlove Python SDK V2

対応製品ContactGlove3 Pro

contactglovesdkは、ContactGlove Python SDK V2のライブラリです。 DivingStationからOSCでグローブのデータを受信し、ポーリング用メソッドとコールバックを提供します。

配布パッケージの内容

ダウンロードできる配布パッケージには、次のファイルが含まれます。

README.md                          (日本語のインストール手順)
README_EN.md                       (英語のインストール手順)
contactglovesdk-X.Y.Z-py3-none-any.whl
examples/
  basic_usage.py
  simple_receive.py
  viewer/
doc/
  LICENSE.md
  NOTICE.md
  THIRD_PARTY_NOTICES.md

データ型・メソッド・コールバックの詳細は、APIリファレンスを参照してください。

必要環境

  • ContactGlove3 Pro（ContactGlove3 では SDK にデータが届きません）
  • Python 3.10以上
  • DivingStation v2以降がインストール済みで起動できること

SDK本体はpure Pythonで、OS固有のビルドは不要です。 Windows 11、macOS、Ubuntuで動作確認済みです。 viewerのセットアップとDivingStationの利用環境は、それぞれ確認してください。

SDKはOSCでDivingStationと通信します。デフォルトでは、DivingStation側の受信 ポートは25791、SDK側の受信ポートはOSが自動的に割り当てます。

送信元ポートの既定値もsend_port=0（OSによる自動割り当て）です。 DivingStationの既定の待受範囲は「このコンピューターのみ」のため、別のPCからは接続できません。信頼できるLANに公開した場合、既定の接続承認設定では別のPCからの接続に承認が必要です。同じPCからの接続は自動で許可されます。

別のPCから接続する

  1. 信頼できるLANを使用してください。
  2. DivingStationのSDK / Protocolで待受範囲をLAN に公開にします。待受範囲を変更した場合は、DivingStationを再起動してください。
  3. SDKの接続先には、DivingStationを実行しているPCの数値IPアドレスと待受ポート（既定25791）を指定します。PythonではHost("DivingStation", "192.168.1.100", 25791)のように設定します。
  4. 接続承認が必要な設定では、DivingStationに表示される接続要求を許可してください。
  5. 両方のPCの実際の受信ポートで、必要なUDP通信を許可してください。SDK側の受信ポートはContactGloveClient(local_port=...)で指定でき、自動割り当て時の実際の値は接続後のclient.local_portで確認できます。

LAN承認待ちやデータ途絶時のリトライは、同じクライアントで connect_to_host(host)を再度呼び出してください。disconnectやcloseを挟まず、 同じ送信ソケット・送信元ポート・受信ポートでConnectだけを再送します。 SDKは30秒ごとの自動再送も続けます。呼び出しの成功はLAN承認完了を意味しません。 DivingStation再起動後も再送で接続を復帰できますが、必要なら再承認してください。 明示的なdisconnectはセッションを終了し、承認待ち・承認済み状態を失う場合があります。

インストール

SDKの配布パッケージをダウンロードして展開し、展開したフォルダでwheelファイルをインストールします。 X.Y.Zは、ダウンロードしたファイルのバージョンに置き換えてください。

python -m pip install ./contactglovesdk-X.Y.Z-py3-none-any.whl

依存パッケージのpython-osc>=1.7.5とmatplotlib>=3.7.5は、pipが自動的にインストールします。 matplotlibはexamples/viewerでのみ使用します。

まず疎通確認する

  1. DivingStationを起動します。
  2. DivingStation上でContactGlove3 Proを接続し、有効な状態にします。
  3. SDKの配布パッケージを展開したフォルダで、次を実行します。
python ./examples/basic_usage.py

次のような出力が出れば、SDKがDivingStationからデータを受信できています。

Listening on local port ... …
Polling target: auto
[device]   id=...
[select]   ...
[poll]     id=...

[device]にIDが表示されているのに[poll]がno data yetのままの場合は、 --gloveオプションで対象のグローブIDまたは名前を指定してください。以下のYOUR_GLOVE_IDは、[device]に表示された実際のIDに置き換えてください。

python ./examples/basic_usage.py --glove YOUR_GLOVE_ID

自分のプロジェクトで使う

インストール後は、通常のPythonパッケージとしてimportして使用できます。

import time

from contactglovesdk import ContactGloveClient, Host

host = Host("localhost", "127.0.0.1", 25791)

with ContactGloveClient() as client:
    client.register_callback_for_glove_data_stream(lambda g: print(g.id))
    client.connect_to_host(host)

    time.sleep(5)

    client.disconnect(host)

データ取得やコールバック登録など、より詳しい使い方はAPIリファレンスを参照してください。 配布パッケージにはexamples/simple_receive.pyとexamples/basic_usage.pyも含まれます。

トラブルシュート

basic_usage.pyがno data yetだけを表示する:

  • DivingStationが起動しているか確認してください。
  • DivingStation上でグローブが接続済みか確認してください。
  • --gloveオプションに渡すIDまたは名前が、[device]に表示された実際の グローブと一致しているか確認してください。

ModuleNotFoundError: No module named 'contactglovesdk':

  • python -m pip install ./contactglovesdk-X.Y.Z-py3-none-any.whlを実行したPython 環境と、サンプルを実行するPython環境が一致しているか確認してください （仮想環境を使っている場合は有効化を忘れずに）。

サンプル実行時にポートの使用中エラーが出る:

  • 他のアプリケーションがSDK側の受信ポートを使用していないか確認してください。
  • ContactGloveClient(local_port=...)で別のポート番号を明示的に指定してください。
  • 送信元ポートを指定する場合は、ContactGloveClient(send_port=...)またはsimple_receive.pyの--send-portを使用してください。

ライセンス

SDK の自社部分は Apache License 2.0 で提供します。全文と著作権表示は、配布パッケージの次のファイルにあります。

doc/LICENSE.md
doc/NOTICE.md

第三者の依存ライブラリにはそれぞれのライセンスが適用され、Apache-2.0 への再許諾対象ではありません。 python-osc の表記・ライセンス全文は、配布パッケージに含まれます。

doc/THIRD_PARTY_NOTICES.md

お問い合わせ

SDKに関するご質問や不具合の報告は、お問い合わせフォームからお送りください。

APIリファレンス

次のページ

このページの内容

配布パッケージの内容必要環境別のPCから接続するインストールまず疎通確認する自分のプロジェクトで使うトラブルシュートライセンスお問い合わせ