AS3935 Lightning sensor (#294)
* Added TX20/TX23 sensor documentation * Update tx20.rst * updated documentation to new structure for tx20 * added missing files * fixed missing newline * fixed/updated documentation * added as3935 sensor * Update as3935.rst * Update as3935.rst * Undo change * Shrink image Co-authored-by: Otto Winter <otto@otto-winter.com>
This commit is contained in:
parent
1c4f70631c
commit
2469943bb7
|
@ -0,0 +1,176 @@
|
|||
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 diestance 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** I2C 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
|
||||
pin: GPIO13
|
||||
# Example configuration for I2C (decide for one!)
|
||||
as3935_i2c:
|
||||
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):
|
||||
---------------------------------
|
||||
|
||||
- **pin** (**Required**, :ref:`config-pin`): The IRQ pin, wh ich 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:
|
||||
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
|
||||
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`
|
Binary file not shown.
After Width: | Height: | Size: 857 KiB |
Binary file not shown.
After Width: | Height: | Size: 16 KiB |
|
@ -93,6 +93,7 @@ Sensor Components
|
|||
AM2320, components/sensor/am2320, am2320.jpg
|
||||
APDS9960, components/sensor/apds9960, apds9960.jpg
|
||||
ATM90E32, components/sensor/atm90e32, atm90e32.jpg
|
||||
AS3935, components/sensor/as3935, as3935.jpg
|
||||
BH1750, components/sensor/bh1750, bh1750.jpg
|
||||
Binary Sensor Map, components/sensor/binary_sensor_map, binary_sensor_map.jpg
|
||||
BLE RSSI, components/sensor/ble_rssi, bluetooth.svg
|
||||
|
|
Loading…
Reference in New Issue