Stroker Setup

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:

https://api.getmelody.io

All protected requests require:

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.

Getting started

Melody

Melody Streaming

Melody WiFi

Melody BLE

Stroker Status (Read)

Stroker Calibration Info (Read)

Stroker Settings (Read/Write)

Best Practices

​Stroker Status (Read)

​Stroker Calibration Info (Read)

​Stroker Settings (Read/Write)

​Best Practices

Stroker Status (Read)

Stroker Calibration Info (Read)

Stroker Settings (Read/Write)

Best Practices