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

# Stroker Setup

> Read live stroker motion state, calibration bounds, hall reference points, and configure software limits for the Melody device using the WiFi API.

This guide covers **stroker motion state**, **calibration bounds**, **hall reference positions**, and **software-enforced motion settings** for the Melody hardware device, controlled over WiFi using the single production API:

```text theme={null}
https://api.getmelody.io
```

All protected requests require:

```http theme={null}
Authorization: Bearer <SESSION_TOKEN>
X-Device-Key: <DEVICE_KEY>
Content-Type: application/json
```

***

## Stroker Status *(Read)*

Dynamic positional and velocity state of the linear haptic actuator ("Stroker").

| Field                   | Type    | Description                              |
| ----------------------- | ------- | ---------------------------------------- |
| `currentPositionAngle`  | `float` | Current stroker position (radians)       |
| `currentPositionRanged` | `int32` | Current position (0–10000 points)        |
| `targetPositionAngle`   | `float` | Current motion target position (radians) |
| `targetPositionRanged`  | `int32` | Target position (0–10000 points)         |
| `currentVelocityAngle`  | `float` | Current velocity (radians/second)        |
| `currentVelocityRanged` | `int32` | Current velocity (points/s)              |

***

## Stroker Calibration Info *(Read)*

Hardware-derived physical motion boundaries captured during calibration.

| Field                     | Type    | Description                                            |
| ------------------------- | ------- | ------------------------------------------------------ |
| `calibrationLowPosition`  | `float` | Lowest physically blocked position (mm)                |
| `calibrationHighPosition` | `float` | Highest physically blocked position (mm)               |
| `calibrationLength`       | `float` | Total stroke length detected during calibration (mm)   |
| `hallSensorLowPosition`   | `float` | Hall sensor reading at low calibration limit (mm)      |
| `hallSensorHighPosition`  | `float` | Hall sensor reading at high calibration limit (mm)     |
| `calibrationShift`        | `float` | Firmware constant offset applied post calibration (mm) |

***

## Stroker Settings *(Read/Write)*

Software limits and motion preferences that operate **inside calibration bounds**.

| Field               | Type    | Description                                    |
| ------------------- | ------- | ---------------------------------------------- |
| `lowPositionShift`  | `float` | User offset from calibrated low limit (mm)     |
| `highPositionShift` | `float` | User offset from calibrated high limit (mm)    |
| `maxVelocity`       | `float` | Max velocity limit set by user                 |
| `playbackRate`      | `float` | Playback speed multiplier (1.0 = normal speed) |

***

## Best Practices

* Only adjust `Position Shift` and `Velocity` limits **after a successful calibration**
* Keep user motion bounds **inside hardware-detected calibration limits**
* Apply velocity caps when streaming (`HPS`) or looping (`HLC`) to ensure smooth, safe motion
* All position shifts are in millimeters (mm) relative to calibration bounds

***

Next, explore how to **read stroker status**, **update motion settings**, or **control loops & timelines** in the **API Reference → Stroker WiFi tabs**.