From 6b436521c4ccd34dcbb0f234a0f15c0970ccfb9f Mon Sep 17 00:00:00 2001 From: Bryce Tuppurainen <63719859+BryceTuppurainen@users.noreply.github.com> Date: Wed, 22 Jun 2022 12:22:49 +1000 Subject: [PATCH 1/6] docs|feat: main and README readability fixes --- README.md | 7 +++---- main.py | 6 +++--- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 6b8c649..8e25702 100644 --- a/README.md +++ b/README.md @@ -12,15 +12,14 @@ See the Quickstart Guides for: # Usage ## Example [main.py](https://github.com/CoreElectronics/CE-PiicoDev-VL53L1X-MicroPython-Module/blob/main/main.py) is a simple example to get started. -``` +```python from PiicoDev_VL53L1X import PiicoDev_VL53L1X from time import sleep -distSensor = PiicoDev_VL53L1X() +dist_sensor = PiicoDev_VL53L1X() while True: - dist = distSensor.read() # read the distance in millimetres - print(str(dist) + " mm") # convert the number to a string and print + print(str(distSensor.read()) + " mm") # read the distance in millimetres convert the number to a string and print sleep(0.1) ``` ## Details diff --git a/main.py b/main.py index f81820f..f5acd19 100644 --- a/main.py +++ b/main.py @@ -1,9 +1,9 @@ from PiicoDev_VL53L1X import PiicoDev_VL53L1X from time import sleep -distSensor = PiicoDev_VL53L1X() +dist_sensor = PiicoDev_VL53L1X() while True: - dist = distSensor.read() # read the distance in millimetres - print(str(dist) + " mm") # convert the number to a string and print + # read the distance in millimetres and convert the number to a string and print + print(str(dist_sensor.read()) + " mm") sleep(0.1) From d4886b59a124374faa7b8bc46185850454d2a6a9 Mon Sep 17 00:00:00 2001 From: Bryce Tuppurainen <63719859+BryceTuppurainen@users.noreply.github.com> Date: Wed, 22 Jun 2022 12:24:44 +1000 Subject: [PATCH 2/6] feat: Formatting and removes artifacts --- PiicoDev_VL53L1X.py | 50 +++++++++++++++++---------------------------- 1 file changed, 19 insertions(+), 31 deletions(-) diff --git a/PiicoDev_VL53L1X.py b/PiicoDev_VL53L1X.py index d53e8dd..4b99606 100644 --- a/PiicoDev_VL53L1X.py +++ b/PiicoDev_VL53L1X.py @@ -1,6 +1,8 @@ from PiicoDev_Unified import * -compat_str = '\nUnified PiicoDev library out of date. Get the latest module: https://piico.dev/unified \n' + +COMPAT_STRING = '\nUnified PiicoDev library out of date. Get the latest module: https://piico.dev/unified \n' + VL51L1X_DEFAULT_CONFIGURATION = bytes([ 0x00, # 0x2d : set bit 2 and 5 to 1 for fast plus mode (1MHz I2C), else don't touch */ @@ -103,9 +105,9 @@ def __init__(self, bus=None, freq=None, sda=None, scl=None, address=0x29): if compat_ind >= 1: pass else: - print(compat_str) + print(COMPAT_STRING) except: - print(compat_str) + print(COMPAT_STRING) self.i2c = create_unified_i2c(bus=bus, freq=freq, sda=sda, scl=scl) self.addr = address self.reset() @@ -120,21 +122,34 @@ def __init__(self, bus=None, freq=None, sda=None, scl=None, address=0x29): self.writeReg16Bit(0x001E, self.readReg16Bit(0x0022) * 4) sleep_ms(200) + def writeReg(self, reg, value): return self.i2c.writeto_mem(self.addr, reg, bytes([value]), addrsize=16) + + def writeReg16Bit(self, reg, value): return self.i2c.writeto_mem(self.addr, reg, bytes([(value >> 8) & 0xFF, value & 0xFF]), addrsize=16) + + def readReg(self, reg): return self.i2c.readfrom_mem(self.addr, reg, 1, addrsize=16)[0] + + def readReg16Bit(self, reg): data = self.i2c.readfrom_mem(self.addr, reg, 2, addrsize=16) return (data[0]<<8) + data[1] + + def read_model_id(self): return self.readReg16Bit(0x010F) + + def reset(self): self.writeReg(0x0000, 0x00) sleep_ms(100) self.writeReg(0x0000, 0x01) + + def read(self): try: data = self.i2c.readfrom_mem(self.addr, 0x0089, 17, addrsize=16) # RESULT__RANGE_STATUS @@ -142,41 +157,14 @@ def read(self): print(i2c_err_str.format(self.addr)) return float('NaN') range_status = data[0] - # report_status = data[1] stream_count = data[2] dss_actual_effective_spads_sd0 = (data[3]<<8) + data[4] - # peak_signal_count_rate_mcps_sd0 = (data[5]<<8) + data[6] ambient_count_rate_mcps_sd0 = (data[7]<<8) + data[8] - # sigma_sd0 = (data[9]<<8) + data[10] - # phase_sd0 = (data[11]<<8) + data[12] final_crosstalk_corrected_range_mm_sd0 = (data[13]<<8) + data[14] peak_signal_count_rate_crosstalk_corrected_mcps_sd0 = (data[15]<<8) + data[16] - #status = None - #if range_status in (17, 2, 1, 3): - #status = "HardwareFail" - #elif range_status == 13: - #status = "MinRangeFail" - #elif range_status == 18: - #status = "SynchronizationInt" - #elif range_status == 5: - #status = "OutOfBoundsFail" - #elif range_status == 4: - #status = "SignalFail" - #elif range_status == 6: - #status = "SignalFail" - #elif range_status == 7: - #status = "WrapTargetFail" - #elif range_status == 12: - #status = "XtalkSignalFail" - #elif range_status == 8: - #status = "RangeValidMinRangeClipped" - #elif range_status == 9: - #if stream_count == 0: - #status = "RangeValidNoWrapCheckFail" - #else: - #status = "OK" return final_crosstalk_corrected_range_mm_sd0 + def change_addr(self, new_addr): self.writeReg(0x0001, new_addr & 0x7F) sleep_ms(50) From 15a5a73e2263f61ce7a07c6eddac7d4a3c5cec3e Mon Sep 17 00:00:00 2001 From: Bryce Tuppurainen <63719859+BryceTuppurainen@users.noreply.github.com> Date: Wed, 22 Jun 2022 12:31:12 +1000 Subject: [PATCH 3/6] feat: Removal of a large number of artifacts in read --- PiicoDev_VL53L1X.py | 34 ++++++++++++++++------------------ 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/PiicoDev_VL53L1X.py b/PiicoDev_VL53L1X.py index 4b99606..cb11aaa 100644 --- a/PiicoDev_VL53L1X.py +++ b/PiicoDev_VL53L1X.py @@ -119,53 +119,51 @@ def __init__(self, bus=None, freq=None, sda=None, scl=None, address=0x29): sleep_ms(100) # the API triggers this change in VL53L1_init_and_start_range() once a # measurement is started; assumes MM1 and MM2 are disabled - self.writeReg16Bit(0x001E, self.readReg16Bit(0x0022) * 4) + self.write_reg_16_bit(0x001E, self.read_reg_16_bit(0x0022) * 4) sleep_ms(200) - def writeReg(self, reg, value): + def write_reg(self, reg, value): return self.i2c.writeto_mem(self.addr, reg, bytes([value]), addrsize=16) - def writeReg16Bit(self, reg, value): + def write_reg_16_bit(self, reg, value): return self.i2c.writeto_mem(self.addr, reg, bytes([(value >> 8) & 0xFF, value & 0xFF]), addrsize=16) - def readReg(self, reg): + def read_reg(self, reg): return self.i2c.readfrom_mem(self.addr, reg, 1, addrsize=16)[0] - def readReg16Bit(self, reg): + def read_reg_16_bit(self, reg): data = self.i2c.readfrom_mem(self.addr, reg, 2, addrsize=16) return (data[0]<<8) + data[1] def read_model_id(self): - return self.readReg16Bit(0x010F) + return self.read_reg_16_bit(0x010F) def reset(self): - self.writeReg(0x0000, 0x00) + self.write_reg(0x0000, 0x00) sleep_ms(100) - self.writeReg(0x0000, 0x01) + self.write_reg(0x0000, 0x01) def read(self): + """ + Return a float representing the distance from the sensor to the surface it reflected from + + This is the final crosstalk-corrected range in mm from sd0 + """ try: data = self.i2c.readfrom_mem(self.addr, 0x0089, 17, addrsize=16) # RESULT__RANGE_STATUS - except: + except: # ! Note for reviewer: Typically best practice is to catch exceptions based on their name rather than loose except calls print(i2c_err_str.format(self.addr)) return float('NaN') - range_status = data[0] - stream_count = data[2] - dss_actual_effective_spads_sd0 = (data[3]<<8) + data[4] - ambient_count_rate_mcps_sd0 = (data[7]<<8) + data[8] - final_crosstalk_corrected_range_mm_sd0 = (data[13]<<8) + data[14] - peak_signal_count_rate_crosstalk_corrected_mcps_sd0 = (data[15]<<8) + data[16] - return final_crosstalk_corrected_range_mm_sd0 - + return (data[13]<<8) + data[14] def change_addr(self, new_addr): - self.writeReg(0x0001, new_addr & 0x7F) + self.write_reg(0x0001, new_addr & 0x7F) sleep_ms(50) self.addr = new_addr From 21e10d1ccf8d5a3310116d6f0fb8fcdd761d312e Mon Sep 17 00:00:00 2001 From: Bryce Tuppurainen <63719859+BryceTuppurainen@users.noreply.github.com> Date: Wed, 22 Jun 2022 12:50:56 +1000 Subject: [PATCH 4/6] docs: Number of documentation changes --- PiicoDev_VL53L1X.py | 78 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 69 insertions(+), 9 deletions(-) diff --git a/PiicoDev_VL53L1X.py b/PiicoDev_VL53L1X.py index cb11aaa..231006c 100644 --- a/PiicoDev_VL53L1X.py +++ b/PiicoDev_VL53L1X.py @@ -2,9 +2,9 @@ COMPAT_STRING = '\nUnified PiicoDev library out of date. Get the latest module: https://piico.dev/unified \n' +EXPECTED_MODEL_ID = 0xEACC - -VL51L1X_DEFAULT_CONFIGURATION = bytes([ +VL53L1X_DEFAULT_CONFIGURATION = bytes([ 0x00, # 0x2d : set bit 2 and 5 to 1 for fast plus mode (1MHz I2C), else don't touch */ 0x00, # 0x2e : bit 0 if I2C pulled up at 1.8V, else set bit 0 to 1 (pull up at AVDD) */ 0x00, # 0x2f : bit 0 if GPIO pulled up at 1.8V, else set bit 0 to 1 (pull up at AVDD) */ @@ -100,7 +100,22 @@ class PiicoDev_VL53L1X: - def __init__(self, bus=None, freq=None, sda=None, scl=None, address=0x29): + """ + The VL53L1X IC is used solely used for the PiicoDev + laser-distance-measurement sensor. This class provides + methods for an instance to properly initialise and take + distance measurements + """ + + def __init__(self, bus=None, freq=None, sda=None, scl=None, addr=0x29): + """ + On instantiation: + - Check compatibilty with installed PiicoDev_Unified.py + - Create the i2c instance for serial communication + - Flip register 0x0 to reset the VL53L1X + - Confirm the model ID is valid + - Configure defaults and registers for VL53L1X to allow sensor reading + """ try: if compat_ind >= 1: pass @@ -109,13 +124,13 @@ def __init__(self, bus=None, freq=None, sda=None, scl=None, address=0x29): except: print(COMPAT_STRING) self.i2c = create_unified_i2c(bus=bus, freq=freq, sda=sda, scl=scl) - self.addr = address + self.addr = addr self.reset() sleep_ms(1) - if self.read_model_id() != 0xEACC: + if self.read_model_id() != EXPECTED_MODEL_ID: raise RuntimeError('Failed to find expected ID register values. Check wiring!') # write default configuration - self.i2c.writeto_mem(self.addr, 0x2D, VL51L1X_DEFAULT_CONFIGURATION, addrsize=16) + self.i2c.writeto_mem(self.addr, 0x2D, VL53L1X_DEFAULT_CONFIGURATION, addrsize=16) sleep_ms(100) # the API triggers this change in VL53L1_init_and_start_range() once a # measurement is started; assumes MM1 and MM2 are disabled @@ -123,28 +138,67 @@ def __init__(self, bus=None, freq=None, sda=None, scl=None, address=0x29): sleep_ms(200) + # ! Note for reviwer: please confirm that the precondition + # ! in the docstring is correct def write_reg(self, reg, value): + """ + Helper function to write an 8-bit value from the + provided register + + Legal reg values: 0x0 through 0x5A + """ return self.i2c.writeto_mem(self.addr, reg, bytes([value]), addrsize=16) + # ! Note for reviwer: please confirm that the precondition + # ! in the docstring is correct def write_reg_16_bit(self, reg, value): + """ + Helper function to write a 16-bit value from the + provided register + + Legal reg values: 0x0 through 0x5A + """ return self.i2c.writeto_mem(self.addr, reg, bytes([(value >> 8) & 0xFF, value & 0xFF]), addrsize=16) + # ! Note for reviwer: please confirm that the precondition + # ! in the docstring is correct def read_reg(self, reg): + """ + Helper function to read an 8-bit value from the + provided register + + Legal reg values: 0x0 through 0x5A + """ return self.i2c.readfrom_mem(self.addr, reg, 1, addrsize=16)[0] - + # ! Note for reviwer: please confirm that the precondition + # ! in the docstring is correct def read_reg_16_bit(self, reg): + """ + Helper function to read a 16-bit value from the + provided register + + Legal reg values: 0x0 through 0x5A + """ data = self.i2c.readfrom_mem(self.addr, reg, 2, addrsize=16) return (data[0]<<8) + data[1] def read_model_id(self): + """ + Return the 16-bit value at register 0x010F + which is the model ID (not the I2C address) of the VL53L1X + """ return self.read_reg_16_bit(0x010F) def reset(self): + """ + Resets the VL53L1X by setting register 0x0 to 0x0 (off) + and after 100ms 0x1 (on) + """ self.write_reg(0x0000, 0x00) sleep_ms(100) self.write_reg(0x0000, 0x01) @@ -152,9 +206,12 @@ def reset(self): def read(self): """ - Return a float representing the distance from the sensor to the surface it reflected from + Return an integer in mm representing the + distance from the sensor to the surface + it reflected from - This is the final crosstalk-corrected range in mm from sd0 + This is the final crosstalk-corrected range + (in mm) from sd0 """ try: data = self.i2c.readfrom_mem(self.addr, 0x0089, 17, addrsize=16) # RESULT__RANGE_STATUS @@ -164,6 +221,9 @@ def read(self): return (data[13]<<8) + data[14] def change_addr(self, new_addr): + """ + See README.md for instructions on how to use this method appropriately + """ self.write_reg(0x0001, new_addr & 0x7F) sleep_ms(50) self.addr = new_addr From 8f55aa506bcd7c858c3d1f142e88b9d6985f8241 Mon Sep 17 00:00:00 2001 From: Bryce Tuppurainen <63719859+BryceTuppurainen@users.noreply.github.com> Date: Wed, 22 Jun 2022 12:51:19 +1000 Subject: [PATCH 5/6] docs: typo --- PiicoDev_VL53L1X.py | 1 + 1 file changed, 1 insertion(+) diff --git a/PiicoDev_VL53L1X.py b/PiicoDev_VL53L1X.py index 231006c..221cba9 100644 --- a/PiicoDev_VL53L1X.py +++ b/PiicoDev_VL53L1X.py @@ -220,6 +220,7 @@ def read(self): return float('NaN') return (data[13]<<8) + data[14] + def change_addr(self, new_addr): """ See README.md for instructions on how to use this method appropriately From 74246f7a27f3e99c8a6b6cf460c680681184a7c6 Mon Sep 17 00:00:00 2001 From: Bryce Tuppurainen <63719859+BryceTuppurainen@users.noreply.github.com> Date: Wed, 22 Jun 2022 12:51:47 +1000 Subject: [PATCH 6/6] docs: feat --- PiicoDev_VL53L1X.py | 1 + 1 file changed, 1 insertion(+) diff --git a/PiicoDev_VL53L1X.py b/PiicoDev_VL53L1X.py index 221cba9..29459d9 100644 --- a/PiicoDev_VL53L1X.py +++ b/PiicoDev_VL53L1X.py @@ -4,6 +4,7 @@ COMPAT_STRING = '\nUnified PiicoDev library out of date. Get the latest module: https://piico.dev/unified \n' EXPECTED_MODEL_ID = 0xEACC + VL53L1X_DEFAULT_CONFIGURATION = bytes([ 0x00, # 0x2d : set bit 2 and 5 to 1 for fast plus mode (1MHz I2C), else don't touch */ 0x00, # 0x2e : bit 0 if I2C pulled up at 1.8V, else set bit 0 to 1 (pull up at AVDD) */