Added docs for new SIM800L features (#2284)

Co-authored-by: Guillermo Ruffino <glm.net@gmail.com>

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
+The ``SIM800L`` Component provides the ability to dial, answer calls, send/receive SMS text messages and
-connected via a :doc:`UART bus </components/uart>` supporting both receiving and transmitting line.
+send/receive USSD codes. The device must be connected via a :doc:`UART bus </components/uart>`
-The UART bus must be configured at the same speed of the module which is by default 9600bps.
+supporting both receiving and transmitting line. The UART bus must be configured at the same speed
-The required connection wires are ``+VCC``, ``GND``, ``RX`` and ``TX``.
+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 <automation>`): An action to be
   performed when an SMS is received. See :ref:`sim800l-on_sms_received`.
+- **on_incoming_call** (*Optional*, :ref:`Automation <automation>`): An action to be
+  performed when a call is received. See :ref:`sim800l-on_incoming_call`.
+- **on_call_connected** (*Optional*, :ref:`Automation <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 <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 <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");
 
 .. _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 <config-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 <config-lambda>`:
+``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
@@ -194,6 +264,18 @@ on Home Assistant and will also setup a service so you can send messages and dia
           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
@@ -202,6 +284,12 @@ on Home Assistant and will also setup a service so you can send messages and dia
       - 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
@@ -213,6 +301,19 @@ on Home Assistant and will also setup a service so you can send messages and dia
         - 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.