Android

The Android app started in 2019 and is now used by millions of people. Its center is a web view that shows the Home Assistant frontend. Around it sit native features: sensors that report from the phone, notifications, widgets, tiles, NFC tags, Assist, a Wear OS app, and car screens for Android Auto and Android Automotive.

The project is written entirely in Kotlin. New UI is Jetpack Compose. You will still find older code, like XML layouts and view binding, that predates the current guidelines. That code is migrated over time, and the pages here describe how new code should look.

Everything lives in home-assistant/android. It is one Gradle project with several modules:

Module	What it is
:app	The phone and tablet app
:automotive	The Android Automotive app. Reuses the sources of :app
:wear	The Wear OS app
:common	Code shared by all apps: the data layer, sensors, the WebSocket and REST clients, the design system, and all strings
:testing-unit	Helpers shared by the unit tests of every module
:lint	The custom lint rules of the project
:microwakeword	On-device wake word detection
:provides-sensor-processor	A code generator for sensor registration
build-logic	Convention plugins that configure every module the same way

The minimum and target SDK versions are in gradle/libs.versions.toml, under the androidSdk-* keys.

• Get started: install Android Studio, build the app, and run it.
• Push notifications: set up your own Firebase project, if you work on notifications.

• Architecture: the principles, the tech stack, and how the modules fit together.
• UI architecture: how a screen is built, from the view down to the repositories.
• The frontend screen: the screen that hosts the web view, and the reference implementation of the UI architecture.
• Flavors and targets: full and minimal, and the phone, car, watch, and TV builds.

• Compose and the design system: building UI with HATheme and the HA* components.
• Best practices: strong types, concurrency, dependency injection, and failing fast.
• Code style and linting: KTLint, Detekt, and the Android linter.
• Dependencies: the version catalog, lockfiles, and Renovate.
• Debug tools: the developer playground, StrictMode, and LeakCanary.

• Testing: how to write tests, and unit tests with JUnit, MockK, Robolectric, and Turbine.
• Screenshot tests
• Instrumentation tests
• End-to-end tests

• Submit a pull request: the checklist, the template, and the review.
• Continuous integration: what runs on your pull request, and after it is merged.
• Releases: from a merged pull request to the Play Store, and building a signed release yourself.

• The Android project thread on the Home Assistant Discord. Pick the developer role under Channels & Roles first.
• Issues in the Android repository, for bugs and feature requests.
• For how the app works for users, see the companion app documentation.