Show the drone's locked home point on the fly-mode map

Adds MSP_WP (118) support to query the flightcontroller's stored home point (WP#0 is a special case for this in iNAV's getWaypoint(), per navigation.c) - the FC reports (0,0,0) rather than an error before one is set, so parseMspHomePoint() treats that pair as "unset". Rendered with a small pentagon house icon (design/homepoint-pentagon.svg, ported to a CustomPainter like the other map icons). Deliberately not polled continuously: a new home_point_provider.dart refreshes it only at the three moments the FC's home point can actually change - connect/reconnect, GPS fix acquired, and arming (iNAV's default reset_home_type=FIRST_ARM only freezes it at the first arm; before that it continuously follows the aircraft while disarmed). Mock's implementation offsets the point 25m from the anchor so it doesn't sit exactly under the drone marker during UI testing.
2026-08-09 21:10:00 +02:00
parent c9f16b13f8
commit 5fd5d0117a
12 changed files with 594 additions and 0 deletions
@@ -144,6 +144,24 @@ class TelemetryFrame {
  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).
@@ -171,4 +189,13 @@ abstract class FlightControllerLink {
  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();
 }
@@ -222,4 +222,24 @@ class MockFlightControllerLink implements FlightControllerLink {

  @override
  Future<int?> readActiveWaypointIndex() async => _activeWaypointIndex;
+
+  /// Liefert immer einen Wert (nahe dem Ankerpunkt, siehe Klassendoku) statt
+  /// wie der echte FC vor dem ersten Fix `null` - fuer UI-Entwicklung ohne
+  /// Hardware (Doku 9) ist ein sofort sichtbarer Homepoint-Marker
+  /// hilfreicher als ein realistisch leerer Zustand.
+  ///
+  /// Bewusst um [_homeOffsetM] Meter suedlich des Ankerpunkts versetzt statt
+  /// exakt darauf: der Drohnen-Marker (siehe connect()) startet ebenfalls am
+  /// Ankerpunkt und drueckt sich nur innerhalb von [_driftRadiusM] (10 m)
+  /// davon weg - ohne Versatz lag der Homepoint-Marker im Mock-Test also
+  /// praktisch immer direkt unter dem Drohnen-Marker und war nie als
+  /// eigenes Icon zu sehen.
+  static const _homeOffsetM = 25.0;
+
+  @override
+  Future<HomePoint?> readHomePoint() async => HomePoint(
+        lat: _anchorLat - _homeOffsetM / _metersPerDegreeLat,
+        lon: _anchorLon,
+        altitudeM: 0,
+      );
 }
@@ -21,6 +21,22 @@ abstract final class MspCommands {
  /// msp_waypoint_codec.dart. (`fc_msp.c`, `case MSP_WP_GETINFO`)
  static const int wpGetInfo = 20;

+  /// Request-Payload (1 Byte): u8 wp_no. Response (21 Byte): u8 wp_no, u8
+  /// action, i32 lat(1e-7 deg), i32 lon(1e-7 deg), i32 alt(cm), i16 p1, i16
+  /// p2, i16 p3, u8 flag (`fc_msp.c`, `mspFcWaypointOutCommand()`, `case
+  /// MSP_WP`). Kein Batch-Kommando - ein Request pro Wegpunktnummer, analog
+  /// zu [setWp]. `wp_no` kennt laut `navigation.c` `getWaypoint()` zwei
+  /// Sonderwerte neben echten Missions-Wegpunktnummern: 0 = Homepoint
+  /// (`GPS_home.lat/lon/alt`, nur gueltig wenn `STATE(GPS_FIX_HOME)` -
+  /// sonst liefert der FC (0,0,0) statt eines Fehlers, siehe
+  /// msp_waypoint_codec.dart `parseMspHomePoint`), 255 = aktuelle
+  /// Ist-Position. Der Homepoint selbst wird vom FC NICHT beim ersten
+  /// GPS-Fix eingefroren, sondern folgt der Drohne kontinuierlich, solange
+  /// sie disarmed ist und noch nie armed war (`updateHomePosition()`) -
+  /// gesperrt wird er erst beim ersten Armen (iNAV-Default
+  /// `reset_home_type = FIRST_ARM`, `settings.yaml`).
+  static const int getWp = 118;
+
  /// Request-Payload (21 Byte, siehe msp_waypoint_codec.dart
  /// `encodeMspSetWaypoint`): u8 wp_no, u8 action, i32 lat(1e-7 deg),
  /// i32 lon(1e-7 deg), i32 alt(cm), i16 p1, i16 p2, i16 p3, u8 flag. Nur
@@ -142,4 +142,21 @@ class MspFlightControllerLink implements FlightControllerLink {
      await client.request(MspCommands.navStatus),
    );
  }
