update ULD, add new API to class, add CNH example

README.md

@@ -51,6 +51,7 @@ There are 3 examples with the VL53L8CH library:
 
 * VL53L8CH_ThresholdsDetection: This example code is to show how to configure the thresholds detection of the VL53L8CH satellite sensor.
 
+* VL53L8CH_CNHData: This example code is to show how to configure, capture and decode CNH data from the VL53L8CH sensors.
 
 ## Documentation
 

examples/VL53L8CH_CNHData/VL53L8CH_CNHData.ino

@@ -0,0 +1,175 @@
+/**
+******************************************************************************
+* @file    VL53L8CH_CNHData.ino
+* @brief   Example Arduino sketch using VL53L8CH class API with CNH feature.
+******************************************************************************
+*/
+
+#include <vl53l8ch.h>
+#include <vl53lmz_plugin_cnh.h>
+
+#ifdef ARDUINO_SAM_DUE
+  #define DEV_I2C Wire1
+#else
+  #define DEV_I2C Wire
+#endif
+#define SerialPort Serial
+
+#define LPN_PIN A3
+#define PWREN_PIN 11
+
+VL53L8CH sensor(&DEV_I2C, LPN_PIN);
+
+VL53LMZ_Motion_Configuration cnh_config;
+cnh_data_buffer_t cnh_data_buffer;
+uint32_t cnh_data_size = 0;
+
+int32_t  *p_hist = NULL;
+int8_t   *p_hist_scaler = NULL;
+int32_t  *p_ambient = NULL;
+int8_t   *p_ambient_scaler = NULL;
+
+uint8_t status;
+uint8_t resolution = VL53LMZ_RESOLUTION_4X4;
+
+void setup()
+{
+  SerialPort.begin(460800);
+
+  if (PWREN_PIN >= 0) {
+    pinMode(PWREN_PIN, OUTPUT);
+    digitalWrite(PWREN_PIN, HIGH);
+    delay(10);
+  }
+
+  DEV_I2C.begin();
+
+  status = sensor.begin();
+  if (status != VL53LMZ_STATUS_OK) {
+    SerialPort.println("Sensor begin failed");
+    while (1);
+  }
+
+  if (status != VL53LMZ_STATUS_OK) {
+    SerialPort.println("Sensor init failed");
+    while (1);
+  }
+
+  status = sensor.set_resolution(resolution);
+  if (status != VL53LMZ_STATUS_OK) {
+    SerialPort.println("Set resolution failed");
+    while (1);
+  }
+
+  status = sensor.cnh_init_config(&cnh_config, 0, 24, 4);
+  if (status != VL53LMZ_STATUS_OK) {
+    SerialPort.println("CNH init config failed");
+    while (1);
+  }
+
+  status = sensor.cnh_create_agg_map(&cnh_config,
+                                     16, 0, 0, 1, 1, 4, 4);
+  if (status != VL53LMZ_STATUS_OK) {
+    SerialPort.println("CNH create agg map failed");
+    while (1);
+  }
+
+  status = sensor.cnh_calc_required_memory(&cnh_config, &cnh_data_size);
+  if (status != VL53LMZ_STATUS_OK || cnh_data_size > VL53LMZ_CNH_MAX_DATA_BYTES) {
+    SerialPort.println("CNH memory size error");
+    while (1);
+  }
+
+  status = sensor.cnh_send_config(&cnh_config);
+  if (status != VL53LMZ_STATUS_OK) {
+    SerialPort.println("CNH send config failed");
+    while (1);
+  }
+
+  status = sensor.create_output_config();
+  if (status != VL53LMZ_STATUS_OK) {
+    SerialPort.println("Create output config failed");
+    while (1);
+  }
+
+  union Block_header cnh_data_bh;
+  cnh_data_bh.idx = VL53LMZ_CNH_DATA_IDX;
+  cnh_data_bh.type = 4;
+  cnh_data_bh.size = cnh_data_size / 4;
+
+  status = sensor.add_output_block(cnh_data_bh.bytes);
+  if (status != VL53LMZ_STATUS_OK) {
+    SerialPort.println("Add output block CNH failed");
+    while (1);
+  }
+
+  status = sensor.send_output_config_and_start();
+  if (status != VL53LMZ_STATUS_OK) {
+    SerialPort.println("Start ranging failed");
+    while (1);
+  }
+
+  SerialPort.println("Sensor and CNH configured, ranging started");
+}
+
+void loop()
+{
+  VL53LMZ_ResultsData results;
+  uint8_t data_ready = 0;
+
+  do {
+    status = sensor.check_data_ready(&data_ready);
+  } while (!data_ready);
+
+  if (status == VL53LMZ_STATUS_OK && data_ready) {
+    status = sensor.get_ranging_data(&results);
+    if (status == VL53LMZ_STATUS_OK) {
+      print_results(&results);
+    }
+
+    status = sensor.results_extract_block(VL53LMZ_CNH_DATA_IDX, (uint8_t *)cnh_data_buffer, cnh_data_size);
+    if (status == VL53LMZ_STATUS_OK) {
+      for (int agg_id = 0; agg_id < cnh_config.nb_of_aggregates; agg_id++) {
+        sensor.cnh_get_block_addresses(&cnh_config, agg_id, cnh_data_buffer,
+                                       &p_hist, &p_hist_scaler,
+                                       &p_ambient, &p_ambient_scaler);
+
+        float ambient = ((float) * p_ambient) / (1 << *p_ambient_scaler);
+        SerialPort.print("Aggregate ");
+        SerialPort.print(agg_id);
+        SerialPort.print(", Ambient: ");
+        SerialPort.print(ambient, 1);
+        SerialPort.print(", Bins: ");
+
+        for (int bin = 0; bin < cnh_config.feature_length; bin++) {
+          float bin_val = ((float)p_hist[bin]) / (1 << p_hist_scaler[bin]);
+          SerialPort.print(bin_val, 1);
+          SerialPort.print(", ");
+        }
+        SerialPort.println();
+      }
+    } else {
+      SerialPort.println("Failed to extract CNH data block");
+    }
+  }
+  delay(100);
+}
+
+void print_results(VL53LMZ_ResultsData *res)
+{
+  SerialPort.println("Ranging Results:");
+  for (int i = 0; i < resolution; i++) {
+    if (res->nb_target_detected[i] > 0) {
+      SerialPort.print("Zone ");
+      SerialPort.print(i);
+      SerialPort.print(": Distance=");
+      SerialPort.print(res->distance_mm[i]);
+      SerialPort.print(" mm, Status=");
+      SerialPort.println(res->target_status[i]);
+    } else {
+      SerialPort.print("Zone ");
+      SerialPort.print(i);
+      SerialPort.println(": No target");
+    }
+  }
+}

