
			MMbasic library for the STMicroelectronic VL53L0X time-of-flight distance sensor
           ================================================================================


this library is entirely based on the C++ code found on GITHUB (https://github.com/pololu/vl53l0x-arduino) which itself is based on the API released by STMicroelectronic and was translated to MMbasic by user ville56 from theBackshed forum (https://www.thebackshed.com).

The translation kept most of the comments of the C++ code and the translated code is as efficient as I could possibly make it. I had C++ edu 30 years ago but never really used it professionally. So there will certainly be much room for improvements, but it may be ok as a starting point. 

There are also ways to get the VL53L0X sensor going in MMbasic with much less code, relying on the defaults but with no control otherwise.



General comments:
-----------------
- functions do not always return specific values (no value assigned in the function-body), look into the sourcecode to find out .... By that way you can call it simply by the funtion-name without a variable to be assigned to it. (e.g. myfunct(abc) instead of status=myfunct(abc) ).

- the code is written to have up to 10 sensors, so many calls have a sensor-index as parameter. This index must be manually assigned at the init_sensor(...) function call.

- assigning an I2C address other than the default &H29 must be done with the help of the shutdown pin of the sensor and the setI2Caddr(...) sub.

- the calls and variables, as long as in public scope, do not have any specific prefix, so be careful there may be some name-clash ...

Part 1:		Stuff needed
========================
	the following constants should be defined in the main program:
		const IO_Timeout = 100
		const tof_range_default = 0, tof_long_range = 1, tof_high_speed = 2, tof_high_accuracy = 3

	There are some additional DIM and CONST statements in the functions/subs which are defined as needed, so no need to do it in the main.

Part 2:			user control elements
=====================================

sub select_tof_mode (sens_idx as integer, tof_mode as integer)

	selects a preconfigured mode for the setup. Modes are:
	
	tof_range_default
	tof_long_range
	tof_high_speed
	tof_high_accuracy
	
	definitions necessary in your code:
		const tof_range_default = 0, tof_long_range = 1, tof_high_speed = 2, tof_high_accuracy = 3
-----------------

sub setI2Caddr (old_addr as integer, new_addr as integer)

	selects a new I2C address for the sensor specified with 'old_addr'
-----------------

function init_sensor (sens_idx as integer, sens_i2c as integer, sens_io_timeout as integer) as integer

	initialises the sensor specified with the 'sens_i2c' address. 
		sens_idx is an index (0 ... 9) for the sensor, given manually
		sens_io_timeout ... timeout [mSec] value for I2C as well as measuring operations, specific for this sensor.
-----------------

sub startContinuous(sens_idx as integer, period_ms as integer)

	starts the refered sensor in continouos mode
	
		period_ms ... interval for the measurements. I a value of '0' is specified, the sensor runs in 'back-to-back' mode. Measurements are taken as often as possible.
-----------------
		
function readRangeContMM(sens_idx as integer) as integer

	reads the next available distance value in continouos mode. Waits for completion of measurement if necessary.
-----------------

sub stopContinuous(sens_idx as integer)

	stop continouos mode
-----------------

function readRangeSingleMM(sens_idx as integer) as integer

	initiates a single measurement and waits for completion.
-----------------

sub startRangeSingleMM_BG(sens_idx as integer) as integer

	starts a measurement and immediately returns control to the caller.
-----------------
	
function readRangeSingleMM_BG(sens_idx as integer) as integer

	tries to read a measurement value and returns immediately (BG ... background).
		if the value is
			65535 ... the sensor has timed out, the measurement took more time than 'sens_io_timeout'.
			65534 ... the measurement has not finished yet, try again later.
			0 to 65533 ... distance value in MM.
-----------------
			
function readRangeSingleMM_WT(sens_idx as integer) as integer

	waits for a measurement value
		if the value is
			65535 ... the sensor has timed out, the measurement took more time than 'sens_io_timeout'.
			0 to 65533 ... distance value in MM.

Part 3:			useful functions/subs
=====================================

sub writereg (VL_idx as integer, reg as integer, content as integer, num_bt as integer)
	writes a number of bytes 'num_bt' at I2C address pointed to by 'VL_idx' starting with I2C register 'reg' and containing 'content' data onto I2C bus.
-----------------

function readreg (VL_idx as integer, reg as integer, num_bt as integer) as integer
	returns the content of a device register (max. 8 bytes). Addressing as with 'writereg'.
-----------------


Part 4:				funtions/subs that may be of use
====================================================

function setSignalRateLimit (sens_idx as integer, sens_rate_lim as float) as integer

function setMeasurementTimingBudget(sens_idx as integer, budget_us as integer) as integer


Part 5:				Functions/subs for internal use
===================================================
General remark:
the subs/functions below are just rewritten in MMbasic without much knowledge about the real function in connection to the VL53L0X sensor. So there may be some error in the resulting code, but so far it seems to run fine. There are some comments which I left where they logically were in the C++ code.

sub start_timeout(sens_idx as integer)

sub getSequenceStepEnables(sens_idx as integer, tcc as integer, dss as integer, msrc as integer, pre_range as integer, final_range as integer)

sub getSequenceStepTimeouts(sens_idx%, pre_range%, pre_range_vcsel_period_pclks%, msrc_dss_tcc_mclks%, msrc_dss_tcc_us%, pre_range_mclks%, pre_range_us%, final_range_vcsel_period_pclks%, final_range_mclks%, final_range_us%)

function check_timeout(sens_idx as integer, timeout as integer) as integer

function getSpadInfo(sens_idx as integer, spad_count as integer, type_is_aperture as integer) as integer

function timeoutMicrosecondsToMclks(timeout_period_us as integer, vcsel_period_pclks as integer) as integer

function decodeTimeout(reg_val as integer) as integer

function encodeTimeout(timeout_mclks as integer) as integer

function timeoutMclksToMicroseconds(timeout_period_mclks as integer, vcsel_period_pclks as integer) as integer

function calcMacroPeriod(vcsel_period_pclks as integer) as integer

function getVcselPulsePeriod(sens_idx as integer, type as integer) as integer

function decodeVcselPeriod(reg_val as integer) as integer

function getMeasurementTimingBudget(sens_idx as integer) as integer

function performSingleRefCalibration(sens_idx as integer, vhv_init_byte as integer) as integer

function setVcselPulsePeriod(sens_idx as integer, type as integer, period_pclks as integer) as integer

function encodeVcselPeriod(period_pclks as integer) as integer

