bluetooth connectivity layer added

2026-07-30 19:46:52 +02:00
parent 310d92f187
commit 5994aee7ad
19 changed files with 1665 additions and 15 deletions
@@ -0,0 +1,79 @@
+import 'dart:typed_data';
+
+/// Transportzustand, protokollneutral (Doku Kommunikationsschicht Abschnitt 2).
+enum LinkState { disconnected, connecting, connected, error }
+
+/// Grund eines [LinkState.error] (Doku Abschnitt 3, Robustheit/Abnahme):
+/// Bluetooth aus und Berechtigung abgelehnt brauchen jeweils einen eigenen,
+/// erklaerenden Hinweis in der Oberflaeche statt eines generischen
+/// "Verbindung fehlgeschlagen".
+enum LinkErrorReason {
+  /// Bluetooth-Adapter ist aus. Kann ab Android 12 nicht mehr programmatisch
+  /// eingeschaltet werden - die Oberflaeche muss zu den Systemeinstellungen
+  /// verlinken.
+  bluetoothOff,
+
+  /// Berechtigung wurde abgelehnt, darf aber erneut angefragt werden.
+  permissionDenied,
+
+  /// Berechtigung wurde dauerhaft abgelehnt ("nicht mehr fragen"). Android
+  /// zeigt den Dialog kein zweites Mal - die Oberflaeche muss zu den
+  /// App-Einstellungen verlinken.
+  permissionDeniedPermanently,
+
+  /// Kein gekoppeltes Zielgeraet konnte automatisch bestimmt werden (weder
+  /// gemerkte MAC-Adresse noch ein Geraet mit "mLRS"-Praefix). Die
+  /// Oberflaeche muss eine Auswahlliste der gekoppelten Geraete anbieten.
+  deviceSelectionRequired,
+
+  /// Verbindungsaufbau zum bestimmten Geraet ist fehlgeschlagen oder wurde
+  /// getrennt.
+  connectionFailed,
+
+  /// Sonstiger, nicht naeher klassifizierter Fehler.
+  unknown,
+}
+
+/// Protokollneutrale Transportschnittstelle (Doku Kommunikationsschicht
+/// Abschnitt 2). Alles oberhalb (MSP-Encoder/-Decoder) programmiert
+/// ausschliesslich gegen diese Schnittstelle - kein Import von Bluetooth-
+/// oder Netzwerkpaketen ausserhalb von transport/.
+///
+/// Implementierungen: BluetoothClassicTransport (MVP), UdpTransport
+/// (spaeter, Doku Abschnitt 6), LoopbackTransport (Tests/Entwicklung ohne
+/// Hardware).
+abstract class LinkTransport {
+  Stream<Uint8List> get incoming;
+  Stream<LinkState> get state;
+
+  /// Grund des zuletzt gemeldeten [LinkState.error], oder null solange kein
+  /// Fehler aufgetreten ist bzw. nach erfolgreicher Verbindung.
+  LinkErrorReason? get lastErrorReason;
+
+  /// Freitext zum zuletzt gemeldeten Fehler, fuer Diagnose/Verbindungsprotokoll
+  /// (Doku Abschnitt 7). Nicht fuer die direkte Nutzeranzeige gedacht - dafuer
+  /// dient [lastErrorReason].
+  String? get lastErrorMessage;
+
+  Future<void> send(Uint8List data);
+  Future<void> connect();
+  Future<void> disconnect();
+  void dispose();
+}
+
+/// Wird von [LinkTransport.connect] geworfen, wenn der Verbindungsaufbau
+/// vorab (also bevor ueberhaupt eine Socket-Verbindung versucht wird)
+/// erkennbar scheitert - z.B. Bluetooth aus, Berechtigung fehlt, oder kein
+/// Geraet automatisch bestimmbar. Der gleiche [reason] wird zeitgleich ueber
+/// [LinkTransport.state]/[LinkTransport.lastErrorReason] gemeldet, damit
+/// sowohl der aufrufende Code (durch Warten auf [LinkTransport.connect])
+/// als auch reine Beobachter der Zustands-Streams reagieren koennen.
+class LinkConnectException implements Exception {
+  const LinkConnectException(this.reason, this.message);
+
+  final LinkErrorReason reason;
+  final String message;
+
+  @override
+  String toString() => 'LinkConnectException($reason): $message';
+}