mirror of
https://github.com/letscontrolit/ESPEasy.git
synced 2026-07-28 04:07:47 +00:00
Created Docs (RTD) for updated Notifications Email plugin.
This commit is contained in:
thomastech
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
@@ -0,0 +1,195 @@
|
||||
.. include:: _notify_substitutions_n00x.repl
|
||||
|
||||
.. _N001_page:
|
||||
|
||||
.. role:: raw-html(raw)
|
||||
:format: html
|
||||
|
||||
Notifications Email (SMTP)
|
||||
===========================
|
||||
|
||||
|N001_shortinfo|
|
||||
|
||||
Type: |N001_type|
|
||||
|
||||
Name: |N001_name|
|
||||
|
||||
Status: |N001_status|
|
||||
|
||||
GitHub: |N001_github|_
|
||||
|
||||
Maintainer: |N001_maintainer|
|
||||
|
||||
Used libraries: |N001_usedlibraries|
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
*Notifications Email (SMTP)* is used to send an email message using ESPEasy rules.
|
||||
|
||||
:raw-html:`<br clear="all">`
|
||||
|
||||
Basic Rules Examples
|
||||
---------------------
|
||||
|
||||
The general syntax for sending an email is:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
notify <Nr>
|
||||
|
||||
Where <Nr> is the position number (1,2,3) assigned to the notification declaration.
|
||||
|
||||
For example, to send your pre-defined email message after WiFi has connected, use a rule like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
on WiFi#Connected do
|
||||
notify 1
|
||||
endon
|
||||
|
||||
To send an email every day at noon, create a rule like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
on Clock#Time=All,12:00 do //will run once a day at noon
|
||||
notify 1
|
||||
endon
|
||||
|
||||
.. hint::
|
||||
The examples discussed here have setup the Notification Email in the very first (Nr 1) row. So the command syntax will be "*notify 1*"
|
||||
|
||||
:raw-html:`<br clear="all">`
|
||||
|
||||
Email Configuration
|
||||
--------------------
|
||||
|
||||
ESPEasy's Notifications tab allows up to three declarations for email (and buzzer) alerts.
|
||||
|
||||
.. image:: NotifyEmail1.png
|
||||
:width: 600
|
||||
:alt: Notifications Tab
|
||||
|
||||
:raw-html:`<br clear="all">`
|
||||
|
||||
The *Notifications Email* page is used to create pre-defined email messages.
|
||||
At least one is required to use the email feature.
|
||||
|
||||
From the *Notifications* page, press *Edit* on an available *Nr* option. Next, Choose *Email (SMTP)* in the drop-down list.
|
||||
|
||||
.. image:: NotifyEmail2.png
|
||||
:width: 600
|
||||
:alt: Email Configuration Example
|
||||
|
||||
* **Domain :** Mail provider domain.
|
||||
* **Server :** Mail server address (DNS or IP number). Must support non-secure SMTP.
|
||||
* **Port :** Server port number. TLS / SSL ports are NOT supported.
|
||||
* **Timeout :** Maximum allowed time for server reply. Increase value if server timeouts occur.
|
||||
* **Sender :** Sender's email address ("From:").
|
||||
* **Receiver :** Recipient's email address ("To:"). Multiple allowed, use comma (,) between each address.
|
||||
* **Subject :** Text for email's subject line.
|
||||
* **User :** Server user name.
|
||||
* **Pass :** Server password.
|
||||
* **Body :** Message text. System variables allowed. Use <br> for new line. Maximum 512 characters.
|
||||
* **Enabled :** Check this box to enable the email feature.
|
||||
|
||||
Be sure to press *Submit* to save your settings.
|
||||
|
||||
Note: For more flexibility, there are :ref:`adv_feat` that allow customized email recipients and/or messages.
|
||||
|
||||
:raw-html:`<br clear="all">`
|
||||
|
||||
Email Server Requirements
|
||||
--------------------------
|
||||
|
||||
ESPEasy doesn't support the SSL protocol.
|
||||
Unfortunately most Email service providers ended support for non-secure SMTP (without TLS / SSL) several years ago.
|
||||
This means that ESPEasy's email is **not** directly compatible with popular providers such as gmail.com, yahoo.com, aol.com, and many others.
|
||||
|
||||
But there are two workarounds for the SSL issue, as follows:
|
||||
|
||||
* Operate a mail server inside your local network.
|
||||
* Use an SMTP Email account from a provider that still supports non-secure SMTP (e.g. SMTP2go.com, smart-mail.de).
|
||||
Services such as SMTP2go will act as an SSL bridge from a non-secure sender.
|
||||
Personal (non-commercial) accounts are available at no cost too.
|
||||
|
||||
The table below provides sample entries for smtp2go.com and smtp.smart-mail.de
|
||||
|
||||
+-----------+--------------------+--------------------+--------------------------------------+
|
||||
| Name | Example 1 | Example 2 | Description |
|
||||
+===========+====================+====================+======================================+
|
||||
| Domain: | smtp2go.com | smart-mail.de | Mail provider domain. |
|
||||
+-----------+--------------------+--------------------+--------------------------------------+
|
||||
| Server: | mail.smtp2go.com | smtp.smart-mail.de | Mail server address. |
|
||||
+-----------+--------------------+--------------------+--------------------------------------+
|
||||
| Port: | 2525 | 25 | SMTP port recommended by provider. |
|
||||
+-----------+--------------------+--------------------+--------------------------------------+
|
||||
| Sender: | joe@gmail.com | joe@anydomain.com | Sender's email address. |
|
||||
+-----------+--------------------+--------------------+--------------------------------------+
|
||||
| Receiver: | Jim@yahoo.com | Jim@domain.com | Recipient's email address. |
|
||||
| | | | Note: Multiple allowed, |
|
||||
| | | | use comma (,) between each address.|
|
||||
+-----------+--------------------+--------------------+--------------------------------------+
|
||||
| Subject: | Subject Text | Subject Text | Topic in email headline. |
|
||||
+-----------+--------------------+--------------------+--------------------------------------+
|
||||
| User: | ESP123 | ESP@smart-mail.de | Username to the SMTP Server. |
|
||||
+-----------+--------------------+--------------------+--------------------------------------+
|
||||
| Pass: | secretepw001%% | secretepw002$$ | Password to the SMTP Server. |
|
||||
+-----------+--------------------+--------------------+--------------------------------------+
|
||||
| Body: | Device uptime is %uptime% mins.<br> | 512 characters max. |
|
||||
| | Connected via WiFi %ssid%. | Use <br> for new line. |
|
||||
+-----------+--------------------+--------------------+--------------------------------------+
|
||||
| Enabled: | Check Box | Check Box | Email is disabled if box unchecked. |
|
||||
+-----------+--------------------+--------------------+--------------------------------------+
|
||||
|
||||
|
||||
:raw-html:`<br clear="all">`
|
||||
|
||||
.. _adv_feat:
|
||||
|
||||
Advanced Features
|
||||
------------------
|
||||
|
||||
Along with the pre-defined settings, it is possible to customized the email message body and recipient address from a Notify command rule.
|
||||
So ad-hoc emails are possible.
|
||||
|
||||
.. hint::
|
||||
Use the latest ESPEasy build. Older releases do not support these advanced features.
|
||||
|
||||
The general syntax for a custom message body is:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
notify <Nr>, "Your Custom Message goes Here."
|
||||
|
||||
So to specify a custom message with the Notify command, simply use a rule like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
notify 1,"%sysname% is online.<br>Location: Office.<br>Local IP: %ip%.<br>WiFi Signal: %rssi%dBm."
|
||||
|
||||
|
||||
The custom message can also include the email recipient.
|
||||
The general syntax is:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
notify <Nr>, "{email@domain.com},This is the email message. System variables can be used here."
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
notify 1,"{jimmydean@domain123.com},%sysname% has rebooted.<br>Local IP: %ip%.<br>WiFi Signal: %rssi%dBm.<br>Have a great day."
|
||||
|
||||
Multiple email recipients can be specified too. Use a comma (,) between addresses.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
notify 1,"{email123@domain.com,billy@steamhouseinc.com},The steam boiler is overheating!"
|
||||
|
||||
.. hint::
|
||||
A custom message MUST be provided whenever the recipient address is specified in the Notify command.
|
||||
Be sure to wrap the entire payload in quotations.
|
||||
|
||||
:raw-html:`<br clear="all">`
|
||||
@@ -0,0 +1,130 @@
|
||||
.. include:: _notify_substitutions_n00x.repl
|
||||
.. include:: ../Plugin/_plugin_substitutions_p00x.repl
|
||||
|
||||
.. _N002_page:
|
||||
|
||||
.. role:: raw-html(raw)
|
||||
:format: html
|
||||
|
||||
Notifications Buzzer
|
||||
=====================
|
||||
|
||||
|N002_shortinfo|
|
||||
|
||||
Type: |N002_type|
|
||||
|
||||
Name: |N002_name|
|
||||
|
||||
Status: |N002_status|
|
||||
|
||||
GitHub: |N002_github|_
|
||||
|
||||
Maintainer: |N002_maintainer|
|
||||
|
||||
Used libraries: |N002_usedlibraries|
|
||||
|
||||
|
||||
Introduction
|
||||
-------------
|
||||
|
||||
*Notifications Buzzer* is used to trigger an audio beep tone.
|
||||
This is ideal for system alerts and other attention seeking situations.
|
||||
|
||||
A "Notify" command is used in the device rule file to produce the sound.
|
||||
It is a simple 440Hz tone with 500mS duration.
|
||||
|
||||
Please be aware that ESPEasy supports a more advanced audio tone feature named *Buzzer (RTTTL)* that can produce user defined melodies.
|
||||
|
||||
.. hint:: To learn about the RTTTL tone feature please click here :ref:`P000_Buzzer_page`
|
||||
|
||||
:raw-html:`<br clear="all">`
|
||||
|
||||
Speaker Driver
|
||||
---------------
|
||||
|
||||
There are many ways to adapt the GPIO output to drive a piezo transducer or common speaker.
|
||||
Adding an alert beep sound to a microcontroller is a popular topic discussed by Arduino project builders.
|
||||
So for inspiration a quick internet search is all that is required.
|
||||
The implementation can be fully DiY using a simple transistor driver circuit, a ready-to-use module, or 1000 watt rock concert amplifier with a stage full of speakers.
|
||||
|
||||
Be aware that the tone frequency is created by software.
|
||||
So the audio output device must be the "passive" type that does not include an oscillator.
|
||||
|
||||
Keep in mind that common buzzers and beepers are turned on by a fixed voltage; Do **NOT** use that type with the Notfications feature.
|
||||
|
||||
The idle state for the Buzzer's GPIO pin is logic low.
|
||||
So the driver circuit should have an active high turn-on state, which will be toggled on/off to create the tone's fixed 440Hz frequency.
|
||||
|
||||
Below is one such circuit, which requires only three components:
|
||||
|
||||
* 2N7000 MOSFET Transistor
|
||||
* 22Ω 1/8W Resistor
|
||||
* 8-16 ohm Speaker
|
||||
|
||||
.. image:: BuzzerSchem.png
|
||||
:width: 275
|
||||
:alt: Simple Speaker Driver Circuit
|
||||
|
||||
:raw-html:`<br clear="all">`
|
||||
|
||||
ESPEasy Buzzer Configuration
|
||||
-----------------------------
|
||||
|
||||
ESPEasy's *Notifications* tab allows up to three declarations for email and buzzer alerts.
|
||||
Only one Buzzer entry is needed to enable the feature.
|
||||
|
||||
.. image:: NotifyBuzzer1.png
|
||||
:width: 600
|
||||
:alt: Notfications Tab
|
||||
|
||||
:raw-html:`<br clear="all">`
|
||||
|
||||
From the *Notifications* page, press *Edit* on an available *Nr* option. Next, Choose *Buzzer* in the drop-down list and select the GPIO pin number for your audio output.
|
||||
Be sure to check the *Enabled* box before pressing the *Submit* button.
|
||||
|
||||
.. image:: NotifyBuzzer2.png
|
||||
:width: 600
|
||||
:alt: Buzzer Configuration Example
|
||||
|
||||
:raw-html:`<br clear="all">`
|
||||
|
||||
|
||||
Command Syntax
|
||||
---------------
|
||||
|
||||
The general syntax for making a buzzer noise is:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
notify <Nr>
|
||||
|
||||
Where <Nr> is the position number (1,2,3) assigned to the notification declaration.
|
||||
|
||||
:raw-html:`<br clear="all">`
|
||||
|
||||
Rules Example
|
||||
--------------
|
||||
|
||||
To make a buzzer sound on startup, create a rule like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
On System#Boot do
|
||||
notify 1 // Beep!
|
||||
endon
|
||||
|
||||
|
||||
To make a buzzer sound every 60 seconds, create a rule file with these commands:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
On System#Boot do
|
||||
timerSet,1,60 // Start the timer.
|
||||
endon
|
||||
|
||||
On Rules#Timer=1 do
|
||||
timerSet,1,60 // Restart the timer.
|
||||
notify 1 // Beep!
|
||||
endon
|
||||
|
||||
.. hint:: The examples discussed here have setup the buzzer in the very first (Nr 1) row. So the command syntax will be "*notify 1*"
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 39 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 37 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 75 KiB |
@@ -0,0 +1,23 @@
|
||||
.. include:: _notify_substitutions_n00x.repl
|
||||
|
||||
Notifications
|
||||
**************
|
||||
|
||||
ESPEasy has two basic Notification methods. It can send an email or briefly alert the user using a audio beep tone.
|
||||
|
||||
Feature Summary
|
||||
----------------
|
||||
- **Email :** |N001_shortinfo|
|
||||
- **Buzzer:** |N002_shortinfo|
|
||||
|
||||
.. _Notifications Plugins:
|
||||
|
||||
Notifications Plugins
|
||||
======================
|
||||
|
||||
.. csv-table::
|
||||
:header: "Name", "Status", "Notify Number"
|
||||
:widths: 10, 8, 5
|
||||
|
||||
":ref:`N001_page`","|N001_status|","N001"
|
||||
":ref:`N002_page`","|N002_status|","N002"
|
||||
@@ -0,0 +1,23 @@
|
||||
.. |N001_type| replace:: :cyan:`Notifications`
|
||||
.. |N001_name| replace:: :cyan:`Notifications Email (SMTP)`
|
||||
.. |N001_typename| replace:: :cyan:`Notifications - Email (SMTP)`
|
||||
.. |N001_porttype| replace:: `.`
|
||||
.. |N001_status| replace:: :green:`NORMAL` :yellow:`CLIMATE` :yellow:`COLLECTION` :yellow:`SONOFF` :yellow:`SHELLY`
|
||||
.. |N001_github| replace:: N001_Email.cpp
|
||||
.. _N001_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_N001_Email.cpp
|
||||
.. |N001_maintainer| replace:: `.`
|
||||
.. |N001_usedlibraries| replace:: `.`
|
||||
.. |N001_shortinfo| replace:: Send the user a message using SMTP email. Mulitple recipients are possible. IMPORTANT: Email server MUST allow a non-secure connection; The SSL/TLS SMTP protocol is not supported.
|
||||
.. |N001_page| replace:: N001
|
||||
|
||||
.. |N002_type| replace:: :cyan:`Notifications`
|
||||
.. |N002_name| replace:: :cyan:`Notifications Buzzer`
|
||||
.. |N002_typename| replace:: :cyan:`Notifications - Buzzer`
|
||||
.. |N002_porttype| replace:: `.`
|
||||
.. |N002_status| replace:: :green:`NORMAL` :yellow:`CLIMATE` :yellow:`COLLECTION` :yellow:`SONOFF` :yellow:`SHELLY`
|
||||
.. |N002_github| replace:: N002_Buzzer.cpp
|
||||
.. _N002_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_N002_Buzzer.cpp
|
||||
.. |N002_maintainer| replace:: `.`
|
||||
.. |N002_usedlibraries| replace:: `.`
|
||||
.. |N002_shortinfo| replace:: Alert the user with a brief 440Hz beep tone driven by a single GPIO pin. This audio feature requires a passive speaker/transducer and driver circuit.
|
||||
.. |N002_page| replace:: N002
|
||||
Reference in New Issue
Block a user