VL53L0X_platform.h

00001 /*******************************************************************************
00002 Copyright © 2015, 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 _VL53L0X_PLATFORM_H_
00031 #define _VL53L0X_PLATFORM_H_
00032 
00033 #include "VL53L0X_def.h"
00034 #include "VL53L0X_platform_log.h"
00035 #include "VL53L0X_i2c_platform.h"
00036 
00037 #ifdef __cplusplus
00038 extern "C" {
00039 #endif
00040 
00041 /**
00042  * @file vl53l0_platform.h
00043  *
00044  * @brief All end user OS/platform/application porting
00045  */
00046 
00047 /**
00048  * @defgroup VL53L0X_platform_group VL53L0 Platform Functions
00049  * @brief    VL53L0 Platform Functions
00050  *  @{
00051  */
00052 
00053 /**
00054  * @struct  VL53L0X_Dev_t
00055  * @brief    Generic PAL device type that does link between API and platform abstraction layer
00056  *
00057  */
00058 typedef struct {
00059     VL53L0X_DevData_t Data;               /*!< embed ST Ewok Dev  data as "Data"*/
00060 
00061     /*!< user specific field */
00062     uint8_t   I2cDevAddr ;                /*!< i2c device address user specific field */
00063     uint8_t   comms_type ;                /*!< Type of comms : VL53L0X_COMMS_I2C or VL53L0X_COMMS_SPI */
00064     uint16_t  comms_speed_khz ;           /*!< Comms speed [kHz] : typically 400kHz for I2C           */
00065 
00066 } VL53L0X_Dev_t;
00067 
00068 
00069 /**
00070  * @brief   Declare the device Handle as a pointer of the structure @a VL53L0X_Dev_t.
00071  *
00072  */
00073 typedef VL53L0X_Dev_t *VL53L0X_DEV;
00074 
00075 /**
00076  * @def PALDevDataGet
00077  * @brief Get ST private structure @a VL53L0X_DevData_t data access
00078  *
00079  * @param Dev       Device Handle
00080  * @param field     ST structure field name
00081  * It maybe used and as real data "ref" not just as "get" for sub-structure item
00082  * like PALDevDataGet(FilterData.field)[i] or PALDevDataGet(FilterData.MeasurementIndex)++
00083  */
00084 #define PALDevDataGet(Dev, field) (Dev->Data.field)
00085 
00086 /**
00087  * @def PALDevDataSet(Dev, field, data)
00088  * @brief  Set ST private structure @a VL53L0X_DevData_t data field
00089  * @param Dev       Device Handle
00090  * @param field     ST structure field name
00091  * @param data      Data to be set
00092  */
00093 #define PALDevDataSet(Dev, field, data) (Dev->Data.field)=(data)
00094 
00095 
00096 /**
00097  * @defgroup VL53L0X_registerAccess_group PAL Register Access Functions
00098  * @brief    PAL Register Access Functions
00099  *  @{
00100  */
00101 
00102 /**
00103  * Lock comms interface to serialize all commands to a shared I2C interface for a specific device
00104  * @param   Dev       Device Handle
00105  * @return  VL53L0X_ERROR_NONE        Success
00106  * @return  "Other error code"    See ::VL53L0X_Error
00107  */
00108 VL53L0X_Error VL53L0X_LockSequenceAccess(VL53L0X_DEV Dev);
00109 
00110 /**
00111  * Unlock comms interface to serialize all commands to a shared I2C interface for a specific device
00112  * @param   Dev       Device Handle
00113  * @return  VL53L0X_ERROR_NONE        Success
00114  * @return  "Other error code"    See ::VL53L0X_Error
00115  */
00116 VL53L0X_Error VL53L0X_UnlockSequenceAccess(VL53L0X_DEV Dev);
00117 
00118 
00119 /**
00120  * Writes the supplied byte buffer to the device
00121  * @param   Dev       Device Handle
00122  * @param   index     The register index
00123  * @param   pdata     Pointer to uint8_t buffer containing the data to be written
00124  * @param   count     Number of bytes in the supplied byte buffer
00125  * @return  VL53L0X_ERROR_NONE        Success
00126  * @return  "Other error code"    See ::VL53L0X_Error
00127  */
00128 VL53L0X_Error VL53L0X_WriteMulti(VL53L0X_DEV Dev, uint8_t index, uint8_t *pdata, uint32_t count);
00129 
00130 /**
00131  * Reads the requested number of bytes from the device
00132  * @param   Dev       Device Handle
00133  * @param   index     The register index
00134  * @param   pdata     Pointer to the uint8_t buffer to store read data
00135  * @param   count     Number of uint8_t's to read
00136  * @return  VL53L0X_ERROR_NONE        Success
00137  * @return  "Other error code"    See ::VL53L0X_Error
00138  */
00139 VL53L0X_Error VL53L0X_ReadMulti(VL53L0X_DEV Dev, uint8_t index, uint8_t *pdata, uint32_t count);
00140 
00141 /**
00142  * Write single byte register
00143  * @param   Dev       Device Handle
00144  * @param   index     The register index
00145  * @param   data      8 bit register data
00146  * @return  VL53L0X_ERROR_NONE        Success
00147  * @return  "Other error code"    See ::VL53L0X_Error
00148  */
00149 VL53L0X_Error VL53L0X_WrByte(VL53L0X_DEV Dev, uint8_t index, uint8_t data);
00150 
00151 /**
00152  * Write word register
00153  * @param   Dev       Device Handle
00154  * @param   index     The register index
00155  * @param   data      16 bit register data
00156  * @return  VL53L0X_ERROR_NONE        Success
00157  * @return  "Other error code"    See ::VL53L0X_Error
00158  */
00159 VL53L0X_Error VL53L0X_WrWord(VL53L0X_DEV Dev, uint8_t index, uint16_t data);
00160 
00161 /**
00162  * Write double word (4 byte) register
00163  * @param   Dev       Device Handle
00164  * @param   index     The register index
00165  * @param   data      32 bit register data
00166  * @return  VL53L0X_ERROR_NONE        Success
00167  * @return  "Other error code"    See ::VL53L0X_Error
00168  */
00169 VL53L0X_Error VL53L0X_WrDWord(VL53L0X_DEV Dev, uint8_t index, uint32_t data);
00170 
00171 /**
00172  * Read single byte register
00173  * @param   Dev       Device Handle
00174  * @param   index     The register index
00175  * @param   data      pointer to 8 bit data
00176  * @return  VL53L0X_ERROR_NONE        Success
00177  * @return  "Other error code"    See ::VL53L0X_Error
00178  */
00179 VL53L0X_Error VL53L0X_RdByte(VL53L0X_DEV Dev, uint8_t index, uint8_t *data);
00180 
00181 /**
00182  * Read word (2byte) register
00183  * @param   Dev       Device Handle
00184  * @param   index     The register index
00185  * @param   data      pointer to 16 bit data
00186  * @return  VL53L0X_ERROR_NONE        Success
00187  * @return  "Other error code"    See ::VL53L0X_Error
00188  */
00189 VL53L0X_Error VL53L0X_RdWord(VL53L0X_DEV Dev, uint8_t index, uint16_t *data);
00190 
00191 /**
00192  * Read dword (4byte) register
00193  * @param   Dev       Device Handle
00194  * @param   index     The register index
00195  * @param   data      pointer to 32 bit data
00196  * @return  VL53L0X_ERROR_NONE        Success
00197  * @return  "Other error code"    See ::VL53L0X_Error
00198  */
00199 VL53L0X_Error VL53L0X_RdDWord(VL53L0X_DEV Dev, uint8_t index, uint32_t *data);
00200 
00201 /**
00202  * Threat safe Update (read/modify/write) single byte register
00203  *
00204  * Final_reg = (Initial_reg & and_data) |or_data
00205  *
00206  * @param   Dev        Device Handle
00207  * @param   index      The register index
00208  * @param   AndData    8 bit and data
00209  * @param   OrData     8 bit or data
00210  * @return  VL53L0X_ERROR_NONE        Success
00211  * @return  "Other error code"    See ::VL53L0X_Error
00212  */
00213 VL53L0X_Error VL53L0X_UpdateByte(VL53L0X_DEV Dev, uint8_t index, uint8_t AndData, uint8_t OrData);
00214 
00215 /** @} end of VL53L0X_registerAccess_group */
00216 
00217 
00218 /**
00219  * @brief execute delay in all polling API call
00220  *
00221  * A typical multi-thread or RTOs implementation is to sleep the task for some 5ms (with 100Hz max rate faster polling is not needed)
00222  * if nothing specific is need you can define it as an empty/void macro
00223  * @code
00224  * #define VL53L0X_PollingDelay(...) (void)0
00225  * @endcode
00226  * @param Dev       Device Handle
00227  * @return  VL53L0X_ERROR_NONE        Success
00228  * @return  "Other error code"    See ::VL53L0X_Error
00229  */
00230 VL53L0X_Error VL53L0X_PollingDelay(VL53L0X_DEV Dev); /* usually best implemented as a real function */
00231 
00232 /** @} end of VL53L0X_platform_group */
00233 
00234 #ifdef __cplusplus
00235 }
00236 #endif
00237 
00238 #endif  /* _VL53L0X_PLATFORM_H_ */
00239 
00240 
00241 
00242