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>

components/sim800l.rst

@@ -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`

guides/automations.rst

@@ -326,6 +326,7 @@ All Triggers
 - :doc:`remote_receiver.on_* </components/remote_receiver>`
 - :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:`sim800l.on_sms_received <sim800l-on_sms_received>`
 
 All Actions
 -----------
@@ -360,6 +361,7 @@ All Actions
 - :ref:`sensor.integration.reset <sensor-integration-reset_action>`
 - :ref:`display.page.show_* <display-pages>`
 - :ref:`uart.write <uart-write_action>`
+- :ref:`sim800l.send_sms <sim800l-send_sms_action>`
 
 .. _config-condition:
 

index.rst

@@ -295,6 +295,7 @@ Misc Components
 
     PCF8574 I/O Expander, components/pcf8574, pcf8574.jpg
     MCP23017 I/O Expander, components/mcp23017, mcp23017.svg
+    SIM800L, components/sim800l, sim800l.jpg
     Debug Component, components/debug, bug-report.svg
 
 Additional Custom Components