# 1. Device and Firmware Setup

This section walks you through setting up VectorHaptics in your project and playing your first haptic effect. Follow each step in order.

---

## 1.1 Include the Headers

At the top of your `.cpp` file, add:

```cpp
#include <VectorHaptics.h>
#include "YourBoardProfile.h"   // Replace with your board-specific header
```

`VectorHaptics.h` gives you the main haptic API. `YourBoardProfile.h` is the board-specific implementation you (or your board repo) provide—it tells VectorHaptics how to talk to your hardware (GPIO, PWM, timers, etc.).

---

## 1.2 Create the Objects

Declare the main objects your program will use:

```cpp
VectorHaptics vh;           // The haptic engine—use this to play effects
YourBoardProfile board;     // Your hardware abstraction—GPIO, PWM, etc.
VHChannels channels;        // Manages output channels (which pin drives which actuator)
```

- **vh** — The central API. You call `vh.play()`, `vh.queue()`, and similar methods on it.
- **board** — Bridges VectorHaptics to your MCU. It implements the HAL (Hardware Abstraction Layer).
- **channels** — Holds the list of output channels. Each channel maps to one or two GPIO pins that drive an actuator.

---

## 1.3 Define Channels

Before starting the engine, you must tell VectorHaptics which pins drive your actuators. Add channels in `setup()`:

```cpp
channels.add(1, {YOUR_OUTPUT_PIN}, {"main"});
```

This line adds channel 1:
- The first argument (`1`) is the channel number. Channels start at 1.
- The second argument (`{YOUR_OUTPUT_PIN}`) is the GPIO pin. Use your actual pin number (e.g. `25` on ESP32).
- The third argument (`{"main"}`) is a list of tags. Tags let you target channels by name later (e.g. `"left"`, `"motor"`).

For a dual-pin H-bridge driver, use two pins:

```cpp
channels.add(1, {PIN_A, PIN_B}, {"left", "motor"});
```

---

## 1.4 Initialize Vector Haptics

After defining channels, call `init()` so the engine knows your board and channels:

```cpp
vh.init(&board, {&channels});
```

- `&board` — Your board profile. The engine uses it to write to pins, delay, and manage timing.
- `{&channels}` — A list of extension modules. The channel manager is required for multi-channel use. You can add others later (DevTools, EffectReceiver, AudioStreaming, etc.).

Optionally set device metadata for identification:

```cpp
vh.setDeviceInfo("MyDevice", "TitanHaptics", "ModelX", "SN001", "2.1.0");
```

---

## 1.5 Play Your First Effect

Once initialized, you can play effects. A simple pulse:

```cpp
vh.play(PULSE(50, 0.8, 0.5));
```

- `50` — Duration in milliseconds.
- `0.8` — Intensity from 0.0 to 1.0 (80%).
- `0.5` — Sharpness from 0.0 to 1.0 (controls attack/decay shape).

A longer vibration at a specific frequency:

```cpp
vh.play(VIBRATE(300, 0.7, 160.0, 0.3));
```

- `300` — Duration in ms.
- `0.7` — Intensity.
- `160.0` — Frequency in Hz.
- `0.3` — Sharpness.

See [02-primitives.md](02-primitives.md) for all primitives and their parameters.

---

## 1.6 Complete Example

Here is the full setup and loop:

```cpp
#include <VectorHaptics.h>
#include "YourBoardProfile.h"

VectorHaptics vh;
YourBoardProfile board;
VHChannels channels;

void setup() {
    Serial.begin(115200);

    channels.add(1, {YOUR_OUTPUT_PIN}, {"main"});
    vh.init(&board, {&channels});
    vh.setDeviceInfo("BasicDemo", "TitanHaptics");
}

void loop() {
    vh.play(PULSE(50, 0.8, 0.5));
    delay(500);
    vh.play(VIBRATE(300, 0.7, 160.0, 0.3));
    delay(500);
}
```

Replace `YOUR_OUTPUT_PIN` with the actual GPIO number for your actuator.
