px4-configuration 0.1.0__py3-none-any.whl

px4_configuration/__init__.py

@@ -0,0 +1,15 @@
+"""PX4 Configuration package."""
+
+__all__ = ["api"]
+
+
+def __getattr__(name):
+    if name == "__version__":
+        from importlib.metadata import version, PackageNotFoundError
+
+        try:
+            return version("px4-configuration")
+        except PackageNotFoundError:
+            return "0.0.0"
+    raise AttributeError(name)
+

px4_configuration/api/__init__.py

@@ -0,0 +1,11 @@
+"""PX4 Configuration REST API package."""
+
+__all__ = [
+    "config",
+    "models",
+    "services",
+    "main",
+]
+
+__version__ = "1.0.0"
+

px4_configuration/api/config.py

@@ -0,0 +1,22 @@
+"""Configuration settings for the PX4 Configuration API."""
+
+import os
+
+
+class Settings:
+    """Application settings with defaults."""
+
+    # Default serial connection settings
+    default_port: str = os.getenv("PX4_DEFAULT_PORT", "/dev/pixhawk")
+    default_baudrate: int = int(os.getenv("PX4_DEFAULT_BAUDRATE", "2000000"))
+
+    # API settings
+    api_title: str = "PX4 Configuration API"
+    api_version: str = "1.0.0"
+    api_description: str = (
+        "REST API for configuring PX4 flight controller from companion computer"
+    )
+
+
+settings = Settings()
+

px4_configuration/api/main.py

