ContactGlove C++/C/Rust SDK V2

ContactGlove C++/C/Rust SDK V2は、C++/C/Rust向けのネイティブライブラリです。 C++ API、C言語から直接使える安定したC ABI v2、公式Rust Bindingを提供します。

インストール

Windows (ZIP)

ZIPを展開し、展開されたフォルダをSDK rootとして使用します。

Expand-Archive .\ContactGloveSDKv2Cpp-<version>-Windows-AMD64.zip -DestinationPath .

Linux (TGZ)

TGZを展開し、展開されたフォルダをSDK rootとして使用します。

tar -xzf ContactGloveSDKv2Cpp-<version>-Linux-x86_64.tar.gz

macOS (Universal TGZ)

macOS 13以降のApple SiliconとIntel Macに対応するTGZです。展開されたフォルダを SDK rootとして使用します。

tar -xzf ContactGloveSDKv2Cpp-<version>-macOS-universal.tar.gz

Ubuntu 22.04 / 24.04 (APT)

APTリポジトリからcontactglove-sdk-v2をインストールします。 Ubuntu 22.04（jammy）または24.04（noble）のamd64が対象です。

初回だけの設定

公開鍵contactglove-archive.ascを配布元から入手し、保存したフォルダで次を実行します。

sudo apt-get update
sudo apt-get install ca-certificates gnupg
gpg --show-keys --with-fingerprint ./contactglove-archive.asc

主鍵のfingerprintが次の値と一致することを確認してください。

DCBF 1BD7 8F31 3033 7506 DDF6 CC4A 11F6 725F 5132

確認した鍵を、SDKのAPTリポジトリ専用のkeyringへ登録します。

sudo install -d -m 0755 /etc/apt/keyrings
gpg --dearmor --output contactglove-archive.gpg ./contactglove-archive.asc
sudo install -m 0644 contactglove-archive.gpg /etc/apt/keyrings/contactglove-archive.gpg

端末のcodenameを使ってAPTリポジトリを登録します。VERSION_CODENAMEはjammyまたはnoble、 architectureはamd64であることを確認してください。

. /etc/os-release
echo "$VERSION_CODENAME"
dpkg --print-architecture

cat <<EOF | sudo tee /etc/apt/sources.list.d/contactglove.sources > /dev/null
Types: deb
URIs: https://apt.melt-interface-technologies.com/ubuntu
Suites: ${VERSION_CODENAME}
Components: main
Architectures: amd64
Signed-By: /etc/apt/keyrings/contactglove-archive.gpg
EOF

インストール

sudo apt-get update
sudo apt-get install contactglove-sdk-v2

インストール後は、ライブラリ、ヘッダー、CMake package config、および contactglove-basic-usageがシステム標準の配置にインストールされます。

更新

初回設定をやり直す必要はありません。SDKを更新するときは次を実行します。

sudo apt-get update
sudo apt-get install --only-upgrade contactglove-sdk-v2

必要環境

ContactGlove3 Pro（ContactGlove3 では SDK にデータが届きません）
Windows 11 x64（ZIP）、Ubuntu 22.04 / 24.04 x86_64（TGZまたは対応DEB）、macOS 13以降（arm64 / x86_64のUniversal TGZ）
独自のC++アプリをビルドする場合は、GCC / Clang / Visual Studio 2019以降などのC++17対応コンパイラ
Windowsの場合は、Microsoft Visual C++ Redistributable（x64）
DivingStation v2以降がインストール済みで起動できること

同梱のビルド済みサンプルを動かすだけならコンパイラは不要です。Cから利用する場合はCコンパイラ（同梱CサンプルはC11）、Rustから利用する場合はRust/Cargo 1.82以降と対応するネイティブSDKが必要です。以下の利用側CMake例は3.16以降、SDK本体のソースビルドはCMake 3.20以降を使用します。

SDKはOSCでDivingStationと通信します。デフォルトでは、DivingStation側の受信ポートは25791、SDK側の受信ポートは25788です。

別のPCから接続する

信頼できるLANを使用してください。
DivingStationのSDK / Protocolで待受範囲をLAN に公開にします。待受範囲を変更した場合は、DivingStationを再起動してください。
SDKの接続先には、DivingStationを実行しているPCの数値IPアドレスと待受ポート（既定25791）を指定します。各言語のフィールドは下表を参照してください。
接続承認が必要な設定では、DivingStationに表示される接続要求を許可してください。
両方のPCの実際の受信ポートで、必要なUDP通信を許可してください。SDK側の受信ポートの既定値は25788です。

