Android Companion App via BLE: Architecture & Implementation

[ap0ught]

Android Companion App via BLE: Architecture & Implementation

Overview

Add an Android companion application that communicates with CYD boards via Bluetooth Low Energy (BLE) while preserving the existing ESP-NOW synchronization between the two CYD boards.

Architecture Document

See docs/ANDROID_COMPANION_ARCHITECTURE.md (to be added) for full specification.

Key Architectural Decisions (ADRs)

ADR	Decision	Rationale
ADR-001	Retain ESP-NOW for CYD↔CYD	Already implemented, encrypted, offline-capable
ADR-002	BLE for Android↔CYD	Both boards verified BLE; Android native BLE APIs
ADR-003	Shared C++ core via JNI/NDK	Single authoritative game/protocol implementation
ADR-004	Explicit packet serialization	No struct memory layout dependence
ADR-005	Spectator mode first	Validate transport before multi-writer sync
ADR-006	CYDs remain authoritative	Boards work offline when phone disconnects
ADR-007	BLE over BT Classic	GATT model, low power, notifications

System Architecture

[Android Phone] <---> BLE GATT <---> [CYD Host/Gateway] <---> ESP-NOW <---> [CYD Peer]
    ^                                              ^
Kotlin +                            C++ Core (shared)
Jetpack Compose                     (JNI on Android)

Phased Implementation Plan

Phase 1: Core Extraction & Protocol Hardening

• Extract platform-neutral C++ logic into core/ (protocol, packet, serializer, reconciliation, active_game, mastermind, puzzle, aquarium)
• Remove Arduino/ESP32 dependencies from core
• Define explicit packet serialization (replace raw struct memcpy)
• Add packet versioning, integrity checks, message IDs, origin tracking
• Create golden packet tests (desktop + ESP32 + Android)
• Exit criteria: Existing CYD firmware builds and behaves identically using extracted core

Phase 2: BLE Spectator Transport (Android Connects, Read-Only)

• Add Flip7 BLE GATT service to CYD firmware
  • Command characteristic (Android → CYD write)
  • Event characteristic (CYD → Android notify)
  • Device info characteristic (protocol version, board ID, active game, etc.)
• Implement BLE fragmentation/reassembly (MTU negotiation)
• Send snapshots on connect, after actions, on request, periodically
• Keep Android read-only (spectator)
• Exit criteria: Android can connect, reconnect, display live synchronized game state

Phase 3: Android Native Core Integration

• Configure Android NDK + CMake in Android project
• Compile shared C++ core into APK
• Add JNI adapter (narrow byte-oriented API)
• Run golden protocol tests on Android
• Validate incoming packets natively before display
• Exit criteria: Android and ESP32 produce matching protocol results

Phase 4: Android Player Actions

• Add action packet types (start game, join, submit move, guess, exit)
• Add authentication/role assignment (spectator/player/controller/admin)
• Validate Android actions through shared core
• Forward accepted changes through ESP-NOW to peer CYD
• Conflict and retry handling
• Exit criteria: Android can participate without causing state divergence

Phase 5: Persistence & History

• Save match history on Android
• Export functionality
• Optional CYD persistence
• Statistics dashboards

Current State

• ✅ Both CYD boards verified: BLE, BT Classic, Dual-mode, WiFi, ESP-NOW, Dual-core
• ✅ Core game logic already partially extracted to core/include/
• ✅ Protocol definitions in include/protocol.h with static_assert wire format checks
• ✅ ESP-NOW synchronization working with encryption

Action Items (Start Here)

1. Add architecture doc to repo - Move the architecture specification into docs/
2. Create Android project skeleton - Kotlin + Jetpack Compose + NDK + CMake
3. Finish core extraction - Move remaining platform-neutral logic from main.cpp to core/
4. Define explicit serialization - Replace struct memcpy with explicit read/write
5. Add BLE GATT service - Command/Event characteristics on CYD

Relevant Files

• Firmware: src/main.cpp, include/protocol.h, core/include/
• Architecture: (to be added) docs/ANDROID_COMPANION_ARCHITECTURE.md
• Android: (new) android/ directory

Labels

android, ble, architecture, enhancement