diff --git a/changelog/v1.14.0.rst b/changelog/v1.14.0.rst index 23d48bb4c..fc5ed3df0 100644 --- a/changelog/v1.14.0.rst +++ b/changelog/v1.14.0.rst @@ -29,7 +29,7 @@ Changelog - Version 1.14.0 - November 1 SGP30, components/sensor/sgp30, sgp30.jpg Tx20, components/sensor/tx20, tx20.jpg - VL53L0x, components/sensor/vl53l0x, vl53l0x.svg + VL53L0x, components/sensor/vl53l0x, vl53l0x.png Xiaomi CGG1, components/sensor/xiaomi_cgg1, xiaomi_cgg1.jpg Xiaomi LYWSD02, components/sensor/xiaomi_lywsd02, xiaomi_lywsd02.jpg ZyAura, components/sensor/zyaura, zgm053.jpg diff --git a/components/sensor/images/vl53l0x.png b/components/sensor/images/vl53l0x.png new file mode 100644 index 000000000..41dde9a26 Binary files /dev/null and b/components/sensor/images/vl53l0x.png differ diff --git a/components/sensor/vl53l0x.rst b/components/sensor/vl53l0x.rst index 3c8f24d4d..e5d60bdb5 100644 --- a/components/sensor/vl53l0x.rst +++ b/components/sensor/vl53l0x.rst @@ -3,12 +3,12 @@ VL53L0X Time Of Flight Distance Sensor .. seo:: :description: Instructions for setting up VL53L0X distance sensors in ESPHome. - :image: vl53l0x.jpg + :image: vl53l0x.png :keywords: VL53L0X The ``vl53l0x`` sensor platform allows you to use VL53L0X optical time of flight (`datasheet `__, -`ST `__) with ESPHome +`ST `__) 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 @@ -17,8 +17,21 @@ on several conditions like surface reflectance, field of view, temperature etc. you can expect surfaces up to 60cm to work, after that you need to make sure the surface is reflecting well enough (see also section 5 of datasheet). -The :ref:`I²C Bus ` is -required to be set up in your configuration for this sensor to work. +.. figure:: images/vl53l0x.png + :align: center + :width: 100.0% + +The :ref:`I²C Bus ` 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 + VL53L0X sensor on the I²C bus and the default ``0x29`` address is used. Otherwise this is required. + + .. figure:: images/vl53l0x-full.jpg :align: center @@ -32,7 +45,7 @@ required to be set up in your configuration for this sensor to work. .. code-block:: yaml - # Example configuration entry + # Simple configuration entry example sensor: - platform: vl53l0x name: "VL53L0x Distance" @@ -50,11 +63,44 @@ Configuration variables: (mega counts per second). This is the minimum signal amplitude detected by the sensor necessary for it to report a valid reading. Setting a lower value may increase the range of the sensor but also increases the chance of getting inaccurate readings. Defaults to ``0.25``. -- All other options from :ref:`Sensor `. - **long_range** (*Optional*, bool): Set the sensor in long range mode. The signal_rate_limit is overruled - to ``0.1``. Defaults to false. -- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x29``. + to ``0.1``. Defaults to ``false``. +- **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 VL53L0X sensor is used on the same i2c bus, a unique address must be specified per sensor. +- **enable_pin** (*Optional*, :ref:`Pin Schema `): The pin connected to XSHUT + on vl53l0x to enable/disable sensor. **Required** if not using address ``0x29`` which is the cause if you + have multiple VL53L0X on the same i2c bus. In this case you have to assign a different pin to each VL53L0X. +- **timeout** (*Optional*, :ref:`config-time`): Sensor setup timeout. Default to ``10ms``. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Sensor `. + + +.. code-block:: yaml + + # Muliple VL53L0X sensors on same i2c bus + # Example configuration entry + sensor: + - platform: vl53l0x + name: "distance1" + id: distance1 + address: 0x41 + enable_pin: GPIO16 + timeout: 200us + update_interval: 500ms + unit_of_measurement: "m" + + - platform: vl53l0x + name: "distance2" + id: distance2 + address: 0x42 + enable_pin: GPIO17 + timeout: 200us + update_interval: 500ms + unit_of_measurement: "m" + + See Also -------- diff --git a/images/vl53l0x.png b/images/vl53l0x.png new file mode 100644 index 000000000..41dde9a26 Binary files /dev/null and b/images/vl53l0x.png differ diff --git a/images/vl53l0x.svg b/images/vl53l0x.svg deleted file mode 100644 index caa00f2b9..000000000 --- a/images/vl53l0x.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/index.rst b/index.rst index d03b97954..349be4a75 100644 --- a/index.rst +++ b/index.rst @@ -169,7 +169,7 @@ Sensor Components TX20, components/sensor/tx20, tx20.jpg Ultrasonic Sensor, components/sensor/ultrasonic, ultrasonic.jpg Uptime Sensor, components/sensor/uptime, timer.svg - VL53L0x, components/sensor/vl53l0x, vl53l0x.jpg + VL53L0x, components/sensor/vl53l0x, vl53l0x.png WiFi Signal Strength, components/sensor/wifi_signal, network-wifi.svg Xiaomi BLE, components/sensor/xiaomi_ble, xiaomi_mijia_logo.jpg Xiaomi Miscale, components/sensor/xiaomi_miscale, xiaomi_miscale.jpg