Referencias

El módulo bhaptics_python proporciona funciones para controlar dispositivos hápticos de bHaptics desde Python. Le permite reproducir patrones hápticos, controlar directamente los motores del dispositivo y gestionar la reproducción háptica.

import bhaptics_python

---

Reproducción de háptica basada en eventos

Reproduce patrones hápticos vinculados a eventos específicos (diseñados en bHaptics Designer/Portal). Estas son las funciones recomendadas para la mayoría de las aplicaciones.

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

Reproduce el evento háptico predefinido.

• La reproducción de eventos afecta a los dispositivos hápticos cuyo índice de dispositivo es el predeterminado (-1). Basta con usar solo el primer parámetro —el nombre del evento—. Esto puede usarse para fines generales.
• Si desea accionar un dispositivo háptico específico, también puede usar el segundo parámetro —el índice de dispositivo—. Puede consultar o establecer el índice de dispositivo en bHaptics Player.

Parámetros

• event_name: nombre del evento háptico.
• device_index (opcional): índice de dispositivo del dispositivo háptico.

Valor de retorno

ID de solicitud. Puede usarlo para detener la reproducción. Devuelve -1 si falla.

Ejemplo

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

Reproduce el evento háptico ajustando la intensidad, la Duration y la dirección de la háptica.

Parámetros

• event_name: nombre del evento háptico.
• intensity: multiplicador de la Intensity háptica. Rango válido: [0.0 - 2.0] (Predeterminado: 1.0)
• duration: multiplicador de la Duration. (Predeterminado: 1.0)
• x_offset: rota la háptica en sentido antihorario. Rango válido: [0.0 - 360.0] (Predeterminado: 0.0)
• y_offset: mueve la háptica hacia arriba o hacia abajo. Rango válido: [-0.5 - 0.5] (Predeterminado: 0.0)
• device_index (opcional): índice de dispositivo del dispositivo háptico.

Valor de retorno

ID de solicitud. Puede usarlo para detener la reproducción. Devuelve -1 si falla.

Ejemplo

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

Reproduce eventos hápticos en bucle.

Parámetros

• event_name: nombre del evento háptico.
• intensity: multiplicador de la Intensity háptica. Rango válido: [0.0 - 2.0] (Predeterminado: 1.0)
• duration: multiplicador de la Duration. (Predeterminado: 1.0)
• x_offset: rota la háptica en sentido antihorario. Rango válido: [0.0 - 360.0] (Predeterminado: 0.0)
• y_offset: mueve la háptica hacia arriba o hacia abajo. Rango válido: [-0.5 - 0.5] (Predeterminado: 0.0)
• interval: intervalo de tiempo entre bucles, en milisegundos.
• max_count: número de bucles.
• device_index (opcional): índice de dispositivo del dispositivo háptico.

Valor de retorno

ID de solicitud. Puede usarlo para detener la reproducción. Devuelve -1 si falla.

Ejemplo

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
)

Reproduce eventos hápticos sin esperar resultados (fire-and-forget).

Parámetros

• event_name: nombre del evento háptico.
• intensity: multiplicador de la Intensity háptica. Rango válido: [0.0 - 2.0] (Predeterminado: 1.0)
• duration: multiplicador de la Duration. (Predeterminado: 1.0)
• x_offset: rota la háptica en sentido antihorario. Rango válido: [0.0 - 360.0] (Predeterminado: 0.0)
• y_offset: mueve la háptica hacia arriba o hacia abajo. Rango válido: [-0.5 - 0.5] (Predeterminado: 0.0)
• device_index (opcional): índice de dispositivo del dispositivo háptico.

Ejemplo

import bhaptics_python

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

Reproducción directa de háptica

Si desea reproducir háptica sin eventos, use estas funciones.

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

Reproduce retroalimentación háptica en el actuador háptico específico.

Parámetros

• position: tipo de dispositivo háptico a reproducir.

  Valor	Dispositivo
  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 de la háptica, medida en milisegundos. Se recomienda un valor mayor o igual a 100.
• values: asigne la longitud de la lista según el número de motores del dispositivo. Los valores de la lista representan la Intensity de los motores. El rango válido para cada valor de la lista es: [0 - 100]
• device_index (opcional): índice de dispositivo del dispositivo háptico.

Ejemplo

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

Reproduce háptica alrededor de coordenadas específicas. A diferencia de la función play_dot, que especifica la Intensity háptica para cada actuador háptico de forma individual, este método especifica la Intensity háptica para coordenadas concretas.

Al especificar la posición de la háptica, play_dot ofrece un control discreto, mientras que play_path es más continuo. play_dot asigna la Intensity a actuadores individuales, mientras que play_path permite especificar la Intensity para coordenadas concretas (entre 0 y 1 tanto para el eje X como para el Y), haciendo que los actuadores cercanos vibren en consecuencia.

Puede colocar varias coordenadas con varias intensidades. Tenga en cuenta que todos los actuadores alrededor de estas coordenadas de la lista se activarán simultáneamente (al mismo tiempo), no de forma secuencial. Además, el tamaño de todas las listas debe ser el mismo.

Al llamar continuamente a esta función mientras cambia los valores gradualmente, puede lograr el efecto de un punto háptico en movimiento.

Parámetros

• position: tipo de dispositivo háptico a reproducir. Para obtener más información, consulte aquí.

  Valor	Dispositivo	Número de motores
  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 de la háptica, medida en milisegundos. Se recomienda un valor mayor o igual a 100.
