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_wait.h 65 * 66 * @brief EwokPlus25 low level Driver wait function definitions 67 */ 68 69 #ifndef _VL53L1_WAIT_H_ 70 #define _VL53L1_WAIT_H_ 71 72 #include "vl53l1_platform.h" 73 74 #ifdef __cplusplus 75 extern "C" { 76 #endif 77 78 79 /** 80 * @brief Wait for initial firmware boot to finish 81 * 82 * Calls VL53L1_poll_for_boot_completion() 83 * 84 * @param[in] Dev : Device handle 85 * 86 * @return VL53L1_ERROR_NONE Success 87 * @return "Other error code" See ::VL53L1_Error 88 */ 89 90 VL53L1_Error VL53L1_wait_for_boot_completion( 91 VL53L1_DEV Dev); 92 93 94 /** 95 * @brief Waits for initial firmware ready 96 * 97 * Only waits to see if the firmware is ready in timed and 98 * single shot modes. 99 * 100 * Calls VL53L1_poll_for_firmware_ready() 101 * 102 * @param[in] Dev : Device handle 103 * 104 * @return VL53L1_ERROR_NONE Success 105 * @return "Other error code" See ::VL53L1_Error 106 */ 107 108 VL53L1_Error VL53L1_wait_for_firmware_ready( 109 VL53L1_DEV Dev); 110 111 112 /** 113 * @brief Waits for the next ranging interrupt 114 * 115 * Calls VL53L1_poll_for_range_completion() 116 * 117 * @param[in] Dev : Device handle 118 * 119 * @return VL53L1_ERROR_NONE Success 120 * @return "Other error code" See ::VL53L1_Error 121 */ 122 123 VL53L1_Error VL53L1_wait_for_range_completion( 124 VL53L1_DEV Dev); 125 126 127 /** 128 * @brief Waits for a device test mode to complete. 129 130 * Calls VL53L1_poll_for_test_completion() 131 * 132 * @param[in] Dev : Device Handle 133 * 134 * @return VL53L1_ERROR_NONE Success 135 * @return "Other error code" See ::VL53L1_Error 136 */ 137 138 VL53L1_Error VL53L1_wait_for_test_completion( 139 VL53L1_DEV Dev); 140 141 142 143 144 /** 145 * @brief Reads FIRMWARE__SYSTEM_STATUS register to detect if the 146 * firmware was finished booting 147 * 148 * @param[in] Dev : Device handle 149 * @param[out] pready : pointer to data ready flag \n 150 * 0 = boot not complete \n 151 * 1 = boot complete 152 * 153 * @return VL53L1_ERROR_NONE Success 154 * @return "Other error code" See ::VL53L1_Error 155 */ 156 157 VL53L1_Error VL53L1_is_boot_complete( 158 VL53L1_DEV Dev, 159 uint8_t *pready); 160 161 /** 162 * @brief Reads FIRMWARE__SYSTEM_STATUS register to detect if the 163 * firmware is ready for ranging. 164 * 165 * @param[in] Dev : Device handle 166 * @param[out] pready : pointer to data ready flag \n 167 * 0 = firmware not ready \n 168 * 1 = firmware ready 169 * 170 * @return VL53L1_ERROR_NONE Success 171 * @return "Other error code" See ::VL53L1_Error 172 */ 173 174 VL53L1_Error VL53L1_is_firmware_ready( 175 VL53L1_DEV Dev, 176 uint8_t *pready); 177 178 179 /** 180 * @brief Reads bit 0 of VL53L1_GPIO__TIO_HV_STATUS register to determine 181 * if new range data is ready (available). 182 * 183 * Interrupt may be either active high or active low. The behaviour of bit 0 184 * of the VL53L1_GPIO__TIO_HV_STATUS register is the same as the interrupt 185 * signal generated on the GPIO pin. 186 * 187 * pdev->stat_cfg.gpio_hv_mux_ctrl bit 4 is used to select required check level 188 * 189 * 190 * @param[in] Dev : Device handle 191 * @param[out] pready : pointer to data ready flag \n 192 * 0 = data not ready \n 193 * 1 = new range data available 194 * 195 * @return VL53L1_ERROR_NONE Success 196 * @return "Other error code" See ::VL53L1_Error 197 */ 198 199 VL53L1_Error VL53L1_is_new_data_ready( 200 VL53L1_DEV Dev, 201 uint8_t *pready); 202 203 204 205 206 /** 207 * @brief Waits (polls) for initial firmware boot to finish 208 * 209 * After power on or a device reset via XSHUTDOWN EwokPlus25 firmware takes 210 * about 2ms to boot. During this boot sequence elected NVM data is copied 211 * to the device's Host & MCU G02 registers 212 * 213 * This function polls the FIRMWARE__SYSTEM_STATUS register to detect when 214 * firmware is ready. 215 * 216 * Polling is implemented using VL53L1_WaitValueMaskEx() 217 * 218 * @param[in] Dev : Device handle 219 * @param[in] timeout_ms : Wait timeout in [ms] 220 * 221 * @return VL53L1_ERROR_NONE Success 222 * @return "Other error code" See ::VL53L1_Error 223 */ 224 225 VL53L1_Error VL53L1_poll_for_boot_completion( 226 VL53L1_DEV Dev, 227 uint32_t timeout_ms); 228 229 230 /** 231 * @brief Waits (polls) for initial firmware ready 232 * 233 * Polling is implemented using VL53L1_WaitValueMaskEx() 234 * 235 * @param[in] Dev : Device handle 236 * @param[in] timeout_ms : Wait timeout in [ms] 237 * 238 * @return VL53L1_ERROR_NONE Success 239 * @return "Other error code" See ::VL53L1_Error 240 */ 241 242 VL53L1_Error VL53L1_poll_for_firmware_ready( 243 VL53L1_DEV Dev, 244 uint32_t timeout_ms); 245 246 247 /** 248 * @brief Polls bit 0 of VL53L1_GPIO__TIO_HV_STATUS register to determine 249 * the state of the GPIO (Interrupt) pin. 250 * 251 * Interrupt may be either active high or active low. The behaviour of bit 0 252 * of the VL53L1_GPIO__TIO_HV_STATUS register is the same as the interrupt 253 * signal generated on the GPIO pin. 254 * 255 * pdev->stat_cfg.gpio_hv_mux_ctrl bit 4 is used to select required check level 256 * 257 * Polling is implemented using VL53L1_WaitValueMaskEx() 258 * 259 * @param[in] Dev : Device handle 260 * @param[in] timeout_ms : Wait timeout in [ms] 261 * 262 * @return VL53L1_ERROR_NONE Success 263 * @return "Other error code" See ::VL53L1_Error 264 */ 265 266 VL53L1_Error VL53L1_poll_for_range_completion( 267 VL53L1_DEV Dev, 268 uint32_t timeout_ms); 269 270 271 272 #ifdef __cplusplus 273 } 274 #endif 275 276 #endif /* _VL53L1_WAIT_H_ */ 277