@@ -0,0 +1,262 @@
+"""FastAPI application for PX4 configuration API."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import tempfile
+from typing import Optional
+
+from fastapi import (
+    FastAPI,
+    File,
+    HTTPException,
+    Query,
+    UploadFile,
+    WebSocket,
+    WebSocketDisconnect,
+)
+from fastapi.middleware.cors import CORSMiddleware
+from sse_starlette.sse import EventSourceResponse
+
+from .config import settings
+from .models import CalibrationRequest, Px4HealthResponse
+from .services.calibration_service import calibrate_sensors
+from .services.param_service import upload_parameters
+from .services.sdcard_service import upload_to_sdcard
+from .services.shell_service import ShellConnection
+from .services.health_service import read_px4_health
+
+app = FastAPI(
+    title=settings.api_title,
+    version=settings.api_version,
+    description=settings.api_description,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+active_shell_connections: dict[str, ShellConnection] = {}
+
+
+@app.get("/api/px4/health", response_model=Px4HealthResponse)
+async def get_px4_health(
+    port: Optional[str] = Query(None),
+    baudrate: Optional[int] = Query(None),
+):
+    """Return a PX4 health snapshot (one-shot JSON)."""
+
+    port = port or settings.default_port
+    baudrate = baudrate or settings.default_baudrate
+
+    return await read_px4_health(port=port, baudrate=baudrate)
+
+@app.post("/api/calibration/start")
+async def start_calibration(request: CalibrationRequest):
+    port = request.port or settings.default_port
+    baudrate = request.baudrate or settings.default_baudrate
+
+    async def event_generator():
+        try:
+            async for payload in calibrate_sensors(
+                port=port,
+                baudrate=baudrate,
+                calibration_type=request.calibration_type,  # <-- enum here
+            ):
+                # Convert dict -> SSE frame
+                yield f"data: {json.dumps(payload)}\n\n"
+        except Exception as exc:
+            yield f"data: {json.dumps({'type': 'error', 'message': str(exc)})}\n\n"
+        finally:
+            yield f"data: {json.dumps({'type': 'complete'})}\n\n"
+
+    return EventSourceResponse(event_generator())
+
+
+@app.post("/api/params/upload")
+async def upload_params(
+    file: UploadFile = File(...),
+    port: Optional[str] = Query(None, description="Serial port (default: /dev/pixhawk)"),
+    baudrate: Optional[int] = Query(None, description="Serial baudrate (default: 2000000)"),
+):
+    """Upload parameters from a `.params` file and stream progress."""
+
+    port = port or settings.default_port
+    baudrate = baudrate or settings.default_baudrate
+
+    with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix=".params") as tmp_file:
+        content = await file.read()
+        tmp_file.write(content.decode("utf-8"))
+        tmp_file_path = tmp_file.name
+
+    async def event_generator():
+        try:
+            async for message in upload_parameters(
+                param_file_path=tmp_file_path,
+                port=port,
+                baudrate=baudrate,
+            ):
+                yield message
+        except Exception as exc:  # pragma: no cover
+            yield f'data: {json.dumps({"type": "error", "message": str(exc)})}\n\n'
+        finally:
+            yield f'data: {json.dumps({"type": "complete"})}\n\n'
+            try:
+                os.unlink(tmp_file_path)
+            except OSError:
+                pass
+
+    return EventSourceResponse(event_generator())
+
+
+@app.post("/api/sdcard/upload")
+async def upload_sdcard_file(
+    file: UploadFile = File(...),
+    port: Optional[str] = Query(None, description="Serial port (default: /dev/pixhawk)"),
+    baudrate: Optional[int] = Query(None, description="Serial baudrate (default: 2000000)"),
+):
+    """Upload a file (e.g. extras.txt) to the PX4 SD card."""
+
+    port = port or settings.default_port
+    baudrate = baudrate or settings.default_baudrate
+
+    with tempfile.NamedTemporaryFile(mode="w", delete=False) as tmp_file:
+        content = await file.read()
+        tmp_file.write(content.decode("utf-8"))
+        tmp_file_path = tmp_file.name
+
+    async def event_generator():
+        try:
+            async for message in upload_to_sdcard(
+                file_path=tmp_file_path,
+                port=port,
+                baudrate=baudrate,
+            ):
+                yield message
+        except Exception as exc:  # pragma: no cover
+            yield f'data: {json.dumps({"type": "error", "message": str(exc)})}\n\n'
+        finally:
+            yield f'data: {json.dumps({"type": "complete"})}\n\n'
+            try:
+                os.unlink(tmp_file_path)
+            except OSError:
+                pass
+
+    return EventSourceResponse(event_generator())
+
+
+@app.websocket("/api/shell/connect")
+async def shell_websocket(
+    websocket: WebSocket,
+    port: Optional[str] = Query(None, description="Serial port (default: /dev/pixhawk)"),
+    baudrate: Optional[int] = Query(None, description="Serial baudrate (default: 2000000)"),
+):
+    """WebSocket endpoint for interactive PX4 shell access."""
+
+    await websocket.accept()
+
+    port = port or settings.default_port
+    baudrate = baudrate or settings.default_baudrate
+
+    connection_id = f"{port}:{baudrate}"
+    shell_conn = None
+
+    try:
+        shell_conn = ShellConnection(port=port, baudrate=baudrate)
+        active_shell_connections[connection_id] = shell_conn
+        await shell_conn.connect()
+
+        await websocket.send_text("Connected to PX4 shell. Type commands and press Enter.\n")
+
+        async def send_output():
+            try:
+                while shell_conn.connected:
+                    output = await shell_conn.receive_output()
+                    if output:
+                        await websocket.send_text(output)
+                    await asyncio.sleep(0.05)
+            except asyncio.CancelledError:  # pragma: no cover
+                pass
+            except Exception as exc:  # pragma: no cover
+                try:
+                    await websocket.send_text(f"Error receiving output: {exc}\n")
+                except Exception:
+                    pass
+
+        output_task = asyncio.create_task(send_output())
+
+        while True:
+            try:
+                command = await websocket.receive_text()
+                if command.strip():
+                    await shell_conn.send_command(command)
+            except WebSocketDisconnect:
+                break
+            except Exception as exc:
+                await websocket.send_text(f"Error: {exc}\n")
+
+        output_task.cancel()
+
+    except Exception as exc:  # pragma: no cover
+        await websocket.send_text(f"Connection error: {exc}\n")
+    finally:
+        if shell_conn:
+            await shell_conn.disconnect()
+        if connection_id in active_shell_connections:
+            del active_shell_connections[connection_id]
+        try:
+            await websocket.close()
+        except Exception:
+            pass
+
+
+def run(host: str = "0.0.0.0", port: int = 8000, reload: bool = False, log_level: str = "info") -> None:
+    """Run the FastAPI application using Uvicorn."""
+
+    import uvicorn
+
+    uvicorn.run(
+        "px4_configuration.api.main:app",
+        host=host,
+        port=port,
+        reload=reload,
+        log_level=log_level,
+    )
+
+
+def main() -> None:
+    """Console script entry point for running the API server."""
+
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="px4-config-api",
+        description="Run the PX4 Configuration REST API server",
+    )
+    parser.add_argument("--host", default="0.0.0.0", help="Bind address (default: 0.0.0.0)")
+    parser.add_argument("--port", type=int, default=8000, help="Listen port (default: 8000)")
+    parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="Enable auto-reload (development only)",
+    )
+    parser.add_argument(
+        "--log-level",
+        default="info",
+        choices=["critical", "error", "warning", "info", "debug", "trace"],
+        help="Set Uvicorn log level (default: info)",
+    )
+
+    args = parser.parse_args()
+    run(host=args.host, port=args.port, reload=args.reload, log_level=args.log_level)
+
+
+if __name__ == "__main__":
+    main()
+

px4_configuration/api/models.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Literal, Optional, Dict, Any
+
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class CalibrationType(StrEnum):
+    """Supported calibration types."""
+    GYROSCOPE = "gyroscope"
+    ACCELEROMETER = "accelerometer"
+    MAGNETOMETER = "magnetometer"
+    HORIZON = "horizon"
+    ESC = "esc"
+
+
+class CalibrationRequest(BaseModel):
+    """Request model for calibration operations.
+
+    Exactly one calibration type is selected via `calibration_type`.
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "calibration_type": "accelerometer",
+                "port": "/dev/pixhawk",
+                "baudrate": 2_000_000,
+            }
+        }
+    )
+
+    calibration_type: CalibrationType = Field(
+        description=(
+            "Which calibration to run. "
+            "One of: gyroscope, accelerometer, magnetometer, horizon, esc."
+        )
+    )
+    port: str = Field(
+        default="/dev/pixhawk",
+        description="Serial port device.",
+    )
+    baudrate: int = Field(
+        default=2_000_000,
+        description="Serial baudrate (must be positive).",
+        ge=1,
+    )
+
+class CalibrationHealth(BaseModel):
+    """Calibration health response."""
+
+    gyroscope_ok: bool = Field(..., description="Whether the gyroscope is calibrated.")
+    accelerometer_ok: bool = Field(..., description="Whether the accelerometer is calibrated.")
+    magnetometer_ok: bool = Field(..., description="Whether the magnetometer is calibrated.")
+
+    @property
+    def requires_calibration(self) -> bool:
+        """Whether the calibration is required."""
+        return not (self.gyroscope_ok and self.accelerometer_ok and self.magnetometer_ok)
+
+class Px4HealthResponse(BaseModel):
+    """
+    High-level PX4 health snapshot.
+
+    Combines:
+    - overall status (ok / degraded / disconnected)
+    - connection information
+    - calibration health (if available)
+    - GPS fix/used satellites
+    - armable flag
+    - optional raw health flags for debugging/advanced UI
+    """
+
+    status: Literal["ok", "degraded", "disconnected"] = Field(
+        ...,
+        description="High-level PX4 health status derived from telemetry.",
+    )
+    connection_port: str = Field(
+        ...,
+        description="Serial port used to reach the PX4 autopilot.",
+    )
+    connection_baudrate: int = Field(
+        ...,
+        description="Baudrate used on the serial link to PX4.",
+    )
+
+    calibration: Optional[CalibrationHealth] = Field(
+        default=None,
+        description="Sensor calibration health, if telemetry health was received.",
+    )
+
+    gps_fix_type: Optional[str] = Field(
+        default=None,
+        description=(
+            "GPS fix type as a lowercase string (e.g. 'no_fix', '2d_fix', '3d_fix', "
+            "'rtk_float', 'rtk_fix'), if GPS info is available."
+        ),
+    )
+    satellites_used: Optional[int] = Field(
+        default=None,
+        ge=0,
+        description=(
+            "Number of satellites currently used for the positioning solution, "
+            "if GPS info is available."
+        ),
+    )
+
+    armable: Optional[bool] = Field(
+        default=None,
+        description="True if PX4 considers the vehicle armable.",
+    )
+
+    raw_health: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description=(
+            "Optional low-level health flags directly from MAVSDK telemetry.health(), "
+            "for debugging or advanced UI use."
+        ),
+    )

