diff --git a/BatteryReporting.md b/BatteryReporting.md index 6634f7d..9207249 100644 --- a/BatteryReporting.md +++ b/BatteryReporting.md @@ -1,8 +1,40 @@ # Battery Reporting -# TODO: app settings config and screen shots for getting the device id +From version 2.1 the application includes a background service to report the current device battery level and charging status back to Home Assistant. This is a feature that Garmin omitted to include with the Bluetooth connection. -The watch will send HTTP requests to HomeAssistant every 5 minutes in a background service. The events produced by the HTTP requests can be listened for with a template entity. In this case we have two (battery level and is charging). +## Start Reporting + +The main drawback of this solution is that the Garmin application must be run once with the feature enabled in the settings before reporting will start. Reporting continues after you have exited the application. This is a limit we cannot code around. + +## Stop Reporting + +To stop the reporting, the option must be turned off in the settings and then the application run once. Running the application then removes the background service. + +In both cases, the enable and repeat time settings can be changed whilst the application is running (i.e. live) and the background service will be amended. + +## Listening for the `device_id` + + + +```yaml +event_type: garmin.battery_level +data: + level: 45.072266 + device_id: e1004acb747607bc205a6ff7bd05a4c12faf3d6d + is_charging: false +origin: REMOTE +time_fired: "2024-01-01T18:15:35.900991+00:00" +context: + id: 01HK33T06WW4D9NEXJ9F6SRYNY + parent_id: null + user_id: 35e0e5a7e4bc49e9a328743697c58b90 +``` + +The `device_id` is consistent for our purposes. It does change between devices and also between the 'application' and 'widget' installations. Different device model simulators also vary the `device_id`. Here we want to extract `e1004acb747607bc205a6ff7bd05a4c12faf3d6d` for use in the sample YAML `trigger` above. + +## Setting up the trigger to update the entity + +The watch will send HTTP requests to HomeAssistant every 5+ minutes in a background service. The events produced by the HTTP requests can be listened for with a template entity. In this case we have two (battery level and is charging). ```yaml - trigger: @@ -37,4 +69,8 @@ The watch will send HTTP requests to HomeAssistant every 5 minutes in a backgrou 1. Copy this yaml to your `configuration.yaml`. 2. Swap `` for the name of your device (This can be anything and is purely for the UI). Swap `` and `` for two different unique identifiers (in the Studio Code Server these can be generated from the right click menu). 3. Open the [event dashboard](https://my.home-assistant.io/redirect/developer_events/) and start listening for `garmin.battery_level` events and when your recieve one copy the device id and replace `` with it (to speed up this process you can close and reopen the GarminHomeAssistant app). -4. Restart HomeAssistant or reload the yaml [here](https://my.home-assistant.io/redirect/server_controls/). +4. Restart HomeAssistant or reload the YAML [here](https://my.home-assistant.io/redirect/server_controls/). + +## Adding a sample Home Assistant UI widget + +## TODO: YAML for a dashboard diff --git a/README.md b/README.md index 71c8edd..cbb12aa 100644 --- a/README.md +++ b/README.md @@ -265,6 +265,10 @@ The `id` attribute values are taken from the same names used in [`strings.xml`]( * The Python script will use the corrections in preference to translating, and * Your pull request will be honoured without comment as we will take your corrections on trust. +## Battery Level Reporting + +The application and widget both now include a background service to report your watch's battery level and charging status. This requires [significant setup](BatteryReporting.md) via YAML in Home Assistant to work. This is not for the feint hearted! + ## Version History | Version | Comment | @@ -278,7 +282,7 @@ The `id` attribute values are taken from the same names used in [`strings.xml`]( | 1.6 | Added a user configurable 'timeout' in seconds so that when no action is taken the application automatically closes, stopping the continuous polling for changes of status and hence saving the drain on the battery. This can be disabled with timeout=0. | | 1.7 | Added timeout to confirmation views so that when used for security devices it does not linger when left unconfirmed. Thanks to [Jan Schneider](https://github.com/j-a-n) for the contribution. Known bug for devices not supporting [`WatchUi.getCurrentView()`](https://developer.garmin.com/connect-iq/api-docs/Toybox/WatchUi.html#getCurrentView-instance_function) API call which is only available on API Level 3.4.0, e.g. Vivoactive 4S. | | 2.0 | A significant code base change to enable both a 'widget' version for older devices, e.g. Venu (1), and an application with a glance, e.g. Venu2. These two versions must now be distributed under separate application IDs, but they have the same code base. A further 20 more devices are now supported, the settings have been internationalised, and there's a bug fix for older devices when trying to display a helpful error message but instead the application crashed. This version has come from a significant collaboration with [Someone0nEarth](https://github.com/Someone0nEarth). | -| 2.1 | Deployment of an idea to provide Home Assistant with access to the watch battery level. Using this requires significant setup on the Home Assistant configuration and will be detailed separately. Due to this, the default state for this battery option is _off_. Changed the application settings user interface to be more intuitive, and hence amended the way settings are managed in the background. | +| 2.1 | Deployment of an idea to provide Home Assistant with access to the watch battery level. Using this requires [significant setup](BatteryReporting.md) on the Home Assistant configuration and will be detailed separately. Due to this, the default state for this battery option is _off_. Changed the application settings user interface to be more intuitive, and hence amended the way settings are managed in the background. | ## Known Issues diff --git a/images/Battery_Event_Screenshot.png b/images/Battery_Event_Screenshot.png new file mode 100644 index 0000000..60a1574 Binary files /dev/null and b/images/Battery_Event_Screenshot.png differ diff --git a/images/GarminHomeAssistantSettings.png b/images/GarminHomeAssistantSettings.png index 7d4e228..2583f59 100644 Binary files a/images/GarminHomeAssistantSettings.png and b/images/GarminHomeAssistantSettings.png differ diff --git a/images/source/Options1.jpg b/images/source/Options1.jpg new file mode 100644 index 0000000..3c87b68 Binary files /dev/null and b/images/source/Options1.jpg differ diff --git a/images/source/Options2.jpg b/images/source/Options2.jpg new file mode 100644 index 0000000..d6755b2 Binary files /dev/null and b/images/source/Options2.jpg differ