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

# Protocol Definitions

> Protocol Buffer (protobuf) messages and BLE binary mapping used in the HapticsConnect API.

# Protocol Definitions

This page documents the Protocol Buffer (protobuf) message definitions used in the HapticsConnect Haptics API. While BLE uses compact binary characteristic formats, understanding the underlying protobuf structures helps with WiFi API integration and provides insight into the data model.

***

## Common Types

### PlaybackProtocol Enum

```protobuf theme={null}
enum PlaybackProtocol {
    HDC = 1;  // Haptics Direct Control
    HSC = 2;  // Haptics Script Control
    HPS = 3;  // Haptics Points Stream
    HLC = 4;  // Haptics Loop Control
}

message Protocol {
    PlaybackProtocol protocol = 1;
}
```

**Purpose:** Select active stroker playback mode before sending control commands.

***

## Device Information

### DebugInformation

```protobuf theme={null}
message DebugInformation {
    uint32 free_heap_size = 2;
    uint32 external_flash_size = 3;
}
```

**Fields:**

* `free_heap_size` — Available heap memory in **bytes**
* `external_flash_size` — External flash storage in **bytes**

***

## Server Connection

### ServerStatus

```protobuf theme={null}
message ServerStatus {
    uint32 device_ip = 1;        // 4‑byte LE integer IP (e.g., 192.168.1.100 → 0xC0A80164)
    uint32 server_sync_time = 2; // Device timestamp when last server time sync was received
}
```

**Fields:**

* `device_ip` — Device IP encoded as Little‑Endian uint32
* `server_sync_time` — Timestamp of last time synchronization reference on the device

***

## Stroker (Linear Actuator)

### StrokerStatus

```protobuf theme={null}
message StrokerStatus {
    float current_pos_angle = 1;   // rad, current position in radians
    int32 current_pos_range = 2;   // points (0–10000)
    float target_pos_angle  = 3;   // rad, target position
    int32 target_pos_range  = 4;   // points (0–10000)
    float current_vel_angle = 5;   // rad/s
    int32 current_vel_range = 6;   // points/s
}
```

**Fields:**

* `current_pos_angle` — Current position (**radians**)
* `current_pos_range` — Current position (**0–10000 points**)
* `target_pos_angle` — Target position (**radians**)
* `target_pos_range` — Target position (**0–10000 points**)
* `current_vel_angle` — Current velocity (**rad/s**)
* `current_vel_range` — Current velocity (**points/s**)

***

### StrokerCalibrationInfo

```protobuf theme={null}
message StrokerCalibrationInfo {
    float calib_low_position  = 1;  // mm
    float calib_high_position = 2;  // mm
    float calibration_length  = 3;  // mm
    float hall_low_position   = 4;  // mm
    float hall_high_position  = 5;  // mm
    float calib_shift         = 6;  // mm
}
```

**Fields:**

* `calib_low_position`  — Lowest physical bound, physically blocked position (**mm**)
* `calib_high_position` — Highest physical bound, physically blocked position (**mm**)
* `calibration_length` — Full mechanical stroke length (**mm**)
* `hall_low_position`  — Hall sensor reading at low limit (**mm**)
* `hall_high_position` — Hall sensor reading at high limit (**mm**)
* `calib_shift` — Firmware positional offset applied after calibration, encoder-only (**mm**)

***

### StrokerSettings

```protobuf theme={null}
message StrokerSettings {
    float low_position_shift  = 1;  // mm
    float high_position_shift = 2;  // mm
    float max_velocity        = 3;  // max velocity limit
    float playback_rate       = 4;  // 1.0 = normal speed
}
```

**Fields:**

* `low_position_shift`  — User defined low position shift (**mm**)
* `high_position_shift` — User defined high position shift (**mm**)
* `max_velocity`        — Max velocity limit set by user
* `playback_rate`       — Playback speed multiplier (**1.0 = normal speed**)

***

## Motion Control Commands

### HDCCommand (Direct Position Move, interruptible)

```protobuf theme={null}
message HDCCommand {
    uint32 position = 1;
    uint32 time     = 2;
}
```

**Fields:**

* `position` — Target position (**transport scale dependent**)
  * WiFi normalized scale: `0–10000 points` (0.01% resolution)
  * BLE scale uses packed `uint16` (see below)
* `time`     — Travel duration (**milliseconds**)

#### BLE binary equivalent mapping

```
[uint16 position (0..10000)][uint16 time (0..65535 ms)]
Total size: 4 bytes, Little‑Endian
```

> **Important:** BLE never queues HDC commands. Every new write **interrupts active movement**.

***

### HPS (Point Streaming)

```protobuf theme={null}
message HPSPoint {
    uint32 time = 1; // ms
    uint32 pos  = 2; // 0–10000 points, 0.01% resolution
}

message HPSSignal {
    repeated HPSPoint points = 1; // max 64 per message
}
```

**Stream Contract Rules:**

* **Velocity is always device‑derived** unless using duration‑based HDC moves
* Requires **minimum 2 valid points** to calculate velocity
* Max **64 points** uploaded per message
* Max **128 points** stored in stream buffer
* Negative time delta between consecutive points → prior timestamp is treated as `0`

#### BLE Binary Layout *(per point write into Char 0x2002 > 0x0001)*

```
[uint16 position][uint32 time]
Total: 6 bytes per point, Little‑Endian
```

***

## Data Type Mapping Table

| Protobuf Type | BLE Binary Format | Size     | Valid Range                    |
| ------------- | ----------------- | -------- | ------------------------------ |
| `uint32`      | LE uint32         | 4 bytes  | 0 → 4,294,967,295              |
| `uint16`      | LE uint16         | 2 bytes  | 0 → 65,535                     |
| `uint64`      | LE uint64         | 8 bytes  | 0 → 2⁶⁴−1                      |
| `int32`       | LE int32          | 4 bytes  | −2,147,483,648 → 2,147,483,647 |
| `float`       | IEEE 754 single   | 4 bytes  | ±3.4E±38                       |
| `bool`        | 1 byte            | 1 byte   | 0 or 1                         |
| `string`      | UTF‑8 + �         | Variable | Max depends on characteristic  |

***

## Developer Mental Model

* **WiFi API → Protocol Buffers decoded to JSON**
* **BLE → Compact packed Little‑Endian binary**
* **Both share the same protocol contract logic**
* **Velocity is never transmitted in BLE point packets**
* Protocol must be set **first**, then commands are accepted

For full endpoint behavior and schema detail, explore separate protocol reference tabs in the documentation.