Références

Le module bhaptics_python fournit des fonctions pour contrôler les appareils haptiques bHaptics depuis Python. Il vous permet de lire des motifs haptiques, de contrôler directement les moteurs des appareils et de gérer la lecture haptique.

import bhaptics_python

---

Lecture haptique basée sur les événements

Lit les motifs haptiques associés à des événements spécifiques (conçus dans bHaptics Designer/Portal). Ces fonctions sont recommandées pour la plupart des applications.

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

Lit l'événement haptique prédéfini.

• La lecture des événements affecte les appareils haptiques dont l'index est la valeur par défaut (-1). Utilisez simplement le premier paramètre — le nom de l'événement — uniquement. Cela peut être utilisé à des fins générales.
• Si vous souhaitez activer un appareil haptique spécifique, vous pouvez également utiliser le deuxième paramètre — l'index de l'appareil. Vous pouvez vérifier ou définir l'index de l'appareil dans bHaptics Player.

Paramètres

• event_name : Nom de l'événement haptique.
• device_index (optionnel) : Index de l'appareil haptique.

Valeur de retour

ID de la requête. Vous pouvez l'utiliser pour arrêter la lecture. Retourne -1 en cas d'échec.

Exemple

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

Lit l'événement haptique en ajustant l'Intensity, la Duration et la direction du retour haptique.

Paramètres

• event_name : Nom de l'événement haptique.
• intensity : Multiplicateur d'Intensity haptique. Plage valide : [0.0 - 2.0] (Défaut : 1.0)
• duration : Multiplicateur de Duration. (Défaut : 1.0)
• x_offset : Fait pivoter le retour haptique dans le sens antihoraire. Plage valide : [0.0 - 360.0] (Défaut : 0.0)
• y_offset : Déplace le retour haptique vers le haut ou vers le bas. Plage valide : [-0.5 - 0.5] (Défaut : 0.0)
• device_index (optionnel) : Index de l'appareil haptique.

Valeur de retour

ID de la requête. Vous pouvez l'utiliser pour arrêter la lecture. Retourne -1 en cas d'échec.

Exemple

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

Lit les événements haptiques en boucle.

Paramètres

• event_name : Nom de l'événement haptique.
• intensity : Multiplicateur d'Intensity haptique. Plage valide : [0.0 - 2.0] (Défaut : 1.0)
• duration : Multiplicateur de Duration. (Défaut : 1.0)
• x_offset : Fait pivoter le retour haptique dans le sens antihoraire. Plage valide : [0.0 - 360.0] (Défaut : 0.0)
• y_offset : Déplace le retour haptique vers le haut ou vers le bas. Plage valide : [-0.5 - 0.5] (Défaut : 0.0)
• interval : Intervalle de temps entre les boucles, en millisecondes.
• max_count : Nombre de boucles.
• device_index (optionnel) : Index de l'appareil haptique.

Valeur de retour

ID de la requête. Vous pouvez l'utiliser pour arrêter la lecture. Retourne -1 en cas d'échec.

Exemple

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
)

Lit les événements haptiques sans attendre de résultat (fire-and-forget).

Paramètres

• event_name : Nom de l'événement haptique.
• intensity : Multiplicateur d'Intensity haptique. Plage valide : [0.0 - 2.0] (Défaut : 1.0)
• duration : Multiplicateur de Duration. (Défaut : 1.0)
• x_offset : Fait pivoter le retour haptique dans le sens antihoraire. Plage valide : [0.0 - 360.0] (Défaut : 0.0)
• y_offset : Déplace le retour haptique vers le haut ou vers le bas. Plage valide : [-0.5 - 0.5] (Défaut : 0.0)
• device_index (optionnel) : Index de l'appareil haptique.

Exemple

import bhaptics_python

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

Lecture haptique directe

Si vous souhaitez lire des retours haptiques sans événements, utilisez ces fonctions.

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

Lit le retour haptique sur un actionneur haptique spécifique.

Paramètres

• position : Type d'appareil haptique pour la lecture.

  Valeur	Appareil
  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 : La Duration du retour haptique, mesurée en millisecondes. Une valeur supérieure ou égale à 100 est recommandée.
• values : Définissez la longueur de la liste selon le nombre de moteurs de l'appareil. Les valeurs de la liste représentent l'Intensity des moteurs. Plage valide pour chaque valeur de la liste : [0 - 100]
• device_index (optionnel) : Index de l'appareil haptique.

Exemple

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

Lit le retour haptique autour de coordonnées spécifiques. Contrairement à la fonction play_dot qui spécifie l'Intensity haptique pour chaque actionneur individuellement, cette méthode spécifie l'Intensity haptique pour des coordonnées particulières.

Lors de la spécification de la position haptique, play_dot offre un contrôle discret, tandis que play_path est plus continu. play_dot attribue l'Intensity à des actionneurs individuels, tandis que play_path permet de spécifier l'Intensity pour des coordonnées spécifiques (entre 0 et 1 pour les axes X et Y), entraînant la vibration des actionneurs à proximité en conséquence.

Vous pouvez spécifier plusieurs coordonnées avec plusieurs intensités. Notez que tous les actionneurs autour de ces coordonnées dans la liste s'activeront simultanément (en même temps), et non séquentiellement. De plus, la taille de toutes les listes doit être identique.

En appelant continuellement cette fonction tout en modifiant progressivement les valeurs, vous pouvez obtenir l'effet d'un point haptique en mouvement.

Paramètres

• position : Type d'appareil haptique pour la lecture. Pour plus d'informations, veuillez consulter ici.

  Valeur	Appareil	Nombre de moteurs
  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 : La Duration du retour haptique, mesurée en millisecondes. Une valeur supérieure ou égale à 100 est recommandée.
