|
1 | | -# Home Assistant Companion for Android [](https://github.com/home-assistant/android/actions/workflows/onPush.yml) |
| 1 | +# Home Assistant Companion for Android |
2 | 2 |
|
3 | | -## Documentation |
4 | | -If you are looking for documentation around the companion applications check out the [Home Assistant Companion Documentation](https://companion.home-assistant.io/). This will provide you with instructions on using the applications. |
5 | | - |
6 | | -## Setup App Development Environment |
7 | | - |
8 | | -1. Download and install [Android Studio](https://developer.android.com/studio) |
9 | | - |
10 | | -2. Download / clone this repository to a folder on your computer |
11 | | - |
12 | | -3. Create a Firebase project at [Firebase Console](https://console.firebase.google.com) |
| 3 | +[](https://github.com/home-assistant/android/actions/workflows/onPush.yml) |
| 4 | +[](https://play.google.com/store/apps/details?id=io.homeassistant.companion.android) |
| 5 | +[](https://play.google.com/apps/testing/io.homeassistant.companion.android) |
| 6 | +[](https://discord.gg/c5DvZ4e) |
| 7 | +[](https://github.com/home-assistant/android/stargazers) |
13 | 8 |
|
14 | | -4. Create four Android apps, with the following package names |
15 | | - - `io.homeassistant.companion.android` |
16 | | - - `io.homeassistant.companion.android.debug` |
17 | | - - `io.homeassistant.companion.android.minimal` |
18 | | - - `io.homeassistant.companion.android.minimal.debug` |
| 9 | +Welcome to the **Home Assistant Companion for Android**! This is the official Android app for [Home Assistant](https://www.home-assistant.io/), a powerful open-source home automation platform. Join us in building an app used by millions of users worldwide. |
19 | 10 |
|
20 | | -5. 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](/.github/mock-google-services.json). 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**). |
21 | | -6. 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. |
22 | | -7. Run `gradlew assembleDebug` to build all debug versions, this might take a while. |
23 | | -8. If the build is successful, you can run the app by doing the following: click **Run** -> **Run 'app'**. |
24 | | -9. Connect your phone or create a new virtual device following on-screen instructions. |
25 | | -10. :tada: |
| 11 | +--- |
26 | 12 |
|
27 | | -If you get stuck while setting up your own environment, you can ask questions in the **#devs_mobile_apps** channel on [Discord](https://discord.gg/c5DvZ4e). |
| 13 | +## Features |
28 | 14 |
|
29 | | -### Push Notifications |
| 15 | +- **Control Your Smart Home**: Seamlessly interact with your Home Assistant instance. |
| 16 | +- **Native Android Experience**: Leverage Android-specific features like widgets, notifications, and location tracking. |
| 17 | +- **Customizable**: Tailor the app to your needs with themes, dashboards, and more. |
| 18 | +- **Open Source**: Contribute to a project that empowers users to take control of their smart homes. |
30 | 19 |
|
31 | | -If you want to work on push notifications or use a development build with push notifications, please go to the server-side code [HERE](https://github.com/home-assistant/mobile-apps-fcm-push) 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.: |
32 | | -```properties |
33 | | -homeAssistantAndroidPushUrl=https://mydomain.cloudfunctions.net/androidV1 |
34 | | -``` |
| 20 | +## Get the app |
35 | 21 |
|
36 | | -You can also define the rate limit function URL, e.g.: |
37 | | -```properties |
38 | | -homeAssistantAndroidRateLimitUrl=https://mydomain.cloudfunctions.net/checkRateLimits |
39 | | -``` |
| 22 | +- **[Download from the Play Store](https://play.google.com/store/apps/details?id=io.homeassistant.companion.android)** |
| 23 | + Join the [Play Store Beta](https://play.google.com/apps/testing/io.homeassistant.companion.android) to test new features early. |
| 24 | +- **Other Stores**: The app is also available in other app stores. |
40 | 25 |
|
41 | | -## App Flavors |
42 | | - |
43 | | -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. |
44 | | - |
45 | | -## Building for publishing |
46 | | - |
47 | | -To build the app for publishing, you will need to sign the app. To do this, do the following: |
48 | | -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. |
49 | | -2. Set environmental variables used in `app/build.gradle.kts`: |
50 | | - - `KEYSTORE_PASSWORD` |
51 | | - - `KEYSTORE_ALIAS` |
52 | | - - `KEYSTORE_ALIAS_PASSWORD` |
53 | | - - `KEYSTORE_PATH` (if your keystore is located differently than stated above) |
54 | | -3. Run `gradlew build` |
55 | | -4. The signed APK is located in your build folder |
| 26 | +## Documentation |
56 | 27 |
|
57 | | -## Testing Dev Releases |
| 28 | +Looking for help? Check out the [Home Assistant Companion Documentation](https://companion.home-assistant.io/) for detailed guides on using the app. |
58 | 29 |
|
59 | | -We are using [Github Actions](https://github.com/home-assistant/android/actions) to perform continuous integration both by unit testing, deploying dev releases to [Play Store Beta](https://play.google.com/apps/testing/io.homeassistant.companion.android) and final releases to the [Play Store](https://play.google.com/store/apps/details?id=io.homeassistant.companion.android) 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. |
| 30 | +## Report a bug or request a feature |
60 | 31 |
|
61 | | -## Quality |
| 32 | +Found a bug or have an idea for a new feature? Let us know! |
62 | 33 |
|
63 | | -We are using [ktlint](https://ktlint.github.io/) as our linter. |
64 | | -You can run a check locally on your machine with: |
65 | | -```bash |
66 | | -./gradlew ktlintCheck |
67 | | -``` |
68 | | -This command runs on our CI for every PR to check if it passes all tests. So we strongly recommend running it before committing. |
| 34 | +- **[Open a Bug Report](https://github.com/home-assistant/android/issues/new?template=Bug_report.md)** |
| 35 | +- **[Request a Feature](https://github.com/home-assistant/android/issues/new?template=feature_request.md)** |
69 | 36 |
|
70 | | -To run a check with an auto-format: |
71 | | -```bash |
72 | | -./gradlew ktlintFormat |
73 | | -``` |
| 37 | +We appreciate your feedback and contributions to make the app even better! |
74 | 38 |
|
75 | | -## Translating |
76 | | -The project currently uses [Lokalise](https://lokalise.com/public/145814835dd655bc5ab0d0.36753359/) to translate the application. If you are interested in helping translate go to the link and click start translating! |
| 39 | +## Contributing |
77 | 40 |
|
| 41 | +We are thrilled to welcome contributions from the community! This app exists thanks to the incredible efforts of the Home Assistant community. Whether you're fixing bugs, adding new features, or improving documentation, your contributions make a difference. |
78 | 42 |
|
79 | | -## Generating a release to production |
80 | | -* Go to the latest Pre-release and edit it |
81 | | -* Uncheck the Pre-release box, check the Latest release box, and click Update release |
82 | | - * This should cause the `Play Publish Production` Workflow to execute and should handle the rest for Google Play |
83 | | - * Some platforms, such as the Amazon App Store, need to be updated manually |
84 | | - * 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 |
| 43 | +Every contribution, big or small, is greatly appreciated. Together, we can make the Home Assistant Companion for Android even better! |
85 | 44 |
|
86 | | -## Managing Dependencies and Lockfiles |
| 45 | +### Getting started |
87 | 46 |
|
88 | | -This project utilizes Gradle's [dependency locking](https://docs.gradle.org/current/userguide/dependency_locking.html) feature to ensure consistent and reproducible builds by tracking the precise versions of all libraries used. |
| 47 | +1. Read the [Developer Guide](https://developers.home-assistant.io/docs/android/). |
| 48 | +2. Fork the repository and create a branch for your changes. |
| 49 | +3. Submit a pull request and join the discussion! |
89 | 50 |
|
90 | | -**Updating Dependencies and Lockfiles** |
| 51 | +## Join the community |
91 | 52 |
|
92 | | -When adding or updating a dependency in `gradle/libs.versions.toml`, it's crucial to also update the corresponding lockfiles. This is necessary because the lockfiles capture the exact versions of all direct and transitive dependencies. |
| 53 | +Connect with other contributors and users in our vibrant **[Discord Community](https://discord.gg/c5DvZ4e)**: Join the **[#Android](https://discord.com/channels/330944238910963714/1346948551892009101)** channel to chat with developers and contributors. |
93 | 54 |
|
94 | | -To update the lockfiles, run the following command from the project root `./gradlew alldependencies --write-locks` |
95 | | -This command will resolve all dependencies and update the `gradle.lockfile` in each module. |
| 55 | +## Star the repository |
96 | 56 |
|
97 | | -**Automated Dependency Updates with Renovate** |
| 57 | +If you find this project useful, consider giving it a star on GitHub! |
| 58 | +It helps others discover the project and motivates us to keep improving. |
98 | 59 |
|
99 | | -To streamline dependency management, we've integrated [Renovate](https://docs.renovatebot.com/) into this repository. Renovate automatically creates pull requests to update dependencies and their associated lockfiles. |
| 60 | +<a href="https://next.ossinsight.io/widgets/official/analyze-repo-stars-history?repo_id=179008173" target="_blank" style="display: block" align="center"> |
| 61 | + <picture> |
| 62 | + <source media="(prefers-color-scheme: dark)" srcset="https://next.ossinsight.io/widgets/official/analyze-repo-stars-history/thumbnail.png?repo_id=179008173&image_size=auto&color_scheme=dark" width="721" height="auto"> |
| 63 | + <img alt="Star History of home-assistant/android" src="https://next.ossinsight.io/widgets/official/analyze-repo-stars-history/thumbnail.png?repo_id=179008173&image_size=auto&color_scheme=light" width="721" height="auto"> |
| 64 | + </picture> |
| 65 | +</a> |
100 | 66 |
|
101 | 67 | [](https://www.openhomefoundation.org/) |
0 commit comments