mirror of
https://github.com/house-of-abbey/GarminHomeAssistant.git
synced 2025-08-02 18:08:34 +00:00
Initial Docs for review
This commit is contained in:
Philip Abbey
@ -1,4 +1,4 @@
|
||||
[Home](README.md) | [Switches](examples/Switches.md) | [Actions](examples/Actions.md) | [Templates](examples/Templates.md) | [Glance](examples/Glance.md) | [Background Service](BackgroundService.md) | [Trouble Shooting](TroubleShooting.md) | [Version History](HISTORY.md)
|
||||
[Home](README.md) | [Switches](examples/Switches.md) | [Actions](examples/Actions.md) | [Templates](examples/Templates.md) | [Glance](examples/Glance.md) | [Background Service](BackgroundService.md) | [Wi-Fi](Wi-Fi.md) | [Trouble Shooting](TroubleShooting.md) | [Version History](HISTORY.md)
|
||||
|
||||
# Background Service
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[Home](README.md) | [Switches](examples/Switches.md) | [Actions](examples/Actions.md) | [Templates](examples/Templates.md) | [Glance](examples/Glance.md) | [Background Service](BackgroundService.md) | [Trouble Shooting](TroubleShooting.md) | [Version History](HISTORY.md)
|
||||
[Home](README.md) | [Switches](examples/Switches.md) | [Actions](examples/Actions.md) | [Templates](examples/Templates.md) | [Glance](examples/Glance.md) | [Background Service](BackgroundService.md) | [Wi-Fi](Wi-Fi.md) | [Trouble Shooting](TroubleShooting.md) | [Version History](HISTORY.md)
|
||||
|
||||
# Version History
|
||||
|
||||
@ -45,3 +45,4 @@
|
||||
| 2.30 | <img src="images/Venu2_glance_default.png" width="200" title="Default Glance"/><br/>Extensive re-work of the [Glance](examples/Glance.md) view, including the ability to customise it with a user supplied template. |
|
||||
| 2.31 | Adding [two new options](./examples/Actions.md#exit-on-tap) to the menu items: 1) The ability to disable a menu item, e.g. temporarily for seasonal changes, 2) The option to exit after a menu item has been select. |
|
||||
| 2.32 | Bug fix for a breaking change extracting options caused by the need to rearrange function parameters for an [annoying compiler error](https://github.com/house-of-abbey/GarminHomeAssistant/issues/253). |
|
||||
| 3.0 | First version with the ability to use [Wi-Fi](Wi-Fi.md) instead of Bluetooth but with limited functionality. |
|
||||
|
||||
19
README.md
19
README.md
@ -1,4 +1,4 @@
|
||||
[Home](README.md) | [Switches](examples/Switches.md) | [Actions](examples/Actions.md) | [Templates](examples/Templates.md) | [Glance](examples/Glance.md) | [Background Service](BackgroundService.md) | [Trouble Shooting](TroubleShooting.md) | [Version History](HISTORY.md)
|
||||
[Home](README.md) | [Switches](examples/Switches.md) | [Actions](examples/Actions.md) | [Templates](examples/Templates.md) | [Glance](examples/Glance.md) | [Background Service](BackgroundService.md) | [Wi-Fi](Wi-Fi.md) | [Trouble Shooting](TroubleShooting.md) | [Version History](HISTORY.md)
|
||||
|
||||
# GarminHomeAssistant
|
||||
|
||||
@ -10,13 +10,18 @@ The application is designed around a simple scrollable menu where menu items hav
|
||||
|
||||
**The intended audience for this application are those comfortable with configuring a Home Assistant** (e.g. editing the YAML configuration files) and debugging why URLs don't work. It does not require programming skills, but the menu is configured via JSON which feels like "coding" (more like "describing"). If you are not comfortable with this relatively low level of configuration, you may like to try other Garmin applications instead.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The Garmin SDK allows HTTP requests only to a limited number of domains specified in their app. Therefore, for your Garmin to communicate with your Home Assistant instance, your Home Assistant instance must be accessible via HTTPS (with a public certificate!) or through a local DNS server that overrides one of the whitelisted domains to communicate using HTTP.
|
||||
> To make your Home Assistant instance accessible via HTTPS, you will need 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/). (You can install a local [Nginx proxy server](https://my.home-assistant.io/redirect/supervisor_addon/?addon=a0d7b954_nginxproxymanager) to manage Let's Encrypt certificates.)
|
||||
> If you use a local DNS server (like [Pi-Hole](https://pi-hole.net/)), you can create a local DNS record for the domain `garmincdn.com` (which is allowed for HTTP in the Garmin SDK) and map it to your Home Assistant instance's IP. You can find additional workarounds for HTTP request restrictions in the Garmin SDK [here](https://www.instructables.com/About-Communication-Between-Garmin-SDK-and-a-Raspb/).
|
||||
|
||||
**If you are struggling with getting the application to work, please consult the [trouble shooting](TroubleShooting.md#menu-configuration-url) guide first.**
|
||||
|
||||
## No HTTPS?
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The Garmin SDK allows HTTP requests only to a limited number of domains specified in their app. Therefore, for your Garmin to communicate with your Home Assistant instance, your Home Assistant instance must be accessible via HTTPS (with a public certificate!) or through a local DNS server that overrides one of the whitelisted domains to communicate using HTTP.
|
||||
>
|
||||
> To make your Home Assistant instance accessible via HTTPS, you will need 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/). (You can install a local [Nginx proxy server](https://my.home-assistant.io/redirect/supervisor_addon/?addon=a0d7b954_nginxproxymanager) to manage Let's Encrypt certificates.)
|
||||
>
|
||||
> If you use a local DNS server (like [Pi-Hole](https://pi-hole.net/)), you can create a local DNS record for the domain `garmincdn.com` (which is allowed for HTTP in the Garmin SDK) and map it to your Home Assistant instance's IP. "_[About Communication Between Garmin SDK and a Raspberry Pi](https://www.instructables.com/About-Communication-Between-Garmin-SDK-and-a-Raspb/)_" provides additional workarounds for HTTP request restrictions in the Garmin SDK.
|
||||
>
|
||||
> **No support is offered to those circumventing the HTTPS restriction of the Connect IQ SDK.** You are supporting yourself!
|
||||
|
||||
## Widget or Application?
|
||||
|
||||
@ -266,7 +271,7 @@ The application timeout prevents the HomeAssistant App running on your watch whe
|
||||
| 0 | > 0 | Permanently open, but poll more gently to save battery. |
|
||||
| > 0 | > 0 | Temporarily open, poll more gently to save battery, but the application closes before the benefit is realised. Not recommended. |
|
||||
|
||||
There is a second timeout value for confirmation views. This is intended for use with more sensitive toggles so that the confirmation view is not left open and forgotten and then confirmed accidentally without you noticing. **We cannot advise you this is safe, be careful what you toggle with the watch application!**
|
||||
There is a second timeout value for confirmation views. This is intended for use with more sensitive toggles so that the confirmation view is not left open and forgotten and then confirmed accidentally without you noticing. **We cannot advise you this is safe, be careful what you toggle with the watch application!** _The developers will not be held responsible for any insecurities resulting from using this feature, including any inadvertent code changes that cause the PIN feature to not work._
|
||||
|
||||
The confirmation timeout is also used for the maximum time between clicks in the PIN confirmation dialog. The PIN confirmation provides a more secure alternative for toggling security-sensitive actions.
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[Home](README.md) | [Switches](examples/Switches.md) | [Actions](examples/Actions.md) | [Templates](examples/Templates.md) | [Glance](examples/Glance.md) | [Background Service](BackgroundService.md) | [Trouble Shooting](TroubleShooting.md) | [Version History](HISTORY.md)
|
||||
[Home](README.md) | [Switches](examples/Switches.md) | [Actions](examples/Actions.md) | [Templates](examples/Templates.md) | [Glance](examples/Glance.md) | [Background Service](BackgroundService.md) | [Wi-Fi](Wi-Fi.md) | [Trouble Shooting](TroubleShooting.md) | [Version History](HISTORY.md)
|
||||
|
||||
# Troubleshooting Guides
|
||||
|
||||
|
||||
29
Wi-Fi.md
Normal file
29
Wi-Fi.md
Normal file
@ -0,0 +1,29 @@
|
||||
[Home](README.md) | [Switches](examples/Switches.md) | [Actions](examples/Actions.md) | [Templates](examples/Templates.md) | [Glance](examples/Glance.md) | [Background Service](BackgroundService.md) | [Wi-Fi](Wi-Fi.md) | [Trouble Shooting](TroubleShooting.md) | [Version History](HISTORY.md)
|
||||
|
||||
# Wi-Fi
|
||||
|
||||
Many watches now include the ability to synchronise data over Wi-Fi in addition to Bluetooth. This gives users of this application the expectation that they should be able to operate Home Assistant devices from their watch without Bluetooth and hence their phone (that they left out of contact distance). The whole point of Bluetooth after all is that it is [low power](https://en.wikipedia.org/wiki/Bluetooth#Uses). Using Wi-Fi is power hungry and therefore not something that can be left on continuously in a small device. The watch function that uses Wi-Fi is the ability to 'synchronise', e.g. activity data (FIT files) and application updates. This function then has a limited period of time for which Wi-Fi is active. Wi-Fi is not "always on" like Bluetooth.
|
||||
|
||||
With version 3.0 onwards the application now includes the ability to temporarily turn on Wi-Fi in order to perform a task on the watch. To do this, the "synchronise" function of the Connect IQ SDK has been cleverly hijacked. This appears to be a highly sought after solution from several users as **it allows the watch to operate when out of range of the associated phone**.
|
||||
|
||||
## Limits of Use
|
||||
|
||||
1. An API request issued over Wi-Fi requires the watch to open up an IP connection to your Wi-Fi access point. This means setting up a secure channel with WPA and being allocated an IP address. Establishing the communication channel takes a short while. _You will see that this adds a noticeable delay to useability._
|
||||
|
||||
2. **This new function can only be used when the menu is already cached.** _The watch will not perform an HTTPS GET request to retrieve the JSON menu file_. You will not be able to turn on the Wi-Fi connection option in the application settings if the menu is not cached (or at least set to be cached in due course).
|
||||
|
||||
3. The menu item statuses will not be set correctly. Instead you will be warned about the lack of connectivity by a 'toast', i.e. message partially occupying the top of the screen temporarily. Fetching the menu item statuses, including rendered templates, requires its own API call, hence this not performed.
|
||||
|
||||
4. Do not forget you need to be within range of your watch's configured Wi-Fi access point to take advantage of this functionality.
|
||||
|
||||
## Video
|
||||
|
||||
This video will hopefully make it obvious how slow it is to use the Wi-Fi option and illustrate the cautionary notes above.
|
||||
|
||||
<video width="100%" controls style="max-width:250px">
|
||||
<source src="./images/wi-fi.mp4" type="video/mp4">
|
||||
</video>
|
||||
|
||||
## Credits
|
||||
|
||||
With thanks to [@vincentezw](https://github.com/vincentezw) for contributing this solution.
|
||||
@ -1,4 +1,4 @@
|
||||
[Home](../README.md) | [Switches](Switches.md) | [Actions](Actions.md) | [Templates](Templates.md) | [Glance](Glance.md) | [Background Service](../BackgroundService.md) | [Trouble Shooting](../TroubleShooting.md) | [Version History](../HISTORY.md)
|
||||
[Home](../README.md) | [Switches](Switches.md) | [Actions](Actions.md) | [Templates](Templates.md) | [Glance](Glance.md) | [Background Service](../BackgroundService.md) | [Wi-Fi](../Wi-Fi.md) | [Trouble Shooting](../TroubleShooting.md) | [Version History](../HISTORY.md)
|
||||
|
||||
|
||||
# Actions
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[Home](../README.md) | [Switches](Switches.md) | [Actions](Actions.md) | [Templates](Templates.md) | [Glance](Glance.md) | [Background Service](../BackgroundService.md) | [Trouble Shooting](../TroubleShooting.md) | [Version History](../HISTORY.md)
|
||||
[Home](../README.md) | [Switches](Switches.md) | [Actions](Actions.md) | [Templates](Templates.md) | [Glance](Glance.md) | [Background Service](../BackgroundService.md) | [Wi-Fi](../Wi-Fi.md) | [Trouble Shooting](../TroubleShooting.md) | [Version History](../HISTORY.md)
|
||||
|
||||
# Glance
|
||||
|
||||
|
||||
@ -1,5 +1,4 @@
|
||||
[Home](../README.md) | [Switches](Switches.md) | [Actions](Actions.md) | [Templates](Templates.md) | [Glance](Glance.md) | [Background Service](../BackgroundService.md) | [Trouble Shooting](../TroubleShooting.md) | [Version History](../HISTORY.md)
|
||||
|
||||
[Home](../README.md) | [Switches](Switches.md) | [Actions](Actions.md) | [Templates](Templates.md) | [Glance](Glance.md) | [Background Service](../BackgroundService.md) | [Wi-Fi](../Wi-Fi.md) | [Trouble Shooting](../TroubleShooting.md) | [Version History](../HISTORY.md)
|
||||
|
||||
# Switches
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[Home](../README.md) | [Switches](Switches.md) | [Actions](Actions.md) | [Templates](Templates.md) | [Glance](Glance.md) | [Background Service](../BackgroundService.md) | [Trouble Shooting](../TroubleShooting.md) | [Version History](../HISTORY.md)
|
||||
[Home](../README.md) | [Switches](Switches.md) | [Actions](Actions.md) | [Templates](Templates.md) | [Glance](Glance.md) | [Background Service](../BackgroundService.md) | [Wi-Fi](../Wi-Fi.md) | [Trouble Shooting](../TroubleShooting.md) | [Version History](../HISTORY.md)
|
||||
|
||||
# Templates
|
||||
|
||||
|
||||
BIN
images/wi-fi.mp4
Normal file
BIN
images/wi-fi.mp4
Normal file
Binary file not shown.
@ -33,6 +33,7 @@
|
||||
"Monkey C: Edit Products" - Lets you add or remove any product
|
||||
-->
|
||||
<iq:products>
|
||||
<!--
|
||||
<iq:product id="approachs50"/>
|
||||
<iq:product id="approachs7042mm"/>
|
||||
<iq:product id="approachs7047mm"/>
|
||||
@ -142,7 +143,9 @@
|
||||
<iq:product id="marqgolfer"/>
|
||||
<iq:product id="montana7xx"/>
|
||||
<iq:product id="venu"/>
|
||||
-->
|
||||
<iq:product id="venu2"/>
|
||||
<!--
|
||||
<iq:product id="venu2plus"/>
|
||||
<iq:product id="venu2s"/>
|
||||
<iq:product id="venu3"/>
|
||||
@ -159,6 +162,7 @@
|
||||
<iq:product id="vivoactive4s"/>
|
||||
<iq:product id="vivoactive5"/>
|
||||
<iq:product id="vivoactive6"/>
|
||||
-->
|
||||
</iq:products>
|
||||
<!--
|
||||
Use "Monkey C: Edit Permissions" from the Visual Studio Code command
|
||||
|
||||
Reference in New Issue
Block a user