Sign in

v1

latestOpenAPI 3.1.0raw.githubusercontent.com2026-02-1354131442.5 KB
v1
heartbeat

Get Real-time Reel System Status

Retrieve comprehensive real-time operational status of the cable reel system.

This endpoint provides critical information for monitoring reel operations including:

  • Current cable position and movement speed (both meters and raw pulses)
  • Motor driver status and error conditions
  • Safety system status (emergency stops, safeguards)
  • Encoder connectivity and calibration state
  • Active hold position engagement status
  • Command lockout and remote control status
  • Active operation contexts (docking, calibration, etc.)
  • Plugin status (charger, docking mechanism, etc.)

Usage

  • Use for real-time monitoring of the reel's operational status.
  • Implement periodic polling to keep track of system changes.
  • Useful for updating user interfaces or triggering automated responses based on reel status.
  • Check active_operations.operation_context to determine if user commands are blocked
  • Monitor plugins dictionary for enabled plugin status
get/api/v1/reel/heartbeat

Response

Complete real-time system status with timestamp

pluginsobject

Dictionary of plugin status information, keyed by plugin ID.

Contains status information for all enabled plugins. Each plugin provides its own status structure with fields relevant to that plugin type. Only enabled plugins appear in this dictionary.

Known Plugin Types:

  • aml_endura_charger: AML Endura 3/6 Charger status
  • docking: Docking mechanism status
  • power_sheave: Power sheave ethernet motor module
timestampstring ISO 8601 with timezone required

UTC timestamp when the heartbeat data was captured.

Format: ISO 8601 datetime string with timezone

Example response

{
  "reel_state": {
    "description": "Reel at rest with active hold position engaged",
    "summary": "Normal Operation - Stationary",
    "value": {
      "cable_position": 15.75,
      "cable_position_pulses": 0,
      "cable_speed_mps": 0,
      "command_lockout_enabled": false,
      "estop_active": false,
      "is_cable_counter_calibrating": false,
      "is_encoder_disconnected": false,
      "is_jogging": false,
      "is_maintaining_position": true,
      "is_remote_active": true,
      "loop_control_mode": 0,
      "motor_driver": {
        "active_errors": [],
        "driver_type": "roboclaw",
        "firmware_version": "USB Roboclaw Solo 60A v4.2.8",
        "input_voltage": 24.1,
        "statuses": {
          "estop_active": false,
          "logic_voltage_high": false,
          "logic_voltage_low": false,
          "m1_current_error": false,
          "m1_driver_fault": false,
          "m1_over_current": false,
          "m1_position_error": false,
          "m1_speed_error": false,
          "main_voltage_high": false,
          "main_voltage_low": false,
          "position_error_limit_warning": false,
          "s4_signal_triggered": false,
          "s5_signal_triggered": false,
          "speed_error_limit_warning": false,
          "temp_error": false,
          "temp_warning": false
        }
      },
      "motor_driver_error": false,
      "motor_driver_error_msgs": [],
      "motor_driver_unresponsive": false,
      "motor_encoder_position": 156250,
      "reed_switch_closed": true,
      "reel_direction": 0,
      "reel_safeguards_enabled": true,
      "safeguard_violations": {
        "cable_position_below_zero_point": false,
        "cable_position_exceeds_max_length": false,
        "no_cable_movement_detected": false
      },
      "speed_percentage": 0
    }
  },
  "active_operations": {
    "deceleration": {
      "description": "Motor deceleration when approaching go-to position target",
      "summary": "Go-To Target Deceleration",
      "value": {
        "active": true,
        "current_safe_speed": 25,
        "distance_to_limit": 1.2,
        "original_speed": 100,
        "reason": "Within 2.0m of go_to_target - reducing to 25%",
        "stage": "DECELERATED"
      }
    },
    "cable_position_calibration": {
      "active": true
    },
    "operation_context": {
      "description": "Active docking operation blocking user wind/unwind",
      "summary": "Docking Operation",
      "value": {
        "blocks_movement": {
          "directions": [
            "WIND",
            "UNWIND"
          ],
          "origins": [
            "api",
            "physical_control"
          ]
        },
        "expects_reed_switch_activity": true,
        "ignore_safeguard_violations": {
          "cable_position_below_zero_point": true,
          "cable_position_exceeds_max_length": false,
          "no_cable_movement_detected": true
        },
        "operation": "docking",
        "owner": "plugin_docking_mechanism",
        "started_at": 1731618000,
        "suppresses_position_hold": true,
        "timeout_seconds": 1
      }
    }
  }
}