Merge branch 'next' of https://github.com/esphome/esphome-docs into next

.gitignore

@@ -4,3 +4,6 @@ _build
 __pycache__/
 *.py[cod]
 *$py.class
+
+.idea
+venv

components/climate/index.rst

@@ -81,6 +81,11 @@ Configuration variables:
   higher target temperature of a climate device with a two-point target temperature.
 - **away** (*Optional*, boolean, :ref:`templatable <config-templatable>`): Set the away mode
   of the climate device.
+- **fan_mode** (*Optional*, boolean, :ref:`templatable <config-templatable>`): Set the fan mode
+  of the climate device. One of ``ON``, ``OFF``, ``AUTO``, ``LOW``, ``MEDIUM``, ``HIGH``, ``MIDDLE``,
+  ``FOCUS``, ``DIFFUSE``.
+- **swing_mode** (*Optional*, boolean, :ref:`templatable <config-templatable>`): Set the swing mode
+  of the climate device. One of ``OFF``, ``BOTH``, ``VERTICAL``, ``HORIZONTAL``.
 
 .. _climate-lambda_calls:
 
@@ -106,6 +111,10 @@ advanced stuff.
       id(my_climate).target_temperature_high
       // Away mode, type: bool
       id(my_climate).away
+      // Fan mode, type: FanMode (enum)
+      id(my_climate).fan_mode
+      // Swing mode, type: SwingMode (enum)
+      id(my_climate).swing_mode
 
 - ``.make_call``: Control the climate device
 

components/display/waveshare_epaper.rst

@@ -75,6 +75,7 @@ Configuration variables:
   - ``2.13in-ttgo`` (T5_V2.3 tested)
   - ``2.70in`` (not tested)
   - ``2.90in``
+  - ``2.90in-b`` (B/W rendering only)
   - ``4.20in``
   - ``7.50in``
 

components/sensor/hmc5883l.rst

@@ -1,3 +1,5 @@
+.. _hmc5883l:
+
 HMC5883L Magnetometer
 =====================
 
@@ -8,9 +10,14 @@ HMC5883L Magnetometer
 
 The ``hmc5883l`` allows you to use your HMC5883L triple-axis magnetometers
 (`datasheet <https://cdn-shop.adafruit.com/datasheets/HMC5883L_3-Axis_Digital_Compass_IC.pdf>`__,
-`Adafruit`_) with
+`Adafruit`_) with ESPHome. The :ref:`I²C Bus <i2c>` is required to be set up in your configuration
-ESPHome. The :ref:`I²C Bus <i2c>` is
+for this sensor to work.
-required to be set up in your configuration for this sensor to work.
+
+.. figure:: ../../images/hmc5883l.jpg
+    :align: center
+    :width: 30.0%
+
+    HMC5883L Magnetometer.
 
 .. _Adafruit: https://www.adafruit.com/product/1746
 
@@ -28,13 +35,14 @@ required to be set up in your configuration for this sensor to work.
           name: "HMC5883L Field Strength Z"
         heading:
           name: "HMC5883L Heading"
+        oversampling: 1x
         range: 130uT
         update_interval: 60s
 
 Configuration variables:
 ------------------------
 
-- **address** (*Optional*, int): Manually specify the i^2c address of the sensor. Defaults to ``0x1E``.
+- **address** (*Optional*, int): Manually specify the  I²c address of the sensor. Defaults to ``0x1E``.
 - **field_strength_x** (*Optional*): The field strength in microtesla along the X-Axis. All options from
   :ref:`Sensor <config-sensor>`.
 - **field_strength_y** (*Optional*): The field strength in microtesla along the Y-Axis. All options from
@@ -43,10 +51,37 @@ Configuration variables:
   :ref:`Sensor <config-sensor>`.
 - **heading** (*Optional*): The heading of the sensor in degrees. All options from
   :ref:`Sensor <config-sensor>`.
+- **oversampling** (*Optional*): The oversampling parameter for the sensor.
+- **range** (*Optional*): The range parameter for the sensor.
 - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
