diff --git a/components/images/sim800l-full.jpg b/components/images/sim800l-full.jpg new file mode 100755 index 000000000..1c6d016f2 Binary files /dev/null and b/components/images/sim800l-full.jpg differ diff --git a/components/sim800l.rst b/components/sim800l.rst new file mode 100644 index 000000000..879239dbb --- /dev/null +++ b/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 ` 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 `): 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 ` +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 `): The message recipient. + number. +- **message** (**Required**, string, :ref:`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 `: + + .. 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` diff --git a/guides/automations.rst b/guides/automations.rst index ed0317933..9ac3e87f4 100644 --- a/guides/automations.rst +++ b/guides/automations.rst @@ -326,6 +326,7 @@ All Triggers - :doc:`remote_receiver.on_* ` - :doc:`sun.on_sunrise ` / :doc:`sun.on_sunset ` - :ref:`switch.on_turn_on/off ` +- :ref:`sim800l.on_sms_received ` All Actions ----------- @@ -360,6 +361,7 @@ All Actions - :ref:`sensor.integration.reset ` - :ref:`display.page.show_* ` - :ref:`uart.write ` +- :ref:`sim800l.send_sms ` .. _config-condition: diff --git a/images/sim800l.jpg b/images/sim800l.jpg new file mode 100755 index 000000000..a27fd109c Binary files /dev/null and b/images/sim800l.jpg differ diff --git a/index.rst b/index.rst index 6ab882e49..dcb633ae6 100644 --- a/index.rst +++ b/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