> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmelody.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Technical overview of the Melody hardware device, sensation scripting engine, and supported Haptic control protocols via the Melody API.

The **Melody Device** is the interactive haptics hardware we engineered in‑house, paired with the Melody sensation‑scripting ecosystem.\
Default Bluetooth (BLE) broadcast name is **`MEL-############`**, where **`############`** - are the 6-byte device BLE MAC address. All command and scripting integrations are handled through the single production API:

**Melody API:** `https://api.getmelody.io`

***

## Glossary

### General Terms

| Term     | Meaning                         |
| -------- | ------------------------------- |
| **HDC**  | Haptics Direct Control          |
| **HSC**  | Haptics Script Control          |
| **HPS**  | Haptics Points Stream           |
| **HLC**  | Haptics Loop Control            |
| **OTA**  | Over‑the‑air update             |
| **OTP**  | One‑time password               |
| **GATT** | Generic Attribute Profile (BLE) |

### Device Components

| Component       | Description                                                            |
| --------------- | ---------------------------------------------------------------------- |
| **Stroker**     | Linear actuator providing haptic motion                                |
| **Hall sensor** | Magnetic position sensor used for calibration                          |
| **Encoder**     | Motor feedback sensor for positional accuracy                          |
| **PCB**         | Printed circuit board, contains temperature and thermal safety sensors |

### Position Terminology

| Concept                | Description                                           |
| ---------------------- | ----------------------------------------------------- |
| **Position (angle)**   | Stroker position expressed in radians (`0` to `2π`)   |
| **Position (ranged)**  | Normalized position (`0–100%` or `0–10000 points`)    |
| **Calibration limits** | Physical min/max detected during hardware calibration |
| **User limits**        | Software range bound within calibration limits        |
| **Position shift**     | User defined offset relative to calibrated bounds     |

### Velocity Terminology

| Concept               | Description                                          |
| --------------------- | ---------------------------------------------------- |
| **Velocity (angle)**  | Stroker angular velocity (radians/second)            |
| **Velocity (ranged)** | Normalized velocity (`0–100%` of max hardware speed) |
| **Max velocity**      | Hardware maximum safe velocity                       |
| **User max velocity** | Software enforced speed cap                          |

### Playback States

| State      | Meaning                                |
| ---------- | -------------------------------------- |
| **IDLE**   | No active playback                     |
| **MANUAL** | Device controlled via physical buttons |
| **WIFI**   | Controlled via WiFi API                |
| **BLE**    | Controlled via BLE API                 |

***

## Data Ranges

| Parameter             | Type                   | Range       | Units                     |
| --------------------- | ---------------------- | ----------- | ------------------------- |
| **Position (ranged)** | `uint16/uint32`        | `0–10000`   | points (0.01% resolution) |
| **Position (angle)**  | `float`                | `0 → 2π`    | radians                   |
| **Velocity (ranged)** | `uint8/uint32`         | `0–100`     | % of max                  |
| **Velocity (angle)**  | `float`                | varies      | rad/s                     |
| **Battery level**     | `uint8`                | `0–100`     | %                         |
| **Battery voltage**   | `float`                | `10.0–15.0` | V                         |
| **Temperature**       | `float`                | varies      | °C                        |
| **Time**              | `uint16/uint32/uint64` | varies      | milliseconds              |

***

## Device Modes

### Active Control Modes

Playback mode is selected using the **physical mode button on the device**.

| Mode             | Requirements                                  | Behavior                                         |
| ---------------- | --------------------------------------------- | ------------------------------------------------ |
| **WiFi Mode**    | Requires a session token (see Authentication) | Device controlled through WiFi API               |
| **BLE Mode**     | Nearby BLE pairing                            | Device controlled directly through BLE commands  |
| **Offline Mode** | No connectivity                               | Local pattern and script playback inside the app |

### Service / Maintenance Modes

Stroker motion is **disabled** during service modes for safety.

