ContactGlove Python SDK V2

contactglovesdk is the ContactGlove Python SDK V2 library. It receives glove data from DivingStation over OSC and provides polling methods and callbacks.

Distribution contentsCopy Anchor Link

The downloadable distribution contains:

README.md                          (Japanese installation guide)
README_EN.md                       (English installation guide)
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

See the API reference for data types, methods, and callbacks.

RequirementsCopy Anchor Link

• ContactGlove3 Pro (with ContactGlove3, no data reaches the SDK)
• Python 3.10 or later
• DivingStation v2 or later installed and able to start

The SDK itself is pure Python and does not require an OS-specific build. Operation has been confirmed on Windows 11, macOS, and Ubuntu. Check the viewer setup and DivingStation availability separately.

The SDK communicates with DivingStation over OSC. By default, the receive port on the DivingStation side is 25791, and the receive port on the SDK side is assigned automatically by the OS.

The default source port is also send_port=0 (assigned by the OS). By default, DivingStation listens on this computer only, so another PC cannot connect. If you expose it on a trusted LAN, the default connection policy requires approval for another PC; connections from the same PC are allowed automatically.

Connect from another PCCopy Anchor Link

1. Use a trusted LAN.
2. In DivingStation's SDK / Protocol, set Listening scope to Expose on LAN. If you change the listening scope, restart DivingStation.
3. Set the SDK's destination to the numeric IP address of the DivingStation PC and its listening port (default 25791). In Python, use a setting such as Host("DivingStation", "192.168.1.100", 25791).
4. If the connection policy requires approval, allow the connection request shown in DivingStation.
5. Allow the required UDP traffic on the actual receive ports of both PCs. Set the SDK receive port with ContactGloveClient(local_port=...); for automatic allocation, check client.local_port after connecting for the actual value.

To retry while waiting for LAN approval or recovering from missing data, call connect_to_host(host) again on the same client without calling disconnect or close. This resends only Connect using the same send socket, source port, and receive port. The SDK also keeps resending Connect every 30 seconds. A successful call does not confirm LAN approval. Retries can restore the connection after DivingStation restarts; approve it again if required. Explicit disconnect ends the session and can revoke pending or granted approval.

InstallationCopy Anchor Link

Download and extract the SDK distribution, then install its wheel file from the extracted folder. Replace X.Y.Z with the version in the downloaded filename.

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

pip automatically installs the dependencies python-osc>=1.7.5 and matplotlib>=3.7.5. matplotlib is used only by examples/viewer.

Checking the connection firstCopy Anchor Link

1. Start DivingStation.
2. Connect ContactGlove3 Pro in DivingStation and make sure it is enabled.
3. Run the following from the extracted SDK distribution folder.

python ./examples/basic_usage.py

Output like the following means the SDK is receiving data from DivingStation.

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

If [device] shows an ID but [poll] stays at no data yet, specify the ID or name of the target glove with the --glove option. Replace YOUR_GLOVE_ID below with the actual ID shown in [device].

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

Using the SDK in your own projectCopy Anchor Link

Once installed, you can import and use it as an ordinary Python package.

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)

For data access and callbacks, see the API reference. The distribution also includes examples/simple_receive.py and examples/basic_usage.py.

TroubleshootingCopy Anchor Link

basic_usage.py only prints no data yet:

• Check that DivingStation is running.
• Check that the glove is connected in DivingStation.
• Check that the ID or name passed to the --glove option matches the actual glove shown in [device].

ModuleNotFoundError: No module named 'contactglovesdk':

• Check that the Python environment where you ran python -m pip install ./contactglovesdk-X.Y.Z-py3-none-any.whl is the same one you use to run the samples (if you use a virtual environment, remember to activate it).

A port-in-use error appears when running a sample:

• Check that no other application is using the receive port on the SDK side.
• Specify a different port number explicitly with ContactGloveClient(local_port=...).
• To specify the source port, use ContactGloveClient(send_port=...) or the --send-port option of simple_receive.py.

LicenseCopy Anchor Link

The Melt Interface Technologies portions of this SDK are licensed under the Apache License, Version 2.0. The full text and copyright notice are included in the distribution:

doc/LICENSE.md
doc/NOTICE.md

Third-party dependencies retain their own license terms and are not relicensed under Apache-2.0. The python-osc notice and full license are included in the distribution:

doc/THIRD_PARTY_NOTICES.md

ContactCopy Anchor Link

For questions or bug reports about this SDK, use the contact form.