What is the proper way of implementing and handling status return values from the VL53L1X ultralight driver (STSW-IMG009)?

[JamesLo]

From Pololu's Arduino adaptation of the "heavy" driver =) (STSW-IMG007) I gather that the functions in vl53l1_platform.c should return 0 if they succeed and 1 if they fail, so that's what I've done in the ultralight driver. However, some of the other functions in the ultralight driver don't appear to be handling the status return values correctly. For instance, the function VL53L1X_SensorInit in VL53L1X_api.c mostly ignores the status return until the final call to WL53L1_WrByte, which it then returns as the status for VL53L1X_SensorInit.

VL53L1X_ERROR VL53L1X_SensorInit(uint16_t dev)
{
	VL53L1X_ERROR status = 0;
	uint8_t Addr = 0x00, tmp;
 
	for (Addr = 0x2D; Addr <= 0x87; Addr++){
		status = VL53L1_WrByte(dev, Addr, VL51L1X_DEFAULT_CONFIGURATION[Addr - 0x2D]);
	}
	status = VL53L1X_StartRanging(dev);
	tmp  = 0;
	while(tmp==0){
			status = VL53L1X_CheckForDataReady(dev, &tmp);
	}
	status = VL53L1X_ClearInterrupt(dev);
	status = VL53L1X_StopRanging(dev);
	status = VL53L1_WrByte(dev, VL53L1_VHV_CONFIG__TIMEOUT_MACROP_LOOP_BOUND, 0x09); /* two bounds VHV */
	status = VL53L1_WrByte(dev, 0x0B, 0); /* start VHV from the previous temperature */
	return status;
}

If the first call to VL53L1_WrByte had failed, that fact would have been overwritten by subsequent assignments to status and might not be reflected in the status return value for VL53L1X_SensorInit.

I'm thinking that any function containing multiple API function calls that return status should examine that status after each call and return it immediately if it equals 1. My only concern is that that strategy might leave the sensor in an unpredictable state, in which case I'd instead change all the status return value assignments to status return value ORs, e.g.

	status |= VL53L1X_ClearInterrupt(dev);
	status |= VL53L1X_StopRanging(dev);
	status |= VL53L1_WrByte(dev, VL53L1_VHV_CONFIG__TIMEOUT_MACROP_LOOP_BOUND, 0x09); /* two bounds VHV */
	status |= VL53L1_WrByte(dev, 0x0B, 0); /* start VHV from the previous temperature */
	return status;

Do you agree with the premise of my question? If so, which status handling convention would you recommend?

[John E KVAM]

I love it as an idea.

Is there any way you could post your modifications to the community?

I'll see what I can do to update the driver.

But you are faster that ST is going to be on this point.

One other way to do it is use +=. That way you 'accumulate' the errors, and have some idea of how far back the error might have occurred.

But I like your idea.

• john

[JamesLo]

There are only two files to change (ultralight!), and I did it your way, with the addition assignment. If you prefer using the OR assignment, you can just perform a global find/replace. Caveat: I didn't test because for my Arduino project I made some additional changes that are prob irrelevant to your customers.

Your way suggests more complicated ways of recording which function returned an error (e.g. shift the status returned from each call into a unique bit) but I'm thinking they might be more complicated than they're worth. In your experience, do customers really see fine-grained failures (e.g. one I2C call failing while others succeed), or do they see mostly global failures (e.g. I2C completely broken, or the sensor not responding at all)? If the latter, I'm inclined to just use the OR assignment and if I encounter a failure, accept that I'm going to have to write ad-hoc instrumentation code to figure out what's wrong.

[JamesLo]

(I can't figure out how to attach 2 files, except to post a 2nd time)