-
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 
+Oversampling Options
+--------------------
+
+By default, the HMC5883L sensor measures each value 1 times when requesting a new value. You can, however,
+configure this amount. The result is the sensor will take the adverage of the x samples. Possible oversampling values:
+
+-  ``1x`` (default)
+-  ``2x``
+-  ``4x``
+-  ``8x``
+
+Range Options
+-------------
+
+By default, the HMC5883L sensor measurement range is 130uT. You can, however,
+configure this amount. Possible values:
+
+-  ``88uT``
+-  ``130uT`` (default)
+-  ``190uT``
+-  ``250uT``
+-  ``400uT``
+-  ``470uT``
+-  ``560uT``
+-  ``810uT``
+
 See Also
 --------
 

components/sensor/qmc5883l.rst

@@ -0,0 +1,83 @@
+QMC5883L Magnetometer
+=====================
+
+.. seo::
+    :description: Instructions for setting up QMC5883L IMU compass sensors.
+    :image: qmc5883l.jpg
+    :keywords: QMC5883L
+
+The ``qmc5883l`` allows you to use your QMC5883L triple-axis magnetometers
+(`datasheet <http://wiki.sunfounder.cc/images/7/72/QMC5883L-Datasheet-1.0.pdf>`__) with
+ESPHome. This sensor is very simular to the :ref:`HMC5883L <hmc5883l>` sensor and is oftern found
+as a knock off replacement. The QMC5883L sensor preforms on par to the HMC5883L sensor,
+though the congiuration differs. The :ref:`I²C Bus <i2c>` is required to be set up in your
+configuration for this sensor to work.
+
+.. figure:: ../../images/qmc5883l.jpg
+    :align: center
+    :width: 30.0%
+
+    QMC5883L Magnetometer.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    sensor:
+      - platform: qmc5883l
+        address: 0x0D
+        field_strength_x:
+          name: "QMC5883L Field Strength X"
+        field_strength_y:
+          name: "QMC5883L Field Strength Y"
+        field_strength_z:
+          name: "QMC5883L Field Strength Z"
+        heading:
+          name: "QMC5883L Heading"
+        range: 200uT
+        oversampling: 512x
+        update_interval: 60s
+
+Configuration variables:
+------------------------
+
+- **address** (*Optional*, int): Manually specify the  I²c address of the sensor. Defaults to ``0x1E``.
+- **field_strength_x** (*Optional*): The field strength in microtesla along the X-Axis. All options from
+  :ref:`Sensor <config-sensor>`.
+- **field_strength_y** (*Optional*): The field strength in microtesla along the Y-Axis. All options from
+  :ref:`Sensor <config-sensor>`.
+- **field_strength_z** (*Optional*): The field strength in microtesla along the Z-Axis. All options from
+  :ref:`Sensor <config-sensor>`.
+- **heading** (*Optional*): The heading of the sensor in degrees. All options from
+  :ref:`Sensor <config-sensor>`.
+- **range** (*Optional*): The range parameter for the sensor.
+- **oversampling** (*Optional*): The oversampling parameter for the sensor.
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+
+Range Options
+-------------
+
+By default, the QMC5883L sensor measurement range is 200µT. You can, however,
+configure this amount. Possible values:
+
+-  ``200µT`` (default)
+-  ``800µT``
+
+Oversampling Options
+--------------------
+
+By default, the QMC5883L sensor measures each value 512 times when requesting a new value. You can, however,
+configure this amount. The result is the sensor will take the adverage of the x samples. Possible sampling values:
+
+-  ``512x`` (default)
+-  ``256x``
+-  ``128x``
+-  ``64x``
+
+See Also
+--------
+
+- :ref:`sensor-filters`
+- :doc:`template`
+- :apiref:`qmc5883l/qmc5883l.h`
+- :ghedit:`Edit`

components/sensor/sps30.rst

