📱 Home Assistant Companion for Android
Go to file
Daniel Shokouhi 226f00b547
Update change log week of 12/20 and disable Health Connect (#4921)
* Update change log week of 12/20

* Update change log

* Tweak
2024-12-21 12:36:21 -08:00
.github Bump actions/setup-java from 4.5.0 to 4.6.0 (#4913) 2024-12-18 08:57:35 +01:00
app Update change log week of 12/20 and disable Health Connect (#4921) 2024-12-21 12:36:21 -08:00
automotive Migrate from Picasso to Coil (#4911) 2024-12-18 11:26:02 -08:00
common Add support for media players in device controls (#4917) 2024-12-21 10:41:54 -08:00
fastlane Play store text and image updates (#4448) 2024-06-21 17:33:04 +02:00
gradle Bump media3 from 1.5.0 to 1.5.1 (#4920) 2024-12-20 10:25:55 +01:00
wear Use a red icon for Wear OS debug build entity complication to make it distinguishable (#4813) 2024-11-14 10:43:03 +01:00
.editorconfig Bump org.jlleitschuh.gradle.ktlint from 11.6.1 to 12.1.0 (#4125) 2024-02-06 21:02:39 -05:00
.gitignore Updates .gitignore to not include .kotlin/ changes into git (#4647) 2024-09-16 15:42:14 +00:00
CLA.md Add required documents 2019-04-01 22:52:24 -07:00
CODE_OF_CONDUCT.md Update Code of Conduct to 2.0 (#603) 2020-05-26 09:10:31 +02:00
Gemfile Migrate deploys to Fastlane (#3745) 2023-08-01 11:08:12 -04:00
Gemfile.lock Bump rexml from 3.3.6 to 3.3.9 (#4762) 2024-10-28 18:54:26 +00:00
LICENSE.md Add required documents 2019-04-01 22:52:24 -07:00
README.md Improve wording, grammar, and punctuation in README.md (#4774) 2024-10-31 08:14:31 -07:00
build.gradle.kts Bump kotlin from 1.9.24 to 2.0.0 (#4414) 2024-06-03 08:22:03 -07:00
gradle.properties Increase heap from 2gig to 4gig (#4276) 2024-03-17 12:17:47 +01:00
gradlew Update to Gradle 8.9, Reckon 0.18.3, optimized order (#4540) 2024-07-31 20:19:57 +00:00
gradlew.bat Update to Gradle 8.9, Reckon 0.18.3, optimized order (#4540) 2024-07-31 20:19:57 +00:00
settings.gradle.kts Update to Gradle 8.9, Reckon 0.18.3, optimized order (#4540) 2024-07-31 20:19:57 +00:00

README.md

📱 Home Assistant Companion for Android Build

Documentation

If you are looking for documentation around the companion applications check out the Home Assistant Companion Documentation. This will provide you with instructions on using the applications.

Setup App Development Environment

  1. Download and install Android Studio

  2. Download / clone this repository to a folder on your computer

  3. Create a Firebase project at Firebase Console

  4. Create four Android apps, with the following package names

  • io.homeassistant.companion.android
  • io.homeassistant.companion.android.debug
  • io.homeassistant.companion.android.minimal
  • io.homeassistant.companion.android.minimal.debug
  1. Now download the google-services.json file and put it in the project's /app, /automotive and /wear folders. This file contains the configuration of the whole project (all four applications). (You can also use the mock services file instead of generating your own. The file should contain client IDs for all packages listed above for debugging to work properly. If you do not generate your own file, FCM push notification will never work, only websocket notifications will).
  2. Start Android Studio, open your source code folder, and check if the Gradle build will be successful using Build/Make Module "App". You might have to install the right Android SDK via Tools/SDK Manager first.
  3. Run gradlew assembleDebug to build all debug versions, this might take a while.
  4. If the build is successful, you can run the app by doing the following: click Run -> Run 'app'.
  5. Connect your phone or create a new virtual device following on-screen instructions.
  6. 🎉

If you get stuck while setting up your own environment, you can ask questions in the #devs_mobile_apps channel on Discord.

Push Notifications

If you want to work on push notifications or use a development build with push notifications, please go to the server-side code HERE and deploy it to your Firebase project. Once you have your androidV1 URL to the deployed service, set it in to your ${GRADLE_USER_HOME}/gradle.properties file, e.g.:

homeAssistantAndroidPushUrl=https://mydomain.cloudfunctions.net/androidV1

You can also define the rate limit function URL, e.g.:

homeAssistantAndroidRateLimitUrl=https://mydomain.cloudfunctions.net/checkRateLimits

App Flavors

The Android app has a full flavor that uses Google Play Services to offer features like location tracking and notifications. There is also a minimal flavor that does not require Google Play Services and can be found in the releases section. The minimal flavor does not have location tracking or notifications.

Building for publishing

To build the app for publishing, you will need to sign the app. To do this, do the following:

  1. Create a keystore containing a keypair for debug application signing. In Android Studio: Menu/Build/Generate signed APK, then use a button to create a new keystore. Remember the passwords and the key alias. Default, the keystore must be named release_keystore.keystore and should be placed in the home-assistant-Android/app and home-assistant-Android/wear folder.
  2. Set environmental variables used in app/build.gradle.kts:
  • KEYSTORE_PASSWORD
  • KEYSTORE_ALIAS
  • KEYSTORE_ALIAS_PASSWORD
  • KEYSTORE_PATH (if your keystore is located differently than stated above)
  1. Run gradlew build
  2. The signed APK is located in your build folder

Testing Dev Releases

We are using Github Actions to perform continuous integration both by unit testing, deploying dev releases to Play Store Beta and final releases to the Play Store when we release. To help test out a specific feature/fixes users can find the APK on the Actions page for each pull request, this debug APK can be installed side-by-side with the production or beta builds.

Quality

We are using ktlint as our linter. You can run a check locally on your machine with:

./gradlew ktlintCheck

This command runs on our CI for every PR to check if it passes all tests. So we strongly recommend running it before committing.

To run a check with an auto-format:

./gradlew ktlintFormat

Translating

The project currently uses Lokalise to translate the application. If you are interested in helping translate go to the link and click start translating!

Generating a release to production

  • Go to the latest Pre-release and edit it
  • Uncheck the Pre-release box, check the Latest release box, and click Update release
    • This should cause the Play Publish Production Workflow to execute and should handle the rest for Google Play
    • Some platforms, such as the Amazon App Store, need to be updated manually
    • F-Droid uses the version_code.txt file of the latest release to detect a new production release and build it themselves, this may take some time

Home Assistant - A project from the Open Home Foundation