remi/GarminHomeAssistant
1
0
Fork 0
mirror of https://github.com/house-of-abbey/GarminHomeAssistant.git synced 2025-05-02 13:42:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
Joseph Abbey
2024-01-11 21:20:58 +00:00
parent 22bb84e13b
commit d4588f02b9
3 changed files with 48 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
BatteryReporting.md
View File

@ -2,91 +2,27 @@
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.
We've had [a report](https://github.com/house-of-abbey/GarminHomeAssistant/issues/39) that this feature does not work without **administrator priviledges**. We've reviewed possible fixes and come up short. We are unable to fix this at present but invite those skilled in the art of Home Assistant to suggest a solution to us!
## 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.
It should be as simple as that, there should be a new device in the mobile app integration called `Garmin Watch` with the battery level and charging status.
[![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=mobile_app)
If this is not the case, head over to the [troubleshooting page](Troubleshooting.md#watch-battery-level-reporting).
## 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`
Open the event viewer in Home Assistant and add `garmin.battery_level` as the event to listen to as shown below.
[![Open your Home Assistant instance and show your event developer tools.](https://my.home-assistant.io/badges/developer_events.svg)](https://my.home-assistant.io/redirect/developer_events/)
<img src="images/Battery_Event_Screenshot.png" width="600" title="Listening for battery events"/>
```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:
- platform: "event"
event_type: "garmin.battery_level"
event_data:
device_id: "<device-id>"
sensor:
- name: "<device-name> Battery Level"
unique_id: "<uid-0>"
device_class: "battery"
unit_of_measurement: "%"
state_class: "measurement"
state: "{{ trigger.event['data']['level'] }}"
icon: mdi:battery{% if trigger.event['data']['is_charging'] %}-charging{% endif %}{% if 0 < (trigger.event['data']['level'] | float / 10 ) | round(0) * 10 < 100 %}-{{ (trigger.event['data']['level'] | float / 10 ) | round(0) * 10 }}{% else %}{% if (trigger.event['data']['level'] | float / 10 ) | round(0) * 10 == 0 %}-outline{% else %}{% if trigger.event['data']['is_charging'] %}-100{% endif %}{% endif %}{% endif %}
attributes:
device_id: "<device-id>"
- trigger:
- platform: "event"
event_type: "garmin.battery_level"
event_data:
device_id: "<device-id>"
binary_sensor:
- name: "<device-name> is Charging"
unique_id: "<uid-1>"
device_class: "battery_charging"
state: "{{ trigger.event['data']['is_charging'] }}"
attributes:
device_id: "<device-id>"
```
1. Copy this yaml to your `configuration.yaml`.
2. Swap `<device-name>` for the name of your device (This can be anything and is purely for the UI). Swap `<uid-0>` and `<uid-1>` for two different unique identifiers (in the Studio Code Server these can be generated from the right click menu).
3. Open the event dashboard and start listening for `garmin.battery_level` events and when your recieve one copy the device id and replace `<device-id>` with it (to speed up this process you can close and reopen the GarminHomeAssistant app).
[![Open your Home Assistant instance and show your event developer tools.](https://my.home-assistant.io/badges/developer_events.svg)](https://my.home-assistant.io/redirect/developer_events/)
4. Restart HomeAssistant or reload the YAML.
[![Open your Home Assistant instance and show your server controls.](https://my.home-assistant.io/badges/server_controls.svg)](https://my.home-assistant.io/redirect/server_controls/)
## Adding a sample Home Assistant UI widget
A gauge for battery level with a chargin icon making use of [mushroom cards](https://github.com/piitaya/lovelace-mushroom), [card_mod](https://github.com/thomasloven/lovelace-card-mod) and [stack-in-card](https://github.com/custom-cards/stack-in-card):
A gauge for battery level with a charging icon making use of [mushroom cards](https://github.com/piitaya/lovelace-mushroom), [card_mod](https://github.com/thomasloven/lovelace-card-mod) and [stack-in-card](https://github.com/custom-cards/stack-in-card):
<img src="images/Battery_Guage_Screenshot.png" width="120" title="Battery Guage"/>
<img src="images/Battery_Guage_Screenshot.png" width="120" title="Battery Gauge"/>
```yaml
type: custom:stack-in-card

52
Troubleshooting.md
View File

@ -110,7 +110,7 @@ There's an online way of testing the API URL too, thanks to [REQBIN](https://req
## Watch Battery Level Reporting
For this you will need to have already got the main application or widget working with a menu in order to prove that the API calls are successful. We have proven this works with both our home brew infrastructure as well as Nabu Casa. Now with a script similar to one of the following two, you should be able to fake the watch API call and verify receipt by Home Assistant in the Event logging as shown in '[Listening for the `device_id`](BatteryReporting.md#listening-for-the-device_id)'.
For this you will need to have already got the main application or widget working with a menu in order to prove that the API calls are successful. We have proven this works with both our home brew infrastructure as well as Nabu Casa. Now with a script similar to one of the following two, you should be able to fake the watch API call and verify receipt by Home Assistant.
#### Battery: Linux, MacOS, UNIX, Cygwin etc
@ -123,7 +123,7 @@ Assume a file called: `send_battery.bash`
# ./send_battery.bash 19 0
#
API_KEY="<Your API key>"
WEBHOOK_ID="<Your Webhook ID>"
URL="https://<Your Domain>/api"
level=${1:-50}
@ -138,10 +138,9 @@ echo "Battery Charging? = ${is_charging}"
echo ""
curl -s -X POST \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{"level": '${level}', "is_charging": '${is_charging}', "device_id": "Bash Script"}' \
${URL}/events/garmin.battery_level
-d '{ "type": "update_sensor_states", "data": [ {"state": ${level},"type": "sensor","unique_id": "battery_level"}, {"state": ${is_charging},"type": "binary_sensor","unique_id": "battery_is_charging"} ] }' \
${URL}/webhook/${WEBHOOK_ID}
```
Execute:
@ -156,7 +155,15 @@ The output looks like this:
Battery Level = 45
Battery Charging? = true
{"message":"Event garmin.battery_level fired."}
{
"battery_level": {
"success": true
},
"battery_is_charging": {
"success": true
}
}
```
NB. The device ID can be any string for the purposes of this testing. Your Garmin device will choose this ID for you when it submits the readings.
@ -171,7 +178,7 @@ rem battery% charging {0|1}
rem ./home_assistant_battery_level 19 0
rem
set API_KEY=<Your API key>FEt_fGzW_lV0xitvJPkaQHSLhGm90ADovgMbJxdHH2I
set WEBHOOK_ID=<Your Webhook ID>
set URL=https://<Your Domain>/api
if [%1] == [] (
@ -195,10 +202,9 @@ echo "Battery Charging? = %is_charging%"
echo.
curl -s -X POST ^
-H "Authorization: Bearer %API_KEY%" ^
-H "Content-Type: application/json" ^
-d "{\"level\": %level%, \"is_charging\": %is_charging%, \"device_id\": \"Batch File\"}" ^
%URL%/events/garmin.battery_level
-d "{ \"type\": \"update_sensor_states\", \"data\": [ {\"state\": %level%,\"type\": \"sensor\",\"unique_id\": \"battery_level\"}, {\"state\": %is_charging%,\"type\": \"binary_sensor\",\"unique_id\": \"battery_is_charging\"} ] }" ^
%URL%/webhook/%WEBHOOK_ID%
echo.
pause
@ -216,7 +222,15 @@ The output looks like this:
"Battery Level = 41"
"Battery Charging? = true"
{"message":"Event garmin.battery_level fired."}
{
"battery_level": {
"success": true
},
"battery_is_charging": {
"success": true
}
}
Press any key to continue . . .
```
@ -237,7 +251,21 @@ https://<Your Domain>/api/events/garmin.battery_level
JSON for copy & paste:
```json
{"level": 19, "is_charging": true, "device_id": "REQBIN"}
{
"type": "update_sensor_states",
"data": [
{
"state": 19,
"type": "sensor",
"unique_id": "battery_level"
},
{
"state": true,
"type": "binary_sensor",
"unique_id": "battery_is_charging"
}
]
}
```
![API Test REQBIN](images/api_test_online_battery2.png)

BIN
images/Battery_Event_Screenshot.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 100 KiB