​

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;   // 0..100, %
    float target_pos_angle  = 3;   // rad, target position
    int32 target_pos_range  = 4;   // 0..100, %
    float current_vel_angle = 5;   // rad/s
    int32 current_vel_range = 6;   // 0..100, % of max
}

• current_pos_angle — Current position (radians)
• current_pos_range — Current position (0–100%)
• target_pos_angle — Target position (radians)
• target_pos_range — Target position (0–100%)
• current_vel_angle — Current velocity (rad/s)
• current_vel_range — Velocity as % of max (0–100%)

​

StrokerCalibrationInfo

message StrokerCalibrationInfo {
    float calib_low_position  = 1;
    float calib_high_position = 2;
    float calib_length        = 3;
    float hall_low_position   = 4;
    float hall_high_position  = 5;
    float calib_shift         = 6;
}

• calib_low_position — Lowest physical bound (fully retracted, radians)
• calib_high_position — Highest physical bound (fully extended, radians)
• calib_length — Full mechanical stroke travel (radians)
• hall_low_position — Hall sensor reading at low limit
• hall_high_position — Hall sensor reading at high limit
• calib_shift — Firmware positional offset applied after calibration (radians)

​

StrokerSettings

message StrokerSettings {
    uint32 low_position_shift  = 1; // 0..100 %, low‑side software offset
    uint32 high_position_shift = 2; // 0..100 %, high‑side software offset
    uint32 max_velocity        = 3; // 0..100 %, max allowed velocity
}

• low_position_shift — User defined low position shift (% within calibration limits)
• high_position_shift — User defined high position shift (% within calibration limits)
• max_velocity — Software velocity safety cap (% of max safe velocity)

​

▶ 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 {
    uint64 time = 1; // ms, 64‑bit sender timescale
    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