keywords.txt

@@ -73,6 +73,10 @@ cnh_calc_min_max_distance    KEYWORD2
 cnh_send_config    KEYWORD2
 cnh_get_block_addresses    KEYWORD2
 cnh_get_ref_residual    KEYWORD2
+get_ranging_frequency_x256   KEYWORD2
+set_ranging_frequency_x256   KEYWORD2
+get_VHV_repeat_count   KEYWORD2
+set_VHV_repeat_count   KEYWORD2
 
 #######################################
 # Constants (LITERAL1)
@@ -184,3 +188,5 @@ VL53LMZ_CNH_MAX_DATA_WORDS LITERAL1
 VL53LMZ_CNH_MAX_DATA_BYTES LITERAL1
 VL53LMZ_CNH_DATA_IDX LITERAL1
 VL53LMZ_CNH_DATA_BH LITERAL1
+VL53LMZ_DCI_VHV_CONFIG LITERAL1
+VL53LMZ_STATUS_FW_CHECKSUM_FAIL LITERAL1

library.properties

@@ -1,5 +1,5 @@
 name=STM32duino VL53L8CH
-version=1.0.0
+version=2.0.0
 author=STMicroelectronics
 maintainer=stm32duino
 sentence=Allows controlling the VL53L8CH (Time-of-Flight 8x8 multizone ranging sensor with wide field view)

src/vl53l8ch.cpp

@@ -770,6 +770,63 @@ uint32_t VL53L8CH::cnh_get_ref_residual(cnh_data_buffer_t mi_persistent_array)
   return vl53lmz_cnh_get_ref_residual(mi_persistent_array);
 }
 