| Service Mode      | Description                                                                                               |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| **CALIBRATION**   | Detects lowest and highest mechanical bounds, identifies hall sensor positions.                           |
| **OTA Update**    | Firmware update initiated from the device menu or WiFi API. Requires explicit user confirmation.          |
| **OTP Retrieval** | Generates short‑lived one‑time secrets during onboarding or device binding. Initiated from device or API. |

***

## Playback Protocols

### HDC (Haptics Direct Control)

**Supported Transports:** WiFi, BLE\
Direct position control where you define a **target position** and **movement duration**.

**Best for:**

* Manual control
* UI‑driven or interactive applications
* Simple positional motion

***

### HSC (Haptics Script Control)

**Supported:** WiFi only\
Device downloads a motion script from a remote URL, while the server orchestrates **start, stop, pause, and seek**.

**Best for:**

* Pre‑recorded video or VR content
* Scripted and synchronized playback

***

### HPS (Haptics Points Stream)

**Supported Transports:** WiFi, BLE\
Stream timestamped motion points; the device calculates velocity using **time deltas between sequential points**.

**Requirements:** Min 2 points to compute motion velocity.

**Best for:**

* Real‑time streaming experiences
* Dynamically generated motion content
* External timeline drivers

***

### HLC (Haptics Loop Control)

**Supported Transports:** WiFi, BLE\
Automatic stroking loop inside a **defined motion range** at a **set velocity**.

**Best for:**

* Continuous rhythmic sensation loops
* Automatic repeating motion patterns

***

## API Coverage Summary

| Feature            | WiFi API | BLE API |
| ------------------ | :------: | :-----: |
| Device information |     ✓    |    ✓    |
| Device status      |     ✓    |    ✓    |
| Stroker status     |     ✓    |    ✓    |
| Stroker settings   |     ✓    |    ✓    |
| WiFi setup         |     ✓    |    ✓    |
| OTP token          |     ✓    |    ✓    |
| HDC control        |     ✓    |    ✓    |
| HSC control        |     ✓    |    ✗    |
| HPS control        |     ✓    |    ✓    |
| HLC control        |     ✓    |    ✓    |
| Debug information  |     ✓    |    ✗    |
| Server connection  |     ✓    |    ✗    |
| Calibration info   |     ✓    |    ✗    |

***

## WiFi vs BLE Protocol Differences

### Command Size & Encoding

* **WiFi API** uses **32/64-bit values** (flexible numeric types, larger payloads)
* **BLE API** uses **packed binary** (optimized for MTU limits of \~512 bytes)

**Examples:**

* **HDC Command**
  `WiFi: 2×uint32 (8 bytes)`
  `BLE: 2×uint16 (4 bytes, packed binary)`
* **HPS Point Stream**
  `WiFi: uint32 pos + uint64 time`
  `BLE: uint16 pos + uint32 time (6 bytes, packed)`

**Why:** BLE has strict MTU limits and requires compact data types.

### Position Range

* Both transports use **`0–10000` ranged position values**
* Resolution: **0.01%** of full motion range
* BLE uses `uint16` (max `65535`, enough for range)
* WiFi uses 32-bit values for protocol flexibility

### Time Limits by Protocol

| Protocol            | WiFi                          | BLE                                    |
| ------------------- | ----------------------------- | -------------------------------------- |
| **HDC Time**        | `uint32` (≈ 65 years max)     | `uint16` (≤ 65535 ms, ≈ 65 seconds)    |
| **HPS Stream Time** | `uint64` (unlimited timeline) | `uint32` (≤ 49 days continuous stream) |

***

## Ecosystem Philosophy

Melody was designed to be:

* **Universal** – partner devices behave consistently via shared command schemas
* **Seekable** – timeline‑driven playback state control
* **Smooth** – motion interpolation derived automatically from point streams
* **Secure** – protected by JWT bearer authentication as defined in OpenAPI

**Hardware + Engine + SDK + Media Scripting = One ecosystem.**\
Developers implement once, creators script once — every supported device feels in sync.

***

Next: explore how to **upload scripts, start sessions, and stream motion** in the dedicated API reference tabs.