> ## 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.

# Services Reference

> Low-level Bluetooth LE services and characteristics for the Melody device, including WiFi setup, device information, status, stroker control, OTP, HDC, HPS, and HLC.

# BLE Services Reference

The **Melody** device exposes several BLE services for configuration and low-latency control.

* **Device name (BLE):** `MEL-############`,  where `############` - 6-byte BLE MAC address.
* **UUID width:** 16-bit
* **Byte order:** **Little-endian**

All characteristics must be interpreted using little-endian byte ordering.

***

## Service `0x1001` — WiFi Setup

Configure WiFi credentials and read available access point list.

| Char     | Type          | R/W | Description                                           |
| -------- | ------------- | --- | ----------------------------------------------------- |
| `0x0001` | `string`      | W   | SSID (write `""` to clear)                            |
| `0x0002` | `string`      | W   | Password (write `""` to clear)                        |
| `0x0003` | `bool`        | R/W | Update AP list (write `1`, wait until it returns `0`) |
| `0x0004` | `string[128]` | R   | AP list, newline (`\n`) separated, `\0` terminated    |

***

## Service `0x1002` — Device Information

Static device metadata and identifiers.

| Char     | Type     | R/W | Description                                |
| -------- | -------- | --- | ------------------------------------------ |
| `0x0001` | `string` | R   | Device name (e.g., `"Melody"`)             |
| `0x0002` | `string` | R   | Device type (e.g., `"melody"`)             |
| `0x0003` | `string` | R   | Firmware version (CI/CD name)              |
| `0x0004` | `string` | R   | Hardware revision                          |
| `0x0005` | `uint32` | R   | Factory activation time (Unix timestamp)   |
| `0x0006` | `string` | R/W | Factory serial number (**one-time write**) |
| `0x0007` | `string` | R   | BLE MAC address                            |

***

## Service `0x1003` — Device Status

Live operational status and power / temperature information.

| Char     | Type     | R/W | Description                                                   |
| -------- | -------- | --- | ------------------------------------------------------------- |
| `0x0001` | `uint32` | R/W | Device time (UTC epoch seconds)                               |
| `0x0002` | `uint8`  | R   | Battery level (0–100%)                                        |
| `0x0003` | `float`  | R   | Battery voltage (10.0–15.0 V)                                 |
| `0x0004` | `int32`  | R   | WiFi RSSI (dB, -100 to 10)                                    |
| `0x0005` | `float`  | R   | Temperature sensor 1 (°C, near charger)                       |
| `0x0006` | `float`  | R   | Temperature sensor 2 (°C, near motor)                         |
| `0x0007` | `bool`   | W   | Power down (write `1` to shut down the device)                |
| `0x0008` | `bool`   | R   | Connected to WiFi **and** server                              |
| `0x0009` | `uint8`  | R   | Charging status (0 = not charging, 1 = charging, 2 = charged) |

***

## Service `0x1004` — Stroker Status

Current motion and target state of the stroker actuator.

| Char     | Type    | R/W | Description                        |
| -------- | ------- | --- | ---------------------------------- |
| `0x0001` | `float` | R   | Current position (rad)             |
| `0x0002` | `int32` | R   | Current position (points, 0–10000) |
| `0x0003` | `float` | R   | Target position (rad)              |
| `0x0004` | `int32` | R   | Target position (points, 0–10000)  |
| `0x0005` | `float` | R   | Current velocity (rad/s)           |
| `0x0006` | `int32` | R   | Current velocity (points/s)        |

***

## Service `0x1005` — Stroker Settings

Software motion limits in millimeters.

| Char     | Type    | R/W | Description              |
| -------- | ------- | --- | ------------------------ |
| `0x0001` | `float` | R/W | Low position shift (mm)  |
| `0x0002` | `float` | R/W | High position shift (mm) |

***

## Service `0x1006` — OTP

Generate and read short-lived OTP codes for secure pairing / token flows.

| Char     | Type        | R/W | Description                                     |
| -------- | ----------- | --- | ----------------------------------------------- |
| `0x0001` | `bool`      | R/W | Update OTP (write `1`, wait for `0` when ready) |
| `0x0002` | `string[6]` | R   | OTP token (6 characters)                        |

***

