From b82e63d1913658b330852e778a69f5d912986944 Mon Sep 17 00:00:00 2001 From: Philip Abbey Date: Sun, 19 Jan 2025 19:47:42 +0000 Subject: [PATCH] Documentation update --- HISTORY.md | 1 + README.md | 53 ++++++++++++++++++++++--------------------- examples/Templates.md | 30 ++++++++++++------------ 3 files changed, 43 insertions(+), 41 deletions(-) diff --git a/HISTORY.md b/HISTORY.md index eb7019f..7446b14 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -35,3 +35,4 @@ | 2.20 | Simplified the code base now that templates have been requested in all menu items. This means the `template` menu item became a superset of `tap`. Therefore the `tap` code has been has been upgraded to include `template` and the latter deprecated. JSON menu definitions continue to support `template` items by instantiating a `tap` menu item, but the schema marks them as deprecated and users should migrate their menu definitions now. Use the [web editor](https://house-of-abbey.github.io/GarminHomeAssistant/web/) for assistance with changes. | | 2.21 | Added 7 new devices (`edge1050`, `enduro3`, `fenix843mm`, `fenix847mm`, `fenix8solar47mm`, `fenix8solar51mm`, `fenixe`) and upgraded the SDK to 7.3.0. Fix for a bug on Edge devices introduced by v2.16 activity reporting improvements. | | 2.22 | Major feature release adding an optional PIN to menu items. This significant new feature has been provided by [moesterheld](https://github.com/moesterheld). Please do not rely on this application for security. Use at your own risk! | +| 2.23 | Added "info" menu item for displaying information via a template without a tap or toggle. Essentially like the old 'template' type that was deprecated when all items were amended to display evaluated templates. That action removed the display only items too hastily. Added 5 new devices in the model range Instinct 3 and Instinct E. | diff --git a/README.md b/README.md index 2d89f6d..fd4b76d 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@ Home | [Switches](examples/Switches.md) | [Actions](examples/Actions.md) | [Temp A Garmin application to provide a "dashboard" to control your devices via [Home Assistant](https://www.home-assistant.io/). The application will never be as fully fledged as a Home Assistant dashboard, so it is designed to be good enough for the simple and essential things. Those things that can be activated via an on/off toggle or a tap. That should cover lights, switches, and anything requiring a single press such as an automation. For anything more complicated, e.g. thermostat, it would always be quicker and simpler to reach for your phone or tablet... or the device's own remote control! -The application is designed around a simple scrollable menu where menu items have been extended to interface with the [Home Assistant API](https://developers.home-assistant.io/docs/api/rest/), e.g. to get the status of switches or lights for display on the toggle menu item, or a text status for an entity (template item). It is possible to nest menus, so there is a menu item to open a sub-menu. This can be arbitrarily deep and nested in the format of a tree of items, although you need to consider if reaching for your phone becomes quicker to select the device what you want to control. +The application is designed around a simple scrollable menu where menu items have been extended to interface with the [Home Assistant API](https://developers.home-assistant.io/docs/api/rest/), e.g. to get the status of switches or lights for display on the `toggle` menu item, or a text status for an entity (`info` item). It is possible to nest menus, so there is a menu item to open a sub-menu. This can be arbitrarily deep and nested in the format of a tree of items, although you need to consider if reaching for your phone becomes quicker to select the device what you want to control. -**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". If you are not comfortable with this relatively low level of configuration, you may like to try other Garmin applications instead. +**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. @@ -145,32 +145,33 @@ NB. Entity names are not real in case anyone's a hacker ;-). The example above illustrates how to configure: -* Lights or switches (toggle), -* Enables for automations (toggle), -* Script invocation (tap) -* Service invocation, e.g. Scene setting, (tap) -* A sub-menu to open (group) -* You can also display the status of devices (template) and add an optional 'tap' action. However that's a bit more involved and has its own [examples page](examples/Templates.md). Add those later! +* Lights or switches (`toggle`), +* Enables for automations (`toggle`), +* Script invocation (`tap`) +* Service invocation, e.g. Scene setting, (`tap`) +* A sub-menu to open (`group`) +* You can also display the status of devices (`info`) which is essentially a `tap` with no action +* All menu items can display the results of evaluating [templates](examples/Templates.md). -The following table indicates how Home Assistant entity types can map to the Garmin applications menu types. Presently, an automation is the only one that can be either a 'tap' or a 'toggle'. +The following table indicates how Home Assistant entity types can map to the Garmin applications menu types. Presently, an automation is the only one that can be either a `tap` or a `toggle`. -| HA Entity Type | Tap | Toggle | Template (custom status text with optional tap action) | -|------------------|:---:|:------:|:------------------------------------------------------:| -| Switch | ❌ | ✅ | ✅
Separate on and off, or anything in between | -| Light | ❌ | ✅ | ✅
Separate on and off, or anything in between | -| Automation | ✅ | ✅ | ✅ | -| Script | ✅ | ❌ | ✅ | -| Scene | ✅ | ❌ | ✅ | -| Sensor | ❌ | ❌ | ✅ | -| Binary Sensor | ❌ | ❌ | ✅ | -| Any other entity | ❌ | ❌ | ✅ | -| Any service | ✅ | ❌ | ✅ | +| HA Entity Type | Tap | Toggle | Info (status)| +|------------------|:---:|:------:|:------------:| +| Switch | ❌ | ✅ | ✅ | +| Light | ❌ | ✅ | ✅ | +| Automation | ✅ | ✅ | ❌ | +| Script | ✅ | ❌ | ❌ | +| Scene | ✅ | ❌ | ❌ | +| Sensor | ❌ | ❌ | ✅ | +| Binary Sensor | ❌ | ❌ | ✅ | +| Any other entity | ❌ | ❌ | ✅ | +| Any service | ✅ | ❌ | ❌ | -Templates need separate HTTP requests to update their status and send an action. Only the toggle items have the on/off icon. A Tap does not require a status update and hence does not require the associated HTTP GET request. NB. All 'tap' items must specify a 'service' tag. +Multiple templates are evaluated in a single HTTP request to update their status. Only the toggle items have the on/off icon. NB. All `tap` items must specify a `service` tag in the `tap_action` object (see example below). You can now specify alternative texts to use instead of "On" and "Off", e.g. "Locked" and "Unlocked" or "Open" and "Closed" through the use of a [template menu item](examples/Templates.md). But wouldn't having locks operated from your watch be a security concern ;-) ? -The [schema](https://raw.githubusercontent.com/house-of-abbey/GarminHomeAssistant/main/config.schema.json) is checked by using a URL directly back to this GitHub source repository, so you do not need to install that file. You can just copy & paste your entity names from the YAML configuration files used to configure Home Assistant. With a submenu, there's a difference between "title" and "name". The "name" goes on the menu item, and the "title" at the head of the submenu. If your dashboard definition fails to meet the schema, the application will simply drop items with the wrong field names without warning to protect itself. +The [schema](https://raw.githubusercontent.com/house-of-abbey/GarminHomeAssistant/main/config.schema.json) is checked by using a URL directly back to this GitHub source repository, so you do not need to install that file. You can just copy & paste your entity names from the YAML configuration files used to configure Home Assistant. With a submenu, there's a difference between `title` and `name`. The `name` goes on the menu item, and the `title` at the head of the submenu. If your dashboard definition fails to meet the schema, the application will simply drop items with the wrong field names without warning to protect itself. ### Old deprecated format @@ -198,13 +199,13 @@ The above should be replaced by the following: } ``` -This allows the `confirm` field to be accommodated in the `tap_action` along side the `service` tag, and follows the Home Assistant YAML format more closely. +This allows the `confirm` and `pin` fields to be accommodated in the `tap_action` along side the `service` tag, and follows the Home Assistant YAML format more closely. ### More Examples -- [Switches](examples/Switches.md) -- [Actions](examples/Actions.md) -- [Templates](examples/Templates.md) +* [Switches](examples/Switches.md) +* [Actions](examples/Actions.md) +* [Templates](examples/Templates.md) ## Editing the JSON file diff --git a/examples/Templates.md b/examples/Templates.md index ec27d82..743c267 100644 --- a/examples/Templates.md +++ b/examples/Templates.md @@ -20,7 +20,7 @@ In this example we get the battery level of the device and add the percent sign. ```json { "name": "Phone", - "type": "template", + "type": "info", "content": "{{ states('sensor._battery_level') }}%" } ``` @@ -32,17 +32,17 @@ The first two keep to the simple proposal above. The last combines them into a s ```json { "name": "Hall Temp", - "type": "template", + "type": "info", "content": "{{ states('sensor.hallway_temperature') }}°C" }, { "name": "Hall Humidity", - "type": "template", + "type": "info", "content": "{{ states('sensor.hallway_humidity') }}%" }, { "name": "Hallway", - "type": "template", + "type": "info", "content": "{{ states('sensor.hallway_temperature') }}°C {{ states('sensor.hallway_humidity') }}%" } ``` @@ -52,7 +52,7 @@ In order to keep the formatting of floating point numbers under control, you mig ```json { "name": "Hallway", - "type": "template", + "type": "info", "content": "T:{{ '%.1f' | format(states('sensor.hallway_temperature') | float) }}°C, H:{{ '%.1f' | format(states('sensor.hallway_humidity') | float) }}%" }, ``` @@ -62,12 +62,12 @@ Where your device supports unicode characters these example may work. ```json { "name": "Charge", - "type": "template", + "type": "info", "content": "☎ {{ states('sensor.my_phone_battery_level') }}%{% if is_state('binary_sensor.my_phone_is_charging', 'on') %}⚡{% endif %}, ⏳ {{ '%.0f'|format(states('sensor.my_watch_battery_level') | float) }}%{% if is_state('binary_binary_sensor.my_watch_battery_is_charging', 'on') %}⚡{% endif %}" }, { "name": "Hallway", - "type": "template", + "type": "info", "content": "🌡{% if is_state('sensor.hallway_temperature', 'unavailable') %}-{% else %}{{ '%.1f'|format(states('sensor.hallway_temperature')|float) }}°C{% if is_state_attr('climate.hallway', 'hvac_action', 'heating') or is_state_attr('climate.hallway', 'hvac_action', 'preheating') -%}🔥{%- endif %}{% endif %}, 💧{% if is_state('sensor.hallway_humidity', 'unavailable') %}-{% else %}{{ '%.1f'|format(states('sensor.hallway_humidity')|float) }}%{% endif %}" } ``` @@ -83,7 +83,7 @@ In this example we get the battery level of the device and add the percent sign. ```json { "name": "Phone", - "type": "template", + "type": "info", "content": "{{ states('sensor._battery_level') }}%{% if is_state('binary_sensor._is_charging', 'on') %}+{% endif %}" } ``` @@ -93,7 +93,7 @@ Here we also use the else clause as well to give proper text instead of just `on ```json { "name": "Garage Doors", - "type": "template", + "type": "info", "content": "{% if is_state('binary_sensor.', 'on') %}Open{% else %}Closed{% endif %} {% if is_state('binary_sensor.', 'on') %}Open{% else %}Closed{% endif %}" } ``` @@ -113,7 +113,7 @@ Note: Only when you use the `tap_action` field do you also need to include the ` { "entity": "cover.garage_door", "name": "Garage Door", - "type": "template", + "type": "tap", "content": "{% if is_state('binary_sensor.garage_connected', 'on') %}{{state_translated('cover.garage_door')}} - {{state_attr('cover.garage_door', 'current_position')}}%{%else%}Unconnected{% endif %}", "tap_action": { "service": "cover.toggle", @@ -150,7 +150,7 @@ Here we generate a bar graph of the battery level. We use the following steps to ```json { "name": "Phone", - "type": "template", + "type": "info", "content": "{{ states('sensor._battery_level') }}%{% if is_state('binary_sensor._is_charging', 'on') %}+{% endif %} {{ '#' * (((states('sensor._battery_level') | int) / 100 * ) | int) }}{{ '_' * ( - (((states('sensor._battery_level') | int) / 100 * ) | int)) }}" } ``` @@ -164,13 +164,13 @@ An example of a dimmer light with 4 brightness settings 0..3. Here our light wor "items": [ { "name": "LEDs", - "type": "template", + "type": "info", "content": "{% if not (is_state('light.green_house', 'off') or is_state('light.green_house', 'unavailable')) %}{{ (((state_attr('light.green_house', 'brightness') | float) / 255 * 100) | round(0)) | int }}%{% else %}Off{% endif %}" }, { "entity": "light.green_house", "name": "LEDs 0", - "type": "template", + "type": "tap", "content": "{% if not (is_state('light.green_house', 'off') or is_state('light.green_house', 'unavailable')) %}{{ (((state_attr('light.green_house', 'brightness') | float) / 255 * 100) | round(0)) | int }}%{% else %}Off{% endif %}", "tap_action": { "service": "light.turn_on", @@ -193,7 +193,7 @@ An example of a dimmer light with 4 brightness settings 0..3. Here our light wor { "entity": "light.green_house", "name": "LEDs 2", - "type": "template", + "type": "tap", "content": "{% if not (is_state('light.green_house', 'off') or is_state('light.green_house', 'unavailable')) %}{{ (((state_attr('light.green_house', 'brightness') | float) / 255 * 100) | round(0)) | int }}%{% else %}Off{% endif %}", "tap_action": { "service": "light.turn_on", @@ -205,7 +205,7 @@ An example of a dimmer light with 4 brightness settings 0..3. Here our light wor { "entity": "light.green_house", "name": "LEDs 3", - "type": "template", + "type": "tap", "content": "{% if not (is_state('light.green_house', 'off') or is_state('light.green_house', 'unavailable')) %}{{ (((state_attr('light.green_house', 'brightness') | float) / 255 * 100) | round(0))| int }}%{% else %}Off{% endif %}", "tap_action": { "service": "light.turn_on",