From 7b55429d35ea57a1b290d674bd41e4b92fe84df9 Mon Sep 17 00:00:00 2001 From: Florian Klien Date: Sat, 13 Oct 2018 21:20:37 +0200 Subject: [PATCH 1/7] xmpp http upload documented --- source/_components/notify.xmpp.markdown | 78 ++++++++++++++++++++++++- 1 file changed, 77 insertions(+), 1 deletion(-) diff --git a/source/_components/notify.xmpp.markdown b/source/_components/notify.xmpp.markdown index 45f452f5a880..f65583e698de 100644 --- a/source/_components/notify.xmpp.markdown +++ b/source/_components/notify.xmpp.markdown @@ -74,4 +74,80 @@ room: All Jabber IDs (JID) must include the domain. Make sure that the password matches the account provided as sender. -To use notifications, please see the [getting started with automation page](/getting-started/automation/). +You can send text messages and images as well as other files through Jabber. + +Here are some examples on how to set up a script, that can be run from an automation. +To send files and images, your jabber server must support HTTP upload ([XEP_0363](https://xmpp.org/extensions/xep-0363.html)). + +Number 1 shows a classical, text-only message. The Title is optional, although if omitted, +`Home-Assistant` will be set. To keep it empty set it to `""`. + +```yaml +# Example script.yaml entry +1_send_jabber_message: + alias: "Text only Jabber message" + sequence: + - service: notify.jabber # notify.NOTIFIER_NAME + data: + title: "Optional Title" + message: "My funny or witty message" +``` + +Number 2 sends only an image, retrieved from the URL. + +```yaml +2_send_jabber_message_with_image_url: + alias: "Send Image via Jabber from website" + sequence: + - service: notify.jabber + data: + title: "" + message: "" + data: + url: "https://www.graz.at:8443/webcam_neu/getimg.php" +``` + +Number 3 sends an image from a local path. + +```yaml +3_send_jabber_message_with_local_image_path: + alias: "Send Image via Jabber from local file" + sequence: + - service: notify.jabber + data: + title: "" + message: "" + data: + path: "/home/homeassistant/super_view.jpg" +``` + +Number 4 sends a text-file, retrieved from Github, renamed to `Hass_Cheatsheet.txt` to be viewable on a mobile Android device, as most don't offer any application to view `.md` files. + +```yaml +4_send_jabber_message_with_file: + alias: "Send text file via Jabber" + sequence: + - service: notify.jabber + data: + title: "" + message: "" + data: + url: "https://raw.githubusercontent.com/arsaboo/homeassistant-config/master/HASS%20Cheatsheet.md" + path: "Hass_Cheatsheet.txt" +``` + +Number 5 sends an image retrieved from a URL, and an additional text message with `title` and `message`. + +```yaml +5_send_jabber_message_with_image_and_text: + alias: "Send Image and Text via Jabber" + sequence: + - service: notify.jabber + data: + title: "The Time is now" + message: "{% raw %} {{ {% endraw %}now(){% raw %} }} {% endraw %}, templating works as well..." + data: + url: "https://github.com/home-assistant/home-assistant.io/raw/next/source/images/favicon-192x192.png" +``` + +To find out more about notifications, please see the [getting started with automation page](/getting-started/automation/). From c72dc67a87e7fb8962ddea3e0b07827bcf190b42 Mon Sep 17 00:00:00 2001 From: Florian Klien Date: Sun, 14 Oct 2018 09:41:50 +0200 Subject: [PATCH 2/7] titles, note for rooms --- source/_components/notify.xmpp.markdown | 30 +++++++++++++++++++------ 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/source/_components/notify.xmpp.markdown b/source/_components/notify.xmpp.markdown index f65583e698de..8b1bb2481f00 100644 --- a/source/_components/notify.xmpp.markdown +++ b/source/_components/notify.xmpp.markdown @@ -22,7 +22,7 @@ To enable Jabber notifications in your installation, add the following to your ` ```yaml # Example configuration.yaml entry notify: - - name: NOTIFIER_NAME + - name: NOTIFIER_NAME # e.g. jabber platform: xmpp sender: YOUR_JID password: YOUR_JABBER_ACCOUNT_PASSWORD @@ -34,7 +34,7 @@ name: description: "Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`." required: false type: string - default: Random Sensor + default: notify sender: description: "The Jabber ID (JID) that will act as origin of the messages. Add your JID including the domain, e.g. your_name@jabber.org." required: true @@ -45,23 +45,23 @@ resource: type: string default: home-assistant password: - description: The password for your given Jabber account. + description: "The password for your given Jabber account." required: true recipient: description: The Jabber ID (JID) that will receive the messages. required: true tls: - description: Force TLS. + description: "Force TLS." required: false type: boolean default: true verify: - description: Allow disabling SSL certificate validity check, e.g., self-signed certificate. + description: "Allow disabling SSL certificate validity check, e.g., self-signed certificate." required: false type: boolean default: true room: - description: Room's name (e.g., example@conference.jabber.org). If set, send a message to chatroom instead of the recipient. + description: "Room's name (e.g., example@conference.jabber.org). If set, send a message to chatroom instead of the recipient." required: false type: string {% endconfiguration %} @@ -76,6 +76,8 @@ All Jabber IDs (JID) must include the domain. Make sure that the password matche You can send text messages and images as well as other files through Jabber. +### {% linkable_title Jabber Text Message %} + Here are some examples on how to set up a script, that can be run from an automation. To send files and images, your jabber server must support HTTP upload ([XEP_0363](https://xmpp.org/extensions/xep-0363.html)). @@ -87,15 +89,22 @@ Number 1 shows a classical, text-only message. The Title is optional, although i 1_send_jabber_message: alias: "Text only Jabber message" sequence: - - service: notify.jabber # notify.NOTIFIER_NAME + - service: notify.jabber # from notify.NOTIFIER_NAME data: title: "Optional Title" message: "My funny or witty message" ``` +### {% linkable_title Jabber Image Message %} + +

+ Currently sending images to rooms is not supported. +

+ Number 2 sends only an image, retrieved from the URL. ```yaml +# Example script.yaml entry 2_send_jabber_message_with_image_url: alias: "Send Image via Jabber from website" sequence: @@ -110,6 +119,7 @@ Number 2 sends only an image, retrieved from the URL. Number 3 sends an image from a local path. ```yaml +# Example script.yaml entry 3_send_jabber_message_with_local_image_path: alias: "Send Image via Jabber from local file" sequence: @@ -121,9 +131,12 @@ Number 3 sends an image from a local path. path: "/home/homeassistant/super_view.jpg" ``` +### {% linkable_title Jabber File Message %} + Number 4 sends a text-file, retrieved from Github, renamed to `Hass_Cheatsheet.txt` to be viewable on a mobile Android device, as most don't offer any application to view `.md` files. ```yaml +# Example script.yaml entry 4_send_jabber_message_with_file: alias: "Send text file via Jabber" sequence: @@ -136,9 +149,12 @@ Number 4 sends a text-file, retrieved from Github, renamed to `Hass_Cheatsheet.t path: "Hass_Cheatsheet.txt" ``` +### {% linkable_title Jabber Text and Image Message %} + Number 5 sends an image retrieved from a URL, and an additional text message with `title` and `message`. ```yaml +# Example script.yaml entry 5_send_jabber_message_with_image_and_text: alias: "Send Image and Text via Jabber" sequence: From b4d8e8e2b3de08d471ebe75f171910817301350c Mon Sep 17 00:00:00 2001 From: Florian Klien Date: Mon, 15 Oct 2018 19:42:19 +0200 Subject: [PATCH 3/7] document unverified request for image retrieval --- source/_components/notify.xmpp.markdown | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/_components/notify.xmpp.markdown b/source/_components/notify.xmpp.markdown index 8b1bb2481f00..e9ff9e50c67b 100644 --- a/source/_components/notify.xmpp.markdown +++ b/source/_components/notify.xmpp.markdown @@ -101,7 +101,7 @@ Number 1 shows a classical, text-only message. The Title is optional, although i Currently sending images to rooms is not supported.

-Number 2 sends only an image, retrieved from the URL. +Number 2 sends only an image, retrieved from the URL. The TLS connection to get the image is also not verified (use with caution). ```yaml # Example script.yaml entry @@ -114,6 +114,7 @@ Number 2 sends only an image, retrieved from the URL. message: "" data: url: "https://www.graz.at:8443/webcam_neu/getimg.php" + verify: false ``` Number 3 sends an image from a local path. From 441735a89ddaeabf871c63cf8281259783c5527e Mon Sep 17 00:00:00 2001 From: Florian Klien Date: Wed, 17 Oct 2018 20:06:34 +0200 Subject: [PATCH 4/7] reverting some quotes in configuration section --- source/_components/notify.xmpp.markdown | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/_components/notify.xmpp.markdown b/source/_components/notify.xmpp.markdown index e9ff9e50c67b..14e04c692e1e 100644 --- a/source/_components/notify.xmpp.markdown +++ b/source/_components/notify.xmpp.markdown @@ -45,18 +45,18 @@ resource: type: string default: home-assistant password: - description: "The password for your given Jabber account." + description: The password for your given Jabber account. required: true recipient: description: The Jabber ID (JID) that will receive the messages. required: true tls: - description: "Force TLS." + description: Force TLS. required: false type: boolean default: true verify: - description: "Allow disabling SSL certificate validity check, e.g., self-signed certificate." + description: Allow disabling SSL certificate validity check, e.g., self-signed certificate. required: false type: boolean default: true From 98553630b7ece46659621356a3abdcfe13f41ea9 Mon Sep 17 00:00:00 2001 From: Florian Klien Date: Sun, 28 Oct 2018 23:27:00 +0100 Subject: [PATCH 5/7] xmpp docs update --- source/_components/notify.xmpp.markdown | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/source/_components/notify.xmpp.markdown b/source/_components/notify.xmpp.markdown index 14e04c692e1e..a960a0dbf10f 100644 --- a/source/_components/notify.xmpp.markdown +++ b/source/_components/notify.xmpp.markdown @@ -79,7 +79,6 @@ You can send text messages and images as well as other files through Jabber. ### {% linkable_title Jabber Text Message %} Here are some examples on how to set up a script, that can be run from an automation. -To send files and images, your jabber server must support HTTP upload ([XEP_0363](https://xmpp.org/extensions/xep-0363.html)). Number 1 shows a classical, text-only message. The Title is optional, although if omitted, `Home-Assistant` will be set. To keep it empty set it to `""`. @@ -97,8 +96,13 @@ Number 1 shows a classical, text-only message. The Title is optional, although i ### {% linkable_title Jabber Image Message %} +You can send images or files from locally stored files or remote web locations via Jabber's HTTP Upload feature. +To send files and images, your jabber server must support [XEP_0363](https://xmpp.org/extensions/xep-0363.html). +

- Currently sending images to rooms is not supported. +Be aware that images are uploaded onto the Jabber server of your provider. They reside there un-encrypted and could be accessed by the server admins. Usually images are deleted after a few days. +
+Home-Assistant supports TLS encryption to ensure transport encryption. TLS is enforced by default. You can disable it with the [`tls`](#tls) flag -- which is not recommended.

Number 2 sends only an image, retrieved from the URL. The TLS connection to get the image is also not verified (use with caution). @@ -134,7 +138,7 @@ Number 3 sends an image from a local path. ### {% linkable_title Jabber File Message %} -Number 4 sends a text-file, retrieved from Github, renamed to `Hass_Cheatsheet.txt` to be viewable on a mobile Android device, as most don't offer any application to view `.md` files. +Number 4 sends a text-file, retrieved from Github, renamed to `Hass_Cheatsheet.txt` to be viewable on a mobile Android device, as most don't offer any application to view `.md` files. Optionally you can add a timeout for the HTTP upload in seconds. ```yaml # Example script.yaml entry @@ -148,6 +152,7 @@ Number 4 sends a text-file, retrieved from Github, renamed to `Hass_Cheatsheet.t data: url: "https://raw.githubusercontent.com/arsaboo/homeassistant-config/master/HASS%20Cheatsheet.md" path: "Hass_Cheatsheet.txt" + timeout: 10 ``` ### {% linkable_title Jabber Text and Image Message %} From 0e5831262a0218a385a421fc71ad5fd1929db348 Mon Sep 17 00:00:00 2001 From: Florian Klien Date: Tue, 30 Oct 2018 23:08:03 +0100 Subject: [PATCH 6/7] XMPP HTTP upload: added templating docs for url and path --- source/_components/notify.xmpp.markdown | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/source/_components/notify.xmpp.markdown b/source/_components/notify.xmpp.markdown index a960a0dbf10f..c37d3b03c868 100644 --- a/source/_components/notify.xmpp.markdown +++ b/source/_components/notify.xmpp.markdown @@ -138,6 +138,7 @@ Number 3 sends an image from a local path. ### {% linkable_title Jabber File Message %} + Number 4 sends a text-file, retrieved from Github, renamed to `Hass_Cheatsheet.txt` to be viewable on a mobile Android device, as most don't offer any application to view `.md` files. Optionally you can add a timeout for the HTTP upload in seconds. ```yaml @@ -155,7 +156,7 @@ Number 4 sends a text-file, retrieved from Github, renamed to `Hass_Cheatsheet.t timeout: 10 ``` -### {% linkable_title Jabber Text and Image Message %} +### {% linkable_title Templating %} Number 5 sends an image retrieved from a URL, and an additional text message with `title` and `message`. @@ -172,4 +173,21 @@ Number 5 sends an image retrieved from a URL, and an additional text message wit url: "https://github.com/home-assistant/home-assistant.io/raw/next/source/images/favicon-192x192.png" ``` +Number 6 sends an image from a templated URL. + +```yaml +# Example script.yaml entry +6_send_jabber_message_with_image_from_url_template: + alias: "Send Image from template URL via Jabber" + sequence: + - service: notify.jabber + data: + title: "" + message: "" + data: + url_template: "https://www.foto-webcam.eu/webcam/dornbirn/{% raw %}{{ now().year }}/{{ now().month }}/{{ now().day }}/{{ now().hour }}{{ (now().minute + 58) % 60 // 10}}{% endraw %}0_hd.jpg" +``` + +The possible source of a file is prioritized and only one will be picked up. `url_template` has the hightest priority; next is `url` then `path_template` and finally if none of them are defined `path` would be used. `path` will be used to eliminate file extension guessing for unknown URL downloads. Only the file extension will be left, as Home Assistant changes the filename to a random string for added privacy. + To find out more about notifications, please see the [getting started with automation page](/getting-started/automation/). From 16399fa2752ae49417f98521960b7b0753c7bc57 Mon Sep 17 00:00:00 2001 From: Florian Klien Date: Fri, 2 Nov 2018 10:38:26 +0100 Subject: [PATCH 7/7] =?UTF-8?q?fix=20url=20template=20in=20example=20n?= =?UTF-8?q?=C2=B06?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- source/_components/notify.xmpp.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_components/notify.xmpp.markdown b/source/_components/notify.xmpp.markdown index c37d3b03c868..6c79aa48fa8c 100644 --- a/source/_components/notify.xmpp.markdown +++ b/source/_components/notify.xmpp.markdown @@ -185,7 +185,7 @@ Number 6 sends an image from a templated URL. title: "" message: "" data: - url_template: "https://www.foto-webcam.eu/webcam/dornbirn/{% raw %}{{ now().year }}/{{ now().month }}/{{ now().day }}/{{ now().hour }}{{ (now().minute + 58) % 60 // 10}}{% endraw %}0_hd.jpg" + url_template: "https://www.foto-webcam.eu/webcam/dornbirn/{% raw %}{{ now().year }}/{{ '%02d' % now().month }}/{{ '%02d' % now().day }}/{{ '%02d' % now().hour }}{{ (now().minute + 58) % 60 // 10}}{% endraw %}0_hd.jpg" ``` The possible source of a file is prioritized and only one will be picked up. `url_template` has the hightest priority; next is `url` then `path_template` and finally if none of them are defined `path` would be used. `path` will be used to eliminate file extension guessing for unknown URL downloads. Only the file extension will be left, as Home Assistant changes the filename to a random string for added privacy.