Add SIM800L docs (#257)
* Add SIM800L docs * Update components/sim800l.rst Co-Authored-By: Otto Winter <otto@otto-winter.com> * Update components/sim800l.rst Co-Authored-By: Otto Winter <otto@otto-winter.com> * Update components/sim800l.rst Co-Authored-By: Otto Winter <otto@otto-winter.com> * review and adding getting started * Updates * Update components/sim800l.rst Co-Authored-By: Otto Winter <otto@otto-winter.com> * Update components/sim800l.rst Co-Authored-By: Otto Winter <otto@otto-winter.com>
This commit is contained in:
parent
56e505fc0d
commit
77e2ad4886
Binary file not shown.
After Width: | Height: | Size: 32 KiB |
|
@ -0,0 +1,165 @@
|
||||||
|
Sim800L Component
|
||||||
|
=================
|
||||||
|
|
||||||
|
.. seo::
|
||||||
|
:description: Instructions for setting up the SIM800L gsm module to send and receive SMS in ESPHome.
|
||||||
|
:image: sim800l.jpg
|
||||||
|
:keywords: SMS SIM800L GSM
|
||||||
|
|
||||||
|
The ``SIM800L`` Component provides the ability to send and receive SMS text messages. The device must be
|
||||||
|
connected via a :doc:`UART bus </components/uart>` supporting both receiving and transmitting line.
|
||||||
|
The uart bus must be configured at the same speed of the module which is by default 9600bps.
|
||||||
|
The required connection wires are ``+VCC``, ``GND``, ``RX`` and ``TX``.
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
If you are using the :doc:`logger` make sure you are not using the same pins for ``TX`` and ``RX`` or
|
||||||
|
otherwise disable the uart logging with the ``baud_rate: 0`` option.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This module requires a power supply between 3.8V and 4.2V that can handle current spikes up
|
||||||
|
to 2 amps, it will not work by powering from the same 3.3v power source of the ESP. However you can
|
||||||
|
connect ``TX`` and ``RX`` lines directly without any level shifter.
|
||||||
|
|
||||||
|
.. figure:: images/sim800l-full.jpg
|
||||||
|
:align: center
|
||||||
|
:width: 60.0%
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# Example configuration entry
|
||||||
|
uart:
|
||||||
|
baud_rate: 9600
|
||||||
|
tx_pin: TX
|
||||||
|
rx_pin: RX
|
||||||
|
|
||||||
|
sim800l:
|
||||||
|
on_sms_received:
|
||||||
|
- logger.log:
|
||||||
|
format: "Received '%s' from %s"
|
||||||
|
args: [ 'message.c_str()', 'sender.c_str()' ]
|
||||||
|
|
||||||
|
Configuration variables:
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the UART hub.
|
||||||
|
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
||||||
|
- **on_sms_received** (*Optional*, :ref:`Automation <automation>`): An action to be
|
||||||
|
performed when a sms is received. See :ref:`sim800l-on_sms_received`.
|
||||||
|
|
||||||
|
.. _sim800l-on_sms_received:
|
||||||
|
|
||||||
|
``on_sms_received`` Trigger
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
With this configuration option you can write complex automations whenever a sms message
|
||||||
|
is received. To use the message content, use a :ref:`lambda <config-lambda>`
|
||||||
|
template, the message content and the sender phone number are available inside that lambda
|
||||||
|
under the variables named ``message`` and ``sender`` respectively.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
on_sms_received:
|
||||||
|
- lambda: |-
|
||||||
|
id(sms_sender).publish_state(sender);
|
||||||
|
id(sms_message).publish_state(message);
|
||||||
|
|
||||||
|
|
||||||
|
.. _sim800l-send_sms_action:
|
||||||
|
|
||||||
|
``sim800l.send_sms`` Action
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
Send a SMS message to a phone recipient using this action in automations.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
on_...:
|
||||||
|
then:
|
||||||
|
- sim800l.send_sms:
|
||||||
|
recipient: '+15551234567'
|
||||||
|
message: Hello there
|
||||||
|
|
||||||
|
# Templated:
|
||||||
|
- sim800l.send_sms:
|
||||||
|
recipient: !lambda |-
|
||||||
|
if (id(reed_switch).state) return "+15551234567";
|
||||||
|
else return "15551234568";
|
||||||
|
message: !lambda |-
|
||||||
|
return id(reed_switch).state ? "Door is now OPEN" : "Hey door just CLOSED";
|
||||||
|
|
||||||
|
Configuration options:
|
||||||
|
|
||||||
|
- **recipient** (***Required**, string, :ref:`templatable <config-templatable>`): The message recipient.
|
||||||
|
number.
|
||||||
|
- **message** (**Required**, string, :ref:`templatable <config-templatable>`): The message content.
|
||||||
|
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the Sim800L if you have multiple components.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This action can also be written in :ref:`lambdas <config-lambda>`:
|
||||||
|
|
||||||
|
.. code-block:: cpp
|
||||||
|
|
||||||
|
id(sim800l1).send_sms("+15551234567", "The message content");
|
||||||
|
|
||||||
|
|
||||||
|
Getting started with Home Assistant
|
||||||
|
-----------------------------------
|
||||||
|
|
||||||
|
The following code will get you up and running with a configuration updating received messages
|
||||||
|
on Home Assistant and will also setup a service so you can send messages with your Sim800L.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
api:
|
||||||
|
services:
|
||||||
|
- service: send_sms
|
||||||
|
variables:
|
||||||
|
recipient: string
|
||||||
|
message: string
|
||||||
|
then:
|
||||||
|
- sim800l.send_sms:
|
||||||
|
recipient: !lambda 'return recipient;'
|
||||||
|
message: !lambda 'return message;'
|
||||||
|
|
||||||
|
text_sensor:
|
||||||
|
- platform: template
|
||||||
|
id: sms_sender
|
||||||
|
name: "Sms Sender"
|
||||||
|
- platform: template
|
||||||
|
id: sms_message
|
||||||
|
name: "Sms Message"
|
||||||
|
|
||||||
|
uart:
|
||||||
|
baud_rate: 9600
|
||||||
|
tx_pin: TX
|
||||||
|
rx_pin: RX
|
||||||
|
|
||||||
|
sim800l:
|
||||||
|
on_sms_received:
|
||||||
|
- lambda: |-
|
||||||
|
id(sms_sender).publish_state(sender);
|
||||||
|
id(sms_message).publish_state(message);
|
||||||
|
|
||||||
|
Now your latest received sms and sender number will be displayed by the text sensors.
|
||||||
|
|
||||||
|
To trigger the automation from Home Assistant you can invoke the service with this code:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
automation:
|
||||||
|
# ...
|
||||||
|
action:
|
||||||
|
- service: esphome.livingroom_send_sms
|
||||||
|
data:
|
||||||
|
recipient: "+15551234567"
|
||||||
|
message: "Hello World!"
|
||||||
|
|
||||||
|
See Also
|
||||||
|
--------
|
||||||
|
|
||||||
|
- :apiref:`sim800l/sim800l.h`
|
||||||
|
- :doc:`/components/uart`
|
||||||
|
- :ghedit:`Edit`
|
|
@ -326,6 +326,7 @@ All Triggers
|
||||||
- :doc:`remote_receiver.on_* </components/remote_receiver>`
|
- :doc:`remote_receiver.on_* </components/remote_receiver>`
|
||||||
- :doc:`sun.on_sunrise </components/sun>` / :doc:`sun.on_sunset </components/sun>`
|
- :doc:`sun.on_sunrise </components/sun>` / :doc:`sun.on_sunset </components/sun>`
|
||||||
- :ref:`switch.on_turn_on/off <switch-on_turn_on_off_trigger>`
|
- :ref:`switch.on_turn_on/off <switch-on_turn_on_off_trigger>`
|
||||||
|
- :ref:`sim800l.on_sms_received <sim800l-on_sms_received>`
|
||||||
|
|
||||||
All Actions
|
All Actions
|
||||||
-----------
|
-----------
|
||||||
|
@ -360,6 +361,7 @@ All Actions
|
||||||
- :ref:`sensor.integration.reset <sensor-integration-reset_action>`
|
- :ref:`sensor.integration.reset <sensor-integration-reset_action>`
|
||||||
- :ref:`display.page.show_* <display-pages>`
|
- :ref:`display.page.show_* <display-pages>`
|
||||||
- :ref:`uart.write <uart-write_action>`
|
- :ref:`uart.write <uart-write_action>`
|
||||||
|
- :ref:`sim800l.send_sms <sim800l-send_sms_action>`
|
||||||
|
|
||||||
.. _config-condition:
|
.. _config-condition:
|
||||||
|
|
||||||
|
|
Binary file not shown.
After Width: | Height: | Size: 23 KiB |
|
@ -295,6 +295,7 @@ Misc Components
|
||||||
|
|
||||||
PCF8574 I/O Expander, components/pcf8574, pcf8574.jpg
|
PCF8574 I/O Expander, components/pcf8574, pcf8574.jpg
|
||||||
MCP23017 I/O Expander, components/mcp23017, mcp23017.svg
|
MCP23017 I/O Expander, components/mcp23017, mcp23017.svg
|
||||||
|
SIM800L, components/sim800l, sim800l.jpg
|
||||||
Debug Component, components/debug, bug-report.svg
|
Debug Component, components/debug, bug-report.svg
|
||||||
|
|
||||||
Additional Custom Components
|
Additional Custom Components
|
||||||
|
|
Loading…
Reference in New Issue