From f9207eb32d9afb5d1af1663fe2bcdfc0219743f5 Mon Sep 17 00:00:00 2001
From: Andreas Motl <andreas.motl@panodata.org>
Date: Mon, 13 Mar 2023 00:20:40 +0100
Subject: [PATCH] [Pushsafer] Update documentation about config layout
 modernization

---
 CHANGES.rst |  1 +
 HANDBOOK.md | 64 +++++++++++++++++++++++++++++++++++++----------------
 2 files changed, 46 insertions(+), 19 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 48715090..e796e884 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -7,6 +7,7 @@ in progress
 ===========
 
 - Pushsafer: Fix to prevent submitting empty parameters to upstream API.
+- Pushsafer: Modernize configuration layout for target addresses.
 
 
 2023-02-13 0.32.0
diff --git a/HANDBOOK.md b/HANDBOOK.md
index 726267ea..947b171b 100644
--- a/HANDBOOK.md
+++ b/HANDBOOK.md
@@ -2449,38 +2449,64 @@ Requires:
 
 ### `pushsafer`
 
-This service is for [Pushsafer](https://www.pushsafer.com), an app for iOS, Android and Windows 10.
-In order to receive pushsafer notifications you need what is called a _private or alias key_:
+[Pushsafer](https://www.pushsafer.com) is an app for iOS, Android and Windows 10.
+You can define different notification targets, in turn dispatching to one or 
+multiple Pushsafer devices or groups.
+For a list of available icons, sounds and other parameters, see the
+[Pushsafer API](https://www.pushsafer.com/en/pushapi) documentation.
+
+#### Requirements
+In order to receive Pushsafer notifications, you need what is called a _private 
+or alias key_. To receive such a key, you will need to sign up for an account.
+
+#### Configuration example
 
 ```ini
 [config:pushsafer]
-targets = {
-    'nagios'     : ['privatekey', 'Device ID', 'Icon', 'Sound', 'Vibration', 'URL', 'Url Title', 'Time2Live', 'Priority', 'Retry', 'Expire', 'Answer'],
-    'tracking'   : ['aliaskey1'],
-    'extraphone' : ['aliaskey2', '', '', '', '', '', '', '60', '2', '60', '600', '0'],
-	'warnme'     : ['aliaskey3', '', '', '', '', '', '', '60', '1', '', '', '1']
+; https://www.pushsafer.com/en/pushapi
+; https://www.pushsafer.com/en/pushapi_ext
+targets = {
+    'basic': { 'private_key': '3SAz1a2iTYsh19eXIMiO' },
+    'nagios': {
+        'private_key': '3SAz1a2iTYsh19eXIMiO',
+        'device': '52|65|78',
+        'icon': 64,
+        'sound': 2,
+        'vibration': 1,
+        'url': 'http://example.org',
+        'url_title': 'Example Org',
+        'time_to_live': 60,
+        'priority': 2,
+        'retry': 60,
+        'expire': 600,
+        'answer': 1,
+        },
+    'tracking': {
+        'private_key': '3SAz1a2iTYsh19eXIMiO',
+        'device': 'gs23',
+        'icon': 18,
+        },
+    'extraphone': { 'private_key': 'aliaskey2', 'time_to_live': 60, 'priority': 2, 'retry': 60, 'expire': 600, 'answer': 0 },
+    'warnme': { 'private_key': 'aliaskey3', 'time_to_live': 60, 'priority': 1, 'answer': 1 },
     }
 ```
 
-This defines targets (`nagios`, `alerts`, etc.) which are directed to the
-configured _private or alias key_ combinations. This in turn enables you to
-notify, say, one or more of your devices as well as one for your spouse.
-For a list of available icons, sounds and other params see the
-[Pushsafer API](https://www.pushsafer.com/en/pushapi).
-
-Please note:
-- [Retry](https://www.pushsafer.com/en/pushapi_ext#API-RE)
-  with [Expire](https://www.pushsafer.com/en/pushapi_ext#API-EX): 
-  For configuring delivery retries, you must set both parameters.
+#### MQTT topic options
 
 | Topic option  |  M/O   | Description                            |
 | ------------- | :----: | -------------------------------------- |
 | `title`       |   O    | application title (dflt: pushsafer dflt) |
 
+#### Notes
+- [Retry](https://www.pushsafer.com/en/pushapi_ext#API-RE)
+  with [Expire](https://www.pushsafer.com/en/pushapi_ext#API-EX):
+  For configuring delivery retries, you must set both parameters.
+- The legacy configuration layout, based on a list for the `addrs` slot,
+  is still supported.
+
+#### Screenshot
 ![pushsafer on iOS](assets/pushsafer.jpg)
 
-Requires:
-* An account at [pushsafer.com](https://www.pushsafer.com/).
 
 ### `redispub`