+
+  /// Fragt WP#0 (Homepoint, siehe `MspCommands.getWp`-Doku) gezielt per
+  /// `MSP_WP` ab - bewusst kein Teil von [MspTelemetryPoller]s Zyklus (Doku:
+  /// "Homepoint muss nicht kontinuierlich abgefragt werden"), Aufrufer ist
+  /// home_point_provider.dart.
+  @override
+  Future<HomePoint?> readHomePoint() async {
+    final client = _client;
+    if (client == null) {
+      throw StateError('readHomePoint() vor connect() aufgerufen.');
+    }
+    final payload = await client.request(
+      MspCommands.getWp,
+      payload: encodeMspGetWaypointRequest(mspWpNumberHome),
+    );
+    return parseMspHomePoint(payload);
+  }
 }
@@ -1,6 +1,7 @@
 import 'dart:typed_data';

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

 /// `navWaypointActions_e` (Doku Kommunikationsschicht v2 Abschnitt 6,
 /// geprueft gegen den iNAV-9.1.0-Quellcode: `navigation.h`). Nur die vier
@@ -136,3 +137,30 @@ MspWpGetInfo parseMspWpGetInfo(Uint8List payload) {
    waypointCount: payload[3],
  );
 }
+
+/// Sonderwert fuer [encodeMspGetWaypointRequest]/`MspCommands.getWp`: WP#0
+/// ist laut `navigation.c` `getWaypoint()` der Homepoint, kein echter
+/// Missions-Wegpunkt.
+const int mspWpNumberHome = 0;
+
+/// Kodiert den 1-Byte-Request-Payload fuer `MspCommands.getWp` (`MSP_WP`).
+Uint8List encodeMspGetWaypointRequest(int wpNumber) =>
+    Uint8List.fromList([wpNumber]);
+
+/// Parst die 21-Byte-Antwort auf `MspCommands.getWp` fuer `wp_no ==
+/// [mspWpNumberHome]` (siehe dortige Doku zu `getWaypoint()`/`GPS_home`).
+///
+/// Liefert `null`, wenn der FC noch keinen Homepoint gesetzt hat: dafuer
+/// gibt es kein eigenes Flag in der Antwort selbst, `getWaypoint()`
+/// initialisiert `lat`/`lon`/`alt` aber generell auf 0 und ueberschreibt
+/// das fuer WP#0 nur, wenn `STATE(GPS_FIX_HOME)` gesetzt ist - (0,0) ist
+/// also der FC-eigene "kein Homepoint"-Wert, nicht eine echte Koordinate
+/// am Nullmeridian/Aequator.
+HomePoint? parseMspHomePoint(Uint8List payload) {
+  final d = ByteData.sublistView(payload);
+  final lat = d.getInt32(2, Endian.little) / 1e7;
+  final lon = d.getInt32(6, Endian.little) / 1e7;
+  if (lat == 0 && lon == 0) return null;
+  final altCm = d.getInt32(10, Endian.little);
+  return HomePoint(lat: lat, lon: lon, altitudeM: altCm / 100);
+}