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_api_core.h 65 * 66 * @brief EwokPlus25 low level API function definitions 67 */ 68 69 #ifndef _VL53L1_API_CORE_H_ 70 #define _VL53L1_API_CORE_H_ 71 72 #include "vl53l1_platform.h" 73 74 #ifdef __cplusplus 75 extern "C" { 76 #endif 77 78 79 /** 80 * @brief Get LL Driver version information 81 * 82 * @param[in] Dev : Device handle 83 * @param[out] pversion : pointer to VL53L1_ll_version_t 84 * 85 * @return VL53L1_ERROR_NONE Success 86 */ 87 88 #ifdef VL53L1_DEBUG 89 VL53L1_Error VL53L1_get_version( 90 VL53L1_DEV Dev, 91 VL53L1_ll_version_t *pversion); 92 93 /** 94 * @brief Gets Device Firmware version 95 * 96 * @param[in] Dev : Device handle 97 * @param[out] pfw_version : pointer to uint16_t FW version 98 * 99 * @return VL53L1_ERROR_NONE Success 100 */ 101 102 VL53L1_Error VL53L1_get_device_firmware_version( 103 VL53L1_DEV Dev, 104 uint16_t *pfw_version); 105 #endif 106 107 108 /** 109 * @brief Initialises pdev structure and optionally read the 110 * part to part information form he device G02 registers 111 * 112 * Important: VL53L1_platform_initialise() *must* called before calling 113 * this function 114 * 115 * @param[in] Dev : Device handle 116 * @param[out] read_p2p_data : if > 0 then reads and caches P2P data 117 * 118 * @return VL53L1_ERROR_NONE Success 119 */ 120 121 VL53L1_Error VL53L1_data_init( 122 VL53L1_DEV Dev, 123 uint8_t read_p2p_data); 124 125 126 /** 127 * @brief For C-API one time initialization only reads device 128 * G02 registers containing data copied from NVM 129 * 130 * Contains the key NVM data e.g identification info 131 * fast oscillator freq, max trim and laser safety info 132 * 133 * Function all only be called after the device has finished booting 134 * 135 * @param[in] Dev : Device handle 136 * 137 * @return VL53L1_ERROR_NONE Success 138 */ 139 140 VL53L1_Error VL53L1_read_p2p_data( 141 VL53L1_DEV Dev); 142 143 144 /** 145 * @brief Performs device software reset and then waits for the firmware 146 * to finish booting 147 * 148 * @param[in] Dev : Device handle 149 * 150 * @return VL53L1_ERROR_NONE Success 151 * @return "Other error code" See ::VL53L1_Error 152 */ 153 154 VL53L1_Error VL53L1_software_reset( 155 VL53L1_DEV Dev); 156 157 158 /** 159 * @brief Sets the customer part to part data 160 * 161 * Important: does **not** apply the settings to the device. 162 * Updates the following structures in the device structure 163 * 164 * Just an internal memcpy to 165 * 166 * 167 * @param[in] Dev : Device handle 168 * @param[in] pcal_data : pointer to VL53L1_calibration_data_t 169 * 170 * @return VL53L1_ERROR_NONE Success 171 * @return "Other error code" See ::VL53L1_Error 172 */ 173 174 VL53L1_Error VL53L1_set_part_to_part_data( 175 VL53L1_DEV Dev, 176 VL53L1_calibration_data_t *pcal_data); 177 178 179 /** 180 * @brief Gets the customer part to part data 181 * 182 * Just an internal memory copy 183 * 184 * @param[in] Dev : Device handle 185 * @param[out] pcal_data : pointer to VL53L1_calibration_data_t 186 * 187 * 188 * @return VL53L1_ERROR_NONE Success 189 * @return "Other error code" See ::VL53L1_Error 190 */ 191 192 VL53L1_Error VL53L1_get_part_to_part_data( 193 VL53L1_DEV Dev, 194 VL53L1_calibration_data_t *pcal_data); 195 196 197 /** 198 * @brief Gets the tuning parm part to part data 199 * 200 * Just an internal copy 201 * 202 * @param[in] Dev : Device handle 203 * @param[out] ptun_data : pointer to VL53L1_tuning_parameters_t 204 * 205 * 206 * @return VL53L1_ERROR_NONE Success 207 * @return "Other error code" See ::VL53L1_Error 208 */ 209 210 #ifdef VL53L1_DEBUG 211 VL53L1_Error VL53L1_get_tuning_debug_data( 212 VL53L1_DEV Dev, 213 VL53L1_tuning_parameters_t *ptun_data); 214 #endif 215 216 217 /** 218 * @brief Sets the inter measurement period in the VL53L1_timing_config_t structure 219 * 220 * Uses the pdev->dbg_results.result__osc_calibrate_val value convert from [ms] 221 * 222 * @param[in] Dev : Device handle 223 * @param[in] inter_measurement_period_ms : requested inter measurement period in [ms] 224 * 225 * @return VL53L1_ERROR_NONE Success 226 * @return "Other error code" See ::VL53L1_Error 227 */ 228 229 VL53L1_Error VL53L1_set_inter_measurement_period_ms( 230 VL53L1_DEV Dev, 231 uint32_t inter_measurement_period_ms); 232 233 234 /** 235 * @brief Gets inter measurement period from the VL53L1_timing_config_t structure 236 * 237 * Uses the pdev->dbg_results.result__osc_calibrate_val value convert into [ms] 238 * 239 * @param[in] Dev : Device handle 240 * @param[out] pinter_measurement_period_ms : current inter measurement period in [ms] 241 * 242 * @return VL53L1_ERROR_NONE Success 243 * @return "Other error code" See ::VL53L1_Error 244 */ 245 246 VL53L1_Error VL53L1_get_inter_measurement_period_ms( 247 VL53L1_DEV Dev, 248 uint32_t *pinter_measurement_period_ms); 249 250 251 /** 252 * @brief Sets the phasecal, mode mitigation and ranging timeouts 253 * in the VL53L1_timing_config_t structure 254 * 255 * Uses the pdev->stat_nvm.osc_measured__fast_osc__frequency value convert from [us] 256 * 257 * @param[in] Dev : Device handle 258 * @param[in] phasecal_config_timeout_us : requested Phase Cal Timeout e.g. 1000us 259 * @param[in] mm_config_timeout_us : requested MM Timeout e.g. 2000us 260 * @param[in] range_config_timeout_us : requested Ranging Timeout e.g 13000us 261 * 262 * @return VL53L1_ERROR_NONE Success 263 * @return "Other error code" See ::VL53L1_Error 264 */ 265 266 VL53L1_Error VL53L1_set_timeouts_us( 267 VL53L1_DEV Dev, 268 uint32_t phasecal_config_timeout_us, 269 uint32_t mm_config_timeout_us, 270 uint32_t range_config_timeout_us); 271 272 273 /** 274 * @brief Gets the phasecal, mode mitigation and ranging timeouts 275 * for the VL53L1_timing_config_t structure 276 * 277 * Uses the pdev->stat_nvm.osc_measured__fast_osc__frequency convert into [us] 278 * 279 * @param[in] Dev : Device handle 280 * @param[out] pphasecal_config_timeout_us : current Phase Cal Timeout in [us] 281 * @param[out] pmm_config_timeout_us : current MM Timeout in [us] 282 * @param[out] prange_config_timeout_us : current Ranging Timeout in [us] 283 * 284 * @return VL53L1_ERROR_NONE Success 285 * @return "Other error code" See ::VL53L1_Error 286 */ 287 288 VL53L1_Error VL53L1_get_timeouts_us( 289 VL53L1_DEV Dev, 290 uint32_t *pphasecal_config_timeout_us, 291 uint32_t *pmm_config_timeout_us, 292 uint32_t *prange_config_timeout_us); 293 294 295 /** 296 * @brief Sets the 12-bit calibration repeat period value 297 * 298 * Sets the repeat period for VHV and phasecal in ranges. 299 * Setting to zero to disables the repeat, but the VHV 300 * and PhaseCal is still run on the very first range in 301 * this case. 302 * 303 * Only even values should be set 304 * 305 * The max value is 4094 i.e. every 306 * 307 * @param[in] Dev : Device handle 308 * @param[in] cal_config__repeat_period : current calibration config repeat period 309 * 310 * @return VL53L1_ERROR_NONE Success 311 * @return "Other error code" See ::VL53L1_Error 312 */ 313 314 VL53L1_Error VL53L1_set_calibration_repeat_period( 315 VL53L1_DEV Dev, 316 uint16_t cal_config__repeat_period); 317 318 319 /** 320 * @brief Gets the current 12-bit calibration repeat period value 321 * 322 * @param[in] Dev : Device handle 323 * @param[out] pcal_config__repeat_period : current calibration config repeat period 324 * 325 * @return VL53L1_ERROR_NONE Success 326 * @return "Other error code" See ::VL53L1_Error 327 */ 328 329 VL53L1_Error VL53L1_get_calibration_repeat_period( 330 VL53L1_DEV Dev, 331 uint16_t *pcal_config__repeat_period); 332 333 334 /** 335 * @brief Set system sequence config bit value 336 * 337 * @param[in] Dev : Device handle 338 * @param[in] bit_id : VL53L1_DeviceSequenceConfig bit id 339 * @param[in] value : Input Bit value = 0 or 1 340 * 341 * @return VL53L1_ERROR_NONE Success 342 * @return "Other error code" See ::VL53L1_Error 343 */ 344 345 VL53L1_Error VL53L1_set_sequence_config_bit( 346 VL53L1_DEV Dev, 347 VL53L1_DeviceSequenceConfig bit_id, 348 uint8_t value); 349 350 351 /** 352 * @brief Get system sequence config bit value 353 * 354 * @param[in] Dev : Device handle 355 * @param[in] bit_id : VL53L1_DeviceSequenceConfig bit id 356 * @param[out] pvalue : Output Bit value = 0 or 1 357 * 358 * @return VL53L1_ERROR_NONE Success 359 * @return "Other error code" See ::VL53L1_Error 360 */ 361 362 VL53L1_Error VL53L1_get_sequence_config_bit( 363 VL53L1_DEV Dev, 364 VL53L1_DeviceSequenceConfig bit_id, 365 uint8_t *pvalue); 366 367 368 /** 369 * @brief Set the interrupt polarity bit in 370 * 371 * @param[in] Dev : Device handle 372 * @param[in] interrupt_polarity : Interrupt Polarity 373 * 374 * @return VL53L1_ERROR_NONE Success 375 * @return "Other error code" See ::VL53L1_Error 376 */ 377 378 VL53L1_Error VL53L1_set_interrupt_polarity( 379 VL53L1_DEV Dev, 380 VL53L1_DeviceInterruptPolarity interrupt_polarity); 381 382 383 /** 384 * @brief Get the interrupt polarity bit state 385 * 386 * @param[in] Dev : Device handle 387 * @param[out] pinterrupt_polarity : Interrupt Polarity Bit value 388 * 389 * @return VL53L1_ERROR_NONE Success 390 * @return "Other error code" See ::VL53L1_Error 391 */ 392 393 VL53L1_Error VL53L1_get_interrupt_polarity( 394 VL53L1_DEV Dev, 395 VL53L1_DeviceInterruptPolarity *pinterrupt_polarity); 396 397 /** 398 * @brief Set the Ref spad char cfg struct internal to pdev 399 * 400 * @param[in] Dev : Device handle 401 * @param[in] pdata : Input pointer to VL53L1_refspadchar_config_t 402 * 403 * @return VL53L1_ERROR_NONE Success 404 * @return "Other error code" See ::VL53L1_Error 405 */ 406 407 #ifndef VL53L1_NOCALIB 408 VL53L1_Error VL53L1_get_refspadchar_config_struct( 409 VL53L1_DEV Dev, 410 VL53L1_refspadchar_config_t *pdata); 411 #endif 412 413 /** 414 * @brief Extract the Ref spad char cfg struct from pdev 415 * 416 * @param[in] Dev : Device handle 417 * @param[out] pdata : Output pointer to VL53L1_refspadchar_config_t 418 * 419 * @return VL53L1_ERROR_NONE Success 420 * @return "Other error code" See ::VL53L1_Error 421 */ 422 423 #ifndef VL53L1_NOCALIB 424 VL53L1_Error VL53L1_set_refspadchar_config_struct( 425 VL53L1_DEV Dev, 426 VL53L1_refspadchar_config_t *pdata); 427 #endif 428 429 /** 430 * @brief Set the Range Ignore Threshold Rate value 431 * 432 * @param[in] Dev : Device handle 433 * @param[in] range_ignore_thresh_mult : Input RIT Mult value, in \ 434 * 3.5 fractional value 435 * @param[in] range_ignore_threshold_mcps : Range Ignore Threshold value 436 * 437 * @return VL53L1_ERROR_NONE Success 438 * @return "Other error code" See ::VL53L1_Error 439 */ 440 441 VL53L1_Error VL53L1_set_range_ignore_threshold( 442 VL53L1_DEV Dev, 443 uint8_t range_ignore_thresh_mult, 444 uint16_t range_ignore_threshold_mcps); 445 446 /** 447 * @brief Get the Range Ignore Threshold Rate value 448 * 449 * 450 * 451 * @param[in] Dev : Device handle 452 * @param[out] prange_ignore_thresh_mult : \ 453 * Range ignore threshold internal multiplier value in \ 454 * 3.5 fractional format. 455 * @param[out] prange_ignore_threshold_mcps_internal : \ 456 * Range Ignore Threshold Rate value generated from \ 457 * current xtalk parms 458 * @param[out] prange_ignore_threshold_mcps_current : \ 459 * Range Ignore Threshold Rate value generated from \ 460 * device static config struct 461 * 462 * @return VL53L1_ERROR_NONE Success 463 * @return "Other error code" See ::VL53L1_Error 464 */ 465 466 VL53L1_Error VL53L1_get_range_ignore_threshold( 467 VL53L1_DEV Dev, 468 uint8_t *prange_ignore_thresh_mult, 469 uint16_t *prange_ignore_threshold_mcps_internal, 470 uint16_t *prange_ignore_threshold_mcps_current); 471 472 473 /** 474 * @brief Sets the current user Zone (ROI) configuration structure data 475 * 476 * @param[in] Dev : Device handle 477 * @param[in] puser_zone : pointer to user Zone (ROI) data structure 478 * 479 * @return VL53L1_ERROR_NONE Success 480 * @return "Other error code" See ::VL53L1_Error 481 */ 482 483 VL53L1_Error VL53L1_set_user_zone( 484 VL53L1_DEV Dev, 485 VL53L1_user_zone_t *puser_zone); 486 487 488 /** 489 * @brief Gets the current user zone (ROI) configuration structure data 490 * 491 * @param[in] Dev : Device handle 492 * @param[out] puser_zone : pointer to user zone (ROI) data structure 493 * 494 * @return VL53L1_ERROR_NONE Success 495 * @return "Other error code" See ::VL53L1_Error 496 */ 497 498 VL53L1_Error VL53L1_get_user_zone( 499 VL53L1_DEV Dev, 500 VL53L1_user_zone_t *puser_zone); 501 502 503 /** 504 * @brief Gets the current mode mitigation zone (ROI) configuration structure data 505 * 506 * @param[in] Dev : Device handle 507 * @param[out] pmm_roi : pointer to user zone (ROI) data structure 508 * 509 * @return VL53L1_ERROR_NONE Success 510 * @return "Other error code" See ::VL53L1_Error 511 */ 512 513 VL53L1_Error VL53L1_get_mode_mitigation_roi( 514 VL53L1_DEV Dev, 515 VL53L1_user_zone_t *pmm_roi); 516 517 518 /** 519 * @brief Initialises the configuration data structures for 520 * the selected preset mode 521 * 522 * Important: does **not** apply the settings to the device. 523 * Updates the following structures in the device structure 524 * 525 * - static config : pdev->stat_cfg 526 * - dynamic config : pdev->dyn_cfg 527 * - system_control :pdev->sys_ctrl 528 * 529 * Uses osc_measured__fast_osc__frequency in pdev->stat_nvm to 530 * convert the input timeouts in [us] to internal macro period 531 * timeout values. 532 * 533 * Please call VL53L1_init_and_start_range() to update device 534 * and start a range 535 * 536 * @param[in] Dev : Device handle 537 * @param[in] device_preset_mode : selected device preset mode 538 * @param[in] dss_config__target_total_rate_mcps : DSS target rate in 9.7 format e.g 0x0A00 -> 20.0 Mcps 539 * @param[in] phasecal_config_timeout_us : requested Phase Cal Timeout e.g. 1000us 540 * @param[in] mm_config_timeout_us : requested MM Timeout e.g. 2000us 541 * @param[in] range_config_timeout_us : requested Ranging Timeout e.g 10000us 542 * @param[in] inter_measurement_period_ms : requested timed mode repeat rate e.g 100ms 543 * 544 * @return VL53L1_ERROR_NONE Success 545 * @return "Other error code" See ::VL53L1_Error 546 */ 547 548 VL53L1_Error VL53L1_set_preset_mode( 549 VL53L1_DEV Dev, 550 VL53L1_DevicePresetModes device_preset_mode, 551 uint16_t dss_config__target_total_rate_mcps, 552 uint32_t phasecal_config_timeout_us, 553 uint32_t mm_config_timeout_us, 554 uint32_t range_config_timeout_us, 555 uint32_t inter_measurement_period_ms); 556 557 558 /** 559 * @brief Gets the requested preset mode configuration tuning parameters 560 * 561 * Function Added as part of Patch_TuningParmPresetModeAddition_11839 562 * 563 * @param[in] Dev : Device Handle 564 * @param[in] device_preset_mode : selected device preset mode 565 * @param[out] pdss_config__target_total_rate_mcps : dss rate output value 566 * @param[out] pphasecal_config_timeout_us : phasecal timeout output value 567 * @param[out] pmm_config_timeout_us : mm timeout output value 568 * @param[out] prange_config_timeout_us : range timeout output value 569 * 570 * @return VL53L1_ERROR_NONE Success 571 * @return "Other error code" See ::VL53L1_Error 572 */ 573 574 VL53L1_Error VL53L1_get_preset_mode_timing_cfg( 575 VL53L1_DEV Dev, 576 VL53L1_DevicePresetModes device_preset_mode, 577 uint16_t *pdss_config__target_total_rate_mcps, 578 uint32_t *pphasecal_config_timeout_us, 579 uint32_t *pmm_config_timeout_us, 580 uint32_t *prange_config_timeout_us); 581 582 /** 583 * @brief Simple function to enable xtalk compensation 584 * 585 * Applies xtalk compensation to hist post processing, 586 * and applies settings to device, 587 * 588 * @param[in] Dev : Device Handle 589 * 590 * @return VL53L1_ERROR_NONE Success 591 * @return "Other error code" See ::VL53L1_Error 592 */ 593 594 VL53L1_Error VL53L1_enable_xtalk_compensation( 595 VL53L1_DEV Dev); 596 597 /** 598 * @brief Simple function to disable xtalk compensation 599 * 600 * Disables xtalk compensation from hist post processing, 601 * and clears settings to device 602 * 603 * @param[in] Dev : Device Handle 604 * 605 * @return VL53L1_ERROR_NONE Success 606 * @return "Other error code" See ::VL53L1_Error 607 */ 608 609 VL53L1_Error VL53L1_disable_xtalk_compensation( 610 VL53L1_DEV Dev); 611 612 613 /** 614 * @brief Simple function to retrieve xtalk compensation 615 * status 616 * 617 * @param[in] Dev : Device Handle 618 * @param[out] pcrosstalk_compensation_enable : pointer to \ 619 * uint8 type, returns crosstalk compensation status \ 620 * where 0 means disabled and 1 means enabled. 621 * 622 */ 623 624 void VL53L1_get_xtalk_compensation_enable( 625 VL53L1_DEV Dev, 626 uint8_t *pcrosstalk_compensation_enable); 627 628 /** 629 * @brief Builds and sends the I2C buffer to initialize the device 630 * and start a range measurement 631 * 632 * The device_config_level input controls the level of initialization 633 * applied to the device 634 * 635 * - System control only 636 * - Dynamic Onwards 637 * - dynamic_config and system_control 638 * - Static Onwards 639 * - static_config, dynamic_config & system_control 640 * - software standby mode only 641 * - Customer Onwards 642 * - customer_nvm_managed, static_config, dynamic_config & system_control 643 * - software standby mode only 644 * - Full 645 * - static_nvm_managed, customer_nvm_managed, static_config, dynamic_config & system_control 646 * - software standby mode only 647 * 648 * The system_control register group is always written as the last 649 * register of this group SYSTEM__MODE_START decides what happens next ... 650 * 651 * @param[in] Dev : Device handle 652 * @param[in] measurement_mode : Options: \n 653 * VL53L1_DEVICEMEASUREMENTMODE_STOP \n 654 * VL53L1_DEVICEMEASUREMENTMODE_SINGLESHOT \n 655 * VL53L1_DEVICEMEASUREMENTMODE_BACKTOBACK \n 656 * VL53L1_DEVICEMEASUREMENTMODE_TIMED 657 * @param[in] device_config_level : Options: \n 658 * VL53L1_DEVICECONFIGLEVEL_SYSTEM_CONTROL \n 659 * VL53L1_DEVICECONFIGLEVEL_DYNAMIC_ONWARDS \n 660 * VL53L1_DEVICECONFIGLEVEL_TIMING_ONWARDS \n 661 * VL53L1_DEVICECONFIGLEVEL_STATIC_ONWARDS \n 662 * VL53L1_DEVICECONFIGLEVEL_CUSTOMER_ONWARDS \n 663 * VL53L1_DEVICECONFIGLEVEL_FULL 664 * 665 * The system_control register group is always written as the last 666 * register of this group SYSTEM__MODE_START decides what happens next .. 667 * @return VL53L1_ERROR_NONE Success 668 * @return "Other error code" See ::VL53L1_Error 669 */ 670 671 VL53L1_Error VL53L1_init_and_start_range( 672 VL53L1_DEV Dev, 673 uint8_t measurement_mode, 674 VL53L1_DeviceConfigLevel device_config_level); 675 676 677 /** 678 * @brief Sends an abort command to stop the in progress range. 679 * Also clears all of the measurement mode bits. 680 * 681 * @param[in] Dev : Device handle 682 * 683 * @return VL53L1_ERROR_NONE Success 684 * @return "Other error code" See ::VL53L1_Error 685 */ 686 687 VL53L1_Error VL53L1_stop_range( 688 VL53L1_DEV Dev); 689 690 691 /** 692 * @brief Get range measurement result data 693 * 694 * Reads the required number of registers as single multi byte read 695 * transaction and decodes the data into the data structures 696 * 697 * range_result_level controls which result data is read back from the 698 * device 699 * 700 * - Full 701 * - both system and core results are read back 702 * - System Results 703 * - only system results are read back 704 * - only the system_results structure is updated in this case 705 * 706 * @param[in] Dev : Device Handle 707 * @param[in] device_result_level : Options: \n 708 * VL53L1_DEVICERESULTSLEVEL_FULL \n 709 * VL53L1_DEVICERESULTSLEVEL_UPTO_CORE \n 710 * VL53L1_DEVICERESULTSLEVEL_SYSTEM_RESULTS 711 * 712 * @return VL53L1_ERROR_NONE Success 713 * @return "Other error code" See ::VL53L1_Error 714 */ 715 716 VL53L1_Error VL53L1_get_measurement_results( 717 VL53L1_DEV Dev, 718 VL53L1_DeviceResultsLevel device_result_level); 719 720 721 /** 722 * @brief Get device system results, updates GPH registers and 723 * clears interrupt and configures SYSTEM__MODE_START 724 * based on the input measurement mode 725 * 726 * Internally uses the following functions: 727 * 728 * - VL53L1_get_measurement_results() 729 * - VLS3L1_init_and_start_range() 730 * 731 * The system_control register group is always written as the last 732 * register of this group SYSTEM__MODE_START decides what happens next ... 733 * 734 * @param[in] Dev : Device Handle 735 * @param[in] device_result_level : Options: \n 736 * VL53L1_DEVICERESULTSLEVEL_FULL \n 737 * VL53L1_DEVICERESULTSLEVEL_UPTO_CORE \n 738 * VL53L1_DEVICERESULTSLEVEL_SYSTEM_RESULTS 739 * @param[out] prange_results : pointer to VL53L1_range_results_t 740 741 * 742 * @return VL53L1_ERROR_NONE Success 743 * @return "Other error code" See ::VL53L1_Error 744 */ 745 746 VL53L1_Error VL53L1_get_device_results( 747 VL53L1_DEV Dev, 748 VL53L1_DeviceResultsLevel device_result_level, 749 VL53L1_range_results_t *prange_results); 750 751 752 /** 753 * @brief Sends the ranging handshake to clear the interrupt 754 * allow the device to move onto the next range 755 * 756 * updates GPH registers and clears interrupt and configures 757 * SYSTEM__MODE_START register based on the input measurement mode 758 * 759 * Internally uses the following functions: 760 * 761 * - VLS3L1_init_and_start_range() 762 * 763 * The system_control register group is always written as the last 764 * register of this group SYSTEM__MODE_START decides what happens next ... 765 * 766 * @param[in] Dev : Device Handle 767 * @param[in] measurement_mode : Options: \n 768 * VL53L1_DEVICEMEASUREMENTMODE_STOP \n 769 * VL53L1_DEVICEMEASUREMENTMODE_SINGLESHOT \n 770 * VL53L1_DEVICEMEASUREMENTMODE_BACKTOBACK \n 771 * VL53L1_DEVICEMEASUREMENTMODE_TIMED 772 * 773 * @return VL53L1_ERROR_NONE Success 774 * @return "Other error code" See ::VL53L1_Error 775 */ 776 777 VL53L1_Error VL53L1_clear_interrupt_and_enable_next_range( 778 VL53L1_DEV Dev, 779 uint8_t measurement_mode); 780 781 782 /** 783 * @brief Copies system and core results to range results data structure 784 * 785 * @param[in] gain_factor : gain correction factor 1.11 format 786 * @param[in] psys : pointer to VL53L1_system_results_t 787 * @param[in] pcore : pointer to VL53L1_core_results_t 788 * @param[out] presults : pointer to VL53L1_range_results_t 789 */ 790 791 void VL53L1_copy_sys_and_core_results_to_range_results( 792 int32_t gain_factor, 793 VL53L1_system_results_t *psys, 794 VL53L1_core_results_t *pcore, 795 VL53L1_range_results_t *presults); 796 797 /** 798 * @brief Configure the GPIO interrupt config, from the given input 799 * 800 * @param[in] Dev : Device Handle 801 * @param[in] intr_mode_distance : distance interrupt mode 802 * @param[in] intr_mode_rate : rate interrupt mode 803 * @param[in] intr_new_measure_ready : trigger when new interrupt ready 804 * @param[in] intr_no_target : trigger when no target found 805 * @param[in] intr_combined_mode : switch on combined mode 806 * @param[in] thresh_distance_high : High distance threshold in mm 807 * @param[in] thresh_distance_low : Low distance threshold in mm 808 * @param[in] thresh_rate_high : High rate threshold in 9.7 Mcps 809 * @param[in] thresh_rate_low : Low rate threshold in 9.7 Mcps 810 */ 811 812 VL53L1_Error VL53L1_set_GPIO_interrupt_config( 813 VL53L1_DEV Dev, 814 VL53L1_GPIO_Interrupt_Mode intr_mode_distance, 815 VL53L1_GPIO_Interrupt_Mode intr_mode_rate, 816 uint8_t intr_new_measure_ready, 817 uint8_t intr_no_target, 818 uint8_t intr_combined_mode, 819 uint16_t thresh_distance_high, 820 uint16_t thresh_distance_low, 821 uint16_t thresh_rate_high, 822 uint16_t thresh_rate_low 823 ); 824 825 /** 826 * @brief Configure the GPIO interrupt config, from the given structure 827 * 828 * @param[in] Dev : Device Handle 829 * @param[in] intconf : input structure (note, not a pointer) 830 */ 831 832 VL53L1_Error VL53L1_set_GPIO_interrupt_config_struct( 833 VL53L1_DEV Dev, 834 VL53L1_GPIO_interrupt_config_t intconf); 835 836 /** 837 * @brief Retrieves the GPIO interrupt config structure currently programmed 838 * into the API 839 * 840 * @param[in] Dev : Device Handle 841 * @param[out] pintconf : output pointer to structure (note, pointer) 842 */ 843 844 VL53L1_Error VL53L1_get_GPIO_interrupt_config( 845 VL53L1_DEV Dev, 846 VL53L1_GPIO_interrupt_config_t *pintconf); 847 848 /** 849 * @brief Set function for offset calibration mode 850 * 851 * @param[in] Dev : Device Handle 852 * @param[in] offset_cal_mode : input calibration mode 853 * 854 * @return VL53L1_ERROR_NONE Success 855 * @return "Other error code" See ::VL53L1_Error 856 */ 857 858 VL53L1_Error VL53L1_set_offset_calibration_mode( 859 VL53L1_DEV Dev, 860 VL53L1_OffsetCalibrationMode offset_cal_mode); 861 862 863 /** 864 * @brief Get function for offset calibration mode 865 * 866 * @param[in] Dev : Device Handle 867 * @param[out] poffset_cal_mode : output pointer for calibration mode 868 * 869 * @return VL53L1_ERROR_NONE Success 870 * @return "Other error code" See ::VL53L1_Error 871 */ 872 873 VL53L1_Error VL53L1_get_offset_calibration_mode( 874 VL53L1_DEV Dev, 875 VL53L1_OffsetCalibrationMode *poffset_cal_mode); 876 877 878 /** 879 * @brief Set function for offset correction mode 880 * 881 * @param[in] Dev : Device Handle 882 * @param[in] offset_cor_mode : input correction mode 883 * 884 * @return VL53L1_ERROR_NONE Success 885 * @return "Other error code" See ::VL53L1_Error 886 */ 887 888 VL53L1_Error VL53L1_set_offset_correction_mode( 889 VL53L1_DEV Dev, 890 VL53L1_OffsetCalibrationMode offset_cor_mode); 891 892 893 /** 894 * @brief Get function for offset correction mode 895 * 896 * @param[in] Dev : Device Handle 897 * @param[out] poffset_cor_mode : output pointer for correction mode 898 * 899 * @return VL53L1_ERROR_NONE Success 900 * @return "Other error code" See ::VL53L1_Error 901 */ 902 903 VL53L1_Error VL53L1_get_offset_correction_mode( 904 VL53L1_DEV Dev, 905 VL53L1_OffsetCorrectionMode *poffset_cor_mode); 906 907 /** 908 * @brief Get function for Xtalk Margin setting 909 * Histogram Mode version 910 * 911 * @param[in] Dev : Device Handle 912 * @param[out] pxtalk_margin : output pointer for int16_t xtalk_margin factor \ 913 * in fixed point 7.9 Kcps. 914 * 915 * @return VL53L1_ERROR_NONE Success 916 * @return "Other error code" See ::VL53L1_Error 917 */ 918 919 VL53L1_Error VL53L1_get_lite_xtalk_margin_kcps( 920 VL53L1_DEV Dev, 921 int16_t *pxtalk_margin); 922 923 /** 924 * @brief Set function for Xtalk Margin setting 925 * Histogram Mode version 926 * 927 * @param[in] Dev : Device Handle 928 * @param[in] xtalk_margin : Input int16_t xtalk_margin factor \ 929 * in fixed point 7.9 Kcps. 930 * 931 * @return VL53L1_ERROR_NONE Success 932 * @return "Other error code" See ::VL53L1_Error 933 */ 934 935 VL53L1_Error VL53L1_set_lite_xtalk_margin_kcps( 936 VL53L1_DEV Dev, 937 int16_t xtalk_margin); 938 939 /** 940 * @brief Get function for Lite Mode Minimum Count Rate 941 * parameter, used to filter and validate ranges based on 942 * signal rate 943 * 944 * Note: the min count rate value is overwritten when setting preset 945 * modes, and should only be altered after preset mode has been 946 * selected when running Lite Mode. 947 * 948 * @param[in] Dev : Device Handle 949 * @param[out] plite_mincountrate : Output pointer for uint16_t min count rate\ 950 * in fixed point 9.7 Mcps 951 * 952 * @return VL53L1_ERROR_NONE Success 953 * @return "Other error code" See ::VL53L1_Error 954 */ 955 956 VL53L1_Error VL53L1_get_lite_min_count_rate( 957 VL53L1_DEV Dev, 958 uint16_t *plite_mincountrate); 959 960 961 /** 962 * @brief Set function for Lite Mode Minimum Count Rate 963 * parameter, used to filter and validate ranges based on 964 * signal rate 965 * 966 * Note: the min count rate value is overwritten when setting preset 967 * modes, and should only be altered after preset mode has been 968 * selected when running Lite Mode. 969 * 970 * @param[in] Dev : Device Handle 971 * @param[in] lite_mincountrate : Input uint16_t min count rate 972 * in fixed point 9.7 Mcps 973 * 974 * @return VL53L1_ERROR_NONE Success 975 * @return "Other error code" See ::VL53L1_Error 976 */ 977 978 VL53L1_Error VL53L1_set_lite_min_count_rate( 979 VL53L1_DEV Dev, 980 uint16_t lite_mincountrate); 981 982 983 /** 984 * @brief Get function for Lite Mode Max Sigma Threshold 985 * parameter, used to filter and validate ranges based on 986 * estimated sigma level 987 * 988 * Note: the sigma thresh value is overwritten when setting preset 989 * modes, and should only be altered after preset mode has been 990 * selected when running Lite Mode. 991 * 992 * @param[in] Dev : Device Handle 993 * @param[out] plite_sigma : Output pointer for uint16_t sigma thresh\ 994 * in fixed point 14.2 mm 995 * 996 * @return VL53L1_ERROR_NONE Success 997 * @return "Other error code" See ::VL53L1_Error 998 */ 999 1000 1001 VL53L1_Error VL53L1_get_lite_sigma_threshold( 1002 VL53L1_DEV Dev, 1003 uint16_t *plite_sigma); 1004 1005 1006 /** 1007 * @brief Set function for Lite Mode Max Sigma Threshold 1008 * parameter, used to filter and validate ranges based on 1009 * estimated sigma level 1010 * 1011 * Note: the sigma thresh value is overwritten when setting preset 1012 * modes, and should only be altered after preset mode has been 1013 * selected when running Lite Mode. 1014 * 1015 * @param[in] Dev : Device Handle 1016 * @param[in] lite_sigma : Input uint16_t sigma thresh\ 1017 * in fixed point 14.2 mm 1018 * 1019 * @return VL53L1_ERROR_NONE Success 1020 * @return "Other error code" See ::VL53L1_Error 1021 */ 1022 1023 VL53L1_Error VL53L1_set_lite_sigma_threshold( 1024 VL53L1_DEV Dev, 1025 uint16_t lite_sigma); 1026 1027 1028 /** 1029 * @brief Function to restore the plane_offset, x gradient and y gradient 1030 * values to original NVM values. 1031 * 1032 * This function does not recalculate all xtalk parms derived from the 1033 * rates in question. In order to ensure correct ranging, a call to 1034 * VL53L1_enable_xtalk_compensation should always be called prior 1035 * to starting the ranging process. 1036 * 1037 * @param[in] Dev : Device Handle 1038 * 1039 * @return VL53L1_ERROR_NONE Success 1040 * @return "Other error code" See ::VL53L1_Error 1041 */ 1042 1043 VL53L1_Error VL53L1_restore_xtalk_nvm_default( 1044 VL53L1_DEV Dev); 1045 1046 /** 1047 * @brief Set function for VHV Config values 1048 * sets two parms into individual internal byte 1049 * 1050 * init_en - enables use of the init value instead of latest setting 1051 * init_value - custom vhv setting or populated from nvm 1052 * 1053 * @param[in] Dev : Device Handle 1054 * @param[in] vhv_init_en : input init_en setting 1055 * @param[in] vhv_init_value : input vhv custom value 1056 * 1057 * @return VL53L1_ERROR_NONE Success 1058 * @return "Other error code" See ::VL53L1_Error 1059 */ 1060 1061 VL53L1_Error VL53L1_set_vhv_config( 1062 VL53L1_DEV Dev, 1063 uint8_t vhv_init_en, 1064 uint8_t vhv_init_value); 1065 1066 /** 1067 * @brief Get function for VHV Config values 1068 * extracts two parms from individual internal byte 1069 * 1070 * init_en - enables use of the init value instead of latest setting 1071 * init_value - custom vhv setting or populated from nvm 1072 * 1073 * @param[in] Dev : Device Handle 1074 * @param[out] pvhv_init_en : Output pointer to uint8_t value 1075 * @param[out] pvhv_init_value : Output pointer to uint8_t value 1076 * 1077 * @return VL53L1_ERROR_NONE Success 1078 * @return "Other error code" See ::VL53L1_Error 1079 */ 1080 1081 VL53L1_Error VL53L1_get_vhv_config( 1082 VL53L1_DEV Dev, 1083 uint8_t *pvhv_init_en, 1084 uint8_t *pvhv_init_value); 1085 1086 /** 1087 * @brief Set function for VHV loopbound config 1088 * 1089 * Loopbound sets the number of +/- vhv settings to try 1090 * around the vhv init value during vhv search 1091 * i.e. if init_value = 10 and loopbound = 2 1092 * vhv search will run from 10-2 to 10+2 1093 * 8 to 12. 1094 * 1095 * @param[in] Dev : Device Handle 1096 * @param[in] vhv_loopbound : input loopbound value 1097 * 1098 * @return VL53L1_ERROR_NONE Success 1099 * @return "Other error code" See ::VL53L1_Error 1100 */ 1101 1102 VL53L1_Error VL53L1_set_vhv_loopbound( 1103 VL53L1_DEV Dev, 1104 uint8_t vhv_loopbound); 1105 1106 /** 1107 * @brief Get function for VHV loopbound config 1108 * 1109 * Loopbound sets the number of +/- vhv settings to try 1110 * around the vhv init value during vhv search 1111 * i.e. if init_value = 10 and loopbound = 2 1112 * vhv search will run from 10-2 to 10+2 1113 * 8 to 12. 1114 * 1115 * @param[in] Dev : Device Handle 1116 * @param[out] pvhv_loopbound : pointer to byte to extract loopbound 1117 * 1118 * @return VL53L1_ERROR_NONE Success 1119 * @return "Other error code" See ::VL53L1_Error 1120 */ 1121 1122 VL53L1_Error VL53L1_get_vhv_loopbound( 1123 VL53L1_DEV Dev, 1124 uint8_t *pvhv_loopbound); 1125 1126 /** 1127 * @brief Generic Tuning Parameter extraction function 1128 * 1129 * User passes a key input to retrieve a specific tuning parameter 1130 * value, this will be cast to the int32_t type and output via 1131 * the ptuning_parm_value pointer 1132 * 1133 * If the key does not match any tuning parameter, status is returned 1134 * with VL53L1_ERROR_INVALID_PARAMS 1135 * 1136 * Patch_AddedTuningParms_11761 1137 * 1138 * @param[in] Dev : Device Handle 1139 * @param[in] tuning_parm_key : Key value to access specific tuning parm 1140 * @param[out] ptuning_parm_value : Pointer to output int32_t type, retrieves \ 1141 * requested tuning parm 1142 * 1143 * @return VL53L1_ERROR_NONE Success 1144 * @return "Other error code" See ::VL53L1_Error 1145 */ 1146 1147 VL53L1_Error VL53L1_get_tuning_parm( 1148 VL53L1_DEV Dev, 1149 VL53L1_TuningParms tuning_parm_key, 1150 int32_t *ptuning_parm_value); 1151 1152 /** 1153 * @brief Generic Tuning Parameter set function 1154 * 1155 * User passes a key input to set a specific tuning parameter 1156 * value, this will be cast to the internal data type from the 1157 * input int32_t data type. 1158 * 1159 * If the key does not match any tuning parameter, status is returned 1160 * with VL53L1_ERROR_INVALID_PARAMS 1161 * 1162 * Patch_AddedTuningParms_11761 1163 * 1164 * @param[in] Dev : Device Handle 1165 * @param[in] tuning_parm_key : Key value to access specific tuning parm 1166 * @param[in] tuning_parm_value : Input tuning parm value of int32_t type, \ 1167 * sets requested tuning parm. 1168 * 1169 * @return VL53L1_ERROR_NONE Success 1170 * @return "Other error code" See ::VL53L1_Error 1171 */ 1172 1173 VL53L1_Error VL53L1_set_tuning_parm( 1174 VL53L1_DEV Dev, 1175 VL53L1_TuningParms tuning_parm_key, 1176 int32_t tuning_parm_value); 1177 1178 1179 #ifdef __cplusplus 1180 } 1181 #endif 1182 1183 #endif /* _VL53L1_API_CORE_H_ */ 1184
