From 56fc8562f4f60bf763db814db9629f7facfecd72 Mon Sep 17 00:00:00 2001 From: Onkel Andy Date: Sun, 29 Oct 2023 00:11:24 +0200 Subject: [PATCH 1/2] mailrcv plugin: replace readme by user_doc --- mailrcv/README.md | 80 -------------------------------------- mailrcv/user_doc.rst | 91 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 91 insertions(+), 80 deletions(-) delete mode 100755 mailrcv/README.md create mode 100644 mailrcv/user_doc.rst diff --git a/mailrcv/README.md b/mailrcv/README.md deleted file mode 100755 index 00dbacddc..000000000 --- a/mailrcv/README.md +++ /dev/null @@ -1,80 +0,0 @@ -# mailrcv - -## Requirements - -This plugin has no requirements or dependencies. - -## Configuration - -### plugin.yaml - -```yaml -imap: - plugin_name: mailrcv - host: mail.example.com - username: smarthome - password: secret - # tls: False - # port: default - # cycle: 300 -``` - -#### Attributes - * `host`: specifies the hostname of your mail server. - * `port`: if you want to use a nonstandard port. - * `username`/`password`: login information - * `tls`: specifies if you want to use SSL/TLS. - * `cycle`: for IMAP you could specify the intervall how often the inbox is checked - -### items.yaml - -There is no item specific configuration. - -### logic.yaml - -You could assign the following keywords to a logic. The matching order is as listed. - -#### mail_subject - -If the incoming mail subject matches the value of this key the logic will be triggerd. - -#### mail_to - -If the mail is sent to specified address the logic will be triggerd. - -If gmail is used, you can trigger multiple logics with one account - just extend email address -with ['+' sign](https://gmail.googleblog.com/2008/03/2-hidden-ways-to-get-more-from-your.html) -(eg use `myaccount+logicname@gmail.com` to trigger `logicname`) - -For safety reasons, use only dedicated gmail account with this plugin and filter out messages -from unkown senders (eg create filter `from:(-my_trusted_mail@example.com)` with action archive -or delete) - - -#### mail - -A generic flag to trigger the logic on receiving a mail. - -Attention: - * You could only call one logic per mail! - * If a mail is processed by a logic it will be delteted (moved to Deleted folder). - * There is no email security. You have to use an infrastructure which provides security (e.g. own mail server which only accepts authenticated messages for the inbox). - -```yaml -sauna: - filename: sauna.py - mail_to: sauna@example.com - -mailbox: - filename: mailbox.py - mail: 'yes' -``` - -A mail to `sauna@example.com` will only trigger the logic 'sauna'. Every other mail is process by the 'mailbox' logic. - -## Usage - -If a logic is triggered by this plugin it will set the trigger `source` to the from address and the `value` contains an [email object](http://docs.python.org/2.6/library/email.message.html). - -See the [phonebook logic](https://github.com/smarthomeNG/smarthome/wiki/Phonebook) for a logic which is triggerd by IMAP. - diff --git a/mailrcv/user_doc.rst b/mailrcv/user_doc.rst new file mode 100644 index 000000000..1087e2b7e --- /dev/null +++ b/mailrcv/user_doc.rst @@ -0,0 +1,91 @@ +.. index:: Plugins; mailrcv +.. index:: mailrcv + +======= +mailrcv +======= + +.. image:: webif/static/img/plugin_logo.png + :alt: plugin logo + :width: 400px + :height: 308px + :scale: 50 % + :align: left + +Konfiguration +============= + +Die Informationen zur Konfiguration des Plugins sind unter :doc:`/plugins_doc/config/mailrcv` beschrieben. + +plugin.yaml +----------- + +.. code:: yaml + + imap: + plugin_name: mailrcv + host: mail.example.com + username: smarthome + password: secret + # tls: False + # port: default + # cycle: 300 + +Logiken +======= + +Wenn eine Logik durch dieses Plugin ausgelöst wird, setzt es den Trigger +``source`` auf die Absenderadresse und der ``value`` enthält ein `Email +Objekt `_. + +Sie können die folgenden Schlüsselwörter einer Logik zuordnen. Die Reihenfolge der Zuordnung +ist wie aufgeführt: + +mail_subject +------------ + +Wenn der Betreff der eingehenden E-Mail mit dem Wert dieses Schlüssels übereinstimmt, +wird die Logik ausgelöst. + +mail_to +------- + +Wenn die E-Mail an die angegebene Adresse gesendet wird, wird die Logik ausgelöst. + +Wenn gmail verwendet wird, können Sie mehrere Logiken mit einem Konto auslösen - +Erweitern Sie einfach die E-Mail Adresse mit dem `+ Zeichen `__ +(z.B. benutzen Sie ``myaccount+logicname@gmail.com`` um ``logicname`` auszulösen) + +Aus Sicherheitsgründen sollten Sie nur ein spezielles gmail-Konto mit diesem Plugin verwenden +und filtern Sie Nachrichten von unbekannten Absendern herausfiltern (z.B. erstellen Sie den Filter +``from:(-my_trusted_mail@example.com)`` mit Aktion archivieren oder löschen) + +mail +---- + +Ein allgemeines Flag, um die Logik beim Empfang einer Mail auszulösen. + +.. important:: + + Es kann nur eine Logik pro Mail aufgerufen werden. Wenn eine Mail von einer Logik verarbeitet wird, wird sie gelöscht (in den Ordner "Gelöscht" verschoben). + +Es gibt keine E-Mail-Sicherheit. Sie müssen eine Infrastruktur verwenden, die Sicherheit bietet +(z.B. ein eigener Mailserver, der nur authentifizierte Nachrichten für den Posteingang akzeptiert). + +.. code-block:: yaml + + sauna: + filename: sauna.py + mail_to: sauna@example.com + + mailbox: + filename: mailbox.py + mail: 'yes' + +Eine Mail an ``sauna@example.com`` wird nur die Logik 'Sauna' auslösen. +Alle anderen Mails werden von der Logik "Mailbox" verarbeitet. + +Web Interface +============= + +Das Plugin stellt kein Web Interface zur Verfügung. From d13580541d70baae75103d713a76eaff4a7f30b7 Mon Sep 17 00:00:00 2001 From: Onkel Andy Date: Sun, 29 Oct 2023 00:12:31 +0200 Subject: [PATCH 2/2] mailrcv plugin: add super().__init__() , push version to 1.4.2 --- mailrcv/__init__.py | 3 ++- mailrcv/plugin.yaml | 4 +--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/mailrcv/__init__.py b/mailrcv/__init__.py index 4233e0a55..16c35e3ec 100755 --- a/mailrcv/__init__.py +++ b/mailrcv/__init__.py @@ -29,9 +29,10 @@ class IMAP(SmartPlugin): ALLOW_MULTIINSTANCE = True - PLUGIN_VERSION = "1.4.1" + PLUGIN_VERSION = "1.4.2" def __init__(self, sh, *args, **kwargs): + super().__init__() self._host = self.get_parameter_value('host') self._port = self.get_parameter_value('port') self._username = self.get_parameter_value('username') diff --git a/mailrcv/plugin.yaml b/mailrcv/plugin.yaml index 4339cc5c6..c8616ca77 100755 --- a/mailrcv/plugin.yaml +++ b/mailrcv/plugin.yaml @@ -12,7 +12,7 @@ plugin: # documentation: https://github.com/smarthomeNG/smarthome/wiki/CLI-Plugin # url of documentation (wiki) page # support: https://knx-user-forum.de/forum/supportforen/smarthome-py - version: 1.4.1 # Plugin version + version: 1.4.2 # Plugin version sh_minversion: 1.4 # minimum shNG version to use this plugin # sh_maxversion: # maximum shNG version to use this plugin (leave empty if latest) multi_instance: True # plugin supports multi instance @@ -85,5 +85,3 @@ plugin_functions: NONE logic_parameters: NONE # Definition of logic parameters defined by this plugin - -