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