# VectorHaptics Library Overview

An overview of the VectorHaptics haptic engine and its companion libraries — their purpose, architecture, features, and design goals for haptic creation and actuator control.

---

## What Is VectorHaptics?

VectorHaptics is a firmware library for driving haptic actuators (LRA, ERM, and compatible transducers) on microcontrollers. It provides a high-level API for authoring and playing haptic effects across multiple output channels, with support for real-time audio streaming, mixing, and remote control over serial, Bluetooth, or WiFi.

The library is **platform-independent**: hardware-specific operations are abstracted behind interfaces, so the same haptic engine can run on different MCU families. Integrators provide a board-specific adapter that implements the hardware layer; the core library remains unchanged.

---

## Design Goals

VectorHaptics aims to:

- **Simplify haptic authoring** — Define effects with parameters (duration, intensity, frequency, sharpness) instead of raw waveform samples. Built-in primitives cover common patterns: pulses, ticks, vibrations, sweeps, and pauses.
- **Support expressive haptics** — Parametric sweeps with easing, custom primitives, and mixing of audio-driven and procedural waveforms enable rich, dynamic feedback.
- **Scale from simple to complex** — Single-channel blocking playback for simple projects; multi-channel, non-blocking queue mode for applications that need concurrent effects on multiple actuators.
- **Enable flexible output** — PWM for direct motor drive, or I2S for audio-grade amplification. Channels can target individual actuators or logical groups via tags.
- **Decouple logic from hardware** — The same effect definitions and command protocols work regardless of MCU or actuator. Porting to a new platform is a matter of implementing the hardware abstraction layer.

---

## Architecture at a Glance

```
┌─────────────────────────────────────────────────────────────┐
│                    Application / User Code                   │
│   Play effects, queue sequences, send commands               │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                    VectorHaptics API                         │
│   play(), queue(), stop(), executeCommand()                  │
└────────────────────────────┬────────────────────────────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
┌─────────────────┐  ┌──────────────┐  ┌─────────────────┐
│    Channels     │  │ Waveform     │  │   Primitives    │
│  (routing,      │  │ Generation   │  │  (built-in &    │
│   mixing, DSP)  │  │              │  │   custom)       │
└────────┬────────┘  └──────────────┘  └─────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│                  Board Abstraction Layer                     │
│  (PWM, GPIO, I2S, timers — implemented per platform)         │
└─────────────────────────────────────────────────────────────┘
```

The core engine processes effect definitions, generates waveform samples, routes them to channels, and outputs via the board abstraction. Optional extension modules add audio streaming, I2S output, text commands, and binary protocol support.

---

## Libraries

### Vectorhaptics (Core) — Required

The core haptic engine. Provides:

- **Effect primitives** — Pulse, tick, vibrate, pause, ERM-style, sweep, PCM playback, and audio-stream reference
- **Channel management** — Multi-channel output with tag-based routing, per-channel mixing strategies, DSP callbacks, and idle detection
- **Playback modes** — Blocking play for simple use; non-blocking queue and render for multi-channel
- **Easing** — Multiple easing functions for parametric sweep transitions
- **Custom primitives** — User-defined waveform generators registered at runtime

### VHAudioStreaming — Optional

Streams audio (e.g., from Bluetooth A2DP or buffers) to haptic channels. Handles sample-rate conversion, channel routing, intensity scaling, and mixing with concurrent procedural effects.

### VHChannelsI2s — Optional

I2S output adapter. Routes channel data to an I2S sound bus for audio-grade amplification instead of direct PWM.

### VHDevTools — Optional

Text command interface for development and testing. Parses human-readable commands over serial (or other text input) and triggers haptic effects — useful for debugging and QA.

### VHEffectReceiver — Optional

Binary protocol receiver for production use. Accepts structured packets over serial, BLE, or WiFi, validates integrity, and executes haptic effects. Designed for low-overhead remote control.

---

## Features

### Effect Types

| Effect   | Use Case                                      |
|----------|-----------------------------------------------|
| Pulse    | Button feedback, notifications                |
| Tick     | Detent clicks, UI ticks                       |
| Vibrate  | Sustained vibration at a given frequency      |
| Pause    | Silent gap between effects in a sequence      |
| ERM      | Constant-intensity vibration (traditional motor) |
| Sweep    | Parametric transitions (intensity, frequency, sharpness) with easing |
| PCM      | Playback of raw waveform samples              |
| Audio    | Real-time audio stream mapped to haptics      |

Custom primitives allow integrators to define and register their own waveform generators.

### Multi-Channel Support

- Configure multiple output channels with pin mappings and optional tags
- Target channels by number or tag expression (e.g., "left & motor")
- Per-channel mixing when audio and procedural effects overlap
- Idle/wake callbacks for power management or UI state

### Output Paths

- **PWM** — Direct drive of haptic actuators
- **I2S** — When VHChannelsI2s is used, output can go to an I2S DAC/amplifier

### Control Interfaces

- **API** — Direct C++ calls (`play()`, `queue()`, etc.)
- **Text commands** — VHDevTools parses commands like `PULSE 100 0.8; PAUSE 50`
- **Binary protocol** — VHEffectReceiver parses packets for remote control

---

## Summary

VectorHaptics provides a complete toolkit for haptic creation and driving: high-level effect authoring, multi-channel routing, audio streaming, flexible output, and platform independence. The core library plus optional extensions can be combined as needed for each product, with all hardware-specific logic isolated in the board adapter.