• x : Liste des coordonnées X pour l'effet haptique. Chaque valeur doit être dans la plage : [0.0 - 1.0]
• y : Liste des coordonnées Y pour l'effet haptique. Chaque valeur doit être dans la plage : [0.0 - 1.0]
• intensity : Liste des valeurs d'Intensity pour chaque coordonnée. La longueur doit correspondre au nombre de coordonnées. Chaque valeur doit être dans la plage : [0 - 100]
• device_index (optionnel) : Index de l'appareil haptique.

Exemple

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

TactGlove uniquement. Lit le retour haptique dans TactGlove. Contrairement à l'utilisation de play_dot, vous pouvez ajuster finement la Duration haptique et les changements d'Intensity de vibration. Cela permet une expression encore plus détaillée du retour haptique.

Chaque liste doit comporter huit éléments, et au moins un élément est nécessaire pour fonctionner.

Paramètres

• position : Type d'appareil haptique pour la lecture. Utilisez uniquement 8 ou 9.

  Valeur	Appareil
  8	TactGlove(Left)
  9	TactGlove(Right)

• motors : Une liste composée de huit éléments, chacun représentant l'Intensity d'un moteur. La liste doit avoir une longueur de huit, car il y a huit moteurs dans un TactGlove. Plage valide pour chaque valeur de la liste : [0 - 100]

  Index de la liste	Position du moteur
  0	Bout du pouce
  1	Bout de l'index
  2	Bout du majeur
  3	Bout de l'annulaire
  4	Bout du petit doigt
  5	Sur le poignet
  6	Sur la paume (côté pouce)
  7	Sur la paume (côté petit doigt)

• playtimes : Une liste composée de huit éléments, chacun représentant un intervalle de temps pour l'actionnement.

  Valeur	Durée de lecture
  1	5ms
  2	10ms
  4	20ms
  6	30ms
  8	40ms

• shapes : Une liste composée de huit éléments, chacun représentant la forme des changements d'Intensity haptique au fil du temps.

  Valeur	Forme d'onde
  0	Intensity constante pendant toute la Duration
  1	Commence à l'Intensity spécifiée et diminue de moitié
  2	Commence à la moitié de l'Intensity spécifiée et augmente jusqu'à l'Intensity spécifiée.

• repeat_count : Nombre de répétitions.

Exemple

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)

Contrôle de la lecture

stop_by_request_id

async def bhaptics_python.stop_by_request_id(request_id: int)

Arrête la lecture haptique par ID de requête.

Paramètres

• request_id : ID de requête retourné par la fonction de lecture haptique.

Exemple

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)

Arrête toute lecture haptique pour un nom d'événement spécifique.

Paramètres

• event_name : Nom de l'événement haptique que vous souhaitez arrêter.

Exemple

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()

Arrête tous les retours haptiques en cours de lecture.

Cycle de vie

registry_and_initialize

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

Initialise l'environnement haptique. Cette fonction initialise le SDK et établit la connexion avec bHaptics Player. Elle doit être appelée avant d'utiliser les fonctions liées aux retours haptiques.

Paramètres

• app_id : ID d'application créé dans bHaptics Developer Portal.
• api_key : Clé API créée dans bHaptics Developer Portal.
• default_config : Passez une chaîne vide ("").

Valeur de retour

Statut de réussite de l'initialisation.

Exemple

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()

Ferme la connexion du SDK.

Vérification de l'état

is_playing_event_by_request_id

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

Vérifie l'état de lecture d'un ID de requête spécifique. Fonctionne que la lecture soit basée sur des événements ou directe.

is_playing_event_by_event_id

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

Vérifie l'état de lecture d'un événement spécifique.

is_playing_event

async def bhaptics_python.is_playing_event() -> bool

Vérifie l'état global de la lecture haptique. Fonctionne que la lecture soit basée sur des événements ou directe.

is_bhaptics_device_connected

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

Vérifie l'état de connexion d'un appareil à une position spécifique.

Paramètres

• position : Type d'appareil haptique à vérifier.

  Valeur	Appareil
  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)

Exemple

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}")

Contrôle des appareils

Les fonctions de contrôle des appareils vous permettent de gérer et d'interagir directement avec les appareils haptiques connectés, par exemple en envoyant un ping, en définissant la force de vibration ou en échangeant les positions des appareils.

ping

async def bhaptics_python.ping(device_address: str)

Envoie un ping à un appareil spécifique.

Paramètres

• device_address : L'adresse MAC de l'appareil haptique. Obtenez l'adresse en utilisant get_device_info_json.

Exemple

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()

Envoie un ping à tous les appareils connectés.

set_device_vsm

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

Définit la valeur VSM (Vibration Strength Multiplier) pour un appareil.

Paramètres

• device_address : L'adresse MAC de l'appareil haptique. Obtenez l'adresse en utilisant get_device_info_json.
• value : Valeur VSM (Vibration Strength Multiplier). Le VSM par défaut est 100 (x1.00 Feedback Intensity). Plage valide : [0 - 200]

Exemple

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)

Échange la position de l'appareil entre gauche et droite.

Les appareils pouvant échanger de position sont :

• Tactosy for Feet
• Tactosy for Hands

Paramètres

• device_address : L'adresse MAC de l'appareil haptique. Obtenez l'adresse en utilisant get_device_info_json.

Exemple

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'])

Récupération d'informations

get_device_info_json

await bhaptics_python.get_device_info_json() -> str

Retourne les informations sur les appareils connectés au format JSON.

Valeur de retour

La chaîne contenant les informations sur les appareils au format JSON.

Voici un exemple de chaîne retournée lorsque deux appareils haptiques sont connectés dans un environnement.

[
  {
    "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
  }
]

Exemple

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)}")