Referenzen

Das Modul bhaptics_python stellt Funktionen zur Steuerung von bHaptics-Haptikgeräten aus Python bereit. Es ermöglicht Ihnen, haptische Pattern abzuspielen, Gerätemotoren direkt zu steuern und die Haptik-Wiedergabe zu verwalten.

import bhaptics_python

---

Ereignisbasierte Haptik abspielen

Spielen Sie haptische Pattern ab, die an bestimmte Ereignisse gebunden sind (entworfen im bHaptics Designer/Portal). Dies sind die empfohlenen Funktionen für die meisten Anwendungen.

play_event

async def bhaptics_python.play_event(event_name: str) -> int
async def bhaptics_python.play_event(event_name: str, device_index: int) -> int

Spielt das vordefinierte haptische Ereignis ab.

• Die Ereigniswiedergabe wirkt sich auf die Haptikgeräte aus, deren Device-Index der Standardwert (-1) ist. Verwenden Sie einfach nur den ersten Parameter — den Ereignisnamen. Dies kann für allgemeine Zwecke verwendet werden.
• Wenn Sie ein bestimmtes Haptikgerät ansteuern möchten, können Sie auch den zweiten Parameter — den Device-Index — verwenden. Den Device-Index können Sie im bHaptics Player prüfen oder festlegen.

Parameter

• event_name: Name des haptischen Ereignisses.
• device_index(optional): Device-Index des Haptikgeräts.

Rückgabewert

Request-ID. Sie können sie verwenden, um die Wiedergabe zu stoppen. Gibt bei einem Fehlschlag -1 zurück.

Beispiel

import bhaptics_python

async def play_example():
    request_id = await bhaptics_python.play_event("heartbeat")
    print(f"Playback request ID: {request_id}")

play_param

async def bhaptics_python.play_param(
    event_name: str,
    intensity: float,
    duration: float,
    x_offset: float,
    y_offset: float
) -> int
async def bhaptics_python.play_param(
    event_name: str,
    intensity: float,
    duration: float,
    x_offset: float,
    y_offset: float,
    device_index: int
) -> int

Spielt das haptische Ereignis ab und passt dabei die Stärke, die Duration und die Richtung der Haptik an.

Parameter

• event_name: Name des haptischen Ereignisses.
• intensity: Multiplikator für die haptische Intensity. Gültiger Bereich: [0.0 - 2.0] (Standard: 1.0)
• duration: Multiplikator für die Duration. (Standard: 1.0)
• x_offset: Dreht die Haptik gegen den Uhrzeigersinn. Gültiger Bereich: [0.0 - 360.0] (Standard: 0.0)
• y_offset: Bewegt die Haptik nach oben oder unten. Gültiger Bereich: [-0.5 - 0.5] (Standard: 0.0)
• device_index(optional): Device-Index des Haptikgeräts.

Rückgabewert

Request-ID. Sie können sie verwenden, um die Wiedergabe zu stoppen. Gibt bei einem Fehlschlag -1 zurück.

Beispiel

import bhaptics_python

async def play_params_example():
    request_id = await bhaptics_python.play_param(
        "pistol_r", 1.0, 1.0, 0.0, 0.0, 0
    )

play_loop

async def play_loop(
    event_name: str,
    intensity: float,
    duration: float,
    x_offset: float,
    y_offset: float,
    interval: int,
    max_count: int
) -> int
async def play_loop(
    event_name: str,
    intensity: float,
    duration: float,
    x_offset: float,
    y_offset: float,
    interval: int,
    max_count: int,
    device_index: int
) -> int

Spielt haptische Ereignisse in einer Schleife ab.

Parameter

• event_name: Name des haptischen Ereignisses.
• intensity: Multiplikator für die haptische Intensity. Gültiger Bereich: [0.0 - 2.0] (Standard: 1.0)
• duration: Multiplikator für die Duration. (Standard: 1.0)
• x_offset: Dreht die Haptik gegen den Uhrzeigersinn. Gültiger Bereich: [0.0 - 360.0] (Standard: 0.0)
• y_offset: Bewegt die Haptik nach oben oder unten. Gültiger Bereich: [-0.5 - 0.5] (Standard: 0.0)
• interval: Zeitintervall zwischen den Schleifendurchläufen in Millisekunden.
• max_count: Anzahl der Schleifendurchläufe.
• device_index(optional): Device-Index des Haptikgeräts.

