dmc/app/lib/transport/flight_controller_link.dart

import '../domain/waypoint/flat_waypoint_list.dart';

/// Abstrakte Flugmodi, protokollunabhaengig (Architektur-Doku 3.1).
enum FlightMode { missionRun, guidedPoint, returnHome, hold }

/// Feature-Flags des angebundenen Flightcontrollers (Doku 3.1).
class FcCapabilities {
  const FcCapabilities({
    required this.supportsMultiMission,
    required this.supportsInFlightUpload,
    required this.maxWaypoints,
  });

  final bool supportsMultiMission;
  final bool supportsInFlightUpload;
  final int maxWaypoints;
}

/// Normalisiertes Telemetrie-Frame, das an die UI weitergereicht wird (Doku 3.4).
///
/// Der Strom wird bewusst NICHT auf einen gueltigen GPS-Fix gegated (frueher
/// wurde ohne Fix gar kein Frame gesendet) - jeder Konsument entscheidet
/// selbst anhand von [hasFix], ob/wie er [lat]/[lon] verwendet. Der
/// Kartenmarker (FlyScreen) faellt bei fehlendem Fix weiterhin auf den
/// ersten Wegpunkt zurueck, das Settings-Diagnosepanel zeigt Hoehe/
/// Geschwindigkeit/Armed-Status dagegen auch ohne Fix an.
class TelemetryFrame {
  const TelemetryFrame({
    required this.lat,
    required this.lon,
    required this.hasFix,
    required this.fixType,
    required this.numSat,
    required this.altitudeM,
    required this.gpsAltitudeM,
    required this.speedMs,
    required this.headingDeg,
    required this.armed,
    required this.batteryPercent,
    required this.batteryVoltage,
    required this.currentA,
    required this.linkQuality,
    required this.snrDb,
    required this.hdop,
    required this.navMode,
    required this.flightMode,
    required this.sensorStatusBits,
    required this.temperaturesC,
    required this.verticalSpeedMs,
    this.activeWaypointIndex,
  });

  /// Nur aussagekraeftig, wenn [hasFix] - ohne Fix meldet der FC oft (0,0)
  /// oder eine veraltete Position.
  final double lat;
  final double lon;
  final bool hasFix;

  /// Roher `gpsFixType_e`-Wert aus `MSP_RAW_GPS` (`MspGpsReading.fixType` in
  /// msp_telemetry_codec.dart): 0 = kein Fix, 1 = 2D, 2 = 3D. [hasFix] ist
  /// bereits daraus abgeleitet (`fixType != 0`) - dieses Feld existiert nur
  /// fuer die 2D/3D-Unterscheidung selbst (Doku: "GPS Fixtyp im Drone Status
  /// Menue anzeigen").
  final int fixType;
  final int numSat;

  /// Barometrisch/GPS-fusionierte Hoehe relativ zum Referenzpunkt der
  /// Positionsschaetzung (in der Praxis: Einschaltort, siehe
  /// MspNavMode-/estAlt-Doku in msp_telemetry_codec.dart) - keine absolute
  /// Hoehe ueber Meeresspiegel.
  final double altitudeM;

  /// Rohe GPS-Hoehe (`MspGpsReading.altitudeM` in msp_telemetry_codec.dart,
  /// `MSP_RAW_GPS`) statt der barometrisch/GPS-fusionierten Schaetzung
  /// oben - nur bei [hasFix] aussagekraeftig, typischerweise etwas
  /// verrauschter als [altitudeM].
  final double gpsAltitudeM;
  final double speedMs;

  /// Kurs ueber Grund in Grad (0 = Norden, im Uhrzeigersinn) - dreht den
  /// Drohnen-Marker (Doku 3.10, [DroneMarkerIcon]).
  final double headingDeg;
  final bool armed;

  /// Akku-Ladestand in Prozent (0-100).
  final int batteryPercent;

  /// Akkuspannung in Volt (siehe parseMspInavAnalogVoltage in
  /// msp_telemetry_codec.dart).
  final double batteryVoltage;

  /// Aktuelle Stromaufnahme in Ampere (siehe parseMspInavAnalogAmperage in
  /// msp_telemetry_codec.dart).
  final double currentA;

  /// Empfaenger-Linkqualitaet in Prozent (0-100).
  final int linkQuality;

  /// Signal-Rausch-Verhaeltnis des Uplinks in dB (siehe
  /// parseMspLinkStatsSnr in msp_telemetry_codec.dart) - hoeher ist besser,
  /// negative Werte bedeuten das Rauschen ueberdeckt das Signal bereits
  /// teilweise trotz ggf. noch ordentlicher Linkqualitaet.
  final int snrDb;

  /// Horizontale Streuung der GPS-Positionsschaetzung (kleiner ist besser,
  /// siehe MspGpsReading.hdop in msp_telemetry_codec.dart). Ohne Fix ein
  /// sehr grosser Wert (iNAV meldet dann 99.99), nicht null.
  final double hdop;