+/**
+ * @brief This function gets the current ranging frequency in Hz scaled up by
+ * a factor of 256 to enable non-integer values to be returned.
+ * Ranging frequency corresponds to the time between each measurement.
+ * @param (VL53LMZ_Configuration) *p_dev : VL53LMZ configuration structure.
+ * @param (uint8_t) *p_frequency_x256: Contains the ranging frequency scaled
+ * to 256 x Hz.
+ * @return (uint8_t) status : 0 if ranging frequency is OK.
+ */
+uint8_t VL53L8CH::get_ranging_frequency_x256(VL53LMZ_Configuration *p_dev, uint16_t *p_frequency_x256)
+{
+  return vl53lmz_get_ranging_frequency_x256(p_dev, p_frequency_x256);
+}
+
+/**
+ * @brief This function sets a new ranging frequency in Hz scaled up by 256
+ * to enable non-integer values to be set.
+ * Ranging frequencycorresponds to the measurements frequency. This setting
+ * depends on the resolution, so please select your resolution before using
+ * this function.
+ * @param (VL53LMZ_Configuration) *p_dev : VL53LMZ configuration structure.
+ * @param (uint8_t) frequency_x256 : Contains the ranging frequency in Hz.
+ * - For 4x4, min and max allowed values are : [1*256;60*256]
+ * - For 8x8, min and max allowed values are : [1*256;15*256]
+ * @return (uint8_t) status : 0 if ranging frequency is OK, or 127 if the value
+ * is not correct.
+ */
+uint8_t VL53L8CH::set_ranging_frequency_x256(VL53LMZ_Configuration *p_dev, uint16_t frequency_x256)
+{
+  return vl53lmz_set_ranging_frequency_x256(p_dev, frequency_x256);
+}
+
+/**
+ * @brief This function is used to get the number of frames between 2 temperature
+ * compensation.
+ * @param (VL53LMZ_Configuration) *p_dev : VL53LMZ configuration structure.
+ * @param (uint32_t) *p_repeat_count : Number of frames before next temperature
+ * compensation. Set to 0 to disable the feature (default configuration).
+ */
+uint8_t VL53L8CH::get_VHV_repeat_count(VL53LMZ_Configuration *p_dev, uint32_t *p_repeat_count)
+{
+  return vl53lmz_get_VHV_repeat_count(p_dev, p_repeat_count);
+}
+
+/**
+ * @brief This function is used to set a periodic temperature compensation. By
+ * setting a repeat count different to 0 the firmware automatically runs a
+ * temperature calibration every N frames.
+ * default the repeat count is set to 0
+ * @param (VL53LMZ_Configuration) *p_dev : VL53LMZ configuration structure.
+ * @param (uint32_t) repeat_count : Number of frames between temperature
+ * compensation. Set to 0 to disable the feature (default configuration).
+ */
+uint8_t VL53L8CH::set_VHV_repeat_count(VL53LMZ_Configuration *p_dev, uint32_t repeat_count)
+{
+  return vl53lmz_set_VHV_repeat_count(p_dev, repeat_count);
+}
 
 uint8_t VL53L8CH_io_write(void *handle, uint16_t RegisterAddress, uint8_t *p_values, uint32_t size)
 {

src/vl53l8ch.h

@@ -117,6 +117,10 @@ class VL53L8CH {
     uint8_t cnh_send_config(VL53LMZ_Motion_Configuration *p_mi_config);
     uint8_t cnh_get_block_addresses(VL53LMZ_Motion_Configuration *p_mi_config, int32_t agg_id, cnh_data_buffer_t mi_persistent_array, int32_t **p_hist, int8_t  **p_hist_scaler, int32_t **p_ambient, int8_t **p_ambient_scaler);
     uint32_t cnh_get_ref_residual(cnh_data_buffer_t mi_persistent_array);
+    uint8_t get_ranging_frequency_x256(VL53LMZ_Configuration *p_dev, uint16_t *p_frequency_x256);
+    uint8_t set_ranging_frequency_x256(VL53LMZ_Configuration *p_dev, uint16_t p_frequency_x256);
+    uint8_t get_VHV_repeat_count(VL53LMZ_Configuration *p_dev, uint32_t *p_repeat_count);
+    uint8_t set_VHV_repeat_count(VL53LMZ_Configuration *p_dev, uint32_t p_repeat_count);
 
     /**
      * @brief Utility function to read data.

src/vl53lmz_api.h

@@ -17,6 +17,7 @@
   #pragma anon_unions
 #endif
 
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -27,7 +28,7 @@ extern "C" {
  * @brief Current driver version.
  */
 
-#define VL53LMZ_API_REVISION      "VL53LMZ_2.0.10"
+#define VL53LMZ_API_REVISION      "VL53LMZ_2.0.16"
 
 
 /**
@@ -86,7 +87,7 @@ extern "C" {
  * - VL53LMZ_POWER_MODE_DEEP_SLEEP: This mode clears all memory, by consequence the firmware,
  * the configuration and the calibration are lost. It is recommended when the device sleeps during
  * a long time as it consumes a very low current consumption.
- * Both modes can be changed using function vl53l8ch_set_power_mode().
+ * Both modes can be changed using function vl53l8cx_set_power_mode().
  */
 
 #define VL53LMZ_POWER_MODE_SLEEP    ((uint8_t) 0U)
@@ -104,6 +105,7 @@ extern "C" {
 #define VL53LMZ_STATUS_CORRUPTED_FRAME    ((uint8_t) 2U)
 #define VL53LMZ_STATUS_LASER_SAFETY     ((uint8_t) 3U)
 #define VL53LMZ_STATUS_UNKNOWN_DEVICE   ((uint8_t) 4U)
+#define VL53LMZ_STATUS_FW_CHECKSUM_FAIL   ((uint8_t) 5U)
 #define VL53LMZ_MCU_ERROR         ((uint8_t) 66U)
 #define VL53LMZ_STATUS_INVALID_PARAM    ((uint8_t) 127U)
 #define VL53LMZ_STATUS_FUNC_NOT_AVAILABLE   ((uint8_t) 254U)
@@ -181,6 +183,7 @@ extern "C" {
 #define VL53LMZ_DCI_FW_NB_TARGET    ((uint16_t)0x5478U)
 #define VL53LMZ_DCI_RANGING_MODE    ((uint16_t)0xAD30U)
 #define VL53LMZ_DCI_DSS_CONFIG      ((uint16_t)0xAD38U)
+#define VL53LMZ_DCI_VHV_CONFIG      ((uint16_t)0xAD60U)
 #define VL53LMZ_DCI_TARGET_ORDER    ((uint16_t)0xAE64U)
 #define VL53LMZ_DCI_SHARPENER     ((uint16_t)0xAED8U)
 #define VL53LMZ_DCI_INTERNAL_CP     ((uint16_t)0xB39CU)
@@ -557,6 +560,36 @@ uint8_t vl53lmz_set_ranging_frequency_hz(
   VL53LMZ_Configuration *p_dev,
   uint8_t       frequency_hz);
 
+/**
+ * @brief This function gets the current ranging frequency in Hz scaled up by
+ * a factor of 256 to enable non-integer values to be returned.
+ * Ranging frequency corresponds to the time between each measurement.
+ * @param (VL53LMZ_Configuration) *p_dev : VL53LMZ configuration structure.
+ * @param (uint8_t) *p_frequency_x256: Contains the ranging frequency scaled
+ * to 256 x Hz.
+ * @return (uint8_t) status : 0 if ranging frequency is OK.
+ */
+uint8_t vl53lmz_get_ranging_frequency_x256(
+  VL53LMZ_Configuration       *p_dev,
+  uint16_t                    *p_frequency_x256);
+
+/**
+ * @brief This function sets a new ranging frequency in Hz scaled up by 256
+ * to enable non-integer values to be set.
+ * Ranging frequencycorresponds to the measurements frequency. This setting
+ * depends on the resolution, so please select your resolution before using
+ * this function.
+ * @param (VL53LMZ_Configuration) *p_dev : VL53LMZ configuration structure.
+ * @param (uint8_t) frequency_x256 : Contains the ranging frequency in Hz.
+ * - For 4x4, min and max allowed values are : [1*256;60*256]
+ * - For 8x8, min and max allowed values are : [1*256;15*256]
+ * @return (uint8_t) status : 0 if ranging frequency is OK, or 127 if the value
+ * is not correct.
+ */
+uint8_t vl53lmz_set_ranging_frequency_x256(
+  VL53LMZ_Configuration       *p_dev,
+  uint16_t                    frequency_x256);
+
 /**
  * @brief This function gets the current integration time in ms.
  * @param (VL53LMZ_Configuration) *p_dev : VL53LMZ configuration structure.
@@ -724,6 +757,29 @@ uint8_t vl53lmz_set_glare_filter_cfg(
   uint8_t         threshold_pc_x10,
   int16_t         max_range);
 
+/**
+ * @brief This function is used to get the number of frames between 2 temperature
+ * compensation.
+ * @param (VL53LMZ_Configuration) *p_dev : VL53LMZ configuration structure.
+ * @param (uint32_t) *p_repeat_count : Number of frames before next temperature
+ * compensation. Set to 0 to disable the feature (default configuration).
+ */
+uint8_t vl53lmz_get_VHV_repeat_count(
+  VL53LMZ_Configuration *p_dev,
+  uint32_t *p_repeat_count);
+
+/**
+ * @brief This function is used to set a periodic temperature compensation. By
+ * setting a repeat count different to 0 the firmware automatically runs a
+ * temperature calibration every N frames.
+ * default the repeat count is set to 0
+ * @param (VL53LMZ_Configuration) *p_dev : VL53LMZ configuration structure.
+ * @param (uint32_t) repeat_count : Number of frames between temperature
+ * compensation. Set to 0 to disable the feature (default configuration).
+ */
+uint8_t vl53lmz_set_VHV_repeat_count(
+  VL53LMZ_Configuration *p_dev,
+  uint32_t repeat_count);
 
 /**
  * @brief This function can be used to read 'extra data' from DCI. Using a known