Guide for Python

Using our Python SDK, you can implement the haptic into your Python project.

1. Install package
2. Set Up Haptic Environment

---

Requirements

• OS: Windows 10/11 (x64)
• Python 3.8 - 3.12
• bHaptics Player installed and running
• Deployed haptic application corresponding to your project
  • App ID and API Key of the haptic app

About haptic application

You can create and manage haptic apps in Developer Portal, a web-based tool.

If you're unfamiliar with haptic apps or haven't created one yet, please follow the Portal guide before proceeding.

Before linking a haptic app to your game project, make sure the haptic app meets the following requirements:

• At least one haptic event must be created.
• API Key must be generated.
  • There is no API Key by default. To generate one, go to the "API Key" tab and click "New" button.
• Haptic app must be deployed
  • If you see "Deploy Now" button in the upper right corner, click it to deploy your haptic app. Otherwise, if you can see "Up to date", it means that the latest haptic app has already been deployed.

Also, link process requires App ID and API Key. Go to the "Settings" tab, and check the App ID and API Key.

Installation

Install the bHaptics Python SDK via pip from PyPI:

pip install bhaptics-python

Import Packages

# bHaptics SDK
import bhaptics_python

# Coroutine
import asyncio

You should also import asyncio package since most of functions are coroutine.

Set Up Haptic Environment

Before using any haptic-related functions, you need to link the haptic app to your project, and initialize the haptic environment.

To do this, you need App ID and API Key of your haptic app. You can get them from the bHaptics Developer Portal.

Initialize

• Replace "your_app_id" and "your_api_key" with your App ID and API Key.
• Before you launch the Python script, ensure the bHaptics Player application is running on your computer.

import bhaptics_python
import asyncio

async def main():
    app_id = "your_app_id"        # Replace with your App ID
    api_key = "your_api_key"      # Replace with your API key
    app_name = "Hello, bHaptics!"
    
    # Initialize SDK
    result = await bhaptics_python.registry_and_initialize(app_id, api_key, app_name)
    print(f"Initialization result: {result}")
    
    # Example: Play a haptic event
    event_name = "your_event_name"
    request_id = await bhaptics_python.play_event(event_name)
    print(f"Playing event: {event_name}, Request ID: {request_id}")

asyncio.run(main())

About Device Index

The bHaptics SDK supports controlling multiple devices simultaneously. You can target all devices or specific devices using the device index system.

All haptic devices has its own device index. By default, the device index sets to -1. You can modify the device index via bHaptics Player.

• All Devices: Functions without device_index parameter affect all unmodified devices(device index is -1).
• Specific Device: Functions with device_index parameter target a specific device.

# Affect all unmodified devices.
await bhaptics_python.play_event(event_name)

# Affect only devices that device index is 0.
await bhaptics_python.play_event(event_name, 0)

You can browse or set the device indexes via bHaptics Player.

1. On the top right, click setting icon.
2. Click "Settings".
3. Go to "Labs" tab.
4. Expand "Device Index".

Then find the device in the list, and adjust the index by clicking "+" or "-".

About Device Type

Different device types have different ranges. Use it when you need haptics for the specific body part.

Value	Device	Placed in...	Motors Count
0	TactSuit	Upper Body	32
1	TactSleeve(Left)	Left Wrist	3
2	TactSleeve(Right)	Right Wrist	3
3	TactVisor	Head	4
4	Tactosy for Hands(Left)	Left Hand	3
5	Tactosy for Hands(Right)	Right Hand	3
6	Tactosy for Feet(Left)	Left Foot	3
7	Tactosy for Feet(Right)	Right Foot	3
8	TactGlove(Left)	Left Hand	6
9	TactGlove(Right)	Right Hand	6

Device Type value is used by the haptic function that doesn't use the event, but specifies the motors vibration strength directly.

device_type = 0    # TactSuit
motors_count = 32  # TactSuit has 32 motors

strength = 50      # 50% strength
duration = 400     # 400 milliseconds

await bhaptics_python.play_dot(device_type, strength, [strength] * motors_count)

Further Reading

You're now ready to use the bHaptics haptic feature! Visit our Python Reference to play haptics in your project, or refer the complete example code below.

If you have troubles for using this library, check the Troubleshooting.

Complete Example Code

import bhaptics_python
import asyncio
import time

async def haptic_demo():
    # 1. Initialization
    app_id = "your_app_id"
    api_key = "your_api_key"
    app_name = "Hello, bHaptics!"
    
    print("🔧 Initializing bHaptics SDK...")
    result = await bhaptics_python.registry_and_initialize(app_id, api_key, app_name)
    print(f"Initialization result: {result}")
    
    print("✅ Connected to bHaptics Player.")
    
    # 2. Check device information
    device_info = await bhaptics_python.get_device_info_json()
    print(f"📱 Connected device info: {device_info}")
    
    # 3. Test haptic effects
    print("\n🎮 Starting haptic effect tests...")
    
    # Play dot pattern
    print("• Playing dot pattern")
    values = [50] * 16 + [0] * 16  # Activate first 16 of 32 motors
    await bhaptics_python.play_dot(0, 2000, values)
    await asyncio.sleep(2.5)
    
    # Play path pattern
    print("• Playing path pattern")
    x = [0.2, 0.4, 0.6, 0.8]
    y = [0.2, 0.8, 0.2, 0.8]
    intensity = [80, 60, 80, 60]
    await bhaptics_python.play_path(0, 3000, x, y, intensity)
    await asyncio.sleep(3.5)
    
    # Test glove haptics (if available)
    print("• Testing glove haptics")
    glove_motors = [100] * 6
    glove_playtimes = [500] * 6
    glove_shapes = [2] * 6
    
    # Left hand
    await bhaptics_python.play_glove(8, glove_motors, glove_playtimes, glove_shapes, 0)
    await asyncio.sleep(1)
    
    # Right hand
    await bhaptics_python.play_glove(9, glove_motors, glove_playtimes, glove_shapes, 0)
    await asyncio.sleep(1)
    
    # 4. Cleanup
    await bhaptics_python.stop_all()
    await bhaptics_python.close()
    print("🔚 Demo completed")

# Run the demo
if __name__ == "__main__":
    asyncio.run(haptic_demo())

If you want to explore more examples, check our README of official GitHub repository.

Error Handling

Always wrap SDK calls in try-catch blocks for production applications:

try:
    result = await bhaptics_python.registry_and_initialize(app_id, api_key, "")
    if not result:
        print("Failed to initialize bHaptics SDK")
except Exception as e:
    print(f"Error initializing SDK: {e}")