diff --git a/components/sim800l.rst b/components/sim800l.rst index 5cea41c1c..58b7f0a17 100644 --- a/components/sim800l.rst +++ b/components/sim800l.rst @@ -9,10 +9,11 @@ Sim800L Component Component/Hub ------------- -The ``SIM800L`` Component provides the ability to dial, 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``. +The ``SIM800L`` Component provides the ability to dial, answer calls, send/receive SMS text messages and +send/receive USSD codes. 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:: @@ -43,16 +44,6 @@ The required connection wires are ``+VCC``, ``GND``, ``RX`` and ``TX``. format: "Received '%s' from %s" args: [ 'message.c_str()', 'sender.c_str()' ] - sensor: - - platform: sim800l - rssi: - name: "Sim800L RSSI" - - binary_sensor: - - platform: sim800l - registered: - name: "Sim800L Registered" - logger: baud_rate: 0 # disable uart logger on esp 8266 @@ -62,10 +53,25 @@ Configuration variables: - **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 an SMS is received. See :ref:`sim800l-on_sms_received`. +- **on_incoming_call** (*Optional*, :ref:`Automation `): An action to be + performed when a call is received. See :ref:`sim800l-on_incoming_call`. +- **on_call_connected** (*Optional*, :ref:`Automation `): An action to be + performed when a call is connected, either because an outgoing call accepted is + accepted or an incoming call answered. +- **on_call_disconnected** (*Optional*, :ref:`Automation `): An action to be + performed when a call is disconnected. + Sensor ------ +.. code-block:: yaml + + sensor: + - platform: sim800l + rssi: + name: "Sim800L RSSI" + Configuration variables: - **rssi** (*Optional*): The informed Received signal strength indication (RSSI) in dBm. @@ -78,6 +84,13 @@ Configuration variables: Binary Sensor ------------- +.. code-block:: yaml + + binary_sensor: + - platform: sim800l + registered: + name: "Sim800L Registered" + Configuration variables: - **registered** (*Optional*): Indicates if the SIM800L has successfully registered in the cellular network. @@ -103,6 +116,42 @@ under the variables named ``message`` and ``sender`` respectively. id(sms_sender).publish_state(sender); id(sms_message).publish_state(message); +.. _sim800l-on_incoming_call: + +``on_incoming_call`` Trigger +---------------------------- + +This automation triggers every time the SIM800L sends a RING / Caller ID message, this message +is sent several times per call, presumably every time the phone "RINGs". The automation provides +a ``caller_id`` string parameter which received information. The phone call is neither accepted +or rejected. + +.. code-block:: yaml + + on_incoming_call: + - logger.log: + format: "Incoming call from '%s'" + args: ["caller_id.c_str()"] + - lambda: |- + id(caller_id_text_sensor).publish_state(caller_id); + - sim800l.disconnect + - homeassistant.event: + event: esphome.incoming_call_event + data: + payload: !lambda 'return id(caller_id_text_sensor).state;' + + +``on_ussd_received`` Trigger +---------------------------- + +With this configuration option you can write complex automations whenever the ussd code from network +has been received. + +.. code-block:: yaml + + on_ussd_received: + + .. _sim800l-send_sms_action: @@ -134,18 +183,11 @@ Configuration options: - **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"); .. _sim800l-dial_action: ``sim800l.dial`` Action ---------------------------- +----------------------- Dial to a phone recipient using this action in automations. @@ -161,13 +203,41 @@ Configuration options: - **recipient** (**Required**, string, :ref:`templatable `): The number to dial. - **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 `: +``sim800l.connect`` Action +-------------------------- - .. code-block:: cpp +Answers an incoming call. - id(sim800l1).dial("+15551234567"); +.. code-block:: yaml + + on_...: + then: + - sim800l.connect + + +``sim800l.disconnect`` Action +----------------------------- + +Disconnects a call, either dialed in or received. + +.. code-block:: yaml + + on_...: + then: + - sim800l.disconnect + + +``sim800l.send_ussd`` Action +---------------------------- + +Sends a ussd code to the network. + +.. code-block:: yaml + + on_...: + then: + - sim800l.send_ussd Getting started with Home Assistant @@ -180,28 +250,46 @@ on Home Assistant and will also setup a service so you can send messages and dia api: services: - - service: send_sms - variables: - recipient: string - message: string - then: - - sim800l.send_sms: - recipient: !lambda 'return recipient;' - message: !lambda 'return message;' - - service: dial - variables: - recipient: string - then: - - sim800l.dial: - recipient: !lambda 'return recipient;' + - service: send_sms + variables: + recipient: string + message: string + then: + - sim800l.send_sms: + recipient: !lambda 'return recipient;' + message: !lambda 'return message;' + - service: dial + variables: + recipient: string + then: + - sim800l.dial: + recipient: !lambda 'return recipient;' + - service: connect + then: + - sim800l.connect + - service: disconnect + then: + - sim800l.disconnect + - service: send_ussd + variables: + ussdCode: string + then: + - sim800l.send_ussd: + ussd: !lambda 'return ussdCode;' text_sensor: - - platform: template - id: sms_sender - name: "Sms Sender" - - platform: template - id: sms_message - name: "Sms Message" + - platform: template + id: sms_sender + name: "Sms Sender" + - platform: template + id: sms_message + name: "Sms Message" + - platform: template + id: caller_id_text_sensor + name: "Caller ID" + - platform: template + id: ussd_message + name: "Ussd Code" uart: baud_rate: 9600 @@ -210,9 +298,22 @@ on Home Assistant and will also setup a service so you can send messages and dia sim800l: on_sms_received: - - lambda: |- - id(sms_sender).publish_state(sender); - id(sms_message).publish_state(message); + - lambda: |- + id(sms_sender).publish_state(sender); + id(sms_message).publish_state(message); + on_incoming_call: + - lambda: |- + id(caller_id_text_sensor).publish_state(caller_id); + on_call_connected: + - logger.log: + format: Call connected + on_call_disconnected: + - logger.log: + format: Call disconnected + on_ussd_received: + - lambda: |- + id(ussd_message).publish_state(ussd); + Now your latest received SMS and sender number will be displayed by the text sensors. @@ -238,10 +339,10 @@ Relay management commands received from an authorized sender: sim800l: on_sms_received: - - lambda: |- - if ( (id(sms_sender).state == "+79991234567") && ( (id(sms_message).state == "relay_1_on") OR (id(sms_message).state == "Relay_1_on") ) ) { - id(relay_1).turn_on(); - } + - lambda: |- + if ( (id(sms_sender).state == "+79991234567") && ( (id(sms_message).state == "relay_1_on") OR (id(sms_message).state == "Relay_1_on") ) ) { + id(relay_1).turn_on(); + } switch: - platform: gpio id: relay_1