Rückgabewert

Request-ID. Sie können sie verwenden, um die Wiedergabe zu stoppen. Gibt bei einem Fehlschlag -1 zurück.

Beispiel

import bhaptics_python

async def play_loop_example():
    result = await bhaptics_python.play_loop(
        "heartbeat", 0.8, 1000, 90, 0, 150, 5
    )

play_without_result

async def bhaptics_python.play_without_result(
    event_name: str,
    intensity: float,
    duration: float,
    x_offset: float,
    y_offset: float
)
async def bhaptics_python.play_without_result(
    event_name: str,
    intensity: float,
    duration: float,
    x_offset: float,
    y_offset: float,
    device_index: int
)

Spielt haptische Ereignisse ab, ohne auf Ergebnisse zu warten (fire-and-forget).

Parameter

• event_name: Name des haptischen Ereignisses.
• intensity: Multiplikator für die haptische Intensity. Gültiger Bereich: [0.0 - 2.0] (Standard: 1.0)
• duration: Multiplikator für die Duration. (Standard: 1.0)
• x_offset: Dreht die Haptik gegen den Uhrzeigersinn. Gültiger Bereich: [0.0 - 360.0] (Standard: 0.0)
• y_offset: Bewegt die Haptik nach oben oder unten. Gültiger Bereich: [-0.5 - 0.5] (Standard: 0.0)
• device_index(optional): Device-Index des Haptikgeräts.

Beispiel

import bhaptics_python

async def play_without_result_example():
    await bhaptics_python.play_without_result(
        "heartbeat", 0.8, 1.0, 90, 0.25
    )

Haptik direkt abspielen

Wenn Sie Haptik ohne Ereignisse abspielen möchten, verwenden Sie diese Funktionen.

play_dot

async def bhaptics_python.play_dot(
    position: int,
    duration_millis: int,
    values: list[int]
) -> int
async def bhaptics_python.play_dot(
    position: int,
    duration_millis: int,
    values: list[int],
    device_index: int
) -> int

Spielt haptisches Feedback auf dem bestimmten haptischen Aktuator ab.

Parameter

• position: Typ des Haptikgeräts für die Wiedergabe.

  Wert	Gerät
  0	TactSuit Pro
  1	TactSleeve(Left)
  2	TactSleeve(Right)
  3	TactVisor
  4	Tactosy for Hands(Left)
  5	Tactosy for Hands(Right)
  6	Tactosy for Feet(Left)
  7	Tactosy for Feet(Right)
  8	TactGlove(Left)
  9	TactGlove(Right)

• duration_millis: Die Duration der Haptik, gemessen in Millisekunden. Ein Wert größer oder gleich 100 wird empfohlen.
• values: Legen Sie die Länge der Liste entsprechend der Anzahl der Motoren des Geräts fest. Die Werte in der Liste geben die Intensity der Motoren an. Der gültige Bereich für jeden Wert in der Liste ist: [0 - 100]
• device_index(optional): Device-Index des Haptikgeräts.

Beispiel

import bhaptics_python

async def play_dot_example():
    # Sequentially activate 32 motors
    motor_len = 32
    values = [0 for _ in range(motor_len)]
    
    for i in range(motor_len):
        values[i] = 50
        if i > 0:
            values[i - 1] = 0
        
        request_id = await bhaptics_python.play_dot(0, 500, values)
        time.sleep(0.5)

play_path

async def bhaptics_python.play_path(
    position: int,
    duration_millis: int,
    x: list[float],
    y: list[float],
    intensity: list[int]
) -> int
async def bhaptics_python.play_path(
    position: int,
    duration_millis: int,
    x: list[float],
    y: list[float],
    intensity: list[int],
    device_index: int
) -> int

Spielt Haptik rund um bestimmte Koordinaten ab. Anders als die Funktion play_dot, die die haptische Intensity für jeden haptischen Aktuator einzeln angibt, gibt diese Methode die haptische Intensity für bestimmte Koordinaten an.

Bei der Angabe der haptischen Position bietet play_dot eine diskrete Steuerung, während play_path kontinuierlicher ist. play_dot weist einzelnen Aktuatoren eine Intensity zu, wohingegen play_path die Angabe einer Intensity für bestimmte Koordinaten (zwischen 0 und 1 sowohl für die X- als auch die Y-Achse) ermöglicht, wodurch die nahegelegenen Aktuatoren entsprechend vibrieren.

