implements continuous mode, with an example

Smankusors · Smankusors · commit d8495adc5d1c · 2020-07-14T06:46:58.000+07:00
diff --git a/adafruit_vl53l0x.py b/adafruit_vl53l0x.py
@@ -45,6 +45,7 @@
   https://github.com/adafruit/circuitpython/releases
 * Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
 """
+import atexit
 import math
 import time
 
@@ -156,6 +157,9 @@ class VL53L0X:
     # thread safe!
     _BUFFER = bytearray(3)
 
+    # Is VL53L0X is currently continuous mode? (Needed by `range` property)
+    _continuous_mode = False
+
     def __init__(self, i2c, address=41, io_timeout_s=0):
         # pylint: disable=too-many-statements
         self._device = i2c_device.I2CDevice(i2c, address)
@@ -317,6 +321,7 @@ def __init__(self, i2c, address=41, io_timeout_s=0):
         self._perform_single_ref_calibration(0x00)
         # "restore the previous Sequence Config"
         self._write_u8(_SYSTEM_SEQUENCE_CONFIG, 0xE8)
+        atexit.register(self._cleanup)
 
     def _read_u8(self, address):
         # Read an 8-bit unsigned value from the specified 8-bit address.
@@ -453,6 +458,11 @@ def _get_sequence_step_timeouts(self, pre_range):
             pre_range_mclks,
         )
 
+    def _cleanup(self):
+        #when exiting, don't forget to also turn off continuous mode
+        if (self._continuous_mode):
+            self.stopContinuous()
+
     @property
     def signal_rate_limit(self):
         """The signal rate limit in mega counts per second."""
@@ -527,11 +537,21 @@ def measurement_timing_budget(self, budget_us):
 
     @property
     def range(self):
-        """Perform a single reading of the range for an object in front of
-        the sensor and return the distance in millimeters.
+        """Perform a single (or continuous if `startContinuous` called)
+        reading of the range for an object in front of the sensor and
+        return the distance in millimeters.
+        """
+        # Adapted from readRangeSingleMillimeters in pololu code at:
+        #   https://github.com/pololu/vl53l0x-arduino/blob/master/VL53L0X.cpp
+        if (not self._continuous_mode):
+            self.doRangeMeasurement()
+        return self.readRange()
+
+    def doRangeMeasurement(self):
+        """Perform a single reading of the range for an object in front of the
+        sensor, but without return the distance.
         """
-        # Adapted from readRangeSingleMillimeters &
-        # readRangeContinuousMillimeters in pololu code at:
+        # Adapted from readRangeSingleMillimeters in pololu code at:
         #   https://github.com/pololu/vl53l0x-arduino/blob/master/VL53L0X.cpp
         for pair in (
             (0x80, 0x01),
@@ -551,6 +571,16 @@ def range(self):
                 and (time.monotonic() - start) >= self.io_timeout_s
             ):
                 raise RuntimeError("Timeout waiting for VL53L0X!")
