diff --git a/components/sensor/as3935.rst b/components/sensor/as3935.rst new file mode 100644 index 000000000..e40850d65 --- /dev/null +++ b/components/sensor/as3935.rst @@ -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 `. +- **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 `. +- **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 `. + +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 `): The chip select pin. + +See Also +-------- + +- :ref:`sensor-filters` +- :apiref:`as3935/as3935.h` +- `AliExpress `__ +- `Data Sheet `__ +- `Little Arduino Projects `__ +- `AMS AS3935 `__ +- `Sparkfun Library `__ +- :ghedit:`Edit` diff --git a/components/sensor/images/as3935.jpg b/components/sensor/images/as3935.jpg new file mode 100644 index 000000000..ca24c1900 Binary files /dev/null and b/components/sensor/images/as3935.jpg differ diff --git a/images/as3935.jpg b/images/as3935.jpg new file mode 100644 index 000000000..d987a8613 Binary files /dev/null and b/images/as3935.jpg differ diff --git a/index.rst b/index.rst index 50ddc424b..1edff94b0 100644 --- a/index.rst +++ b/index.rst @@ -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