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_core.h 65 * 66 * @brief EwokPlus25 core function definitions 67 */ 68 69 #ifndef _VL53L1_CORE_H_ 70 #define _VL53L1_CORE_H_ 71 72 #include "vl53l1_platform.h" 73 #include "vl53l1_core_support.h" 74 75 #ifdef __cplusplus 76 extern "C" { 77 #endif 78 79 80 /** 81 * @brief Initialise version info in pdev 82 * 83 * @param[out] Dev : Device handle 84 */ 85 86 void VL53L1_init_version( 87 VL53L1_DEV Dev); 88 89 90 /** 91 * @brief Initialise LL Driver State 92 * 93 * @param[out] Dev : Device handle 94 * @param[in] ll_state : Device state 95 */ 96 97 void VL53L1_init_ll_driver_state( 98 VL53L1_DEV Dev, 99 VL53L1_DeviceState ll_state); 100 101 102 /** 103 * @brief Update LL Driver Read State 104 * 105 * @param[out] Dev : Device handle 106 * 107 * @return VL53L1_ERROR_NONE Success 108 * @return "Other error code" See ::VL53L1_Error 109 */ 110 111 VL53L1_Error VL53L1_update_ll_driver_rd_state( 112 VL53L1_DEV Dev); 113 114 115 /** 116 * @brief Checks if the LL Driver Read state and expected stream count 117 * matches the state and stream count received from the device 118 * 119 * @param[out] Dev : Device handle 120 * 121 * @return VL53L1_ERROR_NONE Success 122 * @return "Other error code" See ::VL53L1_Error 123 */ 124 125 VL53L1_Error VL53L1_check_ll_driver_rd_state( 126 VL53L1_DEV Dev); 127 128 129 /** 130 * @brief Update LL Driver Configuration State 131 * 132 * @param[out] Dev : Device handle 133 * 134 * @return VL53L1_ERROR_NONE Success 135 * @return "Other error code" See ::VL53L1_Error 136 */ 137 138 VL53L1_Error VL53L1_update_ll_driver_cfg_state( 139 VL53L1_DEV Dev); 140 141 142 /** 143 * @brief Convenience function to copy return SPAD enables to buffer 144 * 145 * @param[in ] pdata : pointer to VL53L1_nvm_copy_data_t 146 * @param[out] pbuffer : pointer to buffer 147 */ 148 149 void VL53L1_copy_rtn_good_spads_to_buffer( 150 VL53L1_nvm_copy_data_t *pdata, 151 uint8_t *pbuffer); 152 153 154 /** 155 * @brief Initialise system results structure to all ones 156 * 157 * This mimics what the device firmware does the the results registers 158 * at the start of each range 159 * 160 * @param[out] pdata : pointer to VL53L1_system_results_t 161 */ 162 163 void VL53L1_init_system_results( 164 VL53L1_system_results_t *pdata); 165 166 167 /** 168 * @brief Initialise zone dynamic config DSS control values 169 * 170 * @param[in] Dev : Device handler 171 */ 172 173 void V53L1_init_zone_dss_configs( 174 VL53L1_DEV Dev); 175 176 177 /** 178 * @brief Encodes a uint16_t register value into an I2C write buffer 179 * 180 * The register is encoded MS byte first is the buffer i.e as per the device register map 181 * 182 * @param[in] ip_value : input uint16_t value 183 * @param[in] count : register size of in bytes (1, 2, 3 or 4) 184 * @param[out] pbuffer : uint8_t pointer to the I2C write buffer 185 */ 186 187 void VL53L1_i2c_encode_uint16_t( 188 uint16_t ip_value, 189 uint16_t count, 190 uint8_t *pbuffer); 191 192 193 /** 194 * @brief Decodes a uint16_t register value from an I2C read buffer 195 * 196 * The I2C read buffer is assumed to be MS byte first i.e. matching the device register map 197 * 198 * @param[in] count : register size of in bytes (1, 2, 3 or 4) 199 * @param[in] pbuffer : uint8_t pointer to the I2C read buffer 200 * 201 * @return value : decoded uint16_t value 202 */ 203 204 uint16_t VL53L1_i2c_decode_uint16_t( 205 uint16_t count, 206 uint8_t *pbuffer); 207 208 209 /** 210 * @brief Encodes a int16_t register value into an I2C write buffer 211 * 212 * The register is encoded MS byte first is the buffer i.e as per the device register map 213 * 214 * @param[in] ip_value : input int16_t value 215 * @param[in] count : register size of in bytes (1, 2, 3 or 4) 216 * @param[out] pbuffer : uint8_t pointer to the I2C write buffer 217 */ 218 219 void VL53L1_i2c_encode_int16_t( 220 int16_t ip_value, 221 uint16_t count, 222 uint8_t *pbuffer); 223 224 225 /** 226 * @brief Decodes a int16_t register value from an I2C read buffer 227 * 228 * The I2C read buffer is assumed to be MS byte first i.e. matching the device register map 229 * 230 * @param[in] count : register size of in bytes (1, 2, 3 or 4) 231 * @param[in] pbuffer : uint8_t pointer to the I2C read buffer 232 * 233 * @return value : decoded int16_t value 234 */ 235 236 int16_t VL53L1_i2c_decode_int16_t( 237 uint16_t count, 238 uint8_t *pbuffer); 239 240 241 /** 242 * @brief Encodes a uint32_t register value into an I2C write buffer 243 * 244 * The register is encoded MS byte first is the buffer i.e as per the device register map 245 * 246 * @param[in] ip_value : input uint32_t value 247 * @param[in] count : register size of in bytes (1, 2, 3 or 4) 248 * @param[out] pbuffer : uint8_t pointer to the I2C write buffer 249 */ 250 251 void VL53L1_i2c_encode_uint32_t( 252 uint32_t ip_value, 253 uint16_t count, 254 uint8_t *pbuffer); 255 256 257 /** 258 * @brief Decodes a uint32_t register value from an I2C read buffer 259 * 260 * The I2C read buffer is assumed to be MS byte first i.e. matching the device register map 261 * 262 * @param[in] count : register size of in bytes (1, 2, 3 or 4) 263 * @param[in] pbuffer : uint8_t pointer to the I2C read buffer 264 * 265 * @return value : decoded uint32_t value 266 */ 267 268 uint32_t VL53L1_i2c_decode_uint32_t( 269 uint16_t count, 270 uint8_t *pbuffer); 271 272 273 /** 274 * @brief Decodes an integer register value from an I2C read buffer 275 * 276 * The I2C read buffer is assumed to be MS byte first i.e. matching the device register map 277 * 278 * @param[in] count : integer size of in bytes (1, 2, 3 or 4) 279 * @param[in] pbuffer : uint8_t pointer to the I2C read buffer 280 * @param[in] bit_mask : bit mask to apply 281 * @param[in] down_shift : down shift to apply 282 * @param[in] offset : offset to apply after the down shift 283 * 284 * @return value : decoded integer value 285 */ 286 287 uint32_t VL53L1_i2c_decode_with_mask( 288 uint16_t count, 289 uint8_t *pbuffer, 290 uint32_t bit_mask, 291 uint32_t down_shift, 292 uint32_t offset); 293 294 295 /** 296 * @brief Encodes a int32_t register value into an I2C write buffer 297 * 298 * The register is encoded MS byte first is the buffer i.e as per the device register map 299 * 300 * @param[in] ip_value : input int32_t value 301 * @param[in] count : register size of in bytes (1, 2, 3 or 4) 302 * @param[out] pbuffer : uint8_t pointer to the I2C write buffer 303 */ 304 305 void VL53L1_i2c_encode_int32_t( 306 int32_t ip_value, 307 uint16_t count, 308 uint8_t *pbuffer); 309 310 311 /** 312 * @brief Decodes a int32_t register value from an I2C read buffer 313 * 314 * The I2C read buffer is assumed to be MS byte first i.e. matching the device register map 315 * 316 * @param[in] count : register size of in bytes (1, 2, 3 or 4) 317 * @param[in] pbuffer : uint8_t pointer to the I2C read buffer 318 * 319 * @return value : decoded int32_t value 320 */ 321 322 int32_t VL53L1_i2c_decode_int32_t( 323 uint16_t count, 324 uint8_t *pbuffer); 325 326 327 /** 328 * @brief Triggers the start of the provided test_mode. 329 * 330 * @param[in] Dev : Device handle 331 * @param[in] test_mode__ctrl : VL53L1_TEST_MODE__CTRL register value 332 * 333 * @return VL53L1_ERROR_NONE Success 334 * @return "Other error code" See ::VL53L1_Error 335 */ 336 337 #ifndef VL53L1_NOCALIB 338 VL53L1_Error VL53L1_start_test( 339 VL53L1_DEV Dev, 340 uint8_t test_mode__ctrl); 341 #endif 342 343 344 /** 345 * @brief Set firmware enable register 346 * 347 * Wrapper for setting power force register state 348 * Also updates pdev->sys_ctrl.firmware__enable 349 * 350 * @param[in] Dev : Device handle 351 * @param[in] value : register value 352 * 353 * @return VL53L1_ERROR_NONE Success 354 * @return "Other error code" See ::VL53L1_Error 355 */ 356 357 VL53L1_Error VL53L1_set_firmware_enable_register( 358 VL53L1_DEV Dev, 359 uint8_t value); 360 361 362 /** 363 * @brief Enables MCU firmware 364 * 365 * @param[in] Dev : Device handle 366 * 367 * @return VL53L1_ERROR_NONE Success 368 * @return "Other error code" See ::VL53L1_Error 369 */ 370 371 VL53L1_Error VL53L1_enable_firmware( 372 VL53L1_DEV Dev); 373 374 375 /** 376 * @brief Disables MCU firmware 377 * 378 * This required to write to MCU G02, G01 registers and access the patch RAM 379 * 380 * @param[in] Dev : Device handle 381 * 382 * @return VL53L1_ERROR_NONE Success 383 * @return "Other error code" See ::VL53L1_Error 384 */ 385 386 VL53L1_Error VL53L1_disable_firmware( 387 VL53L1_DEV Dev); 388 389 390 /** 391 * @brief Set power force register 392 * 393 * Wrapper for setting power force register state 394 * Also updates pdev->sys_ctrl.power_management__go1_power_force 395 * 396 * @param[in] Dev : Device handle 397 * @param[in] value : register value 398 * 399 * @return VL53L1_ERROR_NONE Success 400 * @return "Other error code" See ::VL53L1_Error 401 */ 402 403 VL53L1_Error VL53L1_set_powerforce_register( 404 VL53L1_DEV Dev, 405 uint8_t value); 406 407 408 /** 409 * @brief Enables power force 410 * 411 * This prevents the G01 and patch RAM from powering down between 412 * ranges to enable reading of G01 and patch RAM data 413 * 414 * Calls VL53L1_set_powerforce_register() 415 * 416 * @param[in] Dev : Device handle 417 * 418 * @return VL53L1_ERROR_NONE Success 419 * @return "Other error code" See ::VL53L1_Error 420 */ 421 422 423 VL53L1_Error VL53L1_enable_powerforce( 424 VL53L1_DEV Dev); 425 426 /** 427 * @brief Disables power force 428 * 429 * @param[in] Dev : Device handle 430 * 431 * Disable power force 432 * 433 * Calls VL53L1_set_powerforce_register() 434 * 435 * @return VL53L1_ERROR_NONE Success 436 * @return "Other error code" See ::VL53L1_Error 437 */ 438 439 VL53L1_Error VL53L1_disable_powerforce( 440 VL53L1_DEV Dev); 441 442 443 /** 444 * @brief Clears Ranging Interrupt 445 * 446 * @param[in] Dev : Device handle 447 * 448 * @return VL53L1_ERROR_NONE Success 449 * @return "Other error code" See ::VL53L1_Error 450 */ 451 452 453 VL53L1_Error VL53L1_clear_interrupt( 454 VL53L1_DEV Dev); 455 456 457 /** 458 * @brief Forces shadow stream count to zero 459 * 460 * @param[in] Dev : Device handle 461 * 462 * @return VL53L1_ERROR_NONE Success 463 * @return "Other error code" See ::VL53L1_Error 464 */ 465 466 467 #ifdef VL53L1_DEBUG 468 VL53L1_Error VL53L1_force_shadow_stream_count_to_zero( 469 VL53L1_DEV Dev); 470 #endif 471 472 /** 473 * @brief Calculates the macro period in [us] for the input 474 * fast_osc_frequency and VCSEL period register value 475 * 476 * Processing steps: 477 * 478 * 1. PLL period from fast_osc_frequency 479 * 2. VCSEL period 480 * 3. Macro period 481 * 482 * @param[in] fast_osc_frequency : fast oscillator frequency in 4.12 MHz format 483 * @param[in] vcsel_period : VCSEL period register value 484 * 485 * @return macro_period_us : macro period in [us] 12.12 format 486 */ 487 488 uint32_t VL53L1_calc_macro_period_us( 489 uint16_t fast_osc_frequency, 490 uint8_t vcsel_period); 491 492 493 /** 494 * @brief Calculates the Xtalk Range Ignore Threshold 495 * rate per spad in 3.13Mcps 496 * 497 * This is done by calculating the worst case xtalk seen on the array 498 * and applying a user specified fractional multiplier. 499 * 500 * @param[in] central_rate : xtalk central rate in 9.9u Kcps format 501 * @param[in] x_gradient : xtalk xgradient rate in 4.11s Kcps format 502 * @param[in] y_gradient : xtalk ygradient rate in 4.11s Kcps format 503 * @param[in] rate_mult : rate multiplier in 2.5 fractional format 504 * 505 * @return range_ignore_threshold_kcps : rate per spad in mcps 3.13 506 */ 507 508 uint16_t VL53L1_calc_range_ignore_threshold( 509 uint32_t central_rate, 510 int16_t x_gradient, 511 int16_t y_gradient, 512 uint8_t rate_mult); 513 514 515 /** 516 * @brief Calculates the timeout value in macro period based on the input 517 * timeout period in milliseconds and the macro period in us 518 * 519 * @param[in] timeout_us : timeout period in microseconds 520 * @param[in] macro_period_us : macro period in microseconds 12.12 521 * 522 * @return timeout_mclks : timeout in macro periods 523 */ 524 525 uint32_t VL53L1_calc_timeout_mclks( 526 uint32_t timeout_us, 527 uint32_t macro_period_us); 528 529 /** 530 * @brief Calculates the encoded timeout register value based on the input 531 * timeout period in milliseconds and the macro period in us 532 * 533 * @param[in] timeout_us : timeout period in microseconds 534 * @param[in] macro_period_us : macro period in microseconds 12.12 535 * 536 * @return timeout_encoded : encoded timeout register value 537 */ 538 539 uint16_t VL53L1_calc_encoded_timeout( 540 uint32_t timeout_us, 541 uint32_t macro_period_us); 542 543 544 /** 545 * @brief Calculates the timeout in us based on the input 546 * timeout im macro periods value and the macro period in us 547 * 548 * @param[in] timeout_mclks : timeout im macro periods 549 * @param[in] macro_period_us : macro period in microseconds 12.12 550 * 551 * @return timeout_us : encoded timeout register value 552 */ 553 554 uint32_t VL53L1_calc_timeout_us( 555 uint32_t timeout_mclks, 556 uint32_t macro_period_us); 557 558 /** 559 * @brief Calculates the decoded timeout in us based on the input 560 * encoded timeout register value and the macro period in us 561 * 562 * @param[in] timeout_encoded : encoded timeout register value 563 * @param[in] macro_period_us : macro period in microseconds 12.12 564 * 565 * @return timeout_us : encoded timeout register value 566 */ 567 568 uint32_t VL53L1_calc_decoded_timeout_us( 569 uint16_t timeout_encoded, 570 uint32_t macro_period_us); 571 572 573 /** 574 * @brief Encode timeout in (LSByte * 2^MSByte) + 1 register format. 575 * 576 * @param[in] timeout_mclks : uint32_t timeout value (macro periods) 577 * 578 * @return encoded_timeout : 16-bit encoded value 579 */ 580 581 uint16_t VL53L1_encode_timeout( 582 uint32_t timeout_mclks); 583 584 585 /** 586 * @brief Decode 16-bit timeout register value. 587 * 588 * @param[in] encoded_timeout : 16-bit timeout register value 589 * 590 * @return timeout_macro_clks : uint32_t decoded value 591 * 592 */ 593 594 uint32_t VL53L1_decode_timeout( 595 uint16_t encoded_timeout); 596 597 598 /** 599 * @brief Converts the input MM and range timeouts in [us] 600 * into the appropriate register values 601 * 602 * Must also be run after the VCSEL period settings are changed 603 * 604 * @param[in] phasecal_config_timeout_us : requested Phase Cal Timeout e.g. 1000us 605 * @param[in] mm_config_timeout_us : requested MM Timeout e.g. 2000us 606 * @param[in] range_config_timeout_us : requested Ranging Timeout e.g 10000us 607 * @param[in] fast_osc_frequency : fast oscillator frequency in 4.12 MHz format 608 * @param[out] pgeneral : general data struct 609 * @param[out] ptiming : timing data struct with input vcsel period data 610 * 611 * @return VL53L1_ERROR_NONE Success 612 * @return "Other error code" See ::VL53L1_Error 613 */ 614 615 VL53L1_Error VL53L1_calc_timeout_register_values( 616 uint32_t phasecal_config_timeout_us, 617 uint32_t mm_config_timeout_us, 618 uint32_t range_config_timeout_us, 619 uint16_t fast_osc_frequency, 620 VL53L1_general_config_t *pgeneral, 621 VL53L1_timing_config_t *ptiming); 622 623 624 /** 625 * @brief Encodes the real period in PLL clocks into the register value 626 * 627 * @param[in] vcsel_period_pclks : 8-bit value 628 * 629 * @return vcsel_period_reg : 8-bit encoded value 630 * 631 */ 632 633 uint8_t VL53L1_encode_vcsel_period( 634 uint8_t vcsel_period_pclks); 635 636 637 /** 638 * @brief Decodes an unsigned integer from a uint8_t buffer 16-bit, 24-bit or 32-bit integers. 639 * 640 * Assumes MS Byte first 641 * 642 * @param[in] pbuffer : pointer to start of integer uint8_t data 643 * @param[in] no_of_bytes : size of integer in bytes 644 * 645 * @return decoded_value : decoded integer value 646 * 647 */ 648 649 uint32_t VL53L1_decode_unsigned_integer( 650 uint8_t *pbuffer, 651 uint8_t no_of_bytes); 652 653 654 /** 655 * @brief Encodes an unsigned integer into a uint8_t buffer MS byte first 656 * 657 * @param[in] ip_value : input unsigned integer 658 * @param[in] no_of_bytes : size of integer storage in bytes 659 * @param[out] pbuffer : pointer to output buffer 660 * 661 */ 662 663 void VL53L1_encode_unsigned_integer( 664 uint32_t ip_value, 665 uint8_t no_of_bytes, 666 uint8_t *pbuffer); 667 668 /** 669 * @brief Get the SPAD number, byte index (0-31) and bit index (0-7) for 670 * 671 * Takes the map index (0 - 255) and calculated the SPAD number, byte index 672 * within the SPAD enable byte array and but position within the SPAD enable 673 * byte 674 * 675 * 676 * @param[in] spad_number : spad number 677 * @param[out] pbyte_index : pointer to output 0-31 byte index for SPAD enables 678 * @param[out] pbit_index : pointer to output 0-7 bit index 679 * @param[out] pbit_mask : pointer to output bit mask for the byte 680 * 681 */ 682 683 void VL53L1_spad_number_to_byte_bit_index( 684 uint8_t spad_number, 685 uint8_t *pbyte_index, 686 uint8_t *pbit_index, 687 uint8_t *pbit_mask); 688 689 690 /** 691 * @brief Encodes a (col,row) coord value into ByteIndex.BitIndex format 692 * 693 * 694 * @param[in] row : Row 695 * @param[in] col : Column 696 * @param[out] pspad_number : Encoded Coord in Byte.Bit format 697 * 698 */ 699 700 void VL53L1_encode_row_col( 701 uint8_t row, 702 uint8_t col, 703 uint8_t *pspad_number); 704 705 706 /** 707 * @brief Decodes encoded zone size format into width and height values 708 * 709 * @param[in] encoded_xy_size : Encoded zone size 710 * @param[out] pwidth : Decoded zone width 711 * @param[out] pheight : Decoded zone height 712 * 713 */ 714 715 void VL53L1_decode_zone_size( 716 uint8_t encoded_xy_size, 717 uint8_t *pwidth, 718 uint8_t *pheight); 719 720 721 /** 722 * @brief Encodes a zone width & height into encoded size format 723 * 724 * @param[in] width : Zone Width 725 * @param[in] height : Zone height 726 * @param[out] pencoded_xy_size : Encoded zone size 727 * 728 */ 729 730 void VL53L1_encode_zone_size( 731 uint8_t width, 732 uint8_t height, 733 uint8_t *pencoded_xy_size); 734 735 736 /** 737 * @brief Decodes encoded zone info into min/max limits 738 * 739 * Note both the lower left and upper right coordinated lie within 740 * the zone (inclusive) 741 * 742 * @param[in] encoded_xy_centre : Encoded zone centre (spad number) 743 * @param[in] encoded_xy_size : Encoded zone size 744 * @param[out] px_ll : Decoded zone lower left x coord 745 * @param[out] py_ll : Decoded zone lower left y coord 746 * @param[out] px_ur : Decoded zone upper right x coord 747 * @param[out] py_ur : Decoded zone upper right y coord 748 */ 749 750 void VL53L1_decode_zone_limits( 751 uint8_t encoded_xy_centre, 752 uint8_t encoded_xy_size, 753 int16_t *px_ll, 754 int16_t *py_ll, 755 int16_t *px_ur, 756 int16_t *py_ur); 757 758 759 /** 760 * @brief Returns > 0 if input (row,col) location is an apertured SPAD 761 * 762 * @param[in] row : Row 763 * @param[in] col : Column 764 * 765 * @return is_aperture : if > 0 the location is an apertured SPAD 766 */ 767 768 uint8_t VL53L1_is_aperture_location( 769 uint8_t row, 770 uint8_t col); 771 772 773 /** 774 * @brief Calculates the effective SPAD counts for the MM inner and outer 775 * regions based on the input MM ROI, Zone info and return good 776 * SPAD map 777 * 778 * @param[in] encoded_mm_roi_centre : Encoded MM ROI centre - spad number 779 * @param[in] encoded_mm_roi_size : Encoded MM ROI size 780 * @param[in] encoded_zone_centre : Encoded Zone centre - spad number 781 * @param[in] encoded_zone_size : Encoded Zone size 782 * @param[in] pgood_spads : Return array good SPAD map (32 bytes) 783 * @param[in] aperture_attenuation : Aperture attenuation value, Format 8.8 784 * @param[out] pmm_inner_effective_spads : MM Inner effective SPADs, Format 8.8 785 * @param[out] pmm_outer_effective_spads : MM Outer effective SPADs, Format 8.8 786 * 787 */ 788 789 void VL53L1_calc_mm_effective_spads( 790 uint8_t encoded_mm_roi_centre, 791 uint8_t encoded_mm_roi_size, 792 uint8_t encoded_zone_centre, 793 uint8_t encoded_zone_size, 794 uint8_t *pgood_spads, 795 uint16_t aperture_attenuation, 796 uint16_t *pmm_inner_effective_spads, 797 uint16_t *pmm_outer_effective_spads); 798 799 /** 800 * @brief Function to save dynamic config data per zone at init and start range 801 * 802 * @param[in] Dev : Pointer to data structure 803 * 804 * 805 * @return VL53L1_ERROR_NONE Success 806 * 807 */ 808 809 VL53L1_Error VL53L1_save_cfg_data( 810 VL53L1_DEV Dev); 811 812 813 /** 814 * @brief Encodes VL53L1_GPIO_interrupt_config_t structure to FW register format 815 * 816 * @param[in] pintconf : pointer to gpio interrupt config structure 817 * @return The encoded system__interrupt_config_gpio byte 818 */ 819 820 uint8_t VL53L1_encode_GPIO_interrupt_config( 821 VL53L1_GPIO_interrupt_config_t *pintconf); 822 823 /** 824 * @brief Decodes FW register to VL53L1_GPIO_interrupt_config_t structure 825 * 826 * @param[in] system__interrupt_config : interrupt config register byte 827 * @return The decoded structure 828 */ 829 830 VL53L1_GPIO_interrupt_config_t VL53L1_decode_GPIO_interrupt_config( 831 uint8_t system__interrupt_config); 832 833 /** 834 * @brief SET GPIO distance threshold 835 * 836 * @param[in] Dev : Device Handle 837 * @param[in] threshold_high : High distance threshold in mm 838 * @param[in] threshold_low : Low distance threshold in mm 839 */ 840 841 VL53L1_Error VL53L1_set_GPIO_distance_threshold( 842 VL53L1_DEV Dev, 843 uint16_t threshold_high, 844 uint16_t threshold_low); 845 846 /** 847 * @brief SET GPIO rate threshold 848 * 849 * @param[in] Dev : Device Handle 850 * @param[in] threshold_high : High rate threshold in 9.7 Mcps 851 * @param[in] threshold_low : Low rate threshold in 9.7 Mcps 852 */ 853 854 VL53L1_Error VL53L1_set_GPIO_rate_threshold( 855 VL53L1_DEV Dev, 856 uint16_t threshold_high, 857 uint16_t threshold_low); 858 859 /** 860 * @brief SET GPIO thresholds from structure. Sets both rate and distance 861 * thresholds 862 * 863 * @param[in] Dev : Device Handle 864 * @param[in] pintconf : Pointer to structure 865 */ 866 867 VL53L1_Error VL53L1_set_GPIO_thresholds_from_struct( 868 VL53L1_DEV Dev, 869 VL53L1_GPIO_interrupt_config_t *pintconf); 870 871 872 /** 873 * @brief Set Ref SPAD Characterisation Config 874 * 875 * Initialises the timeout and VCSEL period for the Reference 876 * SPAD Characterisation test mode. 877 * 878 * Register Mapping: 879 * 880 * - timeout -> VL53L1_PHASECAL_CONFIG__TIMEOUT_MACROP 881 * - vcsel_period -> VL53L1_RANGE_CONFIG__VCSEL_PERIOD_A \n 882 * -> VL53L1_SD_CONFIG__WOI_SD0 \n 883 * -> VL53L1_SD_CONFIG__WOI_SD1 884 * - total_rate_target_mcps -> VL53L1_REF_SPAD_CHAR__TOTAL_RATE_TARGET_MCPS 885 * - max_count_rate_rtn_limit_mcps -> VL53L1_RANGE_CONFIG__SIGMA_THRESH 886 * - min_count_rate_rtn_limit_mcps -> VL53L1_SRANGE_CONFIG__SIGMA_THRESH 887 * 888 * @param[in] Dev : Device handle 889 * @param[in] vcsel_period_a : VCSEL period A register value 890 * @param[in] phasecal_timeout_us : requested PhaseCal Timeout in [us] 891 * e.g 1000us 892 * @param[in] total_rate_target_mcps : Target reference rate [Mcps] 9.7 format 893 * @param[in] max_count_rate_rtn_limit_mcps : Max rate final check limit [Mcps] 9.7 format 894 * @param[in] min_count_rate_rtn_limit_mcps : Min rate final check limit [Mcps] 9.7 format 895 * @param[in] fast_osc_frequency : Fast Osc Frequency (4.12) format 896 * 897 * @return VL53L1_ERROR_NONE Success 898 * @return "Other error code" See ::VL53L1_Error 899 */ 900 901 902 #ifndef VL53L1_NOCALIB 903 VL53L1_Error VL53L1_set_ref_spad_char_config( 904 VL53L1_DEV Dev, 905 uint8_t vcsel_period_a, 906 uint32_t phasecal_timeout_us, 907 uint16_t total_rate_target_mcps, 908 uint16_t max_count_rate_rtn_limit_mcps, 909 uint16_t min_count_rate_rtn_limit_mcps, 910 uint16_t fast_osc_frequency); 911 #endif 912 913 914 /** 915 * @brief Applies SSC (SPAD Self Check) configuration to device. 916 * 917 * Prior to calling this function it is assumed both the Fast Osc 918 * and VCSEL have already been trimmed and the register values set. 919 * 920 * Internally the required timeout in macro periods is calculated 921 * from the input VCSEL period, fast_osc_frequency and requested 922 * timeout in microseconds. 923 * 924 * Register Mapping: 925 * 926 * - rate_select -> VL53L1_NVM_BIST__CTRL 927 * - timeout -> VL53L1_RANGE_CONFIG__TIMEOUT_MACROP_ B_HI & _LO 928 * - vcsel_period -> VL53L1_RANGE_CONFIG__VCSEL_PERIOD_B \n 929 * -> VL53L1_SD_CONFIG__WOI_SD0 \n 930 * -> VL53L1_SD_CONFIG__WOI_SD1 931 * - vcsel_start -> VL53L1_CAL_CONFIG__VCSEL_START 932 * - vcsel_width -> VL53L1_GLOBAL_CONFIG__VCSEL_WIDTH 933 * - ssc_limit_mcps -> VL53L1_RANGE_CONFIG__SIGMA_THRESH 934 * 935 * ssc_rate_limit_mcps format: 936 * 937 * - 1.15 for DCR/LCR test modes with VCSEL off 938 * - 9.7 LCR test mode with VCSEL on 939 * 940 * The configuration is set to the device via a 5-byte multi byte write. 941 * 942 * @param[in] Dev : Device handle 943 * @param[in] pssc_cfg : pointer to VL53L1_ssc_config_t 944 * @param[in] fast_osc_frequency : Fast Osc Frequency (4.12) format 945 * 946 * @return VL53L1_ERROR_NONE Success 947 * @return "Other error code" See ::VL53L1_Error 948 */ 949 950 #ifndef VL53L1_NOCALIB 951 VL53L1_Error VL53L1_set_ssc_config( 952 VL53L1_DEV Dev, 953 VL53L1_ssc_config_t *pssc_cfg, 954 uint16_t fast_osc_frequency); 955 #endif 956 957 958 /** 959 * @brief Gets the 256 return array SSC rates from the Patch RAM 960 * 961 * Each SSC rate is 1.15 or 9.7 dependent on test run. 962 * Total of 512 bytes to read! 963 * 964 * ssc_rate_mcps buffer format: 965 * 966 * - 1.15 for DCR/LCR test modes with VCSEL off (ambient) 967 * - 9.7 LCR test mode with VCSEL on (which rate?) 968 * 969 * Assumes that power force has already been enabled 970 * 971 * Function disables firmware at start to allow patch RAM to be read 972 * and then enables the firmware before returning 973 * 974 * The order of the rates is in SPAD number order (increasing) 975 * 976 * @param[in] Dev : Device handle 977 * @param[out] pspad_rates : pointer to VL53L1_spad_rate_data_t 978 * 979 * @return VL53L1_ERROR_NONE Success 980 * @return "Other error code" See ::VL53L1_Error 981 */ 982 983 #ifndef VL53L1_NOCALIB 984 VL53L1_Error VL53L1_get_spad_rate_data( 985 VL53L1_DEV Dev, 986 VL53L1_spad_rate_data_t *pspad_rates); 987 #endif 988 989 /** 990 * @brief Function to add signed margin to the 991 * xtalk plane offset value, dealing with signed and unsigned 992 * value mixing 993 * 994 * Clips output to 0 if negative 995 * Clips to max possible value of 9.9 Kcps if exceeds this limitation 996 * 997 * @param[in] plane_offset_kcps : xtalk plane offset (9.9 format) Kcps 998 * @param[in] margin_offset_kcps : margin offset signed (6.9 format) Kcps 999 * 1000 * @return plane_offset_with_margin in Kcps (7.9 format) 1001 */ 1002 1003 uint32_t VL53L1_calc_crosstalk_plane_offset_with_margin( 1004 uint32_t plane_offset_kcps, 1005 int16_t margin_offset_kcps); 1006 1007 /** 1008 * @brief Initialize the Low Power Auto data structure 1009 * 1010 * Patch_LowPowerAutoMode 1011 * 1012 * @param[in] Dev : Device Handle 1013 * 1014 * @return VL53L1_ERROR_NONE Success 1015 * @return "Other error code" See ::VL53L1_Error 1016 */ 1017 1018 VL53L1_Error VL53L1_low_power_auto_data_init( 1019 VL53L1_DEV Dev 1020 ); 1021 1022 /** 1023 * @brief Reset internal state but leave low_power_auto mode intact 1024 * 1025 * Patch_LowPowerAutoMode 1026 * 1027 * @param[in] Dev : Device Handle 1028 * 1029 * @return VL53L1_ERROR_NONE Success 1030 * @return "Other error code" See ::VL53L1_Error 1031 */ 1032 1033 VL53L1_Error VL53L1_low_power_auto_data_stop_range( 1034 VL53L1_DEV Dev 1035 ); 1036 1037 /** 1038 * @brief Initialize the config strcutures when low power auto preset modes are 1039 * selected 1040 * 1041 * Patch_LowPowerAutoMode 1042 * 1043 * @param[in] pgeneral : pointer to the general config structure 1044 * @param[in] pdynamic : pointer to the dynamic config structure 1045 * @param[in] plpadata : pointer to the low power auto config structure 1046 * 1047 * @return VL53L1_ERROR_NONE Success 1048 * @return "Other error code" See ::VL53L1_Error 1049 */ 1050 1051 VL53L1_Error VL53L1_config_low_power_auto_mode( 1052 VL53L1_general_config_t *pgeneral, 1053 VL53L1_dynamic_config_t *pdynamic, 1054 VL53L1_low_power_auto_data_t *plpadata 1055 ); 1056 1057 /** 1058 * @brief Setup ranges after the first one in low power auto mode by turning 1059 * off FW calibration steps and programming static values 1060 * 1061 * Patch_LowPowerAutoMode 1062 * 1063 * @param[out] Dev : Device handle 1064 * 1065 * @return VL53L1_ERROR_NONE Success 1066 * @return "Other error code" See ::VL53L1_Error 1067 */ 1068 1069 VL53L1_Error VL53L1_low_power_auto_setup_manual_calibration( 1070 VL53L1_DEV Dev); 1071 1072 /** 1073 * @brief Do a DSS calculation and update manual config 1074 * 1075 * Patch_LowPowerAutoMode 1076 * 1077 * @param[out] Dev : Device handle 1078 * 1079 * @return VL53L1_ERROR_NONE Success 1080 * @return "Other error code" See ::VL53L1_Error 1081 */ 1082 1083 VL53L1_Error VL53L1_low_power_auto_update_DSS( 1084 VL53L1_DEV Dev); 1085 1086 #ifdef __cplusplus 1087 } 1088 #endif 1089 1090 #endif /* _VL53L1_API_CORE_H_ */ 1091