## Service `0x2001` — HDC (Haptics Direct Control)

Immediate position control. **New commands interrupt current movement** (not queued).

| Char     | Type        | R/W | Size    | Description                 |
| -------- | ----------- | --- | ------- | --------------------------- |
| `0x0001` | `uint16[2]` | W   | 4 bytes | Position + time command     |
| `0x0002` | `uint16[2]` | W   | 4 bytes | Position + velocity command |

**Binary format for `0x0001` (little-endian):**

* **Bytes 0–1:** Position (`uint16`, 0–10000)
* **Bytes 2–3:** Time (`uint16`, ms, 0–65535)

**Binary format for `0x0002` (little-endian):**

* **Bytes 0–1:** Position (`uint16`, 0–10000)
* **Bytes 2–3:** Velocity (`uint16`)

***

## Service `0x2002` — HPS (Haptics Point Stream)

Stream position/time points. Velocity is calculated from time delta between points.\
**Minimum 2 points required** for valid motion.

**Limits:**

* Max **64 points/message**
* Max **128 points total buffer**

| Char     | Type                     | R/W | Size          | Description                  |
| -------- | ------------------------ | --- | ------------- | ---------------------------- |
| `0x0001` | `[uint16, uint32] array` | W   | 6 bytes/point | Add points (position + time) |
| `0x0002` | `bool`                   | R/W | 1 byte        | Play/pause                   |
| `0x0003` | `bool`                   | W   | 1 byte        | Flush buffer                 |
| `0x0004` | `bool`                   | R/W | 1 byte        | Loop enable                  |
| `0x0005` | `float`                  | R/W | 4 bytes       | Playback rate                |
| `0x0006` | `uint32`                 | W   | 4 bytes       | Sync timestamp (ms)          |

**Binary format for `0x0001` (per point, little-endian):**

* **Bytes 0–1:** Position (`uint16`, 0–10000)
* **Bytes 2–5:** Time (`uint32`, ms)

***

## Service `0x2003` — HLC (Haptics Loop Control)

Automatic up/down stroking loop with configurable range and speed.

| Char     | Type    | R/W | Description                        |
| -------- | ------- | --- | ---------------------------------- |
| `0x0001` | `float` | R/W | Velocity                           |
| `0x0002` | `float` | R/W | Low limit (must be `<` high limit) |
| `0x0003` | `float` | R/W | High limit (must be `>` low limit) |
| `0x0004` | `bool`  | W   | Play (write `1` to start loop)     |

***

## Service `0x1007` — Firmware Update

Firmware update availability and control.

| Char     | Type   | R/W | Description                                |
| -------- | ------ | --- | ------------------------------------------ |
| `0x0001` | `bool` | R   | Firmware update available                  |
| `0x0002` | `bool` | W   | Start firmware update (write `1` to begin) |

***

## Service `0x1008` — Device Settings

Device configuration settings.

| Char     | Type     | R/W | Description                                                     |
| -------- | -------- | --- | --------------------------------------------------------------- |
| `0x0001` | `bool`   | R/W | Travel mode (if enabled, device powers on after 3s button hold) |
| `0x0002` | `string` | R/W | Client name set by client after connection (max 64 chars)       |

***

## Service `0x1009` — Debug Logs

Debug logging control and data streaming.

| Char     | Type     | R/W | Description                |
| -------- | -------- | --- | -------------------------- |
| `0x0001` | `bool`   | R/W | Enable debug log streaming |
| `0x0002` | `string` | R   | Debug log data (notify)    |

***

## Service `0x100A` — Service Commands

System-level service commands.

| Char     | Type    | R/W | Description               |
| -------- | ------- | --- | ------------------------- |
| `0x0001` | `uint8` | R/W | Current screen identifier |

***

## Notes & Best Practices

* Always respect **little-endian** ordering for all numeric values.
* Use **WiFi API** for higher-level orchestration (scripts, sessions, debug) and **BLE** for low-latency or local control.
* For robust apps:
  * Use **HPS** for smooth real-time motion.
  * Reserve **HDC** for simple, interruptible target moves.
  * Configure **HLC** as a simple, automatic loop mode driven by firmware.
* OTP and WiFi setup over BLE are ideal for **first-time device provisioning** and pairing flows.