New component: Add documentation for bmp581 component (#2771)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

components/sensor/bmp581.rst

@@ -0,0 +1,138 @@
+BMP581 Temperature+Pressure Sensor
+===========================================
+
+.. seo::
+    :description: Instructions for setting up BMP581 temperature and pressure sensors with ESPHome
+    :image: bmp581.jpg
+    :keywords: BMP581
+
+The ``bmp581`` sensor platform allows you to use your BMP581 
+(`datasheet <https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bmp581-ds004.pdf>`__, `SparkFun <https://www.sparkfun.com/products/20170>`__) temperature and pressure sensors with ESPHome. The :ref:`I²C <i2c>` bus is
+required to be set up in your configuration for this sensor to work.
+
+.. figure:: images/bmp581.jpg
+    :align: center
+    :width: 50.0%
+
+    BMP581 Temperature and Pressure Sensor.
+    (Credit: `SparkFun <https://www.sparkfun.com/products/20170>`__, image cropped and compressed)
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    sensor:
+      - platform: bmp581
+        temperature:
+          name: "Indoor Temperature"
+        pressure:
+          name: "Indoor Pressure"
+
+Configuration variables:
+------------------------
+
+- **temperature** (*Optional*): The information for the temperature sensor.
+
+  - **oversampling** (*Optional*): The oversampling rate for the temperature sensor.
+    See :ref:`Oversampling Options <bmp581-oversampling>`.
+  - **iir_filter** (*Optional*): The Infinite Impulse Response Filter level for the temperature sensor.
+    See :ref:`Infinite Impulse Response Filter Options <bmp581-iir>`.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **pressure** (*Optional*): The information for the pressure sensor.
+
+  - **oversampling** (*Optional*): The oversampling rate for the pressure sensor.
+    See :ref:`Oversampling Options <bmp581-oversampling>`.
+  - **iir_filter** (*Optional*): The Infinite Impulse Response Filter level for the pressure sensor.
+    See :ref:`Infinite Impulse Response Filter Options <bmp581-iir>`.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **address** (*Optional*, int): Manually specify the I²C address of
+  the sensor. Defaults to ``0x46``. Another address can be ``0x47``.
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
+  sensor. Defaults to ``60s``.
+
+.. _bmp581-oversampling:
+
+Oversampling Options
+--------------------
+
+By default, the BMP581 sensor measures the pressure 16 times and temperature once when requesting a new value to reduce measurement noise. You can, however, configure this amount. Possible oversampling values:
+
+-  ``NONE`` (sensor is sampled once, default for temperature)
+-  ``2x``
+-  ``4x``
+-  ``8x``
+-  ``16x`` (default for pressure)
+-  ``32x``
+-  ``64x``
+-  ``128x``
+
+The datasheet (page 19) gives suggestions for oversampling combinations:
+
+.. list-table:: Oversampling Settings
+    :header-rows: 1 
+
+    * - Oversampling setting
+      - Pressure oversampling
+      - Temperature oversampling
+    * - Lowest power
+      - ``NONE``
+      - ``NONE``
+    * - 
+      - ``2x``
+      - ``NONE``
+    * - Standard resolution
+      - ``4x``
+      - ``NONE``
+    * -
+      - ``8x``
+      - ``NONE``
+    * - High resolution (default)
+      - ``16x``
+      - ``NONE``
+    * -
+      - ``32x``
+      - ``2x``
+    * -
+      - ``64x``
+      - ``4x``
+    * - Highest resolution
+      - ``128x``
+      - ``8x``
+
+.. note::
+
+    High oversampling rates increase power consumption and the time it takes for the sensor to measure temperature and pressure. For example, with no oversampling enabled, the measurement time is approximately 3 ms. The measurement time is approximately 107 ms if the temperature and pressure oversampling rates are ``128x``. The BMP581 component waits the minimum time necessary for the specfically configured oversampling rates before attempting to read a measurement. Consider using lower oversampling rates to reduce power consumption or to speed up measurements for small update intervals.
+
+.. _bmp581-iir:
+
+Infinite Impule Response Filter Options
+---------------------------------------
+
+The BMP581's Infinite Impulse Response filter reduces noise in measurement values due to ambient conditions, for example, a door slamming or a window opening. The BMP581 disables the IIR filter for the temperature and pressure sensors by default, but you may configure the amount of filtering for each sensor independently. Possible IIR filter values:
+
+- ``OFF`` (default)
+-  ``2x``
+-  ``4x``
+-  ``8x``
+-  ``16x``
+-  ``32x``
+-  ``64x``
+-  ``128x``
+
+.. warning::
+
+    The BMP581's deep standby mode is disabled when you enable an IIR filter, which increases power consumption. Consider using a mathematically equivalent ESPHome exponential moving average filter instead, especially if you configure a long update interval. See the :ref:`exponential moving average filter<sensor-filter-exponential_moving_average>` for implementation information.
+
+
+See Also
+--------
+
+- :ref:`sensor-filters`
+- :doc:`bme280`
+- :doc:`bmp280`
+- :doc:`bmp3xx`
+- :doc:`bme680`
+- :doc:`bmp085`
+- `BMP5 sensor API <https://github.com/boschsensortec/BMP5-Sensor-API>`__
+- :ghedit:`Edit`

index.rst

@@ -290,6 +290,7 @@ Environmental
     BMP085, components/sensor/bmp085, bmp180.jpg, Temperature & Pressure
     BMP280, components/sensor/bmp280, bmp280.jpg, Temperature & Pressure
     BMP388 and BMP390, components/sensor/bmp3xx, bmp388.jpg, Temperature & Pressure
+    BMP581, components/sensor/bmp581, bmp581.jpg, Temperature & Pressure
     b-parasite, components/sensor/b_parasite, b_parasite.jpg, Moisture & Temperature & Humidity & Light
     Dallas DS18B20, components/sensor/dallas, dallas.jpg, Temperature
     DHT, components/sensor/dht, dht.jpg, Temperature & Humidity