1 /* 2 * Copyright (c) 2017, STMicroelectronics - All Rights Reserved 3 * 4 * This file is part of VL53L1 Core and is dual licensed, 5 * either 'STMicroelectronics 6 * Proprietary license' 7 * or 'BSD 3-clause "New" or "Revised" License' , at your option. 8 * 9 ******************************************************************************** 10 * 11 * 'STMicroelectronics Proprietary license' 12 * 13 ******************************************************************************** 14 * 15 * License terms: STMicroelectronics Proprietary in accordance with licensing 16 * terms at www.st.com/sla0081 17 * 18 * STMicroelectronics confidential 19 * Reproduction and Communication of this document is strictly prohibited unless 20 * specifically authorized in writing by STMicroelectronics. 21 * 22 * 23 ******************************************************************************** 24 * 25 * Alternatively, VL53L1 Core may be distributed under the terms of 26 * 'BSD 3-clause "New" or "Revised" License', in which case the following 27 * provisions apply instead of the ones mentioned above : 28 * 29 ******************************************************************************** 30 * 31 * License terms: BSD 3-clause "New" or "Revised" License. 32 * 33 * Redistribution and use in source and binary forms, with or without 34 * modification, are permitted provided that the following conditions are met: 35 * 36 * 1. Redistributions of source code must retain the above copyright notice, this 37 * list of conditions and the following disclaimer. 38 * 39 * 2. Redistributions in binary form must reproduce the above copyright notice, 40 * this list of conditions and the following disclaimer in the documentation 41 * and/or other materials provided with the distribution. 42 * 43 * 3. Neither the name of the copyright holder nor the names of its contributors 44 * may be used to endorse or promote products derived from this software 45 * without specific prior written permission. 46 * 47 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 48 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 49 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 50 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 51 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 52 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 53 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 54 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 55 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 56 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 57 * 58 * 59 ******************************************************************************** 60 * 61 */ 62 63 /** 64 * @file vl53l1_ll_def.h 65 * 66 * @brief Type definitions for VL53L1 LL Driver. 67 * 68 */ 69 70 71 #ifndef _VL53L1_LL_DEF_H_ 72 #define _VL53L1_LL_DEF_H_ 73 74 #include "vl53l1_ll_device.h" 75 #include "vl53l1_error_codes.h" 76 #include "vl53l1_register_structs.h" 77 #include "vl53l1_platform_user_config.h" 78 #include "vl53l1_platform_user_defines.h" 79 #include "vl53l1_error_exceptions.h" 80 81 #ifdef __cplusplus 82 extern "C" { 83 #endif 84 85 /** @defgroup VL53L1_globalLLDriverDefine_group VL53L1 Defines 86 * @brief VL53L1 LL Driver Defines 87 * @{ 88 */ 89 90 /** VL53L1 Low Level Driver IMPLEMENTATION major version */ 91 #define VL53L1_LL_API_IMPLEMENTATION_VER_MAJOR 1 92 /** VL53L1 Low Level DriverI IMPLEMENTATION minor version */ 93 #define VL53L1_LL_API_IMPLEMENTATION_VER_MINOR 2 94 /** VL53L1 Low Level DriverI IMPLEMENTATION sub version */ 95 #define VL53L1_LL_API_IMPLEMENTATION_VER_SUB 10 96 /** VL53L1 Low Level Driver IMPLEMENTATION sub version */ 97 #define VL53L1_LL_API_IMPLEMENTATION_VER_REVISION 1840 98 99 #define VL53L1_LL_API_IMPLEMENTATION_VER_STRING "1.2.11.1840" 100 101 /** VL53L1_FIRMWARE min and max compatible revisions */ 102 #define VL53L1_FIRMWARE_VER_MINIMUM 398 103 #define VL53L1_FIRMWARE_VER_MAXIMUM 400 104 105 106 /**************************************** 107 * PRIVATE define do not edit 108 ****************************************/ 109 110 #define VL53L1_LL_CALIBRATION_DATA_STRUCT_VERSION 0xECAB0102 111 /** VL53L1 Calibration Data struct version */ 112 113 /* Start Patch_ZoneCalDataStructVersion_11854 */ 114 115 #define VL53L1_LL_ZONE_CALIBRATION_DATA_STRUCT_VERSION 0xECAE0101 116 /** VL53L1 Zone Calibration Data struct version */ 117 118 /* End Patch_ZoneCalDataStructVersion_11854 */ 119 120 #define VL53L1_MAX_OFFSET_RANGE_RESULTS 3 121 /*!< Sets the maximum number of offset range results 122 required for the offset calibration. 123 Order is RANGE, MM1, MM2 */ 124 125 #define VL53L1_NVM_MAX_FMT_RANGE_DATA 4 126 /*!< The number of FMT range data points stored in NVM */ 127 128 #define VL53L1_NVM_PEAK_RATE_MAP_SAMPLES 25 129 /*!< The number of samples in the NVM peak rate signal map */ 130 #define VL53L1_NVM_PEAK_RATE_MAP_WIDTH 5 131 /*!< Array width of NVM peak rate signal map */ 132 #define VL53L1_NVM_PEAK_RATE_MAP_HEIGHT 5 133 /*!< Array height the NVM peak rate signal map */ 134 135 /** @defgroup VL53L1_defineExtraError_group Error and Warning code returned by API 136 * The following DEFINE are used to identify the PAL ERROR 137 * @{ 138 */ 139 140 #define VL53L1_ERROR_DEVICE_FIRMWARE_TOO_OLD ((VL53L1_Error) - 80) 141 /*!< Device Firmware too old .. */ 142 #define VL53L1_ERROR_DEVICE_FIRMWARE_TOO_NEW ((VL53L1_Error) - 85) 143 /*!< Device Firmware too new .. */ 144 #define VL53L1_ERROR_UNIT_TEST_FAIL ((VL53L1_Error) - 90) 145 /*!< Unit Test Fail */ 146 #define VL53L1_ERROR_FILE_READ_FAIL ((VL53L1_Error) - 95) 147 /*!< File Read Fail */ 148 #define VL53L1_ERROR_FILE_WRITE_FAIL ((VL53L1_Error) - 96) 149 /*!< File Write Fail */ 150 /*!< Tells requested functionality has not been implemented yet or 151 * not compatible with the device */ 152 /** @} VL53L1_defineExtraError_group */ 153 154 155 /** @brief Defines the parameters of the LL driver Get Version Functions 156 */ 157 typedef struct { 158 uint32_t ll_revision; /*!< revision number */ 159 uint8_t ll_major; /*!< major number */ 160 uint8_t ll_minor; /*!< minor number */ 161 uint8_t ll_build; /*!< build number */ 162 } VL53L1_ll_version_t; 163 164 165 /** @brief Reference SPAD Characterization (RefSpadChar) Config 166 */ 167 168 typedef struct { 169 170 uint8_t device_test_mode; /*!< Device test mode */ 171 uint8_t vcsel_period; /*!< VCSEL period (register) value */ 172 uint32_t timeout_us; /*!< timeout in [us] */ 173 uint16_t target_count_rate_mcps; 174 /*!< Target reference total count rate in [Mcps] - 9.7 format */ 175 uint16_t min_count_rate_limit_mcps; 176 /*!< Min valid reference rate [Mcps] - 9.7 format */ 177 uint16_t max_count_rate_limit_mcps; 178 /*!< Max valid reference rate [Mcps] - 9.7 format */ 179 180 } VL53L1_refspadchar_config_t; 181 182 183 /** @brief SPAD Self Check (SSC) Config data structure 184 */ 185 186 187 typedef struct { 188 189 VL53L1_DeviceSscArray array_select; 190 /*!< SPAD Array select 191 * 0 - store RTN array count rates \n 192 * 1 - store REF array count rates */ 193 uint8_t vcsel_period; 194 /*!< VCSEL period (register) value */ 195 uint8_t vcsel_start; 196 /*!< VCSEL start register value */ 197 uint8_t vcsel_width; 198 /*!< VCSEL ssc_timeout_us width register value e.g. 2 */ 199 uint32_t timeout_us; 200 /*!< requested Ranging Timeout in [us] e.g 100000us */ 201 uint16_t rate_limit_mcps; 202 /*!< Rate limit for checks either 1.15 or 203 * 9.7 dependent on test_mode 204 */ 205 206 } VL53L1_ssc_config_t; 207 208 209 /** @brief Xtalk Extraction and Paramter Config 210 */ 211 212 typedef struct { 213 214 215 uint32_t algo__crosstalk_compensation_plane_offset_kcps; 216 /*!< Private crosstalk_compensation_plane_offset_kcps (fixed point 9.9) */ 217 int16_t algo__crosstalk_compensation_x_plane_gradient_kcps; 218 /*!< Private crosstalk_compensation_x_plane_gradient_kcps (fixed point 5.11) */ 219 int16_t algo__crosstalk_compensation_y_plane_gradient_kcps; 220 /*!< Private crosstalk_compensation_y_plane_gradient_kcps (fixed point 5.11) */ 221 uint32_t nvm_default__crosstalk_compensation_plane_offset_kcps; 222 /*!< NVm stored crosstalk_compensation_plane_offset_kcps (fixed point 9.9) */ 223 int16_t nvm_default__crosstalk_compensation_x_plane_gradient_kcps; 224 /*!< NVM stored crosstalk_compensation_x_plane_gradient_kcps (fixed point 5.11) */ 225 int16_t nvm_default__crosstalk_compensation_y_plane_gradient_kcps; 226 /*!< NVM stored crosstalk_compensation_y_plane_gradient_kcps (fixed point 5.11) */ 227 uint8_t global_crosstalk_compensation_enable; 228 /*!< Enable switch for crosstalk compensation in all modes */ 229 int16_t lite_mode_crosstalk_margin_kcps; 230 /*!< Additional xtalk factor rate, added to plane_offset value in both 231 * SD mode, applied as a seperate addition at point of 232 * application to the device, plane_offset 233 * value remains unaltered. (fixed point 7.9) 234 */ 235 uint8_t crosstalk_range_ignore_threshold_mult; 236 /*!< User set multiplier for range ignore threshold setting (fixed point 3.5) */ 237 uint16_t crosstalk_range_ignore_threshold_rate_mcps; 238 /*!< Generated range ignore threshold rate in Mcps per spad (fixed 239 * point 3.13) 240 */ 241 242 } VL53L1_xtalk_config_t; 243 244 245 /** @brief TuningParameter Storage 246 * 247 * - Storage structure for any LLD tuning parms 248 * which are dynamically altered by low level functions 249 * mostly when programming directly to the device 250 * 251 *- Added as part of Patch_AddingTuningParmStorage_11821 252 */ 253 254 typedef struct { 255 256 257 uint16_t tp_tuning_parm_version; 258 /*!< Programmed Global tuning version num for debug 259 */ 260 uint16_t tp_tuning_parm_key_table_version; 261 /*!< Key Table tuning structure \ 262 * version 263 */ 264 uint16_t tp_tuning_parm_lld_version; 265 /*!< Programmed LLD version to ensure matching tuning structure \ 266 * key table 267 */ 268 uint8_t tp_init_phase_rtn_lite_long; 269 /*!< initial phase value for rtn array \ 270 * in Lite Long Ranging Mode 271 */ 272 uint8_t tp_init_phase_rtn_lite_med; 273 /*!< initial phase value for rtn array \ 274 * in Lite Medium Ranging Mode 275 */ 276 uint8_t tp_init_phase_rtn_lite_short; 277 /*!< initial phase value for rtn array \ 278 * in Lite Short Ranging Mode 279 */ 280 uint8_t tp_init_phase_ref_lite_long; 281 /*!< initial phase value for ref array \ 282 * in Lite Long Ranging Mode 283 */ 284 uint8_t tp_init_phase_ref_lite_med; 285 /*!< initial phase value for ref array \ 286 * in Lite Medium Ranging Mode 287 */ 288 uint8_t tp_init_phase_ref_lite_short; 289 /*!< initial phase value for ref array \ 290 * in Lite short Ranging Mode 291 */ 292 293 uint8_t tp_consistency_lite_phase_tolerance; 294 /*!< Phase tolerance consistency value to be used \ 295 * in Lite modes 296 */ 297 uint8_t tp_phasecal_target; 298 /*!< Phasecal target value 299 */ 300 uint16_t tp_cal_repeat_rate; 301 /*!< Auto VHV/Calibration repeat rate for \ 302 * use in Lite mode 303 */ 304 uint8_t tp_lite_min_clip; 305 /*!< Min Clip value in mm applied to device in Lite \ 306 * modes 307 */ 308 309 uint16_t tp_lite_long_sigma_thresh_mm; 310 /*!< Sigma threshold limit for Lite Long mode \ 311 * in 14.2 format mm 312 */ 313 uint16_t tp_lite_med_sigma_thresh_mm; 314 /*!< Sigma threshold limit for Lite Medium mode \ 315 * in 14.2 format mm 316 */ 317 uint16_t tp_lite_short_sigma_thresh_mm; 318 /*!< Sigma threshold limit for Lite Short mode \ 319 * in 14.2 format mm 320 */ 321 322 uint16_t tp_lite_long_min_count_rate_rtn_mcps; 323 /*!< Min count rate level used in lite long mode \ 324 * in 9.7 Mcps format 325 */ 326 uint16_t tp_lite_med_min_count_rate_rtn_mcps; 327 /*!< Min count rate level used in lite medium mode \ 328 * in 9.7 Mcps format 329 */ 330 uint16_t tp_lite_short_min_count_rate_rtn_mcps; 331 /*!< Min count rate level used in lite short mode \ 332 * in 9.7 Mcps format 333 */ 334 335 uint8_t tp_lite_sigma_est_pulse_width_ns; 336 /*!< Sigma thresholding tunign parm for Lite mode 337 */ 338 uint8_t tp_lite_sigma_est_amb_width_ns; 339 /*!< Sigma thresholding tunign parm for Lite mode 340 */ 341 uint8_t tp_lite_sigma_ref_mm; 342 /*!< Sigma thresholding tunign parm for Lite mode 343 */ 344 uint8_t tp_lite_seed_cfg; 345 /*!< Lite Mode Seed mode switch 346 */ 347 uint8_t tp_timed_seed_cfg; 348 /*!< Timed Mode Seed mode switch 349 */ 350 351 uint8_t tp_lite_quantifier; 352 /*!< Low level quantifier setting for lite modes 353 */ 354 uint8_t tp_lite_first_order_select; 355 /*!< Low level First order select setting for lite modes 356 */ 357 358 uint16_t tp_dss_target_lite_mcps; 359 /*!< DSS Target rate in 9.7 format Mcps for lite modes 360 */ 361 uint16_t tp_dss_target_timed_mcps; 362 /*!< DSS Target rate in 9.7 format Mcps for Timed modes 363 */ 364 365 uint32_t tp_phasecal_timeout_lite_us; 366 /*!< Phasecal timeout in us for lite modes 367 */ 368 369 uint32_t tp_phasecal_timeout_timed_us; 370 /*!< Phasecal timeout in us for Timed modes 371 */ 372 373 uint32_t tp_mm_timeout_lite_us; 374 /*!< MM stage timeout in us for Lite modes 375 */ 376 uint32_t tp_mm_timeout_timed_us; 377 /*!< MM stage timeout in us for Timed modes 378 */ 379 uint32_t tp_mm_timeout_lpa_us; 380 /*!< MM stage timeout in us for Low Power Auto modes 381 */ 382 383 uint32_t tp_range_timeout_lite_us; 384 /*!< Ranging stage timeout in us for Lite modes 385 */ 386 uint32_t tp_range_timeout_timed_us; 387 /*!< Ranging stage timeout in us for Timed modes 388 */ 389 uint32_t tp_range_timeout_lpa_us; 390 /*!< Ranging stage timeout in us for Low Power Auto modes 391 */ 392 393 } VL53L1_tuning_parm_storage_t; 394 395 396 397 /** @brief Optical Centre data 398 * 399 */ 400 401 typedef struct { 402 403 uint8_t x_centre; /*!< Optical x centre : 4.4 format */ 404 uint8_t y_centre; /*!< Optical y centre : 4.4 format */ 405 406 } VL53L1_optical_centre_t; 407 408 409 /** @brief Defines User Zone(ROI) parameters 410 * 411 */ 412 413 typedef struct { 414 415 uint8_t x_centre; /*!< Zone x centre : 0-15 range */ 416 uint8_t y_centre; /*!< Zone y centre : 0-15 range */ 417 uint8_t width; /*!< Width of Zone 0 = 1, 7 = 8, 15 = 16 */ 418 uint8_t height; /*!< Height of Zone 0 = 1, 7 = 8, 15 = 16 */ 419 420 } VL53L1_user_zone_t; 421 422 423 /** 424 * @struct VL53L1_GPIO_interrupt_config_t 425 * 426 * @brief Structure to configure conditions when GPIO interrupt is trigerred 427 * 428 */ 429 430 typedef struct { 431 432 /*! Distance interrupt mode */ 433 VL53L1_GPIO_Interrupt_Mode intr_mode_distance; 434 435 /*! Rate interrupt mode */ 436 VL53L1_GPIO_Interrupt_Mode intr_mode_rate; 437 438 /*! trigger interrupt if a new measurement is ready 439 * __WARNING!__ will override other settings 440 */ 441 uint8_t intr_new_measure_ready; 442 443 /*! Trigger interrupt if no target found */ 444 uint8_t intr_no_target; 445 446 /*! If set to 0, interrupts will only be triggered if BOTH rate AND 447 * distance thresholds are triggered (combined mode). If set to 1, 448 * interrupts will be triggered if EITHER rate OR distance thresholds 449 * are triggered (independent mode). */ 450 uint8_t intr_combined_mode; 451 452 /* -- thresholds -- */ 453 /* The struct holds a copy of the thresholds but they are written when 454 * this structure is set using VL53L1_set_GPIO_interrupt_config/_struct 455 * */ 456 457 /*! Distance threshold high limit (mm) */ 458 uint16_t threshold_distance_high; 459 460 /*! Distance threshold low limit (mm) */ 461 uint16_t threshold_distance_low; 462 463 /*! Rate threshold high limit (9.7 Mcps) */ 464 uint16_t threshold_rate_high; 465 466 /*! Rate threshold low limit (9.7 Mcps) */ 467 uint16_t threshold_rate_low; 468 469 } VL53L1_GPIO_interrupt_config_t; 470 471 /* Start Patch_LowPowerAutoMode */ 472 /** 473 * @struct VL53L1_low_power_auto_data_t 474 * 475 * @brief Structure to hold state, tuning and output variables for the low 476 * power auto mode (Presence) 477 * 478 */ 479 480 typedef struct { 481 482 /*! Tuning variable for the VHV loop bound setting in low power auto 483 * mode. This is zero based, so the number of loops in VHV is this + 1. 484 * Please note, the first range will run with default VHV settings. 485 * Only lower 6 bits are allowed */ 486 uint8_t vhv_loop_bound; 487 488 /*! Indicates if we are or are not in low power auto mode */ 489 uint8_t is_low_power_auto_mode; 490 491 /*! Used to check if we're running the first range or not. Not to be 492 * used as a stream count */ 493 uint8_t low_power_auto_range_count; 494 495 /*! saved interrupt config byte to restore */ 496 uint8_t saved_interrupt_config; 497 498 /*! saved vhv config init byte to restore */ 499 uint8_t saved_vhv_init; 500 501 /*! saved vhv config timeout byte to restore */ 502 uint8_t saved_vhv_timeout; 503 504 /*! phase cal resutl from the first range */ 505 uint8_t first_run_phasecal_result; 506 507 /*! DSS. Total rate per spad given from the current range */ 508 uint32_t dss__total_rate_per_spad_mcps; 509 510 /*! DSS. Calculated required SPADs value */ 511 uint16_t dss__required_spads; 512 513 } VL53L1_low_power_auto_data_t; 514 515 /* End Patch_LowPowerAutoMode */ 516 517 /** 518 * @struct VL53L1_range_data_t 519 * @brief Internal data structure for storing post processed ranges 520 * 521 */ 522 523 typedef struct { 524 525 /* Info size */ 526 527 uint8_t range_id; 528 /*!< Range Result id e.g 0, 1, 2 */ 529 uint32_t time_stamp; 530 /*!< 32-bit time stamp */ 531 532 uint16_t width; 533 /*!< VCSEL pulse width in [PLL clocks] 6.4 format */ 534 uint8_t woi; 535 /*!< WOI width in [PLL clocks] */ 536 537 uint16_t fast_osc_frequency; 538 /*!< Oscillator frequency in 4.12 format */ 539 uint16_t zero_distance_phase; 540 /*!< Zero Distance phase in 5.11 format */ 541 uint16_t actual_effective_spads; 542 /*!< effective SPAD count in 8.8 format */ 543 544 uint32_t total_periods_elapsed; 545 /*!< Elapsed time in macro periods for readout channel */ 546 547 uint32_t peak_duration_us; 548 /*!< Peak VCSEL width time in us */ 549 550 uint32_t woi_duration_us; 551 /*!< WOI duration time in us */ 552 553 554 /* Event counts */ 555 556 uint32_t ambient_window_events; 557 /*!< Return event count for the ambient window */ 558 uint32_t ranging_total_events; 559 /*!< Return ranging event count for the ranging window. 560 This includes both VCSEL and ambient contributions */ 561 int32_t signal_total_events; 562 /*!< Return event count for the ranging window with ambient 563 subtracted, Note it is 32-bit signed register */ 564 565 /* Rates */ 566 567 uint16_t peak_signal_count_rate_mcps; 568 /*! Peak signal (VCSEL) Rate in 9.7 format */ 569 uint16_t avg_signal_count_rate_mcps; 570 /*! Average signal (VCSEL) Rate in 9.7 format */ 571 uint16_t ambient_count_rate_mcps; 572 /*! Ambient Rate in 9.7 format */ 573 uint16_t total_rate_per_spad_mcps; 574 /*! Total Rate Per SPAD in 3.13 format */ 575 uint32_t peak_rate_per_spad_kcps; 576 /*! Peak Rate Per SPAD in 13.11 format */ 577 578 /* Sigma */ 579 580 uint16_t sigma_mm; 581 /*!< Range sigma Estimate [mm] 9.7 format */ 582 583 /* Phase */ 584 585 uint16_t median_phase; 586 /*!< Median Phase in 5.11 format */ 587 588 /* Range */ 589 590 int16_t median_range_mm; 591 /*!< Median Range in [mm] by default there are no fractional bits 592 Optionally 1 or 2 fractional can be enabled via the 593 VL53L1_SYSTEM__FRACTIONAL_ENABLE register */ 594 595 /* Range status */ 596 597 uint8_t range_status; 598 599 } VL53L1_range_data_t; 600 601 602 /** 603 * @struct VL53L1_range_results_t 604 * @brief Structure for storing the set of range results 605 * 606 */ 607 608 typedef struct { 609 610 VL53L1_DeviceState cfg_device_state; 611 /*!< Configuration Device State */ 612 VL53L1_DeviceState rd_device_state; 613 /*!< Read Device State */ 614 uint8_t stream_count; 615 /*!< 8-bit stream count */ 616 617 uint8_t device_status; 618 /*!< Global device status for result set */ 619 620 VL53L1_range_data_t data[2]; 621 /*!< Range data each target distance */ 622 623 } VL53L1_range_results_t; 624 625 /** 626 * @struct VL53L1_offset_range_data_t 627 * @brief Structure for storing the set of range results 628 * required for the mm1 and mm2 offset calibration 629 * functions 630 * 631 */ 632 633 typedef struct { 634 635 uint8_t preset_mode; 636 /*!< Preset Mode use for range */ 637 uint8_t dss_config__roi_mode_control; 638 /*!< Dynamic SPAD selection mode */ 639 uint16_t dss_config__manual_effective_spads_select; 640 /*!< Requested number of manual effective SPAD's */ 641 uint8_t no_of_samples; 642 /*!< Number of ranges */ 643 uint32_t effective_spads; 644 /*!< Average effective SPAD's 8.8 format */ 645 uint32_t peak_rate_mcps; 646 /*!< Average peak rate Mcps 9.7 format */ 647 uint32_t sigma_mm; 648 /*!< Average sigma in [mm] 14.2 format */ 649 int32_t median_range_mm; 650 /*!< Avg of median range over all ranges \ 651 note value is signed */ 652 int32_t range_mm_offset; 653 /*!< The calculated range offset value */ 654 655 } VL53L1_offset_range_data_t; 656 657 658 /** 659 * @struct VL53L1_offset_range_results_t 660 * @brief Structure for storing the set of range results 661 * required for the offset calibration functions 662 * 663 */ 664 665 typedef struct { 666 667 int16_t cal_distance_mm; 668 /*!< the calibration distance in [mm]*/ 669 VL53L1_Error cal_status; 670 /*!< Calibration status, check for warning codes */ 671 uint8_t cal_report; 672 /*!< Stage for above cal status - 0 Pre, 1 = MM1, 2 = MM2 */ 673 uint8_t max_results; 674 /*!< Array size for histogram range data i.e. max number 675 of results */ 676 uint8_t active_results; 677 /*!< Number of active measurements */ 678 VL53L1_offset_range_data_t data[VL53L1_MAX_OFFSET_RANGE_RESULTS]; 679 /*!< Range results for each offset measurement */ 680 681 } VL53L1_offset_range_results_t; 682 683 /** 684 * @struct VL53L1_additional_offset_cal_data_t 685 * @brief Additional Offset Calibration Data 686 * 687 * Additional offset calibration data. Contains the rate 688 * and effective SPAD counts for the MM inner and outer 689 * calibration steps. 690 */ 691 692 typedef struct { 693 694 uint16_t result__mm_inner_actual_effective_spads; 695 /*!< MM Inner actual effective SPADs, 8.8 format */ 696 uint16_t result__mm_outer_actual_effective_spads; 697 /*!< MM Outer actual effective SPADs, 8.8 format */ 698 uint16_t result__mm_inner_peak_signal_count_rtn_mcps; 699 /*!< Mean value of MM Inner return peak rate in [Mcps], 9.7 format */ 700 uint16_t result__mm_outer_peak_signal_count_rtn_mcps; 701 /*!< Mean value of MM Outer return peak rate in [Mcps], 9.7 format */ 702 703 } VL53L1_additional_offset_cal_data_t; 704 705 706 /** 707 * @struct VL53L1_cal_peak_rate_map_t 708 * @brief Structure for storing the calibration peak rate map 709 * Used by DMAX to understand the spatial roll off 710 * in the signal rate map towards the corner of the 711 * SPAD array. 712 */ 713 714 typedef struct { 715 716 int16_t cal_distance_mm; 717 /*!< calibration distance in [mm], 14.2 format */ 718 uint16_t max_samples; 719 /*!< Array size for rate map i.e. max number samples */ 720 uint16_t width; 721 /*!< Array width */ 722 uint16_t height; 723 /*!< Array height */ 724 uint16_t peak_rate_mcps[VL53L1_NVM_PEAK_RATE_MAP_SAMPLES]; 725 /*!< Array of rate map samples */ 726 727 } VL53L1_cal_peak_rate_map_t; 728 729 730 /** 731 * @struct VL53L1_gain_calibration_data_t 732 * 733 * @brief Gain calibration data 734 * 735 */ 736 737 typedef struct { 738 739 uint16_t standard_ranging_gain_factor; 740 /*!< Standard ranging gain correction factor 1.11 format */ 741 742 } VL53L1_gain_calibration_data_t; 743 744 745 /** 746 * @struct VL53L1_ll_driver_state_t 747 * 748 * @brief Contains the driver state information 749 * 750 */ 751 752 typedef struct { 753 754 VL53L1_DeviceState cfg_device_state; 755 /*!< Configuration Device State */ 756 uint8_t cfg_stream_count; 757 /*!< configuration stream count, becomes expected 758 stream count for zone */ 759 uint8_t cfg_gph_id; 760 /*!< Config Grouped Parameter Hold ID */ 761 uint8_t cfg_timing_status; 762 /*!< Timing A or B flag 0 = A, 1 = B */ 763 764 VL53L1_DeviceState rd_device_state; 765 /*!< Read Device State */ 766 uint8_t rd_stream_count; 767 /*!< rd stream count, used to check actual stream count */ 768 uint8_t rd_gph_id; 769 /*!< Read Grouped Parameter Hold ID */ 770 uint8_t rd_timing_status; 771 /*!< Timing A or B flag 0 = A, 1 = B */ 772 773 } VL53L1_ll_driver_state_t; 774 775 /** @brief Run Offset Cal Function (offsetcal) Config 776 */ 777 778 typedef struct { 779 780 uint16_t dss_config__target_total_rate_mcps; 781 /*!< DSS Target rate in MCPS (9.7 format) used \ 782 * during run_offset_calibration() */ 783 uint32_t phasecal_config_timeout_us; 784 /*!< Phasecal timeout in us \ 785 * used during run_offset_calibration() */ 786 uint32_t range_config_timeout_us; 787 /*!< Range timeout in us used during \ 788 * run_offset_calibration() */ 789 uint32_t mm_config_timeout_us; 790 /*!< MM timeout in us used during \ 791 * run_offset_calibration() \ 792 * Added as part of Patch_AddedOffsetCalMMTuningParm_11791 */ 793 uint8_t pre_num_of_samples; 794 /*!< Number of Ranging samples used during \ 795 * run_offset_calibration() */ 796 uint8_t mm1_num_of_samples; 797 /*!< Number of MM1 samples used during \ 798 * run_offset_calibration() */ 799 uint8_t mm2_num_of_samples; 800 /*!< Number of MM2 samples used during \ 801 * run_offset_calibration() */ 802 803 } VL53L1_offsetcal_config_t; 804 805 806 807 /** 808 * @struct VL53L1_LLDriverData_t 809 * 810 * @brief VL53L1 LL Driver ST private data structure \n 811 * 812 */ 813 814 typedef struct { 815 816 uint8_t wait_method; 817 /*!< Wait type : blocking or non blocking */ 818 VL53L1_DevicePresetModes preset_mode; 819 /*!< Current preset mode */ 820 VL53L1_DeviceMeasurementModes measurement_mode; 821 /*!< Current measurement mode */ 822 VL53L1_OffsetCalibrationMode offset_calibration_mode; 823 /*!< Current offset calibration mode */ 824 VL53L1_OffsetCorrectionMode offset_correction_mode; 825 /*!< Current offset_ correction mode */ 826 uint32_t phasecal_config_timeout_us; 827 /*!< requested Phase Cal Timeout e.g. 1000us */ 828 uint32_t mm_config_timeout_us; 829 /*!< requested MM Timeout e.g. 2000us */ 830 uint32_t range_config_timeout_us; 831 /*!< requested Ranging Timeout e.g 13000us */ 832 uint32_t inter_measurement_period_ms; 833 /*!< requested Timing mode repeat period e.g 100ms */ 834 uint16_t dss_config__target_total_rate_mcps; 835 /*!< requested DSS Target Total Rate in 9.7 format e.g. 40.0Mcps 836 * - Patch_ChangingPresetModeInputParms_11780 */ 837 uint32_t fw_ready_poll_duration_ms; 838 /*!< FW ready poll duration in ms*/ 839 uint8_t fw_ready; 840 /*!< Result of FW ready check */ 841 uint8_t debug_mode; 842 /*!< Internal Only - read extra debug data */ 843 844 /*!< version info structure */ 845 VL53L1_ll_version_t version; 846 847 /*!< version info structure */ 848 VL53L1_ll_driver_state_t ll_state; 849 850 /*!< decoded GPIO interrupt config */ 851 VL53L1_GPIO_interrupt_config_t gpio_interrupt_config; 852 853 /*!< public register data structures */ 854 VL53L1_customer_nvm_managed_t customer; 855 VL53L1_cal_peak_rate_map_t cal_peak_rate_map; 856 VL53L1_additional_offset_cal_data_t add_off_cal_data; 857 VL53L1_gain_calibration_data_t gain_cal; 858 VL53L1_user_zone_t mm_roi; 859 VL53L1_optical_centre_t optical_centre; 860 861 /*!< tuning parameter storage */ 862 VL53L1_tuning_parm_storage_t tuning_parms; 863 864 /*!< private return good SPAD map */ 865 uint8_t rtn_good_spads[VL53L1_RTN_SPAD_BUFFER_SIZE]; 866 867 /*!< private internal configuration structures */ 868 VL53L1_refspadchar_config_t refspadchar; 869 VL53L1_ssc_config_t ssc_cfg; 870 VL53L1_xtalk_config_t xtalk_cfg; 871 VL53L1_offsetcal_config_t offsetcal_cfg; 872 873 /*!< private internal register data structures */ 874 VL53L1_static_nvm_managed_t stat_nvm; 875 VL53L1_static_config_t stat_cfg; 876 VL53L1_general_config_t gen_cfg; 877 VL53L1_timing_config_t tim_cfg; 878 VL53L1_dynamic_config_t dyn_cfg; 879 VL53L1_system_control_t sys_ctrl; 880 VL53L1_system_results_t sys_results; 881 VL53L1_nvm_copy_data_t nvm_copy_data; 882 883 /*!< Private Offset structure */ 884 VL53L1_offset_range_results_t offset_results; 885 886 /*!< private debug register data structures */ 887 VL53L1_core_results_t core_results; 888 VL53L1_debug_results_t dbg_results; 889 890 /* Start Patch_LowPowerAutoMode */ 891 /*!< Low Powr Auto Mode Data */ 892 VL53L1_low_power_auto_data_t low_power_auto_data; 893 /* End Patch_LowPowerAutoMode */ 894 895 #ifdef PAL_EXTENDED 896 /* Patch Debug Data */ 897 VL53L1_patch_results_t patch_results; 898 VL53L1_shadow_core_results_t shadow_core_results; 899 VL53L1_shadow_system_results_t shadow_sys_results; 900 VL53L1_prev_shadow_core_results_t prev_shadow_core_results; 901 VL53L1_prev_shadow_system_results_t prev_shadow_sys_results; 902 #endif 903 904 } VL53L1_LLDriverData_t; 905 906 907 /** 908 * @struct VL53L1_LLDriverResults_t 909 * 910 * @brief VL53L1 LL Driver ST private results structure 911 * 912 */ 913 914 typedef struct { 915 916 /* Private last range results */ 917 VL53L1_range_results_t range_results; 918 919 } VL53L1_LLDriverResults_t; 920 921 /** 922 * @struct VL53L1_calibration_data_t 923 * 924 * @brief Per Part calibration data 925 * 926 */ 927 928 typedef struct { 929 930 uint32_t struct_version; 931 VL53L1_customer_nvm_managed_t customer; 932 VL53L1_additional_offset_cal_data_t add_off_cal_data; 933 VL53L1_optical_centre_t optical_centre; 934 VL53L1_gain_calibration_data_t gain_cal; 935 VL53L1_cal_peak_rate_map_t cal_peak_rate_map; 936 937 } VL53L1_calibration_data_t; 938 939 940 /** 941 * @struct VL53L1_tuning_parameters_t 942 * 943 * @brief Tuning Parameters Debug data 944 * 945 */ 946 947 typedef struct { 948 uint16_t vl53l1_tuningparm_version; 949 uint16_t vl53l1_tuningparm_key_table_version; 950 uint16_t vl53l1_tuningparm_lld_version; 951 uint8_t vl53l1_tuningparm_consistency_lite_phase_tolerance; 952 uint8_t vl53l1_tuningparm_phasecal_target; 953 uint16_t vl53l1_tuningparm_lite_cal_repeat_rate; 954 uint16_t vl53l1_tuningparm_lite_ranging_gain_factor; 955 uint8_t vl53l1_tuningparm_lite_min_clip_mm; 956 uint16_t vl53l1_tuningparm_lite_long_sigma_thresh_mm; 957 uint16_t vl53l1_tuningparm_lite_med_sigma_thresh_mm; 958 uint16_t vl53l1_tuningparm_lite_short_sigma_thresh_mm; 959 uint16_t vl53l1_tuningparm_lite_long_min_count_rate_rtn_mcps; 960 uint16_t vl53l1_tuningparm_lite_med_min_count_rate_rtn_mcps; 961 uint16_t vl53l1_tuningparm_lite_short_min_count_rate_rtn_mcps; 962 uint8_t vl53l1_tuningparm_lite_sigma_est_pulse_width; 963 uint8_t vl53l1_tuningparm_lite_sigma_est_amb_width_ns; 964 uint8_t vl53l1_tuningparm_lite_sigma_ref_mm; 965 uint8_t vl53l1_tuningparm_lite_rit_mult; 966 uint8_t vl53l1_tuningparm_lite_seed_config; 967 uint8_t vl53l1_tuningparm_lite_quantifier; 968 uint8_t vl53l1_tuningparm_lite_first_order_select; 969 int16_t vl53l1_tuningparm_lite_xtalk_margin_kcps; 970 uint8_t vl53l1_tuningparm_initial_phase_rtn_lite_long_range; 971 uint8_t vl53l1_tuningparm_initial_phase_rtn_lite_med_range; 972 uint8_t vl53l1_tuningparm_initial_phase_rtn_lite_short_range; 973 uint8_t vl53l1_tuningparm_initial_phase_ref_lite_long_range; 974 uint8_t vl53l1_tuningparm_initial_phase_ref_lite_med_range; 975 uint8_t vl53l1_tuningparm_initial_phase_ref_lite_short_range; 976 uint8_t vl53l1_tuningparm_timed_seed_config; 977 uint8_t vl53l1_tuningparm_vhv_loopbound; 978 uint8_t vl53l1_tuningparm_refspadchar_device_test_mode; 979 uint8_t vl53l1_tuningparm_refspadchar_vcsel_period; 980 uint32_t vl53l1_tuningparm_refspadchar_phasecal_timeout_us; 981 uint16_t vl53l1_tuningparm_refspadchar_target_count_rate_mcps; 982 uint16_t vl53l1_tuningparm_refspadchar_min_countrate_limit_mcps; 983 uint16_t vl53l1_tuningparm_refspadchar_max_countrate_limit_mcps; 984 uint16_t vl53l1_tuningparm_offset_cal_dss_rate_mcps; 985 uint32_t vl53l1_tuningparm_offset_cal_phasecal_timeout_us; 986 uint32_t vl53l1_tuningparm_offset_cal_mm_timeout_us; 987 uint32_t vl53l1_tuningparm_offset_cal_range_timeout_us; 988 uint8_t vl53l1_tuningparm_offset_cal_pre_samples; 989 uint8_t vl53l1_tuningparm_offset_cal_mm1_samples; 990 uint8_t vl53l1_tuningparm_offset_cal_mm2_samples; 991 uint8_t vl53l1_tuningparm_spadmap_vcsel_period; 992 uint8_t vl53l1_tuningparm_spadmap_vcsel_start; 993 uint16_t vl53l1_tuningparm_spadmap_rate_limit_mcps; 994 uint16_t vl53l1_tuningparm_lite_dss_config_target_total_rate_mcps; 995 uint16_t vl53l1_tuningparm_timed_dss_config_target_total_rate_mcps; 996 uint32_t vl53l1_tuningparm_lite_phasecal_config_timeout_us; 997 uint32_t vl53l1_tuningparm_timed_phasecal_config_timeout_us; 998 uint32_t vl53l1_tuningparm_lite_mm_config_timeout_us; 999 uint32_t vl53l1_tuningparm_timed_mm_config_timeout_us; 1000 uint32_t vl53l1_tuningparm_lite_range_config_timeout_us; 1001 uint32_t vl53l1_tuningparm_timed_range_config_timeout_us; 1002 uint8_t vl53l1_tuningparm_lowpowerauto_vhv_loop_bound; 1003 uint32_t vl53l1_tuningparm_lowpowerauto_mm_config_timeout_us; 1004 uint32_t vl53l1_tuningparm_lowpowerauto_range_config_timeout_us; 1005 } VL53L1_tuning_parameters_t; 1006 1007 1008 /** 1009 * @struct VL53L1_spad_rate_data_t 1010 * @brief SPAD Rate Data output by SSC 1011 * 1012 * Container for the SPAD Rate data output by SPAD select check (SSC) 1013 * The data is stored in the buffer in SPAD number order and not 1014 * raster order 1015 * 1016 * Rate data is it either 1.15 or 9.7 fixed point format 1017 */ 1018 1019 typedef struct { 1020 1021 uint8_t spad_type; 1022 /*!< Type of rate data stored */ 1023 uint16_t buffer_size; 1024 /*!< SPAD buffer size : should be at least 256 for EwokPlus25 */ 1025 uint16_t rate_data[VL53L1_NO_OF_SPAD_ENABLES]; 1026 /*!< word buffer containing the SPAD rates */ 1027 uint16_t no_of_values; 1028 /*!< Number of bytes used in the buffer */ 1029 uint8_t fractional_bits; 1030 /*!< Number of fractional bits either 7 or 15 */ 1031 uint8_t error_status; 1032 /*!< Set if supplied buffer is too small */ 1033 1034 } VL53L1_spad_rate_data_t; 1035 1036 1037 /* Start Patch_AdditionalDebugData_11823 */ 1038 1039 /** 1040 * @struct VL53L1_additional_data_t 1041 * @brief Additional debug data 1042 * 1043 * Contains the LL Driver configuration information 1044 */ 1045 1046 typedef struct { 1047 1048 VL53L1_DevicePresetModes preset_mode; 1049 /*!< Current preset mode */ 1050 VL53L1_DeviceMeasurementModes measurement_mode; 1051 /*!< Current measurement mode */ 1052 1053 uint32_t phasecal_config_timeout_us; 1054 /*!< requested Phase Cal Timeout e.g. 1000us */ 1055 uint32_t mm_config_timeout_us; 1056 /*!< requested MM Timeout e.g. 2000us */ 1057 uint32_t range_config_timeout_us; 1058 /*!< requested Ranging Timeout e.g 13000us */ 1059 uint32_t inter_measurement_period_ms; 1060 /*!< requested Timing mode repeat period e.g 100ms */ 1061 uint16_t dss_config__target_total_rate_mcps; 1062 /*!< requested DSS Target Total Rate in 9.7 format e.g. 40.0Mcps*/ 1063 1064 } VL53L1_additional_data_t; 1065 1066 /* End Patch_AdditionalDebugData_11823 */ 1067 1068 1069 /** @} VL53L1_globalLLDriverDefine_group */ 1070 1071 1072 #define SUPPRESS_UNUSED_WARNING(x) \ 1073 ((void) (x)) 1074 1075 1076 #define IGNORE_STATUS(__FUNCTION_ID__, __ERROR_STATUS_CHECK__, __STATUS__) \ 1077 do { \ 1078 DISABLE_WARNINGS(); \ 1079 if (__FUNCTION_ID__) { \ 1080 if (__STATUS__ == __ERROR_STATUS_CHECK__) { \ 1081 __STATUS__ = VL53L1_ERROR_NONE; \ 1082 WARN_OVERRIDE_STATUS(__FUNCTION_ID__); \ 1083 } \ 1084 } \ 1085 ENABLE_WARNINGS(); \ 1086 } \ 1087 while (0) 1088 1089 #define VL53L1_COPYSTRING(str, ...) \ 1090 (strncpy(str, ##__VA_ARGS__, VL53L1_MAX_STRING_LENGTH-1)) 1091 1092 #ifdef __cplusplus 1093 } 1094 #endif 1095 1096 #endif /* _VL53L1_LL_DEF_H_ */ 1097 1098 1099