Sie können mehrere Koordinaten mit mehreren Intensities angeben. Beachten Sie, dass alle Aktuatoren um diese Koordinaten in der Liste gleichzeitig (zur selben Zeit) aktiviert werden, nicht nacheinander. Darüber hinaus muss die Größe aller Listen gleich sein.

Indem Sie diese Funktion kontinuierlich aufrufen und dabei die Werte schrittweise ändern, können Sie den Effekt eines sich bewegenden haptischen Punktes erzielen.

Parameter

• position: Typ des Haptikgeräts für die Wiedergabe. Weitere Informationen finden Sie hier.

  Wert	Gerät	Anzahl der Motoren
  0	TactSuit Pro	32
  1	TactSleeve(Left)	3
  2	TactSleeve(Right)	3
  3	TactVisor	4
  4	Tactosy for Hands(Left)	3
  5	Tactosy for Hands(Right)	3
  6	Tactosy for Feet(Left)	3
  7	Tactosy for Feet(Right)	3
  8	TactGlove(Left)	8
  9	TactGlove(Right)	8

• duration_millis: Die Duration der Haptik, gemessen in Millisekunden. Ein Wert größer oder gleich 100 wird empfohlen.
• x: Liste von X-Koordinaten für den haptischen Effect. Jeder Wert muss im Bereich liegen: [0.0 - 1.0]
• y: Liste von Y-Koordinaten für den haptischen Effect. Jeder Wert muss im Bereich liegen: [0.0 - 1.0]
• intensity: Liste von Intensity-Werten für jede Koordinate. Die Länge muss mit der Anzahl der Koordinaten übereinstimmen. Jeder Wert muss im Bereich liegen: [0 - 100]
• device_index(optional): Device-Index des Haptikgeräts.

Beispiel

import bhaptics_python
import time

async def play_path_example():
    # Path of point #1
    x1 = [0.738, 0.723, 0.709, 0.696, 0.682, 0.667, 0.653]
    y1 = [0.680, 0.715, 0.749, 0.782, 0.816, 0.852, 0.885]
    intensity1 = [20] * len(x1)
    # Path of point #2
    x2 = [0.061, 0.072, 0.102, 0.184, 0.254, 0.310, 0.363]
    y2 = [0.632, 0.587, 0.542, 0.498, 0.411, 0.366, 0.301]
    intensity2 = [60] * len(x2)

    for i in range(len(x1)):
        # Point #1 and #2 will vibrate at the same time.
        await bhaptics_python.play_path(0, 250, [x1[i], x2[i]], [y1[i], y2[i]], [intensity1[i], intensity2[i]])
        time.sleep(0.25)

play_glove

async def bhaptics_python.play_glove(
    position: int, 
    motors: list[int], 
    playtimes: list[int], 
    shapes: list[int], 
    repeat_count: int
) -> int

Nur TactGlove. Spielt Haptik im TactGlove ab. Anders als bei der Verwendung von play_dot können Sie die haptische Duration und die Änderungen der Vibrations-Intensity fein einstellen. Dies ermöglicht eine noch detailliertere Darstellung von haptischem Feedback.

Jede Liste muss acht Elemente enthalten, und mindestens ein Element ist erforderlich, damit es funktioniert.

Parameter

• position: Typ des Haptikgeräts für die Wiedergabe. Verwenden Sie nur 8 oder 9.

  Wert	Gerät
  8	TactGlove(Left)
  9	TactGlove(Right)

• motors: Eine Liste aus acht Elementen, von denen jedes die Intensity eines Motors darstellt. Die Liste muss eine Länge von acht haben, da sich in einem TactGlove acht Motoren befinden. Der gültige Bereich für jeden Wert in der Liste ist: [0 - 100]

  Listen-Index	Motor befindet sich an …
  0	Spitze des Daumens
  1	Spitze des Zeigefingers
  2	Spitze des Mittelfingers
  3	Spitze des Ringfingers
  4	Spitze des kleinen Fingers
  5	Am Handgelenk
  6	An der Handfläche (Daumenseite)
  7	An der Handfläche (Seite des kleinen Fingers)

• playtimes: Eine Liste aus acht Elementen, von denen jedes ein Zeitintervall für die Ansteuerung darstellt.

  Wert	Playtimes
  1	5ms
  2	10ms
  4	20ms
  6	30ms
  8	40ms

