Merge main 0.3.1 into wear-os-watch-ultra

Brings in the multi-wheel-support work (V12, P6, virtual sim) and the
verified P6 telemetry offset corrections so the watch dashboard's PWM /
torque / temp readouts are correct on every supported wheel.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

# Conflicts:
#	.github/workflows/branch-apk.yml
#	BRANCH.md

Author: eried

.gitignore

@@ -20,4 +20,13 @@ keystore.properties
 release/
 /.playwright-mcp
 /.claude
-/.claude
+
+# Scratch files (analysis, screenshots, ad-hoc)
+.tmp_*
+*.btsnoop
+*.cfa
+*.log
+
+# Stray build-output paths that have leaked into the repo before
+**/eucplanet_*.png
+**/build/eucplanet_*

BRANCH.md

@@ -7,6 +7,10 @@ Ultra). The phone holds the BLE link to the wheel and pushes a compact
 telemetry snapshot to the watch over the Wearable Data Layer; the watch is a
 thin client and never talks to the wheel directly.
 
+This branch is built on top of `main` (V14 + V12 + P6 multi-wheel support
+verified through 0.3.1), so the watch dashboard inherits the corrected P6
+telemetry offsets (PWM, torque, MOS+motor temps, signed reverse speed).
+
 Concretely shipped here:
 
 - **Full-bleed speed dial** that wraps the entire watch face. Same arc
@@ -33,6 +37,9 @@ Concretely shipped here:
 - **Resolution-clean.** All sizes derive from `BoxWithConstraints.maxWidth`
   so the layout looks right on small round watches (~390 dp) and on Watch
   Ultra (~454 dp) without separate code paths.
+- **Auto-start ping** on phone-app open and a manual "Play" button next to
+  the Auto-start setting so users can verify pairing without backgrounding
+  and relaunching the phone app.
 
 ## Architecture
 

DGitHubeucplanetbuildeucplanet_1.png

