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_support.h 65 * 66 * @brief EwokPlus25 core function definitions 67 */ 68 69 #ifndef _VL53L1_CORE_SUPPORT_H_ 70 #define _VL53L1_CORE_SUPPORT_H_ 71 72 #include "vl53l1_types.h" 73 74 #ifdef __cplusplus 75 extern "C" { 76 #endif 77 78 79 /** 80 * @brief Calculates the PLL period in [us] from the input 81 * fast_osc_frequency 82 * 83 * @param[in] fast_osc_frequency : fast oscillator frequency in 4.12 MHz format 84 * 85 * @return pll_period_us : PLL period in [us] 8.24 format 86 */ 87 88 uint32_t VL53L1_calc_pll_period_us( 89 uint16_t fast_osc_frequency); 90 91 92 93 #ifdef PAL_EXTENDED 94 /** 95 * @brief Calculates the ranging duration in ns using fixed point maths 96 * * 97 * Uses a temporary uint64_t variable internally 98 * 99 * @param[in] pll_period_us : PLL Period in [us] 0.25 format 100 * @param[in] vcsel_parm_pclks : period, width or WOI window in PLL clocks 101 * in 6.4 format. 102 * @param[in] window_vclks : ranging or ambient window duration in VCSEL clocks 103 * @param[in] periods_elapsed_mclks : elapsed time in macro clocks 104 * 105 * @return duration_us : uint32_t containing the duration time in us 106 */ 107 108 uint32_t VL53L1_duration_maths( 109 uint32_t pll_period_us, 110 uint32_t vcsel_parm_pclks, 111 uint32_t window_vclks, 112 uint32_t periods_elapsed_mclks); 113 114 115 /** 116 * @brief Calculates the square root of the input integer 117 * 118 * Reference : http://en.wikipedia.org/wiki/Methods_of_computing_square_roots 119 * 120 * @param[in] num : input integer 121 * 122 * @return res : square root result 123 */ 124 125 uint32_t VL53L1_isqrt( 126 uint32_t num); 127 128 /** 129 * @brief Calculates the count rate using fixed point maths 130 * 131 * Uses a temporary uint64_t variable internally 132 * Any negative negative rates are clipped to 0. 133 * 134 * @param[in] events : accumulated SPAD events 135 * @param[in] time_us : elapsed time in us 136 * 137 * @return rate_mcps : uint16_t count rate in 9.7 format 138 */ 139 140 uint16_t VL53L1_rate_maths( 141 int32_t events, 142 uint32_t time_us); 143 144 /** 145 * @brief Calculates the Rate per spad 146 * 147 * Uses a temporary uint32_t variable internally 148 * Any output rates larger than 16 bit are clipped to 0xFFFF. 149 * 150 * @param[in] frac_bits : required output fractional precision - 7 \ 151 * due to inherent resolution of pk_rate 152 * @param[in] peak_count_rate : peak signal count rate in mcps 153 * @param[in] num_spads : actual effective spads in 8.8 154 * @param[in] max_output_value : User set value to clip output 155 * 156 * @return rate_per_spad : uint16_t count rate in variable fractional format 157 */ 158 159 uint16_t VL53L1_rate_per_spad_maths( 160 uint32_t frac_bits, 161 uint32_t peak_count_rate, 162 uint16_t num_spads, 163 uint32_t max_output_value); 164 165 166 /** 167 * @brief Calculates the range from the phase data 168 * 169 * Uses a temporary int64_t variable internally 170 * 171 * @param[in] fast_osc_frequency : Fast oscillator freq [MHz] 4.12 format 172 * @param[in] phase : phase in 5.11 format 173 * @param[in] zero_distance_phase : zero distance phase in 5.11 format 174 * @param[in] fractional_bits : valid options : 0, 1, 2 175 * @param[in] gain_factor : gain correction factor 1.11 format 176 * @param[in] range_offset_mm : range offset [mm] 14.2 format 177 178 * @return range_mm : signed range in [mm] 179 * format depends on fractional_bits input 180 */ 181 182 int32_t VL53L1_range_maths( 183 uint16_t fast_osc_frequency, 184 uint16_t phase, 185 uint16_t zero_distance_phase, 186 uint8_t fractional_bits, 187 int32_t gain_factor, 188 int32_t range_offset_mm); 189 #endif 190 191 192 /** 193 * @brief Decodes VCSEL period register value into the real period in PLL clocks 194 * 195 * @param[in] vcsel_period_reg : 8 -bit register value 196 * 197 * @return vcsel_period_pclks : 8-bit decoded value 198 * 199 */ 200 201 uint8_t VL53L1_decode_vcsel_period( 202 uint8_t vcsel_period_reg); 203 204 /** 205 * @brief Decodes the Byte.Bit coord encoding into an (x,y) coord value 206 * 207 * @param[in] spad_number : Coord location in Byte.Bit format 208 * @param[out] prow : Decoded row 209 * @param[out] pcol : Decoded column 210 * 211 */ 212 213 void VL53L1_decode_row_col( 214 uint8_t spad_number, 215 uint8_t *prow, 216 uint8_t *pcol); 217 218 #ifdef __cplusplus 219 } 220 #endif 221 222 #endif /* _VL53L1_CORE_SUPPORT_H_ */ 223
