Tacton Playback

A Python application for playing vibrotactile patterns on CollabJam devices.

Overview

This project provides a command-line tool to playback vibrotactile patterns on CollabJam devices via BLE. It supports parsing pattern files, simulating playback, and sending commands directly to compatible hardware (CollabJam PCB [v1,v4]).

Requirements

• Python 3.12+
• bleak (GitHub)
• asyncio

Setup

This project uses the uv package manager. To set up the environment and install dependencies, first make sure to install uv (see installation guide). Then run the following command.

uv sync

Scripts

• src/tacton_playback.py: Main application logic for parsing, simulating, and playing back vibrotactile patterns
• src/bleak_discover.py: Utility script for discovering BLE devices

Usage

Basic Usage

uv run src/tacton_playback.py <device_address/identifier> <pattern_file>

python src/tacton_playback.py <device_address/identifier> <pattern_file>

Options

• -t, --timeline: Only print the timeline of commands without executing them
• -s, --simulate: Simulate playback without playback on the device

Pattern File Format

Pattern files contain commands in the following format:

SET <channel1,channel2,...> <intensity>
WAIT <delay_ms>

Example:

SET 0,1 0.5
WAIT 1000
SET 2,3 0.8
WAIT 500

Details of the format are provided in doc/vt_pattern_text_format.md.

bleak_discover.py

The bleak_discover.py script is used to discover available BLE devices. Run it without arguments to scan for nearby devices:

uv run src/bleak_discover.py

python src/bleak_discover.py

This will list all discovered BLE devices with their addresses and names. The CollabJam firmware (GitHub) provides BLE characteristics that can be read or written. Details of these characteristics are provided in doc/ble_peripheral.md.