esphome-docs/components/sensor/as3935.rst

200 lines
8.8 KiB
ReStructuredText
Raw Normal View History

AMS AS3935 Franklin Lightning Sensor
====================================
.. seo::
:description: Instructions for setting up AS3935 lightning sensor
:image: images/as3935.jpg
:keywords: as3935
The **AS3935** sensor platform allows you to use your AS3935 sensor
(`AliExpress`_, `AMS_AS3935`_)
in order to get notified when a thunderstorm is getting close.
The AS3935 can detect the presence of lightning activity and provide an estimation
on the distance to the head of the storm. The chip issues a notification through an interrupt
pin.
Component/Hub
-------------
The AS3935 can be configured to use either the SPI **or** I²C protocol for data communication.
First choose which communication method you want to use for the sensor, set the SI pin for the appropriate
level and set up the ESPHome integration for the chosen communication method.
Module Pins
-----------
============ ===============================================================
2020-05-10 21:27:59 +02:00
Module Pin Description
============ ===============================================================
2020-05-10 21:27:59 +02:00
VCC/VDD Positive supply voltage
GND Ground
SCL I²C clock bus or SPI clock bus (according to SI setting)
MOSI I²C data bus or SPI data input bus (according to SI setting)
MISO SPI data output bus
CS Chip Select (active low)
SI Select Interface (GND → SPI or VDD → I²C)
IRQ Interrupt (out)
EN_V Voltage Regulator Enable
A0 I²C address selection LSB
A1 I²C address selection MSB
============ ===============================================================
.. figure:: images/as3935.jpg
:align: center
:width: 50.0%
AS3935 Lightning Sensor.
.. _AliExpress: https://de.aliexpress.com/af/as3935.html?SearchText=as3935
.. _AMS_AS3935: https://ams.com/as3935
Over SPI
--------
The ``as3935_spi`` sensor platform allows you to use your AS3935 sensor
(`AliExpress`_, `AMS_AS3935`_) in order to get notified when a thunderstorm is getting close.
.. code-block:: yaml
# Example configuration for SPI (decide for one!)
as3935_spi:
cs_pin: GPIO12
irq_pin: GPIO13
# Example lightning and energy sensor
sensor:
- platform: as3935
lightning_energy:
name: "Lightning Energy"
distance:
name: "Distance Storm"
binary_sensor:
- platform: as3935
name: "Storm Alert"
Configuration variables:
************************
- **cs_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The chip select pin.
- **irq_pin** (**Required**, :ref:`config-pin`): The IRQ pin, which indicates if a lightning strike has been detected.
- **indoor** (*Optional*, boolean): Indicates if the sensor is used indoor. Defaults to ``true``.
- **noise_level** (*Optional*, integer): Noise floor level is compared to known reference voltage.
If this level is exceeded the chip will issue an interrupt to the IRQ pin, broadcasting that it can not
operate properly due to noise (INT_NH). Defaults to ``2``.
- **spike_rejection** (*Optional*, integer): Helps to differentiate between false events and actual lightning.
Increasing this value increases robustness at the cost of sensitivity to distant events. Defaults to ``2``.
- **lightning_threshold** (*Optional*, integer): The number of lightnings that must appear in a 15-minute time
window before a lightning storm is detected.
15 minutes is the window of time before the number of detected lightning events is reset.
The number of lightning strikes can be set to 1,5,9, or 16. Defaults to ``1``.
- **mask_disturber** (*Optional*, boolean): This setting will return whether or not disturbers trigger
the IRQ Pin. Defaults to ``false``.
- **div_ratio** (*Optional*, integer): The antenna is designed to resonate at 500kHz and so can be tuned
with the following setting. The accuracy of the antenna must be within 3.5 percent of that value for
proper signal validation and distance estimation. Defaults to ``0``.
- **capacitance** (*Optional*, integer): This setting will add capacitance to the series RLC antenna on the product
to help tune its resonance. The datasheet specifies being within 3.5 percent of 500kHz to get optimal lightning
detection and distance sensing. It's possible to add up to 120pF in steps of 8pF to the antenna. Defaults to ``0``.
- **watchdog_threshold** (*Optional*, integer): Determines the threshold for events that trigger the IRQ pin.
Defaults to ``2``.
Over I²C
--------
The ``as3935_i2c`` sensor platform allows you to use your AS3935 sensor
(`AliExpress`_, `AMS_AS3935`_) in order to get notified when a thunderstorm is getting close.
.. code-block:: yaml
# Example configuration for I²C (decide for one!)
as3935_i2c:
irq_pin: GPIO12
# Example shared configuration
sensor:
- platform: as3935
lightning_energy:
name: "Lightning Energy"
distance:
name: "Distance Storm"
binary_sensor:
- platform: as3935
name: "Storm Alert"
Configuration variables:
************************
- **address** (*Optional*, int): Manually specify the I²C address of
the sensor. Defaults to ``0x03`` (``A0`` and ``A1`` pins pulled high).
The address is made up using the state of ``A0`` as bit 1 and the state of ``A1`` as bit 2, so a total of four addresses is possible.
- **irq_pin** (**Required**, :ref:`config-pin`): The IRQ pin, which indicates if a lightning strike has been detected.
- **indoor** (*Optional*, boolean): Indicates if the sensor is used indoor. Defaults to ``true``.
- **noise_level** (*Optional*, integer): Noise floor level is compared to known reference voltage.
If this level is exceeded the chip will issue an interrupt to the IRQ pin, broadcasting that it can not
operate properly due to noise (INT_NH). Defaults to ``2``.
- **spike_rejection** (*Optional*, integer): Helps to differentiate between false events and actual lightning.
Increasing this value increases robustness at the cost of sensitivity to distant events. Defaults to ``2``.
- **lightning_threshold** (*Optional*, integer): The number of lightnings that must appear in a 15-minute time
window before a lightning storm is detected.
15 minutes is the window of time before the number of detected lightning events is reset.
The number of lightning strikes can be set to 1,5,9, or 16. Defaults to ``1``.
- **mask_disturber** (*Optional*, boolean): This setting will return whether or not disturbers trigger
the IRQ Pin. Defaults to ``false``.
- **div_ratio** (*Optional*, integer): The antenna is designed to resonate at 500kHz and so can be tuned
with the following setting. The accuracy of the antenna must be within 3.5 percent of that value for
proper signal validation and distance estimation. Defaults to ``0``.
- **capacitance** (*Optional*, integer): This setting will add capacitance to the series RLC antenna on the product
to help tune its resonance. The datasheet specifies being within 3.5 percent of 500kHz to get optimal lightning
detection and distance sensing. It's possible to add up to 120pF in steps of 8pF to the antenna. Defaults to ``0``.
- **watchdog_threshold** (*Optional*, integer): Determines the threshold for events that trigger the IRQ pin.
Defaults to ``2``.
Sensor
------
A sensor platform to read lightning data
Configuration variables:
- **lightning_energy** (*Optional*): Lightning energy value. According to the datasheet this is only a pure value that doesn't have any physical meaning.
- **name** (**Required**, string): The name for the lightning energy sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **distance** (*Optional*): Distance in km to the front of the storm and not the distance to a lightning strike.
- **name** (**Required**, string): The name for the distance sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
Binary Sensor
-------------
Binary sensor that indicates if a lightning strike was detected.
Configuration variables:
- **name** (**Required**, string): The name of the binary sensor.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
See Also
--------
- :ref:`sensor-filters`
- :apiref:`as3935/as3935.h`
- `AliExpress <https://de.aliexpress.com/af/as3935.html?SearchText=as3935>`__
- `Data Sheet <https://www.embeddedadventures.com/datasheets/AS3935_Datasheet_EN_v2.pdf>`__
- `Little Arduino Projects <https://github.com/tardate/LittleArduinoProjects/tree/master/playground/AS3935>`__
- `AMS AS3935 <https://ams.com/as3935>`__
2020-05-10 21:27:59 +02:00
- `SparkFun Library <https://github.com/sparkfun/SparkFun_AS3935_Lightning_Detector_Arduino_Library>`__
- :ghedit:`Edit`