• x: lista de coordenadas X para el efecto háptico. Cada valor debe estar en el rango: [0.0 - 1.0]
• y: lista de coordenadas Y para el efecto háptico. Cada valor debe estar en el rango: [0.0 - 1.0]
• intensity: lista de valores de Intensity para cada coordenada. La longitud debe coincidir con el número de coordenadas. Cada valor debe estar en el rango: [0 - 100]
• device_index (opcional): índice de dispositivo del dispositivo háptico.

Ejemplo

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

Solo TactGlove. Reproduce háptica en TactGlove. A diferencia del uso de play_dot, puede ajustar con precisión la Duration de la háptica y los cambios de Intensity de la vibración. Esto permite una expresión aún más detallada de la retroalimentación háptica.

Cada lista debe tener ocho elementos, y se requiere al menos un elemento para que funcione.

Parámetros

• position: tipo de dispositivo háptico a reproducir. Use solo 8 o 9.

  Valor	Dispositivo
  8	TactGlove(Left)
  9	TactGlove(Right)

• motors: lista compuesta por ocho elementos, cada uno de los cuales representa la Intensity de un motor. La lista debe tener una longitud de ocho, ya que hay ocho motores en un TactGlove. El rango válido para cada valor de la lista es: [0 - 100]

  Índice de lista	El motor está ubicado en…
  0	Punta del pulgar
  1	Punta del dedo índice
  2	Punta del dedo medio
  3	Punta del dedo anular
  4	Punta del dedo meñique
  5	En la muñeca
  6	En la palma (lado del pulgar)
  7	En la palma (lado del dedo meñique)

• playtimes: lista compuesta por ocho elementos, cada uno de los cuales representa un intervalo de tiempo de accionamiento.

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

• shapes: lista compuesta por ocho elementos, cada uno de los cuales representa las formas de los cambios de Intensity háptica a lo largo del tiempo.

  Valor	Forma de onda
  0	Intensity constante durante la Duration
  1	Comienza con la Intensity especificada y disminuye a la mitad
  2	Comienza con la mitad de la Intensity especificada y aumenta hasta la especificada.

• repeat_count: número de repeticiones.

Ejemplo

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)

Control de la reproducción

stop_by_request_id

async def bhaptics_python.stop_by_request_id(request_id: int)

Detiene la reproducción háptica por ID de solicitud.

Parámetros

• request_id: ID de solicitud devuelto por la función de reproducción háptica.

Ejemplo

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)

Detiene toda la reproducción háptica de un nombre de evento específico.

Parámetros

• event_name: nombre del evento háptico que desea detener.

Ejemplo

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

Detiene toda la háptica que se está reproduciendo actualmente.

Ciclo de vida

registry_and_initialize

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

Inicializa el entorno háptico. Inicializará el SDK y establecerá la conexión con bHaptics Player. Esta función debe llamarse antes de usar las funciones relacionadas con la háptica.

Parámetros

• app_id: ID de la aplicación creado en bHaptics Developer Portal.
• api_key: API Key creada en bHaptics Developer Portal.
• default_config: pase una cadena vacía ("").

Valor de retorno

Estado de éxito de la inicialización.

Ejemplo

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

Cierra la conexión del SDK.

Comprobación de estado

is_playing_event_by_request_id

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

Comprueba el estado de reproducción de un ID de solicitud específico. Funciona tanto en la reproducción basada en eventos como en la reproducción directa.

is_playing_event_by_event_id

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

Comprueba el estado de reproducción de un evento específico.

is_playing_event

async def bhaptics_python.is_playing_event() -> bool

Comprueba el estado general de la reproducción háptica. Funciona tanto en la reproducción basada en eventos como en la reproducción directa.

is_bhaptics_device_connected

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

Comprueba el estado de conexión de un dispositivo en una posición específica.

Parámetros

• position: tipo de dispositivo háptico a comprobar.

  Valor	Dispositivo
  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)

Ejemplo

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

Control del dispositivo

Las funciones de control del dispositivo le permiten gestionar e interactuar directamente con los dispositivos hápticos conectados, como hacer ping, establecer la intensidad de vibración o intercambiar las posiciones de los dispositivos.

ping

async def bhaptics_python.ping(device_address: str)

Envía un ping a un dispositivo específico.

Parámetros

• device_address: la dirección MAC del dispositivo háptico. Obtenga la dirección usando get_device_info_json.

Ejemplo

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

Envía un ping a todos los dispositivos conectados.

set_device_vsm

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

Establece el valor VSM (Vibration Strength Multiplier) de un dispositivo.

Parámetros

• device_address: la dirección MAC del dispositivo háptico. Obtenga la dirección usando get_device_info_json.
• value: valor VSM (Vibration Strength Multiplier). El VSM predeterminado es 100 (x1.00 Feedback Intensity). Rango válido: [0 - 200]

Ejemplo

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)

Intercambia la posición del dispositivo entre izquierda y derecha.

Los dispositivos que pueden intercambiar la posición son:

• Tactosy for Feet
• Tactosy for Hands

Parámetros

• device_address: la dirección MAC del dispositivo háptico. Obtenga la dirección usando get_device_info_json.

Ejemplo

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

Recuperación de información

get_device_info_json

await bhaptics_python.get_device_info_json() -> str

Devuelve la información de los dispositivos conectados en formato JSON.

Valor de retorno

La cadena que contiene la información del dispositivo en formato JSON.

Este es un ejemplo de una cadena devuelta cuando hay dos dispositivos hápticos conectados en un entorno.

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

Ejemplo

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