• shapes: Eine Liste aus acht Elementen, von denen jedes die Form der Änderungen der haptischen Intensity im Laufe der Zeit darstellt.

  Wert	Waveform
  0	Konstante Intensity für die Duration
  1	Beginnt bei der angegebenen Intensity und nimmt um die Hälfte ab
  2	Beginnt bei der Hälfte der angegebenen Intensity und steigt auf die angegebene an.

• repeat_count: Anzahl der Wiederholungen.

Beispiel

import bhaptics_python
import time

async def play_glove_example():
    motors = [100] * 8
    playtimes = [8] * 8
    shapes = [2] * 8
    
    # Left hand
    for _ in range(3):
        await bhaptics_python.play_glove(8, motors, playtimes, shapes, 0)
        time.sleep(0.3)
    
    # Right hand
    for _ in range(3):
        await bhaptics_python.play_glove(9, motors, playtimes, shapes, 0)
        time.sleep(0.3)

Wiedergabesteuerung

stop_by_request_id

async def bhaptics_python.stop_by_request_id(request_id: int)

Stoppt die Haptik-Wiedergabe anhand der Request-ID.

Parameter

• request_id: Von der Haptik-Wiedergabefunktion zurückgegebene Request-ID.

Beispiel

import bhaptics_python
import asyncio

async def stop_by_id_example():
    request_id = await bhaptics_python.play_event("shoot")
    await asyncio.sleep(2)
    await bhaptics_python.stop_by_request_id(request_id)

stop_by_event_name

async def bhaptics_python.stop_by_event_name(event_name: str)

Stoppt die gesamte Haptik-Wiedergabe für einen bestimmten Ereignisnamen.

Parameter

• event_name: Name des haptischen Ereignisses, das Sie stoppen möchten.

Beispiel

import bhaptics_python
import asyncio

async def stop_by_name_example():
    await bhaptics_python.play_event("shoot")
    await asyncio.sleep(2)
    await bhaptics_python.stop_by_event_name("shoot")

stop_all

async def bhaptics_python.stop_all()

Stoppt alle gerade abgespielten Haptiken.

Lifecycle

registry_and_initialize

async def bhaptics_python.registry_and_initialize(
    app_id: str, 
    api_key: str, 
    default_config: str
) -> bool

Initialisiert die Haptik-Umgebung. Sie initialisiert das SDK und stellt die Verbindung zum bHaptics Player her. Diese Funktion sollte aufgerufen werden, bevor die haptikbezogenen Funktionen verwendet werden.

Parameter

• app_id: Im bHaptics Developer Portal erstellte Anwendungs-ID.
• api_key: Im bHaptics Developer Portal erstellter API Key.
• default_config: Übergeben Sie einen leeren String ("").

Rückgabewert

Erfolgsstatus der Initialisierung.

Beispiel

import bhaptics_python
import asyncio

async def main():
    app_id = "your_app_id"    # App ID created in bHaptics Developer Portal
    api_key = "your_api_key"  # API key created in bHaptics Developer Portal
    
    # Initialize SDK
    result = await bhaptics_python.registry_and_initialize(app_id, api_key, "")
    print(f"Initialization result: {result}")

asyncio.run(main())

close

async def bhaptics_python.close()

Schließt die SDK-Verbindung.

Statusprüfung

is_playing_event_by_request_id

async def bhaptics_python.is_playing_event_by_request_id(request_id: int) -> bool

Prüft den Wiedergabestatus einer bestimmten Request-ID. Funktioniert sowohl bei ereignisbasierter als auch bei direkter Wiedergabe.

is_playing_event_by_event_id

async def bhaptics_python.is_playing_event_by_event_id(event_name: str) -> bool

Prüft den Wiedergabestatus eines bestimmten Ereignisses.

is_playing_event

async def bhaptics_python.is_playing_event() -> bool

Prüft den gesamten Haptik-Wiedergabestatus. Funktioniert sowohl bei ereignisbasierter als auch bei direkter Wiedergabe.

is_bhaptics_device_connected

async def bhaptics_python.is_bhaptics_device_connected(position: int) -> bool

Prüft den Verbindungsstatus eines Geräts an einer bestimmten Position.

Parameter

