Updated troubleshooting guide.

Now includes battery level transmission debug.

Co-Authored-By: Joseph Abbey <me@josephabbey.dev>

README.md

@@ -8,7 +8,8 @@ The application is designed around a simple scrollable menu where menu items hav
 
 It is important to note that your Home Assistant instance will need to be accessible via HTTPS with public SSL or all requests from the Garmin will not work. This cannot be a self-signed certificate, it must be a public certificate. You can get one for free from [Let's Encrypt](https://letsencrypt.org/) or you can pay for [Home Assistant cloud](https://www.nabucasa.com/).
 
-**If you are struggling with getting the application to work, please consult the [trouble shooting](Troubleshooting.md) guide first.**
+**If you are struggling with getting the application to work, please consult the [trouble shooting](Troubleshooting.md#menu-configuration-url) guide first.**
+
 
 ## Widget or Application?
 
@@ -267,7 +268,8 @@ The `id` attribute values are taken from the same names used in [`strings.xml`](
 
 ## 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! We are keen to received improvements, but are reluctant to provide much in the way of support. The Home Assistant community, in particular the posts on the forum at [Bluetooth Battery Levels (Android)](https://community.home-assistant.io/t/bluetooth-battery-levels-android/661525), are your best source of support for this feature.
+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! We are keen to received improvements, but are reluctant to provide much in the way of support. The Home Assistant community, in particular the posts on the forum at [Bluetooth Battery Levels (Android)](https://community.home-assistant.io/t/bluetooth-battery-levels-android/661525), are your best source of support for this feature. We do however offer this [trouble shooting](Troubleshooting.md#watch-battery-level-reporting) guide.
+
 
 ## Version History
 

Troubleshooting.md

@@ -1,8 +1,10 @@
-# Troubleshooting Guide
+# Troubleshooting Guides
+
+## Watch Menu and API
 
 With either of the following setups, there are inevitably some problems along the way. GarminHomeAssistant is careful to rely only on having working URLs. Getting them working is the user's responsibility. However, we have developed some fault finding tools.
 
-## Nabu Casa Setup
+### Nabu Casa Setup
 
 You can purchase cloud-based access to your Home Assistant from [Nabu Casa](https://www.nabucasa.com/), and then your setup will look something like this.
 
@@ -13,7 +15,7 @@ You can purchase cloud-based access to your Home Assistant from [Nabu Casa](http
 
 Where `<id>` is your personal Nabu Casa account ID.
 
-## Do It Yourself Setup
+### Do It Yourself Setup
 
 Before Nabu Casa, or if you wanted to manage your own infrastructure, you might have something like the following:
 
@@ -38,7 +40,7 @@ http:
     - 172.16.0.0/12  #
 ```
 
-## Menu Configuration URL
+### Menu Configuration URL
 
 This URL is very simple, you should be able to read the contents returned in a standard web browser.
 
@@ -50,7 +52,7 @@ The browser page should then display the JSON string you saved to the file on th
 
 The menu configuration can be hosted anywhere, it does not have to be on the Home Assistant web server. Just as long as it is reachable from your phone from which you Bluetooth connect to your watch, or you watch if it has direct Internet access.
 
-## Home Assistant API URL
+### Home Assistant API URL
 
 This is slightly trickier owning to the need to supply the API key. Here are three ways you can test your API URL is correctly configured. If successful, each of these should produce a JSON string output looking like:
 
@@ -58,7 +60,7 @@ This is slightly trickier owning to the need to supply the API key. Here are thr
 {"message":"API running."}
 ```
 
-### Linux, MacOS, UNIX, Cygwin etc
+#### API: Linux, MacOS, UNIX, Cygwin etc
 
 Save the following as a file called `api_test.sh`, edit to include your personal values for the variables, `chmod +x api_test.sh` and then execute with `./api_test.sh`.
 
@@ -74,11 +76,11 @@ curl -s -X GET \
   ${URL}/
 ```
 
-### MS Windows
+#### API: MS Windows
 
 Save the following as a file called `api_test.cmd`, edit to include your personal values for the variables and then double click.
 
-```shell
+```cmd
 @echo off
 
 set API_KEY=<Your API key>
@@ -95,13 +97,149 @@ pause
 
 ![API Test MS-DOS Output](images/api_test_dos_output.png)
 
-### On-line
+#### API: On-line
 
 There's an online way of testing the API URL too, thanks to [REQBIN](https://reqbin.com/post-online). This has less setup and it can be saved if you log into the web site.
 
-![API Test MS-DOS Output](images/api_test_online.png)
+![API Test REQBIN](images/api_test_online.png)
 
-## Top Problems
+### Top Problems
 
 1. Failure to copy & paste keys and URLs leading to minor and hard to see errors in strings, even with protestations they are the same! (No they weren't...)
 2. Accessibility of URLs, hence the above help guide.
+
+## 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 by clicking the following button.
+
+[![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/)
+
+#### Battery: Linux, MacOS, UNIX, Cygwin etc
+
+Assume a file called: `send_battery.bash`
+
+```shell
+#!/bin/bash
+#
+#               battery% charging {0|1}
+# ./send_battery.bash 19 0
+#
+
+API_KEY="<Your API key>"
+URL="https://<Your Domain>/api"
+
+level=${1:-50}
+is_charging=${2:-0}
+echo "Battery Level = ${level}"
+if [ ${is_charging} -eq 1 ]; then
+  is_charging=true
+else
+  is_charging=false
+fi
+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
+```
+
+Execute:
+
+```
+$ ./send_battery.bash 45 1
+```
+
+The output looks like this:
+
+```
+Battery Level = 45
+Battery Charging? = true
+
+{"message":"Event garmin.battery_level fired."}
+```
+
+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.
+
+#### Battery: MS Windows
+
+Assume a file called: `home_assistant_battery_level.cmd`
+
+```cmd
+@echo off
+rem               battery% charging {0|1}
+rem ./home_assistant_battery_level 19 0
+rem
+
+set API_KEY=<Your API key>FEt_fGzW_lV0xitvJPkaQHSLhGm90ADovgMbJxdHH2I
+set URL=https://<Your Domain>/api
+
+if [%1] == [] (
+  set level=50
+) else (
+  set level=%1
+)
+
+if [%1] == [] (
+  set is_charging=0
+) else (
+  set is_charging=%2
+)
+echo "Battery Level = %level%"
+if "%is_charging%"=="1" (
+  set is_charging=true
+) else (
+  set is_charging=false
+)
+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
+
+echo.
+pause
+```
+
+Execute:
+
+```
+> home_assistant_battery_level.cmd 41 1
+```
+
+The output looks like this:
+
+```
+"Battery Level = 41"
+"Battery Charging? = true"
+
+{"message":"Event garmin.battery_level fired."}
+Press any key to continue . . .
+```
+
+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.
+
+#### Battery: On-line
+
+There's an online way of testing the API URL too, thanks to [REQBIN](https://reqbin.com/post-online). This has less setup and it can be saved if you log into the web site.
+
+URL for copy & paste:
+
+```
+https://<Your Domain>/api/events/garmin.battery_level
+```
+
+![API Test REQBIN](images/api_test_online_battery1.png)
+
+JSON for copy & paste:
+
+```json
+{"level": 19, "is_charging": true, "device_id": "REQBIN"}
+```
+
+![API Test REQBIN](images/api_test_online_battery2.png)