@@ -0,0 +1,145 @@
+SPS30 Particulate Matter Sensor
+===============================
+
+.. seo::
+    :description: Instructions for setting up SPS30 PM1.0, PM2.5, PM4, PM10 Particulate Matter sensors
+    :image: sps30.jpg
+
+The ``sps30`` sensor platform allows you to use your Sensiron SPS30
+(`datasheet <https://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/0_Datasheets/Particulate_Matter/Sensirion_PM_Sensors_SPS30_Datasheet.pdf>`__) sensors with ESPHome.
+The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work.
+This sensor supports both UART and I²C communication. However, at the moment only I²C communication is implemented.
+
+.. _Sparkfun: https://www.sparkfun.com/products/15103
+
+.. figure:: images/sensirion-pm.png
+    :align: center
+    :width: 50.0%
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    sensor:
+      - platform: sps30
+        pm_1_0:
+          name: "Workshop PM <1µm Weight concentration"
+          id: "workshop_PM_1_0"
+        pm_2_5:
+          name: "Workshop PM <2.5µm Weight concentration"
+          id: "workshop_PM_2_5"
+        pm_4_0:
+          name: "Workshop PM <4µm Weight concentration"
+          id: "workshop_PM_4_0"
+        pm_10_0:
+          name: "Workshop PM <10µm Weight concentration"
+          id: "workshop_PM_10_0"
+        pmc_0_5:
+          name: "Workshop PM <0.5µm Number concentration"
+          id: "workshop_PMC_0_5"
+        pmc_1_0:
+          name: "Workshop PM <1µm Number concentration"
+          id: "workshop_PMC_1_0"
+        pmc_2_5:
+          name: "Workshop PM <2.5µm Number concentration"
+          id: "workshop_PMC_2_5"
+        pmc_4_0:
+          name: "Workshop PM <4µm Number concentration"
+          id: "workshop_PMC_4_0"
+        pmc_10_0:
+          name: "Workshop PM <10µm Number concentration"
+          id: "workshop_PMC_10_0"
+        address: 0x69
+        update_interval: 10s
+
+
+Configuration variables:
+------------------------
+
+- **pm_1_0** (*Optional*): The information for the **Weight Concentration** sensor for fine particles up to 1μm. Readings in µg/m³.
+
+  - **name** (**Required**, string): The name for this sensor.
+  - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **pm_2_5** (*Optional*): The information for the **Weight Concentration** sensor for fine particles up to 2.5μm. Readings in µg/m³.
+
+  - **name** (**Required**, string): The name for this sensor.
+  - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **pm_4_0** (*Optional*): The information for the **Weight Concentration** sensor for coarse particles up to 4μm. Readings in µg/m³.
+
+  - **name** (**Required**, string): The name for this sensor.
+  - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **pm_10_0** (*Optional*): The information for the **Weight Concentration** sensor for coarse particles up to 10μm. Readings in µg/m³.
+
+  - **name** (**Required**, string): The name for this sensor.
+  - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **pmc_0_5** (*Optional*): The information for the **Number Concentration** sensor for ultrafine particles up to 0.5μm. Readings in particles/m³.
+
+  - **name** (**Required**, string): The name for this sensor.
+  - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **pmc_1_0** (*Optional*): The information for the **Number Concentration** sensor for fine particles up to 1μm. Readings in particles/m³.
+
+  - **name** (**Required**, string): The name for this sensor.
+  - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **pmc_2_5** (*Optional*): The information for the **Number Concentration** sensor for fine particles up to 2.5μm. Readings in particles/m³.
+
+  - **name** (**Required**, string): The name for this sensor.
+  - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **pmc_4_0** (*Optional*): The information for the **Number Concentration** sensor for coarse particles up to 4μm. Readings in particles/m³.
+
+  - **name** (**Required**, string): The name for this sensor.
+  - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **pmc_10_0** (*Optional*): The information for the **Number Concentration** sensor for coarse particles up to 10μm. Readings in particles/m³.
+
+  - **name** (**Required**, string): The name for this sensor.
+  - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **address** (*Optional*, int): Manually specify the i^2c address of the sensor.
+  Defaults to ``0x69``.
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
+  sensor. Defaults to ``60s``.
+
+Wiring:
+-------
+
+The sensor has a 5 pin JST ZHR type connector, with a 1.5mm pitch. (`Matching connector housing <https://octopart.com/zhr-5-jst-279203>`__, `datasheet <http://www.farnell.com/datasheets/1393424.pdf>`__)
+To force the force the sensor into I²C mode, the SEL pin (Interface Select pin no.5) should be shorted to ground (pin no.4)
+
+.. figure:: images/sps30-wiring.png
+    :align: center
+    :width: 50.0%
+
+For better stability, the SDA and SCL lines require suitable pull-up resistors.
+
+Automatic Cleaning:
+-------------------
+
+The SPS30 sensor has an automatic fan-cleaning which will accelerate the built-in fan to maximum speed for 10 seconds in order to blow out the dust accumulated inside the fan.
+The default automatic-cleaning interval is 168 hours (1 week) of uninterrupted use. Switching off the sensor resets this time counter.
+Disabling of automatic-cleaning or setting a manual interval is not supported at the moment.
+
+See Also
+--------
+
+- :ref:`sensor-filters`
+- :doc:`sds011`
+- :doc:`pmsx003`
+- :doc:`ccs811`
+- :doc:`sgp30`
+- :apiref:`sps30/sps30.h`
+- :ghedit:`Edit`

