Documentation

README.md

@@ -287,10 +287,14 @@ The application and widget both now include a background service to report your
 |   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 hence is 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.2   | Adds a feature to cache the menu configuration and save the time taken for an HTTP request to fetch it. You as the user are responsible for managing the cache by clearing it when you update your configuration. Improvement to widget root display updates. Bug fix for battery level reporting when in the glance carousel. Fixed an uninternationalised string, "Execute". Unfixed issue with battery level updates when the user is not an administrator. |
 |   2.3   | Fix for battery level updates where previously the function only worked for administrator accounts. The new solution is based on Webhooks and is simpler to implement on Home Assistant. Language support fix where an automatic translation produced an inappropriate word, possibly in more than one language. |
-|   2.4   | Sensor status reporting via Home Assistant 'templates'. This provides a generalised way of viewing the status of any entity as long as the result can be rendered as text, e.g. 'uncovered', 'open', '76%', '21 °C'. Removal of the menu style option. The original style was kept after the introduction of the icon style solely to keep the code for a possible re-use for sensor statuses. This version delivers that new feature, hence the style option has been removed. The new JSON configuration file format allows for the old style to be replicated if you are desperate! |
+|   2.4   | Sensor status reporting via Home Assistant 'templates'. This provides a generalised way of viewing the status of any entity as long as the result can be rendered as text, e.g. 'uncovered', 'open', '76%', '21 °C'. Removal of the menu style option. The original style was kept after the introduction of the icon style solely to keep the code for a possible re-use for sensor statuses. This version delivers that new feature, hence the style option has been removed. The new JSON configuration file format allows for the old style to be replicated if you are desperate! Added a feature to provide parameters to actions (`tap` or `template`). Added a feature to confirm `toggle` menu items. |
 
 ## Known Issues
 
 1. On some (old) devices (e.g. Vivoactive 3, Fenix 5s & Edge 520+), the menu does not update correctly to reflect changes in state effected by an external Home Assistant control. E.g. when the phone application changes the toggle status of a switch, the Garmin application does not reflect that change until the menu is touched or scrolled a little. This is a [known issue](https://forums.garmin.com/developer/connect-iq/i/bug-reports/menu2-doesn-t-allow-live-updates) already reported without a suggested software fix.
 
-2. Widgets have less memory than applications. With the new template based sensor display, widgets are more likely to run out of memory. E.g. a Vivoactive 3 device has a memory limit of 60 kB runtime memory for widgets (compare with 124 kB for applications) and is likely to be ~90% used. This makes it very likely that a larger menu will crash the application. We cannot predict what will take the application "over the edge", but we can provide this feedback to users to raise awareness.
+2. Widgets have less memory than applications. With the new template based sensor display, widgets are more likely to run out of memory. E.g. a Vivoactive 3 device has a memory limit of 60 kB runtime memory for widgets (compare with 124 kB for applications) and is likely to be ~90% used. This makes it very likely that a larger menu will crash the application. We cannot predict what will take the application "over the edge", but we can provide this feedback to users to raise awareness, hence the widget displays menu usage as a reminder.
+
+3. Templates can require significant definition for highly customised text. Just remember, you have the ability to crash the application by creating an excessively long menu definition. Older devices running as a widget can be limited in memory such that the JSON definition causes an "Out of Memory" error. Don't be silly. **Please don't give the application a poor review for an excessive menu definition!**
+
+4. Parameters to tap menu items cannot have their parameter usage verified. If you get this wrong and crash the application, that's your fault not the application's. In this case, start by removing the parameters for the menu item causing the crash, and add them back one at a time until you find your fault. **Please don't give the application a poor review for your bad parameter definition!**

examples/Actions.md

@@ -0,0 +1,52 @@
+# Actions
+
+A simple example using a scene as a `tap`` menu item.
+
+```json
+{
+  "entity": "scene.telly_watching",
+  "name": "Telly Scene",
+  "type": "tap",
+  "tap_action": {
+    "service": "scene.turn_on"
+  }
+},
+```
+
+Any menu item with an action (`tap`, `template`, or `toggle`), may have a confirmation view added. For consistency this is always done via the `tap_action` JSON object, even though for a `toggle` menu item there will only ever be a single field inside. For the `toggle` menu item, the confirmation is presented on both `on` and `off` directions. There is no option for asymmetry, i.e. only in one direction.
+
+```json
+  "tap_action": {
+    "confirm": true
+  }
+```
+
+For example:
+
+```json
+{
+  "entity": "switch.garage_door",
+  "name": "Garage Door",
+  "type": "toggle",
+  "tap_action": {
+    "confirm": true
+  }
+}
+```
+
+Note that for notify events, you _must_ not supply an `entity_id` or the API call will fail. There are other examples too.
+
+```json
+{
+  "name": "Message",
+  "type": "tap",
+  "tap_action": {
+    "service": "notify.mobile_app_on_phone",
+    "data": {
+      "title": "This is a title",
+      "message": "This is the message"
+    },
+    "confirm": true
+  }
+}
+```

examples/Templates.md

@@ -64,3 +64,71 @@ Here we generate a bar graph of the battery level. We use the following steps to
   "content": "{{ states('sensor.<device>_battery_level') }}%{% if is_state('binary_sensor.<device>_is_charging', 'on') %}+{% endif %} {{ '#' * (((states('sensor.<device>_battery_level') | int) / 100 * <width>) | int) }}{{ '_' * (<width> - (((states('sensor.<device>_battery_level') | int) / 100 * <width>) | int)) }}"
 }
 ```
+
+An example of a dimmer light with 4 brightness settings 0..3. Here our light worked on a percentage, so that had to be converted to the range 0..3.
+
+```json
+{
+  "$schema": "./schema.json",
+  "title": "Home",
+  "items": [
+    {
+      "entity": "light.green_house",
+      "name": "LEDs",
+      "type": "template",
+      "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) | int }}%{% else %}Off{% endif %}"
+    },
+    {
+      "entity": "light.green_house",
+      "name": "LEDs 0",
+      "type": "template",
+      "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) | int }}%{% else %}Off{% endif %}",
+      "tap_action": {
+        "service": "light.turn_on",
+        "data": {
+          "brightness_pct": 12
+        }
+      }
+    },
+    {
+      "entity": "light.green_house",
+      "name": "LEDs 1",
+      "type": "tap",
+      "tap_action": {
+        "service": "light.turn_on",
+        "data": {
+          "brightness_pct": 37
+        }
+      }
+    },
+    {
+      "entity": "light.green_house",
+      "name": "LEDs 2",
+      "type": "template",
+      "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) | int }}%{% else %}Off{% endif %}",
+      "tap_action": {
+        "service": "light.turn_on",
+        "data": {
+          "brightness_pct": 62
+        }
+      }
+    },
+    {
+      "entity": "light.green_house",
+      "name": "LEDs 3",
+      "type": "template",
+      "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) | int }}%{% else %}Off{% endif %}",
+      "tap_action": {
+        "service": "light.turn_on",
+        "data": {
+          "brightness_pct": 87
+        }
+      }
+    }
+  ]
+}
+```
+
+## Warnings
+
+Just remember, you have the ability to crash the application by creating an excessive menu definition. Older devices running as a widget can be limited in memory such that the JSON definition causes an "Out of Memory" error. Templates can require significant definition for highly customised text. Don't be silly.