feat(car): Android Car App Library integration

[jamesarich]

Summary

Full Android Car App Library integration for Meshtastic — delivering a distraction-optimized, safety-first mesh radio interface for Android Auto and AAOS.

Features

Messaging (ConversationItem API — official required pattern)

• Native ConversationItem template with built-in TTS readout, voice reply, and mark-as-read
• ConversationCallback handles reply via SendMessageUseCase (homoglyph encoding, message queuing, persistence)
• Channel conversations + DM conversations ordered by recency
• Group conversation detection for channels (3+ participants)

Node Dashboard

• All mesh nodes with signal quality coloring (Excellent/Good/Fair/Bad/None)
• Per-node colored icons via nodeColorsFromNum()
• Battery percentage, last-heard time, signal indicators
• Node detail drill-down

Device Status Tab

• Battery level, channel utilization, air utilization
• Online/total node count, uptime, TX/RX packet counts
• Mirrors the home-screen Local Stats widget metrics

Emergency Alerts

• Alert.Builder modal alerts (API 8+) with 10s duration
• Emergency spotlight section in messaging list
• Graceful fallback on API 7 hosts (notification-only)

Notification Integration

• MessagingStyle notifications with proper SEMANTIC_ACTION_REPLY / SEMANTIC_ACTION_MARK_AS_READ
• ConversationShortcutManager publishes dynamic shortcuts for favorites + channels
• PersonIconFactory renders circular avatars with node-colored initials
• LocusIdCompat links notifications ↔ template conversations
• CarReplyReceiver handles inline reply and mark-as-read

Safety & Security

• minCarApiLevel = 7 with graceful API 8 feature fallbacks
• android:permission="androidx.car.app.CarAppService" on service
• MessageFilter.validateOutgoing() enforces 237-byte Meshtastic packet limit
• CoroutineExceptionHandler on all scopes to prevent silent failures
• PII stripped from logs (char count only, not content)
• Explicit CarReplyReceiver (android:exported=false) for notification actions

Architecture

• Module: feature/car — zero modifications to existing core/feature modules
• DI: Koin annotations (@Factory, @Single) with proper module
• Data flow: Reactive StateFlow collection → debounced invalidate()
• Testability: CarScreenDataBuilder — pure functions with 533-line unit test suite
• Coordinator pattern: CarStateCoordinator bridges repositories to car UI state

Comparison with PR #5162

This implementation supersedes #5162 (feat(auto)) with:

• ✅ Official ConversationItem API (required for MESSAGING category)
• ✅ 3-tab layout (Messages / Nodes / Status) vs 3-tab (Status / Favorites / Messages)
• ✅ Emergency alert system (Alert API + EmergencyHandler)
• ✅ Signal quality coloring + node-colored icons
• ✅ ConversationShortcutManager + PersonIconFactory
• ✅ API 7 minimum with API 8 graceful fallbacks
• ✅ Full spec/plan/tasks/checklists documentation (65/65 items)
• ✅ 533-line unit test suite for business logic

Technical Details

• Min Car API: 7 (ConversationItem)
• CAL Version: 1.9.0-alpha01
• Target: Android Auto (phone projection) + AAOS
• Categories: MESSAGING (template + notification)
• Templated messaging: Beta (internal/closed testing tracks)

Verification

spotlessCheck ✓ | detekt ✓ | compileFdroidDebugKotlin ✓ | testFdroidDebugUnitTest ✓

Files (22 Kotlin + resources)

Module structure

feature/car/
├── src/main/kotlin/org/meshtastic/feature/car/
│   ├── alerts/EmergencyHandler.kt
│   ├── di/FeatureCarModule.kt
│   ├── model/CarUiModels.kt
│   ├── panels/MeshStatusPanel.kt
│   ├── panels/MeshStatusSessionWiring.kt
│   ├── screens/
│   │   ├── ChannelChipBuilder.kt
│   │   ├── EmergencySpotlightBuilder.kt
│   │   ├── HomeScreen.kt
│   │   ├── MessagingScreen.kt
│   │   ├── NodeDashboardScreen.kt
│   │   └── NodeDetailScreen.kt
│   ├── service/
│   │   ├── CarNotificationManager.kt
│   │   ├── CarReplyReceiver.kt
│   │   ├── CarStateCoordinator.kt
│   │   ├── ConversationShortcutManager.kt
│   │   ├── MeshtasticCarAppService.kt
│   │   └── MeshtasticCarSession.kt
│   └── util/
│       ├── CarScreenDataBuilder.kt
│       ├── CrashlyticsCarTagger.kt
│       ├── FuzzyNodeNameResolver.kt
│       ├── MessageFilter.kt
│       ├── NodeSubtitleFormatter.kt
│       └── PersonIconFactory.kt
├── src/test/kotlin/.../util/
│   ├── CarScreenDataBuilderTest.kt (533 lines)
│   ├── FuzzyNodeNameResolverTest.kt
│   └── MessageFilterTest.kt
└── src/main/res/
    ├── drawable/ (icons)
    ├── values/strings.xml
    └── xml/automotive_app_desc.xml

[github-actions]

✅ Docs staleness check passed

This PR includes updates to docs/en/ alongside the source changes. Thank you!

[jamesarich]

🔗 Release 2.8.0 Integration Report

Branch: release/2.8.0 | Status: ✅ Demo verified on emulator

Integration Changes Required

1. HomeScreen.kt — After AIDL removal (refactor: Remove AIDL API and modernize service architecture #5586), ServiceRepository.connectionState changed from a direct property to a StateFlow. Updated Car App HomeScreen to collect from the flow instead of reading a snapshot value.

2. ConversationShortcutManager.kt — PacketRepository API changed: getContactList() return type evolved from List<Contact> to Flow<List<Contact>> (now reactive). Updated to .first() for one-shot usage in car shortcuts.

3. CarScreenDataBuilder.kt — NodeEntity field access changed after discovery PR (feat(discovery): mesh network discovery #5275) added new fields. Builder needed adjustment for the expanded node model.

4. FlavorModule.kt — Car module DI registration merged alongside App Functions module registration in the shared Google flavor module.

Merge Guidance

• Merge order: Should merge second (after feat(ai): Add App Functions for system AI integration #5585 App Functions, before refactor: Remove AIDL API and modernize service architecture #5586 AIDL removal)
• Key dependency: After AIDL removal merges, ServiceRepository APIs change significantly. The car module references connectionState, meshStatus, and packet queries — all affected.
• Recommendation: Rebase onto AIDL removal branch to pre-adapt, OR plan a fixup commit post-merge of refactor: Remove AIDL API and modernize service architecture #5586