Action Items: Android Companion App Implementation

[ap0ught]

Action Items: Android Companion App Implementation

This issue tracks the concrete action items for implementing the Android companion app with BLE transport.

Phase 1: C++ Core Extraction & Hardening

• 1.1 Create core/CMakeLists.txt for shared library build
• 1.2 Move protocol, puzzle_logic, mastermind_logic to core/src/
• 1.3 Remove Arduino/ESP32 includes from core headers
• 1.4 Add explicit serialization functions (writeU32LE, readU32LE, etc.)
• 1.5 Create protocol.cpp with packet encode/decode
• 1.6 Add golden packet test fixtures
• 1.7 Add unit tests (GoogleTest) for serialization, reconciliation, game logic
• 1.8 Verify ESP32 firmware still builds with extracted core

Phase 2: ESP32 BLE Transport (Host CYD)

• 2.1 Add NimBLE library to PlatformIO (h2zero/NimBLE-Arduino@^2.0.0)
• 2.2 Define Flip7 BLE Service UUID and characteristic UUIDs
• 2.3 Implement BLE GATT server on Host CYD:
  • Command characteristic (write with response)
  • Event characteristic (notify)
  • Device Info characteristic (read)
• 2.4 Implement packet fragmentation/reassembly (MTU negotiation)
• 2.5 Bridge BLE packets ↔ ESP-NOW for peer CYD forwarding
• 2.6 Handle BLE connect/disconnect gracefully (CYD remains authoritative)

Phase 3: Android App Foundation

• 3.1 Create Android Studio project with NDK/CMake
• 3.2 Configure CMake to build shared C++ core as libflip7core.so
• 3.3 Write JNI wrapper: handlePacket(byte[]), getGameState(), createMovePacket()
• 3.4 Implement BLE client: scan, connect, discover services, enable notifications
• 3.5 Kotlin BLE manager with coroutines/Flow for reactive UI

Phase 4: Android UI (Jetpack Compose)

• 4.1 Game list screen (discovered CYDs, connection status)
• 4.2 Spectator view: live game state display
• 4.3 Active game screen (Flip7 scoring, Mastermind, Greek Slide, UTTT, Periodic)
• 4.4 Move submission UI (validated by C++ core before sending)
• 4.5 Connection management (reconnect, bonding, multiple boards)

Phase 5: Integration & Testing

• 5.1 End-to-end: Android ↔ Host CYD ↔ Peer CYD
• 5.2 Test offline CYD↔CYD play (BLE disconnected)
• 5.3 Test Android reconnect mid-game
• 5.4 Test reconciliation with Android as participant
• 5.5 Stress test simultaneous BLE + ESP-NOW traffic

Next Immediate Action

Start with Phase 1.1-1.3: Extract C++ core to core/ with clean CMake build.

Dependencies

• Issue Add Android Companion App with BLE Transport #48 (parent architecture issue)
• docs/ANDROID_COMPANION_ARCHITECTURE.md added in commit 2619597

Labels

android, ble, enhancement