components/tm1651.rst

@@ -0,0 +1,101 @@
+TM1651 Battery Display
+======================
+
+.. seo::
+    :description: Instructions for setting up TM1651 Battery Display.
+    :image: tm1651_battery_display.jpg
+
+.. _tm1651:
+
+Battery Display
+---------------
+
+The ``tm1651`` display platform allows you to use battery display units based on TM1651 chip, like
+`this one <https://aliexpress.com/item/32811491559.html>`__
+with ESPHome. Currently integration supports level and brightness setting. All updates can be made via lambda expressions.
+
+.. figure:: images/tm1651-battery-display.jpg
+    :align: center
+    :width: 70.0%
+
+.. code-block:: yaml
+
+    display:
+      - platform: tm1651
+        id: tm1651_battery
+        clk_pin: D6
+        dio_pin: D5
+
+Configuration variables:
+************************
+
+- **clk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): CLK pin
+- **dio_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): DIO pin
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+
+.. _tm1651-set_level_action:
+
+``tm1651.set_level`` Action
+---------------------------
+
+This :ref:`Action <config-action>` changes the level of the battery display at runtime.
+
+.. code-block:: yaml
+
+    on_...:
+      - tm1651.set_level:
+          id: tm1651_battery
+          level: 50
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the TM1651.
+- **level** (**Required**, :ref:`templatable <config-templatable>`, int): Level from 9 to 100
+
+.. _tm1651-set_brightness_action:
+
+``tm1651.set_brightness`` Action
+--------------------------------
+
+This :ref:`Action <config-action>` allows you to manually change the brightness of the battery display at runtime.
+
+.. code-block:: yaml
+
+    on_...:
+      - tm1651.set_brightness:
+          id: tm1651_battery
+          brightness: 1
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the TM1651.
+- **brightness** (**Required**, :ref:`templatable <config-templatable>`, int): There is three levels of brightness
+  (``1``, ``2`` or ``3``) from lowest to highest brightness.
+
+Advanced Configuration
+----------------------
+
+You also can control this component with lambda expressions
+
+.. code-block:: yaml
+
+    api:
+      services:
+        - service: battery_level
+          variables:
+            level: int
+          then:
+            - lambda: |-
+                id(tm1651_battery).set_level(level);
+        - service: battery_brightness
+          variables:
+            brightness: int
+          then:
+            - lambda: |-
+                id(tm1651_battery).set_brightness(brightness);
+
+See Also
+--------
+
+- :doc:`index`
+- :ghedit:`Edit`

index.rst

@@ -114,6 +114,7 @@ Sensor Components
     HDC1080, components/sensor/hdc1080, hdc1080.jpg
     HLW8012, components/sensor/hlw8012, hlw8012.svg
     HMC5883L, components/sensor/hmc5883l, hmc5883l.jpg
+    QMC5883L, components/sensor/qmc5883l, qmc5883l.jpg
     Home Assistant, components/sensor/homeassistant, home-assistant.svg
     HX711, components/sensor/hx711, hx711.jpg
     INA219, components/sensor/ina219, ina219.jpg
@@ -143,6 +144,7 @@ Sensor Components
     SCD30, components/sensor/scd30, scd30.jpg
     SHTCx, components/sensor/shtcx, shtc3.jpg
     SHT3X-D, components/sensor/sht3xd, sht3xd.jpg
+    SPS30, components/sensor/sps30, sps30.jpg
     STS3X, components/sensor/sts3x, sts3x.jpg
     SGP30, components/sensor/sgp30, sgp30.jpg
     TCS34725, components/sensor/tcs34725, tcs34725.jpg
@@ -326,6 +328,7 @@ Misc Components
     DFPlayer, components/dfplayer, dfplayer.svg
     Captive Portal, components/captive_portal, wifi-strength-alert-outline.svg
     Debug Component, components/debug, bug-report.svg
+    TM1651 Battery Display, components/tm1651, tm1651_battery_display.jpg
 
 Additional Custom Components
 ----------------------------