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

2019-09-01 11:24:35 +02:00 · 2019-09-01 11:24:35 +02:00 · c5ee042d56
parent 8d91d657dc a4a4495844
commit c5ee042d56
13 changed files with 298 additions and 2 deletions
--- a/components/binary_sensor/index.rst
+++ b/components/binary_sensor/index.rst
@ -77,6 +77,7 @@ of these entries matters!)
          - invert:
          - delayed_on: 100ms
          - delayed_off: 100ms
+          - delayed_on_off: 100ms
          - lambda: |-
              if (id(other_binary_sensor).state) {
                return x;
@ -95,6 +96,9 @@ Supported filters:
  an OFF state. If an ON value is received while waiting, the OFF action is discarded. Or in other words:
  Only send an OFF value if the binary sensor has stayed OFF for at least the specified time period.
  **Useful for debouncing push buttons**.
+- **delayed_on_off**: Only send an ON or OFF value if the binary sensor has stayed in the same state
+  for at least the specified time period.
+  **Useful for debouncing binary switches**.
 - **lambda**: Specify any :ref:`lambda <config-lambda>` for more complex filters. The input value from
  the binary sensor is ``x`` and you can return ``true`` for ON, ``false`` for OFF, and ``{}`` to stop
  the filter chain.
--- a/components/cover/time_based.rst
+++ b/components/cover/time_based.rst
@ -46,11 +46,22 @@ Configuration variables:
 - **close_duration** (**Required**, :ref:`config-time`): The amount of time it takes the cover
  to close from the fully-open state.
 - **stop_action** (**Required**, :ref:`Action <config-action>`): The action that should
-  be performed when the remote requests the cover to be closed or the cover has been opening/closing
-  for the given durations.
+  be performed to stop the cover when the remote requests the cover to be stopped or
+  when the cover has been opening/closing for the given durations.
+- **has_built_in_endstop** (*Optional*, boolean): Indicates that the cover has built in end stop
+  detectors. In this configuration the ``stop_action`` is not perfomed when the open or close
+  time is completed and if the cover is commanded to open or close the corresponding actions
+  will be performed without checking current state. Defaults to ``False``.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 - All other options from :ref:`Cover <config-cover>`.

+
+.. note::
+
+    The stop button on the UI is always enabled even when the cover is stopped and each press
+    on the button will cause the ``stop_action`` to be performed.
+
+
 See Also
 --------

--- a/components/sensor/images/scd30.jpg
+++ b/components/sensor/images/scd30.jpg
--- a/components/sensor/images/xiaomi_lywsd02-full.png
+++ b/components/sensor/images/xiaomi_lywsd02-full.png
--- a/components/sensor/images/xiaomi_lywsd02-ui.png
+++ b/components/sensor/images/xiaomi_lywsd02-ui.png
--- a/components/sensor/index.rst
+++ b/components/sensor/index.rst
@ -104,6 +104,10 @@ for platforms with multiple sensors)
          - 40.0 -> 45.0
          - 100.0 -> 102.5
      - filter_out: 42.0
+      - median:
+          window_size: 5
+          send_every: 5
+          send_first_at: 1
      - sliding_window_moving_average:
          window_size: 15
          send_every: 15
@ -200,6 +204,40 @@ Filter out specific values to be displayed. For example to filter out the value
      filters:
        - filter_out: 85.0

+``median``
+**********
+
+Calculate moving median over the data. This can be used to filter outliers from the received
+sensor data. A large window size will make the filter slow to react to input changes.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    - platform: wifi_signal
+      # ...
+      filters:
+        - median:
+            window_size: 7
+            send_every: 4
+            send_first_at: 3
+
+-  **median**: A `simple moving median
+   <https://en.wikipedia.org/wiki/Median_filter#Worked_1D_example>`__
+   over the last few values.
+
+   -  **window_size**: The number of values over which to calculate the median
+      when pushing out a value. This number should
+      be odd if you want an actual received value pushed out.
+      Defaults to ``5``.
+   -  **send_every**: How often a sensor value should be pushed out. For
+      example, in above configuration the median is calculated after every 4th
+      received sensor value, over the last 7 received values.
+      Defaults to ``5``.
+   -  **send_first_at**: By default, the very first raw value on boot is immediately
+      published. With this parameter you can specify when the very first value is to be sent.
+      Must be smaller than or equal to ``send_every``
+      Defaults to ``1``.
+
 ``sliding_window_moving_average`` / ``exponential_moving_average``
 ******************************************************************

--- a/components/sensor/mhz19.rst
+++ b/components/sensor/mhz19.rst
@ -37,6 +37,7 @@ TX/RX labels are from the perspective of the MH-Z19). Additionally, you need to
        temperature:
          name: "MH-Z19 Temperature"
        update_interval: 60s
+        automatic_baseline_calibration: false

 Configuration variables:
 ------------------------