言語・接続設定	DivingStation PCの数値IPアドレス	DivingStationの待受ポート	SDKの受信ポート
C++ `Host`	`ipAddress`	`port`	`receivePort`
C `cg_host_t`	`ip_address`	`port`	`receive_port`
Rust `Host`	`ip_address`	`port`	`receive_port`

まず疎通確認する

DivingStationを起動します。
DivingStation上でContactGlove3 Proを接続し、有効な状態にします。
インストールまたは展開したSDKで、次を実行します。

Linux TGZ:

LD_LIBRARY_PATH="$PWD/lib" ./bin/contactglove-basic-usage

macOS Universal TGZ:

./bin/contactglove-basic-usage

macOSでは、同梱実行ファイルcontactglove-basic-usageとcontactglove-c-basic-usageに限り、 INSTALL_RPATHが@loader_path/../libに設定されています。独自アプリのライブラリ検索は、後述の手順で別途設定してください。

Ubuntu DEB:

contactglove-basic-usage

Windows ZIP:

.\bin\contactglove-basic-usage.exe

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

Listening on port 25788...
[callback] id=...
[poll] id=...

起動直後は[poll] waiting for callback dataが出ることがあります。 contactglove-basic-usageは、callbackで最初に受信したグローブIDの情報を自動でポーリングします。

CMakeプロジェクトから使う

ZIP/TGZはビルド済みライブラリの配布物で、SDKソースのCMakeLists.txtは含まれていません。ビルドするのは利用側のプロジェクトで、SDKはCMAKE_PREFIX_PATHから find_package()で参照します。

まず、利用側のCMakeLists.txtを用意します。

cmake_minimum_required(VERSION 3.16)
project(my_app LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(ContactGloveSDKv2 CONFIG REQUIRED)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE ContactGloveSDKv2::ContactGloveSDKv2)

次に、利用側プロジェクトのディレクトリでconfigureとビルドを実行します。以下の-S .は利用側プロジェクトを指します。展開したSDKのフォルダではありません。

Linux debでインストールした場合は、通常は追加指定なしで解決できます。

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

Windows ZIPを展開した場合:

cmake -S . -B build -DCMAKE_PREFIX_PATH="C:\path\to\ContactGloveSDKv2Cpp-<version>-Windows-AMD64"
cmake --build build --config Release

Linux TGZを展開した場合:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH="/path/to/ContactGloveSDKv2Cpp-<version>-Linux-x86_64"
cmake --build build

macOS Universal TGZを展開した場合:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH="/path/to/ContactGloveSDKv2Cpp-<version>-macOS-universal"
cmake --build build

Windowsでは、利用側アプリが実行時にContactGloveSDKv2.dllを見つけられる必要があります。最も簡単なのは、 bin/ContactGloveSDKv2.dllを利用側アプリの.exeと同じフォルダにコピーする方法です。代わりに、SDK配布物のbin/をPATHに追加しても構いません。 Windows ZIPには、Debug構成用のContactGloveSDKv2d.dllも含まれます。find_package()で参照すると、利用側アプリのDebugビルドにはContactGloveSDKv2d.dll、Release・RelWithDebInfo・MinSizeRelビルドには ContactGloveSDKv2.dllが自動で選ばれます。MSVCではDebugとReleaseのC++ランタイムに互換性がないため、手動でコピーする場合も、利用側アプリと同じ構成のDLLを使ってください。

Linux debでインストールした場合は、libContactGloveSDKv2.soは標準のmultiarch library pathに配置されます。

macOSで配布するアプリは、SDKのlibContactGloveSDKv2*.dylibをアプリバンドルへ同梱し、その場所を解決する@rpathを設定してください。TGZ同梱サンプル以外では、ライブラリを単体でコピーするだけの配布はサポートしません。

DLLのコピーは、利用側のCMakeLists.txtで自動化できます。

if(WIN32)
    add_custom_command(TARGET my_app POST_BUILD
        COMMAND ${CMAKE_COMMAND} -E copy_if_different
            $<TARGET_FILE:ContactGloveSDKv2::ContactGloveSDKv2>
            $<TARGET_FILE_DIR:my_app>
        VERBATIM)
endif()

C ABIとRust Binding

include/contactglove/ContactGloveSDKv2C.h はC/C++互換のC ABI v2ヘッダーです。 Cではcg_sdk_*関数を使い、同じネイティブSDKライブラリにリンクします。同梱の share/ContactGloveSDKv2/examples/c_basic_usage.cに接続・ポーリング・購読の例があります。 CMakeではproject(my_c_app LANGUAGES C)、add_executable(my_c_app main.c)、 target_link_libraries(my_c_app PRIVATE ContactGloveSDKv2::ContactGloveSDKv2)を使い、 find_package()と実行時のライブラリ検索はC++利用側と同様に設定します。バッファとコールバックの有効期間はAPIリファレンスを参照してください。

