---
title: "Get Real-time Reel System Status"
method: GET
path: "/api/v1/reel/heartbeat"
tags: ["v1", "heartbeat"]
---

# Get Real-time Reel System Status

`GET /api/v1/reel/heartbeat`

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

## Response `200`

Complete real-time system status with timestamp

- HeartbeatResponse — Complete heartbeat response containing system state and timestamp. This is the top-level response model for the heartbeat endpoint, providing a timestamped snapshot of the complete reel system state.
  - `reel_state` ReelStateSchema, required — Complete operational state of the cable reel system. This schema represents the real-time status of all reel subsystems including position, movement, safety systems, and hardware condition. All measurements use SI units unless otherwise specified.
    - `loop_control_mode` integer, required — Current control loop mode of the reel system. - **0 (Open Loop)**: Basic speed control without position feedback - **1 (Closed Loop)**: Precision position control with encoder feedback
    - `cable_position` number, required — Current cable position in meters from the zero reference point.
    - `cable_position_pulses` integer, required — Current cable position in raw pulses from the zero reference point.
    - `cable_speed_mps` number, nullable — Current cable movement speed in meters per second. - **Positive**: Cable unwinding (extending from reel) - **Negative**: Cable winding (retracting to reel) - **Zero**: Cable stationary - **None**: Speed measurement unavailable (encoder disconnected)
    - `reel_direction` union, required — Current reel rotation direction. - **0 or "STOP"**: Motor stopped, no movement - **1 or "WIND"**: Motor winding cable onto reel (retracting) - **2 or "UNWIND"**: Motor unwinding cable from reel (extending)
      - integer
      - string
    - `speed_percentage` integer, required — Current motor speed as percentage of maximum speed. **Range**: 0-100% **Resolution**: 1% increments
    - `reel_safeguards_enabled` boolean, required — Master enable/disable state for all reel safety systems. - **True**: Safety systems active (recommended for normal operation) - **False**: Safety systems disabled (use only for maintenance/testing)
    - `is_remote_active` boolean, required — Remote control (API) activation status. - **True**: API control enabled, accepts movement commands - **False**: API control disabled, commands will be rejected **Control Sources**: Can be disabled by physical controls or always_enable_remote_control setting. **Override**: Set always_enable_remote_control=true to prevent physical control interference.
    - `reed_switch_closed` boolean, nullable — Reed switch sensor status (if installed). - **True**: Magnetic sensor activated (magnet near sensor) - **False**: Magnetic sensor not activated - **None**: Reed switch not installed or not configured **Purpose**: When reed switch is closed, stops the motor and rejects wind commands. **Installation**: Sensor mounted on reel, magnet attached to cable/tether.
    - `is_encoder_disconnected` boolean, required — Cable position encoder connectivity status. - **True**: Encoder offline/disconnected (critical issue, or not installed) - **False**: Encoder connected and communicating normally
    - `is_cable_counter_calibrating` boolean, required — Encoder calibration process status. - **True**: Calibration in progress (movement commands may be restricted) - **False**: Normal operation, calibration complete/inactive
    - `motor_driver_unresponsive` boolean, required — Motor driver communication status. - **True**: Driver not responding to commands (critical hardware issue) - **False**: Driver communicating normally
    - `motor_driver_error` boolean, required — Motor driver error condition indicator. - **True**: Driver reporting one or more error conditions - **False**: Driver operating normally **Details**: Specific errors listed in motor_driver_error_msgs array. **Resolution**: Error-specific troubleshooting required (see error messages).
    - `motor_driver_error_msgs` string[], required — Detailed motor driver error messages. **Format**: Human-readable error descriptions **Examples**: "Over temperature", "Main voltage low", "Motor overcurrent" **Empty Array**: No active errors (normal condition) **Multiple Errors**: Array may contain multiple simultaneous error conditions
    - `motor_encoder_position` number, nullable — Raw motor encoder position in encoder pulses/counts. **Units**: Encoder-specific pulse counts (not meters) **Purpose**: Low-level motor position feedback for diagnostics **None**: Motor encoder not installed or not available
    - `is_jogging` boolean, required — Jog operation status. - **True**: Currently executing a jog command (brief movement) - **False**: Normal operation, not jogging **Jog Operation**: Short duration movement (typically 0.1 seconds) at full speed **Purpose**: Fine position adjustments, testing, maintenance operations
    - `is_maintaining_position` boolean, nullable — Active hold position engagement status. - **True**: Active braking engaged, motor maintaining current position against external forces - **False**: Active braking disengaged, motor not actively holding position - **None**: Feature disabled or motor encoder not available **Purpose**: Prevents cable drift due to external forces (wind, payload weight) **Requirements**: Requires motor position encoder and active_position_hold_enabled setting **Behavior**: Temporarily disengages during user movement commands, re-engages when stopped
    - `estop_active` boolean, nullable — Emergency stop activation status. - **True**: Emergency stop activated (all movement disabled) - **False**: Emergency stop not active (normal operation) - **None**: Emergency stop feature not available/configured **Safety Priority**: Highest priority safety system - overrides all other commands **Recovery**: Must be manually deactivated before resuming operations
    - `command_lockout_enabled` boolean, required — Movement command lockout status. - **True**: All movement commands locked out/disabled - **False**: Movement commands accepted normally **Purpose**: Administrative lock to prevent external movement commands. **Scope**: Blocks wind, unwind, go-to-position, jog commands **Exception**: Active hold position continues to function when enabled
    - `safeguard_violations` SafeguardViolationsSchema — Status of active safety system violations. These fields indicate whether specific safety safeguards are currently being violated. A value of None means the corresponding safeguard is disabled or not applicable to the current system configuration.
      - `cable_position_below_zero_point` boolean, nullable — Indicates if the cable position has gone below the zero point gutter. - **True**: Cable has wound past the safe zero point (safety violation) - **False**: Cable position is within safe winding limits - **None**: Zero point safeguard is disabled or not configured **Action Required**: If True, the reel will stop winding operations to prevent over-winding damage. Check zero_point_gutter setting in reel configuration.
      - `cable_position_exceeds_max_length` boolean, nullable — Indicates if the cable position has exceeded the maximum allowed length. - **True**: Cable has unwound beyond safe operational limits (safety violation) - **False**: Cable position is within maximum length limits - **None**: Maximum length safeguard is disabled **Action Required**: If True, the reel will stop unwinding operations to prevent cable damage or entanglement. Check max_cable_length_meters setting.
      - `no_cable_movement_detected` boolean, nullable — Indicates system expected cable movement but encoder detected none. - **True**: Motor commanded to move but no cable movement detected (potential jam/failure) - **False**: Cable movement matches motor commands (normal operation) - **None**: Cable movement detection safeguard is disabled
    - `motor_driver` union — Detailed motor driver state and diagnostic information. Contains driver-specific status information including: - **Input voltage and power status** - **Temperature and thermal protection status** - **Hardware fault conditions** - **Driver-specific error flags and warnings** **Driver Types**: Roboclaw, Motoron (structure varies by type) **Purpose**: Hardware diagnostics and fault detection
      - RoboclawStateSchema — Schema for Roboclaw motor driver state.
        - `driver_type` 'roboclaw'
        - `input_voltage` number, nullable — The input voltage for the motor driver in volts.
        - `firmware_version` string, nullable — Roboclaw firmware version.
        - `statuses` RoboclawStatusSchema — Schema for Roboclaw-specific status flags.
          - `estop_active` boolean — Emergency stop is active.
          - `temp_error` boolean — Temperature error detected.
          - `main_voltage_high` boolean — Main voltage is too high.
          - `logic_voltage_high` boolean — Logic voltage is too high.
          - `logic_voltage_low` boolean — Logic voltage is too low.
          - `m1_driver_fault` boolean — Motor 1 driver fault detected.
          - `m1_speed_error` boolean — Motor 1 speed error detected.
          - `m1_position_error` boolean — Motor 1 position error detected.
          - `m1_current_error` boolean — Motor 1 current error detected.
          - `m1_over_current` boolean — Motor 1 over current detected.
          - `main_voltage_low` boolean — Main voltage is too low.
          - `temp_warning` boolean — Temperature warning detected.
          - `s4_signal_triggered` boolean — S4 signal has been triggered.
          - `s5_signal_triggered` boolean — S5 signal has been triggered.
          - `speed_error_limit_warning` boolean — Speed error limit warning.
          - `position_error_limit_warning` boolean — Position error limit warning.
        - `active_errors` string[] — List of active error messages from the Roboclaw.
      - MotoronStateSchema — Schema for Motoron motor driver state.
        - `driver_type` 'motoron'
        - `input_voltage` number, nullable — The input voltage for the motor driver in volts.
        - `statuses` MotoronStatusSchema — Schema for Motoron-specific status flags.
          - `reset` boolean — Controller was reset.
          - `error_active` boolean — Error is active.
          - `motor_output_enabled` boolean — Motor output is enabled.
          - `motor_driving` boolean — Motor is currently driving.
          - `no_power` boolean — No power to motor driver.
          - `motor_faulting` boolean — Motor fault detected.
  - `active_operations` ActiveOperationsSchema — Current active system operations and their status.
    - `deceleration` MotorDecelerationStatus — Motor deceleration operation status when active. Provides detailed information about automatic motor speed reduction when approaching safety limits or go-to position targets.
      - `active` boolean, required — Whether motor deceleration is currently active
      - `stage` string, required — Current deceleration stage indicating operational state. **Stage Values**: - **NORMAL**: No deceleration, full speed operation - **DECELERATED**: Speed reduced due to approaching limit/target **Usage**: Monitor this field to understand current deceleration behavior
      - `distance_to_limit` number, nullable — Distance in meters to the safety limit or go-to target triggering deceleration. **Context-Dependent Meaning**: - **Safety Limits**: Distance to max cable length or zero point boundary - **Go-To Operations**: Distance remaining to target position - **None**: Distance calculation not available or not applicable **Monitoring**: Use to gauge proximity to stopping point
      - `original_speed` integer, nullable — Original speed percentage before deceleration began. **Purpose**: Reference speed that would be used without deceleration **Range**: 0-100% when available **None**: Original speed not tracked or not applicable
      - `current_safe_speed` integer, nullable — Current safe speed percentage being applied during deceleration. **Behavior**: Actual motor speed when deceleration is active **Configuration**: Determined by motor_deceleration.decelerated_speed_percent setting **Range**: Typically 5-95% based on system configuration
      - `reason` string, nullable — Detailed human-readable reason for deceleration activation. **Go-To Target Examples**: - "Within 2.0m of go_to_target - reducing to 25%" - "Approaching go-to position at 15.5m - reducing to 25%" **Safety Limit Examples**: - "Within 2.0m of max_tether_length - reducing to 25%" - "Within 1.5m of zero_point - reducing to 25%" **Parsing**: Contains identifiable keywords for programmatic interpretation
    - `cable_position_calibration` CablePositionCalibrationStatus — Cable position calibration operation status when active. Provides detailed information about the cable position encoder calibration process that establishes accurate position reference.
      - `active` boolean, required — Whether cable position calibration is currently active
    - `operation_context` OperationContextSchema — Active operation context that modifies system behavior. When an automated operation (like docking) is in progress, this context defines what user commands are blocked and what safety overrides are in effect.
      - `operation` string, required — Name of the active operation. **Common Values**: - "docking": Payload docking sequence in progress - "undocking": Payload undocking sequence in progress - "calibration": Encoder calibration in progress **Purpose**: Human-readable identifier for the operation
      - `started_at` number, required — Unix timestamp when the operation started. **Format**: Seconds since epoch (Unix timestamp) **Purpose**: Track operation duration and detect stale operations
      - `blocks_movement` BlocksMovementSchema — Movement blocking configuration for active operations.
        - `directions` string[] — List of movement directions that are blocked by the active operation. **Possible Values**: - "STOP": Stop commands blocked (rarely used) - "WIND": Wind/retract commands blocked - "UNWIND": Unwind/extend commands blocked **Empty List**: No movement directions blocked
        - `origins` string[] — List of command origins that are blocked by the active operation. **Possible Values**: - "api": Commands from REST API - "physical_control": Commands from physical pendant/controls - "active_hold_position": Active hold position adjustments - "safety_controller": Safety system commands - "plugin_docking_mechanism": Docking plugin commands - Others as defined in MovementCommandOrigin enum **Default**: ["api", "physical_control"] - blocks user-initiated commands
      - `ignore_safeguard_violations` IgnoreSafeguardViolationsSchema — Safeguard violations that are ignored during the active operation.
        - `cable_position_below_zero_point` boolean — Whether to ignore zero point safeguard violations. - **True**: Operation is allowed to move cable below zero point (e.g., docking) - **False**: Normal zero point enforcement applies
        - `cable_position_exceeds_max_length` boolean — Whether to ignore maximum cable length safeguard violations. - **True**: Operation is allowed to exceed max cable length - **False**: Normal max length enforcement applies
        - `no_cable_movement_detected` boolean — Whether to ignore no-movement detection violations. - **True**: Operation expects periods without cable movement (e.g., reed switch interactions) - **False**: Normal movement detection enforcement applies
      - `suppresses_position_hold` boolean — Whether active position hold is suppressed during this operation. - **True**: Active hold position will not engage during operation - **False**: Normal active hold behavior applies
      - `expects_reed_switch_activity` boolean — Whether the operation expects reed switch state changes. - **True**: Reed switch changes are part of normal operation flow - **False**: Reed switch changes may indicate unexpected conditions **Purpose**: Informational flag for system monitoring
      - `owner` string, nullable — Owner/source of the operation. **Possible Values**: - "plugin_docking_mechanism": Docking plugin owns the operation - "api": API-initiated operation - Other MovementCommandOrigin values **Purpose**: Identify which subsystem is controlling the operation
      - `timeout_seconds` number, nullable — Time-to-live for the operation context in seconds. - **When set**: Context auto-clears if not refreshed before timeout - **None**: No automatic timeout **Purpose**: Safety mechanism to clear stale operations if owner crashes
  - `plugins` object — 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
  - `timestamp` string, ISO 8601 with timezone, required — UTC timestamp when the heartbeat data was captured. **Format**: ISO 8601 datetime string with timezone

## Other responses

- `401` — Could not validate credentials
- `403` — Setup required before using this endpoint
- `500` — Internal server error

---

[API](https://skmtc.net/reach-systems-tech/apis/reelapi-v1.md) · [All operations](https://skmtc.net/reach-systems-tech/apis/reelapi-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/reach-systems-tech/reelapi-v1/revisions/1dd366a9c6a3/schema)