vl53l1_platform.h

00001 /*******************************************************************************
00002  Copyright (C) 2016, STMicroelectronics International N.V.
00003  All rights reserved.
00004 
00005  Redistribution and use in source and binary forms, with or without
00006  modification, are permitted provided that the following conditions are met:
00007  * Redistributions of source code must retain the above copyright
00008  notice, this list of conditions and the following disclaimer.
00009  * Redistributions in binary form must reproduce the above copyright
00010  notice, this list of conditions and the following disclaimer in the
00011  documentation and/or other materials provided with the distribution.
00012  * Neither the name of STMicroelectronics nor the
00013  names of its contributors may be used to endorse or promote products
00014  derived from this software without specific prior written permission.
00015 
00016  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00017  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00018  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
00019  NON-INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS ARE DISCLAIMED.
00020  IN NO EVENT SHALL STMICROELECTRONICS INTERNATIONAL N.V. BE LIABLE FOR ANY
00021  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00022  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00023  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00024  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00025  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00026  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00027  ******************************************************************************/
00028 
00029 
00030 #ifndef _VL53L1_PLATFORM_H_
00031 #define _VL53L1_PLATFORM_H_
00032 
00033 #include "vl53l1_ll_def.h"
00034 #include "vl53l1_platform_log.h"
00035 
00036 #define VL53L1_IPP_API
00037 #include "vl53l1_platform_ipp_imports.h"
00038 #include "vl53l1_platform_user_data.h"
00039 
00040 #ifdef __cplusplus
00041 extern "C"
00042 {
00043 #endif
00044 
00045 /**
00046  * @file   vl53l1_platform.h
00047  *
00048  * @brief  All end user OS/platform/application porting
00049  */
00050 
00051 
00052 
00053 /**
00054  * @brief  Initialise platform comms.
00055  *
00056  * @param[in]   pdev            : pointer to device structure (device handle)
00057  * @param[in]   comms_type      : selects between I2C and SPI
00058  * @param[in]   comms_speed_khz : unsigned short containing the I2C speed in kHz
00059  *
00060  * @return   VL53L1_ERROR_NONE    Success
00061  * @return  "Other error code"    See ::VL53L1_Error
00062  */
00063 
00064 VL53L1_Error VL53L1_CommsInitialise(
00065     VL53L1_Dev_t *pdev,
00066     uint8_t       comms_type,
00067     uint16_t      comms_speed_khz);
00068 
00069 
00070 /**
00071  * @brief  Close platform comms.
00072  *
00073  * @param[in]   pdev      : pointer to device structure (device handle)
00074  *
00075  * @return   VL53L1_ERROR_NONE    Success
00076  * @return  "Other error code"    See ::VL53L1_Error
00077  */
00078 
00079 VL53L1_Error VL53L1_CommsClose(
00080     VL53L1_Dev_t *pdev);
00081 
00082 
00083 /**
00084  * @brief Writes the supplied byte buffer to the device
00085  *
00086  * @param[in]   pdev      : pointer to device structure (device handle)
00087  * @param[in]   index     : uint16_t register index value
00088  * @param[in]   pdata     : pointer to uint8_t (byte) buffer containing the data to be written
00089  * @param[in]   count     : number of bytes in the supplied byte buffer
00090  *
00091  * @return   VL53L1_ERROR_NONE    Success
00092  * @return  "Other error code"    See ::VL53L1_Error
00093  */
00094 
00095 VL53L1_Error VL53L1_WriteMulti(
00096         VL53L1_Dev_t *pdev,
00097         uint16_t      index,
00098         uint8_t      *pdata,
00099         uint32_t      count);
00100 
00101 
00102 /**
00103  * @brief  Reads the requested number of bytes from the device
00104  *
00105  * @param[in]   pdev      : pointer to device structure (device handle)
00106  * @param[in]   index     : uint16_t register index value
00107  * @param[out]  pdata     : pointer to the uint8_t (byte) buffer to store read data
00108  * @param[in]   count     : number of bytes to read
00109  *
00110  * @return   VL53L1_ERROR_NONE    Success
00111  * @return  "Other error code"    See ::VL53L1_Error
00112  */
00113 
00114 VL53L1_Error VL53L1_ReadMulti(
00115         VL53L1_Dev_t *pdev,
00116         uint16_t      index,
00117         uint8_t      *pdata,
00118         uint32_t      count);
00119 
00120 
00121 /**
00122  * @brief  Writes a single byte to the device
00123  *
00124  * @param[in]   pdev      : pointer to device structure (device handle)
00125  * @param[in]   index     : uint16_t register index value
00126  * @param[in]   data      : uint8_t data value to write
00127  *
00128  * @return   VL53L1_ERROR_NONE    Success
00129  * @return  "Other error code"    See ::VL53L1_Error
00130  */
00131 
00132 VL53L1_Error VL53L1_WrByte(
00133         VL53L1_Dev_t *pdev,
00134         uint16_t      index,
00135         uint8_t       data);
00136 
00137 
00138 /**
00139  * @brief  Writes a single word (16-bit unsigned) to the device
00140  *
00141  * Manages the big-endian nature of the device register map
00142  * (first byte written is the MS byte).
00143  *
00144  * @param[in]   pdev      : pointer to device structure (device handle)
00145  * @param[in]   index     : uint16_t register index value
00146  * @param[in]   data      : uin16_t data value write
00147  *
00148  * @return   VL53L1_ERROR_NONE    Success
00149  * @return  "Other error code"    See ::VL53L1_Error
00150  */
00151 
00152 VL53L1_Error VL53L1_WrWord(
00153         VL53L1_Dev_t *pdev,
00154         uint16_t      index,
00155         uint16_t      data);
00156 
00157 
00158 /**
00159  * @brief  Writes a single dword (32-bit unsigned) to the device
00160  *
00161  * Manages the big-endian nature of the device register map
00162  * (first byte written is the MS byte).
00163  *
00164  * @param[in]   pdev      : pointer to device structure (device handle)
00165  * @param[in]   index     : uint16_t register index value
00166  * @param[in]   data      : uint32_t data value to write
00167  *
00168  * @return   VL53L1_ERROR_NONE    Success
00169  * @return  "Other error code"    See ::VL53L1_Error
00170  */
00171 
00172 VL53L1_Error VL53L1_WrDWord(
00173         VL53L1_Dev_t *pdev,
00174         uint16_t      index,
00175         uint32_t      data);
00176 
00177 
00178 
00179 /**
00180  * @brief  Reads a single byte from the device
00181  *
00182  * @param[in]   pdev      : pointer to device structure (device handle)
00183  * @param[in]   index     : uint16_t register index
00184  * @param[out]  pdata     : pointer to uint8_t data value
00185  *
00186  * @return   VL53L1_ERROR_NONE    Success
00187  * @return  "Other error code"    See ::VL53L1_Error
00188  *
00189  */
00190 
00191 VL53L1_Error VL53L1_RdByte(
00192         VL53L1_Dev_t *pdev,
00193         uint16_t      index,
00194         uint8_t      *pdata);
00195 
00196 
00197 /**
00198  * @brief  Reads a single word (16-bit unsigned) from the device
00199  *
00200  * Manages the big-endian nature of the device (first byte read is the MS byte).
00201  *
00202  * @param[in]   pdev      : pointer to device structure (device handle)
00203  * @param[in]   index     : uint16_t register index value
00204  * @param[out]  pdata     : pointer to uint16_t data value
00205  *
00206  * @return   VL53L1_ERROR_NONE    Success
00207  * @return  "Other error code"    See ::VL53L1_Error
00208  */
00209 
00210 VL53L1_Error VL53L1_RdWord(
00211         VL53L1_Dev_t *pdev,
00212         uint16_t      index,
00213         uint16_t     *pdata);
00214 
00215 
00216 /**
00217  * @brief  Reads a single dword (32-bit unsigned) from the device
00218  *
00219  * Manages the big-endian nature of the device (first byte read is the MS byte).
00220  *
00221  * @param[in]   pdev      : pointer to device structure (device handle)
00222  * @param[in]   index     : uint16_t register index value
00223  * @param[out]  pdata     : pointer to uint32_t data value
00224  *
00225  * @return   VL53L1_ERROR_NONE    Success
00226  * @return  "Other error code"    See ::VL53L1_Error
00227  */
00228 
00229 VL53L1_Error VL53L1_RdDWord(
00230         VL53L1_Dev_t *pdev,
00231         uint16_t      index,
00232         uint32_t     *pdata);
00233 
00234 
00235 
00236 /**
00237  * @brief  Implements a programmable wait in us
00238  *
00239  * @param[in]   pdev      : pointer to device structure (device handle)
00240  * @param[in]   wait_us   : integer wait in micro seconds
00241  *
00242  * @return  VL53L1_ERROR_NONE     Success
00243  * @return  "Other error code"    See ::VL53L1_Error
00244  */
00245 
00246 VL53L1_Error VL53L1_WaitUs(
00247         VL53L1_Dev_t *pdev,
00248         int32_t       wait_us);
00249 
00250 
00251 /**
00252  * @brief  Implements a programmable wait in ms
00253  *
00254  * @param[in]   pdev      : pointer to device structure (device handle)
00255  * @param[in]   wait_ms   : integer wait in milliseconds
00256  *
00257  * @return  VL53L1_ERROR_NONE     Success
00258  * @return  "Other error code"    See ::VL53L1_Error
00259  */
00260 
00261 VL53L1_Error VL53L1_WaitMs(
00262         VL53L1_Dev_t *pdev,
00263         int32_t       wait_ms);
00264 
00265 
00266 /**
00267 * @brief Get the frequency of the timer used for ranging results time stamps
00268 *
00269 * @param[out] ptimer_freq_hz : pointer for timer frequency
00270 *
00271  * @return  VL53L1_ERROR_NONE     Success
00272  * @return  "Other error code"    See ::VL53L1_Error
00273 */
00274 
00275 VL53L1_Error VL53L1_GetTimerFrequency(int32_t *ptimer_freq_hz);
00276 
00277 /**
00278 * @brief Get the timer value in units of timer_freq_hz (see VL53L1_get_timestamp_frequency())
00279 *
00280 * @param[out] ptimer_count : pointer for timer count value
00281 *
00282  * @return  VL53L1_ERROR_NONE     Success
00283  * @return  "Other error code"    See ::VL53L1_Error
00284 */
00285 
00286 VL53L1_Error VL53L1_GetTimerValue(int32_t *ptimer_count);
00287 
00288 
00289 /**
00290  * @brief Set the mode of a specified GPIO pin
00291  *
00292  * @param  pin - an identifier specifying the pin being modified - defined per platform
00293  *
00294  * @param  mode - an identifier specifying the requested mode - defined per platform
00295  *
00296  * @return  VL53L1_ERROR_NONE     Success
00297  * @return  "Other error code"    See ::VL53L1_Error
00298  */
00299 
00300 VL53L1_Error VL53L1_GpioSetMode(uint8_t pin, uint8_t mode);
00301 
00302 
00303 /**
00304  * @brief Set the value of a specified GPIO pin
00305  *
00306  * @param  pin - an identifier specifying the pin being modified - defined per platform
00307  *
00308  * @param  value - a value to set on the GPIO pin - typically 0 or 1
00309  *
00310  * @return  VL53L1_ERROR_NONE     Success
00311  * @return  "Other error code"    See ::VL53L1_Error
00312  */
00313 
00314 VL53L1_Error VL53L1_GpioSetValue(uint8_t pin, uint8_t value);
00315 
00316 
00317 /**
00318  * @brief Get the value of a specified GPIO pin
00319  *
00320  * @param  pin - an identifier specifying the pin being modified - defined per platform
00321  *
00322  * @param  pvalue - a value retrieved from the GPIO pin - typically 0 or 1
00323  *
00324  * @return  VL53L1_ERROR_NONE     Success
00325  * @return  "Other error code"    See ::VL53L1_Error
00326  */
00327 
00328 VL53L1_Error VL53L1_GpioGetValue(uint8_t pin, uint8_t *pvalue);
00329 
00330 
00331 /**
00332  * @brief Sets and clears the XShutdown pin on the Ewok
00333  *
00334  * @param  value - the value for xshutdown - 0 = in reset, 1 = operational
00335  *
00336  * @return  VL53L1_ERROR_NONE     Success
00337  * @return  "Other error code"    See ::VL53L1_Error
00338  */
00339 
00340 VL53L1_Error VL53L1_GpioXshutdown(uint8_t value);
00341 
00342 
00343 /**
00344  * @brief Sets and clears the Comms Mode pin (NCS) on the Ewok
00345  *
00346  * @param  value - the value for comms select - 0 = I2C, 1 = SPI
00347  *
00348  * @return  VL53L1_ERROR_NONE     Success
00349  * @return  "Other error code"    See ::VL53L1_Error
00350  */
00351 
00352 VL53L1_Error VL53L1_GpioCommsSelect(uint8_t value);
00353 
00354 
00355 /**
00356  * @brief Enables and disables the power to the Ewok module
00357  *
00358  * @param  value - the state of the power supply - 0 = power off, 1 = power on
00359  *
00360  * @return  VL53L1_ERROR_NONE     Success
00361  * @return  "Other error code"    See ::VL53L1_Error
00362  */
00363 
00364 VL53L1_Error VL53L1_GpioPowerEnable(uint8_t value);
00365 
00366 /**
00367  * @brief Enables callbacks to the supplied funtion pointer when Ewok interrupts ocurr
00368  *
00369  * @param  function - a function callback supplies by the caller, for interrupt notification
00370  * @param  edge_type - falling edge or rising edge interrupt detection
00371  *
00372  * @return  VL53L1_ERROR_NONE     Success
00373  * @return  "Other error code"    See ::VL53L1_Error
00374  */
00375 
00376 VL53L1_Error  VL53L1_GpioInterruptEnable(void (*function)(void), uint8_t edge_type);
00377 
00378 
00379 /**
00380  * @brief Disables the callback on Ewok interrupts
00381  *
00382  * @return  VL53L1_ERROR_NONE     Success
00383  * @return  "Other error code"    See ::VL53L1_Error
00384  */
00385 
00386 VL53L1_Error  VL53L1_GpioInterruptDisable(void);
00387 
00388 
00389 /*
00390  * @brief Gets current system tick count in [ms]
00391  *
00392  * @return  time_ms : current time in [ms]
00393  *
00394  * @return  VL53L1_ERROR_NONE     Success
00395  * @return  "Other error code"    See ::VL53L1_Error
00396  */
00397 
00398 VL53L1_Error VL53L1_GetTickCount(
00399     uint32_t *ptime_ms);
00400 
00401 
00402 /**
00403  * @brief Register "wait for value" polling routine
00404  *
00405  * Port of the V2WReg Script function  WaitValueMaskEx()
00406  *
00407  * @param[in]   pdev          : pointer to device structure (device handle)
00408  * @param[in]   timeout_ms    : timeout in [ms]
00409  * @param[in]   index         : uint16_t register index value
00410  * @param[in]   value         : value to wait for
00411  * @param[in]   mask          : mask to be applied before comparison with value
00412  * @param[in]   poll_delay_ms : polling delay been each read transaction in [ms]
00413  *
00414  * @return  VL53L1_ERROR_NONE     Success
00415  * @return  "Other error code"    See ::VL53L1_Error
00416  */
00417 
00418 VL53L1_Error VL53L1_WaitValueMaskEx(
00419         VL53L1_Dev_t *pdev,
00420         uint32_t      timeout_ms,
00421         uint16_t      index,
00422         uint8_t       value,
00423         uint8_t       mask,
00424         uint32_t      poll_delay_ms);
00425 
00426 #ifdef __cplusplus
00427 }
00428 #endif
00429 
00430 #endif
00431 
00432