{
  "openapi": "3.1.0",
  "info": {
    "title": "ReelAPI v1",
    "description": "\n# ReelAPI - Cable Reel Control System\n\nReelAPI is a comprehensive control and monitoring system for Reach cable reel systems. This API provides features for user authentication, motor control, emergency operations, encoder calibration, and real-time status monitoring. It is designed for applications that require precise tether management and remote reel operation.\n\n## Quick Start\n\n### Base URLs\n- **API Base**: `http://{your-reel-ip}/api/v1/`\n- **Interactive Docs, Swagger**: `http://{your-reel-ip}/api/docs`\n- **Interactive Docs, Redoc**: `http://{your-reel-ip}/api/redoc`\n- **OpenAPI JSON**: `http://{your-reel-ip}/api/openapi.json`\n\n### Authentication Flow\n1. Login using `/api/v1/login` to receive an access token\n2. Include this access token in the Authorization header of subsequent requests\n3. Token lifespan: **24 hours**\n\n**Example Login:**\n```bash\ncurl -X 'POST' \n  'http://your-reel-ip/api/v1/login'   \n  -H 'Content-Type: application/x-www-form-urlencoded'   \n  -d 'grant_type=password&username=your-username&password=your-password'\n```\n\n## Measurement Standards\n\nThe ReelAPI uses **meters** as its basis for length and positioning. If different units are required, they need to be implemented by the requester.\n\n## System Architecture\n\n### Main Feature Categories\n\n#### Authentication\nUser registration and login system with JWT token-based authentication for secure API access.\n\n#### **Health and Utility**\nSystem monitoring endpoints that provide operational status information for diagnostics and monitoring systems.\n\n#### **Reel Operations**\nCore motor control functionality including wind, unwind, stop, speed control, jogging, and precise position targeting.\n\n#### **Emergency Operations**\nSafety-critical emergency stop activation and deactivation controls for immediate system shutdown when needed.\n\n#### **Encoder Operations**\nCable position management including encoder zeroing, position reading/setting, and cable offset adjustments.\n\n#### **Calibration**\nSystem calibration procedures for both cable length measurement and PID controller tuning for optimal performance.\n\n#### **Settings**\nSystem configuration management for hardware parameters, safety features, and operational modes.\n\n## Key Features\n\n### Active Hold Position\nThe active hold position feature, when enabled, will actively maintain the position it last stopped at. This setting can be disabled and enabled using the settings endpoint. When a motor encoder is installed and the feature is enabled, the system will automatically maintain precise positioning.\n\n### Real-time Monitoring\nUse the heartbeat endpoint (`GET /api/v1/reel/heartbeat`) for real-time monitoring of the reel's operational status. This provides live data including:\n- Cable position and speed\n- Motor status and direction\n- Safety system states\n- Error conditions\n- System health indicators\n\n### Safety Systems\n- **Emergency Stop**: Immediate system shutdown capability\n- **Safeguards**: Configurable safety features and operational limits\n- **Remote Control Override**: Settings to manage physical vs. remote control priority\n\n### Basic System Check\n```bash\ncurl -X 'GET' \n  'http://your-reel-ip/api/v1/health'\n```\n\n### Get Real-time Status\n```bash\ncurl -X 'GET' \n  'http://your-reel-ip/api/v1/reel/heartbeat'   \n  -H 'Authorization: Bearer <your-token>'\n```\n\n### Motor Control Examples\n```bash\n# Wind cable at 75% speed\ncurl -X 'PUT' \n  'http://your-reel-ip/api/v1/reel/wind'   \n  -H 'Authorization: Bearer <your-token>'   \n  -H 'Content-Type: application/json'   \n  -d '{\"speed\": 75}'\n\n# Go to specific position (15.5 meters)\ncurl -X 'PUT' \n  'http://your-reel-ip/api/v1/reel/go-to-position'   \n  -H 'Authorization: Bearer <your-token>'   \n  -H 'Content-Type: application/json'   \n  -d '{\"target_position\": 15.5}'\n\n# Emergency stop\ncurl -X 'PUT' \n  'http://your-reel-ip/api/v1/reel/activate-estop'   \n  -H 'Authorization: Bearer <your-token>'\n\n# Stop motor\ncurl -X 'PUT' \n  'http://your-reel-ip/api/v1/reel/stop'   \n  -H 'Authorization: Bearer <your-token>'\n```\n\n### Position Management\n```bash\n# Get current cable position\ncurl -X 'GET' \n  'http://your-reel-ip/api/v1/reel/encoder/count'   \n  -H 'Authorization: Bearer <your-token>'\n\n# Zero the encoder\ncurl -X 'PUT' \n  'http://your-reel-ip/api/v1/reel/encoder/zero'   \n  -H 'Authorization: Bearer <your-token>'\n\n# Set cable position to 10 meters\ncurl -X 'PUT' \n  'http://your-reel-ip/api/v1/reel/encoder/count'   \n  -H 'Authorization: Bearer <your-token>'   \n  -H 'Content-Type: application/json'   \n  -d '{\"cable_position\": 10.0}'\n```\n\n## Important Notes\n\n- **Network Configuration**: The URL and IP address examples use `192.168.1.90` - replace with your actual reel system IP\n- **Safety First**: Emergency stop functions are available for immediate system shutdown\n- **Authentication Required**: Most endpoints require valid JWT tokens\n- **Error Handling**: API returns detailed validation errors (422) for malformed requests\n- **Rate Limits**: Token expires after 24 hours, requiring re-authentication\n\n## Support\n\nFor technical support, system setup, and additional documentation:\n\n- **Website**: [https://www.reach-systems.com/](https://www.reach-systems.com/)\n- **Email**: [info@reach-systems.com](mailto:info@reach-systems.com)\n\n",
    "contact": {
      "name": "Reach Systems",
      "url": "https://www.reach-systems.com/",
      "email": "info@reach-systems.com"
    },
    "version": "1.3.13"
  },
  "paths": {
    "/api/v1/health": {
      "get": {
        "tags": [
          "v1",
          "health"
        ],
        "summary": "Basic API Health Check",
        "description": "Perform a basic health check of the ReelAPI system.\n\nReturns essential health status information including database connectivity, disk space availability, \nand API version. Use this endpoint for simple health monitoring and automated health checks.",
        "operationId": "health_check_api_v1_health_get",
        "responses": {
          "200": {
            "description": "Basic health status including database, disk space, and temperature",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthCheckResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error during health check",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Health check failed due to internal error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/health/detailed": {
      "get": {
        "tags": [
          "v1",
          "health"
        ],
        "summary": "Detailed API Health Diagnostics",
        "description": "Perform comprehensive health diagnostics of the ReelAPI system.\n\nReturns detailed system information including:\n- Database connectivity and latency metrics\n- Disk space utilization with detailed breakdowns\n- System identification (UUID, serial number, display name)\n- API and deployment environment information\n\nUse this endpoint for thorough system diagnostics, monitoring dashboards, and asset tracking.",
        "operationId": "detailed_health_check_api_v1_health_detailed_get",
        "responses": {
          "200": {
            "description": "Comprehensive health diagnostics with performance metrics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DetailedHealthCheckResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error during health check",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Health check failed due to internal error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/register": {
      "post": {
        "tags": [
          "v1",
          "authentication"
        ],
        "summary": "Register New User Account",
        "description": "Create a new user account for ReelAPI access.\n\nThis endpoint allows creation of new user accounts with role-based permissions.\n\n## User Roles\n- **operator** - Standard reel operation and monitoring access\n- **admin** - Full system administration capabilities\n- **sys_admin** - System administrator with all permissions including serial number updates\n\n## Registration Control\nRegistration availability is controlled by system configuration. Check registration status using the `/registration-status` endpoint before attempting registration.\n\n**NOTE**: This endpoint is disabled until further development for Role-Based Access Controls are completed.",
        "operationId": "register_user_api_v1_register_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserRegister"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Successfully created user account with username confirmation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserRegisterResponse"
                }
              }
            }
          },
          "403": {
            "description": "Registration is currently closed",
            "content": {
              "application/json": {
                "examples": {
                  "registration_closed": {
                    "summary": "Registration Disabled",
                    "description": "New user registration is currently disabled by system configuration",
                    "value": {
                      "detail": "Registration is currently closed"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Username already exists",
            "content": {
              "application/json": {
                "examples": {
                  "duplicate_username": {
                    "summary": "Username Taken",
                    "description": "The requested username is already registered to another account",
                    "value": {
                      "detail": "Username already registered"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error in registration data",
            "content": {
              "application/json": {
                "examples": {
                  "invalid_username": {
                    "summary": "Invalid Username",
                    "description": "Username does not meet validation requirements",
                    "value": {
                      "detail": [
                        {
                          "type": "value_error",
                          "loc": [
                            "body",
                            "username"
                          ],
                          "msg": "Username must be between 3 and 50 characters",
                          "input": "ab"
                        }
                      ]
                    }
                  },
                  "weak_password": {
                    "summary": "Weak Password",
                    "description": "Password does not meet security requirements",
                    "value": {
                      "detail": [
                        {
                          "type": "value_error",
                          "loc": [
                            "body",
                            "password"
                          ],
                          "msg": "Password must be at least 8 characters long",
                          "input": "weak"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/registration-status": {
      "get": {
        "tags": [
          "v1",
          "authentication"
        ],
        "summary": "Check Registration Availability",
        "description": "Check whether new user registration is currently available.\n\nThis endpoint provides information about registration availability without requiring authentication.\n\n## Registration States\n- **Open Registration** (`registration_open: true`) - New accounts can be created\n- **Closed Registration** (`registration_open: false`) - Account creation disabled for security",
        "operationId": "get_registration_status_api_v1_registration_status_get",
        "responses": {
          "200": {
            "description": "Current registration availability status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserRegistrationOpen"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/login": {
      "post": {
        "tags": [
          "v1",
          "authentication"
        ],
        "summary": "User Authentication Login",
        "description": "Authenticate user credentials and obtain access token for ReelAPI.\n\nReturns JWT access token along with user information for authentication and authorization.\n\n## Response Information\n- **access_token**: JWT Bearer token for API authentication\n- **token_type**: Token type (always \"bearer\")\n- **user_role**: User's assigned role (operator, admin, or sys_admin)\n- **username**: Authenticated username for display and identification\n\n## Token Details\n- **Type**: Bearer token for Authorization header\n- **Lifespan**: 24 hours from generation\n- **Usage Pattern**: `Authorization: Bearer <access_token>`\n\n## Frontend Usage\nUse the `user_role` field to control UI element visibility and provide role-appropriate user experiences.",
        "operationId": "login_user_api_v1_login_post",
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/Body_login_user_api_v1_login_post"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "JWT access token and user information for authenticated API access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserLoginResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed",
            "content": {
              "application/json": {
                "examples": {
                  "invalid_credentials": {
                    "summary": "Invalid Credentials",
                    "description": "Username or password is incorrect",
                    "value": {
                      "detail": "Invalid username or password"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Invalid request format",
            "content": {
              "application/json": {
                "examples": {
                  "missing_credentials": {
                    "summary": "Missing Credentials",
                    "description": "Username or password not provided in request",
                    "value": {
                      "detail": [
                        {
                          "type": "missing",
                          "loc": [
                            "body",
                            "username"
                          ],
                          "msg": "Field required"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/reel/calibration/start": {
      "post": {
        "tags": [
          "v1",
          "cable-calibration"
        ],
        "summary": "Start cable encoder calibration process",
        "description": "Initiate cable encoder calibration by recording the current encoder position as baseline.\n\nThe encoder position is recorded as the starting reference point for calibration calculations. Once started, use reel controls to unwind a measured distance of cable (1-10 meters), then complete the process with the finish endpoint.\n\nEmergency stop remains functional during calibration. Monitor calibration status via the `is_cable_counter_calibrating` field in heartbeat responses.",
        "operationId": "start_encoder_calibration_api_v1_reel_calibration_start_post",
        "responses": {
          "200": {
            "description": "Calibration initiation status with system state information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StartCalibrationResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/calibration/cancel": {
      "post": {
        "tags": [
          "v1",
          "cable-calibration"
        ],
        "summary": "Cancel active cable encoder calibration",
        "description": "Cancel the active calibration process and return to normal operations.\n\nSafely aborts calibration and the previous calibration factor is preserved. This operation is idempotent - calling cancel when no calibration is active will not result in an error.",
        "operationId": "cancel_encoder_calibration_api_v1_reel_calibration_cancel_post",
        "responses": {
          "200": {
            "description": "Calibration cancellation confirmation with restored system state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelCalibrationResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/calibration/finish": {
      "post": {
        "tags": [
          "v1",
          "cable-calibration"
        ],
        "summary": "Complete cable encoder calibration with measured distance",
        "description": "Complete calibration using the measured cable distance to calculate the new calibration factor.\n\nCalculates the calibration factor (pulses per meter) by dividing encoder position change by the actual measured cable distance. The new factor is applied immediately and saved to system configuration. Requires the exact distance in meters that the cable was extended during calibration.",
        "operationId": "finish_encoder_calibration_api_v1_reel_calibration_finish_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FinishCalibrationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Calibration completion results with new calibration factor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FinishCalibrationResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Invalid calibration measurement data",
            "content": {
              "application/json": {
                "examples": {
                  "negative_distance": {
                    "summary": "Negative Distance Invalid",
                    "description": "Cable distance must be positive value",
                    "value": {
                      "detail": [
                        {
                          "type": "value_error",
                          "loc": [
                            "body",
                            "pulled_cable_length"
                          ],
                          "msg": "Cable length must be positive",
                          "input": -5.2
                        }
                      ]
                    }
                  },
                  "zero_distance": {
                    "summary": "Zero Distance Invalid",
                    "description": "Cable distance must be greater than zero for calibration",
                    "value": {
                      "detail": [
                        {
                          "type": "value_error",
                          "loc": [
                            "body",
                            "pulled_cable_length"
                          ],
                          "msg": "Cable length must be greater than 0",
                          "input": 0.0
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/activate-estop": {
      "put": {
        "tags": [
          "v1",
          "emergency"
        ],
        "summary": "Activate emergency stop",
        "description": "Immediately activates the emergency stop system to halt all reel motor operations.\n\nWhen activated, the emergency stop system prevents any motor movement commands from executing, ensuring safe shutdown of reel operations. The system maintains its emergency stop state until explicitly deactivated.\n\nEmergency stop activation is a critical safety operation that takes priority over all other reel functions. Normal reel operations cannot resume until emergency stop is deactivated.",
        "operationId": "activate_emergency_stop_api_v1_reel_activate_estop_put",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmergencyStopActivateResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/deactivate-estop": {
      "put": {
        "tags": [
          "v1",
          "emergency"
        ],
        "summary": "Deactivate emergency stop",
        "description": "Deactivates the emergency stop system to restore normal reel operations.\n\nDeactivation releases the emergency stop lock and allows normal motor control operations to resume. The system returns to its previous operational state, ready to accept movement commands.\n\nExercise caution when deactivating emergency stop - ensure the area is clear and safe for reel operations before proceeding.",
        "operationId": "deactivate_emergency_stop_api_v1_reel_deactivate_estop_put",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmergencyStopDeactivateResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/encoder/zero": {
      "put": {
        "tags": [
          "v1",
          "cable-position"
        ],
        "summary": "Zero cable position",
        "description": "Resets the cable encoder position to zero meters.\n\nThis operation establishes a new reference point for cable position measurements by setting the current encoder reading to zero. Use this endpoint when the cable is at a known reference position and you want to reset the position counter.",
        "operationId": "zero_cable_position_api_v1_reel_encoder_zero_put",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ZeroCablePositionResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/encoder/count": {
      "get": {
        "tags": [
          "v1",
          "cable-position"
        ],
        "summary": "Get cable position",
        "description": "Retrieves the current cable position from the encoder in meters.\n\nReturns the current encoder reading converted to meters using the active calibration factor. This the cable position is also returned as part of the heartbeat data.",
        "operationId": "get_cable_position_api_v1_reel_encoder_count_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetCablePositionResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      },
      "put": {
        "tags": [
          "v1",
          "cable-position"
        ],
        "summary": "Set cable position",
        "description": "Sets the cable encoder position to a specific value in meters.\n\nThis operation manually assigns a specific position value to the current encoder reading, useful for correcting position readings or setting the encoder to match a known cable length. The position can be positive or negative depending on your reference system.",
        "operationId": "set_cable_position_api_v1_reel_encoder_count_put",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetEncoderCountRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SetEncoderCountResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/encoder/add-cable-offset": {
      "put": {
        "tags": [
          "v1",
          "cable-position"
        ],
        "summary": "Add cable position offset",
        "description": "Adds a specified offset to the current cable encoder position.\n\nThis operation performs a relative adjustment to the current position reading by adding the specified offset value. Positive values increase the position reading, negative values decrease it.",
        "operationId": "add_cable_position_offset_api_v1_reel_encoder_add_cable_offset_put",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddCableOffsetRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddCableOffsetResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/go-to-position": {
      "put": {
        "tags": [
          "v1",
          "reel-movement"
        ],
        "summary": "Move to specific cable position",
        "description": "Commands the reel motor to move to a specific cable position using encoder feedback for precise positioning.\n\nGo-to operations automatically determine the required direction (wind or unwind) based on current position and target position. The system uses encoder calibration data to convert position measurements to motor movements with high accuracy.\n\nRequires a properly calibrated encoder system and is subject to all standard safeguards including maximum cable length and zero point protection. Optional speed parameter allows control over positioning velocity.",
        "operationId": "go_to_position_api_v1_reel_go_to_position_put",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GoToRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GoToResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/stop": {
      "put": {
        "tags": [
          "v1",
          "reel-movement"
        ],
        "summary": "Stop reel motor",
        "description": "Immediately stops reel motor operation and sets motor speed to zero.\n\nStop operations provide immediate cessation of all motor movement and can be issued regardless of current motor state. This is the primary method for halting ongoing wind, unwind, or positioning operations under normal conditions.\n\nStop commands are always processed and take priority over other movement commands, making this endpoint essential for safe operation control.\n\n**NOTE**: If Active Hold Position is enabled, once the reel stops AHP will start its position maintainence procedure until a movement command is received.",
        "operationId": "stop_reel_motor_api_v1_reel_stop_put",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StopResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/unwind": {
      "put": {
        "tags": [
          "v1",
          "reel-movement"
        ],
        "summary": "Unwind reel motor",
        "description": "Initiates reel motor unwind operation to extend cable at the specified speed percentage.\n\nUnwind operations deploy cable from the reel drum and are subject to safeguard limits including maximum cable length protection and emergency stop status. The motor maintains the specified speed until stopped, interrupted by safeguards, or superseded by another command.\n\nSafety considerations include monitoring cable tension and ensuring the maximum cable length setting prevents over-extension beyond operational limits.",
        "operationId": "unwind_reel_motor_api_v1_reel_unwind_put",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReelMotorControlRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnwindResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/wind": {
      "put": {
        "tags": [
          "v1",
          "reel-movement"
        ],
        "summary": "Wind reel motor",
        "description": "Initiates reel motor wind operation to retract cable at the specified speed percentage.\n\nWind operations pull cable back onto the reel drum and are subject to safeguard limits including zero point protection and emergency stop status. The motor maintains the specified speed until stopped, interrupted by safeguards, or superseded by another command.\n\nSafety considerations include ensuring the operational area is clear of personnel and verifying that the zero point gutter setting provides adequate safety margin for automatic stopping.",
        "operationId": "wind_reel_motor_api_v1_reel_wind_put",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReelMotorControlRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WindResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/speed": {
      "put": {
        "tags": [
          "v1",
          "reel-movement"
        ],
        "summary": "Update reel motor speed",
        "description": "Updates the motor speed percentage for ongoing wind or unwind operations while maintaining current direction.\n\nSpeed updates allow real-time adjustment of motor velocity without interrupting the current operation. The new speed setting is applied immediately if the motor is currently moving, or stored for the next movement command if the motor is stopped.\n\nThis endpoint preserves the current motor direction (wind/unwind) and only modifies the velocity component of the operation.",
        "operationId": "update_reel_speed_api_v1_reel_speed_put",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReelMotorControlRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpeedUpdateResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/jog": {
      "put": {
        "tags": [
          "v1",
          "reel-movement"
        ],
        "summary": "Jog reel motor briefly",
        "description": "Performs a brief directional motor movement at full speed for precise cable positioning adjustments.\n\nJog operations run for exactly 1/10th of a second at 100% speed in the specified direction (wind or unwind). This provides fine control for cable positioning during setup, maintenance, or when precise adjustments are needed.\n\nJog commands are useful for incremental positioning and cable tension adjustment without requiring continuous motor operation or specific target positions.",
        "operationId": "jog_reel_api_v1_reel_jog_put",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReelMotorJogRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JogResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/command-lockout": {
      "get": {
        "tags": [
          "v1",
          "reel-movement"
        ],
        "summary": "Get command lockout status",
        "description": "Retrieves the current status of the command lockout feature.\n\nReturns whether movement commands are currently blocked by the lockout system. This status check allows applications to verify system state and provide appropriate user interface feedback about operational restrictions.\n\nCommand lockout status is independent of other system states like emergency stop or safeguard conditions.",
        "operationId": "get_command_lockout_status_api_v1_reel_command_lockout_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommandLockoutResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      },
      "put": {
        "tags": [
          "v1",
          "reel-movement"
        ],
        "summary": "Set command lockout status",
        "description": "Enables or disables the command lockout feature to prevent user-initiated movement operations.\n\nWhen command lockout is enabled, all movement commands (wind, unwind, go-to-position, jog, and speed updates) are blocked and return error responses. Safety features including emergency stop and active braking continue to function normally.\n\nCommand lockout provides an additional safety layer during maintenance operations or when the system must remain stationary while other processes are active.",
        "operationId": "set_command_lockout_api_v1_reel_command_lockout_put",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CommandLockoutRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommandLockoutResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/info": {
      "get": {
        "tags": [
          "v1",
          "settings"
        ],
        "summary": "Get cable reel system information",
        "description": "Retrieve static system information and capabilities including hardware \nconfiguration, calibration status, and API version details.\n\nProvides read-only information about the reel system's hardware configuration, \ncurrent calibration factors, supported maximum speeds, and installed component \nspecifications. This data remains relatively static unless hardware is modified \nor recalibrated.",
        "operationId": "get_cable_reel_info_api_v1_reel_info_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CableReelInfoResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "v1",
          "settings"
        ],
        "summary": "Update reel identification information",
        "description": "Update reel serial number and/or display name with role-based permissions",
        "operationId": "update_reel_info_api_v1_reel_info_patch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateReelInfoRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateReelInfoResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/settings": {
      "get": {
        "tags": [
          "v1",
          "settings"
        ],
        "summary": "Get current reel settings",
        "description": "Retrieve the current operational configuration of the reel system including safety \nsettings, cable limits, and control modes.\n\nReturns comprehensive configuration data for the reel system including individual \nsafeguard settings, cable length constraints, remote control permissions, and active \nposition hold parameters. This endpoint provides the current state of all \nuser-configurable system parameters.\n\nUse this endpoint to verify system configuration, populate settings interfaces, or \nensure proper system state before performing operations that depend on specific \nsettings configurations.",
        "operationId": "get_reel_settings_api_v1_reel_settings_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReelSettingsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      },
      "put": {
        "tags": [
          "v1",
          "settings"
        ],
        "summary": "Update reel settings",
        "description": "Modify operational configuration parameters for the reel system including \nsafety controls, cable limits, and advanced features.\n\nAllows selective updates to reel configuration by providing only the settings \nto be modified (null values are ignored). Changes are validated for consistency \nand safety before being applied to the system. Safeguard synchronization ensures \nmaster safeguard control properly reflects individual safeguard states.\n\nCritical safety settings modifications require careful consideration as they \ndirectly affect operational limits and protection mechanisms. Changes are \nimmediately applied and saved to persistent configuration storage.",
        "operationId": "update_reel_settings_api_v1_reel_settings_put",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateReelSettingsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateReelSettingsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/heartbeat": {
      "get": {
        "tags": [
          "v1",
          "heartbeat"
        ],
        "summary": "Get Real-time Reel System Status",
        "description": "Retrieve comprehensive real-time operational status of the cable reel system.\n\nThis endpoint provides critical information for monitoring reel operations including:\n- Current cable position and movement speed (both meters and raw pulses)\n- Motor driver status and error conditions \n- Safety system status (emergency stops, safeguards)\n- Encoder connectivity and calibration state\n- Active hold position engagement status\n- Command lockout and remote control status\n- Active operation contexts (docking, calibration, etc.)\n- Plugin status (charger, docking mechanism, etc.)\n\n## Usage\n\n- Use for real-time monitoring of the reel's operational status. \n- Implement periodic polling to keep track of system changes. \n- Useful for updating user interfaces or triggering automated responses based on reel status.\n- Check `active_operations.operation_context` to determine if user commands are blocked\n- Monitor `plugins` dictionary for enabled plugin status",
        "operationId": "get_heartbeat_api_v1_reel_heartbeat_get",
        "responses": {
          "200": {
            "description": "Complete real-time system status with timestamp",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HeartbeatResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/pid-calibration/start": {
      "post": {
        "tags": [
          "v1",
          "pid-calibration"
        ],
        "summary": "Start PID Controller Calibration",
        "description": "Initiates the automated PID controller calibration process for the active hold position feature. \nThis endpoint starts an automated calibration routine that optimizes the PID controller \nparameters for maintaining precise motor position control.\n\nThe calibration process performs a systematic tuning sequence that oscillates the motor \nposition in small increments while automatically determining optimal PID gains. During \ncalibration, the reel will move small amounts (a few degrees) as the system tests different \nparameter values. The system will either complete successfully when it finds the ultimate \ngain value or timeout after 45 seconds and cancel the procedure automatically.\n\nThis calibration is typically performed at the factory and should not be necessary during \nnormal operation. The process requires the motor position encoder to be installed and the \nactive hold position feature to be enabled in system settings. Ensure adequate unwound cable \nlength (approximately 1 meter minimum) before starting calibration to accommodate the \nautomated movement sequence.",
        "operationId": "start_pid_calibration_api_v1_reel_pid_calibration_start_post",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StartPIDCalibrationResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/reel/pid-calibration/cancel": {
      "post": {
        "tags": [
          "v1",
          "pid-calibration"
        ],
        "summary": "Cancel PID Controller Calibration",
        "description": "Cancels an active PID controller calibration process for the active hold position feature. \nThis endpoint immediately terminates any ongoing calibration routine and returns the system \nto normal operational mode.\n\nThe cancellation stops the automated tuning sequence and preserves any previously configured \nPID parameters. Use this endpoint if the calibration process needs to be interrupted due to \noperational requirements or safety concerns. The system will safely halt all calibration \nmovements and restore normal motor control functionality.\n\nCancellation requires the same system prerequisites as starting calibration, including an \ninstalled motor position encoder and enabled active hold position feature. After cancellation, \nthe system returns to its previous PID configuration state without applying any partially \ncompleted calibration results.",
        "operationId": "cancel_pid_calibration_api_v1_reel_pid_calibration_cancel_post",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelPIDCalibrationResponse"
                }
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "403": {
            "description": "Setup required before using this endpoint",
            "content": {
              "application/json": {
                "examples": {
                  "setup_incomplete": {
                    "summary": "System setup not complete",
                    "value": {
                      "detail": "Setup required before using this endpoint. Unconfigured components: ['motor_driver', 'cable_encoder']"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/logs/download": {
      "get": {
        "tags": [
          "v1",
          "utility"
        ],
        "summary": "Download ReelAPI Log Files",
        "description": "Download a ZIP archive containing all ReelAPI log files.\n\nThis endpoint creates and returns a compressed archive of all available log files from the ReelAPI system for:\n\nArchive files use the format: `reelapi_logs_YYYYMMDD_HHMMSS.zip`. Timezone is in UTC.",
        "operationId": "download_logs_api_v1_logs_download_get",
        "responses": {
          "200": {
            "description": "ZIP archive containing ReelAPI log files",
            "headers": {
              "Content-Disposition": {
                "description": "Attachment filename for download",
                "schema": {
                  "type": "string",
                  "example": "attachment; filename=reelapi_logs_20241105_143022.zip"
                }
              },
              "Content-Type": {
                "description": "MIME type for ZIP file download",
                "schema": {
                  "type": "string",
                  "example": "application/zip"
                }
              }
            },
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                },
                "example": "reelapi_logs_20241105_143022.zip"
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          },
          "404": {
            "description": "No log files found",
            "content": {
              "application/json": {
                "example": {
                  "detail": "No log files found in the log directory"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/setup/status": {
      "get": {
        "tags": [
          "v1",
          "setup",
          "factory"
        ],
        "summary": "Get System Setup Status",
        "description": "Get the current system setup mode status and component configuration state.\n\n**FACTORY USE ONLY** - This endpoint is designed for factory configuration and initial system setup.\n\nThis endpoint provides comprehensive information about the system's setup state including:\n- **Setup mode activation status** - Whether system requires configuration\n- **Component configuration progress** - Which components are configured vs pending\n- **Setup completion readiness** - Whether system can exit setup mode\n\n## Setup Mode Overview\n\nSetup mode is automatically activated when the system detects unconfigured components in the manifest. During setup mode:\n- **Normal reel operations are disabled** until all components are properly configured\n- **Only factory/setup endpoints remain accessible** for configuration tasks\n- **System remains in safe state** preventing operation with unconfigured hardware\n\n## Component Types Requiring Configuration\n\n- **motor_driver** - Motor control hardware (Roboclaw, Motoron, etc.)\n- **cable_encoder** - Cable position measurement system\n- **motor_encoder** - Motor position feedback encoder\n- **physical_control** - Manual control interfaces (pendant, switches)\n- **reed_switch** - Magnetic proximity sensors\n- **estop** - Emergency stop safety systems\n- **status_rgb_led** - Visual status indication\n- **cable_reel_chassis** - Physical reel mounting configuration\n- **serial_handler** - Communication interface setup\n\n## Usage in Factory Environment\n\n1. **Check setup status** to identify unconfigured components\n2. **Configure each component** using the appropriate hardware type\n3. **Verify configuration** by checking remaining components\n4. **Exit setup mode** once all components are configured\n\nThis endpoint is essential for **factory technicians** and **system integrators** during initial deployment.",
        "operationId": "get_setup_status_api_v1_setup_status_get",
        "responses": {
          "200": {
            "description": "Current setup mode status and component configuration state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SetupStatusDetailed"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error during setup operation",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Setup service encountered an internal error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/setup/step_summary": {
      "get": {
        "tags": [
          "v1",
          "setup",
          "factory"
        ],
        "summary": "Get summary of all setup steps and their results",
        "description": "Get complete summary of setup steps for audit/review purposes.",
        "operationId": "get_step_summary_api_v1_setup_step_summary_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/setup/configure/{component_id}": {
      "post": {
        "tags": [
          "v1",
          "setup",
          "factory"
        ],
        "summary": "Configure System Component",
        "description": "Configure a specific system component with hardware-specific settings.\n\n**FACTORY USE ONLY** - This endpoint configures critical system hardware and should only be used during factory setup.\n\nThis endpoint allows configuration of individual system components by:\n- **Specifying component hardware type** - Select from available driver implementations\n- **Applying component-specific settings** - Configure hardware parameters and options\n- **Validating configuration** - Ensure settings are compatible with system requirements\n- **Tracking setup progress** - Update configuration state and remaining tasks\n\n## Configuration Process\n\n### 1. **Component Identification**\nThe `component_id` path parameter specifies which component to configure:\n- Must match a component listed in \"unconfigured_components\" from setup status\n- Component must be present in the system manifest\n- Invalid component IDs will result in configuration failure\n\n### 2. **Hardware Type Selection**\nThe `type` field in settings specifies the hardware driver/implementation:\n- **motor_driver**: `roboclaw`, `motoron`, `null` (testing)\n- **cable_encoder**: `roboclaw`, `qsb`, `null` (no encoder)\n- **motor_encoder**: `roboclaw`, `null` (no motor encoder)\n- **physical_control**: `pendant`, `null` (API-only control)\n- **reed_switch**: `gpio`, `null` (no reed switch)\n- **estop**: `gpio`, `null` (no emergency stop)\n- **status_rgb_led**: `gpio`, `null` (no status LED)\n\n### 3. **Additional Settings**\nComponent-specific configuration parameters (optional):\n- Hardware addresses, pin assignments, communication settings\n- Calibration values, thresholds, operational parameters\n- Safety settings, timing configurations\n\n## Factory Workflow\n\n1. **Get setup status** to identify pending components\n2. **Configure each component** with appropriate hardware type\n3. **Verify successful configuration** from response\n4. **Continue until all components configured**\n5. **Exit setup mode** to enable normal operations\n\n## Security Note\nThis endpoint can modify critical system hardware configuration and should be restricted to authorized factory personnel only.",
        "operationId": "configure_component_api_v1_setup_configure__component_id__post",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "component_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Component Id"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ComponentConfigRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Component configuration result with remaining setup tasks",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ComponentConfigResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error during setup operation",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Setup service encountered an internal error"
                }
              }
            }
          },
          "400": {
            "description": "Configuration error or not in setup mode",
            "content": {
              "application/json": {
                "examples": {
                  "not_in_setup": {
                    "summary": "Not in Setup Mode",
                    "description": "Attempted to configure component when not in setup mode",
                    "value": {
                      "detail": "Not in setup mode"
                    }
                  },
                  "config_failed": {
                    "summary": "Configuration Failed",
                    "description": "Component configuration failed due to invalid settings",
                    "value": {
                      "detail": "Failed to configure component motor_driver"
                    }
                  },
                  "invalid_component": {
                    "summary": "Invalid Component",
                    "description": "Attempted to configure non-existent component",
                    "value": {
                      "detail": "Component 'invalid_component' not found in setup manifest"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/setup/exit": {
      "post": {
        "tags": [
          "v1",
          "setup",
          "factory"
        ],
        "summary": "Exit Setup Mode",
        "description": "Exit setup mode and transition system to normal operational state.\n\n**FACTORY USE ONLY** - This endpoint finalizes factory configuration and enables system operation.\n\nThis endpoint completes the setup process by:\n- **Validating complete configuration** - Ensuring all required components are configured\n- **Transitioning to operational mode** - Enabling normal reel control endpoints\n- **Activating safety systems** - Initializing configured hardware safeguards\n- **Publishing system events** - Notifying system of setup completion\n\n## Prerequisites for Exiting Setup\n\nBefore the system can exit setup mode, **ALL** components in the manifest must be configured:\n- **Critical components** (motor_driver, cable_encoder) must have valid hardware types\n- **Optional components** can be set to 'null' if not physically present\n- **Configuration validation** ensures all settings are compatible\n\n## System State Transition\n\n### During Setup Mode:\n- **Reel operations disabled** - Movement, calibration, and control endpoints blocked\n- **Setup endpoints active** - Configuration and status endpoints available\n- **Safety systems inactive** - Hardware not yet initialized\n\n### After Exiting Setup:\n- **Full reel operations enabled** - All movement and control endpoints available  \n- **Hardware systems initialized** - Configured components become active\n- **Safety systems operational** - Emergency stops, safeguards, and monitoring active\n- **Setup endpoints disabled** - Configuration locked to prevent accidental changes\n\n## Error Conditions\n\nThe system **cannot exit setup mode** if:\n- **Unconfigured components remain** - All components must have assigned types\n- **Invalid configurations detected** - Hardware settings fail validation\n- **Critical hardware missing** - Required components (motor_driver) not configured\n\n## Factory Completion Workflow\n\n1. **Configure all system components** using setup endpoints\n2. **Verify setup status** shows `can_exit_setup: true`\n3. **Call exit setup endpoint** to complete configuration\n4. **Verify normal operations** by testing reel control endpoints\n5. **Document final configuration** for customer deployment\n\nThis endpoint represents the **final step** in factory configuration before customer delivery.",
        "operationId": "exit_setup_mode_api_v1_setup_exit_post",
        "responses": {
          "200": {
            "description": "Setup mode exit result and operational status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExitSetupResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error during setup operation",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Setup service encountered an internal error"
                }
              }
            }
          },
          "400": {
            "description": "Cannot exit setup mode due to incomplete configuration",
            "content": {
              "application/json": {
                "examples": {
                  "incomplete_setup": {
                    "summary": "Setup Incomplete",
                    "description": "Cannot exit setup mode with unconfigured components",
                    "value": {
                      "detail": "Cannot exit setup mode - components still require configuration"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/setup/current_step": {
      "get": {
        "tags": [
          "v1",
          "setup",
          "factory"
        ],
        "summary": "Get current setup step",
        "description": "Returns the current step and instructions.",
        "operationId": "get_current_step_api_v1_setup_current_step_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/StepResponse"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "title": "Response Get Current Step Api V1 Setup Current Step Get"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/setup/step": {
      "post": {
        "tags": [
          "v1",
          "setup",
          "factory"
        ],
        "summary": "Submit setup step result",
        "description": "Submit result for the current setup step.",
        "operationId": "submit_step_api_v1_setup_step_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StepRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StepResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/setup/force_setup_mode": {
      "post": {
        "tags": [
          "v1",
          "setup",
          "factory"
        ],
        "summary": "Force enter setup mode for hardware re-verification",
        "description": "Force entry into setup mode to re-run hardware verification steps.",
        "operationId": "force_setup_mode_api_v1_setup_force_setup_mode_post",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/setup/certificate": {
      "get": {
        "tags": [
          "v1",
          "setup",
          "factory"
        ],
        "summary": "Generate Setup Certificate",
        "description": "Generate a detailed setup certificate/report in Markdown format documenting all configuration steps and their results",
        "operationId": "generate_certificate_api_v1_setup_certificate_get",
        "responses": {
          "200": {
            "description": "Setup certificate generated successfully",
            "content": {
              "application/json": {
                "schema": {}
              },
              "text/markdown": {
                "example": "# System Setup Certificate\n**Generated**: 2025-10-22..."
              }
            }
          },
          "500": {
            "description": "Internal server error during setup operation",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Setup service encountered an internal error"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/setup/metadata": {
      "patch": {
        "tags": [
          "v1",
          "setup",
          "factory"
        ],
        "summary": "Update System Metadata",
        "description": "Update system identification metadata fields.\n\n**Metadata vs Configuration:**\n- **Metadata**: Identification fields (chassis type, location, etc.)\n- **Configuration**: Operational hardware settings (requires setup mode)\n\n**Chassis Type Notes:**\n- Setting to 'user' marks chassis as not yet determined\n- Allows completing setup while deferring chassis identification\n- Can be updated later without re-entering setup mode\n\n**Does Not Require Setup Mode** - these are non-operational fields.",
        "operationId": "update_system_metadata_api_v1_setup_metadata_patch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SystemMetadataUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Metadata update result with list of updated fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemMetadataResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error during setup operation",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Setup service encountered an internal error"
                }
              }
            }
          },
          "400": {
            "description": "Invalid metadata field or value",
            "content": {
              "application/json": {
                "examples": {
                  "invalid_chassis": {
                    "summary": "Invalid Chassis Type",
                    "description": "Provided chassis type is not valid",
                    "value": {
                      "detail": "Invalid chassis type: 'invalid_type'. Valid types: croc_mini, croc_xl, kronos, caiman, user"
                    }
                  },
                  "no_fields": {
                    "summary": "No Fields Provided",
                    "description": "Request contained no valid metadata fields",
                    "value": {
                      "detail": "No metadata fields provided for update"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/camera/status": {
      "get": {
        "tags": [
          "v1",
          "camera"
        ],
        "summary": "Get Camera Status",
        "description": "Get current USB camera connection status using v4l2 detection.\n\nThis endpoint provides real-time camera availability and operational status including connection \ndetection via v4l2 interface, initialization status for camera readiness, device information with \nhardware details and capabilities, and streaming state with active format information.\n\n## Detection Process\n\nThe system performs an active stream check to return current status if camera already streaming, \nfollowed by v4l2 device scan to detect available video devices, camera initialization to attempt \ncamera setup, and capability query to retrieve supported formats and optimal settings.\n\n## Usage Recommendations\n\nCheck camera status before attempting to start streaming for pre-stream validation, poll \nperiodically to detect camera disconnections for connection monitoring, and use `best_format` \ninformation for format optimization to achieve optimal streaming quality.",
        "operationId": "get_camera_status_api_v1_camera_status_get",
        "responses": {
          "200": {
            "description": "Camera status retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CameraStatusResponse"
                },
                "examples": {
                  "camera_active_streaming": {
                    "summary": "Camera Active and Streaming",
                    "description": "Camera is currently active and streaming video",
                    "value": {
                      "connected": true,
                      "message": "Camera active and streaming",
                      "ready": true,
                      "video_devices": [
                        "/dev/video0"
                      ],
                      "device_name": "Integrated_Webcam_HD: Integrate",
                      "streaming": true,
                      "current_format": {
                        "format": "MJPG",
                        "width": 1280,
                        "height": 720,
                        "fps": 30.0
                      }
                    }
                  },
                  "camera_ready_not_streaming": {
                    "summary": "Camera Ready (Not Streaming)",
                    "description": "Camera detected and initialized, ready to start streaming",
                    "value": {
                      "connected": true,
                      "message": "Camera detected and ready",
                      "ready": true,
                      "video_devices": [
                        "/dev/video0"
                      ],
                      "device_name": "Integrated_Webcam_HD: Integrate",
                      "bus_info": "usb-xhci-hcd.1-2",
                      "driver_name": "uvcvideo",
                      "best_format": {
                        "format": "MJPG",
                        "width": 1280,
                        "height": 720,
                        "fps": 30.0
                      },
                      "total_cameras": 1
                    }
                  },
                  "camera_detected_failed": {
                    "summary": "Camera Detected but Failed",
                    "description": "Camera hardware detected but initialization failed",
                    "value": {
                      "connected": true,
                      "message": "Camera detected but failed to initialize",
                      "ready": false,
                      "video_devices": [
                        "/dev/video0"
                      ],
                      "device_name": "USB Camera",
                      "bus_info": "usb-ehci-hcd.1-1",
                      "error": "Camera initialization failed"
                    }
                  },
                  "no_camera_connected": {
                    "summary": "No Camera Connected",
                    "description": "No USB cameras detected on the system",
                    "value": {
                      "connected": false,
                      "message": "No USB cameras detected",
                      "ready": false,
                      "cameras_found": []
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "500": {
            "description": "Camera initialization or operation failed",
            "content": {
              "application/json": {
                "examples": {
                  "initialization_failed": {
                    "summary": "Camera Initialization Failed",
                    "description": "Camera detected but failed to initialize for streaming",
                    "value": {
                      "detail": "Failed to start camera: Device initialization error",
                      "error_code": "CAMERA_INIT_FAILED",
                      "suggestions": [
                        "Check camera drivers are properly installed",
                        "Verify camera is not in use by another application",
                        "Try disconnecting and reconnecting camera"
                      ]
                    }
                  },
                  "driver_error": {
                    "summary": "Camera Driver Error",
                    "description": "Camera driver reported an error during operation",
                    "value": {
                      "detail": "Camera driver error: v4l2 ioctl failed",
                      "error_code": "DRIVER_ERROR",
                      "suggestions": [
                        "Update camera drivers",
                        "Check system logs for hardware errors",
                        "Try using a different USB port"
                      ]
                    }
                  },
                  "resource_conflict": {
                    "summary": "Resource Conflict",
                    "description": "Camera resource is busy or in use by another process",
                    "value": {
                      "detail": "Camera resource busy: Device in use",
                      "error_code": "RESOURCE_BUSY",
                      "suggestions": [
                        "Close other applications using the camera",
                        "Stop existing camera streams",
                        "Check for background processes using camera"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/camera/info": {
      "get": {
        "tags": [
          "v1",
          "camera"
        ],
        "summary": "Get Detailed Camera Information",
        "description": "Get comprehensive camera information including all detected \ndevices and capabilities.\n\nThis endpoint provides detailed analysis of all available USB cameras including complete \ndevice enumeration via v4l2, hardware specifications with device names and drivers, format \ncapabilities for supported video formats and resolutions, and primary camera selection with \nsystem recommendations.\n\n## Information Categories\n\nWhen camera is currently streaming, the system provides active camera status with current \ndevice and format information plus all detected cameras for complete device reference. \nWhen no camera is actively streaming, the system returns all cameras with complete device \nenumeration, primary camera selection with system recommendations, and capability analysis \nwith detailed format and resolution support.\n\nThis endpoint is essential for applications requiring detailed camera analysis or \nmulti-camera management.",
        "operationId": "get_camera_info_api_v1_camera_info_get",
        "responses": {
          "200": {
            "description": "Camera information retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CameraInfoResponse"
                },
                "examples": {
                  "active_camera_with_details": {
                    "summary": "Active Camera with Full Details",
                    "description": "Detailed information when camera is actively streaming",
                    "value": {
                      "connected": true,
                      "message": "Camera active and providing detailed info",
                      "active_camera": {
                        "device_path": "/dev/video0",
                        "streaming": true,
                        "current_format": {
                          "format": "MJPG",
                          "width": 1280,
                          "height": 720,
                          "fps": 30.0
                        },
                        "settings": {
                          "brightness": 128,
                          "contrast": 128,
                          "saturation": 128,
                          "auto_exposure": true,
                          "auto_white_balance": true
                        }
                      },
                      "all_cameras": [
                        {
                          "device_name": "Integrated_Webcam_HD: Integrate",
                          "bus_info": "usb-xhci-hcd.1-2",
                          "device_path": "/dev/video0",
                          "card_name": "Integrated_Webcam_HD: Integrate",
                          "driver_name": "uvcvideo",
                          "supported_formats": [
                            {
                              "format": "MJPG",
                              "description": "Motion-JPEG, compressed",
                              "resolutions": [
                                {
                                  "width": 1280,
                                  "height": 720,
                                  "framerates": [
                                    15.0,
                                    30.0
                                  ]
                                },
                                {
                                  "width": 640,
                                  "height": 480,
                                  "framerates": [
                                    15.0,
                                    30.0,
                                    60.0
                                  ]
                                }
                              ]
                            },
                            {
                              "format": "YUYV",
                              "description": "YUV 4:2:2, uncompressed",
                              "resolutions": [
                                {
                                  "width": 640,
                                  "height": 480,
                                  "framerates": [
                                    15.0,
                                    30.0,
                                    60.0
                                  ]
                                },
                                {
                                  "width": 320,
                                  "height": 240,
                                  "framerates": [
                                    30.0,
                                    60.0
                                  ]
                                }
                              ]
                            }
                          ],
                          "best_format": {
                            "format": "MJPG",
                            "width": 1280,
                            "height": 720,
                            "fps": 30.0
                          }
                        }
                      ]
                    }
                  },
                  "multiple_cameras_detected": {
                    "summary": "Multiple Cameras Available",
                    "description": "System with multiple USB cameras detected",
                    "value": {
                      "connected": true,
                      "message": "Found 2 USB camera(s)",
                      "cameras": [
                        {
                          "device_name": "Integrated_Webcam_HD: Integrate",
                          "bus_info": "usb-xhci-hcd.1-2",
                          "device_path": "/dev/video0",
                          "card_name": "Integrated_Webcam_HD: Integrate",
                          "driver_name": "uvcvideo",
                          "supported_formats": [
                            {
                              "format": "MJPG",
                              "description": "Motion-JPEG, compressed",
                              "resolutions": [
                                {
                                  "width": 1280,
                                  "height": 720,
                                  "framerates": [
                                    15.0,
                                    30.0
                                  ]
                                },
                                {
                                  "width": 640,
                                  "height": 480,
                                  "framerates": [
                                    15.0,
                                    30.0,
                                    60.0
                                  ]
                                }
                              ]
                            },
                            {
                              "format": "YUYV",
                              "description": "YUV 4:2:2, uncompressed",
                              "resolutions": [
                                {
                                  "width": 640,
                                  "height": 480,
                                  "framerates": [
                                    15.0,
                                    30.0,
                                    60.0
                                  ]
                                },
                                {
                                  "width": 320,
                                  "height": 240,
                                  "framerates": [
                                    30.0,
                                    60.0
                                  ]
                                }
                              ]
                            }
                          ],
                          "best_format": {
                            "format": "MJPG",
                            "width": 1280,
                            "height": 720,
                            "fps": 30.0
                          }
                        },
                        {
                          "device_name": "USB Camera",
                          "bus_info": "usb-ehci-hcd.1-1",
                          "device_path": "/dev/video2",
                          "card_name": "USB Camera",
                          "driver_name": "uvcvideo",
                          "supported_formats": [
                            {
                              "format": "MJPG",
                              "description": "Motion-JPEG, compressed",
                              "resolutions": [
                                {
                                  "width": 1280,
                                  "height": 720,
                                  "framerates": [
                                    15.0,
                                    30.0
                                  ]
                                },
                                {
                                  "width": 640,
                                  "height": 480,
                                  "framerates": [
                                    15.0,
                                    30.0,
                                    60.0
                                  ]
                                }
                              ]
                            }
                          ],
                          "best_format": {
                            "format": "MJPG",
                            "width": 640,
                            "height": 480,
                            "fps": 30.0
                          }
                        }
                      ],
                      "primary_camera": {
                        "device_name": "Integrated_Webcam_HD: Integrate",
                        "bus_info": "usb-xhci-hcd.1-2",
                        "device_path": "/dev/video0",
                        "card_name": "Integrated_Webcam_HD: Integrate",
                        "driver_name": "uvcvideo",
                        "supported_formats": [
                          {
                            "format": "MJPG",
                            "description": "Motion-JPEG, compressed",
                            "resolutions": [
                              {
                                "width": 1280,
                                "height": 720,
                                "framerates": [
                                  15.0,
                                  30.0
                                ]
                              },
                              {
                                "width": 640,
                                "height": 480,
                                "framerates": [
                                  15.0,
                                  30.0,
                                  60.0
                                ]
                              }
                            ]
                          },
                          {
                            "format": "YUYV",
                            "description": "YUV 4:2:2, uncompressed",
                            "resolutions": [
                              {
                                "width": 640,
                                "height": 480,
                                "framerates": [
                                  15.0,
                                  30.0,
                                  60.0
                                ]
                              },
                              {
                                "width": 320,
                                "height": 240,
                                "framerates": [
                                  30.0,
                                  60.0
                                ]
                              }
                            ]
                          }
                        ],
                        "best_format": {
                          "format": "MJPG",
                          "width": 1280,
                          "height": 720,
                          "fps": 30.0
                        }
                      },
                      "total_cameras": 2
                    }
                  },
                  "single_camera_detected": {
                    "summary": "Single Camera Available",
                    "description": "System with one USB camera detected",
                    "value": {
                      "connected": true,
                      "message": "Found 1 USB camera(s)",
                      "cameras": [
                        {
                          "device_name": "Integrated_Webcam_HD: Integrate",
                          "bus_info": "usb-xhci-hcd.1-2",
                          "device_path": "/dev/video0",
                          "card_name": "Integrated_Webcam_HD: Integrate",
                          "driver_name": "uvcvideo",
                          "supported_formats": [
                            {
                              "format": "MJPG",
                              "description": "Motion-JPEG, compressed",
                              "resolutions": [
                                {
                                  "width": 1280,
                                  "height": 720,
                                  "framerates": [
                                    15.0,
                                    30.0
                                  ]
                                },
                                {
                                  "width": 640,
                                  "height": 480,
                                  "framerates": [
                                    15.0,
                                    30.0,
                                    60.0
                                  ]
                                }
                              ]
                            },
                            {
                              "format": "YUYV",
                              "description": "YUV 4:2:2, uncompressed",
                              "resolutions": [
                                {
                                  "width": 640,
                                  "height": 480,
                                  "framerates": [
                                    15.0,
                                    30.0,
                                    60.0
                                  ]
                                },
                                {
                                  "width": 320,
                                  "height": 240,
                                  "framerates": [
                                    30.0,
                                    60.0
                                  ]
                                }
                              ]
                            }
                          ],
                          "best_format": {
                            "format": "MJPG",
                            "width": 1280,
                            "height": 720,
                            "fps": 30.0
                          }
                        }
                      ],
                      "primary_camera": {
                        "device_name": "Integrated_Webcam_HD: Integrate",
                        "bus_info": "usb-xhci-hcd.1-2",
                        "device_path": "/dev/video0",
                        "card_name": "Integrated_Webcam_HD: Integrate",
                        "driver_name": "uvcvideo",
                        "supported_formats": [
                          {
                            "format": "MJPG",
                            "description": "Motion-JPEG, compressed",
                            "resolutions": [
                              {
                                "width": 1280,
                                "height": 720,
                                "framerates": [
                                  15.0,
                                  30.0
                                ]
                              },
                              {
                                "width": 640,
                                "height": 480,
                                "framerates": [
                                  15.0,
                                  30.0,
                                  60.0
                                ]
                              }
                            ]
                          },
                          {
                            "format": "YUYV",
                            "description": "YUV 4:2:2, uncompressed",
                            "resolutions": [
                              {
                                "width": 640,
                                "height": 480,
                                "framerates": [
                                  15.0,
                                  30.0,
                                  60.0
                                ]
                              },
                              {
                                "width": 320,
                                "height": 240,
                                "framerates": [
                                  30.0,
                                  60.0
                                ]
                              }
                            ]
                          }
                        ],
                        "best_format": {
                          "format": "MJPG",
                          "width": 1280,
                          "height": 720,
                          "fps": 30.0
                        }
                      },
                      "total_cameras": 1
                    }
                  },
                  "no_cameras_found": {
                    "summary": "No Cameras Found",
                    "description": "No USB cameras detected on the system",
                    "value": {
                      "connected": false,
                      "message": "No USB cameras detected",
                      "cameras_found": []
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "500": {
            "description": "Camera initialization or operation failed",
            "content": {
              "application/json": {
                "examples": {
                  "initialization_failed": {
                    "summary": "Camera Initialization Failed",
                    "description": "Camera detected but failed to initialize for streaming",
                    "value": {
                      "detail": "Failed to start camera: Device initialization error",
                      "error_code": "CAMERA_INIT_FAILED",
                      "suggestions": [
                        "Check camera drivers are properly installed",
                        "Verify camera is not in use by another application",
                        "Try disconnecting and reconnecting camera"
                      ]
                    }
                  },
                  "driver_error": {
                    "summary": "Camera Driver Error",
                    "description": "Camera driver reported an error during operation",
                    "value": {
                      "detail": "Camera driver error: v4l2 ioctl failed",
                      "error_code": "DRIVER_ERROR",
                      "suggestions": [
                        "Update camera drivers",
                        "Check system logs for hardware errors",
                        "Try using a different USB port"
                      ]
                    }
                  },
                  "resource_conflict": {
                    "summary": "Resource Conflict",
                    "description": "Camera resource is busy or in use by another process",
                    "value": {
                      "detail": "Camera resource busy: Device in use",
                      "error_code": "RESOURCE_BUSY",
                      "suggestions": [
                        "Close other applications using the camera",
                        "Stop existing camera streams",
                        "Check for background processes using camera"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/camera/stream": {
      "get": {
        "tags": [
          "v1",
          "camera"
        ],
        "summary": "Stream Live Video",
        "description": "Stream live video from USB camera using MJPEG format.\n\nThis endpoint provides real-time video streaming with automatic camera selection using \nv4l2 detection, format optimization for best available video format, MJPEG streaming \nprotocol via multipart HTTP response, and connection management with camera \ninitialization and error recovery.\n\n## Streaming Protocol\n\nThe system uses Content-Type `multipart/x-mixed-replace; boundary=frame` to deliver \nMotion-JPEG compressed frames as a continuous stream with compatibility for standard \nweb browsers and video players.\n\n## Client Integration\n\nWeb browsers can display streams using `<img src=\"/api/camera/stream\" alt=\"Live Camera Feed\">` \nwhile video players like VLC can open network streams with the endpoint URL, ffmpeg can use it \nas input source for processing, and OpenCV can capture frames using VideoCapture.",
        "operationId": "stream_video_api_v1_camera_stream_get",
        "responses": {
          "200": {
            "description": "MJPEG video stream",
            "content": {
              "multipart/x-mixed-replace": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                },
                "examples": {
                  "mjpeg_stream": {
                    "summary": "MJPEG Video Stream",
                    "description": "Continuous MJPEG stream with boundary markers",
                    "value": "Multipart MJPEG stream content"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No USB cameras available",
            "content": {
              "application/json": {
                "examples": {
                  "no_cameras_detected": {
                    "summary": "No Cameras Found",
                    "description": "System scan found no connected USB cameras",
                    "value": {
                      "detail": "No USB cameras available",
                      "error_code": "CAMERA_NOT_FOUND",
                      "suggestions": [
                        "Check that a USB camera is connected",
                        "Verify camera permissions",
                        "Try restarting the camera service"
                      ]
                    }
                  },
                  "camera_disconnected": {
                    "summary": "Camera Disconnected",
                    "description": "Previously available camera is no longer connected",
                    "value": {
                      "detail": "Camera disconnected during operation",
                      "error_code": "CAMERA_DISCONNECTED",
                      "suggestions": [
                        "Check camera USB connection",
                        "Try reconnecting the camera",
                        "Check for USB hub issues"
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Camera initialization or operation failed",
            "content": {
              "application/json": {
                "examples": {
                  "initialization_failed": {
                    "summary": "Camera Initialization Failed",
                    "description": "Camera detected but failed to initialize for streaming",
                    "value": {
                      "detail": "Failed to start camera: Device initialization error",
                      "error_code": "CAMERA_INIT_FAILED",
                      "suggestions": [
                        "Check camera drivers are properly installed",
                        "Verify camera is not in use by another application",
                        "Try disconnecting and reconnecting camera"
                      ]
                    }
                  },
                  "driver_error": {
                    "summary": "Camera Driver Error",
                    "description": "Camera driver reported an error during operation",
                    "value": {
                      "detail": "Camera driver error: v4l2 ioctl failed",
                      "error_code": "DRIVER_ERROR",
                      "suggestions": [
                        "Update camera drivers",
                        "Check system logs for hardware errors",
                        "Try using a different USB port"
                      ]
                    }
                  },
                  "resource_conflict": {
                    "summary": "Resource Conflict",
                    "description": "Camera resource is busy or in use by another process",
                    "value": {
                      "detail": "Camera resource busy: Device in use",
                      "error_code": "RESOURCE_BUSY",
                      "suggestions": [
                        "Close other applications using the camera",
                        "Stop existing camera streams",
                        "Check for background processes using camera"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/camera/stop": {
      "post": {
        "tags": [
          "v1",
          "camera"
        ],
        "summary": "Stop Camera Stream",
        "description": "Stop active camera streaming and release camera resources.\n\nThis endpoint safely terminates camera streaming operations with stream termination to \nstop active video, resource cleanup to release camera devices and memory, state management \nto update camera status, and idempotent operation safety for repeated calls.\n\n## Resource Release Process\n\nThe system performs stream termination to stop frame generation and delivery, camera \nrelease to free exclusive device access, memory cleanup to free allocated buffers and \nresources, and status update to reflect the stopped state internally.\n\n## Integration Recommendations\n\nAlways stop cameras when applications shut down for cleanup procedures, stop cameras \nwhen users log out or sessions expire for session management, and include stop \noperations in camera error recovery procedures for error recovery workflows.",
        "operationId": "stop_camera_stream_api_v1_camera_stop_post",
        "responses": {
          "200": {
            "description": "Camera stopped successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StopCameraResponse"
                },
                "examples": {
                  "stop_success": {
                    "summary": "Camera Stopped",
                    "description": "Camera streaming stopped successfully",
                    "value": {
                      "success": true,
                      "message": "Camera stopped"
                    }
                  },
                  "already_stopped": {
                    "summary": "Already Stopped",
                    "description": "Camera was not streaming (idempotent operation)",
                    "value": {
                      "success": true,
                      "message": "Camera was not active"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "500": {
            "description": "Failed to stop camera",
            "content": {
              "application/json": {
                "examples": {
                  "stop_failed": {
                    "summary": "Stop Operation Failed",
                    "description": "Error occurred while stopping camera",
                    "value": {
                      "detail": "Failed to stop camera: Resource cleanup error",
                      "error_code": "STOP_FAILED"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/camera/supported-resolutions": {
      "get": {
        "tags": [
          "v1",
          "camera"
        ],
        "summary": "Get Supported Resolutions",
        "description": "Get supported camera resolutions and video formats \nusing v4l2 detection.\n\nThis endpoint provides comprehensive camera capability information including resolution \nenumeration for all supported image sizes, framerate details with available rates for \neach resolution, format capabilities for supported video formats like MJPEG and YUYV, \nand optimization recommendations for best format selection.\n\n## Detection Methods\n\nWhen camera is currently streaming, the system provides active camera query with \nreal-time capability information from the active device. When no camera is actively \nstreaming, the system performs v4l2 static detection with complete capability scan \nusing the v4l2 interface.\n\n## Format Categories\n\nThe system supports MJPEG compressed formats for efficient streaming applications \nand YUYV uncompressed formats for processing applications requiring raw video data.\n\n## Integration Recommendations\n\nCheck supported resolutions before starting streams for pre-streaming validation, \nadjust resolution based on network conditions for dynamic adaptation, and cache \nresolution data to avoid repeated queries for capability caching optimization.",
        "operationId": "get_supported_resolutions_api_v1_camera_supported_resolutions_get",
        "responses": {
          "200": {
            "description": "Supported resolutions retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SupportedResolutionsResponse"
                },
                "examples": {
                  "active_camera_resolutions": {
                    "summary": "Active Camera Resolutions",
                    "description": "Resolution information from currently streaming camera",
                    "value": {
                      "device": "/dev/video0",
                      "supported_resolutions": [
                        {
                          "width": 1280,
                          "height": 720,
                          "framerates": [
                            15.0,
                            30.0
                          ]
                        },
                        {
                          "width": 640,
                          "height": 480,
                          "framerates": [
                            15.0,
                            30.0,
                            60.0
                          ]
                        }
                      ],
                      "current_format": {
                        "format": "MJPG",
                        "width": 1280,
                        "height": 720,
                        "fps": 30.0
                      },
                      "source": "active_camera"
                    }
                  },
                  "v4l2_detection_resolutions": {
                    "summary": "v4l2 Detection Resolutions",
                    "description": "Full capability scan using v4l2 interface",
                    "value": {
                      "device": "/dev/video0",
                      "device_name": "Integrated_Webcam_HD: Integrate",
                      "supported_resolutions": [
                        {
                          "width": 1280,
                          "height": 720,
                          "framerates": [
                            15.0,
                            30.0
                          ]
                        },
                        {
                          "width": 640,
                          "height": 480,
                          "framerates": [
                            15.0,
                            30.0,
                            60.0
                          ]
                        }
                      ],
                      "supported_formats": [
                        {
                          "format": "MJPG",
                          "description": "Motion-JPEG, compressed",
                          "resolutions": [
                            {
                              "width": 1280,
                              "height": 720,
                              "framerates": [
                                15.0,
                                30.0
                              ]
                            },
                            {
                              "width": 640,
                              "height": 480,
                              "framerates": [
                                15.0,
                                30.0,
                                60.0
                              ]
                            }
                          ]
                        },
                        {
                          "format": "YUYV",
                          "description": "YUV 4:2:2, uncompressed",
                          "resolutions": [
                            {
                              "width": 640,
                              "height": 480,
                              "framerates": [
                                15.0,
                                30.0,
                                60.0
                              ]
                            },
                            {
                              "width": 320,
                              "height": 240,
                              "framerates": [
                                30.0,
                                60.0
                              ]
                            }
                          ]
                        }
                      ],
                      "best_format": {
                        "format": "MJPG",
                        "width": 1280,
                        "height": 720,
                        "fps": 30.0
                      },
                      "source": "v4l2_detection"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "404": {
            "description": "No USB cameras available",
            "content": {
              "application/json": {
                "examples": {
                  "no_cameras_detected": {
                    "summary": "No Cameras Found",
                    "description": "System scan found no connected USB cameras",
                    "value": {
                      "detail": "No USB cameras available",
                      "error_code": "CAMERA_NOT_FOUND",
                      "suggestions": [
                        "Check that a USB camera is connected",
                        "Verify camera permissions",
                        "Try restarting the camera service"
                      ]
                    }
                  },
                  "camera_disconnected": {
                    "summary": "Camera Disconnected",
                    "description": "Previously available camera is no longer connected",
                    "value": {
                      "detail": "Camera disconnected during operation",
                      "error_code": "CAMERA_DISCONNECTED",
                      "suggestions": [
                        "Check camera USB connection",
                        "Try reconnecting the camera",
                        "Check for USB hub issues"
                      ]
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Invalid camera format or settings",
            "content": {
              "application/json": {
                "examples": {
                  "unsupported_resolution": {
                    "summary": "Unsupported Resolution",
                    "description": "Requested resolution is not supported by camera",
                    "value": {
                      "detail": "Resolution 1920x1080 not supported by camera",
                      "error_code": "UNSUPPORTED_RESOLUTION",
                      "suggestions": [
                        "Check supported resolutions using /camera/supported-resolutions",
                        "Use a supported resolution from the capabilities list",
                        "Try a lower resolution"
                      ]
                    }
                  },
                  "invalid_format": {
                    "summary": "Invalid Video Format",
                    "description": "Requested video format is not supported",
                    "value": {
                      "detail": "Video format H264 not supported by camera",
                      "error_code": "UNSUPPORTED_FORMAT",
                      "suggestions": [
                        "Use MJPEG format for streaming",
                        "Check camera format capabilities",
                        "Try YUYV format for raw video"
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Camera initialization or operation failed",
            "content": {
              "application/json": {
                "examples": {
                  "initialization_failed": {
                    "summary": "Camera Initialization Failed",
                    "description": "Camera detected but failed to initialize for streaming",
                    "value": {
                      "detail": "Failed to start camera: Device initialization error",
                      "error_code": "CAMERA_INIT_FAILED",
                      "suggestions": [
                        "Check camera drivers are properly installed",
                        "Verify camera is not in use by another application",
                        "Try disconnecting and reconnecting camera"
                      ]
                    }
                  },
                  "driver_error": {
                    "summary": "Camera Driver Error",
                    "description": "Camera driver reported an error during operation",
                    "value": {
                      "detail": "Camera driver error: v4l2 ioctl failed",
                      "error_code": "DRIVER_ERROR",
                      "suggestions": [
                        "Update camera drivers",
                        "Check system logs for hardware errors",
                        "Try using a different USB port"
                      ]
                    }
                  },
                  "resource_conflict": {
                    "summary": "Resource Conflict",
                    "description": "Camera resource is busy or in use by another process",
                    "value": {
                      "detail": "Camera resource busy: Device in use",
                      "error_code": "RESOURCE_BUSY",
                      "suggestions": [
                        "Close other applications using the camera",
                        "Stop existing camera streams",
                        "Check for background processes using camera"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/camera/settings": {
      "get": {
        "tags": [
          "v1",
          "camera"
        ],
        "summary": "Get Camera Settings",
        "description": "Get current camera configuration settings and \npreferences.\n\nThis endpoint provides access to camera system configuration including camera \npreferences for device selection and format settings, system settings for \ncamera-related configuration parameters, default values with factory defaults and \nrecommendations, and operational parameters that affect camera behavior and performance.\n\n## Configuration Categories\n\nThe system manages camera selection settings for preferred device criteria and \nauto-detection behavior, and format preferences including default resolution, \nformat priority order for MJPEG versus YUYV, and default framerate selection policy.",
        "operationId": "get_camera_settings_api_v1_camera_settings_get",
        "responses": {
          "200": {
            "description": "Camera settings retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CameraSettings"
                },
                "examples": {
                  "default_settings": {
                    "summary": "Default Camera Settings",
                    "description": "Standard camera configuration settings",
                    "value": {
                      "preferred_resolution": {
                        "width": 1280,
                        "height": 720
                      },
                      "preferred_format": "MJPG",
                      "default_fps": 30.0,
                      "auto_select_camera": true,
                      "quality_preference": "balanced",
                      "enable_auto_exposure": true,
                      "enable_auto_white_balance": true
                    }
                  },
                  "high_quality_settings": {
                    "summary": "High Quality Settings",
                    "description": "Camera settings optimized for image quality",
                    "value": {
                      "preferred_resolution": {
                        "width": 1920,
                        "height": 1080
                      },
                      "preferred_format": "MJPG",
                      "default_fps": 30.0,
                      "auto_select_camera": true,
                      "quality_preference": "quality",
                      "enable_auto_exposure": false,
                      "enable_auto_white_balance": false,
                      "manual_exposure": 150,
                      "manual_gain": 64
                    }
                  },
                  "performance_settings": {
                    "summary": "Performance Optimized Settings",
                    "description": "Camera settings optimized for low resource usage",
                    "value": {
                      "preferred_resolution": {
                        "width": 640,
                        "height": 480
                      },
                      "preferred_format": "MJPG",
                      "default_fps": 15.0,
                      "auto_select_camera": true,
                      "quality_preference": "performance",
                      "enable_auto_exposure": true,
                      "enable_auto_white_balance": true,
                      "compression_quality": 75
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "500": {
            "description": "Failed to retrieve camera settings",
            "content": {
              "application/json": {
                "examples": {
                  "settings_error": {
                    "summary": "Settings Retrieval Failed",
                    "description": "Error occurred while retrieving camera settings",
                    "value": {
                      "detail": "Failed to get camera settings: Configuration service unavailable",
                      "error_code": "SETTINGS_UNAVAILABLE"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/plugins/available": {
      "get": {
        "tags": [
          "v1",
          "plugins"
        ],
        "summary": "Get all available plugins",
        "description": "Get list of all available plugins with metadata.",
        "operationId": "get_available_plugins_api_v1_plugins_available_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginListResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/plugins/status": {
      "get": {
        "tags": [
          "v1",
          "plugins"
        ],
        "summary": "Get status of all enabled plugins",
        "description": "Get status information for all enabled plugins.",
        "operationId": "get_plugin_status_api_v1_plugins_status_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginStatusResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/api/v1/plugins/{plugin_id}/settings": {
      "patch": {
        "tags": [
          "v1",
          "plugins"
        ],
        "summary": "Update plugin settings",
        "description": "Update hardware and/or settings for a specific plugin",
        "operationId": "update_plugin_settings_api_v1_plugins__plugin_id__settings_patch",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "plugin_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Plugin Id"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdatePluginSettingsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdatePluginSettingsResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/plugins/{plugin_id}": {
      "get": {
        "tags": [
          "v1",
          "plugins"
        ],
        "summary": "Get detailed plugin information",
        "description": "Get detailed information about a specific plugin.",
        "operationId": "get_plugin_info_api_v1_plugins__plugin_id__get",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "plugin_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Plugin Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginInfoResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/plugins/{plugin_id}/enable": {
      "post": {
        "tags": [
          "v1",
          "plugins"
        ],
        "summary": "Enable a plugin",
        "description": "Enable a specific plugin.",
        "operationId": "enable_plugin_api_v1_plugins__plugin_id__enable_post",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "plugin_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Plugin Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/plugins/{plugin_id}/disable": {
      "post": {
        "tags": [
          "v1",
          "plugins"
        ],
        "summary": "Disable a plugin",
        "description": "Disable a specific plugin.",
        "operationId": "disable_plugin_api_v1_plugins__plugin_id__disable_post",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "plugin_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Plugin Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/plugins/{plugin_id}/actions/{action_name}": {
      "post": {
        "tags": [
          "v1",
          "plugins"
        ],
        "summary": "Execute a plugin action",
        "description": "Execute a custom action on an enabled plugin",
        "operationId": "execute_plugin_action_api_v1_plugins__plugin_id__actions__action_name__post",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "plugin_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Plugin Id"
            }
          },
          {
            "name": "action_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Action Name"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PluginActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginActionResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/plugins/{plugin_id}/actions": {
      "get": {
        "tags": [
          "v1",
          "plugins"
        ],
        "summary": "Get available actions for a plugin",
        "description": "Returns a list of actions that can be executed on this plugin",
        "operationId": "get_plugin_actions_api_v1_plugins__plugin_id__actions_get",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "plugin_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Plugin Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "title": "Response Get Plugin Actions Api V1 Plugins  Plugin Id  Actions Get"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/persistence/download": {
      "get": {
        "tags": [
          "v1",
          "utility"
        ],
        "summary": "Download ReelAPI Persistence Files",
        "description": "Download a ZIP archive containing all files from the ReelAPI persistence directory, excluding log files.",
        "operationId": "download_persistence_files_api_v1_persistence_download_get",
        "responses": {
          "200": {
            "description": "ZIP archive containing ReelAPI persistence files",
            "headers": {
              "Content-Disposition": {
                "description": "Attachment filename for download",
                "schema": {
                  "type": "string",
                  "example": "attachment; filename=rcs_api_persistence_20241020_143022.zip"
                }
              },
              "Content-Type": {
                "description": "MIME type for ZIP file download",
                "schema": {
                  "type": "string",
                  "example": "application/zip"
                }
              }
            },
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                },
                "example": "rcs_api_persistence_20241020_143022.zip"
              }
            }
          },
          "401": {
            "description": "Could not validate credentials",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer token authentication required",
                "schema": {
                  "type": "string",
                  "example": "Bearer"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "detail": "Could not validate credentials"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "example": {
                  "detail": "Internal server error"
                }
              }
            }
          },
          "404": {
            "description": "No persistence files found",
            "content": {
              "application/json": {
                "example": {
                  "detail": "No files found in the persistence directory"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ActiveCameraStatus": {
        "properties": {
          "device_path": {
            "type": "string",
            "title": "Device Path",
            "description": "Active camera device path"
          },
          "streaming": {
            "type": "boolean",
            "title": "Streaming",
            "description": "Whether camera is currently streaming"
          },
          "current_format": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CameraFormatDetail"
              },
              {
                "type": "null"
              }
            ],
            "description": "Current streaming format"
          },
          "settings": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Settings",
            "description": "Current camera settings"
          }
        },
        "type": "object",
        "required": [
          "device_path",
          "streaming"
        ],
        "title": "ActiveCameraStatus",
        "description": "Status of currently active camera",
        "example": {
          "current_format": {
            "format": "MJPG",
            "fps": 30.0,
            "height": 720,
            "width": 1280
          },
          "device_path": "/dev/video0",
          "settings": {
            "brightness": 128,
            "contrast": 128
          },
          "streaming": true
        }
      },
      "ActiveOperationsSchema": {
        "properties": {
          "deceleration": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MotorDecelerationStatus"
              },
              {
                "type": "null"
              }
            ],
            "description": "Motor deceleration status when deceleration is active."
          },
          "cable_position_calibration": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CablePositionCalibrationStatus"
              },
              {
                "type": "null"
              }
            ],
            "description": "Cable position calibration status when calibration is active."
          },
          "operation_context": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/OperationContextSchema"
              },
              {
                "type": "null"
              }
            ],
            "description": "\nActive operation context that may block user commands.\n\nWhen present, indicates an automated operation is in progress that\nrestricts certain user commands. UI should check blocks_movement\nto determine which controls to disable.\n\n**When None**: No special operation in progress, all controls enabled\n        "
          }
        },
        "type": "object",
        "title": "ActiveOperationsSchema",
        "description": "Current active system operations and their status."
      },
      "AddCableOffsetRequest": {
        "properties": {
          "offset_to_add_in_meters": {
            "type": "number",
            "title": "Offset To Add In Meters",
            "description": "Offset value to add to the current cable position in meters.\n        \nPositive values increase the position reading, negative values decrease it. This performs a relative adjustment without requiring knowledge of the absolute position.\n        ",
            "example": 2.5,
            "note": "Can be positive or negative for bidirectional adjustment",
            "unit": "meters"
          }
        },
        "type": "object",
        "required": [
          "offset_to_add_in_meters"
        ],
        "title": "AddCableOffsetRequest",
        "description": "Request data for adding an offset to the current cable encoder position.",
        "examples": [
          {
            "description": "Add 2.5 meters to current position",
            "name": "Positive Offset",
            "value": {
              "offset_to_add_in_meters": 2.5
            }
          },
          {
            "description": "Subtract 1.8 meters from current position",
            "name": "Negative Offset",
            "value": {
              "offset_to_add_in_meters": -1.8
            }
          },
          {
            "description": "Fine adjustment of 0.1 meters",
            "name": "Small Adjustment",
            "value": {
              "offset_to_add_in_meters": 0.1
            }
          }
        ]
      },
      "AddCableOffsetResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/AddCableOffsetResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "AddCableOffsetResponse",
        "description": "Response for cable encoder offset operations.\n\nAdds a specified offset to the current cable encoder position. Useful for making fine adjustments to position readings without requiring absolute position knowledge.",
        "examples": [
          {
            "description": "Cable offset added successfully",
            "name": "Offset Added",
            "value": {
              "action": "REEL_ADD_ENCODER_OFFSET",
              "error": false,
              "error_msgs": [],
              "result": {
                "new_cable_length": 28.2,
                "success": true
              }
            }
          },
          {
            "description": "Negative cable offset applied successfully",
            "name": "Negative Offset Applied",
            "value": {
              "action": "REEL_ADD_ENCODER_OFFSET",
              "error": false,
              "error_msgs": [],
              "result": {
                "new_cable_length": 18.3,
                "success": true
              }
            }
          },
          {
            "description": "Cannot add offset - encoder not installed",
            "name": "No Encoder Installed",
            "value": {
              "action": "REEL_ADD_ENCODER_OFFSET",
              "error": true,
              "error_msgs": [
                "Encoder not installed"
              ],
              "result": {
                "new_cable_length": 0.0,
                "success": false
              }
            }
          }
        ]
      },
      "AddCableOffsetResult": {
        "properties": {
          "success": {
            "type": "boolean",
            "title": "Success",
            "description": "Indicates whether the offset operation completed successfully.\n        \nTrue when the offset was applied successfully, False if the operation failed (e.g., encoder not installed).\n        ",
            "example": true
          },
          "new_cable_length": {
            "type": "number",
            "title": "New Cable Length",
            "description": "The updated cable position in meters after applying the offset.\n        \nRepresents the final cable position following the offset operation. This is the original position plus the applied offset value.\n        ",
            "example": 28.2,
            "calculation": "original_position + offset_value",
            "unit": "meters"
          }
        },
        "type": "object",
        "required": [
          "success",
          "new_cable_length"
        ],
        "title": "AddCableOffsetResult",
        "description": "Result data for cable encoder offset operations."
      },
      "AmlEnduraChargerStatusSchema": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "description": "\nCurrent charger status.\n\n**Possible values:**\n- \"Unknown\": Plugin not initialized\n- \"Search\": Charger is searching for a receiver\n- \"RX misaligned\": Receiver is present but not properly aligned\n- \"RX in range\": Receiver is detected and in range\n- \"RX charging\": Active charging in progress\n- \"VIN fault\": Input voltage fault detected\n- \"OC/OV fault\": Overcurrent or overvoltage fault\n- \"RX thermal fault\": Receiver thermal fault detected\n- \"TX thermal fault\": Transmitter thermal fault detected\n        "
          },
          "state_value": {
            "type": "integer",
            "maximum": 7.0,
            "minimum": -1.0,
            "title": "State Value",
            "description": "\nRaw state value (0-7) from charger.\n\n**Mapping:**\n- -1: \"Unknown\"\n- 0: \"Search\"\n- 1: \"RX misaligned\"\n- 2: \"RX in range\"\n- 3: \"RX charging\"\n- 4: \"VIN fault\"\n- 5: \"OC/OV fault\"\n- 6: \"RX thermal fault\"\n- 7: \"TX thermal fault\"\n        ",
            "enum_values": {
              "-1": "Unknown",
              "0": "Search",
              "1": "RX misaligned",
              "2": "RX in range",
              "3": "RX charging",
              "4": "VIN fault",
              "5": "OC/OV fault",
              "6": "RX thermal fault",
              "7": "TX thermal fault"
            }
          }
        },
        "type": "object",
        "required": [
          "status",
          "state_value"
        ],
        "title": "AmlEnduraChargerStatusSchema",
        "description": "Status schema for AML Endura 3/6 Charger plugin.\n\nContains the specific status fields reported by the AML Endura Charger\nplugin in the heartbeat response.",
        "examples": [
          {
            "description": "Charging active and working normally",
            "summary": "Charging",
            "value": {
              "state_value": 3,
              "status": "RX charging"
            }
          },
          {
            "description": "Receiver detected but not charging",
            "summary": "In Range",
            "value": {
              "state_value": 2,
              "status": "RX in range"
            }
          },
          {
            "description": "Receiver thermal fault",
            "summary": "Error",
            "value": {
              "state_value": 6,
              "status": "RX thermal fault"
            }
          }
        ]
      },
      "BlocksMovementSchema": {
        "properties": {
          "directions": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "enum": [
              "STOP",
              "WIND",
              "UNWIND"
            ],
            "title": "Directions",
            "description": "\nList of movement directions that are blocked by the active operation.\n\n**Possible Values**:\n- \"STOP\": Stop commands blocked (rarely used)\n- \"WIND\": Wind/retract commands blocked\n- \"UNWIND\": Unwind/extend commands blocked\n\n**Empty List**: No movement directions blocked\n        ",
            "examples": [
              [
                "WIND",
                "UNWIND"
              ],
              [
                "WIND"
              ],
              []
            ]
          },
          "origins": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Origins",
            "description": "\nList of command origins that are blocked by the active operation.\n\n**Possible Values**:\n- \"api\": Commands from REST API\n- \"physical_control\": Commands from physical pendant/controls\n- \"active_hold_position\": Active hold position adjustments\n- \"safety_controller\": Safety system commands\n- \"plugin_docking_mechanism\": Docking plugin commands\n- Others as defined in MovementCommandOrigin enum\n\n**Default**: [\"api\", \"physical_control\"] - blocks user-initiated commands\n        ",
            "examples": [
              [
                "api",
                "physical_control"
              ],
              [
                "api"
              ]
            ]
          }
        },
        "type": "object",
        "title": "BlocksMovementSchema",
        "description": "Movement blocking configuration for active operations."
      },
      "Body_login_user_api_v1_login_post": {
        "properties": {
          "grant_type": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^password$"
              },
              {
                "type": "null"
              }
            ],
            "title": "Grant Type"
          },
          "username": {
            "type": "string",
            "title": "Username"
          },
          "password": {
            "type": "string",
            "format": "password",
            "title": "Password"
          },
          "scope": {
            "type": "string",
            "title": "Scope",
            "default": ""
          },
          "client_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Client Id"
          },
          "client_secret": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "format": "password",
            "title": "Client Secret"
          }
        },
        "type": "object",
        "required": [
          "username",
          "password"
        ],
        "title": "Body_login_user_api_v1_login_post"
      },
      "BypassSettings": {
        "properties": {
          "reed_switch_bypassed": {
            "type": "boolean",
            "title": "Reed Switch Bypassed",
            "description": "Bypass reed switch position reset functionality.\n        \nWhen enabled, ignores reed switch activation. \n        ",
            "default": false,
            "example": true,
            "consequence": "Reed switch closing will not fire-off an event. Features depending on that event will not work, such as stopping the reel, or resetting the cable counter to 0."
          }
        },
        "type": "object",
        "title": "BypassSettings",
        "description": "Individual bypass control settings for operational flexibility."
      },
      "CablePositionCalibrationStatus": {
        "properties": {
          "active": {
            "type": "boolean",
            "title": "Active",
            "description": "Whether cable position calibration is currently active",
            "example": true
          }
        },
        "type": "object",
        "required": [
          "active"
        ],
        "title": "CablePositionCalibrationStatus",
        "description": "Cable position calibration operation status when active.\n\nProvides detailed information about the cable position encoder\ncalibration process that establishes accurate position reference."
      },
      "CablePositionEncoderInfoResponse": {
        "properties": {
          "calibrated": {
            "type": "boolean",
            "title": "Calibrated",
            "description": "Indicates whether the cable position encoder has been successfully calibrated.\n        \nTrue when the encoder has completed calibration and calibration factor is set for accurate position measurements. False when calibration is required or has not been performed.\n        ",
            "example": true,
            "requirement": "Required for accurate cable position measurements"
          },
          "calibrated_timestamp": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "format": "ISO 8601 datetime string",
            "title": "Calibrated Timestamp",
            "description": "ISO 8601 timestamp of the last successful cable position calibration.\n        \nRecords when calibration was last completed successfully. Null if no calibration has been performed. Useful for maintenance tracking and calibration history.\n        ",
            "example": "2024-09-03T10:15:30Z"
          },
          "calibration_factor": {
            "type": "integer",
            "title": "Calibration Factor",
            "description": "Current encoder calibration factor in pulses per meter.\n        \nConversion factor used to translate encoder pulses into distance measurements. Determined during calibration process and affects all position calculations.\n        ",
            "example": 1895,
            "typical_range": "1500-25000",
            "unit": "pulses_per_meter"
          },
          "connected": {
            "type": "boolean",
            "title": "Connected",
            "description": "Cable position encoder connectivity status.\n        \nTrue when the encoder is connected and communicating properly. False when encoder is disconnected, offline, or experiencing communication issues.\n        ",
            "example": true,
            "related_field": "is_encoder_disconnected in heartbeat (inverted)"
          }
        },
        "type": "object",
        "required": [
          "calibrated",
          "calibrated_timestamp",
          "calibration_factor",
          "connected"
        ],
        "title": "CablePositionEncoderInfoResponse",
        "description": "Status and calibration information for the cable position encoder."
      },
      "CablePositionOperationResult": {
        "properties": {
          "new_position": {
            "type": "number",
            "title": "New Position",
            "description": "The updated encoder position in meters after the operation.\n        \nRepresents the cable position following the requested operation. Positive values typically indicate cable extended from the reel, while the zero point serves as the operational reference.\n        ",
            "example": 15.5,
            "reference": "Zero point established by last zero operation",
            "unit": "meters"
          }
        },
        "type": "object",
        "required": [
          "new_position"
        ],
        "title": "CablePositionOperationResult",
        "description": "Result data for cable position operations that modify encoder position."
      },
      "CableReelInfoResponse": {
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid4",
            "title": "Uuid",
            "description": "Unique identifier for this reel system.\n        \nPermanent UUID that uniquely identifies this specific reel hardware. Used for asset tracking, configuration management, and system identification.\n        ",
            "default": "00000000-0000-0000-0000-000000000000",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "serial_number": {
            "type": "string",
            "title": "Serial Number",
            "description": "Hardware serial number for this reel system.\n        \nFactory or field-assigned serial number for hardware identification and warranty tracking. Can be updated by administrators.\n        ",
            "default": "UNSET",
            "example": "RWS-2024-001",
            "updatable": "Admin users only"
          },
          "display_name": {
            "type": "string",
            "title": "Display Name",
            "description": "User-friendly display name for this reel system.\n        \nCustomizable name for easy identification in multi-reel environments or user interfaces. Can be updated by any authenticated user.\n        ",
            "default": "Smart Winch",
            "example": "Smart Winch",
            "updatable": "All authenticated users"
          },
          "api_version": {
            "type": "string",
            "format": "semantic_version",
            "title": "Api Version",
            "description": "Current ReelAPI software version.\n        \nVersion of the ReelAPI system software. Used for compatibility checking and feature availability verification by client applications.\n        ",
            "example": "1.1.3"
          },
          "reel_chassis": {
            "$ref": "#/components/schemas/ReelChassisInfoResponse",
            "description": "Reel chassis hardware information.\n    \nProvides information about the physical reel chassis hardware platform.\n    "
          },
          "motor_driver": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MotorDriverInfoResponse"
              },
              {
                "type": "null"
              }
            ],
            "description": "Motor driver hardware information.\n        \nProvides comprehensive information about the installed motor driver including type and version. Null indicates no motor driver is installed or information is unavailable.\n        "
          },
          "encoders": {
            "$ref": "#/components/schemas/EncodersInfoResponse",
            "description": "Consolidated encoder information for all system encoders.\n        \nProvides comprehensive information about installed encoders including cable position and motor position encoders with their respective types.\n        "
          },
          "calibrations": {
            "$ref": "#/components/schemas/CalibrationsInfoResponse",
            "description": "Consolidated calibration information for all system components.\n        \nProvides comprehensive calibration status and information for PID controller and cable position encoder in a single organized structure.\n        "
          },
          "setup": {
            "$ref": "#/components/schemas/SetupStatusSimple",
            "description": "Current setup status and phase information.\n        \nProvides information about the system's setup progress, including current phase and component configuration status. Essential for managing devices during initial setup and maintenance.\n        ",
            "example": {
              "component_configuration_complete": true,
              "configured_components": 6,
              "current_phase": "complete",
              "hardware_verification_complete": true,
              "setup_mode_active": false,
              "unconfigured_components": 0
            }
          },
          "reed_switch": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ReedSwitchInfoResponse"
              },
              {
                "type": "null"
              }
            ],
            "description": "Reed switch configuration and role information.\n        \nProvides information about the reed switch hardware if installed. Not all systems have reed switches installed.\n        ",
            "example": {
              "role": "emergency_stop"
            },
            "optional": true
          }
        },
        "type": "object",
        "required": [
          "api_version",
          "reel_chassis",
          "encoders",
          "calibrations",
          "setup"
        ],
        "title": "CableReelInfoResponse",
        "description": "Static system information and hardware configuration details.",
        "examples": [
          {
            "description": "Full system information including reel identification and setup status",
            "name": "Complete Reel Info",
            "value": {
              "api_version": "1.1.3",
              "calibrations": {
                "cable_position_encoder": {
                  "calibrated": true,
                  "calibrated_timestamp": "2024-09-03T10:15:30Z",
                  "calibration_factor": 1895,
                  "connected": true
                },
                "pid_controller": {
                  "calibrated": true,
                  "calibrated_timestamp": "2024-09-15T14:30:00Z",
                  "calibrating": false
                }
              },
              "display_name": "Smart Winch",
              "encoders": {
                "cable_position": {
                  "type": "qsb"
                },
                "motor_position": {
                  "type": "roboclaw"
                }
              },
              "motor_driver": {
                "type": "roboclaw",
                "version": "v4.2.8"
              },
              "reel_chassis": {
                "type": "croc_mini"
              },
              "serial_number": "RWS-2024-001",
              "setup": {
                "component_configuration_complete": true,
                "configured_components": 6,
                "current_phase": "complete",
                "hardware_verification_complete": true,
                "setup_mode_active": false,
                "unconfigured_components": 0
              },
              "uuid": "550e8400-e29b-41d4-a716-446655440000"
            }
          },
          {
            "description": "System with cable encoder needing calibration",
            "name": "Uncalibrated Cable Encoder",
            "value": {
              "api_version": "1.1.3",
              "calibrations": {
                "cable_position_encoder": {
                  "calibrated": false,
                  "calibration_factor": 1,
                  "connected": true
                },
                "pid_controller": {
                  "calibrated": false,
                  "calibrating": false
                }
              },
              "display_name": "Smart Winch - Needs Calibration",
              "encoders": {
                "cable_position": {
                  "type": "qsb"
                },
                "motor_position": {
                  "type": "roboclaw"
                }
              },
              "motor_driver": {
                "type": "roboclaw",
                "version": "v4.2.8"
              },
              "reel_chassis": {
                "type": "kronos"
              },
              "serial_number": "RWS-2024-002",
              "setup": {
                "component_configuration_complete": true,
                "configured_components": 6,
                "current_phase": "complete",
                "hardware_verification_complete": true,
                "setup_mode_active": false,
                "unconfigured_components": 0
              },
              "uuid": "550e8400-e29b-41d4-a716-446655440000"
            }
          },
          {
            "description": "System currently in setup mode for configuration",
            "name": "In Setup Mode",
            "value": {
              "api_version": "1.1.3",
              "calibrations": {
                "cable_position_encoder": {
                  "calibrated": false,
                  "calibration_factor": 1,
                  "connected": true
                },
                "pid_controller": {
                  "calibrated": false,
                  "calibrating": false
                }
              },
              "display_name": "Smart Winch - Setup",
              "encoders": {
                "cable_position": {},
                "motor_position": {}
              },
              "reel_chassis": {
                "type": "user"
              },
              "serial_number": "RWS-2024-004",
              "setup": {
                "component_configuration_complete": false,
                "configured_components": 2,
                "current_phase": "component_configuration",
                "hardware_verification_complete": false,
                "setup_mode_active": true,
                "unconfigured_components": 3
              },
              "uuid": "550e8400-e29b-41d4-a716-446655440000"
            }
          }
        ]
      },
      "CalibrationResult": {
        "properties": {
          "calibrating": {
            "type": "boolean",
            "title": "Calibrating",
            "description": "Current calibration status of the cable encoder system.\n        \nIndicates whether the system is actively in calibration mode. Monitor this status via heartbeat `is_cable_counter_calibrating` field. Emergency stop remains functional during calibration.\n        ",
            "example": true,
            "monitoring_field": "is_cable_counter_calibrating"
          }
        },
        "type": "object",
        "required": [
          "calibrating"
        ],
        "title": "CalibrationResult",
        "description": "Result data for calibration start and cancel operations."
      },
      "CalibrationsInfoResponse": {
        "properties": {
          "pid_controller": {
            "$ref": "#/components/schemas/PIDControllerInfoResponse",
            "description": "PID controller status and calibration information.\n        \nProvides detailed information about the PID controller used for active position hold. Includes calibration status and timing information.\n        "
          },
          "cable_position_encoder": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CablePositionEncoderInfoResponse"
              },
              {
                "type": "null"
              }
            ],
            "description": "Cable position encoder status and calibration information.\n        \nProvides detailed information about the cable position encoder used for position feedback. Includes calibration status, connectivity, and timing information.\n        "
          }
        },
        "type": "object",
        "required": [
          "pid_controller",
          "cable_position_encoder"
        ],
        "title": "CalibrationsInfoResponse",
        "description": "Consolidated calibration information for all system components."
      },
      "CameraDevice": {
        "properties": {
          "device_name": {
            "type": "string",
            "title": "Device Name",
            "description": "Camera device name"
          },
          "bus_info": {
            "type": "string",
            "title": "Bus Info",
            "description": "USB bus information"
          },
          "device_path": {
            "type": "string",
            "title": "Device Path",
            "description": "Device path (e.g., /dev/video0)"
          },
          "card_name": {
            "type": "string",
            "title": "Card Name",
            "description": "Camera card name"
          },
          "driver_name": {
            "type": "string",
            "title": "Driver Name",
            "description": "Camera driver name"
          },
          "supported_formats": {
            "items": {
              "$ref": "#/components/schemas/SupportedFormat"
            },
            "type": "array",
            "title": "Supported Formats",
            "description": "All supported formats and resolutions",
            "default": []
          },
          "best_format": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CameraFormatDetail"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optimal format based on preferences"
          }
        },
        "type": "object",
        "required": [
          "device_name",
          "bus_info",
          "device_path",
          "card_name",
          "driver_name"
        ],
        "title": "CameraDevice",
        "description": "Individual camera device information",
        "example": {
          "best_format": {
            "format": "MJPG",
            "fps": 30.0,
            "height": 720,
            "width": 1280
          },
          "bus_info": "usb-xhci-hcd.1-2",
          "card_name": "Integrated_Webcam_HD: Integrate",
          "device_name": "Integrated_Webcam_HD: Integrate",
          "device_path": "/dev/video0",
          "driver_name": "uvcvideo",
          "supported_formats": []
        }
      },
      "CameraFormatDetail": {
        "properties": {
          "format": {
            "$ref": "#/components/schemas/VideoFormat",
            "description": "Video format (MJPG, YUYV, etc.)"
          },
          "width": {
            "type": "integer",
            "exclusiveMinimum": 0.0,
            "title": "Width",
            "description": "Frame width in pixels"
          },
          "height": {
            "type": "integer",
            "exclusiveMinimum": 0.0,
            "title": "Height",
            "description": "Frame height in pixels"
          },
          "fps": {
            "type": "number",
            "exclusiveMinimum": 0.0,
            "title": "Fps",
            "description": "Frames per second"
          }
        },
        "type": "object",
        "required": [
          "format",
          "width",
          "height",
          "fps"
        ],
        "title": "CameraFormatDetail",
        "description": "Camera format with resolution and framerate details",
        "example": {
          "format": "MJPG",
          "fps": 30.0,
          "height": 720,
          "width": 1280
        }
      },
      "CameraInfoResponse": {
        "properties": {
          "connected": {
            "type": "boolean",
            "title": "Connected",
            "description": "Whether any camera is connected"
          },
          "message": {
            "type": "string",
            "title": "Message",
            "description": "Information message"
          },
          "active_camera": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ActiveCameraStatus"
              },
              {
                "type": "null"
              }
            ],
            "description": "Currently active camera status"
          },
          "all_cameras": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/CameraDevice"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "All Cameras",
            "description": "All detected cameras when one is active"
          },
          "cameras": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/CameraDevice"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Cameras",
            "description": "All detected camera devices"
          },
          "primary_camera": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CameraDevice"
              },
              {
                "type": "null"
              }
            ],
            "description": "Primary/preferred camera"
          },
          "total_cameras": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Total Cameras",
            "description": "Total number of cameras detected"
          },
          "cameras_found": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/CameraDevice"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Cameras Found",
            "description": "Cameras found (may be empty)"
          }
        },
        "type": "object",
        "required": [
          "connected",
          "message"
        ],
        "title": "CameraInfoResponse",
        "description": "Response for GET /camera/info endpoint",
        "example": {
          "cameras": [
            {
              "best_format": {
                "format": "MJPG",
                "fps": 30.0,
                "height": 720,
                "width": 1280
              },
              "bus_info": "usb-xhci-hcd.1-2",
              "card_name": "Integrated_Webcam_HD: Integrate",
              "device_name": "Integrated_Webcam_HD: Integrate",
              "device_path": "/dev/video0",
              "driver_name": "uvcvideo",
              "supported_formats": []
            }
          ],
          "connected": true,
          "message": "Found 1 USB camera(s)",
          "primary_camera": {},
          "total_cameras": 1
        }
      },
      "CameraSettings": {
        "properties": {
          "preferred_resolution": {
            "type": "string",
            "title": "Preferred Resolution",
            "default": "1920x1080"
          },
          "preferred_framerate": {
            "type": "integer",
            "title": "Preferred Framerate",
            "default": 30
          },
          "preferred_format": {
            "type": "string",
            "title": "Preferred Format",
            "default": "MJPG"
          },
          "fallback_format": {
            "type": "string",
            "title": "Fallback Format",
            "default": "YUYV"
          },
          "exclude_devices": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Exclude Devices",
            "default": [
              "pispbe",
              "rpi-hevc-dec"
            ]
          },
          "jpeg_quality": {
            "type": "integer",
            "title": "Jpeg Quality",
            "default": 85
          },
          "buffer_size": {
            "type": "integer",
            "title": "Buffer Size",
            "default": 2
          }
        },
        "type": "object",
        "title": "CameraSettings"
      },
      "CameraStatusResponse": {
        "properties": {
          "connected": {
            "type": "boolean",
            "title": "Connected",
            "description": "Whether any camera is connected"
          },
          "message": {
            "type": "string",
            "title": "Message",
            "description": "Status message"
          },
          "ready": {
            "type": "boolean",
            "title": "Ready",
            "description": "Whether camera is ready for use"
          },
          "video_devices": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Video Devices",
            "description": "List of available video device paths"
          },
          "device_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Device Name",
            "description": "Primary camera device name"
          },
          "bus_info": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Bus Info",
            "description": "USB bus information"
          },
          "driver_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Driver Name",
            "description": "Camera driver name"
          },
          "best_format": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CameraFormatDetail"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optimal camera format"
          },
          "total_cameras": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Total Cameras",
            "description": "Total number of cameras detected"
          },
          "streaming": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Streaming",
            "description": "Whether camera is currently streaming"
          },
          "current_format": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CameraFormatDetail"
              },
              {
                "type": "null"
              }
            ],
            "description": "Current streaming format"
          },
          "cameras_found": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/CameraDevice"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Cameras Found",
            "description": "Cameras found but not ready"
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Error",
            "description": "Error message if camera failed to initialize"
          }
        },
        "type": "object",
        "required": [
          "connected",
          "message",
          "ready"
        ],
        "title": "CameraStatusResponse",
        "description": "Response for GET /camera/status endpoint",
        "example": {
          "best_format": {
            "format": "MJPG",
            "fps": 30.0,
            "height": 720,
            "width": 1280
          },
          "bus_info": "usb-xhci-hcd.1-2",
          "connected": true,
          "device_name": "Integrated_Webcam_HD: Integrate",
          "driver_name": "uvcvideo",
          "message": "Camera detected and ready",
          "ready": true,
          "total_cameras": 1,
          "video_devices": [
            "/dev/video0"
          ]
        }
      },
      "CancelCalibrationResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/CalibrationResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "CancelCalibrationResponse",
        "description": "Response for cancelling active cable encoder calibration.\n\nTerminates calibration mode and restores normal operations. Previous calibration factor is preserved.",
        "examples": [
          {
            "description": "Active calibration cancelled successfully",
            "name": "Calibration Cancelled",
            "value": {
              "action": "cancel_calibration",
              "error": false,
              "error_msgs": [],
              "result": {
                "calibrating": false
              }
            }
          },
          {
            "description": "No calibration was active (idempotent operation)",
            "name": "No Active Calibration",
            "value": {
              "action": "cancel_calibration",
              "error": false,
              "error_msgs": [],
              "result": {
                "calibrating": false
              }
            }
          },
          {
            "description": "Cannot cancel - no encoder installed",
            "name": "No Encoder",
            "value": {
              "action": "cancel_calibration",
              "error": true,
              "error_msgs": [
                "Encoder not installed"
              ],
              "result": {
                "calibrating": false
              }
            }
          }
        ]
      },
      "CancelPIDCalibrationResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/PIDCalibrationResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "CancelPIDCalibrationResponse",
        "description": "Response from cancelling active PID controller calibration",
        "cancellation_effects": [
          "Immediately stops automated calibration movements",
          "Preserves existing PID controller parameters",
          "Returns motor control to normal operational mode",
          "No partial calibration results are applied"
        ],
        "safety_features": [
          "Safe termination of all calibration movements",
          "Automatic restoration of previous control mode",
          "Preservation of last known good PID configuration"
        ]
      },
      "CommandLockoutRequest": {
        "properties": {
          "lockout_enabled": {
            "type": "boolean",
            "title": "Lockout Enabled",
            "description": "Enable or disable movement command restrictions.\n        \nWhen True, blocks all user movement commands (wind, unwind, go-to, jog, speed) while preserving safety features. When False, allows normal movement command processing.\n        ",
            "example": false,
            "safety_note": "Emergency stop and safeguards remain functional when locked out"
          }
        },
        "type": "object",
        "required": [
          "lockout_enabled"
        ],
        "title": "CommandLockoutRequest",
        "description": "Request data for setting command lockout state.",
        "examples": [
          {
            "description": "Block all movement commands",
            "name": "Enable Lockout",
            "value": {
              "lockout_enabled": true
            }
          },
          {
            "description": "Allow normal movement commands",
            "name": "Disable Lockout",
            "value": {
              "lockout_enabled": false
            }
          }
        ]
      },
      "CommandLockoutResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/CommandLockoutResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "CommandLockoutResponse",
        "description": "Response for command lockout operations.\n\nManages movement command restrictions for enhanced safety control. Lockout system blocks user movement commands while preserving emergency stop and safety feature functionality.",
        "examples": [
          {
            "description": "Movement commands now blocked",
            "name": "Lockout Enabled",
            "value": {
              "action": "set_command_lockout",
              "error": false,
              "error_msgs": [],
              "result": {
                "lockout_enabled": true
              }
            }
          },
          {
            "description": "Movement commands now allowed",
            "name": "Lockout Disabled",
            "value": {
              "action": "set_command_lockout",
              "error": false,
              "error_msgs": [],
              "result": {
                "lockout_enabled": false
              }
            }
          },
          {
            "description": "Current lockout state retrieved",
            "name": "Lockout Status",
            "value": {
              "action": "get_command_lockout_status",
              "error": false,
              "error_msgs": [],
              "result": {
                "lockout_enabled": false
              }
            }
          }
        ]
      },
      "CommandLockoutResult": {
        "properties": {
          "lockout_enabled": {
            "type": "boolean",
            "title": "Lockout Enabled",
            "description": "Current state of the command lockout system.\n        \nIndicates whether movement commands are currently blocked (True) or allowed (False). This status affects all user-initiated movement operations.\n        ",
            "example": false,
            "scope": "Affects wind, unwind, go-to, jog, and speed commands"
          }
        },
        "type": "object",
        "required": [
          "lockout_enabled"
        ],
        "title": "CommandLockoutResult",
        "description": "Result data for command lockout operations."
      },
      "ComponentConfigRequest": {
        "properties": {
          "settings": {
            "additionalProperties": true,
            "type": "object",
            "title": "Settings",
            "description": "Configuration settings for the component.\n        \n**Required Field:**\n- **type** (string): Hardware type identifier\n\n**Optional Fields:**\n- Hardware-specific parameters (addresses, pins, etc.)\n- Calibration values and operational settings\n- Safety thresholds and timing configurations\n\n**Example Settings by Component:**\n```json\n{\n  \"type\": \"roboclaw\",\n  \"address\": \"0x80\",\n  \"baud_rate\": 38400\n}\n```\n        ",
            "example": {
              "address": "0x80",
              "baud_rate": 38400,
              "type": "roboclaw"
            },
            "required_field": "type"
          }
        },
        "type": "object",
        "required": [
          "settings"
        ],
        "title": "ComponentConfigRequest",
        "description": "Request payload for configuring a system component.\n\nContains the configuration settings needed to set up a specific\nhardware component in the system.",
        "examples": [
          {
            "description": "Configure Roboclaw motor driver with address",
            "summary": "Motor Driver Configuration",
            "value": {
              "settings": {
                "address": "0x80",
                "baud_rate": 38400,
                "type": "roboclaw"
              }
            }
          },
          {
            "description": "Configure QSB encoder with basic settings",
            "summary": "Encoder Configuration",
            "value": {
              "settings": {
                "resolution": 1000,
                "type": "qsb"
              }
            }
          },
          {
            "description": "Configure component as not present",
            "summary": "Null Component",
            "value": {
              "settings": {
                "type": "null"
              }
            }
          }
        ]
      },
      "ComponentConfigResponse": {
        "properties": {
          "success": {
            "type": "boolean",
            "title": "Success",
            "description": "Whether the component configuration was successful.\n        \n- **True**: Component configured successfully, settings applied\n- **False**: Configuration failed, check error details\n\n**Success Criteria:**\n- Hardware type is valid for the component\n- Configuration settings pass validation  \n- Component successfully initializes with settings\n        ",
            "example": true
          },
          "component_id": {
            "type": "string",
            "title": "Component Id",
            "description": "The component identifier that was configured",
            "example": "motor_driver",
            "matches": "Path parameter from configuration request"
          },
          "remaining_components": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Remaining Components",
            "description": "Components that still need configuration after this operation.\n        \n**Empty List**: All components now configured, can exit setup mode\n**Non-Empty**: Additional components still require configuration\n\n**Setup Progress**: Compare with previous unconfigured_components list to track progress\n        ",
            "example": [
              "cable_encoder"
            ],
            "decreases": "As components are successfully configured"
          }
        },
        "type": "object",
        "required": [
          "success",
          "component_id",
          "remaining_components"
        ],
        "title": "ComponentConfigResponse",
        "description": "Response from component configuration operation.\n\nIndicates whether configuration was successful and provides\nupdated information about remaining setup tasks.",
        "examples": [
          {
            "description": "Component configured with remaining tasks",
            "summary": "Successful Configuration",
            "value": {
              "component_id": "motor_driver",
              "remaining_components": [
                "cable_encoder"
              ],
              "success": true
            }
          }
        ]
      },
      "ConfiguredComponent": {
        "properties": {
          "component_id": {
            "type": "string",
            "pattern": "^[a-z_]+$",
            "title": "Component Id",
            "description": "Component identifier from system manifest.\n        \n**Common Component IDs:**\n- **motor_driver** - Primary motor control hardware\n- **cable_encoder** - Cable position measurement system  \n- **motor_encoder** - Motor position feedback encoder\n- **physical_control** - Manual control interfaces\n- **reed_switch** - Magnetic proximity sensors\n- **estop** - Emergency stop safety systems\n        ",
            "example": "motor_driver"
          },
          "type": {
            "type": "string",
            "title": "Type",
            "description": "Configured hardware type identifier.\n        \n**Hardware Types by Component:**\n- **Motor Drivers**: roboclaw, motoron, null\n- **Encoders**: roboclaw, qsb, null  \n- **Control Systems**: pendant, gpio, null\n- **Safety Systems**: gpio, null\n\n**null type**: Indicates component is not physically present\n        ",
            "example": "roboclaw",
            "note": "Hardware-specific driver implementation"
          }
        },
        "type": "object",
        "required": [
          "component_id",
          "type"
        ],
        "title": "ConfiguredComponent",
        "description": "Information about a successfully configured system component.\n\nRepresents a component that has been properly configured with\nits hardware type and is ready for operation.",
        "example": {
          "component_id": "motor_driver",
          "type": "roboclaw"
        }
      },
      "CpuStatus": {
        "properties": {
          "frequency_mhz": {
            "type": "integer",
            "title": "Frequency Mhz",
            "description": "Current CPU frequency in MHz"
          },
          "max_frequency_mhz": {
            "type": "integer",
            "title": "Max Frequency Mhz",
            "description": "Maximum CPU frequency in MHz"
          },
          "is_throttled": {
            "type": "boolean",
            "title": "Is Throttled",
            "description": "CPU is currently throttled"
          }
        },
        "type": "object",
        "required": [
          "frequency_mhz",
          "max_frequency_mhz",
          "is_throttled"
        ],
        "title": "CpuStatus",
        "description": "CPU frequency and throttle status"
      },
      "DetailedHealthCheckResponse": {
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "healthy",
              "unhealthy"
            ],
            "title": "Status",
            "description": "Overall system health status.\n        \n- **\"healthy\"**: All systems operational and within normal parameters  \n- **\"unhealthy\"**: One or more critical systems experiencing issues\n        ",
            "example": "healthy"
          },
          "database_connection": {
            "type": "string",
            "enum": [
              "ok",
              "failed"
            ],
            "title": "Database Connection",
            "description": "Database connectivity status.\n        \n- **\"ok\"**: Database is accessible and responding normally\n- **\"failed\"**: Unable to establish database connection\n        ",
            "example": "ok"
          },
          "database_latency": {
            "type": "number",
            "minimum": 0.0,
            "title": "Database Latency",
            "description": "Database connection latency in milliseconds.",
            "example": 23.5,
            "typical_range": "10-100ms",
            "unit": "milliseconds"
          },
          "version": {
            "type": "string",
            "format": "semantic versioning (major.minor.patch)",
            "title": "Version",
            "description": "Current ReelAPI version number",
            "example": "1.1.3"
          },
          "api_version": {
            "type": "string",
            "format": "version prefix (v1, v2, etc.)",
            "title": "Api Version",
            "description": "API endpoint version identifier",
            "example": "v1"
          },
          "serial_number": {
            "type": "string",
            "title": "Serial Number",
            "description": "Hardware serial number for this reel system.\n        \nFactory or field-assigned serial number for hardware identification and warranty tracking. Can be updated by administrators.\n        ",
            "default": "UNSET",
            "example": "RWS-2024-001",
            "updatable": "Admin users only"
          },
          "display_name": {
            "type": "string",
            "title": "Display Name",
            "description": "User-friendly display name for this reel system.\n        \nCustomizable name for easy identification in multi-reel environments or user interfaces. Can be updated by any authenticated user.\n        ",
            "default": "Smart Winch",
            "example": "Smart Winch",
            "updatable": "All authenticated users"
          },
          "uuid": {
            "type": "string",
            "format": "uuid4",
            "title": "Uuid",
            "description": "Unique identifier for this reel system.\n        \nPermanent UUID that uniquely identifies this specific reel hardware. Used for asset tracking, configuration management, and system identification.\n        ",
            "default": "00000000-0000-0000-0000-000000000000",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "environment": {
            "type": "string",
            "title": "Environment",
            "description": "Deployment environment identifier.\n        \n**Common Values:**\n- **\"production\"**: Live production deployment\n- **\"testing\"**: Testing environment  \n- **\"local\"**: Local development instance\n\n**Usage**: Helps identify which environment is being monitored\n        ",
            "example": "production",
            "common_values": [
              "production",
              "development",
              "local"
            ]
          },
          "disk_space": {
            "$ref": "#/components/schemas/DiskSpace",
            "description": "Detailed disk space utilization metrics.\n        \nProvides comprehensive storage information including:\n- **Byte-level precision** for exact storage calculations\n- **Gigabyte conversions** for human-readable capacity planning  \n- **Percentage utilization** for threshold monitoring"
          },
          "raspi_hardware": {
            "$ref": "#/components/schemas/RaspiHardwareStatus",
            "description": "Raspberry Pi 5 hardware diagnostics including temperature and power status"
          }
        },
        "type": "object",
        "required": [
          "status",
          "database_connection",
          "database_latency",
          "version",
          "api_version",
          "environment",
          "disk_space",
          "raspi_hardware"
        ],
        "title": "DetailedHealthCheckResponse",
        "description": "Comprehensive system health diagnostics response.\n\nExtends basic health check with detailed performance metrics and\nsystem information for thorough diagnostics and monitoring.",
        "examples": [
          {
            "description": "Comprehensive health status showing optimal performance",
            "summary": "Healthy System - Detailed",
            "value": {
              "api_version": "v1",
              "database_connection": "ok",
              "database_latency": 23.5,
              "disk_space": {
                "free_bytes": 33739681792,
                "free_gb": 31.42,
                "percent_used": 40.74,
                "total_bytes": 62303657984,
                "total_gb": 58.02,
                "used_bytes": 25381072896,
                "used_gb": 23.64
              },
              "display_name": "Smart Winch",
              "environment": "production",
              "raspi_hardware": {
                "cpu": {
                  "frequency_mhz": 2400,
                  "is_throttled": false,
                  "max_frequency_mhz": 2400
                },
                "power": {
                  "input_voltage_v": 5.14,
                  "under_voltage_detected": false
                },
                "temperature": {
                  "status": "healthy",
                  "temperature_celsius": 59.7
                }
              },
              "serial_number": "RWS-2024-001",
              "status": "healthy",
              "uuid": "550e8400-e29b-41d4-a716-446655440000",
              "version": "1.1.3"
            }
          },
          {
            "description": "Detailed diagnostics showing performance or connectivity problems",
            "summary": "System Issues - Detailed",
            "value": {
              "api_version": "v1",
              "database_connection": "failed",
              "database_latency": 1205.8,
              "disk_space": {
                "free_bytes": 4000000000,
                "free_gb": 3.71,
                "percent_used": 93.61,
                "total_bytes": 62303657984,
                "total_gb": 58.02,
                "used_bytes": 58303657984,
                "used_gb": 54.31
              },
              "display_name": "Smart Winch",
              "environment": "production",
              "raspi_hardware": {
                "cpu": {
                  "frequency_mhz": 1000,
                  "is_throttled": true,
                  "max_frequency_mhz": 2400
                },
                "power": {
                  "input_voltage_v": 4.82,
                  "under_voltage_detected": true
                },
                "temperature": {
                  "status": "critical",
                  "temperature_celsius": 81.2
                }
              },
              "serial_number": "RWS-2024-001",
              "status": "unhealthy",
              "uuid": "550e8400-e29b-41d4-a716-446655440000",
              "version": "1.1.3"
            }
          }
        ]
      },
      "DiskSpace": {
        "properties": {
          "total_bytes": {
            "type": "integer",
            "title": "Total Bytes",
            "description": "Total disk space in bytes",
            "example": 62303657984,
            "unit": "bytes"
          },
          "used_bytes": {
            "type": "integer",
            "title": "Used Bytes",
            "description": "Used disk space in bytes",
            "example": 25381072896,
            "unit": "bytes"
          },
          "free_bytes": {
            "type": "integer",
            "title": "Free Bytes",
            "description": "Available free disk space in bytes",
            "example": 33739681792,
            "unit": "bytes"
          },
          "total_gb": {
            "type": "number",
            "title": "Total Gb",
            "description": "Total disk space in gigabytes (rounded to 2 decimal places)",
            "example": 58.02,
            "precision": "2 decimal places",
            "unit": "gigabytes"
          },
          "used_gb": {
            "type": "number",
            "title": "Used Gb",
            "description": "Used disk space in gigabytes (rounded to 2 decimal places)",
            "example": 23.64,
            "precision": "2 decimal places",
            "unit": "gigabytes"
          },
          "free_gb": {
            "type": "number",
            "title": "Free Gb",
            "description": "Free disk space in gigabytes (rounded to 2 decimal places)",
            "example": 31.42,
            "precision": "2 decimal places",
            "unit": "gigabytes"
          },
          "percent_used": {
            "type": "number",
            "maximum": 100.0,
            "minimum": 0.0,
            "title": "Percent Used",
            "description": "Percentage of disk space currently used",
            "example": 40.74,
            "range": "0-100",
            "unit": "percentage"
          }
        },
        "type": "object",
        "required": [
          "total_bytes",
          "used_bytes",
          "free_bytes",
          "total_gb",
          "used_gb",
          "free_gb",
          "percent_used"
        ],
        "title": "DiskSpace",
        "description": "Detailed disk space utilization metrics.\n\nProvides comprehensive storage information for system monitoring\nand capacity planning.",
        "examples": [
          {
            "description": "Healthy disk space with moderate utilization",
            "summary": "Normal Disk Usage",
            "value": {
              "free_bytes": 33739681792,
              "free_gb": 31.42,
              "percent_used": 40.74,
              "total_bytes": 62303657984,
              "total_gb": 58.02,
              "used_bytes": 25381072896,
              "used_gb": 23.64
            }
          },
          {
            "description": "High disk utilization requiring attention",
            "summary": "Low Disk Space Warning",
            "value": {
              "free_bytes": 4000000000,
              "free_gb": 1.71,
              "percent_used": 97.05,
              "total_bytes": 62303657984,
              "total_gb": 58.02,
              "used_bytes": 58303657984,
              "used_gb": 56.31
            }
          }
        ]
      },
      "DockingPluginStatusSchema": {
        "properties": {
          "state": {
            "$ref": "#/components/schemas/DockingState",
            "description": "Current state of the docking mechanism",
            "examples": [
              "idle",
              "docked",
              "docking_winding",
              "undocking_unwinding"
            ]
          },
          "is_docked": {
            "type": "boolean",
            "title": "Is Docked",
            "description": "Whether the payload is currently docked"
          },
          "is_moving": {
            "type": "boolean",
            "title": "Is Moving",
            "description": "Whether a docking/undocking operation is in progress"
          },
          "reed_switch_state": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reed Switch State",
            "description": "Current reed switch sensor state (True=closed, False=open, None=unknown)"
          }
        },
        "type": "object",
        "required": [
          "state",
          "is_docked",
          "is_moving"
        ],
        "title": "DockingPluginStatusSchema",
        "description": "Status schema for docking mechanism plugin heartbeat data."
      },
      "DockingSettingsUpdate": {
        "properties": {
          "plugin_type": {
            "type": "string",
            "const": "docking_mechanism",
            "title": "Plugin Type",
            "description": "Plugin identifier for discriminated union",
            "default": "docking_mechanism"
          },
          "dock_timeout_seconds": {
            "anyOf": [
              {
                "type": "integer",
                "maximum": 300.0,
                "minimum": 1.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Dock Timeout Seconds",
            "description": "Timeout for docking operations in seconds"
          },
          "undock_timeout_seconds": {
            "anyOf": [
              {
                "type": "integer",
                "maximum": 300.0,
                "minimum": 1.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Undock Timeout Seconds",
            "description": "Timeout for undocking operations in seconds"
          },
          "motor_speed": {
            "anyOf": [
              {
                "type": "integer",
                "maximum": 100.0,
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Motor Speed",
            "description": "Motor speed percentage (0-100)"
          },
          "docking_reversing_timeout_seconds": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 30.0,
                "minimum": 0.05
              },
              {
                "type": "null"
              }
            ],
            "title": "Docking Reversing Timeout Seconds",
            "description": "Timeout for reverse phase during docking (seconds)"
          },
          "undock_wind_delay_seconds": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 10.0,
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Undock Wind Delay Seconds",
            "description": "Duration to continue winding after reed opens during undocking (seconds)"
          },
          "undock_completion_delay_seconds": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 10.0,
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Undock Completion Delay Seconds",
            "description": "Delay after final reed open before stopping (seconds)"
          }
        },
        "type": "object",
        "title": "DockingSettingsUpdate",
        "description": "Updateable settings for Docking Mechanism plugin."
      },
      "DockingState": {
        "type": "string",
        "enum": [
          "idle",
          "docking_winding",
          "docking_wait_open",
          "docking_reversing",
          "docked",
          "undocking_winding",
          "undocking_wait_close",
          "undocking_wait_open",
          "undocking_completing"
        ],
        "title": "DockingState",
        "description": "States for docking state machine."
      },
      "EmergencyStopActivateResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/EmergencyStopResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "EmergencyStopActivateResponse",
        "description": "Response for emergency stop activation requests.\n\nActivates the emergency stop system to immediately halt all reel motor operations. Emergency stop takes priority over all other motor commands and maintains its state until explicitly deactivated.",
        "examples": [
          {
            "description": "Emergency stop activated successfully",
            "name": "Emergency Stop Activated",
            "value": {
              "action": "REEL_ACTIVATE_ESTOP",
              "error": false,
              "error_msgs": [],
              "result": {
                "is_active": true
              }
            }
          },
          {
            "description": "Emergency stop activation failed",
            "name": "Activation Failed",
            "value": {
              "action": "REEL_ACTIVATE_ESTOP",
              "error": true,
              "error_msgs": [
                "Failed to activate emergency stop."
              ],
              "result": {
                "is_active": false
              }
            }
          }
        ]
      },
      "EmergencyStopDeactivateResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/EmergencyStopResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "EmergencyStopDeactivateResponse",
        "description": "Response for emergency stop deactivation requests.\n\nDeactivates the emergency stop system to restore normal reel operations. Ensures the operational area is clear before deactivating emergency stop, as normal motor controls will resume functionality.",
        "examples": [
          {
            "description": "Emergency stop deactivated successfully",
            "name": "Emergency Stop Deactivated",
            "value": {
              "action": "REEL_DEACTIVATE_ESTOP",
              "error": false,
              "error_msgs": [],
              "result": {
                "is_active": false
              }
            }
          },
          {
            "description": "Emergency stop deactivation failed",
            "name": "Deactivation Failed",
            "value": {
              "action": "REEL_DEACTIVATE_ESTOP",
              "error": true,
              "error_msgs": [
                "Failed to deactivate emergency stop."
              ],
              "result": {
                "is_active": true
              }
            }
          }
        ]
      },
      "EmergencyStopResult": {
        "properties": {
          "is_active": {
            "type": "boolean",
            "title": "Is Active",
            "description": "Current emergency stop activation status.\n        \nIndicates whether the emergency stop system is currently active. When active (true), all motor operations are halted and normal reel controls are disabled. When inactive (false), normal reel operations are permitted.\n        ",
            "example": true,
            "safety_note": "Always verify operational area is clear before deactivating"
          }
        },
        "type": "object",
        "required": [
          "is_active"
        ],
        "title": "EmergencyStopResult",
        "description": "Result data for emergency stop operations."
      },
      "EncoderIdentifiers": {
        "type": "string",
        "enum": [
          "none",
          "roboclaw",
          "qsb",
          "auto"
        ],
        "title": "EncoderIdentifiers"
      },
      "EncoderInfoResponse": {
        "properties": {
          "type": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EncoderIdentifiers"
              },
              {
                "type": "null"
              }
            ],
            "description": "Encoder hardware type identifier.\n        \nSpecifies the type of encoder hardware installed. Null indicates no encoder is installed or type is unknown.\n        ",
            "example": "roboclaw",
            "nullable": true
          }
        },
        "type": "object",
        "title": "EncoderInfoResponse",
        "description": "Encoder type information for system encoders."
      },
      "EncodersInfoResponse": {
        "properties": {
          "cable_position": {
            "$ref": "#/components/schemas/EncoderInfoResponse",
            "description": "Cable position encoder information.\n        \nProvides information about the encoder used for cable position feedback. Required for accurate cable length measurement and positioning operations.\n        "
          },
          "motor_position": {
            "$ref": "#/components/schemas/EncoderInfoResponse",
            "description": "Motor position encoder information.\n        \nProvides information about the encoder installed on the motor shaft for precise motor position feedback. Required for active position hold functionality.\n        "
          }
        },
        "type": "object",
        "required": [
          "cable_position",
          "motor_position"
        ],
        "title": "EncodersInfoResponse",
        "description": "Consolidated encoder information for all system encoders."
      },
      "EthernetConfig": {
        "properties": {
          "host": {
            "type": "string",
            "title": "Host",
            "description": "IP address of the motor controller"
          },
          "port": {
            "type": "integer",
            "title": "Port",
            "description": "Port number"
          },
          "timeout": {
            "type": "number",
            "title": "Timeout",
            "description": "Connection timeout in seconds",
            "default": 5.0
          }
        },
        "type": "object",
        "required": [
          "host",
          "port"
        ],
        "title": "EthernetConfig",
        "description": "Ethernet hardware configuration."
      },
      "ExitSetupResponse": {
        "properties": {
          "success": {
            "type": "boolean",
            "title": "Success",
            "description": "Whether exiting setup mode was successful.\n        \n- **True**: System now in normal operation mode, all endpoints available\n- **False**: Setup mode exit failed, system remains in setup mode\n\n**Success Criteria:**\n- All components must be configured (can_exit_setup = true)\n- Configuration validation must pass\n- Hardware initialization must complete successfully\n        ",
            "example": true
          },
          "message": {
            "type": "string",
            "title": "Message",
            "description": "Status message describing the operation result.\n        \n**Success Messages:**\n- \"Successfully exited setup mode\" - Normal completion\n- \"Already in normal operation mode\" - No action needed\n\n**Error Messages:**\n- Details about why setup mode exit failed\n- Information about remaining configuration requirements\n        ",
            "example": "Successfully exited setup mode",
            "provides": "Human-readable operation result"
          }
        },
        "type": "object",
        "required": [
          "success",
          "message"
        ],
        "title": "ExitSetupResponse",
        "description": "Response from setup mode exit operation.\n\nIndicates whether the system successfully transitioned from setup\nmode to normal operational state.",
        "examples": [
          {
            "description": "Successfully transitioned to normal operation",
            "summary": "Setup Exit Success",
            "value": {
              "message": "Successfully exited setup mode",
              "success": true
            }
          },
          {
            "description": "System was already in normal operation mode",
            "summary": "Already Operational",
            "value": {
              "message": "Already in normal operation mode",
              "success": true
            }
          }
        ]
      },
      "FinishCalibrationRequest": {
        "properties": {
          "pulled_cable_length": {
            "type": "number",
            "exclusiveMinimum": 0.0,
            "title": "Pulled Cable Length",
            "description": "Exact physical distance the cable was extended during calibration in meters.\n        \nThis value determines the accuracy of all future position calculations. Measure to nearest centimeter for optimal accuracy. Typical values: 1 meter (minimum), 5 meters (standard), 10 meters (long/high precision).\n        ",
            "examples": [
              5.0,
              1.0,
              10.0
            ]
          }
        },
        "type": "object",
        "required": [
          "pulled_cable_length"
        ],
        "title": "FinishCalibrationRequest",
        "description": "Request data for completing cable encoder calibration with measured distance.",
        "examples": [
          {
            "description": "Typical 5 meter calibration",
            "name": "Standard Calibration",
            "value": {
              "pulled_cable_length": 5.0
            }
          },
          {
            "description": "1 meter calibration for constrained spaces",
            "name": "Minimum Distance Calibration",
            "value": {
              "pulled_cable_length": 1.0
            }
          },
          {
            "description": "10 meter calibration for maximum accuracy",
            "name": "High Precision Calibration",
            "value": {
              "pulled_cable_length": 10.0
            }
          }
        ]
      },
      "FinishCalibrationResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/FinishCalibrationResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "FinishCalibrationResponse",
        "description": "Response for completing cable encoder calibration with calculated factor.\n\nCalculates and applies new calibration factor based on measured cable extension. System returns to normal operations with improved position accuracy.",
        "examples": [
          {
            "description": "Calibration completed with new factor calculated",
            "name": "Calibration Completed",
            "value": {
              "action": "finish_calibration",
              "error": false,
              "error_msgs": [],
              "result": {
                "calibrating": false,
                "new_factor": 1895
              }
            }
          },
          {
            "description": "Long-distance calibration with high precision factor",
            "name": "High Precision Result",
            "value": {
              "action": "finish_calibration",
              "error": false,
              "error_msgs": [],
              "result": {
                "calibrating": false,
                "new_factor": 2150
              }
            }
          },
          {
            "description": "Cannot complete - no encoder installed",
            "name": "No Encoder",
            "value": {
              "action": "finish_calibration",
              "error": true,
              "error_msgs": [
                "Encoder not installed"
              ],
              "result": {
                "calibrating": false,
                "new_factor": 0
              }
            }
          },
          {
            "description": "Could not calculate valid calibration factor",
            "name": "Calculation Failed",
            "value": {
              "action": "finish_calibration",
              "error": true,
              "error_msgs": [
                "Calibration failed: new factor is 0"
              ],
              "result": {
                "calibrating": false,
                "new_factor": 0
              }
            }
          },
          {
            "description": "Factor calculated but could not be saved",
            "name": "Save Failed",
            "value": {
              "action": "finish_calibration",
              "error": true,
              "error_msgs": [
                "Failed to save calibration factor"
              ],
              "result": {
                "calibrating": true,
                "new_factor": 1895
              }
            }
          }
        ]
      },
      "FinishCalibrationResult": {
        "properties": {
          "calibrating": {
            "type": "boolean",
            "title": "Calibrating",
            "description": "Current calibration status of the cable encoder system.\n        \nIndicates whether the system is actively in calibration mode. Monitor this status via heartbeat `is_cable_counter_calibrating` field. Emergency stop remains functional during calibration.\n        ",
            "example": true,
            "monitoring_field": "is_cable_counter_calibrating"
          },
          "new_factor": {
            "type": "number",
            "title": "New Factor",
            "description": "Newly calculated calibration factor in pulses per meter.\n        \nCalculated as: encoder position change \u00f7 measured cable distance. Used for all future position calculations and automatically saved to system configuration.\n        ",
            "example": 1895,
            "calculation": "encoder_position_change / measured_distance",
            "typical_range": "1500 - 25000",
            "unit": "pulses_per_meter"
          }
        },
        "type": "object",
        "required": [
          "calibrating",
          "new_factor"
        ],
        "title": "FinishCalibrationResult",
        "description": "Result data for calibration completion including new calibration factor."
      },
      "GetCablePositionResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/GetCablePositionResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "GetCablePositionResponse",
        "description": "Response for cable encoder position retrieval operations.\n\nReturns the current cable position from the encoder in meters. Provides real-time cable length information for monitoring and control purposes.",
        "examples": [
          {
            "description": "Current cable position retrieved successfully",
            "name": "Position Retrieved",
            "value": {
              "action": "REEL_GET_ENCODER_COUNT",
              "error": false,
              "error_msgs": [],
              "result": {
                "cable_position": 23.7
              }
            }
          },
          {
            "description": "Cannot get position - encoder not installed",
            "name": "No Encoder Installed",
            "value": {
              "action": "REEL_GET_ENCODER_COUNT",
              "error": true,
              "error_msgs": [
                "Encoder not installed"
              ],
              "result": {
                "cable_position": 0.0
              }
            }
          }
        ]
      },
      "GetCablePositionResult": {
        "properties": {
          "cable_position": {
            "type": "number",
            "title": "Cable Position",
            "description": "Current cable encoder position in meters.\n        \nReal-time position reading from the cable encoder, converted to meters using the active calibration factor. Position is relative to the last established zero point.\n        ",
            "example": 23.7,
            "accuracy": "Depends on encoder calibration quality",
            "unit": "meters"
          }
        },
        "type": "object",
        "required": [
          "cable_position"
        ],
        "title": "GetCablePositionResult",
        "description": "Result data for cable position retrieval operations."
      },
      "GoToRequest": {
        "properties": {
          "target_position": {
            "type": "number",
            "title": "Target Position",
            "description": "Target cable position in meters from the established zero point.\n        \nSpecifies the desired final cable position using the current encoder calibration. Position must be within operational limits defined by maximum cable length and zero point gutter settings.\n        ",
            "example": 25.0,
            "range": "Typically 0 to max_cable_length_meters",
            "reference": "Zero point established by encoder zero operation",
            "unit": "meters"
          },
          "speed": {
            "anyOf": [
              {
                "type": "integer",
                "maximum": 100.0,
                "exclusiveMinimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Speed",
            "description": "Optional speed percentage for positioning operation.\n        \nIf specified, the motor moves to target position at this speed. If None, uses the current motor speed setting. Slower speeds provide more precise positioning but longer operation time.\n        ",
            "example": 50,
            "default_behavior": "Uses current motor speed setting when None",
            "range": "1-100 when specified",
            "unit": "percentage"
          }
        },
        "type": "object",
        "required": [
          "target_position"
        ],
        "title": "GoToRequest",
        "description": "Request data for precision cable positioning operations.",
        "examples": [
          {
            "description": "Move to specific position at default speed",
            "name": "Standard Positioning",
            "value": {
              "target_position": 25.0
            }
          },
          {
            "description": "Move to position with specified low speed",
            "name": "Precision Positioning",
            "value": {
              "speed": 25,
              "target_position": 12.5
            }
          },
          {
            "description": "Return to zero reference point",
            "name": "Zero Position",
            "value": {
              "speed": 50,
              "target_position": 0.0
            }
          }
        ]
      },
      "GoToResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/GoToResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "GoToResponse",
        "description": "Response for cable positioning operations.\n\nProvides position feedback and movement direction for go-to operations. Includes current and target positions with calculated movement direction for monitoring positioning progress.",
        "examples": [
          {
            "description": "Moving to target by winding cable",
            "name": "Go-To Wind Direction",
            "value": {
              "action": "GO_TO_POSITION",
              "error": false,
              "error_msgs": [],
              "result": {
                "current_position": 23.5,
                "reel_direction": "WIND",
                "target_position": 15.0
              }
            }
          },
          {
            "description": "Moving to target by unwinding cable",
            "name": "Go-To Unwind Direction",
            "value": {
              "action": "GO_TO_POSITION",
              "error": false,
              "error_msgs": [],
              "result": {
                "current_position": 23.5,
                "reel_direction": "UNWIND",
                "target_position": 45.0
              }
            }
          },
          {
            "description": "Positioning failed - encoder required",
            "name": "No Encoder Installed",
            "value": {
              "action": "GO_TO_POSITION",
              "error": true,
              "error_msgs": [
                "Encoder not installed"
              ],
              "result": {
                "current_position": 0.0,
                "reel_direction": "STOP",
                "target_position": 30.0
              }
            }
          },
          {
            "description": "Target position exceeds operational limits",
            "name": "Target Out of Bounds",
            "value": {
              "action": "GO_TO_POSITION",
              "error": true,
              "error_msgs": [
                "Target position exceeds maximum cable length - operation not allowed"
              ],
              "result": {
                "current_position": 45.2,
                "reel_direction": "STOP",
                "target_position": 500.0
              }
            }
          }
        ]
      },
      "GoToResult": {
        "properties": {
          "target_position": {
            "type": "number",
            "title": "Target Position",
            "description": "The requested target position in meters.\n        \nConfirms the position target that was specified in the request. Motor will move toward this position using encoder feedback for precise positioning.\n        ",
            "example": 25.0,
            "unit": "meters"
          },
          "current_position": {
            "type": "number",
            "title": "Current Position",
            "description": "Current cable position in meters at operation start.\n        \nPosition reading from encoder at the time the go-to command was initiated. Provides reference point for calculating required movement direction and distance.\n        ",
            "example": 18.3,
            "accuracy": "Depends on encoder calibration quality",
            "unit": "meters"
          },
          "reel_direction": {
            "type": "string",
            "title": "Reel Direction",
            "description": "Determined movement direction to reach target position.\n        \nAutomatically calculated based on current and target positions. WIND moves toward zero (retracts cable), UNWIND moves away from zero (extends cable).\n        ",
            "example": "UNWIND",
            "calculation": "Based on target_position relative to current_position",
            "values": [
              "WIND",
              "UNWIND",
              "STOP"
            ]
          }
        },
        "type": "object",
        "required": [
          "target_position",
          "current_position",
          "reel_direction"
        ],
        "title": "GoToResult",
        "description": "Result data for go-to positioning operations."
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "HealthCheckResponse": {
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "healthy",
              "unhealthy"
            ],
            "title": "Status",
            "description": "Overall system health status.\n        \n- **\"healthy\"**: All systems operational and within normal parameters\n- **\"unhealthy\"**: One or more critical systems experiencing issues\n\n**Dependencies**: Database connectivity and disk space availability\n        ",
            "example": "healthy"
          },
          "database_connection": {
            "type": "string",
            "enum": [
              "ok",
              "failed"
            ],
            "title": "Database Connection",
            "description": "Database connectivity status.\n        \n- **\"ok\"**: Database is accessible and responding normally\n- **\"failed\"**: Unable to establish database connection\n\n**Impact**: Database failure will result in overall unhealthy status\n        ",
            "example": "ok"
          },
          "version": {
            "type": "string",
            "format": "semantic versioning (major.minor.patch)",
            "title": "Version",
            "description": "Current ReelAPI version number",
            "example": "1.1.3"
          },
          "disk_space": {
            "type": "string",
            "enum": [
              "ok",
              "low"
            ],
            "title": "Disk Space",
            "description": "Simple disk space status indicator.\n        \n- **\"ok\"**: Disk utilization under 90% OR more than 8GB free space available\n- **\"low\"**: Disk utilization over 90% AND less than 8GB free space\n\n**Monitoring**: Monitor this field for storage capacity warnings\n        ",
            "example": "ok",
            "threshold": "90% utilization or 8GB free space"
          },
          "raspi_hardware": {
            "$ref": "#/components/schemas/RaspiHardwareStatus",
            "description": "Raspberry Pi 5 hardware diagnostics including temperature and power status"
          }
        },
        "type": "object",
        "required": [
          "status",
          "database_connection",
          "version",
          "disk_space",
          "raspi_hardware"
        ],
        "title": "HealthCheckResponse",
        "description": "Basic system health check response.\n\nProvides essential health status information for quick system monitoring\nand automated health checks.",
        "examples": [
          {
            "description": "All systems operational with normal status",
            "summary": "Healthy System",
            "value": {
              "database_connection": "ok",
              "disk_space": "ok",
              "raspi_hardware": {
                "cpu": {
                  "frequency_mhz": 2400,
                  "is_throttled": false,
                  "max_frequency_mhz": 2400
                },
                "power": {
                  "input_voltage_v": 5.14,
                  "under_voltage_detected": false
                },
                "temperature": {
                  "status": "healthy",
                  "temperature_celsius": 59.7
                }
              },
              "status": "healthy",
              "version": "1.1.3"
            }
          },
          {
            "description": "System with database or disk space issues",
            "summary": "Unhealthy System",
            "value": {
              "database_connection": "failed",
              "disk_space": "low",
              "raspi_hardware": {
                "cpu": {
                  "frequency_mhz": 1000,
                  "is_throttled": true,
                  "max_frequency_mhz": 2400
                },
                "power": {
                  "input_voltage_v": 4.82,
                  "under_voltage_detected": true
                },
                "temperature": {
                  "status": "critical",
                  "temperature_celsius": 81.2
                }
              },
              "status": "unhealthy",
              "version": "1.1.3"
            }
          }
        ]
      },
      "HeartbeatResponse": {
        "properties": {
          "reel_state": {
            "$ref": "#/components/schemas/ReelStateSchema",
            "description": "Complete real-time operational state of the reel system"
          },
          "active_operations": {
            "$ref": "#/components/schemas/ActiveOperationsSchema",
            "description": "\nCurrent active system operations and their detailed status.\n\nContains status information for temporary operations like:\n- **Motor deceleration**: When approaching safety limits or go-to targets\n\nFields are None when the corresponding operation is not active.\n        "
          },
          "plugins": {
            "additionalProperties": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/AmlEnduraChargerStatusSchema"
                },
                {
                  "$ref": "#/components/schemas/DockingPluginStatusSchema"
                },
                {
                  "$ref": "#/components/schemas/PowerSheaveStatusSchema"
                },
                {
                  "additionalProperties": true,
                  "type": "object"
                }
              ]
            },
            "type": "object",
            "title": "Plugins",
            "description": "\nDictionary of plugin status information, keyed by plugin ID.\n\nContains status information for all enabled plugins.\nEach plugin provides its own status structure with fields relevant to that plugin type.\nOnly enabled plugins appear in this dictionary.\n\n**Known Plugin Types**:\n- **aml_endura_charger**: AML Endura 3/6 Charger status\n- **docking**: Docking mechanism status\n- **power_sheave**: Power sheave ethernet motor module\n"
          },
          "timestamp": {
            "type": "string",
            "format": "ISO 8601 with timezone",
            "title": "Timestamp",
            "description": "\nUTC timestamp when the heartbeat data was captured.\n\n**Format**: ISO 8601 datetime string with timezone\n        ",
            "precision": "milliseconds"
          }
        },
        "type": "object",
        "required": [
          "reel_state",
          "timestamp"
        ],
        "title": "HeartbeatResponse",
        "description": "Complete heartbeat response containing system state and timestamp.\n\nThis is the top-level response model for the heartbeat endpoint,\nproviding a timestamped snapshot of the complete reel system state."
      },
      "IgnoreSafeguardViolationsSchema": {
        "properties": {
          "cable_position_below_zero_point": {
            "type": "boolean",
            "title": "Cable Position Below Zero Point",
            "description": "\nWhether to ignore zero point safeguard violations.\n\n- **True**: Operation is allowed to move cable below zero point (e.g., docking)\n- **False**: Normal zero point enforcement applies\n        ",
            "default": false
          },
          "cable_position_exceeds_max_length": {
            "type": "boolean",
            "title": "Cable Position Exceeds Max Length",
            "description": "\nWhether to ignore maximum cable length safeguard violations.\n\n- **True**: Operation is allowed to exceed max cable length\n- **False**: Normal max length enforcement applies\n        ",
            "default": false
          },
          "no_cable_movement_detected": {
            "type": "boolean",
            "title": "No Cable Movement Detected",
            "description": "\nWhether to ignore no-movement detection violations.\n\n- **True**: Operation expects periods without cable movement (e.g., reed switch interactions)\n- **False**: Normal movement detection enforcement applies\n        ",
            "default": false
          }
        },
        "type": "object",
        "title": "IgnoreSafeguardViolationsSchema",
        "description": "Safeguard violations that are ignored during the active operation."
      },
      "JogResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/ReelMotorControlResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "JogResponse",
        "description": "Response for jog motor operations.",
        "examples": [
          {
            "description": "Brief wind jog completed successfully",
            "name": "Jog Wind Complete",
            "value": {
              "action": "JOG_WIND",
              "error": false,
              "error_msgs": [],
              "result": {
                "speed": 100
              }
            }
          },
          {
            "description": "Brief unwind jog completed successfully",
            "name": "Jog Unwind Complete",
            "value": {
              "action": "JOG_UNWIND",
              "error": false,
              "error_msgs": [],
              "result": {
                "speed": 100
              }
            }
          },
          {
            "description": "Jog operation prevented by safety limits",
            "name": "Jog Blocked by Safeguards",
            "value": {
              "action": "JOG_WIND",
              "error": true,
              "error_msgs": [
                "Cable position below zero point - operation not allowed"
              ],
              "result": {
                "speed": 0
              }
            }
          },
          {
            "description": "Jog operation failed - motor driver not responding",
            "name": "Motor Driver Disconnected",
            "value": {
              "action": "JOG_WIND",
              "error": true,
              "error_msgs": [
                "Motor driver not connected"
              ],
              "result": {
                "speed": 0
              }
            }
          }
        ]
      },
      "LoopControlMode": {
        "type": "integer",
        "enum": [
          0,
          1
        ],
        "title": "LoopControlMode"
      },
      "MotorDecelerationSettings": {
        "properties": {
          "trigger_distance_meters": {
            "type": "number",
            "maximum": 10.0,
            "minimum": 0.1,
            "title": "Trigger Distance Meters",
            "description": "Distance from safety limit where deceleration begins in meters.\n        \nControls when the motor starts reducing speed as it approaches safety boundaries. Larger values provide more gradual deceleration but start slowing down earlier.\n        ",
            "example": 1.0,
            "range": "0.1-10.0",
            "typical_values": "0.5-2.0 meters for most applications",
            "unit": "meters"
          },
          "decelerated_speed_percent": {
            "type": "integer",
            "maximum": 95.0,
            "minimum": 5.0,
            "title": "Decelerated Speed Percent",
            "description": "Target speed percentage during deceleration phase.\n        \nMotor speed when approaching safety limits. Lower values provide more conservative approach but may extend operation time. Must be greater than minimum speed.\n        ",
            "example": 25,
            "range": "5-95",
            "relationship": "Must be > minimum_speed_percent",
            "unit": "percentage"
          },
          "minimum_speed_percent": {
            "type": "integer",
            "maximum": 50.0,
            "minimum": 1.0,
            "title": "Minimum Speed Percent",
            "description": "Absolute minimum speed percentage (safety floor).\n        \nLowest speed the motor will operate at during deceleration. Ensures motor maintains enough torque for control while providing maximum safety margin.\n        ",
            "example": 15,
            "purpose": "Prevents motor stall while maintaining control",
            "range": "1-50",
            "unit": "percentage"
          },
          "minimum_trigger_distance": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.01,
            "title": "Minimum Trigger Distance",
            "description": "Minimum trigger distance to prevent false triggers in meters.\n        \nSafety threshold to prevent deceleration activation from minor position fluctuations or encoder noise. Should be smaller than trigger distance.\n        ",
            "example": 0.1,
            "range": "0.01-1.0",
            "relationship": "Must be <= trigger_distance_meters",
            "unit": "meters"
          }
        },
        "type": "object",
        "required": [
          "trigger_distance_meters",
          "decelerated_speed_percent",
          "minimum_speed_percent",
          "minimum_trigger_distance"
        ],
        "title": "MotorDecelerationSettings",
        "description": "Motor deceleration configuration for API requests and responses."
      },
      "MotorDecelerationStatus": {
        "properties": {
          "active": {
            "type": "boolean",
            "title": "Active",
            "description": "Whether motor deceleration is currently active",
            "example": true
          },
          "stage": {
            "type": "string",
            "title": "Stage",
            "description": "Current deceleration stage indicating operational state.\n        \n**Stage Values**:\n- **NORMAL**: No deceleration, full speed operation\n- **DECELERATED**: Speed reduced due to approaching limit/target\n\n**Usage**: Monitor this field to understand current deceleration behavior\n        ",
            "example": "DECELERATED"
          },
          "distance_to_limit": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Distance To Limit",
            "description": "Distance in meters to the safety limit or go-to target triggering deceleration.\n        \n**Context-Dependent Meaning**:\n- **Safety Limits**: Distance to max cable length or zero point boundary\n- **Go-To Operations**: Distance remaining to target position\n- **None**: Distance calculation not available or not applicable\n\n**Monitoring**: Use to gauge proximity to stopping point\n        ",
            "example": 1.2,
            "unit": "meters"
          },
          "original_speed": {
            "anyOf": [
              {
                "type": "integer",
                "maximum": 100.0,
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Original Speed",
            "description": "Original speed percentage before deceleration began.\n        \n**Purpose**: Reference speed that would be used without deceleration\n**Range**: 0-100% when available\n**None**: Original speed not tracked or not applicable\n        ",
            "example": 100
          },
          "current_safe_speed": {
            "anyOf": [
              {
                "type": "integer",
                "maximum": 100.0,
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Current Safe Speed",
            "description": "Current safe speed percentage being applied during deceleration.\n        \n**Behavior**: Actual motor speed when deceleration is active\n**Configuration**: Determined by motor_deceleration.decelerated_speed_percent setting\n**Range**: Typically 5-95% based on system configuration\n        ",
            "example": 25
          },
          "reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reason",
            "description": "Detailed human-readable reason for deceleration activation.\n        \n**Go-To Target Examples**:\n- \"Within 2.0m of go_to_target - reducing to 25%\"\n- \"Approaching go-to position at 15.5m - reducing to 25%\"\n\n**Safety Limit Examples**:\n- \"Within 2.0m of max_tether_length - reducing to 25%\"\n- \"Within 1.5m of zero_point - reducing to 25%\"\n\n**Parsing**: Contains identifiable keywords for programmatic interpretation\n        ",
            "example": "Within 2.0m of go_to_target - reducing to 25%"
          }
        },
        "type": "object",
        "required": [
          "active",
          "stage"
        ],
        "title": "MotorDecelerationStatus",
        "description": "Motor deceleration operation status when active.\n\nProvides detailed information about automatic motor speed reduction\nwhen approaching safety limits or go-to position targets.",
        "examples": [
          {
            "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"
            }
          },
          {
            "description": "Motor deceleration when approaching maximum cable length",
            "summary": "Safety Limit Deceleration",
            "value": {
              "active": true,
              "current_safe_speed": 25,
              "distance_to_limit": 0.8,
              "original_speed": 75,
              "reason": "Within 2.0m of max_tether_length - reducing to 25%",
              "stage": "DECELERATED"
            }
          }
        ]
      },
      "MotorDriverIdentifiers": {
        "type": "string",
        "enum": [
          "roboclaw",
          "motoron",
          "auto",
          "none"
        ],
        "title": "MotorDriverIdentifiers"
      },
      "MotorDriverInfoResponse": {
        "properties": {
          "type": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MotorDriverIdentifiers"
              },
              {
                "type": "null"
              }
            ],
            "description": "Motor driver hardware type identifier.\n        \nSpecifies the type of motor driver hardware installed. Null indicates no motor driver is installed or type is unknown.\n        ",
            "example": "roboclaw",
            "nullable": true
          },
          "version": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "format": "Driver-specific version string",
            "title": "Version",
            "description": "Motor driver firmware or software version.\n        \nProvides specific version information for the installed motor driver. Format depends on the driver type. Null indicates version information is unavailable.\n        ",
            "example": "v4.2.8",
            "nullable": true
          }
        },
        "type": "object",
        "title": "MotorDriverInfoResponse",
        "description": "Motor driver hardware information."
      },
      "MotoronSpeedBoostSettings": {
        "properties": {
          "enabled": {
            "type": "boolean",
            "title": "Enabled",
            "description": "Speed boost feature activation status.\n        \nWhen enabled, allows motor to exceed standard speed limits during specific operations for improved performance. Only available with compatible Motoron motor drivers.\n        ",
            "default": false,
            "example": false,
            "compatibility": "Requires Motoron motor driver hardware"
          },
          "speed_boost_percentage": {
            "type": "integer",
            "maximum": 200.0,
            "minimum": 50.0,
            "title": "Speed Boost Percentage",
            "description": "Speed boost multiplication factor as percentage.\n        \nDefines the maximum speed increase when boost is active. 150% provides 50% speed increase, 200% doubles the speed. Higher values provide faster operation but may affect precision.\n        ",
            "default": 150,
            "example": 150,
            "interpretation": "150% = 50% faster than base speed",
            "range": "50-200",
            "unit": "percentage"
          }
        },
        "type": "object",
        "title": "MotoronSpeedBoostSettings",
        "description": "Motor speed boost configuration for enhanced performance."
      },
      "MotoronStateSchema": {
        "properties": {
          "driver_type": {
            "type": "string",
            "const": "motoron",
            "title": "Driver Type",
            "default": "motoron"
          },
          "input_voltage": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Input Voltage",
            "description": "The input voltage for the motor driver in volts."
          },
          "statuses": {
            "$ref": "#/components/schemas/MotoronStatusSchema",
            "description": "Status flags for the Motoron motor driver."
          }
        },
        "type": "object",
        "title": "MotoronStateSchema",
        "description": "Schema for Motoron motor driver state.",
        "example": {
          "driver_type": "motoron",
          "input_voltage": 12.8,
          "statuses": {
            "error_active": false,
            "motor_driving": false,
            "motor_faulting": false,
            "motor_output_enabled": true,
            "no_power": false,
            "reset": false
          }
        }
      },
      "MotoronStatusSchema": {
        "properties": {
          "reset": {
            "type": "boolean",
            "title": "Reset",
            "description": "Controller was reset.",
            "default": false
          },
          "error_active": {
            "type": "boolean",
            "title": "Error Active",
            "description": "Error is active.",
            "default": false
          },
          "motor_output_enabled": {
            "type": "boolean",
            "title": "Motor Output Enabled",
            "description": "Motor output is enabled.",
            "default": false
          },
          "motor_driving": {
            "type": "boolean",
            "title": "Motor Driving",
            "description": "Motor is currently driving.",
            "default": false
          },
          "no_power": {
            "type": "boolean",
            "title": "No Power",
            "description": "No power to motor driver.",
            "default": false
          },
          "motor_faulting": {
            "type": "boolean",
            "title": "Motor Faulting",
            "description": "Motor fault detected.",
            "default": false
          }
        },
        "type": "object",
        "title": "MotoronStatusSchema",
        "description": "Schema for Motoron-specific status flags.",
        "example": {
          "error_active": false,
          "motor_driving": false,
          "motor_faulting": false,
          "motor_output_enabled": true,
          "no_power": false,
          "reset": false
        }
      },
      "OperationContextSchema": {
        "properties": {
          "operation": {
            "type": "string",
            "title": "Operation",
            "description": "\nName of the active operation.\n\n**Common Values**:\n- \"docking\": Payload docking sequence in progress\n- \"undocking\": Payload undocking sequence in progress\n- \"calibration\": Encoder calibration in progress\n\n**Purpose**: Human-readable identifier for the operation\n        ",
            "examples": [
              "docking",
              "undocking",
              "calibration"
            ]
          },
          "started_at": {
            "type": "number",
            "title": "Started At",
            "description": "\nUnix timestamp when the operation started.\n\n**Format**: Seconds since epoch (Unix timestamp)\n**Purpose**: Track operation duration and detect stale operations\n        ",
            "examples": [
              1731618000.0
            ]
          },
          "blocks_movement": {
            "$ref": "#/components/schemas/BlocksMovementSchema",
            "description": "\nMovement blocking configuration.\n\nDefines which movement directions and command origins are blocked\nwhile this operation is active. UI should disable blocked controls.\n        "
          },
          "ignore_safeguard_violations": {
            "$ref": "#/components/schemas/IgnoreSafeguardViolationsSchema",
            "description": "\nSafeguard violations that are ignored during this operation.\n\nCertain operations (like docking) may need to temporarily bypass\nspecific safety restrictions to complete their task.\n        "
          },
          "suppresses_position_hold": {
            "type": "boolean",
            "title": "Suppresses Position Hold",
            "description": "\nWhether active position hold is suppressed during this operation.\n\n- **True**: Active hold position will not engage during operation\n- **False**: Normal active hold behavior applies\n        ",
            "default": false
          },
          "expects_reed_switch_activity": {
            "type": "boolean",
            "title": "Expects Reed Switch Activity",
            "description": "\nWhether the operation expects reed switch state changes.\n\n- **True**: Reed switch changes are part of normal operation flow\n- **False**: Reed switch changes may indicate unexpected conditions\n\n**Purpose**: Informational flag for system monitoring\n        ",
            "default": false
          },
          "owner": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Owner",
            "description": "\nOwner/source of the operation.\n\n**Possible Values**:\n- \"plugin_docking_mechanism\": Docking plugin owns the operation\n- \"api\": API-initiated operation\n- Other MovementCommandOrigin values\n\n**Purpose**: Identify which subsystem is controlling the operation\n        ",
            "examples": [
              "plugin_docking_mechanism",
              "api"
            ]
          },
          "timeout_seconds": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Timeout Seconds",
            "description": "\nTime-to-live for the operation context in seconds.\n\n- **When set**: Context auto-clears if not refreshed before timeout\n- **None**: No automatic timeout\n\n**Purpose**: Safety mechanism to clear stale operations if owner crashes\n        ",
            "examples": [
              1.0,
              10.0
            ]
          }
        },
        "type": "object",
        "required": [
          "operation",
          "started_at"
        ],
        "title": "OperationContextSchema",
        "description": "Active operation context that modifies system behavior.\n\nWhen an automated operation (like docking) is in progress, this context\ndefines what user commands are blocked and what safety overrides are in effect.",
        "examples": [
          {
            "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.0,
              "suppresses_position_hold": true,
              "timeout_seconds": 1.0
            }
          }
        ]
      },
      "PIDCalibrationResult": {
        "properties": {
          "calibrating": {
            "type": "boolean",
            "title": "Calibrating",
            "description": "Indicates whether the PID controller is currently in calibration mode. True when PID calibration is active and tuning parameters, False when calibration is completed, cancelled, or not running."
          }
        },
        "type": "object",
        "required": [
          "calibrating"
        ],
        "title": "PIDCalibrationResult",
        "description": "PID calibration operation result containing current calibration status",
        "examples": [
          {
            "calibrating": true
          },
          {
            "calibrating": false
          }
        ],
        "operational_notes": [
          "Calibration state is automatically managed by the system",
          "Active calibration includes automated movement and parameter tuning",
          "Completion occurs when optimal gains are found or timeout is reached"
        ]
      },
      "PIDControllerInfoResponse": {
        "properties": {
          "calibrated": {
            "type": "boolean",
            "title": "Calibrated",
            "description": "Indicates whether the PID controller has been successfully calibrated.\n        \nTrue when the controller has completed calibration and parameters are set for optimal position holding performance. False when calibration is required or has not been performed.\n        ",
            "example": true,
            "requirement": "Required for optimal active position hold performance"
          },
          "calibrating": {
            "type": "boolean",
            "title": "Calibrating",
            "description": "Current calibration process status.\n        \nIndicates whether PID calibration is actively in progress. Monitor this field during calibration operations to track completion status.\n        ",
            "example": false,
            "duration": "Typically completes within 45 seconds"
          },
          "calibrated_timestamp": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "format": "ISO 8601 datetime string",
            "title": "Calibrated Timestamp",
            "description": "ISO 8601 timestamp of the last successful PID calibration.\n        \nRecords when calibration was last completed successfully. Null if no calibration has been performed. Useful for maintenance tracking and calibration history.\n        ",
            "example": "2024-09-15T14:30:00Z"
          }
        },
        "type": "object",
        "required": [
          "calibrated",
          "calibrating",
          "calibrated_timestamp"
        ],
        "title": "PIDControllerInfoResponse",
        "description": "Status and calibration information for the PID controller."
      },
      "PluginActionRequest": {
        "properties": {
          "params": {
            "additionalProperties": true,
            "type": "object",
            "title": "Params",
            "description": "Parameters to pass to the action"
          }
        },
        "type": "object",
        "title": "PluginActionRequest",
        "description": "Request schema for executing a plugin action."
      },
      "PluginActionResponse": {
        "properties": {
          "success": {
            "type": "boolean",
            "title": "Success",
            "description": "Whether the action was successful"
          },
          "message": {
            "type": "string",
            "title": "Message",
            "description": "Response message"
          },
          "data": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Data",
            "description": "Action result data"
          }
        },
        "type": "object",
        "required": [
          "success",
          "message"
        ],
        "title": "PluginActionResponse",
        "description": "Response schema for plugin action execution."
      },
      "PluginConfigSchema": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name",
            "description": "Display name of the plugin"
          },
          "version": {
            "type": "string",
            "title": "Version",
            "description": "Plugin version number"
          },
          "description": {
            "type": "string",
            "title": "Description",
            "description": "Plugin description"
          },
          "requirements": {
            "additionalProperties": true,
            "type": "object",
            "title": "Requirements",
            "description": "Hardware requirements"
          },
          "hardware": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Hardware",
            "description": "Hardware configuration"
          },
          "settings": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Settings",
            "description": "Plugin settings"
          }
        },
        "type": "object",
        "required": [
          "name",
          "version",
          "description"
        ],
        "title": "PluginConfigSchema",
        "description": "Schema for plugin configuration data."
      },
      "PluginInfo": {
        "properties": {
          "plugin_id": {
            "type": "string",
            "title": "Plugin Id",
            "description": "Unique identifier for the plugin"
          },
          "name": {
            "type": "string",
            "title": "Name",
            "description": "Display name of the plugin"
          },
          "description": {
            "type": "string",
            "title": "Description",
            "description": "Description of the plugin functionality"
          },
          "version": {
            "type": "string",
            "title": "Version",
            "description": "Plugin version"
          },
          "enabled": {
            "type": "boolean",
            "title": "Enabled",
            "description": "Whether the plugin is currently enabled"
          },
          "requirements": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Requirements",
            "description": "Hardware requirements for the plugin"
          }
        },
        "type": "object",
        "required": [
          "plugin_id",
          "name",
          "description",
          "version",
          "enabled"
        ],
        "title": "PluginInfo",
        "description": "Basic plugin information schema."
      },
      "PluginInfoResponse": {
        "properties": {
          "plugin_id": {
            "type": "string",
            "title": "Plugin Id",
            "description": "Unique identifier for the plugin"
          },
          "enabled": {
            "type": "boolean",
            "title": "Enabled",
            "description": "Whether the plugin is currently enabled"
          },
          "status": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Status",
            "description": "Current plugin status if enabled"
          },
          "config": {
            "$ref": "#/components/schemas/PluginConfigSchema",
            "description": "Complete plugin configuration"
          }
        },
        "type": "object",
        "required": [
          "plugin_id",
          "enabled",
          "config"
        ],
        "title": "PluginInfoResponse",
        "description": "Response schema for detailed plugin information."
      },
      "PluginListResponse": {
        "properties": {
          "plugins": {
            "items": {
              "$ref": "#/components/schemas/PluginInfo"
            },
            "type": "array",
            "title": "Plugins",
            "description": "List of available plugins"
          }
        },
        "type": "object",
        "required": [
          "plugins"
        ],
        "title": "PluginListResponse",
        "description": "Response schema for listing available plugins."
      },
      "PluginResponse": {
        "properties": {
          "success": {
            "type": "boolean",
            "title": "Success",
            "description": "Whether the operation was successful"
          },
          "message": {
            "type": "string",
            "title": "Message",
            "description": "Response message"
          },
          "data": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Data",
            "description": "Additional data if available"
          }
        },
        "type": "object",
        "required": [
          "success",
          "message"
        ],
        "title": "PluginResponse",
        "description": "Standard response for plugin operations."
      },
      "PluginStatusResponse": {
        "properties": {
          "plugin_status": {
            "additionalProperties": true,
            "type": "object",
            "title": "Plugin Status",
            "description": "Status information for enabled plugins"
          }
        },
        "type": "object",
        "required": [
          "plugin_status"
        ],
        "title": "PluginStatusResponse",
        "description": "Response schema for plugin status information."
      },
      "PowerSheaveHardwareUpdate": {
        "properties": {
          "plugin_type": {
            "type": "string",
            "const": "power_sheave",
            "title": "Plugin Type",
            "description": "Plugin identifier for discriminated union",
            "default": "power_sheave"
          },
          "ethernet": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EthernetConfig"
              },
              {
                "type": "null"
              }
            ],
            "description": "Ethernet motor controller configuration"
          }
        },
        "type": "object",
        "title": "PowerSheaveHardwareUpdate",
        "description": "Updateable hardware configuration for Power Sheave plugin."
      },
      "PowerSheaveMotorTelemetry": {
        "properties": {
          "current": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Current",
            "description": "Motor current in amperes",
            "example": 2.5,
            "unit": "amps"
          },
          "voltage": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Voltage",
            "description": "Motor voltage in volts",
            "example": 24.0,
            "unit": "volts"
          },
          "speed": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Speed",
            "description": "Motor speed in meters per second",
            "example": 0.689,
            "unit": "m/s"
          },
          "position": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Position",
            "description": "Motor position in meters",
            "example": 10.5,
            "unit": "meters"
          },
          "encoder_count": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Encoder Count",
            "description": "Raw encoder pulse count",
            "example": 15234
          },
          "temperature": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Temperature",
            "description": "Motor temperature in Celsius",
            "example": 35.2,
            "unit": "\u00b0C"
          },
          "last_update": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Update",
            "description": "Unix timestamp of last telemetry update",
            "example": 1707689123.456
          }
        },
        "type": "object",
        "title": "PowerSheaveMotorTelemetry",
        "description": "Motor telemetry data from the power sheave."
      },
      "PowerSheaveSettingsUpdate": {
        "properties": {
          "plugin_type": {
            "type": "string",
            "const": "power_sheave",
            "title": "Plugin Type",
            "description": "Plugin identifier for discriminated union",
            "default": "power_sheave"
          },
          "speed_differential_percentage": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 100.0,
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Speed Differential Percentage",
            "description": "Speed differential percentage"
          },
          "reverse_direction": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reverse Direction",
            "description": "Whether to reverse motor direction of the power sheave"
          },
          "control_mode": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "open",
                  "closed"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Control Mode",
            "description": "Control mode for the motor"
          },
          "ecd_gain": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Ecd Gain",
            "description": "Encoder Counter to Distance (ECD) gain K_w for converting encoder pulses to distance (x10^-6 m/pulse)",
            "default": 5.5644,
            "example": 5.5644,
            "unit": "x10^-6 m/pulse"
          }
        },
        "type": "object",
        "title": "PowerSheaveSettingsUpdate",
        "description": "Updateable settings for Power Sheave plugin."
      },
      "PowerSheaveStatusSchema": {
        "properties": {
          "enabled": {
            "type": "boolean",
            "title": "Enabled",
            "description": "Whether the power sheave plugin is enabled",
            "example": true
          },
          "motor_connected": {
            "type": "boolean",
            "title": "Motor Connected",
            "description": "Whether the power sheave motor is connected",
            "example": true
          },
          "control_mode": {
            "type": "string",
            "title": "Control Mode",
            "description": "Control mode: 'open' for manual control, 'closed' for auto-sync",
            "examples": [
              "closed",
              "open"
            ]
          },
          "speed_differential_percentage": {
            "type": "number",
            "title": "Speed Differential Percentage",
            "description": "Speed differential percentage for tension control",
            "example": 10.0,
            "unit": "percent"
          },
          "reverse_direction": {
            "type": "boolean",
            "title": "Reverse Direction",
            "description": "Whether motor direction is reversed relative to main reel",
            "example": false
          },
          "telemetry": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PowerSheaveMotorTelemetry"
              },
              {
                "type": "null"
              }
            ],
            "description": "Motor telemetry data (null if motor disconnected or telemetry unavailable)"
          }
        },
        "type": "object",
        "required": [
          "enabled",
          "motor_connected",
          "control_mode",
          "speed_differential_percentage",
          "reverse_direction"
        ],
        "title": "PowerSheaveStatusSchema",
        "description": "Status schema for power sheave plugin heartbeat data.",
        "examples": [
          {
            "description": "Power sheave in closed-loop mode with active telemetry",
            "summary": "Power Sheave Running",
            "value": {
              "control_mode": "closed",
              "enabled": true,
              "motor_connected": true,
              "reverse_direction": false,
              "speed_differential_percentage": 10.0,
              "telemetry": {
                "current": 2.5,
                "encoder_count": 15234,
                "last_update": 1707689123.456,
                "position": 10.5,
                "speed": 0.689,
                "temperature": 35.2,
                "voltage": 24.0
              }
            }
          },
          {
            "description": "Power sheave enabled but motor not connected",
            "summary": "Power Sheave Disconnected",
            "value": {
              "control_mode": "closed",
              "enabled": true,
              "motor_connected": false,
              "reverse_direction": false,
              "speed_differential_percentage": 10.0
            }
          }
        ]
      },
      "PowerStatus": {
        "properties": {
          "input_voltage_v": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Input Voltage V",
            "description": "USB-C input voltage in volts"
          },
          "under_voltage_detected": {
            "type": "boolean",
            "title": "Under Voltage Detected",
            "description": "Under-voltage alarm active"
          }
        },
        "type": "object",
        "required": [
          "under_voltage_detected"
        ],
        "title": "PowerStatus",
        "description": "Power supply status"
      },
      "RaspiHardwareStatus": {
        "properties": {
          "temperature": {
            "$ref": "#/components/schemas/RaspiTempStatus",
            "description": "CPU temperature status and current reading"
          },
          "cpu": {
            "$ref": "#/components/schemas/CpuStatus",
            "description": "CPU current status"
          },
          "power": {
            "$ref": "#/components/schemas/PowerStatus",
            "description": "Power supply voltage and CPU throttle status"
          }
        },
        "type": "object",
        "required": [
          "temperature",
          "cpu",
          "power"
        ],
        "title": "RaspiHardwareStatus"
      },
      "RaspiTempStatus": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "description": "The health of the Raspberry Pi 5 chip temperature.",
            "default": "healthy"
          },
          "temperature_celsius": {
            "type": "number",
            "title": "Temperature Celsius",
            "description": "The current temperature of the Raspberry Pi 5 chip, in Celsius. -9999 is a sentinel values.",
            "default": -9999
          }
        },
        "type": "object",
        "title": "RaspiTempStatus"
      },
      "ReedSwitchInfoResponse": {
        "properties": {
          "role": {
            "$ref": "#/components/schemas/ReedSwitchRole",
            "default": "emergency_stop"
          }
        },
        "type": "object",
        "title": "ReedSwitchInfoResponse"
      },
      "ReedSwitchRole": {
        "type": "string",
        "enum": [
          "emergency_stop",
          "limit_hold",
          "benson_push_push_lock"
        ],
        "title": "ReedSwitchRole"
      },
      "ReedSwitchUpdateSettings": {
        "properties": {
          "role": {
            "$ref": "#/components/schemas/ReedSwitchRole",
            "description": "Reed switch operational role."
          }
        },
        "type": "object",
        "required": [
          "role"
        ],
        "title": "ReedSwitchUpdateSettings",
        "description": "Reed switch configuration for update requests."
      },
      "ReelChassisIdentifiers": {
        "type": "string",
        "enum": [
          "croc_mini",
          "croc_xl",
          "kronos",
          "caiman",
          "user"
        ],
        "title": "ReelChassisIdentifiers"
      },
      "ReelChassisInfoResponse": {
        "properties": {
          "type": {
            "$ref": "#/components/schemas/ReelChassisIdentifiers",
            "description": "Reel chassis hardware type identifier.\n        \nSpecifies the type of reel chassis hardware platform.\n        ",
            "example": "croc_mini",
            "values": [
              "croc_mini",
              "croc_xl",
              "kronos",
              "caiman",
              "user"
            ]
          }
        },
        "type": "object",
        "required": [
          "type"
        ],
        "title": "ReelChassisInfoResponse",
        "description": "Reel chassis hardware information."
      },
      "ReelMotorControlRequest": {
        "properties": {
          "speed": {
            "type": "integer",
            "maximum": 100.0,
            "minimum": 0.0,
            "title": "Speed",
            "description": "Motor speed as percentage of maximum rated speed.\n        \nValid range is 0-100 where 0 stops the motor and 100 provides maximum speed. \nSpeed settings are applied immediately for active operations or stored for subsequent \nmovement commands.\n        ",
            "example": 75,
            "notes": "0 = stopped, 100 = maximum speed",
            "range": "0-100",
            "unit": "percentage"
          }
        },
        "type": "object",
        "required": [
          "speed"
        ],
        "title": "ReelMotorControlRequest",
        "description": "Request data for reel motor control operations (wind, unwind, speed update).",
        "examples": [
          {
            "description": "Full speed motor operation",
            "name": "High Speed Operation",
            "value": {
              "speed": 100
            }
          },
          {
            "description": "Medium speed motor operation",
            "name": "Moderate Speed Operation",
            "value": {
              "speed": 50
            }
          },
          {
            "description": "Slow speed motor operation for precision",
            "name": "Low Speed Operation",
            "value": {
              "speed": 15
            }
          }
        ]
      },
      "ReelMotorControlResult": {
        "properties": {
          "speed": {
            "type": "integer",
            "title": "Speed",
            "description": "Current or target motor speed percentage after operation.\n        \nRepresents the motor speed setting following the requested operation. For stop operations, this will be 0. For speed updates, this reflects the new target speed.\n        ",
            "example": 75,
            "range": "0-100",
            "unit": "percentage"
          }
        },
        "type": "object",
        "required": [
          "speed"
        ],
        "title": "ReelMotorControlResult",
        "description": "Result data for motor control operations."
      },
      "ReelMotorJogRequest": {
        "properties": {
          "direction": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "string"
              }
            ],
            "title": "Direction",
            "description": "Direction for jog operation - accepts integer codes or string names.\n        \nInteger values: 1 = WIND (retract cable), 2 = UNWIND (extend cable)\nString values: \"WIND\" or \"UNWIND\" (case insensitive)\n        ",
            "examples": [
              1,
              2,
              "WIND",
              "UNWIND"
            ],
            "duration": "1/10 second at 100% speed",
            "integer_codes": {
              "1": "WIND",
              "2": "UNWIND"
            }
          }
        },
        "type": "object",
        "required": [
          "direction"
        ],
        "title": "ReelMotorJogRequest",
        "description": "Request data for brief directional motor movements.",
        "examples": [
          {
            "description": "Brief wind movement using integer direction",
            "name": "Jog Wind (Integer)",
            "value": {
              "direction": 1
            }
          },
          {
            "description": "Brief unwind movement using integer direction",
            "name": "Jog Unwind (Integer)",
            "value": {
              "direction": 2
            }
          },
          {
            "description": "Brief wind movement using string direction",
            "name": "Jog Wind (String)",
            "value": {
              "direction": "WIND"
            }
          },
          {
            "description": "Brief unwind movement using string direction",
            "name": "Jog Unwind (String)",
            "value": {
              "direction": "UNWIND"
            }
          }
        ]
      },
      "ReelSettings": {
        "properties": {
          "loop_control_mode": {
            "$ref": "#/components/schemas/LoopControlMode"
          },
          "reel_safeguards_enabled": {
            "type": "boolean",
            "title": "Reel Safeguards Enabled",
            "default": true
          },
          "safeguards": {
            "$ref": "#/components/schemas/SafeguardSettings"
          },
          "max_cable_length_meters": {
            "type": "number",
            "title": "Max Cable Length Meters"
          },
          "zero_point_gutter": {
            "type": "number",
            "title": "Zero Point Gutter"
          },
          "always_enable_remote_control": {
            "type": "boolean",
            "title": "Always Enable Remote Control"
          },
          "active_position_hold_enabled": {
            "type": "boolean",
            "title": "Active Position Hold Enabled"
          },
          "motoron_speed_boost": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MotoronSpeedBoostSettings"
              },
              {
                "type": "null"
              }
            ]
          },
          "motor_deceleration": {
            "$ref": "#/components/schemas/MotorDecelerationSettings"
          },
          "zero_point_reset": {
            "type": "boolean",
            "title": "Zero Point Reset"
          },
          "bypasses": {
            "$ref": "#/components/schemas/BypassSettings"
          }
        },
        "type": "object",
        "required": [
          "loop_control_mode",
          "max_cable_length_meters",
          "zero_point_gutter",
          "always_enable_remote_control",
          "active_position_hold_enabled",
          "motoron_speed_boost",
          "zero_point_reset"
        ],
        "title": "ReelSettings"
      },
      "ReelSettingsResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/ReelSettingsResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "ReelSettingsResponse",
        "description": "Response for reel settings retrieval operations.\n\nReturns comprehensive system configuration including safeguard settings, operational limits, and control modes. Essential for understanding current system behavior and populating configuration interfaces.",
        "examples": [
          {
            "description": "Current reel settings retrieved successfully",
            "name": "Settings Retrieved",
            "value": {
              "action": "GET_REEL_SETTINGS",
              "error": false,
              "error_msgs": [],
              "result": {
                "settings": {
                  "active_position_hold_enabled": true,
                  "always_enable_remote_control": false,
                  "loop_control_mode": 0,
                  "max_cable_length_meters": 300.0,
                  "motor_deceleration": {
                    "decelerated_speed_percent": 25,
                    "minimum_speed_percent": 15,
                    "minimum_trigger_distance": 0.1,
                    "trigger_distance_meters": 1.0
                  },
                  "motoron_speed_boost": {
                    "enabled": false,
                    "speed_boost_percentage": 150
                  },
                  "reel_safeguards_enabled": true,
                  "safeguards": {
                    "max_tether_length_enabled": true,
                    "no_cable_movement_enabled": true,
                    "zero_point_enabled": true
                  },
                  "zero_point_gutter": 0.5
                }
              }
            }
          }
        ]
      },
      "ReelSettingsResult": {
        "properties": {
          "settings": {
            "$ref": "#/components/schemas/ReelSettings",
            "description": "Complete reel system configuration settings.\n        \nContains all user-configurable system parameters including safety controls, operational limits, remote control permissions, and advanced features.\n        "
          }
        },
        "type": "object",
        "required": [
          "settings"
        ],
        "title": "ReelSettingsResult",
        "description": "Result container for reel settings retrieval operations."
      },
      "ReelStateSchema": {
        "properties": {
          "loop_control_mode": {
            "type": "integer",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Loop Control Mode",
            "description": "\nCurrent control loop mode of the reel system.\n\n- **0 (Open Loop)**: Basic speed control without position feedback\n- **1 (Closed Loop)**: Precision position control with encoder feedback\n        ",
            "enum_descriptions": {
              "0": "Open loop - speed control only",
              "1": "Closed loop - position feedback control"
            }
          },
          "cable_position": {
            "type": "number",
            "title": "Cable Position",
            "description": "\nCurrent cable position in meters from the zero reference point.\n        ",
            "precision": "\u00b10.01m typical",
            "unit": "meters",
            "update_rate": "Real-time"
          },
          "cable_position_pulses": {
            "type": "integer",
            "title": "Cable Position Pulses",
            "description": "\nCurrent cable position in raw pulses from the zero reference point.\n        ",
            "unit": "pulses",
            "update_rate": "Real-time"
          },
          "cable_speed_mps": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Cable Speed Mps",
            "description": "\nCurrent cable movement speed in meters per second.\n\n- **Positive**: Cable unwinding (extending from reel)\n- **Negative**: Cable winding (retracting to reel)\n- **Zero**: Cable stationary\n- **None**: Speed measurement unavailable (encoder disconnected)\n        ",
            "availability": "Requires encoder connection",
            "precision": "\u00b10.01 m/s",
            "unit": "meters per second"
          },
          "reel_direction": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "string"
              }
            ],
            "title": "Reel Direction",
            "description": "\nCurrent reel rotation direction.\n\n- **0 or \"STOP\"**: Motor stopped, no movement\n- **1 or \"WIND\"**: Motor winding cable onto reel (retracting)\n- **2 or \"UNWIND\"**: Motor unwinding cable from reel (extending)\n        ",
            "enum_values": {
              "0": "STOP",
              "1": "WIND",
              "2": "UNWIND"
            }
          },
          "speed_percentage": {
            "type": "integer",
            "maximum": 100.0,
            "minimum": 0.0,
            "title": "Speed Percentage",
            "description": "\nCurrent motor speed as percentage of maximum speed.\n\n**Range**: 0-100%\n**Resolution**: 1% increments\n        ",
            "note": "Physical speed depends on reel configuration",
            "unit": "percentage of maximum speed"
          },
          "reel_safeguards_enabled": {
            "type": "boolean",
            "title": "Reel Safeguards Enabled",
            "description": "\nMaster enable/disable state for all reel safety systems.\n\n- **True**: Safety systems active (recommended for normal operation)\n- **False**: Safety systems disabled (use only for maintenance/testing)\n        ",
            "recommendation": "Keep enabled during normal operations",
            "safety_level": "critical"
          },
          "is_remote_active": {
            "type": "boolean",
            "title": "Is Remote Active",
            "description": "\nRemote control (API) activation status.\n\n- **True**: API control enabled, accepts movement commands\n- **False**: API control disabled, commands will be rejected\n\n**Control Sources**: Can be disabled by physical controls or always_enable_remote_control setting.\n**Override**: Set always_enable_remote_control=true to prevent physical control interference.\n        ",
            "control_priority": "Can be overridden by physical controls unless configured otherwise"
          },
          "reed_switch_closed": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reed Switch Closed",
            "description": "\nReed switch sensor status (if installed).\n\n- **True**: Magnetic sensor activated (magnet near sensor)\n- **False**: Magnetic sensor not activated\n- **None**: Reed switch not installed or not configured\n\n**Purpose**: When reed switch is closed, stops the motor and rejects wind commands.\n**Installation**: Sensor mounted on reel, magnet attached to cable/tether.\n        ",
            "hardware_dependency": "Requires reed switch sensor installation",
            "typical_use": "Position detection, attachment sensing"
          },
          "is_encoder_disconnected": {
            "type": "boolean",
            "title": "Is Encoder Disconnected",
            "description": "\nCable position encoder connectivity status.\n\n- **True**: Encoder offline/disconnected (critical issue, or not installed)\n- **False**: Encoder connected and communicating normally\n        ",
            "criticality": "High - affects position accuracy",
            "troubleshooting": [
              "Check encoder wiring",
              "Verify power supply"
            ]
          },
          "is_cable_counter_calibrating": {
            "type": "boolean",
            "title": "Is Cable Counter Calibrating",
            "description": "\nEncoder calibration process status.\n\n- **True**: Calibration in progress (movement commands may be restricted)\n- **False**: Normal operation, calibration complete/inactive\n        ",
            "process_duration": "30-60 seconds typical",
            "restrictions": "Limited movement commands during calibration"
          },
          "motor_driver_unresponsive": {
            "type": "boolean",
            "title": "Motor Driver Unresponsive",
            "description": "\nMotor driver communication status.\n\n- **True**: Driver not responding to commands (critical hardware issue)\n- **False**: Driver communicating normally\n        ",
            "criticality": "Critical - prevents all motor operations"
          },
          "motor_driver_error": {
            "type": "boolean",
            "title": "Motor Driver Error",
            "description": "\nMotor driver error condition indicator.\n\n- **True**: Driver reporting one or more error conditions\n- **False**: Driver operating normally\n\n**Details**: Specific errors listed in motor_driver_error_msgs array.\n**Resolution**: Error-specific troubleshooting required (see error messages).\n        ",
            "details_source": "motor_driver_error_msgs field"
          },
          "motor_driver_error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Motor Driver Error Msgs",
            "description": "\nDetailed motor driver error messages.\n\n**Format**: Human-readable error descriptions\n**Examples**: \"Over temperature\", \"Main voltage low\", \"Motor overcurrent\"\n**Empty Array**: No active errors (normal condition)\n**Multiple Errors**: Array may contain multiple simultaneous error conditions\n        ",
            "example_errors": [
              "Over temperature",
              "Main voltage low",
              "Motor overcurrent"
            ]
          },
          "motor_encoder_position": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Motor Encoder Position",
            "description": "\nRaw motor encoder position in encoder pulses/counts.\n\n**Units**: Encoder-specific pulse counts (not meters)\n**Purpose**: Low-level motor position feedback for diagnostics\n**None**: Motor encoder not installed or not available\n        ",
            "availability": "Requires motor position encoder",
            "purpose": "Motor diagnostics and calibration",
            "unit": "encoder pulses/counts"
          },
          "is_jogging": {
            "type": "boolean",
            "title": "Is Jogging",
            "description": "\nJog operation status.\n\n- **True**: Currently executing a jog command (brief movement)\n- **False**: Normal operation, not jogging\n\n**Jog Operation**: Short duration movement (typically 0.1 seconds) at full speed\n**Purpose**: Fine position adjustments, testing, maintenance operations\n        ",
            "operation_type": "Short duration movement for fine adjustments",
            "typical_duration": "0.1 seconds"
          },
          "is_maintaining_position": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Is Maintaining Position",
            "description": "\nActive hold position engagement status.\n\n- **True**: Active braking engaged, motor maintaining current position against external forces\n- **False**: Active braking disengaged, motor not actively holding position  \n- **None**: Feature disabled or motor encoder not available\n\n**Purpose**: Prevents cable drift due to external forces (wind, payload weight)\n**Requirements**: Requires motor position encoder and active_position_hold_enabled setting\n**Behavior**: Temporarily disengages during user movement commands, re-engages when stopped\n        ",
            "benefit": "Prevents position drift from external forces",
            "feature_name": "Active Hold Position",
            "requirements": [
              "Motor position encoder",
              "active_position_hold_enabled=true"
            ]
          },
          "estop_active": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Estop Active",
            "description": "\nEmergency stop activation status.\n\n- **True**: Emergency stop activated (all movement disabled)\n- **False**: Emergency stop not active (normal operation)\n- **None**: Emergency stop feature not available/configured\n\n**Safety Priority**: Highest priority safety system - overrides all other commands\n**Recovery**: Must be manually deactivated before resuming operations\n        ",
            "recovery": "Manual deactivation required",
            "safety_priority": "Highest - overrides all commands"
          },
          "command_lockout_enabled": {
            "type": "boolean",
            "title": "Command Lockout Enabled",
            "description": "\nMovement command lockout status.\n\n- **True**: All movement commands locked out/disabled\n- **False**: Movement commands accepted normally\n\n**Purpose**: Administrative lock to prevent external movement commands.\n**Scope**: Blocks wind, unwind, go-to-position, jog commands\n**Exception**: Active hold position continues to function when enabled\n        ",
            "purpose": "Administrative movement prevention",
            "scope": "All movement commands except active hold position"
          },
          "safeguard_violations": {
            "$ref": "#/components/schemas/SafeguardViolationsSchema",
            "description": "Status of active safeguard violations. Fields will be None when the corresponding safeguard is disabled."
          },
          "motor_driver": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RoboclawStateSchema"
              },
              {
                "$ref": "#/components/schemas/MotoronStateSchema"
              }
            ],
            "title": "Motor Driver",
            "description": "\nDetailed motor driver state and diagnostic information.\n\nContains driver-specific status information including:\n- **Input voltage and power status**\n- **Temperature and thermal protection status**  \n- **Hardware fault conditions**\n- **Driver-specific error flags and warnings**\n\n**Driver Types**: Roboclaw, Motoron (structure varies by type)\n**Purpose**: Hardware diagnostics and fault detection\n        "
          }
        },
        "type": "object",
        "required": [
          "loop_control_mode",
          "cable_position",
          "cable_position_pulses",
          "reel_direction",
          "speed_percentage",
          "reel_safeguards_enabled",
          "is_remote_active",
          "is_encoder_disconnected",
          "is_cable_counter_calibrating",
          "motor_driver_unresponsive",
          "motor_driver_error",
          "motor_driver_error_msgs",
          "is_jogging",
          "command_lockout_enabled"
        ],
        "title": "ReelStateSchema",
        "description": "Complete operational state of the cable reel system.\n\nThis schema represents the real-time status of all reel subsystems including\nposition, movement, safety systems, and hardware condition. All measurements\nuse SI units unless otherwise specified.",
        "examples": [
          {
            "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.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
            }
          },
          {
            "description": "Reel actively unwinding cable at 75% speed",
            "summary": "Active Unwinding",
            "value": {
              "cable_position": 25.3,
              "cable_position_pulses": 5712,
              "cable_speed_mps": 1.2,
              "command_lockout_enabled": false,
              "estop_active": false,
              "is_cable_counter_calibrating": false,
              "is_encoder_disconnected": false,
              "is_jogging": false,
              "is_maintaining_position": false,
              "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": 253000,
              "reed_switch_closed": false,
              "reel_direction": 2,
              "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": 75
            }
          },
          {
            "description": "System with motor driver error and emergency stop active",
            "summary": "Error Condition",
            "value": {
              "cable_position": 12.1,
              "cable_position_pulses": 0,
              "cable_speed_mps": 0.0,
              "command_lockout_enabled": false,
              "estop_active": true,
              "is_cable_counter_calibrating": false,
              "is_encoder_disconnected": false,
              "is_jogging": false,
              "is_remote_active": false,
              "loop_control_mode": 0,
              "motor_driver": {
                "active_errors": [
                  "Main voltage low",
                  "Temperature warning"
                ],
                "driver_type": "roboclaw",
                "firmware_version": "USB Roboclaw Solo 60A v4.2.8",
                "input_voltage": 22.8,
                "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": true,
                  "position_error_limit_warning": false,
                  "s4_signal_triggered": false,
                  "s5_signal_triggered": false,
                  "speed_error_limit_warning": false,
                  "temp_error": false,
                  "temp_warning": true
                }
              },
              "motor_driver_error": true,
              "motor_driver_error_msgs": [
                "Main voltage low",
                "Temperature warning"
              ],
              "motor_driver_unresponsive": false,
              "motor_encoder_position": 121000,
              "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
            }
          }
        ]
      },
      "ResolutionDetail": {
        "properties": {
          "width": {
            "type": "integer",
            "exclusiveMinimum": 0.0,
            "title": "Width",
            "description": "Frame width in pixels"
          },
          "height": {
            "type": "integer",
            "exclusiveMinimum": 0.0,
            "title": "Height",
            "description": "Frame height in pixels"
          },
          "framerates": {
            "items": {
              "type": "number"
            },
            "type": "array",
            "title": "Framerates",
            "description": "Supported framerates for this resolution"
          }
        },
        "type": "object",
        "required": [
          "width",
          "height",
          "framerates"
        ],
        "title": "ResolutionDetail",
        "description": "Resolution with supported framerates",
        "example": {
          "framerates": [
            15.0,
            30.0
          ],
          "height": 720,
          "width": 1280
        }
      },
      "RoboclawStateSchema": {
        "properties": {
          "driver_type": {
            "type": "string",
            "const": "roboclaw",
            "title": "Driver Type",
            "default": "roboclaw"
          },
          "input_voltage": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Input Voltage",
            "description": "The input voltage for the motor driver in volts."
          },
          "firmware_version": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Firmware Version",
            "description": "Roboclaw firmware version."
          },
          "statuses": {
            "$ref": "#/components/schemas/RoboclawStatusSchema",
            "description": "Status flags for the Roboclaw motor driver."
          },
          "active_errors": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Active Errors",
            "description": "List of active error messages from the Roboclaw."
          }
        },
        "type": "object",
        "title": "RoboclawStateSchema",
        "description": "Schema for Roboclaw motor driver state.",
        "example": {
          "active_errors": [],
          "driver_type": "roboclaw",
          "firmware_version": "4.1.34",
          "input_voltage": 24.3,
          "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
          }
        }
      },
      "RoboclawStatusSchema": {
        "properties": {
          "estop_active": {
            "type": "boolean",
            "title": "Estop Active",
            "description": "Emergency stop is active.",
            "default": false
          },
          "temp_error": {
            "type": "boolean",
            "title": "Temp Error",
            "description": "Temperature error detected.",
            "default": false
          },
          "main_voltage_high": {
            "type": "boolean",
            "title": "Main Voltage High",
            "description": "Main voltage is too high.",
            "default": false
          },
          "logic_voltage_high": {
            "type": "boolean",
            "title": "Logic Voltage High",
            "description": "Logic voltage is too high.",
            "default": false
          },
          "logic_voltage_low": {
            "type": "boolean",
            "title": "Logic Voltage Low",
            "description": "Logic voltage is too low.",
            "default": false
          },
          "m1_driver_fault": {
            "type": "boolean",
            "title": "M1 Driver Fault",
            "description": "Motor 1 driver fault detected.",
            "default": false
          },
          "m1_speed_error": {
            "type": "boolean",
            "title": "M1 Speed Error",
            "description": "Motor 1 speed error detected.",
            "default": false
          },
          "m1_position_error": {
            "type": "boolean",
            "title": "M1 Position Error",
            "description": "Motor 1 position error detected.",
            "default": false
          },
          "m1_current_error": {
            "type": "boolean",
            "title": "M1 Current Error",
            "description": "Motor 1 current error detected.",
            "default": false
          },
          "m1_over_current": {
            "type": "boolean",
            "title": "M1 Over Current",
            "description": "Motor 1 over current detected.",
            "default": false
          },
          "main_voltage_low": {
            "type": "boolean",
            "title": "Main Voltage Low",
            "description": "Main voltage is too low.",
            "default": false
          },
          "temp_warning": {
            "type": "boolean",
            "title": "Temp Warning",
            "description": "Temperature warning detected.",
            "default": false
          },
          "s4_signal_triggered": {
            "type": "boolean",
            "title": "S4 Signal Triggered",
            "description": "S4 signal has been triggered.",
            "default": false
          },
          "s5_signal_triggered": {
            "type": "boolean",
            "title": "S5 Signal Triggered",
            "description": "S5 signal has been triggered.",
            "default": false
          },
          "speed_error_limit_warning": {
            "type": "boolean",
            "title": "Speed Error Limit Warning",
            "description": "Speed error limit warning.",
            "default": false
          },
          "position_error_limit_warning": {
            "type": "boolean",
            "title": "Position Error Limit Warning",
            "description": "Position error limit warning.",
            "default": false
          }
        },
        "type": "object",
        "title": "RoboclawStatusSchema",
        "description": "Schema for Roboclaw-specific status flags.",
        "example": {
          "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
        }
      },
      "SafeguardSettings": {
        "properties": {
          "no_cable_movement_enabled": {
            "type": "boolean",
            "title": "No Cable Movement Enabled",
            "description": "Detection and alerting for cable movement failures.\n        \nWhen enabled, monitors for situations where cable should be moving based on motor commands but encoder readings indicate no movement. Helps detect mechanical failures or obstructions.\n        ",
            "default": true,
            "example": true,
            "detection": "Compares motor commands with encoder feedback"
          },
          "zero_point_enabled": {
            "type": "boolean",
            "title": "Zero Point Enabled",
            "description": "Protection against cable over-retraction past zero point.\n        \nPrevents cable from winding past the established zero point plus gutter distance. Essential for preventing cable damage and maintaining proper reference positioning.\n        ",
            "default": true,
            "example": true,
            "reference": "Uses zero_point_gutter setting for safety margin"
          },
          "max_tether_length_enabled": {
            "type": "boolean",
            "title": "Max Tether Length Enabled",
            "description": "Protection against cable over-extension beyond maximum length.\n        \nPrevents unwinding beyond the configured maximum cable length to protect against cable damage, spool depletion, or operational area violations.\n        ",
            "default": true,
            "example": true,
            "reference": "Uses max_cable_length_meters setting for limit"
          },
          "motor_safe_deceleration_enabled": {
            "type": "boolean",
            "title": "Motor Safe Deceleration Enabled",
            "description": "Automatic motor deceleration when approaching safety limits.\n        \nWhen enabled, gradually reduces motor speed when approaching zero point or maximum tether length limits, or when approaching go-to targets.\n        ",
            "default": true,
            "example": true,
            "behavior": "Gradual speed reduction in stages (75%, 50%, 25%, stop)",
            "benefits": "Reduces mechanical stress and provides smoother operation"
          }
        },
        "type": "object",
        "title": "SafeguardSettings",
        "description": "Individual safeguard control settings for granular safety management."
      },
      "SafeguardViolationsSchema": {
        "properties": {
          "cable_position_below_zero_point": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Cable Position Below Zero Point",
            "description": "\nIndicates if the cable position has gone below the zero point gutter.\n\n- **True**: Cable has wound past the safe zero point (safety violation)\n- **False**: Cable position is within safe winding limits\n- **None**: Zero point safeguard is disabled or not configured\n\n**Action Required**: If True, the reel will stop winding operations to prevent\nover-winding damage. Check zero_point_gutter setting in reel configuration.\n        ",
            "auto_action": "Stop winding operations",
            "safety_level": "critical"
          },
          "cable_position_exceeds_max_length": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Cable Position Exceeds Max Length",
            "description": "\nIndicates if the cable position has exceeded the maximum allowed length.\n\n- **True**: Cable has unwound beyond safe operational limits (safety violation)  \n- **False**: Cable position is within maximum length limits\n- **None**: Maximum length safeguard is disabled\n\n**Action Required**: If True, the reel will stop unwinding operations to prevent\ncable damage or entanglement. Check max_cable_length_meters setting.\n        ",
            "auto_action": "Stop unwinding operations",
            "safety_level": "critical"
          },
          "no_cable_movement_detected": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "No Cable Movement Detected",
            "description": "\nIndicates system expected cable movement but encoder detected none.\n\n- **True**: Motor commanded to move but no cable movement detected (potential jam/failure)\n- **False**: Cable movement matches motor commands (normal operation)\n- **None**: Cable movement detection safeguard is disabled\n        ",
            "safety_level": "warning",
            "troubleshooting": [
              "Check for cable jams",
              "Verify motor coupling",
              "Inspect encoder operation"
            ]
          }
        },
        "type": "object",
        "title": "SafeguardViolationsSchema",
        "description": "Status of active safety system violations.\n\nThese fields indicate whether specific safety safeguards are currently being\nviolated. A value of None means the corresponding safeguard is disabled or\nnot applicable to the current system configuration.",
        "examples": [
          {
            "description": "All safeguards enabled and operating normally",
            "summary": "Normal Operation",
            "value": {
              "cable_position_below_zero_point": false,
              "cable_position_exceeds_max_length": false,
              "no_cable_movement_detected": false
            }
          },
          {
            "description": "Some safeguards disabled in system configuration",
            "summary": "Safeguards Disabled",
            "value": {
              "no_cable_movement_detected": false
            }
          },
          {
            "description": "Cable has exceeded maximum safe length",
            "summary": "Safety Violation",
            "value": {
              "cable_position_below_zero_point": false,
              "cable_position_exceeds_max_length": true,
              "no_cable_movement_detected": false
            }
          }
        ]
      },
      "SetEncoderCountRequest": {
        "properties": {
          "cable_position": {
            "type": "number",
            "title": "Cable Position",
            "description": "Desired cable position in meters.\n        \nSets the encoder reading to this specific value. Can be positive or negative depending on your reference system. Use when the actual cable position is known and differs from current encoder reading.\n        ",
            "example": 15.5,
            "range": "Typically 0 to max_cable_length, but can be negative",
            "unit": "meters"
          }
        },
        "type": "object",
        "required": [
          "cable_position"
        ],
        "title": "SetEncoderCountRequest",
        "description": "Request data for setting cable encoder position to a specific value.",
        "examples": [
          {
            "description": "Set cable position to 15.5 meters",
            "name": "Standard Position",
            "value": {
              "cable_position": 15.5
            }
          },
          {
            "description": "Set cable position to zero",
            "name": "Zero Position",
            "value": {
              "cable_position": 0.0
            }
          },
          {
            "description": "Set cable position to 50 meters",
            "name": "Extended Position",
            "value": {
              "cable_position": 50.0
            }
          }
        ]
      },
      "SetEncoderCountResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/CablePositionOperationResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "SetEncoderCountResponse",
        "description": "Response for cable encoder position setting operations.\n\nSets the cable encoder position to a specified value in meters. Useful for correcting position readings when the actual cable position is known.",
        "examples": [
          {
            "description": "Cable position set to specified value",
            "name": "Position Set",
            "value": {
              "action": "REEL_SET_ENCODER_COUNT",
              "error": false,
              "error_msgs": [],
              "result": {
                "new_position": 15.5
              }
            }
          },
          {
            "description": "Cannot set position - encoder not installed",
            "name": "No Encoder Installed",
            "value": {
              "action": "REEL_SET_ENCODER_COUNT",
              "error": true,
              "error_msgs": [
                "Encoder not installed"
              ],
              "result": {
                "new_position": 0.0
              }
            }
          }
        ]
      },
      "SetupPhase": {
        "type": "string",
        "enum": [
          "component_configuration",
          "hardware_verification",
          "complete"
        ],
        "title": "SetupPhase",
        "description": "Represents the different phases of system setup"
      },
      "SetupStatusDetailed": {
        "properties": {
          "setup_mode_active": {
            "type": "boolean",
            "title": "Setup Mode Active",
            "description": "Whether the system is currently in any setup phase",
            "example": true
          },
          "current_phase": {
            "$ref": "#/components/schemas/SetupPhase",
            "description": "Current setup phase the system is in",
            "example": "hardware_verification"
          },
          "component_configuration_complete": {
            "type": "boolean",
            "title": "Component Configuration Complete",
            "description": "Whether component configuration phase is complete",
            "example": false
          },
          "hardware_verification_complete": {
            "type": "boolean",
            "title": "Hardware Verification Complete",
            "description": "Whether hardware verification phase is complete",
            "example": false
          },
          "unconfigured_components": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Unconfigured Components",
            "description": "List of components that still require manual configuration",
            "example": []
          },
          "configured_components": {
            "items": {
              "$ref": "#/components/schemas/ConfiguredComponent"
            },
            "type": "array",
            "title": "Configured Components",
            "description": "List of components that have been successfully configured"
          },
          "hardware_ready_for_initialization": {
            "type": "boolean",
            "title": "Hardware Ready For Initialization",
            "description": "\nWhether hardware components can be fully initialized.\n\n- **True**: Components configured, ReelManager can create full hardware instances\n- **False**: Component configuration incomplete, limited functionality\n\n**Usage**: Determines if motor/encoder testing is available during verification\n        ",
            "example": true
          },
          "can_exit_setup": {
            "type": "boolean",
            "title": "Can Exit Setup",
            "description": "\nWhether setup mode can be exited (all phases complete).\n\n- **True**: Both component configuration AND hardware verification complete\n- **False**: One or more phases still pending\n\n**Requirements**: component_configuration_complete=True AND hardware_verification_complete=True\n        ",
            "example": false
          }
        },
        "type": "object",
        "required": [
          "setup_mode_active",
          "current_phase",
          "component_configuration_complete",
          "hardware_verification_complete",
          "unconfigured_components",
          "configured_components",
          "hardware_ready_for_initialization",
          "can_exit_setup"
        ],
        "title": "SetupStatusDetailed",
        "description": "Enhanced setup status with phase information",
        "example": {
          "can_exit_setup": false,
          "component_configuration_complete": false,
          "configured_components": [
            {
              "component_id": "physical_control",
              "type": "gpio"
            },
            {
              "component_id": "reed_switch",
              "type": "gpio"
            },
            {
              "component_id": "estop",
              "type": "gpio"
            }
          ],
          "configured_components_count": 3,
          "current_phase": "hardware_verification",
          "hardware_ready_for_initialization": true,
          "hardware_verification_complete": false,
          "setup_mode_active": true,
          "unconfigured_components": [
            "motor_driver",
            "cable_encoder"
          ],
          "unconfigured_components_count": 2
        }
      },
      "SetupStatusSimple": {
        "properties": {
          "setup_mode_active": {
            "type": "boolean",
            "title": "Setup Mode Active",
            "description": "Whether the system is currently in any setup phase",
            "example": true
          },
          "current_phase": {
            "$ref": "#/components/schemas/SetupPhase",
            "description": "Current setup phase the system is in",
            "example": "hardware_verification"
          },
          "component_configuration_complete": {
            "type": "boolean",
            "title": "Component Configuration Complete",
            "description": "Whether component configuration phase is complete",
            "example": false
          },
          "hardware_verification_complete": {
            "type": "boolean",
            "title": "Hardware Verification Complete",
            "description": "Whether hardware verification phase is complete",
            "example": false
          },
          "unconfigured_components": {
            "type": "integer",
            "title": "Unconfigured Components",
            "description": "Number of components that still require manual configuration",
            "example": 2
          },
          "configured_components": {
            "type": "integer",
            "title": "Configured Components",
            "description": "Number of components that have been successfully configured",
            "example": 3
          }
        },
        "type": "object",
        "required": [
          "setup_mode_active",
          "current_phase",
          "component_configuration_complete",
          "hardware_verification_complete",
          "unconfigured_components",
          "configured_components"
        ],
        "title": "SetupStatusSimple",
        "description": "Simplified setup status for discovery and high-level monitoring"
      },
      "SpeedUpdateResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/ReelMotorControlResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "SpeedUpdateResponse",
        "description": "Response for speed update operations.",
        "examples": [
          {
            "description": "Motor speed updated during operation",
            "name": "Speed Updated",
            "value": {
              "action": "UPDATE_SPEED",
              "error": false,
              "error_msgs": [],
              "result": {
                "speed": 90
              }
            }
          },
          {
            "description": "Speed setting stored but motor not currently moving",
            "name": "Speed Update While Stopped",
            "value": {
              "action": "UPDATE_SPEED",
              "error": false,
              "error_msgs": [],
              "result": {
                "speed": 60
              }
            }
          },
          {
            "description": "Speed update failed - motor driver not responding",
            "name": "Motor Driver Disconnected",
            "value": {
              "action": "UPDATE_SPEED",
              "error": true,
              "error_msgs": [
                "Motor driver not connected"
              ],
              "result": {
                "speed": 0
              }
            }
          }
        ]
      },
      "StartCalibrationResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/CalibrationResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "StartCalibrationResponse",
        "description": "Response for starting cable encoder calibration process.\n\nInitiates calibration mode and prepares system for manual measurement. Monitor status via heartbeat `is_cable_counter_calibrating` field.",
        "examples": [
          {
            "description": "Calibration process initiated successfully",
            "name": "Calibration Started",
            "value": {
              "action": "start_calibration",
              "error": false,
              "error_msgs": [],
              "result": {
                "calibrating": true
              }
            }
          },
          {
            "description": "System could not initiate calibration",
            "name": "Calibration Failed",
            "value": {
              "action": "start_calibration",
              "error": true,
              "error_msgs": [
                "Failed to start calibration"
              ],
              "result": {
                "calibrating": false
              }
            }
          },
          {
            "description": "Cannot calibrate - no encoder installed",
            "name": "No Encoder",
            "value": {
              "action": "start_calibration",
              "error": true,
              "error_msgs": [
                "Encoder not installed"
              ],
              "result": {
                "calibrating": false
              }
            }
          }
        ]
      },
      "StartPIDCalibrationResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/PIDCalibrationResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "StartPIDCalibrationResponse",
        "description": "Response from initiating PID controller calibration for active hold position",
        "calibration_process": [
          "Unwind reel at 100% speed for 1 second",
          "Wind reel at 100% speed for 1 second",
          "Oscillate at target position while tuning PID parameters",
          "Complete when ultimate gain found or 45-second timeout"
        ],
        "success_conditions": [
          "Motor position encoder is installed and connected",
          "Active hold position feature is enabled in settings",
          "System is not currently in another calibration mode",
          "Motor control system is operational"
        ]
      },
      "StepRequest": {
        "properties": {
          "result": {
            "additionalProperties": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "boolean"
                }
              ]
            },
            "type": "object",
            "title": "Result"
          }
        },
        "type": "object",
        "required": [
          "result"
        ],
        "title": "StepRequest"
      },
      "StepResponse": {
        "properties": {
          "step_id": {
            "type": "string",
            "title": "Step Id"
          },
          "instructions": {
            "type": "string",
            "title": "Instructions"
          },
          "fields": {
            "additionalProperties": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "boolean"
                }
              ]
            },
            "type": "object",
            "title": "Fields"
          },
          "completed": {
            "type": "boolean",
            "title": "Completed",
            "default": false
          },
          "completed_timestamp": {
            "type": "string",
            "title": "Completed Timestamp"
          }
        },
        "type": "object",
        "required": [
          "step_id",
          "instructions",
          "fields",
          "completed_timestamp"
        ],
        "title": "StepResponse"
      },
      "StopCameraResponse": {
        "properties": {
          "success": {
            "type": "boolean",
            "title": "Success",
            "description": "Whether the stop operation was successful"
          },
          "message": {
            "type": "string",
            "title": "Message",
            "description": "Result message"
          }
        },
        "type": "object",
        "required": [
          "success",
          "message"
        ],
        "title": "StopCameraResponse",
        "description": "Response for POST /camera/stop endpoint",
        "example": {
          "message": "Camera stopped",
          "success": true
        }
      },
      "StopResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/ReelMotorControlResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "StopResponse",
        "description": "Response for stop motor operations.",
        "examples": [
          {
            "description": "Reel motor stopped successfully",
            "name": "Motor Stopped",
            "value": {
              "action": "STOP",
              "error": false,
              "error_msgs": [],
              "result": {
                "speed": 0
              }
            }
          },
          {
            "description": "Motor was already stopped (idempotent operation)",
            "name": "Already Stopped",
            "value": {
              "action": "STOP",
              "error": false,
              "error_msgs": [],
              "result": {
                "speed": 0
              }
            }
          },
          {
            "description": "Motor stop command could not be sent",
            "name": "Stop Command Failed",
            "value": {
              "action": "STOP",
              "error": true,
              "error_msgs": [
                "Failed to stop motor"
              ],
              "result": {
                "speed": 0
              }
            }
          }
        ]
      },
      "SupportedFormat": {
        "properties": {
          "format": {
            "$ref": "#/components/schemas/VideoFormat",
            "description": "Video format identifier"
          },
          "description": {
            "type": "string",
            "title": "Description",
            "description": "Human-readable format description"
          },
          "resolutions": {
            "items": {
              "$ref": "#/components/schemas/ResolutionDetail"
            },
            "type": "array",
            "title": "Resolutions",
            "description": "Supported resolutions for this format"
          }
        },
        "type": "object",
        "required": [
          "format",
          "description",
          "resolutions"
        ],
        "title": "SupportedFormat",
        "description": "Supported camera format with resolutions",
        "example": {
          "description": "Motion-JPEG, compressed",
          "format": "MJPG",
          "resolutions": [
            {
              "framerates": [
                30.0
              ],
              "height": 720,
              "width": 1280
            }
          ]
        }
      },
      "SupportedResolutionsResponse": {
        "properties": {
          "device": {
            "type": "string",
            "title": "Device",
            "description": "Camera device path"
          },
          "supported_resolutions": {
            "items": {
              "$ref": "#/components/schemas/ResolutionDetail"
            },
            "type": "array",
            "title": "Supported Resolutions",
            "description": "List of supported resolutions"
          },
          "source": {
            "type": "string",
            "title": "Source",
            "description": "Source of resolution data (active_camera or v4l2_detection)"
          },
          "current_format": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CameraFormatDetail"
              },
              {
                "type": "null"
              }
            ],
            "description": "Current streaming format"
          },
          "device_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Device Name",
            "description": "Camera device name"
          },
          "supported_formats": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/SupportedFormat"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Supported Formats",
            "description": "All supported formats"
          },
          "best_format": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CameraFormatDetail"
              },
              {
                "type": "null"
              }
            ],
            "description": "Recommended format"
          }
        },
        "type": "object",
        "required": [
          "device",
          "supported_resolutions",
          "source"
        ],
        "title": "SupportedResolutionsResponse",
        "description": "Response for GET /camera/supported-resolutions endpoint",
        "example": {
          "best_format": {
            "format": "MJPG",
            "fps": 30.0,
            "height": 720,
            "width": 1280
          },
          "device": "/dev/video0",
          "device_name": "USB Camera",
          "source": "v4l2_detection",
          "supported_formats": [],
          "supported_resolutions": [
            {
              "framerates": [
                30.0
              ],
              "height": 720,
              "width": 1280
            }
          ]
        }
      },
      "SystemMetadataResponse": {
        "properties": {
          "success": {
            "type": "boolean",
            "title": "Success",
            "description": "Whether the metadata update was successful",
            "example": true
          },
          "updated_fields": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Updated Fields",
            "description": "List of metadata fields that were successfully updated",
            "example": [
              "chassis_type"
            ]
          },
          "message": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Message",
            "description": "Additional information about the update operation",
            "example": "System metadata updated successfully"
          }
        },
        "type": "object",
        "required": [
          "success",
          "updated_fields"
        ],
        "title": "SystemMetadataResponse",
        "description": "Response from system metadata update operation.",
        "examples": [
          {
            "description": "Chassis type updated successfully",
            "summary": "Successful Update",
            "value": {
              "message": "System metadata updated successfully",
              "success": true,
              "updated_fields": [
                "chassis_type"
              ]
            }
          }
        ]
      },
      "SystemMetadataUpdate": {
        "properties": {
          "chassis_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "enum": [
              "croc_mini",
              "croc_xl",
              "kronos",
              "caiman",
              "user"
            ],
            "pattern": "^[a-z_]+$",
            "title": "Chassis Type",
            "description": "Cable reel chassis type identifier.\n        \n**Valid Chassis Types:**\n- **croc_mini** - Compact design for smaller USVs\n- **croc_xl** - Extended capacity model\n- **kronos** - High-performance variant\n- **caiman** - Heavy-duty configuration\n- **user** - Not yet determined/configured\n\n**Usage**: For tracking, support, and maintenance records\n\n**Note**: Setting to 'user' indicates the chassis type has not been determined yet.\nThis allows deferring the chassis type decision while completing other setup steps.\n        ",
            "example": "croc_xl"
          }
        },
        "type": "object",
        "title": "SystemMetadataUpdate",
        "description": "Request model for updating system identification metadata.\n\nThese are non-operational identification fields that can be updated\noutside of setup mode since they don't affect hardware behavior.",
        "examples": [
          {
            "description": "Set chassis type for system identification",
            "summary": "Update Chassis Type",
            "value": {
              "chassis_type": "croc_xl"
            }
          },
          {
            "description": "Mark chassis as not yet determined",
            "summary": "Defer Configuration",
            "value": {
              "chassis_type": "user"
            }
          }
        ]
      },
      "UnwindResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/ReelMotorControlResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "UnwindResponse",
        "description": "Response for unwind motor operations.",
        "examples": [
          {
            "description": "Reel motor unwind operation initiated successfully",
            "name": "Unwind Operation Started",
            "value": {
              "action": "UNWIND",
              "error": false,
              "error_msgs": [],
              "result": {
                "speed": 50
              }
            }
          },
          {
            "description": "Unwind operation stopped by safeguard limit",
            "name": "Maximum Length Reached",
            "value": {
              "action": "UNWIND",
              "error": true,
              "error_msgs": [
                "Cable position exceeds maximum length - operation not allowed"
              ],
              "result": {
                "speed": 0
              }
            }
          },
          {
            "description": "Unwind operation failed - motor driver not responding",
            "name": "Motor Driver Disconnected",
            "value": {
              "action": "UNWIND",
              "error": true,
              "error_msgs": [
                "Motor driver not connected"
              ],
              "result": {
                "speed": 0
              }
            }
          }
        ]
      },
      "UpdatePluginSettingsRequest": {
        "properties": {
          "hardware": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PowerSheaveHardwareUpdate"
              },
              {
                "type": "null"
              }
            ],
            "description": "Hardware configuration updates"
          },
          "settings": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PowerSheaveSettingsUpdate"
              },
              {
                "$ref": "#/components/schemas/DockingSettingsUpdate"
              },
              {
                "type": "null"
              }
            ],
            "title": "Settings",
            "description": "Plugin settings updates"
          }
        },
        "type": "object",
        "title": "UpdatePluginSettingsRequest",
        "description": "Request for updating plugin settings (hardware and/or settings)."
      },
      "UpdatePluginSettingsResponse": {
        "properties": {
          "success": {
            "type": "boolean",
            "title": "Success"
          },
          "message": {
            "type": "string",
            "title": "Message"
          },
          "updated_config": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PluginConfigSchema"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object",
        "required": [
          "success",
          "message"
        ],
        "title": "UpdatePluginSettingsResponse",
        "description": "Response schema for update plugin settings request."
      },
      "UpdateReelInfoRequest": {
        "properties": {
          "serial_number": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Serial Number",
            "description": "New serial number for the reel system.\n        \nOnly system administrators can update this field. Will be ignored if user lacks sys_admin role.\n        ",
            "example": "RWS-2024-001",
            "permission": "sys_admin only"
          },
          "display_name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 100,
                "minLength": 1
              },
              {
                "type": "null"
              }
            ],
            "title": "Display Name",
            "description": "New display name for the reel system.\n        \nAny authenticated user can update this field. Must be between 1-100 characters.\n        ",
            "example": "Smart Winch - Production Line 1",
            "permission": "All authenticated users"
          }
        },
        "type": "object",
        "title": "UpdateReelInfoRequest",
        "description": "Request data for updating reel identification information.",
        "examples": [
          {
            "description": "Any user can update display name",
            "name": "Update Display Name Only",
            "value": {
              "display_name": "Smart Winch - Dock 3"
            }
          },
          {
            "description": "Only sys_admin can update serial number",
            "name": "Update Serial Number Only",
            "value": {
              "serial_number": "RWS-2024-042"
            }
          },
          {
            "description": "Update both fields (requires sys_admin for serial_number)",
            "name": "Update Both Fields",
            "value": {
              "display_name": "Smart Winch - Dock 3",
              "serial_number": "RWS-2024-042"
            }
          }
        ]
      },
      "UpdateReelInfoResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/UpdateReelInfoResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "UpdateReelInfoResponse",
        "description": "Response for reel info update operations.\n\nConfirms successful updates and provides current reel identification state. May include warnings for fields that were ignored due to permission restrictions.",
        "examples": [
          {
            "description": "User updated display name",
            "name": "Display Name Updated Successfully",
            "value": {
              "action": "UPDATE_REEL_INFO",
              "error": false,
              "error_msgs": [],
              "result": {
                "reel_info": {
                  "display_name": "Smart Winch - Dock 3",
                  "serial_number": "UNSET",
                  "uuid": "3f930e75-5672-4275-839b-c6a5cbae454a"
                },
                "warnings": []
              }
            }
          },
          {
            "description": "Non-admin user tried to update serial number",
            "name": "Serial Number Update Denied",
            "value": {
              "action": "UPDATE_REEL_INFO",
              "error": false,
              "error_msgs": [],
              "result": {
                "reel_info": {
                  "display_name": "Smart Winch - Updated",
                  "serial_number": "UNSET",
                  "uuid": "3f930e75-5672-4275-839b-c6a5cbae454a"
                },
                "warnings": [
                  "Serial number update ignored: insufficient permissions (sys_admin required)"
                ]
              }
            }
          },
          {
            "description": "Sys admin updated both fields",
            "name": "Both Fields Updated",
            "value": {
              "action": "UPDATE_REEL_INFO",
              "error": false,
              "error_msgs": [],
              "result": {
                "reel_info": {
                  "display_name": "Smart Winch - Production",
                  "serial_number": "RWS-2024-042",
                  "uuid": "3f930e75-5672-4275-839b-c6a5cbae454a"
                },
                "warnings": []
              }
            }
          }
        ]
      },
      "UpdateReelInfoResult": {
        "properties": {
          "reel_info": {
            "additionalProperties": true,
            "type": "object",
            "title": "Reel Info",
            "description": "Updated reel identification information.\n        \nContains the current state of all reel identification fields after the update operation.\n        "
          },
          "warnings": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Warnings",
            "description": "List of warnings about ignored fields.\n        \nContains messages about fields that were requested but not updated due to insufficient permissions.\n        ",
            "default": []
          }
        },
        "type": "object",
        "required": [
          "reel_info"
        ],
        "title": "UpdateReelInfoResult",
        "description": "Result container for reel info update operations."
      },
      "UpdateReelSettingsRequest": {
        "properties": {
          "reel_safeguards_enabled": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reel Safeguards Enabled",
            "description": "Master control for all reel safety systems.\n        \nWhen True, enables safety monitoring and protection features. When False, disables all safeguards for maintenance or emergency operations. Changes automatically sync with individual safeguard settings.\n        ",
            "example": true,
            "interaction": "Automatically manages individual safeguard states"
          },
          "safeguards": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/SafeguardSettings"
              },
              {
                "type": "null"
              }
            ],
            "description": "Individual safeguard control settings.\n        \nGranular control over specific safety features. Allows selective enabling/disabling of individual protections while maintaining overall safety system coherence.\n        "
          },
          "max_cable_length_meters": {
            "anyOf": [
              {
                "type": "number",
                "exclusiveMinimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Max Cable Length Meters",
            "description": "Maximum allowed cable extension distance in meters.\n        \nDefines the operational limit for cable unwinding to prevent over-extension, cable damage, or operational area violations. Must be positive value greater than zero.\n        ",
            "example": 300.0,
            "constraint": "Must be greater than zero",
            "unit": "meters"
          },
          "zero_point_gutter": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Zero Point Gutter",
            "description": "Safety margin distance from zero point in meters.\n        \nAdditional retraction distance beyond the established zero point where the system will stop winding. Prevents over-retraction and provides operational safety margin.\n        ",
            "example": 0.5,
            "purpose": "Prevents over-retraction beyond zero point",
            "unit": "meters"
          },
          "always_enable_remote_control": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Always Enable Remote Control",
            "description": "Remote control override for physical controls.\n        \nWhen True, prevents physical control interfaces from disabling remote API control. When False, allows physical controls to disable remote operations for safety.\n        ",
            "example": false,
            "safety_note": "False allows physical emergency override"
          },
          "active_position_hold_enabled": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Active Position Hold Enabled",
            "description": "Active motor position holding feature control.\n        \nEnables/disables the system's ability to actively maintain the last stopped position using motor encoder feedback and PID control. Requires motor position encoder installation.\n        ",
            "example": true,
            "requirement": "Requires motor_position_encoder_installed=true"
          },
          "motoron_speed_boost": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MotoronSpeedBoostSettings"
              },
              {
                "type": "null"
              }
            ],
            "description": "Motor speed boost configuration settings.\n        \nControls enhanced speed capabilities for compatible Motoron motor drivers. Allows configuration of speed boost parameters for improved performance when hardware supports it.\n        "
          },
          "motor_deceleration": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MotorDecelerationSettings"
              },
              {
                "type": "null"
              }
            ],
            "description": "Motor deceleration behavior configuration.\n        \nControls how the motor reduces speed when approaching safety limits. Allows fine-tuning of deceleration distances, target speeds, and safety thresholds for optimal operation.\n        ",
            "benefit": "Provides smoother operation and reduces mechanical stress",
            "feature": "Requires motor_safe_deceleration_enabled=true in safeguards"
          },
          "zero_point_reset": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Zero Point Reset",
            "description": "Cable counter position reset configuration.\n\nIf `zero_point_reset` is true, when the reed switch is closed (active) the reel will reset \nthe cable counter position to 0. This is to accommodate cable counter drift or slippage \nduring operation and set the position back to a known quantity.\n        ",
            "example": true,
            "dependency": "Requires reed switch to be configured and functional"
          },
          "bypasses": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BypassSettings"
              },
              {
                "type": "null"
              }
            ],
            "description": "Individual bypass control settings for operational flexibility.\n    \nGranular control over system features that can be bypassed when needed. Allows selective disabling of automatic behaviors while maintaining system functionality for specialized operations or troubleshooting.\n    ",
            "example": {
              "reed_switch_bypassed": false
            },
            "purpose": "Provides operational flexibility for specialized use cases",
            "warning": "Bypassing features may affect automatic position correction"
          },
          "reed_switch": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ReedSwitchUpdateSettings"
              },
              {
                "type": "null"
              }
            ],
            "description": "Reed switch role configuration.\n    \nSets the operational role/behavior of the installed reed switch hardware. Not all systems have reed switches installed.\n    ",
            "example": {
              "role": "emergency_stop"
            },
            "optional": true,
            "values": [
              "emergency_stop",
              "limit_hold",
              "benson_push_push_lock"
            ]
          }
        },
        "type": "object",
        "title": "UpdateReelSettingsRequest",
        "description": "Request data for updating reel system configuration.",
        "examples": [
          {
            "description": "Enable reel safeguards with all individual protections active",
            "name": "Enable All Safeguards",
            "value": {
              "reel_safeguards_enabled": true,
              "safeguards": {
                "max_tether_length_enabled": true,
                "motor_safe_deceleration_enabled": true,
                "no_cable_movement_enabled": true,
                "zero_point_enabled": true
              }
            }
          },
          {
            "description": "Modify maximum cable length and zero point safety gutter",
            "name": "Update Cable Limits",
            "value": {
              "max_cable_length_meters": 250.0,
              "zero_point_gutter": 1.0
            }
          },
          {
            "description": "Allow remote control to override physical controls",
            "name": "Enable Remote Override",
            "value": {
              "always_enable_remote_control": true
            }
          },
          {
            "description": "Enable active position hold with motor speed boost",
            "name": "Configure Active Position Hold",
            "value": {
              "active_position_hold_enabled": true,
              "motoron_speed_boost": {
                "enabled": true,
                "speed_boost_percentage": 175
              }
            }
          },
          {
            "description": "Enable zero point reset and configure reed switch role",
            "name": "Configure Reed Switch Features",
            "value": {
              "bypasses": {
                "reed_switch_bypassed": false
              },
              "reed_switch": "limit_hold",
              "zero_point_reset": true
            }
          },
          {
            "description": "Comprehensive settings update showing all available fields",
            "name": "Complete Configuration Update",
            "value": {
              "active_position_hold_enabled": true,
              "always_enable_remote_control": false,
              "bypasses": {
                "reed_switch_bypassed": false
              },
              "max_cable_length_meters": 300.0,
              "motor_deceleration": {
                "decelerated_speed_percent": 25,
                "minimum_speed_percent": 15,
                "minimum_trigger_distance": 0.1,
                "trigger_distance_meters": 1.0
              },
              "motoron_speed_boost": {
                "enabled": false,
                "speed_boost_percentage": 150
              },
              "reel_safeguards_enabled": true,
              "safeguards": {
                "max_tether_length_enabled": true,
                "motor_safe_deceleration_enabled": true,
                "no_cable_movement_enabled": true,
                "zero_point_enabled": true
              },
              "zero_point_gutter": 0.5,
              "zero_point_reset": true
            }
          }
        ]
      },
      "UpdateReelSettingsResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/UpdateReelSettingsResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "UpdateReelSettingsResponse",
        "description": "Response for reel settings update operations.\n\nConfirms successful application of configuration changes and returns the updated system settings. Includes validation results and current configuration state.",
        "examples": [
          {
            "description": "Reel settings updated successfully",
            "name": "Settings Updated",
            "value": {
              "action": "UPDATE_REEL_SETTINGS",
              "error": false,
              "error_msgs": [],
              "result": {
                "settings": {
                  "active_position_hold_enabled": true,
                  "always_enable_remote_control": true,
                  "loop_control_mode": 0,
                  "max_cable_length_meters": 250.0,
                  "motor_deceleration": {
                    "decelerated_speed_percent": 25,
                    "minimum_speed_percent": 15,
                    "minimum_trigger_distance": 0.1,
                    "trigger_distance_meters": 1.0
                  },
                  "motoron_speed_boost": {
                    "enabled": true,
                    "speed_boost_percentage": 175
                  },
                  "reel_safeguards_enabled": true,
                  "safeguards": {
                    "max_tether_length_enabled": true,
                    "motor_safe_deceleration_enabled": true,
                    "no_cable_movement_enabled": true,
                    "zero_point_enabled": true
                  },
                  "zero_point_gutter": 1.0
                }
              }
            }
          },
          {
            "description": "Invalid settings values provided",
            "name": "Settings Validation Failed",
            "value": {
              "action": "UPDATE_REEL_SETTINGS",
              "error": true,
              "error_msgs": [
                "Invalid speed boost percentage: must be between 50 and 200"
              ],
              "result": {
                "settings": {
                  "active_position_hold_enabled": true,
                  "always_enable_remote_control": false,
                  "loop_control_mode": 0,
                  "max_cable_length_meters": 300.0,
                  "motor_deceleration": {
                    "decelerated_speed_percent": 25,
                    "minimum_speed_percent": 15,
                    "minimum_trigger_distance": 0.1,
                    "trigger_distance_meters": 1.0
                  },
                  "motoron_speed_boost": {
                    "enabled": false,
                    "speed_boost_percentage": 150
                  },
                  "reel_safeguards_enabled": true,
                  "safeguards": {
                    "max_tether_length_enabled": true,
                    "motor_safe_deceleration_enabled": true,
                    "no_cable_movement_enabled": true,
                    "zero_point_enabled": true
                  },
                  "zero_point_gutter": 0.5
                }
              }
            }
          },
          {
            "description": "Settings validation passed but save operation failed",
            "name": "Settings Save Failed",
            "value": {
              "action": "UPDATE_REEL_SETTINGS",
              "error": true,
              "error_msgs": [
                "Failed to update reel settings: Configuration save error"
              ],
              "result": {
                "settings": {
                  "active_position_hold_enabled": true,
                  "always_enable_remote_control": false,
                  "loop_control_mode": 0,
                  "max_cable_length_meters": 300.0,
                  "motoron_speed_boost": {
                    "enabled": false,
                    "speed_boost_percentage": 150
                  },
                  "reel_safeguards_enabled": true,
                  "safeguards": {
                    "max_tether_length_enabled": true,
                    "no_cable_movement_enabled": true,
                    "zero_point_enabled": true
                  },
                  "zero_point_gutter": 0.5
                }
              }
            }
          }
        ]
      },
      "UpdateReelSettingsResult": {
        "properties": {
          "settings": {
            "$ref": "#/components/schemas/ReelSettings",
            "description": "Updated reel system configuration settings.\n        \nReturns the complete configuration after applying requested changes. All settings reflect their current state including any automatic adjustments made during validation.\n        "
          }
        },
        "type": "object",
        "required": [
          "settings"
        ],
        "title": "UpdateReelSettingsResult",
        "description": "Result container for reel settings update operations."
      },
      "UserLoginResponse": {
        "properties": {
          "access_token": {
            "type": "string",
            "format": "JWT token",
            "title": "Access Token",
            "description": "JWT access token for API authentication.\n        \n**Token Usage**: Include in Authorization header as `Bearer <access_token>`\n**Lifespan**: Valid for 24 hours from generation (system configured)\n**Format**: Standard JWT with cryptographic signature\n**Security**: Contains user identification and role information\n\n**Authorization Header Format**:\n```\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\n```\n\n**Token Expiration**: Tokens expire after 1440 minutes\n        ",
            "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJvcGVyYXRvcl8xIiwiZXhwIjoxNjM5NTg0MDAwfQ.signature",
            "expires_in_hours": 24,
            "expires_in_minutes": 1440
          },
          "token_type": {
            "type": "string",
            "enum": [
              "bearer"
            ],
            "title": "Token Type",
            "description": "Authentication token type identifier.\n        \n**Standard Value**: \"bearer\" - indicates Bearer token authentication\n**Usage**: Specifies how to include token in Authorization header\n**OAuth2 Compliance**: Follows OAuth2 Bearer token specification\n        ",
            "example": "bearer",
            "oauth2_standard": "RFC 6750 Bearer Token"
          },
          "user_role": {
            "type": "string",
            "enum": [
              "operator",
              "admin",
              "sys_admin"
            ],
            "title": "User Role",
            "description": "User role for frontend permission handling and UX optimization.\n        \n**Available Roles:**\n- **operator** - Standard reel operation and monitoring permissions\n- **admin** - Full system administration and configuration permissions  \n- **sys_admin** - System administrator with all permissions including serial number updates\n\n**Frontend Usage**: Use this role to show/hide UI elements and provide appropriate user experience\n**Permission Hierarchy**: sys_admin > admin > operator\n**UX Benefit**: Prevents users from seeing controls they cannot use\n        ",
            "example": "operator",
            "frontend_usage": "Control UI element visibility and user experience"
          },
          "username": {
            "type": "string",
            "title": "Username",
            "description": "Username of the authenticated user.\n        \n**Usage**: Display in UI, user identification, logging\n**Security**: Safe to display in frontend interfaces\n**Consistency**: Matches username used for login request\n        ",
            "example": "operator_1",
            "usage": "Display name and user identification"
          }
        },
        "type": "object",
        "required": [
          "access_token",
          "token_type",
          "user_role",
          "username"
        ],
        "title": "UserLoginResponse",
        "description": "Response containing JWT access token and user information for authenticated API access.\n\nProvides the authentication token, type information, and user role needed\nfor subsequent API requests and frontend permission handling.",
        "examples": [
          {
            "description": "Standard operator user authentication",
            "summary": "Operator Login",
            "value": {
              "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJvcGVyYXRvcl8xIiwiZXhwIjoxNjM5NTg0MDAwfQ.signature",
              "token_type": "bearer",
              "user_role": "operator",
              "username": "operator_1"
            }
          },
          {
            "description": "Administrator user authentication",
            "summary": "Admin Login",
            "value": {
              "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbl91c2VyIiwiZXhwIjoxNjM5NTg0MDAwfQ.signature",
              "token_type": "bearer",
              "user_role": "admin",
              "username": "admin_user"
            }
          },
          {
            "description": "System administrator authentication with full permissions",
            "summary": "System Admin Login",
            "value": {
              "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJzeXNfYWRtaW4iLCJleHAiOjE2Mzk1ODQwMDB9.signature",
              "token_type": "bearer",
              "user_role": "sys_admin",
              "username": "sys_admin"
            }
          }
        ]
      },
      "UserRegister": {
        "properties": {
          "username": {
            "type": "string",
            "maxLength": 64,
            "minLength": 6,
            "pattern": "^[a-zA-Z0-9_]+$",
            "title": "Username",
            "description": "Unique username for the new account.\n        \n**Validation Requirements:**\n- **Length**: 6-64 characters (system configured)\n- **Characters**: Alphanumeric and underscores only (a-z, A-Z, 0-9, _)\n- **Format Rules**: Cannot start or end with underscore, no consecutive underscores\n- **Uniqueness**: Must not exist in user database\n- **Pattern**: Must match `^[a-zA-Z0-9_]+$` regex\n\n**Examples:**\n- Valid: `operator_1`, `admin_user`, `monitoring`, `user123`\n- Invalid: `ab` (too short), `_admin` (starts with underscore), `user__name` (consecutive underscores), `user name` (spaces), `user@domain` (special chars), `admin_` (ends with underscore)\n        ",
            "example": "operator_1"
          },
          "password": {
            "type": "string",
            "maxLength": 64,
            "minLength": 6,
            "format": "password",
            "title": "Password",
            "description": "Secure password for account authentication.\n        \n**Security Requirements:**\n- **Minimum Length**: 6 characters (system configured)\n- **Maximum Length**: 64 characters (system configured)\n        ",
            "writeOnly": true,
            "example": "SecurePass123!"
          },
          "user_role": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "enum": [
              "operator",
              "admin"
            ],
            "title": "User Role",
            "description": "Role assignment for access control and permissions.\n        \n**Available Roles:**\n- **operator** (default) - Standard reel operation and monitoring\n- **admin** - Full system administration and configuration\n\n**Role Permissions:**\n- **operator**: Reel control, calibration, settings modification\n- **admin**: All operator permissions plus user management, system configuration\n\n**Default Assignment**: New users receive 'operator' role unless specified\n        ",
            "default": "operator",
            "example": "operator"
          }
        },
        "type": "object",
        "required": [
          "username",
          "password"
        ],
        "title": "UserRegister",
        "description": "User registration request with credential validation.\n\nContains the required information for creating a new user account\nincluding username, password, and role assignment.",
        "examples": [
          {
            "description": "Create new operator account with default permissions",
            "summary": "Standard Operator Account",
            "value": {
              "password": "SecurePass123!",
              "user_role": "operator",
              "username": "operator_1"
            }
          },
          {
            "description": "Create admin account with full system access",
            "summary": "Administrator Account",
            "value": {
              "password": "AdminPass123!",
              "user_role": "admin",
              "username": "admin_user"
            }
          },
          {
            "description": "Create dedicated monitoring account with admin privileges",
            "summary": "Monitoring Account",
            "value": {
              "password": "MonitorPass456!",
              "user_role": "admin",
              "username": "monitor_sys"
            }
          }
        ]
      },
      "UserRegisterResponse": {
        "properties": {
          "username": {
            "type": "string",
            "title": "Username",
            "description": "Username of the successfully created account.\n        \n**Confirmation**: Matches the username provided in registration request\n**Account Status**: Account is immediately active and ready for login\n**Next Steps**: Use this username with provided password to login via `/login`\n        ",
            "example": "operator_1",
            "purpose": "Confirms successful account creation"
          }
        },
        "type": "object",
        "required": [
          "username"
        ],
        "title": "UserRegisterResponse",
        "description": "Response confirming successful user account creation.\n\nReturns the username of the newly created account for confirmation.",
        "examples": [
          {
            "description": "Account created successfully with username confirmation",
            "summary": "Successful Registration",
            "value": {
              "username": "operator_1"
            }
          }
        ]
      },
      "UserRegistrationOpen": {
        "properties": {
          "registration_open": {
            "type": "boolean",
            "title": "Registration Open",
            "description": "Registration availability status.\n        \n- **True**: New user registration is available via `/register` endpoint\n- **False**: Registration is closed, new accounts cannot be created\n\n**Current System Setting**: `API_REGISTRATION_ENABLED = 0`\n**Administrative Control**: Status controlled by `API_REGISTRATION_ENABLED` configuration\n**Security Policy**: Often disabled after initial system setup for enhanced security\n**User Impact**: When false, `/register` endpoint returns 403 Forbidden\n\n**Configuration Notes:**\n- Setting controlled in environment variables or settings file\n- Requires system restart to change registration availability\n- Recommended to disable after initial admin account creation\n        ",
            "example": false,
            "admin_setting": "API_REGISTRATION_ENABLED configuration",
            "current_value": 0,
            "setting_type": "System configuration (requires restart to change)"
          }
        },
        "type": "object",
        "required": [
          "registration_open"
        ],
        "title": "UserRegistrationOpen",
        "description": "System registration availability status.\n\nIndicates whether new user account creation is currently permitted\nbased on system configuration settings.",
        "examples": [
          {
            "description": "Registration status based on current system configuration",
            "summary": "Registration Status (Currently Closed)",
            "value": {
              "registration_open": false
            }
          },
          {
            "description": "New user accounts can be created",
            "summary": "Registration Available",
            "value": {
              "registration_open": true
            }
          },
          {
            "description": "New account creation is disabled",
            "summary": "Registration Closed",
            "value": {
              "registration_open": false
            }
          }
        ]
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "VideoFormat": {
        "type": "string",
        "enum": [
          "MJPG",
          "YUYV",
          "H264",
          "UYVY"
        ],
        "title": "VideoFormat",
        "description": "Supported video formats"
      },
      "WindResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/ReelMotorControlResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "WindResponse",
        "description": "Response for wind motor operations.",
        "examples": [
          {
            "description": "Reel motor wind operation initiated successfully",
            "name": "Wind Operation Started",
            "value": {
              "action": "WIND",
              "error": false,
              "error_msgs": [],
              "result": {
                "speed": 75
              }
            }
          },
          {
            "description": "Wind operation failed - motor driver not responding",
            "name": "Motor Driver Disconnected",
            "value": {
              "action": "WIND",
              "error": true,
              "error_msgs": [
                "Motor driver not connected"
              ],
              "result": {
                "speed": 0
              }
            }
          },
          {
            "description": "Wind operation blocked by active emergency stop",
            "name": "Emergency Stop Active",
            "value": {
              "action": "WIND",
              "error": true,
              "error_msgs": [
                "Emergency stop is active - operation not allowed"
              ],
              "result": {
                "speed": 0
              }
            }
          },
          {
            "description": "Wind operation blocked by command lockout",
            "name": "Command Lockout Active",
            "value": {
              "action": "WIND",
              "error": true,
              "error_msgs": [
                "Movement commands are locked out"
              ],
              "result": {
                "speed": 0
              }
            }
          }
        ]
      },
      "ZeroCablePositionResponse": {
        "properties": {
          "action": {
            "type": "string",
            "title": "Action",
            "description": "The action that was requested or performed by the endpoint"
          },
          "error": {
            "type": "boolean",
            "title": "Error",
            "description": "Indicates whether the operation encountered an error"
          },
          "error_msgs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Error Msgs",
            "description": "List of error messages if the operation failed",
            "default": [],
            "example": []
          },
          "result": {
            "$ref": "#/components/schemas/CablePositionOperationResult",
            "description": "The result data specific to the operation performed"
          }
        },
        "type": "object",
        "required": [
          "action",
          "error",
          "result"
        ],
        "title": "ZeroCablePositionResponse",
        "description": "Response for cable encoder zero operations.\n\nResets the cable encoder position to zero meters at the current cable location. This establishes a new reference point for all subsequent position measurements.",
        "examples": [
          {
            "description": "Cable position successfully reset to zero",
            "name": "Position Zeroed",
            "value": {
              "action": "REEL_ZERO_ENCODER",
              "error": false,
              "error_msgs": [],
              "result": {
                "new_position": 0.0
              }
            }
          },
          {
            "description": "Cannot zero position - encoder not installed",
            "name": "No Encoder Installed",
            "value": {
              "action": "REEL_ZERO_ENCODER",
              "error": true,
              "error_msgs": [
                "Encoder not installed"
              ],
              "result": {
                "new_position": 0.0
              }
            }
          }
        ]
      }
    },
    "securitySchemes": {
      "OAuth2PasswordBearer": {
        "type": "oauth2",
        "flows": {
          "password": {
            "scopes": {},
            "tokenUrl": "v1/login"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "authentication",
      "description": "\n# User Authentication and Authorization\n\n## Overview\n\n**ReelAPI** authentication system provides secure access control through token-based authentication. Users register accounts, authenticate with credentials, and receive JWT tokens for API access.\n\n## Authentication Flow\n\nThe standard authentication process involves three steps:\n\n1. **Check registration status**: Verify if new account creation is available\n2. **Register user account**: Create credentials with username, password, and role assignment\n3. **Authenticate and obtain token**: Login with credentials to receive JWT access token\n\n## Token Usage\n\nAll authenticated endpoints require the JWT token in the Authorization header:\n```\nAuthorization: Bearer <access_token>\n```\n\n"
    },
    {
      "name": "health",
      "description": "\n# System Health and Diagnostics\n\n## Overview\n\n**ReelAPI** health monitoring provides comprehensive system status verification and diagnostic \ncapabilities for operational monitoring and maintenance. These endpoints enable automated \nhealth checks, performance monitoring, and system troubleshooting without requiring authentication.\n\n\n"
    },
    {
      "name": "heartbeat",
      "description": "\n# Real-time System Status Monitoring\n\n## Overview\n\n**ReelAPI** heartbeat operations provide comprehensive real-time visibility into all aspects \nof reel system operation. These endpoints deliver complete system status including motor \noperations, cable position, safety conditions, and hardware health indicators.\n"
    },
    {
      "name": "emergency",
      "description": "\n# Emergency Stop Documentation\n\n## Overview\n\n**ReelAPI** emergency stop system provides immediate motor shutdown capability for safety-critical situations. Emergency stop functionality operates independently of normal reel controls and takes priority over all other motor operations.\n\n## Usage\n\n- Use to immediately halt all reel operations in case of emergencies. \n- Implement as a prominently accessible function in all control interfaces.\n- When active, will block control commands until emergency stop is deactivated.\n- System status shows `estop_active: false` in heartbeat responses\n\n**Important**: If Active Hold Position is enabled, an active emergency stop will block AHP from normal operation.\n\n"
    },
    {
      "name": "cable-position",
      "description": "\n# Cable Position Operations\n\n## Overview\n\n**ReelAPI** cable encoder operations provide precise cable position measurement and control capabilities. The encoder system tracks cable movement and converts mechanical rotation into accurate distance measurements in meters.\n\n## Technical Requirements\n\n- **Encoder installation**: All operations require a properly installed and configured cable encoder\n- **Calibration**: Position accuracy depends on proper encoder calibration (see calibration endpoints)\n"
    },
    {
      "name": "reel-movement",
      "description": "# Reel Motor Control Operations\n\nThe reel movement endpoints provide comprehensive control over cable reel motor operations, enabling \nprecise positioning, speed control, and directional movement. These operations form the core \nfunctionality for automated cable deployment and retrieval systems."
    },
    {
      "name": "cable-calibration",
      "description": "\n# Cable Calibration Documentation\n\n## Overview\n\n**ReelAPI** cable encoder calibration system ensures accurate cable distance measurements by correlating encoder counts with actual cable length. Calibration is typically completed at the factory but may require redoing after factory resets or cable replacement.\n\n## Calibration Process\n\nThe calibration procedure consists of three steps:\n\n1. **Start calibration** - Initialize calibration mode via `/reel/calibration/start` endpoint\n2. **Unwind measured cable** - Use reel controls to pull a known distance (typically 5-10 meters), ensuring cable doesn't bunch up. \n    - **NOTE**:The longer the distance the more accurate the calibration.\n3. **Finish calibration** - Complete process via `/reel/calibration/finish` endpoint with the measured distance\n\n*Note: Manual cable pulling is often not feasible due to physical limitations - use reel controls for unwinding.*\n\n## When Calibration is Required\n\n- After factory reset\n- When cable is replaced\n- If distance measurements appear inaccurate\n\n## Technical Details\n\n- **Calibration factors**: Factors are pulses per meter\n- **Safety**: Emergency stop remains functional throughout calibration\n- **Monitoring**: Check `is_cable_counter_calibrating` field in heartbeat responses\n"
    },
    {
      "name": "pid-calibration",
      "description": "\n# PID Controller Calibration for Active Hold Position\n\n## Overview\n\n**ReelAPI** PID controller calibration optimizes motor position control for the active hold position feature. \nThis automated process tunes the controller parameters to maintain precise motor positioning when active hold is enabled.\n\n## Calibration Process\n\nThe automated calibration oscillates at position while tuning PID paramaters. The reel will unwind/wind a few degrees during this process.\n\n## Prerequisites\n\n- Motor position encoder must be installed\n- Active hold position feature must be enabled in settings\n- Minimum 1 meter of unwound cable recommended for safe operation\n\n## Technical Details\n\n- **Timeout protection**: 45-second maximum calibration time\n- **Safety**: Calibration can be cancelled at any time\n- **Parameter preservation**: Existing settings retained if calibration is cancelled or timeout is exceeded\n"
    },
    {
      "name": "settings",
      "description": "\n# Reel Settings and System Information\n\n## Overview\n\n**ReelAPI** settings operations provide comprehensive control over reel system configuration and access to \nhardware information. These endpoints manage safety parameters, operational limits, remote control \npermissions, and advanced features while providing static system specifications.\n"
    },
    {
      "name": "camera",
      "description": "\n# USB Camera Management and Streaming\n\n## Overview\n\n**ReelAPI** camera operations provide comprehensive USB camera management for visual monitoring and \nremote observation. The system supports automatic camera detection, live video streaming, and \ncomplete device capability management through v4l2 interface integration.\n"
    },
    {
      "name": "utility",
      "description": "\n# System Utilities and Log Management\n\n## Overview\n\n**ReelAPI** utility operations provide essential system administration capabilities including \nlog file management, system diagnostics, and maintenance tools. These endpoints support \noperational visibility and troubleshooting for technical support.\n"
    },
    {
      "name": "v1",
      "description": "\n# ReelAPI Version 1\n\n**ReelAPI v1** encompasses all current API endpoints and serves as the comprehensive version identifier for the complete cable reel control system. This version tag provides future-proofing capabilities for potential API evolution, ensuring backward compatibility and clear versioning when additional API versions may be introduced. All endpoints within this version maintain consistent authentication, response formats, and operational behaviors across the entire ReelAPI system.\n"
    }
  ]
}