177 lines
7.0 KiB
ReStructuredText
177 lines
7.0 KiB
ReStructuredText
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.
|
|
|
|
The AS3935 can be configured to use either the SPI **or** I^2C 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
|
|
-----------
|
|
|
|
============ ===============================================================
|
|
Module Pin Description
|
|
============ ===============================================================
|
|
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
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration for SPI (decide for one!)
|
|
as3935_spi:
|
|
cs_pin: GPIO12
|
|
irq_pin: GPIO13
|
|
# Example configuration for I2C (decide for one!)
|
|
as3935_i2c:
|
|
irq_pin: GPIO12
|
|
|
|
# Example configuration for creating sensors
|
|
sensor:
|
|
- platform: as3935
|
|
lightning_energy:
|
|
name: "Lightning Energy"
|
|
distance:
|
|
name: "Distance Storm"
|
|
binary_sensor:
|
|
- platform: as3935
|
|
name: "Storm Alert"
|
|
|
|
|
|
Configuration variables (shared):
|
|
---------------------------------
|
|
|
|
- **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 real 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 entries:
|
|
|
|
- **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** (*Optional*): Binary sensor that indicates if a lightning strike was detected.
|
|
|
|
- **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>`.
|
|
|
|
Configuration variables (I^2C):
|
|
-------------------------------
|
|
|
|
Use this if you want to use your AS3935 in I^2C mode.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration for I2C (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"
|
|
|
|
- **address** (*Optional*, int): Manually specify the I^2C address of
|
|
the sensor. Defaults to ``0x03`` (``A0` and ``A1`` pins pulled low).
|
|
Another address can be ``0x02``.
|
|
|
|
Configuration variables (SPI):
|
|
------------------------------
|
|
|
|
Use this if you want to use your AS3935 in SPI mode.
|
|
|
|
.. 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"
|
|
|
|
- **cs_pin** (*Required*, :ref:`Pin Schema <config-pin_schema>`): The chip select pin.
|
|
|
|
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>`__
|
|
- `SparkFun Library <https://github.com/sparkfun/SparkFun_AS3935_Lightning_Detector_Arduino_Library>`__
|
|
- :ghedit:`Edit`
|