Protocol Definitions

The WiFi API carries Protocol Buffer messages; the BLE API carries the same data packed into compact binary characteristics. This page covers the messages you meet most often and how they map onto BLE writes. The full schema.proto lives in a private repository — ask support for access.

Common Types

PlaybackProtocol

enum PlaybackProtocol {
  unknown_protocol = 0;
  hdc = 1; // Haptic Direct Control
  hsc = 2; // Haptic Script Control
  hps = 3; // Haptic Points Stream
  hlc = 4; // Haptic Loop Control
}

Purpose: select the active playback mode before sending control commands. The protocol is set through Auth.protocol when a client connects, or through DeviceRemoteControl.playback_protocol on an established connection.

Device Information

DebugInformation

message DebugInformation {
  uint32 free_heap_size = 2;
  uint32 external_flash_size = 3;
  bool debug_logging_enabled = 4;
}

Fields:

free_heap_size — available heap memory, in bytes
external_flash_size — external flash storage, in bytes
debug_logging_enabled — whether the device is currently emitting debug log frames (see Debug Logging)

Stroker (Linear Actuator)

StrokerStatus

message StrokerStatus {
  float current_pos_angle = 1;       // rad
  int32 current_pos_range = 2;       // points
  float target_pos_angle = 3;        // rad
  int32 target_pos_range = 4;        // points
  float current_vel_angle = 5;       // rad/s
  int32 current_vel_range = 6;       // points/s
}

Positions and velocities are reported twice: as an angle in radians, and normalized to the 0–10000 point range.

StrokerCalibrationInfo

message StrokerCalibrationInfo {
  float calib_low_position = 1;  // rad, stroker in physically blocked position
  float calib_high_position = 2; // rad, stroker in physically blocked position
  float calibration_length = 3;  // rad, stroker length
  float hall_low_position = 4;   // rad, low hall sensor position
  float hall_high_position = 5;  // rad, high hall sensor position
  float calib_shift = 6;         // rad, shift after calibration if only encoder used
}

Fields:

calib_low_position — lowest physical bound, where the stroker is mechanically blocked
calib_high_position — highest physical bound, where the stroker is mechanically blocked
calibration_length — full mechanical stroke length
hall_low_position — hall sensor reading at the low limit
hall_high_position — hall sensor reading at the high limit
calib_shift — offset applied after calibration when only the encoder is used

Every field of StrokerCalibrationInfo is in radians, not millimeters. The user-facing limits in StrokerSettings are the ones expressed in millimeters.

StrokerSettings

message StrokerSettings {
  float low_position_shift = 1;  // mm
  float high_position_shift = 2; // mm
  float max_velocity = 3;        // max velocity limit set by user
  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 — user-defined velocity cap
playback_rate — playback speed multiplier (1.0 = normal speed)

Motion Control Commands

HDCCommand (direct position move, interruptible)

Move is the payload of a direct control command:

message HDCCommand {
  message Command {
    uint64 request_id = 1;
    oneof command {
      Move move = 2;
    }
  }

  message Move {
    uint32 position = 1; // stroker range [0..10000)
    uint32 time = 2;     // millis
  }

  message Status {
    bool playing = 1;
    uint32 dest_position = 2;
  }
}

Fields:

position — target position, 0–10000 points (0.01% resolution)
time — travel duration, in milliseconds

BLE binary equivalent

[uint16 position (0..10000)][uint16 time (0..65535 ms)]
Total size: 4 bytes, little-endian

Because BLE packs time into a uint16, a single BLE move is capped at 65535 ms; the WiFi API uses uint32 and has no such limit.

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

HPSSignal (point streaming)

message HPSSignal {
  message HPSPoint {
    uint32 time = 1;
    uint32 pos = 2; // stroker range [0..10000)
  }

  repeated HPSPoint points = 1;
}

Stream contract:

Velocity is always derived on the device from the time delta between consecutive points
At least 2 points are required before the stroker moves
Over BLE, at most 64 points per write and 128 points in the stream buffer
A negative time delta between consecutive points causes the earlier timestamp to be treated as 0

BLE binary layout (per point, characteristic `0x2002` → `0x0001`)

[uint16 position][uint32 time]
Total: 6 bytes per point, little-endian

Data Type Mapping

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	Depends on the characteristic

Two rules that catch people out: velocity is never transmitted in BLE point packets — the device derives it — and the playback protocol must be selected before commands are accepted.

Getting started

Melody

Melody Streaming

Melody WiFi

Melody BLE

Protocol Definitions

Common Types

PlaybackProtocol

Device Information

DebugInformation

Stroker (Linear Actuator)

StrokerStatus

StrokerCalibrationInfo

StrokerSettings

Motion Control Commands

HDCCommand (direct position move, interruptible)

BLE binary equivalent

HPSSignal (point streaming)

BLE binary layout (per point, characteristic `0x2002` → `0x0001`)

Data Type Mapping

​Common Types

​PlaybackProtocol

​Device Information

​DebugInformation

​Stroker (Linear Actuator)

​StrokerStatus

​StrokerCalibrationInfo

​StrokerSettings

​Motion Control Commands

​HDCCommand (direct position move, interruptible)

​BLE binary equivalent

​HPSSignal (point streaming)

​BLE binary layout (per point, characteristic 0x2002 → 0x0001)

​Data Type Mapping

Common Types

PlaybackProtocol

Device Information

DebugInformation

Stroker (Linear Actuator)

StrokerStatus

StrokerCalibrationInfo

StrokerSettings

Motion Control Commands

HDCCommand (direct position move, interruptible)

BLE binary equivalent

HPSSignal (point streaming)

BLE binary layout (per point, characteristic `0x2002` → `0x0001`)

Data Type Mapping