​

Protocol Definitions

​

Common Types

​

PlaybackProtocol Enum

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;
}

​

Device Information

​

DebugInformation

message DebugInformation {
    uint32 free_heap_size = 2;
    uint32 external_flash_size = 3;
}

• free_heap_size — Available heap memory in bytes
• external_flash_size — External flash storage in bytes

​

Server Connection

​

ServerStatus

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
}

• 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

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
}

• 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

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
}

• 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

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
}

• 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)

message HDCCommand {
    uint32 position = 1;
    uint32 time     = 2;
}

• 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)

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
}

• 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

​

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