Add documentation for VL53L1X

Author: ccutrer

Diff for: components/index.rst

@@ -291,6 +291,7 @@ Distance
     TOF10120, components/sensor/tof10120, tof10120.jpg, IR optical distance
     Ultrasonic Sensor, components/sensor/ultrasonic, ultrasonic.jpg, Acoustic distance
     VL53L0x, components/sensor/vl53l0x, vl53l0x.jpg, IR optical distance
+    VL53L1x, components/sensor/vl53l1x, vl53l1x.jpg, IR optical distance
     Zio Ultrasonic Sensor, components/sensor/zio_ultrasonic, zio_ultrasonic.jpg, Acoustic distance
 
 Electricity

Diff for: components/sensor/images/vl53l1x.jpg

@@ -104,6 +104,7 @@ See Also
 --------
 
 - :ref:`sensor-filters`
+- :doc:`vl53l1x`
 - :apiref:`vl53l0x/vl53l0x_sensor.h`
 - `vl53l0x-arduino library <https://github.com/pololu/vl53l0x-arduino/>`__ by `Pololu <https://github.com/pololu>`__
 - :ghedit:`Edit`

Diff for: components/sensor/vl53l0x.rst

@@ -0,0 +1,96 @@
+VL53L1X Time Of Flight Distance Sensor
+======================================
+
+.. seo::
+    :description: Instructions for setting up VL53L1X distance sensors in ESPHome.
+    :image: vl53l1x.jpg
+    :keywords: VL53L1X
+
+The ``vl53l1x`` sensor platform allows you to use VL53L1X optical time of flight
+(`datasheet <https://www.st.com/resource/en/datasheet/vl53l1x.pdf>`__,
+`ST <https://www.st.com/en/imaging-and-photonics-solutions/vl53l1x.html>`__) with ESPHome
+to measure distances. The sensor works optically by emitting short infrared pulses
+and measuring the time it takes the light to be reflected back
+
+The sensor can measure distances up to 2 meters, though that figure depends significantly
+on several conditions like surface reflectance, field of view, temperature etc. In general
+you can expect surfaces up to 73cm to work, after that you need to make sure the surface is reflecting
+well enough (see also section 3.5 of datasheet).
+
+.. figure:: images/vl53l1x.png
+    :align: center
+    :width: 100.0%
+
+The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this sensor to work.
+
+- ``VCC`` connects to 3V3 (``3V3`` will output 3.3V), or directly connect ``VCC`` to 3.3V
+- ``GND`` connects to ground
+- ``SCL`` connects I2C SCL (clock)
+- ``SDA`` connects I2C SDA (data)
+- ``GPIO1`` is not used by ESPHome
+- ``XSHUT`` connects to free GPIO pin. Enable/disable device. This is optional if there is only one
+  VL53L1X sensor on the I²C bus and the default ``0x29`` address is used. Otherwise this is required.
+
+.. code-block:: yaml
+
+    # Simple configuration entry example
+    sensor:
+      - platform: vl53l1x
+        name: "VL53L1x Distance"
+        address: 0x29
+        update_interval: 60s
+        distance_mode: long
+
+Configuration variables:
+------------------------
+
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
+  sensor. Defaults to ``60s``.
+- **distance_mode** (*Optional*): Set the distance mode. Long distance mode allows the longest possible ranging
+  distance of 4 m to be reached. However, this maximum ranging distance is impacted by ambient light.
+  Short distance mode is more immune to ambient light, but its maximum ranging distance is typically limited to
+  1.3m. One of ``short``, ``medium``, or ``long``. Defaults to ``long``.
+- **address** (*Optional*, int): Manually specify the i2c address of the sensor. Defaults to ``0x29``.
+  If an address other the ``0x29`` is specified, the sensor will be dynamically re-addressed at startup.
+  A dynamic re-address of sensor requires the ``enable_pin`` configuration variable to be assigned.
+  If more then one VL53L1X sensor is used on the same i2c bus, a unique address must be specified per sensor.
+- **enable_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin connected to XSHUT
+  on vl53l1x to enable/disable sensor. **Required** if not using address ``0x29`` which is the cause if you
+  have multiple VL53L1X on the same i2c bus. In this case you have to assign a different pin to each VL53L1X.
+- **timeout** (*Optional*, :ref:`config-time`): Sensor setup timeout. Default to ``10ms``.
+- All other options from :ref:`Sensor <config-sensor>`.
+
+
+.. code-block:: yaml
+
+    # Muliple VL53L1X sensors on same i2c bus
+    # Example configuration entry
+    sensor:
+      - platform: vl53l1x
+        name: "distance1"
+        id: distance1
+        address: 0x41
+        enable_pin: GPIOXX
+        timeout: 200us
+        update_interval: 500ms
+        unit_of_measurement: "m"
+
+      - platform: vl53l1x
+        name: "distance2"
+        id: distance2
+        address: 0x42
+        enable_pin: GPIOXX
+        timeout: 200us
+        update_interval: 500ms
+        unit_of_measurement: "m"
+
+
+
+See Also
+--------
+
+- :ref:`sensor-filters`
+- :doc:`vl53l0x`
+- :apiref:`vl53l1x/vl53l1x_sensor.h`
+- `vl53l1x-arduino library <https://github.com/pololu/vl53l1x-arduino/>`__ by `Pololu <https://github.com/pololu>`__
+- :ghedit:`Edit`