Rust Bindingとしては、同梱workspaceをお使いください。ZIP/TGZではSDK rootのrust/、DEBでは share/ContactGloveSDKv2/rust/を開き、SDK rootを指定してCargoを実行します。

$env:CONTACTGLOVE_SDK_ROOT = "C:\path\to\ContactGloveSDKv2Cpp-<version>-Windows-AMD64"
$env:PATH = "$env:CONTACTGLOVE_SDK_ROOT\bin;$env:PATH"
cargo run --manifest-path "$env:CONTACTGLOVE_SDK_ROOT\rust\Cargo.toml" -p contactglove-sdk-v2 --example basic_usage

macOS Universal TGZの場合:

export CONTACTGLOVE_SDK_ROOT="$PWD"
export DYLD_LIBRARY_PATH="$CONTACTGLOVE_SDK_ROOT/lib:${DYLD_LIBRARY_PATH:-}"
cargo run --manifest-path "$CONTACTGLOVE_SDK_ROOT/rust/Cargo.toml" -p contactglove-sdk-v2 --example basic_usage

自分のCargoプロジェクトから使う場合は、Cargo.tomlの[dependencies]に contactglove-sdk-v2 = { path = "<SDK root>/rust/contactglove-sdk-v2" }を追加し、上と同じ環境変数を設定してからcargo runを実行します。 DEBではpathを/usr/share/ContactGloveSDKv2/rust/contactglove-sdk-v2にします。環境変数の設定は不要です。

SdkとSubscriptionはSend / Syncではありません。コールバックはSDKの受信スレッドで動きます。必要なら所有する値を別スレッドへコピー・送信してください。Sdkの切断・破棄より先に各Subscriptionを解放します。binding再生成の保守手順は Rust READMEにあります。

最小コード例

#include <chrono>
#include <iostream>
#include <thread>

#include "contactglove/ContactGloveSDKv2.hpp"

int main() {
    ContactGloveSDKv2::SDK sdk;

    sdk.RegisterCallbackForGloveDataStream([](const ContactGloveSDKv2::GloveData& g) {
        std::cout << "glove id=" << g.id
                  << " battery=" << g.batteryPercentage << "%"
                  << "\n";
    });

    ContactGloveSDKv2::Host host;
    host.hostName = "localhost";
    host.ipAddress = "127.0.0.1";
    host.port = 25791;
    host.receivePort = 25788;

    if (sdk.ConnectToHost(host) != ContactGloveSDKv2::SDKReturnCode::Success) {
        std::cerr << "Failed to start the connection (socket or port error)\n";
        return 1;
    }

    std::this_thread::sleep_for(std::chrono::seconds(5));
    sdk.Disconnect(host);
    return 0;
}

より長いサンプル:

share/ContactGloveSDKv2/examples/basic_usage.cpp

トラブルシュート

contactglove-basic-usageが[poll] waiting for callback dataを表示し続ける:

DivingStationが起動しているか確認してください。
DivingStation上でグローブが接続済みか確認してください。
SDK側受信ポート25788を他のアプリが使用していないか確認してください。

[callback] id=...は出るが[poll] <id>: no data yetが続く:

contactglove-basic-usageを一度終了し、同じSDK受信ポートを使う別アプリがない状態で再実行してください。
DivingStation上で該当グローブが有効な状態か確認してください。

アプリ起動時にContactGloveSDKv2.dllが見つからない:

bin/ContactGloveSDKv2.dllを自分の.exeと同じフォルダにコピーしてください。
または、SDK配布物のbin/フォルダをPATHに追加してください。

WindowsのDebugビルドで、ConnectToHost()の呼び出し中にアプリが終了する（終了コード3など）:

DebugビルドのアプリがRelease版のContactGloveSDKv2.dllを読み込んでいます。 ContactGloveSDKv2d.dllを含むSDK配布物を使い、上記の$<TARGET_FILE:...>でDLLをコピーしてください。
ContactGloveSDKv2d.dllを含まないSDKでは、Release または RelWithDebInfo でビルドしてください。

LinuxでlibContactGloveSDKv2.so.0が見つからない:

debがインストール済みか確認してください。
任意prefixへ展開したTGZを使う場合は、ライブラリのあるlib/を LD_LIBRARY_PATHへ追加してください。

macOSでLibrary not loaded: @rpath/libContactGloveSDKv2...dylibが出る:

