esphome-docs/components/sim800l.rst

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`