px4_configuration/api/services/__init__.py

@@ -0,0 +1,9 @@
+"""Service modules for PX4 configuration operations."""
+
+__all__ = [
+    "calibration_service",
+    "param_service",
+    "sdcard_service",
+    "shell_service",
+]
+

px4_configuration/api/services/calibration_service.py

@@ -0,0 +1,136 @@
+"""Service for PX4 sensor calibration operations."""
+
+from __future__ import annotations
+
+from typing import AsyncGenerator, Dict, Any
+
+from mavsdk import System
+
+from ..models import CalibrationType
+from ..utils.calibration_parser import (
+    parse_accelerometer_progress,
+    parse_gyroscope_progress,
+    parse_magnetometer_progress,
+    parse_horizon_progress,
+)
+
+
+async def calibrate_sensors(
+    port: str,
+    baudrate: int,
+    calibration_type: CalibrationType,
+) -> AsyncGenerator[Dict[str, Any], None]:
+    """
+    Calibrate PX4 sensors and stream progress as structured dict payloads.
+
+    This function is transport-agnostic: it does NOT produce SSE-formatted strings.
+    It yields plain Python dicts suitable for JSON serialization. The API layer
+    (FastAPI endpoint) is responsible for converting these dicts into SSE frames.
+    """
+
+    serial = f"serial://{port}:{baudrate}"
+    drone = System()
+
+    # Initial status messages
+    yield {
+        "type": "status",
+        "message": f"Connecting to {port}...",
+    }
+
+    # Connect to the PX4 system
+    await drone.connect(system_address=serial)
+
+    yield {
+        "type": "status",
+        "message": "Connected to device",
+    }
+
+    # Dispatch based on calibration type
+    if calibration_type is CalibrationType.GYROSCOPE:
+        # Gyroscope calibration
+        yield {
+            "type": "status",
+            "message": "Starting gyroscope calibration...",
+        }
+
+        async for progress_data in drone.calibration.calibrate_gyro():
+            structured_data = parse_gyroscope_progress(progress_data)
+            yield structured_data
+
+        yield {
+            "type": "gyroscope_complete",
+            "message": "Gyroscope calibration finished",
+            "is_complete": True,
+        }
+
+    elif calibration_type is CalibrationType.ACCELEROMETER:
+        # Accelerometer calibration
+        yield {
+            "type": "status",
+            "message": "Starting accelerometer calibration...",
+        }
+
+        async for progress_data in drone.calibration.calibrate_accelerometer():
+            structured_data = parse_accelerometer_progress(progress_data)
+            yield structured_data
+
+        yield {
+            "type": "accelerometer_complete",
+            "message": "Accelerometer calibration finished",
+            "is_complete": True,
+        }
+
+    elif calibration_type is CalibrationType.MAGNETOMETER:
+        # Magnetometer calibration
+        yield {
+            "type": "status",
+            "message": "Starting magnetometer calibration...",
+        }
+
+        async for progress_data in drone.calibration.calibrate_magnetometer():
+            structured_data = parse_magnetometer_progress(progress_data)
+            yield structured_data
+
+        yield {
+            "type": "magnetometer_complete",
+            "message": "Magnetometer calibration finished",
+            "is_complete": True,
+        }
+
+    elif calibration_type is CalibrationType.HORIZON:
+        # Level horizon calibration
+        yield {
+            "type": "status",
+            "message": "Starting board level horizon calibration...",
+        }
+
+        async for progress_data in drone.calibration.calibrate_level_horizon():
+            structured_data = parse_horizon_progress(progress_data)
+            yield structured_data
+
+        yield {
+            "type": "horizon_complete",
+            "message": "Level horizon calibration finished",
+            "is_complete": True,
+        }
+
+    elif calibration_type is CalibrationType.ESC:
+        # ESC calibration not implemented yet
+        yield {
+            "type": "status",
+            "message": "Starting ESC calibration...",
+        }
+        yield {
+            "type": "warning",
+            "message": "ESC calibration not yet implemented",
+        }
+        yield {
+            "type": "status",
+            "message": "ESC calibration finished",
+        }
+
+    # Final success message for the whole calibration run
+    yield {
+        "type": "success",
+        "message": "Calibration sequence completed",
+    }