Upstream
/
esphome-docs
mirror of https://github.com/esphome/esphome-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Added docs for new SIM800L features (#2284) 

Co-authored-by: Guillermo Ruffino <glm.net@gmail.com>
This commit is contained in:
Matus Ivanecky 2022-09-14 21:43:13 +02:00 committed by Jesse Hills
parent 5a9e1eae2c
commit 5e6dabdaa1
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A
1 changed files with 154 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

207
components/sim800l.rst
View File

@ -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 </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``.
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 </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::
@ -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
@ -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