drivers: sensor: vl53l0x: add private channels with measurement metadata

drivers/sensor/st/vl53l0x/vl53l0x.c

@@ -20,12 +20,16 @@
 #include <zephyr/types.h>
 #include <zephyr/device.h>
 #include <zephyr/logging/log.h>
+#include <zephyr/drivers/sensor/vl53l0x.h>
 
 #include "vl53l0x_api.h"
 #include "vl53l0x_platform.h"
 
 LOG_MODULE_REGISTER(VL53L0X, CONFIG_SENSOR_LOG_LEVEL);
 
+#define VL53L0X_FIXPOINT1616_SCALE_FACTOR (65536)
+#define VL53L0X_SENSOR_CHANNEL_VAL2_FACTOR (1000000)
+
 /* All the values used in this driver are coming from ST datasheet and examples.
  * It can be found here:
  *   https://www.st.com/en/embedded-software/stsw-img005.html
@@ -288,6 +292,26 @@ static int vl53l0x_channel_get(const struct device *dev,
 	} else if (chan == SENSOR_CHAN_DISTANCE) {
 		val->val1 = drv_data->RangingMeasurementData.RangeMilliMeter / 1000;
 		val->val2 = (drv_data->RangingMeasurementData.RangeMilliMeter % 1000) * 1000;
+	} else if ((enum sensor_channel_vl53l0x)chan ==
+			SENSOR_CHAN_VL53L0X_EFFECTIVE_SPAD_RTN_COUNT) {
+		val->val1 = drv_data->RangingMeasurementData.EffectiveSpadRtnCount / 256;
+		val->val2 = 0;
+	} else if ((enum sensor_channel_vl53l0x)chan == SENSOR_CHAN_VL53L0X_AMBIENT_RATE_RTN_CPS) {
+		val->val1 = (drv_data->RangingMeasurementData.AmbientRateRtnMegaCps >> 16) +
+			(((drv_data->RangingMeasurementData.AmbientRateRtnMegaCps & 0xFFFF) *
+			  VL53L0X_SENSOR_CHANNEL_VAL2_FACTOR) / VL53L0X_FIXPOINT1616_SCALE_FACTOR);
+		val->val2 = 0;
+	} else if ((enum sensor_channel_vl53l0x)chan == SENSOR_CHAN_VL53L0X_SIGNAL_RATE_RTN_CPS) {
+		val->val1 = (drv_data->RangingMeasurementData.SignalRateRtnMegaCps >> 16) +
+			(((drv_data->RangingMeasurementData.SignalRateRtnMegaCps & 0xFFFF) *
+			  VL53L0X_SENSOR_CHANNEL_VAL2_FACTOR) / VL53L0X_FIXPOINT1616_SCALE_FACTOR);
+		val->val2 = 0;
+	} else if ((enum sensor_channel_vl53l0x)chan == SENSOR_CHAN_VL53L0X_RANGE_DMAX) {
+		val->val1 = drv_data->RangingMeasurementData.RangeDMaxMilliMeter / 1000;
+		val->val2 = (drv_data->RangingMeasurementData.RangeDMaxMilliMeter % 1000) * 1000;
+	} else if ((enum sensor_channel_vl53l0x)chan == SENSOR_CHAN_VL53L0X_RANGE_STATUS) {
+		val->val1 = drv_data->RangingMeasurementData.RangeStatus;
+		val->val2 = 0;
 	} else {
 		return -ENOTSUP;
 	}

include/zephyr/drivers/sensor/vl53l0x.h

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2024 Michal Piekos
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @file
+ * @brief Custom channels and values for VL53L0X ToF Sensor
+ *
+ * These channels provide additional sensor data not covered by the standard
+ * Zephyr sensor channels. Application must include vl53l0x.h file to gain
+ * access to these channels.
+ *
+ * Example usage:
+ * @code{c}
+ * #include <zephyr/drivers/sensor/vl53l0x.h>
+ *
+ * if (sensor_channel_get(dev, SENSOR_CHAN_VL53L0X_RANGE_STATUS, &value)) {
+ *	printk("Status: %d\n", value.val1);
+ * }
+ * @endcode
+ */
+
+#ifndef ZEPHYR_INCLUDE_DRIVERS_SENSOR_VL53L0X_H_
+#define ZEPHYR_INCLUDE_DRIVERS_SENSOR_VL53L0X_H_
+
+#include <zephyr/drivers/sensor.h>
+
+/* VL53L0x specific channels */
+enum sensor_channel_vl53l0x {
+	SENSOR_CHAN_VL53L0X_RANGE_DMAX = SENSOR_CHAN_PRIV_START,
+	SENSOR_CHAN_VL53L0X_SIGNAL_RATE_RTN_CPS,
+	SENSOR_CHAN_VL53L0X_AMBIENT_RATE_RTN_CPS,
+	SENSOR_CHAN_VL53L0X_EFFECTIVE_SPAD_RTN_COUNT,
+	SENSOR_CHAN_VL53L0X_RANGE_STATUS,
+};
+
+/* VL53L0x meas status values */
+#define VL53L0X_RANGE_STATUS_RANGE_VALID    (0)
+#define VL53L0X_RANGE_STATUS_SIGMA_FAIL	    (1)
+#define VL53L0X_RANGE_STATUS_SIGNAL_FAIL    (2)
+#define VL53L0X_RANGE_STATUS_MIN_RANGE_FAIL (3)
+#define VL53L0X_RANGE_STATUS_PHASE_FAIL	    (4)
+#define VL53L0X_RANGE_STATUS_HARDWARE_FAIL  (5)
+#define VL53L0X_RANGE_STATUS_NO_UPDATE      (255)
+
+#endif /* ZEPHYR_INCLUDE_DRIVERS_SENSOR_VL53L0X_H_ */

