Skip to main content
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 <YOUR_JWT_TOKEN>
Content-Type: application/json

​
📡 Stroker Status (Read)

Dynamic positional and velocity state of the linear haptic actuator (“Stroker”).
FieldTypeDescription
currentPositionAnglefloatCurrent stroker position (radians)
currentPositionRangedint32Current normalized position (0–100%)
targetPositionAnglefloatCurrent motion target position (radians)
targetPositionRangedint32Target normalized position (0–100%)
currentVelocityAnglefloatCurrent velocity (radians/second)
currentVelocityRangedint32Current velocity (0–100% of device max)

​
🎯 Stroker Calibration Info (Read)

Hardware-derived physical motion boundaries captured during calibration.
FieldTypeDescription
calibrationLowPositionfloatLowest physically blocked position (radians)
calibrationHighPositionfloatHighest physically blocked position (radians)
calibrationLengthfloatTotal stroke length detected during calibration (radians)
hallSensorLowPositionfloatHall sensor reading at low calibration limit (radians)
hallSensorHighPositionfloatHall sensor reading at high calibration limit (radians)
calibrationShiftfloatFirmware constant offset applied post calibration (radians)

​
⚙️ Stroker Settings (Read/Write)

Software limits and motion preferences that operate inside calibration bounds.
FieldTypeRangeDescription
lowPositionShiftuint320–100%User offset from calibrated low limit
highPositionShiftuint320–100%User offset from calibrated high limit
maxVelocityuint320–100%Max velocity safety cap
fastLoopSpeeduint320–100%Speed for “edging mode” (default: 75%)
slowLoopSpeeduint320–100%Speed for “climax mode” (default: 25%)
fastLoopRangeuint320–100%Motion range for edging (default: 25%)
slowLoopRangeuint320–100%Motion range for climax (default: 75%)
Note: Other loop-based parameters follow the same 0–100% normalization system for universality.

​
✅ 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
  • Use percentage normalization for UI sliders and motion scripting editors
  • Use Fast/Slow loops for preset rhythmic modes as part of your player UI
Next, explore how to read stroker status, update motion settings, or control loops & timelines in the API Reference → Stroker WiFi tabs.