@ -61,12 +62,85 @@ Configuration variables:
 - **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component <uart>` if you want
  to use multiple UART buses.

+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for actions.
+
+- **automatic_baseline_calibration** (*Optional*, boolean): MH-Z19 has automatic calibration procedure.
+  The automatic calibration cycle is every 24 hours after powered on.
+  Set this value to ``false`` to disable ABC on boot (it's better if you use sensor indoor).
+  Set this value to ``true`` to enable ABC on boot.
+  Doesn't send calibration command if not set (default sensor logic will be used).
+
 .. figure:: images/mhz19-pins.jpg
    :align: center
    :width: 80.0%

    Pins on the MH-Z19. Only the ones marked with a red circle need to be connected.

+.. _mhz19-calibrate_zero_action:
+
+``mhz19.calibrate_zero`` Action
+-------------------------------
+
+This :ref:`action <config-action>` executes zero point calibration command on the sensor with the given ID.
+
+If you want to execute zero point calibration, the MH-Z19 sensor must work in stable gas environment (400ppm)
+for over 20 minutes and you execute this function.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - mhz19.calibrate_zero: my_mhz19_id
+
+You can provide :ref:`service <api-services>` to call it from Home Assistant
+
+.. code-block:: yaml
+
+    api:
+      services:
+        - service: mhz19_calibrate_zero
+          then:
+            - mhz19.calibrate_zero: my_mhz19_id
+
+.. _mhz19-abc_enable_action:
+
+``mhz19.abc_enable`` Action
+---------------------------
+
+This :ref:`action <config-action>` enables automatic baseline calibration on the sensor with the given ID.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - mhz19.abc_enable: my_mhz19_id
+
+.. _mhz19-abc_disable_action:
+
+``mhz19.abc_disable`` Action
+----------------------------
+
+This :ref:`action <config-action>` disables automatic baseline calibration on the sensor with the given ID.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - mhz19.abc_disable: my_mhz19_id
+
+You can provide switch and control ABC from Home Assistant
+
+.. code-block:: yaml
+
+    switch:
+      - platform: template
+        name: "MH-Z19 ABC"
+        optimistic: true
+        on_turn_on:
+          mhz19.abc_enable: my_mhz19_id
+        on_turn_off:
+          mhz19.abc_disable: my_mhz19_id
+
 See Also
 --------

--- a/components/sensor/scd30.rst
+++ b/components/sensor/scd30.rst
@ -0,0 +1,73 @@
+SCD30 CO₂, Temperature and Relative Humidty Sensor
+==================================================
+
+.. seo::
+    :description: Instructions for setting up SCD30 CO₂ Temperature and Relative Humidty Sensor
+    :image: scd30.jpg
+
+The ``scd30`` sensor platform  allows you to use your Sensiron SCD30 CO₂  
+(`datasheet <https://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/0_Datasheets/CO2/Sensirion_CO2_Sensors_SCD30_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.
+
+.. figure:: images/scd30.jpg
+    :align: center
+    :width: 80.0%
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    sensor:
+      - platform: scd30
+        co2:
+          name: "Workshop CO2"
+          accuracy_decimals: 1
+        temperature:
+          name: "Workshop Temperature"
+          accuracy_decimals: 2
+        humidity:
+          name: "Workshop Humidity"
+          accuracy_decimals: 1
+        address: 0x61
+        update_interval: 5s
+        
+
+Configuration variables:
+------------------------
+
+- **co2** (**Required**): The information for the CO₂ sensor.
+
+  - **name** (**Required**, string): The name for the CO₂eq sensor.
+  - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **temperature** (**Required**): The information for the Temperature sensor.
+
+  - **name** (**Required**, string): The name for the temperature sensor.
+  - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+
+- **humidity** (**Required**): The information for the Humidity sensor.
+
+  - **name** (**Required**, string): The name for the humidity 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 ``0x61``.
+
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
+  sensor. Defaults to ``60s``.
+
+
+
+See Also
+--------
+
+- :ref:`sensor-filters`
+- :doc:`dht`
+- :doc:`dht12`
+- :doc:`hdc1080`
+- :doc:`htu21d`
+- :apiref:`scd30/scd30.h`
+- :ghedit:`Edit`
--- a/components/sensor/xiaomi_lywsd02.rst
+++ b/components/sensor/xiaomi_lywsd02.rst
@ -0,0 +1,93 @@
+Xiaomi LYWSD02 BLE Sensor
+=========================
+
+.. seo::
+    :description: Instructions for setting up Xiaomi LYWSD02 bluetooth-based temperature and humidity sensors in ESPHome.
+    :image: xiaomi_lywsd02.jpg
+    :keywords: Xiaomi, LYWSD02, BLE, Bluetooth
+
+The ``xiaomi_lywsd02`` sensor platform lets you track the output of Xiaomi LYWSD02 Bluetooth Low Energy
+devices using the :doc:`/components/esp32_ble_tracker`. This component will track the
+temperature, humidity of the LYWSD02 device every time the sensor
+sends out a BLE broadcast. Note that contrary to other implementations, ESPHome can track as many
+LYWSD02 devices at once as you want.
+
+.. figure:: images/xiaomi_lywsd02-full.png
+    :align: center
+    :width: 60.0%
+
+    Xiaomi LYWSD02 Temperature and Humidity Sensor over BLE.
+
+.. figure:: images/xiaomi_lywsd02-ui.png
+    :align: center
+    :width: 80.0%
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    esp32_ble_tracker:
+
+    sensor:
+      - platform: xiaomi_lywsd02
+        mac_address: 3F:5B:7D:82:58:4E
+        temperature:
+          name: "Xiaomi LYWSD02 Temperature"
+        humidity:
+          name: "Xiaomi LYWSD02 Humidity"
+
+Configuration variables:
+------------------------
+
+- **mac_address** (**Required**, MAC Address): The MAC address of the Xiaomi LYWSD02 device.
+- **temperature** (*Optional*): The information for the temperature sensor.
+
+  - **name** (**Required**, string): The name for the temperature sensor.
+  - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+- **humidity** (*Optional*): The information for the humidity sensor
+
+  - **name** (**Required**, string): The name for the humidity sensor.
+  - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+  - All other options from :ref:`Sensor <config-sensor>`.
+
+Setting Up Devices
+------------------
+
+To set up Xiaomi LYWSD02 devices you first need to find their MAC Address so that ESPHome can
+identify them. So first, create a simple configuration without any ``xiaomi_lywsd02`` entries like so:
+
+.. code-block:: yaml
+
+    esp32_ble_tracker:
+
+After uploading the ESP32 will immediately try to scan for BLE devices such as the Xiaomi LYWSD02. When
+it detects these sensors, it will automatically parse the BLE message print a message like this one:
+
+.. code::
+
+    Got Xiaomi LYWSD02 (3F:5B:7D:82:58:4E): Temperature: 26.9°C
+
+Note that it can sometimes take some time for the first BLE broadcast to be received. You can speed up
+the process by pressing the grey bluetooth button on the back of the device.
+
+Then just copy the address (``3F:5B:7D:82:58:4E``) into a new ``sensor.xiaomi_lywsd02`` platform entry like
+in the configuration example at the top.
+
+.. note::
+
+    The ESPHome Xiaomi integration listens passively to packets the xiaomi device sends by itself.
+    ESPHome therefore has no impact on the battery life of the device.
+
+See Also
+--------
+
+- :doc:`/components/esp32_ble_tracker`
+- :doc:`/components/sensor/xiaomi_mijia`
+- :doc:`/components/sensor/xiaomi_miflora`
+- :doc:`/components/sensor/index`
+- :apiref:`xiaomi_mijia/xiaomi_mijia.h`
+- `Xiaomi Mijia BLE protocol <https://github.com/mspider65/Xiaomi-Mijia-Bluetooth-Temperature-and-Humidity-Sensor>`__
+  by `@mspider65 <https://github.com/mspider65>`__
+- `OpenMQTTGateway <https://github.com/1technophile/OpenMQTTGateway>`__ by `@1technophile <https://github.com/1technophile>`__
+- :ghedit:`Edit`
--- a/guides/automations.rst
+++ b/guides/automations.rst
@ -364,6 +364,7 @@ All Actions
 - :ref:`display.page.show_* <display-pages>`
 - :ref:`uart.write <uart-write_action>`
 - :ref:`sim800l.send_sms <sim800l-send_sms_action>`