• position: Typ des zu prüfenden Haptikgeräts.

  Wert	Gerät
  0	TactSuit Pro
  1	TactSleeve(Left)
  2	TactSleeve(Right)
  3	TactVisor
  4	Tactosy for Hands(Left)
  5	Tactosy for Hands(Right)
  6	Tactosy for Feet(Left)
  7	Tactosy for Feet(Right)
  8	TactGlove(Left)
  9	TactGlove(Right)

Beispiel

import bhaptics_python

# Check connection status for all positions
async def check_all_positions_example():
    for i in range(10):
        is_device_connected = await bhaptics_python.is_bhaptics_device_connected(i)
        print(f"Position {i} device connection: {is_device_connected}")

Gerätesteuerung

Die Funktionen zur Gerätesteuerung ermöglichen es Ihnen, verbundene Haptikgeräte direkt zu verwalten und mit ihnen zu interagieren, etwa Ping zu senden, die Vibrationsstärke einzustellen oder die Geräteposition zu tauschen.

ping

async def bhaptics_python.ping(device_address: str)

Sendet ein Ping an ein bestimmtes Gerät.

Parameter

• device_address: Die MAC-Adresse des Haptikgeräts. Rufen Sie die Adresse mit get_device_info_json ab.

Beispiel

import bhaptics_python
import json

async def ping_first_device_example():
    device_info_string = await bhaptics_python.get_device_info_json()
    device_info_list = json.loads(device_info_string)
    
    if len(device_info_list) > 0:
        bhaptics_python.ping(device_info_list[0]['address'])

ping_all

async def bhaptics_python.ping_all()

Sendet ein Ping an alle verbundenen Geräte.

set_device_vsm

async def bhaptics_python.set_device_vsm(device_address: str, value: int)

Stellt den VSM-Wert (Vibration Strength Multiplier) für ein Gerät ein.

Parameter

• device_address: Die MAC-Adresse des Haptikgeräts. Rufen Sie die Adresse mit get_device_info_json ab.
• value: VSM-Wert (Vibration Strength Multiplier). Der Standard-VSM ist 100 (x1.00 Feedback Intensity). Gültiger Bereich: [0 - 200]

Beispiel

import bhaptics_python
import json

async def set_first_device_esm_example():
    device_info_string = await bhaptics_python.get_device_info_json()
    device_info_list = json.loads(device_info_string)
    
    if len(device_info_list) > 0:
        bhaptics_python.set_device_vsm(device_info_list[0]['address'], 100)

swap_position

async def bhaptics_python.swap_position(device_address: str)

Tauscht die Position des Geräts zwischen links und rechts.

Die Geräte, deren Position getauscht werden kann, sind:

• Tactosy for Feet
• Tactosy for Hands

Parameter

• device_address: Die MAC-Adresse des Haptikgeräts. Rufen Sie die Adresse mit get_device_info_json ab.

Beispiel

import bhaptics_python
import json

async def swap_first_device_example():
    device_info_string = await bhaptics_python.get_device_info_json()
    device_info_list = json.loads(device_info_string)
    
    if len(device_info_list) > 0:
        # Swap the position of the first device
        await bhaptics_python.swap_position(device_info_list[0]['address'])

Informationsabruf

get_device_info_json

await bhaptics_python.get_device_info_json() -> str

Gibt die Informationen der verbundenen Geräte im JSON-Format zurück.

Rückgabewert

Der String, der die Geräteinformationen im JSON-Format enthält.

Dies ist ein Beispiel für einen zurückgegebenen String, wenn in einer Umgebung zwei Haptikgeräte verbunden sind.

[
  {
    "position": 0,
    "deviceName": "TactSuitPro",
    "address": "UNIQUE_ADDRESS_GOES_HERE",
    "connected": true,
    "paired": true,
    "battery": 72,
    "audioJackIn": false,
    "vsm": 20
  },
  {
    "position": 3,
    "deviceName": "TactVisor",
    "address": "UNIQUE_ADDRESS_GOES_HERE",
    "connected": true,
    "paired": true,
    "battery": 85,
    "audioJackIn": false,
    "vsm": 20
  }
]

Beispiel

import bhaptics_python
import json

async def device_count_example():
    device_info_string = await bhaptics_python.get_device_info_json()
    device_info_list = json.loads(device_info_string)
    
    print(f"Connected device count: {len(device_info_list)}")