samples/sensor/vl53l0x/README.rst

@@ -9,7 +9,7 @@ Overview
 
 This sample periodically measures distance between vl53l0x sensor
 and target. The result is displayed on the console.
-It also shows how we can use the vl53l0x as a proximity sensor.
+It shows the usage of all available channels including private ones.
 
 Requirements
 ************
@@ -24,24 +24,33 @@ References
 Building and Running
 ********************
 
- This project outputs sensor data to the console. It requires a VL53L0X
- sensor, which is present on the disco_l475_iot1 board.
+This project outputs sensor data to the console. It requires a VL53L0X
+sensor, which is present on the disco_l475_iot1 board.
 
- .. zephyr-app-commands::
-    :zephyr-app: samples/sensor/vl53l0x/
-    :goals: build flash
+.. zephyr-app-commands::
+   :zephyr-app: samples/sensor/vl53l0x/
+   :goals: build flash
 
 
 Sample Output
 =============
 
- .. code-block:: console
-
-    prox is 0
-    distance is 1938
-    prox is 1
-    distance is 70
-    prox is 0
-    distance is 1995
-
-    <repeats endlessly every second>
+.. code-block:: console
+
+   prox is 0
+   distance is 1874 mm
+   Max distance is 000 mm
+   Signal rate is 33435 Cps
+   Ambient rate is 17365 Cps
+   SPADs used: 195
+   Status: OK
+
+   prox is 0
+   distance is 1888 mm
+   Max distance is 000 mm
+   Signal rate is 20846 Cps
+   Ambient rate is 25178 Cps
+   SPADs used: 195
+   Status: OK
+
+   <repeats endlessly every 5 seconds>

samples/sensor/vl53l0x/src/main.c

@@ -7,8 +7,8 @@
 #include <zephyr/kernel.h>
 #include <zephyr/device.h>
 #include <zephyr/drivers/sensor.h>
-#include <stdio.h>
 #include <zephyr/sys/printk.h>
+#include <zephyr/drivers/sensor/vl53l0x.h>
 
 int main(void)
 {
@@ -31,12 +31,30 @@ int main(void)
 		ret = sensor_channel_get(dev, SENSOR_CHAN_PROX, &value);
 		printk("prox is %d\n", value.val1);
 
-		ret = sensor_channel_get(dev,
-					 SENSOR_CHAN_DISTANCE,
-					 &value);
-		printf("distance is %.3fm\n", sensor_value_to_double(&value));
+		ret = sensor_channel_get(dev, SENSOR_CHAN_DISTANCE, &value);
+		printk("distance is %.3lld mm\n", sensor_value_to_milli(&value));
 
-		k_sleep(K_MSEC(1000));
+		ret = sensor_channel_get(dev, SENSOR_CHAN_VL53L0X_RANGE_DMAX, &value);
+		printk("Max distance is %.3lld mm\n", sensor_value_to_milli(&value));
+
+		ret = sensor_channel_get(dev, SENSOR_CHAN_VL53L0X_SIGNAL_RATE_RTN_CPS, &value);
+		printk("Signal rate is %d Cps\n", value.val1);
+
+		ret = sensor_channel_get(dev, SENSOR_CHAN_VL53L0X_AMBIENT_RATE_RTN_CPS, &value);
+		printk("Ambient rate is %d Cps\n", value.val1);
+
+		ret = sensor_channel_get(dev, SENSOR_CHAN_VL53L0X_EFFECTIVE_SPAD_RTN_COUNT, &value);
+		printk("SPADs used: %d\n", value.val1);
+
+		ret = sensor_channel_get(dev, SENSOR_CHAN_VL53L0X_RANGE_STATUS, &value);
+		if (value.val1 == VL53L0X_RANGE_STATUS_RANGE_VALID) {
+			printk("Status: OK\n");
+		} else {
+			printk("Status: Error code %d\n", value.val1);
+		}
+
+		printk("\n");
+		k_sleep(K_MSEC(5000));
 	}
 	return 0;
 }