+- :ref:`mhz19.calibrate_zero <mhz19-calibrate_zero_action>` / :ref:`mhz19.abc_enable <mhz19-abc_enable_action>` / :ref:`mhz19.abc_disable <mhz19-abc_disable_action>`

 .. _config-condition:

--- a/images/scd30.jpg
+++ b/images/scd30.jpg
--- a/images/xiaomi_lywsd02.jpg
+++ b/images/xiaomi_lywsd02.jpg
--- a/index.rst
+++ b/index.rst
@ -130,6 +130,7 @@ Sensor Components
    Resistance, components/sensor/resistance, omega.svg
    Rotary Encoder, components/sensor/rotary_encoder, rotary_encoder.jpg
    SDS011 Sensor, components/sensor/sds011, sds011.jpg
+    SCD30, components/sensor/scd30, scd30.jpg
    SHT3X-D, components/sensor/sht3xd, sht3xd.jpg
    TCS34725, components/sensor/tcs34725, tcs34725.jpg
    Template Sensor, components/sensor/template, description.svg
@ -141,6 +142,7 @@ Sensor Components
    WiFi Signal Strength, components/sensor/wifi_signal, network-wifi.svg
    Xiaomi MiFlora, components/sensor/xiaomi_miflora, xiaomi_miflora.jpg
    Xiaomi MiJia, components/sensor/xiaomi_mijia, xiaomi_mijia.jpg
+    Xiaomi LYWSD02, components/sensor/xiaomi_lywsd02, xiaomi_lywsd02.jpg
    ZyAura, components/sensor/zyaura, zgm053.jpg
    Custom Sensor, components/sensor/custom, language-cpp.svg