+
+    def readRange(self):
+        """Return a range reading in millimeters.
+
+        Note: Avoid calling this directly. If you do single mode, you need
+        to call doRangeMeasurement first. Or your program will stuck or
+        timeout occurred.
+        """
+        # Adapted from readRangeContinuousMillimeters in pololu code at:
+        #   https://github.com/pololu/vl53l0x-arduino/blob/master/VL53L0X.cpp
         start = time.monotonic()
         while (self._read_u8(_RESULT_INTERRUPT_STATUS) & 0x07) == 0:
             if (
@@ -564,6 +594,59 @@ def range(self):
         self._write_u8(_SYSTEM_INTERRUPT_CLEAR, 0x01)
         return range_mm
 
+    @property
+    def continuous_mode(self):
+        return self._continuous_mode
+
+    @continuous_mode.setter
+    def continuous_mode(self, enabled):
+        if (enabled):
+            self.startContinuous()
+        else:
+            self.stopContinuous()
+
+    def startContinuous(self):
+        """Perform a continuous reading of the range for an object in front of
+        the sensor.
+        """
+        # Adapted from startContinuous in pololu code at:
+        #   https://github.com/pololu/vl53l0x-arduino/blob/master/VL53L0X.cpp
+        for pair in (
+            (0x80, 0x01),
+            (0xFF, 0x01),
+            (0x00, 0x00),
+            (0x91, self._stop_variable),
+            (0x00, 0x01),
+            (0xFF, 0x00),
+            (0x80, 0x00),
+            (_SYSRANGE_START, 0x02),
+        ):
+            self._write_u8(pair[0], pair[1])
+        start = time.monotonic()
+        while (self._read_u8(_SYSRANGE_START) & 0x01) > 0:
+            if (
+                self.io_timeout_s > 0
+                and (time.monotonic() - start) >= self.io_timeout_s
+            ):
+                raise RuntimeError("Timeout waiting for VL53L0X!")
+        self._continuous_mode = True
+
+    def stopContinuous(self):
+        """Stop continuous readings.
+        """
+        # Adapted from stopContinuous in pololu code at:
+        #   https://github.com/pololu/vl53l0x-arduino/blob/master/VL53L0X.cpp
+        for pair in (
+            (_SYSRANGE_START, 0x01),
+            (0xFF, 0x01),
+            (0x00, 0x00),
+            (0x91, 0x00),
+            (0x00, 0x01),
+            (0xFF, 0x00)
+        ):
+            self._write_u8(pair[0], pair[1])
+        self._continuous_mode = False
+
     def set_address(self, new_address):
         """Set a new I2C address to the instantaited object. This is only called when using
         multiple VL53L0X sensors on the same I2C bus (SDA & SCL pins). See also the
diff --git a/examples/vl53l0x_continuous.py b/examples/vl53l0x_continuous.py
@@ -0,0 +1,92 @@
+"""
+Example of how to use the adafruit_vl53l0x library to change the assigned address of
+multiple VL53L0X sensors on the same I2C bus. This example only focuses on 2 VL53L0X
+sensors, but can be modified for more. BE AWARE: a multitude of sensors may require
+more current than the on-board 3V regulator can output (typical current consumption during
+active range readings is about 19 mA per sensor).
+
+This example like vl53l0x_multiple_sensors, but this with sensors in continuous mode.
+So you don't need to wait the sensor to do range measurement and return the distance
+for you.
+
+For example, you have 2 VL53L0X sensors, with timing budget of 200ms, on single mode.
+When you want to get distance from sensor #1, sensor #2 will idle because waiting
+for sensor #1 completes the range measurement. You could do multithreading so you
+can ask both the sensor at the same time, but it's quite expensive.
+
+When you use continuous mode, the sensor will always do range measurement after it
+completes. So when you want to get the distance from both of the device, you don't
+need to wait 400ms, just 200ms for both of the sensors.
+"""
+import time
+import board
+from digitalio import DigitalInOut
+from adafruit_vl53l0x import VL53L0X
+
+# declare the singleton variable for the default I2C bus
+i2c = board.I2C()
+
+# declare the digital output pins connected to the "SHDN" pin on each VL53L0X sensor
+xshut = [
+    DigitalInOut(board.D17),
+    DigitalInOut(board.D18),
+    # add more VL53L0X sensors by defining their SHDN pins here
+]
+
+for power_pin in xshut:
+    # make sure these pins are a digital output, not a digital input
+    power_pin.switch_to_output(value=False)
+    # These pins are active when Low, meaning:
+    #   if the output signal is LOW, then the VL53L0X sensor is off.
+    #   if the output signal is HIGH, then the VL53L0X sensor is on.
+# all VL53L0X sensors are now off
+
+# initialize a list to be used for the array of VL53L0X sensors
+vl53 = []
+
+# now change the addresses of the VL53L0X sensors
+for i, power_pin in enumerate(xshut):
+    # turn on the VL53L0X to allow hardware check
+    power_pin.value = True
+    # instantiate the VL53L0X sensor on the I2C bus & insert it into the "vl53" list
+    vl53.insert(i, VL53L0X(i2c))    # also performs VL53L0X hardware check
+
+    # start continous mode
+    vl53[i].continuous_mode = True
+    # or alternatively with this
+    # vl53[i].startContinous()
+
+    # you will see the benefit of continous mode if you set the measurement timing
+    # budget very high.
+    #vl53[i].measurement_timing_budget = 2000000
+
+    # no need to change the address of the last VL53L0X sensor
+    if i < len(xshut) - 1:
+        # default address is 0x29. Change that to something else
+        vl53[i].set_address(i + 0x30)  # address assigned should NOT be already in use
+# there is a helpful list of pre-designated I2C addresses for various I2C devices at
+# https://learn.adafruit.com/i2c-addresses/the-list
+# According to this list 0x30-0x34 are available, although the list may be incomplete.
+# In the python REPR, you can scan for all I2C devices that are attached and detirmine
+# their addresses using:
+#   >>> import board
+#   >>> i2c = board.I2C()
+#   >>> if i2c.try_lock():
+#   >>>     [hex(x) for x in i2c.scan()]
+#   >>>     i2c.unlock()
+
+def detect_range(count=5):
+    """ take count=5 samples """
+    while count:
+        for index, sensor in enumerate(vl53):
+            print("Sensor {} Range: {}mm".format(index + 1, sensor.range))
+        time.sleep(1.0)
+        count -= 1
+
+if __name__ == "__main__":
+    detect_range()
+else:
+    print(
+        "Multiple VL53L0X sensors' addresses are assigned properly\n"
+        "execute detect_range() to read each sensors range readings"
+    )