同梱サンプルはSDK rootのbin/から実行してください。
Rust Bindingまたは独自アプリでは、SDK rootのlib/をDYLD_LIBRARY_PATHへ追加するか、アプリバンドルの@rpathを正しく設定してください。

macOSでGatekeeperの警告が出る:

この初回配布物は未署名・未公証です。配布元と内容を確認してから、組織のmacOS セキュリティポリシーに従って実行してください。

The source directory ... does not appear to contain CMakeLists.txt:

展開したSDKのフォルダをcmake -Sに指定しています。このパッケージに CMakeLists.txtは含まれていません。-Sには利用側プロジェクトのフォルダを指定し、SDKのフォルダはCMAKE_PREFIX_PATHにのみ指定してください。

find_package(ContactGloveSDKv2 CONFIG REQUIRED)が失敗する:

展開したSDK rootをCMAKE_PREFIX_PATHに指定してください。
または、ContactGloveSDKv2_DIRに <SDK_ROOT>\lib\cmake\ContactGloveSDKv2を指定してください。

SDKソースからビルドする

配布物とSDKソースのcheckoutは用途が異なります。SDK本体をビルドするには、ソースリポジトリ、 CMake 3.20以降、C++17対応コンパイラ（MSVC 2019以降、GCC 9以降、Clang 9以降）、 CMakeが固定したoscpackを取得するためのGitが必要です。macOSではXcode Command Line Toolsを使用します。 Universal配布オプションはmacOS 13以降のarm64 / x86_64を対象にします。

git clone https://github.com/MeltInterfaceTechnologies/ContactGloveSDKv2Cpp.git
cd ContactGloveSDKv2Cpp
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

macOS Universalビルドはconfigure時に-DCONTACTGLOVE_MACOS_UNIVERSAL=ONを追加します。 install・パッケージ生成・API生成の保守手順はソースのREADMEを参照してください。

ライセンス

SDKの自社実装（C/C++、公開ヘッダー、Rust binding、サンプル、SDK文書）は Apache License 2.0 で提供します。ライセンス全文は次のファイルにあります。

share/doc/ContactGloveSDKv2/LICENSE.md

著作権表示は同じフォルダの NOTICE.md にあります。

第三者コンポーネントには各々のライセンスが適用され、Apache-2.0 へ再許諾するものではありません。第三者の表示とライセンスは次のファイルを参照してください。

share/doc/ContactGloveSDKv2/THIRD_PARTY_NOTICES.md

oscpack はSDK内部依存として同梱ビルドされ、revision 3e7e3a102e316d75fe176885a6dd08f216f2eac0 に固定されています。

別管理のプロトコル仕様書は、SDK配布物には同梱しません。 SDKのビルド・利用に仕様書の取得は不要です。

お問い合わせ

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

配布物の内容

インストール

Windows (ZIP)

Linux (TGZ)

macOS (Universal TGZ)

Ubuntu 22.04 / 24.04 (APT)

初回だけの設定

インストール

更新

必要環境

別のPCから接続する

まず疎通確認する

CMakeプロジェクトから使う

C ABIとRust Binding

最小コード例

トラブルシュート

SDKソースからビルドする

ライセンス

お問い合わせ

このページの内容

配布物の内容見出しへのリンクをコピー

インストール見出しへのリンクをコピー

Windows (ZIP)見出しへのリンクをコピー

Linux (TGZ)見出しへのリンクをコピー

macOS (Universal TGZ)見出しへのリンクをコピー

Ubuntu 22.04 / 24.04 (APT)見出しへのリンクをコピー

初回だけの設定見出しへのリンクをコピー

インストール見出しへのリンクをコピー

更新見出しへのリンクをコピー

必要環境見出しへのリンクをコピー

別のPCから接続する見出しへのリンクをコピー

まず疎通確認する見出しへのリンクをコピー

CMakeプロジェクトから使う見出しへのリンクをコピー

C ABIとRust Binding見出しへのリンクをコピー

最小コード例見出しへのリンクをコピー

トラブルシュート見出しへのリンクをコピー

SDKソースからビルドする見出しへのリンクをコピー

ライセンス見出しへのリンクをコピー

お問い合わせ見出しへのリンクをコピー

このページの内容

配布物の内容

インストール

Windows (ZIP)

Linux (TGZ)

macOS (Universal TGZ)

Ubuntu 22.04 / 24.04 (APT)

初回だけの設定

インストール

更新

必要環境

別のPCから接続する

まず疎通確認する

CMakeプロジェクトから使う

C ABIとRust Binding

最小コード例

トラブルシュート

SDKソースからビルドする

ライセンス

お問い合わせ