From f51197ff752e5187974404a9ac17b1b9f57f64c1 Mon Sep 17 00:00:00 2001 From: Matthias Oesterheld Date: Wed, 13 Nov 2024 22:10:24 +0100 Subject: [PATCH] adjust docs --- README.md | 5 ++++- examples/Actions.md | 16 ++++++++++++++++ examples/Switches.md | 15 ++++++++++++++- examples/Templates.md | 8 ++++---- images/pin_view.png | Bin 0 -> 8350 bytes 5 files changed, 38 insertions(+), 6 deletions(-) create mode 100644 images/pin_view.png diff --git a/README.md b/README.md index 2a9c705..05d6aaa 100644 --- a/README.md +++ b/README.md @@ -131,7 +131,8 @@ Example schema: "name": "TV Lights Scene", "type": "tap", "tap_action": { - "service": "scene.turn_on" + "service": "scene.turn_on", + "pin": true } } ] @@ -264,6 +265,8 @@ The application timeout prevents the HomeAssistant App running on your watch whe 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 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. + There is a toggle setting for "text alignment" that provides finer adjustment for right-to-left languages. Perhaps this could be made automatic based on device language? The application and widget both include a background service to report your watch's battery level and charging status. You may enable a background service to report the battery level to your Home Assistant. This is not available over your Bluetooth connection like with other Bluetooth devices as Garmin did not implement it. This no longer requires any setup, and we offer this [trouble shooting](TroubleShooting.md#watch-battery-level-reporting) guide. The last field here is readonly and allows the user to copy & paste the Webhook ID setup by the application when required for this trouble shooting guide. diff --git a/examples/Actions.md b/examples/Actions.md index 3d840c0..db2d1b0 100644 --- a/examples/Actions.md +++ b/examples/Actions.md @@ -38,6 +38,22 @@ For example: } ``` +**Please be advised that for security sensitive actions, a PIN confirmation should be used.** + +This can be enabled by setting the `pin` field in the `tap_action`. The `pin` field overrides `confirm`. Explicitly setting `confirm` is not necessary. + +The 4-digit PIN is set globally for all actions in the app settings in Connect IQ. + +```json + "tap_action": { + "pin": true + } +``` + +When entering an invalid PIN for the fifth time within 2 minutes, the PIN dialog will be locked for all actions for the next 10 minutes. Entering a valid PIN will always reset the failure counter. + + + Note that for notify events, you _must_ not supply an `entity_id` or the API call will fail. There are other examples too. ```json diff --git a/examples/Switches.md b/examples/Switches.md index 0474499..fa22fa5 100644 --- a/examples/Switches.md +++ b/examples/Switches.md @@ -22,7 +22,20 @@ And with an optional confirmation: "tap_action": { "confirm": true } - }, + } +``` + +or an optional PIN confirmation: + +```json + { + "entity": "light.exterior", + "name": "Exterior Lights", + "type": "toggle", + "tap_action": { + "pin": true + } + } ``` To support a non-standard light, switch, or automation as a toggle menu item you may like to define a custom switch. In order to facilitate custom switches at this time, you must create a template switch in HomeAssistant. diff --git a/examples/Templates.md b/examples/Templates.md index ccc20b3..ec27d82 100644 --- a/examples/Templates.md +++ b/examples/Templates.md @@ -101,10 +101,10 @@ Here we also use the else clause as well to give proper text instead of just `on > [!IMPORTANT] > We advise users against adding security devices. -However, users are doing this **against our advice** and asking how to operate 'covers'. This is an example of toggling a garage door open and closed with confirmation. *Do this at your own risk*. +However, for users doing this **against our advice**, we strongly recommend to secure confirmation of the action using our PIN confirmation dialog. +This an example of toggling a garage door open and closed with a PIN confirmation. *Do this at your own risk*. -In order to provide some additional security, users with touch devices can now choose to use a PIN confirmation when using actions annotated with `"confirm": true`. -This is activated once a PIN is configured in the application settings. The PIN needs to be a 4-digit number. +The PIN confirmation is activated for actions with `"pin": true`. The PIN is configured globally in the application settings. The PIN needs to be a 4-digit number. The user has 5 attempts to provide a valid PIN within 2 minutes. If too many failures have been detected during this time, the PIN dialog will be locked for 10 minutes. Note: Only when you use the `tap_action` field do you also need to include the `entity` field. This is a change to a previous version of the application, hence the presence of the `entity` field will be ignored for backwards compatibility, and the schema will provide a warning only. @@ -117,7 +117,7 @@ Note: Only when you use the `tap_action` field do you also need to include the ` "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", - "confirm": true + "pin": true } } ``` diff --git a/images/pin_view.png b/images/pin_view.png new file mode 100644 index 0000000000000000000000000000000000000000..7f8158c3e51bce4c7cf31838937056f4d3034f9a GIT binary patch literal 8350 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