vl53l1_core.h

00001 
00002 /* SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause */
00003 /******************************************************************************
00004  * Copyright (c) 2020, STMicroelectronics - All Rights Reserved
00005 
00006  This file is part of VL53L1 and is dual licensed,
00007  either GPL-2.0+
00008  or 'BSD 3-clause "New" or "Revised" License' , at your option.
00009  ******************************************************************************
00010  */
00011 
00012 
00013 
00014 
00015 #ifndef _VL53L1_CORE_H_
00016 #define _VL53L1_CORE_H_
00017 
00018 #include "vl53l1_platform.h"
00019 #include "vl53l1_core_support.h"
00020 
00021 #ifdef __cplusplus
00022 extern "C" {
00023 #endif
00024 
00025 
00026 
00027 
00028 void VL53L1_init_version(
00029     VL53L1_DEV         Dev);
00030 
00031 
00032 
00033 
00034 void VL53L1_init_ll_driver_state(
00035     VL53L1_DEV         Dev,
00036     VL53L1_DeviceState ll_state);
00037 
00038 
00039 
00040 
00041 VL53L1_Error VL53L1_update_ll_driver_rd_state(
00042     VL53L1_DEV         Dev);
00043 
00044 
00045 
00046 
00047 VL53L1_Error VL53L1_check_ll_driver_rd_state(
00048     VL53L1_DEV         Dev);
00049 
00050 
00051 
00052 
00053 VL53L1_Error VL53L1_update_ll_driver_cfg_state(
00054     VL53L1_DEV         Dev);
00055 
00056 
00057 
00058 
00059 void VL53L1_copy_rtn_good_spads_to_buffer(
00060     VL53L1_nvm_copy_data_t  *pdata,
00061     uint8_t                 *pbuffer);
00062 
00063 
00064 
00065 
00066 void VL53L1_init_system_results(
00067     VL53L1_system_results_t      *pdata);
00068 
00069 
00070 
00071 
00072 void V53L1_init_zone_results_structure(
00073     uint8_t                 active_zones,
00074     VL53L1_zone_results_t  *pdata);
00075 
00076 
00077 
00078 
00079 void V53L1_init_zone_dss_configs(
00080     VL53L1_DEV              Dev);
00081 
00082 
00083 
00084 
00085 void VL53L1_init_histogram_config_structure(
00086     uint8_t   even_bin0,
00087     uint8_t   even_bin1,
00088     uint8_t   even_bin2,
00089     uint8_t   even_bin3,
00090     uint8_t   even_bin4,
00091     uint8_t   even_bin5,
00092     uint8_t   odd_bin0,
00093     uint8_t   odd_bin1,
00094     uint8_t   odd_bin2,
00095     uint8_t   odd_bin3,
00096     uint8_t   odd_bin4,
00097     uint8_t   odd_bin5,
00098     VL53L1_histogram_config_t  *pdata);
00099 
00100 
00101 
00102 void VL53L1_init_histogram_multizone_config_structure(
00103     uint8_t   even_bin0,
00104     uint8_t   even_bin1,
00105     uint8_t   even_bin2,
00106     uint8_t   even_bin3,
00107     uint8_t   even_bin4,
00108     uint8_t   even_bin5,
00109     uint8_t   odd_bin0,
00110     uint8_t   odd_bin1,
00111     uint8_t   odd_bin2,
00112     uint8_t   odd_bin3,
00113     uint8_t   odd_bin4,
00114     uint8_t   odd_bin5,
00115     VL53L1_histogram_config_t  *pdata);
00116 
00117 
00118 
00119 
00120 void VL53L1_init_xtalk_bin_data_struct(
00121     uint32_t                        bin_value,
00122     uint16_t                        VL53L1_p_024,
00123     VL53L1_xtalk_histogram_shape_t *pdata);
00124 
00125 
00126 
00127 
00128 void VL53L1_i2c_encode_uint16_t(
00129     uint16_t    ip_value,
00130     uint16_t    count,
00131     uint8_t    *pbuffer);
00132 
00133 
00134 
00135 
00136 uint16_t VL53L1_i2c_decode_uint16_t(
00137     uint16_t    count,
00138     uint8_t    *pbuffer);
00139 
00140 
00141 
00142 
00143 void VL53L1_i2c_encode_int16_t(
00144     int16_t     ip_value,
00145     uint16_t    count,
00146     uint8_t    *pbuffer);
00147 
00148 
00149 
00150 
00151 int16_t VL53L1_i2c_decode_int16_t(
00152     uint16_t    count,
00153     uint8_t    *pbuffer);
00154 
00155 
00156 
00157 
00158 void VL53L1_i2c_encode_uint32_t(
00159     uint32_t    ip_value,
00160     uint16_t    count,
00161     uint8_t    *pbuffer);
00162 
00163 
00164 
00165 
00166 uint32_t VL53L1_i2c_decode_uint32_t(
00167     uint16_t    count,
00168     uint8_t    *pbuffer);
00169 
00170 
00171 
00172 
00173 uint32_t VL53L1_i2c_decode_with_mask(
00174     uint16_t    count,
00175     uint8_t    *pbuffer,
00176     uint32_t    bit_mask,
00177     uint32_t    down_shift,
00178     uint32_t    offset);
00179 
00180 
00181 
00182 
00183 void VL53L1_i2c_encode_int32_t(
00184     int32_t     ip_value,
00185     uint16_t    count,
00186     uint8_t    *pbuffer);
00187 
00188 
00189 
00190 
00191 int32_t VL53L1_i2c_decode_int32_t(
00192     uint16_t    count,
00193     uint8_t    *pbuffer);
00194 
00195 
00196 
00197 
00198 VL53L1_Error VL53L1_start_test(
00199     VL53L1_DEV     Dev,
00200     uint8_t        test_mode__ctrl);
00201 
00202 
00203 
00204 
00205 VL53L1_Error VL53L1_set_firmware_enable_register(
00206     VL53L1_DEV         Dev,
00207     uint8_t            value);
00208 
00209 
00210 
00211 
00212 VL53L1_Error VL53L1_enable_firmware(
00213     VL53L1_DEV         Dev);
00214 
00215 
00216 
00217 
00218 VL53L1_Error VL53L1_disable_firmware(
00219     VL53L1_DEV         Dev);
00220 
00221 
00222 
00223 
00224 VL53L1_Error VL53L1_set_powerforce_register(
00225     VL53L1_DEV         Dev,
00226     uint8_t            value);
00227 
00228 
00229 
00230 
00231 
00232 VL53L1_Error VL53L1_enable_powerforce(
00233     VL53L1_DEV         Dev);
00234 
00235 
00236 
00237 VL53L1_Error VL53L1_disable_powerforce(
00238     VL53L1_DEV         Dev);
00239 
00240 
00241 
00242 
00243 
00244 VL53L1_Error VL53L1_clear_interrupt(
00245     VL53L1_DEV         Dev);
00246 
00247 
00248 
00249 
00250 
00251 VL53L1_Error VL53L1_force_shadow_stream_count_to_zero(
00252     VL53L1_DEV         Dev);
00253 
00254 
00255 
00256 
00257 uint32_t VL53L1_calc_macro_period_us(
00258     uint16_t fast_osc_frequency,
00259     uint8_t  VL53L1_p_009);
00260 
00261 
00262 
00263 
00264 uint16_t VL53L1_calc_range_ignore_threshold(
00265     uint32_t central_rate,
00266     int16_t  x_gradient,
00267     int16_t  y_gradient,
00268     uint8_t  rate_mult);
00269 
00270 
00271 
00272 
00273 uint32_t VL53L1_calc_timeout_mclks(
00274     uint32_t  timeout_us,
00275     uint32_t  macro_period_us);
00276 
00277 
00278 
00279 uint16_t VL53L1_calc_encoded_timeout(
00280     uint32_t  timeout_us,
00281     uint32_t  macro_period_us);
00282 
00283 
00284 
00285 
00286 uint32_t VL53L1_calc_timeout_us(
00287     uint32_t  timeout_mclks,
00288     uint32_t  macro_period_us);
00289 
00290 
00291 
00292 uint32_t VL53L1_calc_decoded_timeout_us(
00293     uint16_t  timeout_encoded,
00294     uint32_t  macro_period_us);
00295 
00296 
00297 
00298 
00299 uint16_t VL53L1_encode_timeout(
00300     uint32_t timeout_mclks);
00301 
00302 
00303 
00304 
00305 uint32_t VL53L1_decode_timeout(
00306     uint16_t encoded_timeout);
00307 
00308 
00309 
00310 
00311 VL53L1_Error  VL53L1_calc_timeout_register_values(
00312     uint32_t                 phasecal_config_timeout_us,
00313     uint32_t                 mm_config_timeout_us,
00314     uint32_t                 range_config_timeout_us,
00315     uint16_t                 fast_osc_frequency,
00316     VL53L1_general_config_t *pgeneral,
00317     VL53L1_timing_config_t  *ptiming);
00318 
00319 
00320 
00321 
00322 uint8_t VL53L1_encode_vcsel_period(
00323     uint8_t VL53L1_p_031);
00324 
00325 
00326 
00327 
00328 uint32_t VL53L1_decode_unsigned_integer(
00329     uint8_t  *pbuffer,
00330     uint8_t   no_of_bytes);
00331 
00332 
00333 
00334 
00335 void   VL53L1_encode_unsigned_integer(
00336     uint32_t  ip_value,
00337     uint8_t   no_of_bytes,
00338     uint8_t  *pbuffer);
00339 
00340 
00341 
00342 
00343 VL53L1_Error VL53L1_hist_copy_and_scale_ambient_info(
00344     VL53L1_zone_hist_info_t        *pidata,
00345     VL53L1_histogram_bin_data_t    *podata);
00346 
00347 
00348 
00349 
00350 void  VL53L1_hist_get_bin_sequence_config(
00351     VL53L1_DEV                     Dev,
00352     VL53L1_histogram_bin_data_t   *pdata);
00353 
00354 
00355 
00356 
00357 VL53L1_Error  VL53L1_hist_phase_consistency_check(
00358     VL53L1_DEV                   Dev,
00359     VL53L1_zone_hist_info_t     *phist_prev,
00360     VL53L1_zone_objects_t       *prange_prev,
00361     VL53L1_range_results_t      *prange_curr);
00362 
00363 
00364 
00365 
00366 
00367 
00368 
00369 VL53L1_Error  VL53L1_hist_events_consistency_check(
00370     uint8_t                      event_sigma,
00371     uint16_t                     min_effective_spad_count,
00372     VL53L1_zone_hist_info_t     *phist_prev,
00373     VL53L1_object_data_t        *prange_prev,
00374     VL53L1_range_data_t         *prange_curr,
00375     int32_t                     *pevents_tolerance,
00376     int32_t                     *pevents_delta,
00377     VL53L1_DeviceError          *prange_status);
00378 
00379 
00380 
00381 
00382 
00383 
00384 
00385 VL53L1_Error  VL53L1_hist_merged_pulse_check(
00386     int16_t                      min_max_tolerance_mm,
00387     VL53L1_range_data_t         *pdata,
00388     VL53L1_DeviceError          *prange_status);
00389 
00390 
00391 
00392 
00393 
00394 
00395 VL53L1_Error  VL53L1_hist_xmonitor_consistency_check(
00396     VL53L1_DEV                   Dev,
00397     VL53L1_zone_hist_info_t     *phist_prev,
00398     VL53L1_zone_objects_t       *prange_prev,
00399     VL53L1_range_data_t         *prange_curr);
00400 
00401 
00402 
00403 
00404 
00405 
00406 VL53L1_Error  VL53L1_hist_wrap_dmax(
00407     VL53L1_hist_post_process_config_t *phistpostprocess,
00408     VL53L1_histogram_bin_data_t       *pcurrent,
00409     int16_t                           *pwrap_dmax_mm);
00410 
00411 
00412 
00413 
00414 void VL53L1_hist_combine_mm1_mm2_offsets(
00415     int16_t                              mm1_offset_mm,
00416     int16_t                              mm2_offset_mm,
00417     uint8_t                              encoded_mm_roi_centre,
00418     uint8_t                              encoded_mm_roi_size,
00419     uint8_t                              encoded_zone_centre,
00420     uint8_t                              encoded_zone_size,
00421     VL53L1_additional_offset_cal_data_t *pcal_data,
00422     uint8_t                             *pgood_spads,
00423     uint16_t                             aperture_attenuation,
00424     int16_t                             *prange_offset_mm);
00425 
00426 
00427 
00428 
00429 VL53L1_Error VL53L1_hist_xtalk_extract_calc_window(
00430     int16_t                             target_distance_mm,
00431     uint16_t                            target_width_oversize,
00432     VL53L1_histogram_bin_data_t        *phist_bins,
00433     VL53L1_hist_xtalk_extract_data_t   *pxtalk_data);
00434 
00435 
00436 
00437 
00438 VL53L1_Error VL53L1_hist_xtalk_extract_calc_event_sums(
00439     VL53L1_histogram_bin_data_t        *phist_bins,
00440     VL53L1_hist_xtalk_extract_data_t   *pxtalk_data);
00441 
00442 
00443 
00444 
00445 VL53L1_Error VL53L1_hist_xtalk_extract_calc_rate_per_spad(
00446     VL53L1_hist_xtalk_extract_data_t   *pxtalk_data);
00447 
00448 
00449 
00450 VL53L1_Error VL53L1_hist_xtalk_extract_calc_shape(
00451     VL53L1_hist_xtalk_extract_data_t  *pxtalk_data,
00452     VL53L1_xtalk_histogram_shape_t    *pxtalk_shape);
00453 
00454 
00455 
00456 VL53L1_Error VL53L1_hist_xtalk_shape_model(
00457     uint16_t                         events_per_bin,
00458     uint16_t                         pulse_centre,
00459     uint16_t                         pulse_width,
00460     VL53L1_xtalk_histogram_shape_t  *pxtalk_shape);
00461 
00462 
00463 
00464 
00465 uint16_t VL53L1_hist_xtalk_shape_model_interp(
00466     uint16_t      events_per_bin,
00467     uint32_t      phase_delta);
00468 
00469 
00470 
00471 
00472 void VL53L1_spad_number_to_byte_bit_index(
00473     uint8_t  spad_number,
00474     uint8_t *pbyte_index,
00475     uint8_t *pbit_index,
00476     uint8_t *pbit_mask);
00477 
00478 
00479 
00480 
00481 void VL53L1_encode_row_col(
00482     uint8_t  row,
00483     uint8_t  col,
00484     uint8_t *pspad_number);
00485 
00486 
00487 
00488 
00489 void VL53L1_decode_zone_size(
00490     uint8_t   encoded_xy_size,
00491     uint8_t  *pwidth,
00492     uint8_t  *pheight);
00493 
00494 
00495 
00496 
00497 void VL53L1_encode_zone_size(
00498     uint8_t  width,
00499     uint8_t  height,
00500     uint8_t *pencoded_xy_size);
00501 
00502 
00503 
00504 
00505 void VL53L1_decode_zone_limits(
00506     uint8_t   encoded_xy_centre,
00507     uint8_t   encoded_xy_size,
00508     int16_t  *px_ll,
00509     int16_t  *py_ll,
00510     int16_t  *px_ur,
00511     int16_t  *py_ur);
00512 
00513 
00514 
00515 
00516 uint8_t VL53L1_is_aperture_location(
00517     uint8_t   row,
00518     uint8_t   col);
00519 
00520 
00521 
00522 
00523 void VL53L1_calc_max_effective_spads(
00524     uint8_t     encoded_zone_centre,
00525     uint8_t     encoded_zone_size,
00526     uint8_t    *pgood_spads,
00527     uint16_t    aperture_attenuation,
00528     uint16_t   *pmax_effective_spads);
00529 
00530 
00531 
00532 
00533 void VL53L1_calc_mm_effective_spads(
00534     uint8_t     encoded_mm_roi_centre,
00535     uint8_t     encoded_mm_roi_size,
00536     uint8_t     encoded_zone_centre,
00537     uint8_t     encoded_zone_size,
00538     uint8_t    *pgood_spads,
00539     uint16_t    aperture_attenuation,
00540     uint16_t   *pmm_inner_effective_spads,
00541     uint16_t   *pmm_outer_effective_spads);
00542 
00543 
00544 
00545 
00546 void VL53L1_hist_copy_results_to_sys_and_core(
00547     VL53L1_histogram_bin_data_t      *pbins,
00548     VL53L1_range_results_t           *phist,
00549     VL53L1_system_results_t          *psys,
00550     VL53L1_core_results_t            *pcore);
00551 
00552 
00553 
00554 
00555 VL53L1_Error VL53L1_sum_histogram_data(
00556         VL53L1_histogram_bin_data_t *phist_input,
00557         VL53L1_histogram_bin_data_t *phist_output);
00558 
00559 
00560 
00561 
00562 VL53L1_Error VL53L1_avg_histogram_data(
00563         uint8_t no_of_samples,
00564         VL53L1_histogram_bin_data_t *phist_sum,
00565         VL53L1_histogram_bin_data_t *phist_avg);
00566 
00567 
00568 
00569 
00570 VL53L1_Error VL53L1_save_cfg_data(
00571     VL53L1_DEV  Dev);
00572 
00573 
00574 
00575 
00576 VL53L1_Error VL53L1_dynamic_zone_update(
00577     VL53L1_DEV  Dev,
00578     VL53L1_range_results_t *presults);
00579 
00580 
00581 
00582 
00583 VL53L1_Error VL53L1_update_internal_stream_counters(
00584     VL53L1_DEV  Dev,
00585     uint8_t     external_stream_count,
00586     uint8_t     *pinternal_stream_count,
00587     uint8_t     *pinternal_stream_count_val
00588     );
00589 
00590 
00591 
00592 VL53L1_Error VL53L1_multizone_hist_bins_update(
00593     VL53L1_DEV  Dev);
00594 
00595 
00596 
00597 VL53L1_Error VL53L1_set_histogram_multizone_initial_bin_config(
00598     VL53L1_zone_config_t           *pzone_cfg,
00599     VL53L1_histogram_config_t      *phist_cfg,
00600     VL53L1_histogram_config_t      *pmulti_hist
00601     );
00602 
00603 
00604 
00605 uint8_t VL53L1_encode_GPIO_interrupt_config(
00606     VL53L1_GPIO_interrupt_config_t  *pintconf);
00607 
00608 
00609 
00610 VL53L1_GPIO_interrupt_config_t VL53L1_decode_GPIO_interrupt_config(
00611     uint8_t     system__interrupt_config);
00612 
00613 
00614 
00615 VL53L1_Error VL53L1_set_GPIO_distance_threshold(
00616     VL53L1_DEV                      Dev,
00617     uint16_t            threshold_high,
00618     uint16_t            threshold_low);
00619 
00620 
00621 
00622 VL53L1_Error VL53L1_set_GPIO_rate_threshold(
00623     VL53L1_DEV                      Dev,
00624     uint16_t            threshold_high,
00625     uint16_t            threshold_low);
00626 
00627 
00628 
00629 VL53L1_Error VL53L1_set_GPIO_thresholds_from_struct(
00630     VL53L1_DEV                      Dev,
00631     VL53L1_GPIO_interrupt_config_t *pintconf);
00632 
00633 
00634 
00635 
00636 
00637 VL53L1_Error VL53L1_set_ref_spad_char_config(
00638     VL53L1_DEV    Dev,
00639     uint8_t       vcsel_period_a,
00640     uint32_t      phasecal_timeout_us,
00641     uint16_t      total_rate_target_mcps,
00642     uint16_t      max_count_rate_rtn_limit_mcps,
00643     uint16_t      min_count_rate_rtn_limit_mcps,
00644     uint16_t      fast_osc_frequency);
00645 
00646 
00647 
00648 
00649 VL53L1_Error VL53L1_set_ssc_config(
00650     VL53L1_DEV           Dev,
00651     VL53L1_ssc_config_t *pssc_cfg,
00652     uint16_t             fast_osc_frequency);
00653 
00654 
00655 
00656 
00657 VL53L1_Error VL53L1_get_spad_rate_data(
00658     VL53L1_DEV                Dev,
00659     VL53L1_spad_rate_data_t  *pspad_rates);
00660 
00661 
00662 
00663 uint32_t VL53L1_calc_crosstalk_plane_offset_with_margin(
00664         uint32_t     plane_offset_kcps,
00665         int16_t      margin_offset_kcps);
00666 
00667 
00668 
00669 VL53L1_Error VL53L1_low_power_auto_data_init(
00670     VL53L1_DEV                     Dev
00671     );
00672 
00673 
00674 
00675 VL53L1_Error VL53L1_low_power_auto_data_stop_range(
00676     VL53L1_DEV                     Dev
00677     );
00678 
00679 
00680 
00681 
00682 VL53L1_Error VL53L1_dynamic_xtalk_correction_calc_required_samples(
00683     VL53L1_DEV                     Dev
00684     );
00685 
00686 
00687 
00688 VL53L1_Error VL53L1_dynamic_xtalk_correction_calc_new_xtalk(
00689     VL53L1_DEV              Dev,
00690     uint32_t                xtalk_offset_out,
00691     VL53L1_smudge_corrector_config_t    *pconfig,
00692     VL53L1_smudge_corrector_data_t      *pout,
00693     uint8_t                 add_smudge,
00694     uint8_t                 soft_update
00695     );
00696 
00697 
00698 
00699 VL53L1_Error VL53L1_dynamic_xtalk_correction_corrector(
00700     VL53L1_DEV                     Dev
00701     );
00702 
00703 
00704 
00705 VL53L1_Error VL53L1_dynamic_xtalk_correction_data_init(
00706     VL53L1_DEV                     Dev
00707     );
00708 
00709 
00710 
00711 VL53L1_Error VL53L1_dynamic_xtalk_correction_output_init(
00712     VL53L1_LLDriverResults_t *pres
00713     );
00714 
00715 
00716 
00717 VL53L1_Error VL53L1_xtalk_cal_data_init(
00718     VL53L1_DEV                          Dev
00719     );
00720 
00721 
00722 
00723 VL53L1_Error VL53L1_config_low_power_auto_mode(
00724     VL53L1_general_config_t   *pgeneral,
00725     VL53L1_dynamic_config_t   *pdynamic,
00726     VL53L1_low_power_auto_data_t *plpadata
00727     );
00728 
00729 
00730 
00731 VL53L1_Error VL53L1_low_power_auto_setup_manual_calibration(
00732     VL53L1_DEV        Dev);
00733 
00734 
00735 
00736 VL53L1_Error VL53L1_low_power_auto_update_DSS(
00737     VL53L1_DEV        Dev);
00738 
00739 
00740 VL53L1_Error VL53L1_compute_histo_merge_nb(
00741     VL53L1_DEV        Dev,  uint8_t *histo_merge_nb);
00742 
00743 #ifdef __cplusplus
00744 }
00745 #endif
00746 
00747 #endif
00748