  /// Roher `MW_GPS_MODE_*`-Wert aus `MSP_NAV_STATUS` (0=None, 1=Hold,
  /// 2=RTH, 3=Waypoint mission, 15=Emergency) - siehe MspNavMode.mode in
  /// msp_telemetry_codec.dart. Getrennt von [flightMode] (der bereits
  /// formatierten Kurzbeschreibung), weil computeDroneStatus in
  /// domain/telemetry/drone_status.dart den Rohwert fuer die
  /// Zustandsableitung braucht.
  final int navMode;

  /// Menschenlesbare Kurzbeschreibung des Navigationsmodus (z.B. "Waypoint
  /// mission (en route)", "Return to home (climbing)", "Idle") - siehe
  /// MspNavMode.formatted in msp_telemetry_codec.dart.
  final String flightMode;

  /// Rohes `sensorStatus`-Bitfeld aus `MSP2_INAV_STATUS` (protokollneutral
  /// als Bitmaske durchgereicht, analog zu [navMode]) - Bit-Bedeutung siehe
  /// `MspSensorStatusBits` in `msp_commands.dart`. `0` bei
  /// [MockFlightControllerLink]/fehlendem Frame bedeutet "kein Sensor
  /// gemeldet", nicht zwingend "kein Sensor vorhanden".
  final int sensorStatusBits;

  /// Die ersten 3 Temperatursensoren in °C (siehe
  /// `MspCommands.inavTemperatures`), `null` je Slot ohne konfigurierten/
  /// gueltigen Sensor. Immer genau 3 Eintraege lang.
  final List<double?> temperaturesC;

  /// Steig-/Sinkrate in m/s, positiv = Steigen (siehe
  /// `parseMspAltitudeVerticalSpeedMs` in msp_telemetry_codec.dart).
  final double verticalSpeedMs;

  /// 0-basierter Index des gerade angeflogenen Wegpunkts in der
  /// App-eigenen Wegpunktliste (z.B. `currentMissionProvider`), oder null,
  /// wenn keine Mission aktiv ist. Bei MSP bereits aus dem 1-basierten
  /// `activeWpNumber` umgerechnet (siehe parseMspNavStatusActiveWaypoint in
  /// msp_telemetry_codec.dart).
  final int? activeWaypointIndex;
}

/// Vom Flightcontroller gemeldeter Homepoint (Doku: "den auf der Drohne
/// gelockten Homepoint abfragen") - anders als [TelemetryFrame] NICHT Teil
/// des kontinuierlichen Telemetrie-Stroms, sondern gezielt per
/// [FlightControllerLink.readHomePoint] abgefragt (siehe dortige Doku und
/// ui/providers/home_point_provider.dart fuer die drei Momente, zu denen
/// das tatsaechlich noetig ist).
class HomePoint {
  const HomePoint({required this.lat, required this.lon, required this.altitudeM});

  final double lat;
  final double lon;

  /// Referenzhoehe des Homepoints in Metern (bei MSP: `GPS_home.alt` in cm,
  /// bereits umgerechnet) - relativ zum selben Nullpunkt wie
  /// TelemetryFrame.altitudeM, keine absolute Hoehe ueber Meeresspiegel.
  final double altitudeM;
}

/// Zentrale Abstraktion fuer alle Flightcontroller-Interaktionen (Doku 3.1).
/// Implementierungen: MspFlightControllerLink (iNAV), MavlinkFlightControllerLink
/// (ArduPilot, Post-MVP), MockFlightControllerLink (Tests ohne Hardware).
abstract class FlightControllerLink {
  FcCapabilities get capabilities;

  Future<void> connect();

  Future<void> disconnect();

  Future<void> uploadMission(FlatWaypointList mission);

  /// Prueft nach [uploadMission], ob der Flightcontroller die Mission
  /// tatsaechlich vollstaendig und gueltig uebernommen hat (Doku 2.2/4.5:
  /// Ready-to-Fly-Gate "Upload + verifiziert + disarmed") - protokollneutrale
  /// Ja/Nein-Antwort, jede Implementierung entscheidet selbst, wie sie das
  /// beim jeweiligen Flightcontroller abfragt (MSP: `MSP_WP_GETINFO`,
  /// MAVLink: `MISSION_REQUEST_LIST`/`MISSION_COUNT`-Runde).
  Future<bool> verifyMission(FlatWaypointList mission);

  Future<void> setFlightMode(FlightMode mode);

  Future<void> arm();

  Stream<TelemetryFrame> subscribeTelemetry();

  Future<int?> readActiveWaypointIndex();

  /// Fragt den aktuell auf dem Flightcontroller gespeicherten Homepoint ab,
  /// oder `null`, wenn dort noch keiner gesetzt ist (bei MSP: FC meldet vor
  /// dem ersten Fix (0,0,0) statt eines Fehlers, siehe
  /// `MspFlightControllerLink.readHomePoint`-Doku). Bewusst ein einzelner
  /// gezielter Abruf statt eines Streams/Poll-Feldes - der Homepoint
  /// aendert sich ausserhalb weniger Trigger-Momente ohnehin nicht (siehe
  /// ui/providers/home_point_provider.dart).
  Future<HomePoint?> readHomePoint();
}