Add adaptive BLE mode detection for Triki motion input.

TrikiBLEMonitor classifies fast/normal/lowPower from packet timing with
debounced transitions; TrikiMotionEngine and TrikiGameController adapt
processing, HUD rate, idle UX, and optional wake-up INIT.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: koderhack

AGENTS.md

@@ -32,6 +32,7 @@ VeltoKit/
   MotionConfig.swift   # Presets per MotionMode
   BLE/BLEManager.swift # Stub → TrikiBLEManager
   Triki/TrikiBLEManager.swift      # Scan, connect, reconnect, notify
+  Triki/TrikiBLEMonitor.swift      # fast/normal/lowPower from packet Δt
   Triki/TrikiParser.swift          # Format-detecting int16 decode
   Triki/TrikiMotionEngine.swift    # Velocity / shake / tilt / swing
   Triki/TrikiGameController.swift  # Gamepad API (TrikiGameInput)

VeltoKit/MotionSDK.swift

@@ -26,6 +26,10 @@ public final class MotionSDK: ObservableObject {
   @Published public internal(set) var isConnected = false
   /// Informuje, czy napływają pakiety BLE.
   @Published public internal(set) var isReceiving = false
+  /// Wykryty tryb częstotliwości notify (fast / normal / low power).
+  public var trikiBLEMode: TrikiBLEMode {
+    trikiController?.getBLEMode() ?? .unknown
+  }
   /// Ostatnia ramka wejścia publikowana do HUD.
   @Published public internal(set) var liveInput = GameInput()
 

VeltoKit/Triki/TrikiBLEMonitor.swift

@@ -0,0 +1,131 @@
+import Foundation
+import os
+
+/// Tryb wydajności notify firmware (wykrywany z odstępów między pakietami).
+public enum TrikiBLEMode: String, Sendable, Equatable, CaseIterable {
+  case fast
+  case normal
+  case lowPower
+  case unknown
+}
+
+/// Wynik aktualizacji monitora — opcjonalna zmiana trybu po debounce.
+public struct TrikiBLEModeTransition: Sendable, Equatable {
+  public let previous: TrikiBLEMode
+  public let current: TrikiBLEMode
+  public let packetDelta: TimeInterval
+}
+
+/// Śledzi timing pakietów BLE i stabilnie wykrywa tryb fast / normal / low power.
+public final class TrikiBLEMonitor: @unchecked Sendable {
+  private let log = Logger(subsystem: "com.koderteam.gametriki", category: "TrikiBLEMonitor")
+  private let lock = NSLock()
+
+  /// Ostatni znany tryb (po debounce).
+  public private(set) var currentMode: TrikiBLEMode = .unknown
+  /// Ostatni zmierzony odstęp między pakietami (s).
+  public private(set) var lastPacketDelta: TimeInterval = 0
+  /// Czas ostatniego pakietu (s od 1970).
+  public private(set) var lastTimestamp: TimeInterval = 0
+
+  /// Włącza log delta + przejść trybu.
+  public var debugLoggingEnabled = false
+
+  /// Ile kolejnych pakietów z tym samym trybem przed commit (anty-flicker).
+  public var requiredStablePackets = 3
+  /// Ignoruj delty powyżej tej wartości przy klasyfikacji (przerwa / reconnect).
+  public var maxClassifyDelta: TimeInterval = 3.0
+  /// Po tylu sekundach bez pakietów → low power (UX idle).
+  public var stalePacketThreshold: TimeInterval = 1.5
+
+  private var candidateMode: TrikiBLEMode = .unknown
+  private var candidateStreak = 0
+
+  public init() {}
+
+  /// Rejestruje przyjęcie pakietu; zwraca przejście trybu po debounce (jeśli było).
+  @discardableResult
+  public func recordPacket(at timestamp: TimeInterval) -> TrikiBLEModeTransition? {
+    lock.lock()
+    defer { lock.unlock() }
+
+    var transition: TrikiBLEModeTransition?
+
+    if lastTimestamp > 0 {
+      let delta = timestamp - lastTimestamp
+      lastPacketDelta = delta
+
+      if debugLoggingEnabled {
+        print(String(format: "[TrikiBLEMonitor] Δ=%.0fms", delta * 1000))
+        log.debug("packet delta=\(delta, privacy: .public)s")
+      }
+
+      if delta >= 0.001, delta <= maxClassifyDelta {
+        let sample = Self.classify(delta: delta)
+        transition = applyCandidate(sample, delta: delta)
+      } else if delta > maxClassifyDelta, debugLoggingEnabled {
+        print("[TrikiBLEMonitor] skip classify (Δ=\(String(format: "%.2f", delta))s)")
+      }
+    }
+
+    lastTimestamp = timestamp
+    return transition
+  }
+
+  /// Wywołuj z pętli gry gdy długo nie było pakietów (idle / low power UX).
+  public func evaluateStale(now: TimeInterval) -> TrikiBLEModeTransition? {
+    lock.lock()
+    defer { lock.unlock() }
+
+    guard lastTimestamp > 0 else { return nil }
+    let gap = now - lastTimestamp
+    guard gap >= stalePacketThreshold else { return nil }
+    return applyCandidate(.lowPower, delta: gap)
+  }
+
+  public func reset() {
+    lock.lock()
+    defer { lock.unlock() }
+    lastTimestamp = 0
+    lastPacketDelta = 0
+    currentMode = .unknown
+    candidateMode = .unknown
+    candidateStreak = 0
+  }
+
+  // MARK: - Classification
+
+  public static func classify(delta: TimeInterval) -> TrikiBLEMode {
+    if delta < 0.03 {
+      return .fast
+    }
+    if delta < 0.2 {
+      return .normal
+    }
+    return .lowPower
+  }
+
+  private func applyCandidate(_ sample: TrikiBLEMode, delta: TimeInterval) -> TrikiBLEModeTransition? {
+    if sample == candidateMode {
+      candidateStreak += 1
+    } else {
+      candidateMode = sample
+      candidateStreak = 1
+    }
+
+    guard candidateStreak >= requiredStablePackets, sample != currentMode else {
+      return nil
+    }
+
+    let previous = currentMode
+    currentMode = sample
+    candidateStreak = 0
+
+    if debugLoggingEnabled {
+      print("[TrikiBLEMonitor] mode \(previous.rawValue) → \(sample.rawValue) (Δ=\(String(format: "%.0f", delta * 1000))ms)")
+    }
+    log.info("BLE mode \(previous.rawValue, privacy: .public) → \(sample.rawValue, privacy: .public)")
+
+    return TrikiBLEModeTransition(previous: previous, current: sample, packetDelta: delta)
+  }
+}

VeltoKit/Triki/TrikiGameController.swift

@@ -1,10 +1,9 @@
 import Combine
 import Foundation
 
-/// Publiczna fasada gamepada Triki — BLE → parser → motion → `TrikiGameInput`.
+/// Publiczna fasada gamepada Triki — BLE → monitor → parser → adaptacyjny motion.
 @MainActor
 public final class TrikiGameController: ObservableObject {
-  /// Tryb czułości (szybki vs stabilny).
   public enum InputMode: Sendable, Equatable {
     case game
     case smooth
@@ -16,25 +15,39 @@ public final class TrikiGameController: ObservableObject {
     didSet { motion.inputMode = mapInputMode(inputMode) }
   }
 
-  /// Log hex + wartości parsera (DEV).
   public var debugParserLogging: Bool {
     get { parser.debugLoggingEnabled }
     set { parser.debugLoggingEnabled = newValue }
   }
 
+  public var debugBLEMonitorLogging: Bool {
+    get { bleMonitor.debugLoggingEnabled }
+    set { bleMonitor.debugLoggingEnabled = newValue }
+  }
+
+  /// Odstęp publikacji HUD w trybie low power (mniej odświeżeń UI).
+  public var lowPowerHudPublishInterval: TimeInterval = 0.35
+
   @Published public private(set) var gameInput = TrikiGameInput()
+  @Published public private(set) var bleMode: TrikiBLEMode = .unknown
   @Published public private(set) var isConnected = false
   @Published public private(set) var isReceiving = false
+  /// Tekst podpowiedzi UX przy low power.
+  @Published public private(set) var idleStatusMessage: String? = nil
 
   private var parser = TrikiParser()
   private var motion = TrikiMotionEngine()
+  private let bleMonitor = TrikiBLEMonitor()
   private var cancellables = Set<AnyCancellable>()
   private var lastPacketAt: TimeInterval = 0
   private var lastPollTime: TimeInterval?
+  private var lastHudPublishAt: TimeInterval = 0
+  private var lastWakeUpAttemptAt: TimeInterval = 0
 
   private var moveHandlers: [(Float) -> Void] = []
   private var shakeHandlers: [() -> Void] = []
   private var actionHandlers: [() -> Void] = []
+  private var modeChangedHandlers: [(TrikiBLEMode) -> Void] = []
 
   public init() {
     motion.inputMode = .game
@@ -43,7 +56,6 @@ public final class TrikiGameController: ObservableObject {
 
   // MARK: - Connection
 
-  /// Skan + auto-connect do jedynego urządzenia z „triki” w nazwie.
   public func connect() {
     ble.autoConnectWhenSingleLikelyMatch = true
     if ble.cachedPeripheralUUID != nil, ble.status == .idle {
@@ -58,21 +70,28 @@ public final class TrikiGameController: ObservableObject {
     resetSession()
   }
 
-  // MARK: - Manual bytes (własny central)
-
   public func ingest(_ bytes: [UInt8]) {
     guard !bytes.isEmpty else { return }
+    let now = Date().timeIntervalSince1970
+    if let transition = bleMonitor.recordPacket(at: now) {
+      applyBLEModeTransition(transition)
+    }
     parser.append(bytes)
-    lastPacketAt = Date().timeIntervalSince1970
+    lastPacketAt = now
     if !isReceiving { isReceiving = true }
+    updateIdleMessage()
   }
 
-  /// Wywołuj w pętli gry (~60 Hz). Zwraca bieżącą ramkę gamepada.
   @discardableResult
   public func tick(deltaTime: TimeInterval? = nil) -> TrikiGameInput {
     let now = Date().timeIntervalSince1970
     if now - lastPacketAt > 0.35, isReceiving { isReceiving = false }
 
+    if let transition = bleMonitor.evaluateStale(now: now) {
+      applyBLEModeTransition(transition)
+    }
+    attemptWakeUpIfStuck(now: now)
+
     let dt: TimeInterval
     if let deltaTime {
       dt = deltaTime
@@ -84,29 +103,38 @@ public final class TrikiGameController: ObservableObject {
     let frames = parser.drainParsedFrames()
     if !frames.isEmpty {
       motion.ingest(parsed: frames, deltaTime: dt)
-      gameInput = motion.output
+      publishGameInputIfNeeded(now: now)
       dispatchCallbacks()
+    } else if bleMode == .lowPower, now - lastHudPublishAt >= lowPowerHudPublishInterval {
+      gameInput = motion.output
+      lastHudPublishAt = now
     }
+
     return gameInput
   }
 
   public func resetSession() {
     parser.reset()
     motion.reset()
+    bleMonitor.reset()
     gameInput = TrikiGameInput()
+    bleMode = .unknown
+    idleStatusMessage = nil
     isReceiving = false
     lastPollTime = nil
+    lastHudPublishAt = 0
+    lastWakeUpAttemptAt = 0
   }
 
-  // MARK: - Gamepad API (bez surowych osi)
+  // MARK: - Public API
+
+  public func getBLEMode() -> TrikiBLEMode { bleMode }
 
   public func getDirection() -> Float { motion.getDirection() }
   public func getVelocity() -> Float { motion.getVelocity() }
   public func isShake() -> Bool { motion.isShake() }
   public func isMoving() -> Bool { motion.isMoving() }
 
-  // MARK: - Callbacks (DX)
-
   public func onMove(_ handler: @escaping (Float) -> Void) {
     moveHandlers.append(handler)
   }
@@ -119,10 +147,15 @@ public final class TrikiGameController: ObservableObject {
     actionHandlers.append(handler)
   }
 
+  public func onModeChanged(_ handler: @escaping (TrikiBLEMode) -> Void) {
+    modeChangedHandlers.append(handler)
+  }
+
   public func clearHandlers() {
     moveHandlers.removeAll()
     shakeHandlers.removeAll()
     actionHandlers.removeAll()
+    modeChangedHandlers.removeAll()
   }
 
   // MARK: - Private
@@ -146,10 +179,50 @@ public final class TrikiGameController: ObservableObject {
       .store(in: &cancellables)
   }
 
+  private func applyBLEModeTransition(_ transition: TrikiBLEModeTransition) {
+    bleMode = transition.current
+    motion.setBLEMode(transition.current)
+    for handler in modeChangedHandlers {
+      handler(transition.current)
+    }
+    updateIdleMessage()
+  }
+
+  private func updateIdleMessage() {
+    switch bleMode {
+    case .lowPower:
+      idleStatusMessage = "Bezruch — czekam na ruch"
+    case .fast, .normal:
+      idleStatusMessage = nil
+    case .unknown:
+      idleStatusMessage = nil
+    }
+  }
+
+  private func publishGameInputIfNeeded(now: TimeInterval) {
+    let interval: TimeInterval = bleMode == .lowPower ? lowPowerHudPublishInterval : 0
+    if interval > 0, now - lastHudPublishAt < interval, lastHudPublishAt > 0 {
+      return
+    }
+    gameInput = motion.output
+    lastHudPublishAt = now
+  }
+
+  /// Po długim low power bez pakietów — delikatne „obudzenie” streamu (INIT).
+  private func attemptWakeUpIfStuck(now: TimeInterval) {
+    guard bleMode == .lowPower, isConnected else { return }
+    guard now - lastPacketAt > 4.0 else { return }
+    guard now - lastWakeUpAttemptAt > 5.0 else { return }
+    lastWakeUpAttemptAt = now
+    ble.sendInitAndStartIfReady()
+    if debugBLEMonitorLogging {
+      print("[TrikiGameController] wake-up INIT (low power stall)")
+    }
+  }
+
   private func dispatchCallbacks() {
-    let direction = gameInput.direction
     if gameInput.isMoving {
-      for handler in moveHandlers { handler(direction) }
+      for handler in moveHandlers { handler(gameInput.direction) }
     }
     if gameInput.isShake {
       for handler in shakeHandlers { handler() }