@@ -27,8 +27,8 @@ android {
         applicationId = "com.eried.eucplanet"
         minSdk = 29
         targetSdk = 35
-        versionCode = 7
-        versionName = "0.3.0"
+        versionCode = 8
+        versionName = "0.3.1"
 
         val buildStamp = SimpleDateFormat("yyMMdd.HHmm")
             .apply { timeZone = TimeZone.getTimeZone("UTC") }

app/build.gradle.kts

@@ -24,7 +24,8 @@ import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asSharedFlow
 import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.launch
-import java.io.ByteArrayOutputStream
+import com.eried.eucplanet.ble.virtual.VirtualWheel
+import com.eried.eucplanet.ble.virtual.VirtualWheelRegistry
 import java.util.UUID
 import javax.inject.Inject
 import javax.inject.Singleton
@@ -39,15 +40,13 @@ enum class ConnectionState {
 
 @Singleton
 class BleConnectionManager @Inject constructor(
-    @ApplicationContext private val context: Context
+    @ApplicationContext private val context: Context,
+    private val wheelAdapter: WheelAdapter
 ) {
     companion object {
         private const val TAG = "BleConnection"
 
-        // Nordic UART Service UUIDs
-        val NUS_SERVICE_UUID: UUID = UUID.fromString("6e400001-b5a3-f393-e0a9-e50e24dcca9e")
-        val NUS_RX_UUID: UUID = UUID.fromString("6e400002-b5a3-f393-e0a9-e50e24dcca9e")  // write
-        val NUS_TX_UUID: UUID = UUID.fromString("6e400003-b5a3-f393-e0a9-e50e24dcca9e")  // notify
+        // Client Characteristic Configuration Descriptor — same for every wheel family.
         val CCCD_UUID: UUID = UUID.fromString("00002902-0000-1000-8000-00805f9b34fb")
     }
 
@@ -57,41 +56,108 @@ class BleConnectionManager @Inject constructor(
     private val _connectionState = MutableStateFlow(ConnectionState.DISCONNECTED)
     val connectionState: StateFlow<ConnectionState> = _connectionState.asStateFlow()
 
-    private val _receivedPackets = MutableSharedFlow<ParsedPacket>(extraBufferCapacity = 64)
-    val receivedPackets: SharedFlow<ParsedPacket> = _receivedPackets.asSharedFlow()
+    private val _decodedResults = MutableSharedFlow<DecodeResult>(extraBufferCapacity = 64)
+    /** Stream of decoded results from the active wheel adapter. */
+    val decodedResults: SharedFlow<DecodeResult> = _decodedResults.asSharedFlow()
 
     private var gatt: BluetoothGatt? = null
     private var rxCharacteristic: BluetoothGattCharacteristic? = null
     private var currentAddress: String? = null
+    /** BLE advertised name from the most recent connect call, kept across reconnects. */
+    private var currentName: String? = null
     private var shouldReconnect = true
 
     // Write serialization - only one BLE write at a time
     private val writeChannel = Channel<ByteArray>(Channel.BUFFERED)
     private var writeReady = false
 
-    // Packet reassembly buffer
-    private val reassemblyBuffer = ByteArrayOutputStream()
+    // Active virtual wheel when in demo mode (address starts with "VIRTUAL:").
+    // When non-null, writes are routed to the simulator instead of GATT and the
+    // simulator's response bytes are fed back through the adapter pipeline as if
+    // they had arrived as real BLE notifications. GATT handles stay null.
+    @Volatile private var virtualWheel: VirtualWheel? = null
 
     init {
         scope.launch { processWriteQueue() }
     }
 
     @SuppressLint("MissingPermission")
-    fun connect(address: String) {
+    fun connect(address: String, name: String? = null) {
+        // Demo / simulator mode: VIRTUAL:<id> bypasses GATT and connects to a fake wheel.
+        val virtualId = VirtualWheelRegistry.parsePseudoAddress(address)
+        if (virtualId != null) {
+            connectVirtual(virtualId)
+            return
+        }
+
         currentAddress = address
+        // Hold on to the name so the auto-reconnect path keeps the same hint —
+        // otherwise a P6 that briefly drops would come back as an unknown wheel.
+        currentName = name ?: currentName
         shouldReconnect = true
         _connectionState.value = ConnectionState.CONNECTING
 
+        // Adapter pre-selects model from the BLE name; needed for the InMotion
+        // P6 because its legacy carType query returns zeros and we'd otherwise
+        // never identify it before sending V14-shaped queries the wheel ignores.
+        wheelAdapter.notifyConnectingTo(currentName)
+
         val device: BluetoothDevice = bluetoothManager.adapter.getRemoteDevice(address)
         gatt = device.connectGatt(context, false, gattCallback, BluetoothDevice.TRANSPORT_LE)
     }
 
+    /**
+     * Skip GATT entirely and run a simulated wheel. The fake produces the same
+     * raw-byte responses a real wheel would emit, so the parser/adapter/repository
+     * pipeline runs unchanged. Disconnect by calling [disconnect] as usual.
+     */
+    private fun connectVirtual(id: String) {
+        val wheel = VirtualWheelRegistry.create(id) ?: run {
+            Log.e(TAG, "Unknown virtual wheel id: $id")
+            return
+        }
+        Log.i(TAG, "Connecting to virtual wheel: ${wheel.displayName}")
+        wheel.reset()
+        virtualWheel = wheel
+        currentAddress = VirtualWheelRegistry.pseudoAddress(id)
+        shouldReconnect = false
+        _connectionState.value = ConnectionState.CONNECTING
+        scope.launch {
+            // Brief delays so the UI's connection-state animations actually animate.
+            delay(150)
+            _connectionState.value = ConnectionState.INITIALIZING
+            for (resp in wheel.onConnect()) emitVirtualResponse(resp)
+            delay(150)
+            // Mark CONNECTED last so writeReady gates open AFTER on-connect responses
+            // have already filtered through the adapter — same ordering a real wheel
+            // gets, where notifications start landing once the GATT subscription is up.
+            writeReady = true
+            _connectionState.value = ConnectionState.CONNECTED
+        }
+    }
+
+    private fun emitVirtualResponse(rawBytes: ByteArray) {
+        for (result in wheelAdapter.onRawNotification(rawBytes)) {
+            _decodedResults.tryEmit(result)
+        }
+    }
+
     @SuppressLint("MissingPermission")
     fun disconnect() {
         shouldReconnect = false
         currentAddress = null
+        currentName = null
         rxCharacteristic = null
         writeReady = false
+
+        // Virtual wheel: just drop the reference; no GATT to tear down.
+        if (virtualWheel != null) {
+            wheelAdapter.onDisconnect()
+            virtualWheel = null
+            _connectionState.value = ConnectionState.DISCONNECTED
+            return
+        }
+
         val g = gatt
         if (g == null) {
             _connectionState.value = ConnectionState.DISCONNECTED
@@ -125,6 +191,13 @@ class BleConnectionManager @Inject constructor(
     @SuppressLint("MissingPermission")
     private suspend fun processWriteQueue() {
         for (data in writeChannel) {
+            // Virtual mode: hand the write to the simulator and feed any responses
+            // back through the adapter pipeline. No GATT, no writeReady gating.
+            val virtual = virtualWheel
+            if (virtual != null) {
+                for (resp in virtual.onWrite(data)) emitVirtualResponse(resp)
+                continue
+            }
             if (!writeReady || rxCharacteristic == null || gatt == null) {
                 Log.w(TAG, "Write skipped: ready=$writeReady rx=${rxCharacteristic != null} gatt=${gatt != null}")
                 continue
@@ -174,6 +247,8 @@ class BleConnectionManager @Inject constructor(
                     Log.i(TAG, "Disconnected from GATT (status=$status, shouldReconnect=$shouldReconnect)")
                     rxCharacteristic = null
                     writeReady = false
+                    // Reset adapter framing state for the next connection
+                    wheelAdapter.onDisconnect()
                     // Close the GATT here so the underlying connection is fully torn down
                     try { gatt.close() } catch (_: Exception) {}
                     if (this@BleConnectionManager.gatt === gatt) {
@@ -202,17 +277,18 @@ class BleConnectionManager @Inject constructor(
                 return
             }
 
-            val nusService = gatt.getService(NUS_SERVICE_UUID)
-            if (nusService == null) {
-                Log.e(TAG, "NUS service not found")
+            val profile = wheelAdapter.bleProfile()
+            val service = gatt.getService(profile.serviceUuid)
+            if (service == null) {
+                Log.e(TAG, "Adapter service ${profile.serviceUuid} not found on this wheel")
                 return
             }
 
-            rxCharacteristic = nusService.getCharacteristic(NUS_RX_UUID)
-            val txCharacteristic = nusService.getCharacteristic(NUS_TX_UUID)
+            rxCharacteristic = service.getCharacteristic(profile.writeCharacteristic)
+            val txCharacteristic = service.getCharacteristic(profile.notifyCharacteristic)
 
             if (rxCharacteristic == null || txCharacteristic == null) {
-                Log.e(TAG, "NUS characteristics not found")
+                Log.e(TAG, "Adapter characteristics not found on service ${profile.serviceUuid}")
                 return
             }
 
@@ -232,7 +308,7 @@ class BleConnectionManager @Inject constructor(
 
             writeReady = true
             _connectionState.value = ConnectionState.CONNECTED
-            Log.i(TAG, "NUS service ready")
+            Log.i(TAG, "Service ${profile.serviceUuid} ready (adapter=${wheelAdapter.familyId})")
         }
 
         override fun onCharacteristicWrite(
@@ -263,48 +339,13 @@ class BleConnectionManager @Inject constructor(
     }
 
     /**
-     * Process incoming BLE notification data. Handles packet reassembly
-     * since NUS may split packets across multiple notifications.
+     * Forward each BLE notification to the active wheel adapter and emit any
+     * DecodeResults it produces. Framing (reassembly, parsing) lives in the
+     * adapter — each protocol family has its own.
      */
     private fun processIncomingData(data: ByteArray) {
-        reassemblyBuffer.write(data)
-        val buffer = reassemblyBuffer.toByteArray()
-
-        // Scan for complete packets
-        var start = -1
-        for (i in 0 until buffer.size - 1) {
-            if (buffer[i] == InMotionV2Protocol.HEADER && buffer[i + 1] == InMotionV2Protocol.HEADER) {
-                if (start >= 0) {
-                    // Found next header - previous packet ends here
-                    val packetBytes = buffer.copyOfRange(start, i)
-                    tryParseAndEmit(packetBytes)
-                }
-                start = i
-            }
-        }
-
-        if (start >= 0) {
-            // Try to parse from start to end of buffer
-            val candidate = buffer.copyOfRange(start, buffer.size)
-            if (candidate.size >= 5) {
-                val packet = InMotionV2Protocol.parsePacket(candidate)
-                if (packet != null) {
-                    _receivedPackets.tryEmit(packet)
-                    reassemblyBuffer.reset()
-                    return
-                }
-            }
-            // Keep remaining data in buffer
-            reassemblyBuffer.reset()
-            reassemblyBuffer.write(candidate)
-        } else {
-            // No header found, clear buffer
-            reassemblyBuffer.reset()
+        for (result in wheelAdapter.onRawNotification(data)) {
+            _decodedResults.tryEmit(result)
         }
     }
-
-    private fun tryParseAndEmit(data: ByteArray) {
-        val packet = InMotionV2Protocol.parsePacket(data) ?: return
-        _receivedPackets.tryEmit(packet)
-    }
 }

app/src/main/java/com/eried/eucplanet/ble/BleConnectionManager.kt

@@ -28,15 +28,24 @@ class BleScanner @Inject constructor(
     private val bluetoothAdapter = bluetoothManager.adapter
     private var scanCallback: ScanCallback? = null
 
+    /**
+     * Start a BLE scan and emit one [BleDevice] per advertisement match.
+     *
+     * @param showAll  when true, every named peripheral is forwarded (matches
+     *                 WheelLog's behaviour). When false, only names that match
+     *                 a known wheel prefix are forwarded — useful for keeping
+     *                 the scan list short and free of unrelated devices in
+     *                 typical usage.
+     */
     @SuppressLint("MissingPermission")
-    fun scanForDevices(): Flow<BleDevice> = callbackFlow {
+    fun scanForDevices(showAll: Boolean = false): Flow<BleDevice> = callbackFlow {
         val scanner = bluetoothAdapter?.bluetoothLeScanner
             ?: throw IllegalStateException("Bluetooth not available")
 
         val callback = object : ScanCallback() {
             override fun onScanResult(callbackType: Int, result: ScanResult) {
                 val name = result.device.name ?: return
-                if (name.startsWith("Adventure-") || name.startsWith("InMotion")) {
+                if (showAll || isLikelyWheel(name)) {
                     trySend(BleDevice(
                         name = name,
                         address = result.device.address,
@@ -63,6 +72,32 @@ class BleScanner @Inject constructor(
         }
     }
 
+    /**
+     * BLE-name allowlist for the default ("known wheels only") scan mode.
+     *
+     * V14 advertises as `Adventure-<id>`, P6 as `P6-<id>`. The InMotion V2
+     * registry covers V8 through V13 — those wheels broadcast as
+     * `V<digits><letters?>-<id>` (V11-…, V11Y-…, V12HS-…, V13Pro-…) per
+     * community captures. We don't have one of each here to confirm, so
+     * the regex errs inclusive. The generic `InMotion` prefix catches
+     * anything that ships with the brand name in the advertised name.
+     * Users with an unusual name can flip the "show all" switch on the
+     * scan screen.
+     */
+    private fun isLikelyWheel(name: String): Boolean {
+        if (name.startsWith("Adventure-")) return true
+        if (name.startsWith("P6-")) return true
+        if (name.startsWith("InMotion")) return true
+        // V8-…, V9-…, V10-…, V11-…, V11Y-…, V12HS-…, V13Pro-…: leading V
+        // followed by at least one digit and at least one more character
+        // (separator, model letter, or further digit). Rejects bare "V" /
+        // "V1" / "V12" beacons, accepts the InMotion V2 family.
+        if (name.length < 3 || name[0] != 'V' || !name[1].isDigit()) return false
+        var i = 2
+        while (i < name.length && name[i].isDigit()) i++
+        return i < name.length
+    }
+
     @SuppressLint("MissingPermission")
     fun stopScan() {
         val scanner = bluetoothAdapter?.bluetoothLeScanner ?: return