How home-assistant/android works
Purpose and build shape
Official Kotlin/Android client for connecting devices to Home Assistant servers, exposing the server UI plus native Android capabilities (sensors, notifications, controls, widgets, Assist, NFC, vehicle, and Wear OS). Gradle builds three principal apps: handset (app), Wear OS (wear), and Android Automotive (automotive), with shared domain/data infrastructure in common. Variant source sets distinguish full and minimal handset capabilities.
• settings.gradle.kts
• app/build.gradle.kts
• common/build.gradle.kts
Process entry points and composition
Android manifests register the application components; application classes initialize dependency injection and platform behavior. Handset startup enters LaunchActivity, which selects onboarding or the connected frontend. Additional OS-owned entry points include notification, Quick Settings, voice-assistant, controls, widget, and automotive services.
• app/src/main/AndroidManifest.xml
• app/src/main/kotlin/io/homeassistant/companion/android/HomeAssistantApplication.kt
• app/src/main/kotlin/io/homeassistant/companion/android/launch/LaunchActivity.kt
Server, authentication, and persistence boundary
common owns server selection, authenticated HTTP integration calls, TLS/trust handling, WebSocket protocol types, preferences, and Room persistence. Repository interfaces separate consumers from Retrofit/HTTP, socket, Android keystore, and database implementations. The Room database persists server/session metadata, sensor configuration, notifications, tiles, and widget state.
• common/src/main/kotlin/io/homeassistant/companion/android/common/data/servers/ServerManager.kt
• common/src/main/kotlin/io/homeassistant/companion/android/common/data/authentication/AuthenticationRepository.kt
• common/src/main/kotlin/io/homeassistant/companion/android/database/AppDatabase.kt
Primary Home Assistant data flow
After registration/authentication, feature layers use integration repositories for REST-style device registration, sensor updates, actions, and location updates; long-lived WebSocket repositories carry entity state, registry, template, conversation/Assist, Matter, and Thread responses/events. App-level WebsocketManager manages handset connectivity and reacts to Android lifecycle/network events.
• common/src/main/kotlin/io/homeassistant/companion/android/common/data/integration/IntegrationRepository.kt
• common/src/main/kotlin/io/homeassistant/companion/android/common/data/websocket/WebSocketRepository.kt
• app/src/main/kotlin/io/homeassistant/companion/android/websocket/WebsocketManager.kt
Handset experience: frontend and onboarding
The default experience is a native Compose shell around the Home Assistant web frontend. FrontendViewModel drives URL/session/UI state; handlers bridge WebView or JavaScript requests to native capabilities such as permissions, downloads, barcode scanning, dialogs, haptics, media, Bluetooth Improv provisioning, and Matter/Thread. First-run and server-change flows are a native Compose onboarding graph for discovery, manual server setup, connectivity/security, device naming, and location choices.
• app/src/main/kotlin/io/homeassistant/companion/android/frontend/FrontendScreen.kt
• app/src/main/kotlin/io/homeassistant/companion/android/frontend/handler/FrontendMessageHandler.kt
• app/src/main/kotlin/io/homeassistant/companion/android/onboarding/serverdiscovery/HomeAssistantSearcher.kt
Native capability pipelines
Sensor managers collect Android and device state; receivers/workers schedule updates, while SensorRepository serializes registration and uploads to Home Assistant. Native surfaces consume the same server/integration layer: Android Controls map HA entities to system controls; widgets store configuration locally and invoke HA actions; FCM receives server push notifications and routes actions. Assist combines voice-interaction services, audio strategies, Home Assistant assist pipelines, TTS, and optional bundled TensorFlow Lite wake-word models via a JNI/C++ module.
• common/src/main/kotlin/io/homeassistant/companion/android/common/sensors/SensorUpdater.kt
• app/src/main/kotlin/io/homeassistant/companion/android/controls/HaControlsProviderService.kt
• app/src/main/kotlin/io/homeassistant/companion/android/assist/service/AssistVoiceInteractionService.kt
Wear, automotive, and external infrastructure
Wear is a distinct Wear OS app with onboarding, home/entity views, complications, tiles, health sensors, phone data exchange, and FCM; it shares common persistence/protocol abstractions. Automotive contributes its own manifest while handset code contains the car-app service/screens. Full variants integrate Google Play services for Matter/Thread and Firebase Cloud Messaging; native wake-word execution uses CMake/JNI. CI runs GitHub Actions, including emulator E2E against a checked-in Home Assistant fixture.
• wear/src/main/kotlin/io/homeassistant/companion/android/splash/SplashActivity.kt
• app/src/full/kotlin/io/homeassistant/companion/android/matter/MatterManagerImpl.kt
• microwakeword/src/main/cpp/MicroWakeWord_jni.cpp
Main entry points: ServerManager.kt Server & authentication · IntegrationRepository.kt Integration repository · WebSocketRepository.kt WebSocket repository · LaunchActivity.kt Launch activity
Components 20
Build & variants
- Gradle multi-app build · Builds handset, Wear OS, automotive, and shared modules with full/minimal variants.
settings.gradle.kts
Shared data layer
- Server & authentication · Selects servers and manages authenticated sessions, TLS, and trust.
common/src/main/kotlin/io/homeassistant/companion/android/common/data/servers/ServerManager.kt - Authentication repository
common/src/main/kotlin/io/homeassistant/companion/android/common/data/authentication/AuthenticationRepository.kt - Integration repository · Registers devices and sends sensor, action, and location updates.
common/src/main/kotlin/io/homeassistant/companion/android/common/data/integration/IntegrationRepository.kt - WebSocket repository · Carries entity, registry, template, Assist, Matter, and Thread events.
common/src/main/kotlin/io/homeassistant/companion/android/common/data/websocket/WebSocketRepository.kt - Room app database · Stores server/session metadata and native feature state.
common/src/main/kotlin/io/homeassistant/companion/android/database/AppDatabase.kt
Handset app
- Android component registry · Registers app and OS-owned Android entry points.
app/src/main/AndroidManifest.xml - Home Assistant application · Initializes dependency injection and platform behavior.
app/src/main/kotlin/io/homeassistant/companion/android/HomeAssistantApplication.kt - Launch activity · Selects onboarding or the connected frontend.
app/src/main/kotlin/io/homeassistant/companion/android/launch/LaunchActivity.kt - Server onboarding · Discovers and configures servers, security, device name, and location.
app/src/main/kotlin/io/homeassistant/companion/android/onboarding/serverdiscovery/HomeAssistantSearcher.kt - Web frontend shell · Hosts the Home Assistant frontend with native session state.
app/src/main/kotlin/io/homeassistant/companion/android/frontend/FrontendScreen.kt - Frontend native bridge · Bridges web requests to Android permissions and device capabilities.
app/src/main/kotlin/io/homeassistant/companion/android/frontend/handler/FrontendMessageHandler.kt - Handset WebSocket manager · Maintains socket connectivity across lifecycle and network changes.
app/src/main/kotlin/io/homeassistant/companion/android/websocket/WebsocketManager.kt
Native surfaces
- Sensor update pipeline · Collects Android state and serializes registration and uploads.
common/src/main/kotlin/io/homeassistant/companion/android/common/sensors/SensorUpdater.kt - Android controls · Maps Home Assistant entities to Android system controls.
app/src/main/kotlin/io/homeassistant/companion/android/controls/HaControlsProviderService.kt - Assist voice service · Connects audio, Assist pipelines, TTS, and wake-word handling.
app/src/main/kotlin/io/homeassistant/companion/android/assist/service/AssistVoiceInteractionService.kt
Wear, automotive & native
- Wear OS app · Provides Wear onboarding, entities, tiles, complications, sensors, and phone exchange.
wear/src/main/kotlin/io/homeassistant/companion/android/splash/SplashActivity.kt - Matter & Thread integration · Uses Google Play services in full handset variants.
app/src/full/kotlin/io/homeassistant/companion/android/matter/MatterManagerImpl.kt - Micro wake-word JNI · Runs bundled TensorFlow Lite wake-word models.
microwakeword/src/main/cpp/MicroWakeWord_jni.cpp
Other components
- Home Assistant server · Provides frontend, authenticated APIs, WebSocket events, and Assist services.
Connections 25
- Gradle multi-app build → Home Assistant application: builds handset
- Gradle multi-app build → Wear OS app: builds Wear app
- Android component registry → Home Assistant application: starts
- Android component registry → Launch activity: registers
- Home Assistant application → Launch activity: initializes
- Launch activity → Server onboarding: unregistered server
- Launch activity → Web frontend shell: connected session
- Server onboarding → Server & authentication: registers server
- Web frontend shell → Frontend native bridge: native requests
- Web frontend shell → Server & authentication: uses session
- Frontend native bridge → Integration repository: native actions
- Server & authentication → Authentication repository: authenticates
- Server & authentication → Room app database: persists sessions
- Authentication repository → Home Assistant server: authentication
- Integration repository → Home Assistant server: REST calls
- Handset WebSocket manager → WebSocket repository: maintains connection
- WebSocket repository → Home Assistant server: events and responses
- Sensor update pipeline → Integration repository: uploads state
- Android controls → WebSocket repository: entity state
- Android controls → Integration repository: invokes actions
- Assist voice service → WebSocket repository: Assist conversations
- Assist voice service → Micro wake-word JNI: optional detection
- Matter & Thread integration → WebSocket repository: Matter and Thread events
- Wear OS app → Server & authentication: shares server access
- Wear OS app → Integration repository: sensor and action calls