VL53L0X_i2c_platform.h

00001 /*
00002  * COPYRIGHT (C) STMicroelectronics 2014. All rights reserved.
00003  *
00004  * This software is the confidential and proprietary information of
00005  * STMicroelectronics ("Confidential Information").  You shall not
00006  * disclose such Confidential Information and shall use it only in
00007  * accordance with the terms of the license agreement you entered into
00008  * with STMicroelectronics
00009  *
00010  * Programming Golden Rule: Keep it Simple!
00011  *
00012  */
00013 
00014 /**
00015  * @file   VL53L0X_platform.h
00016  * @brief  Function prototype definitions for Ewok Platform layer.
00017  *
00018  */
00019 
00020 
00021 #ifndef _VL53L0X_I2C_PLATFORM_H_
00022 #define _VL53L0X_I2C_PLATFORM_H_
00023 
00024 #include "VL53L0X_def.h"
00025 
00026 #ifdef __cplusplus
00027 extern "C" {
00028 #endif
00029 
00030 // Include uint8_t, unit16_t  etc definitions
00031 
00032 #include <stdint.h>
00033 #include <stdarg.h>
00034 
00035 
00036 /**
00037  *  @brief Typedef defining .\n
00038  * The developer shoud modify this to suit the platform being deployed.
00039  *
00040  */
00041 
00042 // enum  {TRUE = true, FALSE = false};
00043 
00044 /**
00045  * @brief Typedef defining 8 bit unsigned char type.\n
00046  * The developer shoud modify this to suit the platform being deployed.
00047  *
00048  */
00049 
00050 #ifndef bool_t
00051 typedef unsigned char bool_t;
00052 #endif
00053 
00054 
00055 #define    I2C                0x01
00056 #define    SPI                0x00
00057 
00058 #define    COMMS_BUFFER_SIZE    64  // MUST be the same size as the SV task buffer
00059 
00060 #define    BYTES_PER_WORD        2
00061 #define    BYTES_PER_DWORD       4
00062 
00063 #define    VL53L0X_MAX_STRING_LENGTH_PLT       256
00064 
00065 /**
00066  * @brief  Initialise platform comms.
00067  *
00068  * @param  comms_type      - selects between I2C and SPI
00069  * @param  comms_speed_khz - unsigned short containing the I2C speed in kHz
00070  *
00071  * @return status - status 0 = ok, 1 = error
00072  *
00073  */
00074 
00075 int32_t VL53L0X_comms_initialise(uint8_t  comms_type,
00076                                  uint16_t comms_speed_khz);
00077 
00078 /**
00079 * @brief  Initialise platform serial comms.
00080 *
00081 * @param  comPortStr   - String to indicate the comm port
00082 * @param  baudRate     - Bau rate
00083 *
00084 * @return status - status 0 = ok, 1 = error
00085 *
00086 */
00087 int VL53L0_i2c_init(char *comPortStr, unsigned int baudRate);
00088 
00089 
00090 /**
00091  * @brief  Close platform comms.
00092  *
00093  * @return status - status 0 = ok, 1 = error
00094  *
00095  */
00096 
00097 int32_t VL53L0X_comms_close(void);
00098 
00099 /**
00100  * @brief  Cycle Power to Device
00101  *
00102  * @return status - status 0 = ok, 1 = error
00103  *
00104  */
00105 
00106 int32_t VL53L0X_cycle_power(void);
00107 
00108 
00109 /**
00110  * @brief Writes the supplied byte buffer to the device
00111  *
00112  * Wrapper for SystemVerilog Write Multi task
00113  *
00114  * @code
00115  *
00116  * Example:
00117  *
00118  * uint8_t *spad_enables;
00119  *
00120  * int status = VL53L0X_write_multi(RET_SPAD_EN_0, spad_enables, 36);
00121  *
00122  * @endcode
00123  *
00124  * @param  address - uint8_t device address value
00125  * @param  index - uint8_t register index value
00126  * @param  pdata - pointer to uint8_t buffer containing the data to be written
00127  * @param  count - number of bytes in the supplied byte buffer
00128  *
00129  * @return status - SystemVerilog status 0 = ok, 1 = error
00130  *
00131  */
00132 
00133 int32_t VL53L0X_write_multi(uint8_t address, uint8_t index, uint8_t  *pdata, int32_t count);
00134 
00135 
00136 /**
00137  * @brief  Reads the requested number of bytes from the device
00138  *
00139  * Wrapper for SystemVerilog Read Multi task
00140  *
00141  * @code
00142  *
00143  * Example:
00144  *
00145  * uint8_t buffer[COMMS_BUFFER_SIZE];
00146  *
00147  * int status = status  = VL53L0X_read_multi(DEVICE_ID, buffer, 2)
00148  *
00149  * @endcode
00150  *
00151  * @param  address - uint8_t device address value
00152  * @param  index - uint8_t register index value
00153  * @param  pdata - pointer to the uint8_t buffer to store read data
00154  * @param  count - number of uint8_t's to read
00155  *
00156  * @return status - SystemVerilog status 0 = ok, 1 = error
00157  *
00158  */
00159 
00160 int32_t VL53L0X_read_multi(uint8_t address,  uint8_t index, uint8_t  *pdata, int32_t count);
00161 
00162 
00163 /**
00164  * @brief  Writes a single byte to the device
00165  *
00166  * Wrapper for SystemVerilog Write Byte task
00167  *
00168  * @code
00169  *
00170  * Example:
00171  *
00172  * uint8_t page_number = MAIN_SELECT_PAGE;
00173  *
00174  * int status = VL53L0X_write_byte(PAGE_SELECT, page_number);
00175  *
00176  * @endcode
00177  *
00178  * @param  address - uint8_t device address value
00179  * @param  index - uint8_t register index value
00180  * @param  data  - uint8_t data value to write
00181  *
00182  * @return status - SystemVerilog status 0 = ok, 1 = error
00183  *
00184  */
00185 
00186 int32_t VL53L0X_write_byte(uint8_t address,  uint8_t index, uint8_t   data);
00187 
00188 
00189 /**
00190  * @brief  Writes a single word (16-bit unsigned) to the device
00191  *
00192  * Manages the big-endian nature of the device (first byte written is the MS byte).
00193  * Uses SystemVerilog Write Multi task.
00194  *
00195  * @code
00196  *
00197  * Example:
00198  *
00199  * uint16_t nvm_ctrl_pulse_width = 0x0004;
00200  *
00201  * int status = VL53L0X_write_word(NVM_CTRL__PULSE_WIDTH_MSB, nvm_ctrl_pulse_width);
00202  *
00203  * @endcode
00204  *
00205  * @param  address - uint8_t device address value
00206  * @param  index - uint8_t register index value
00207  * @param  data  - uin16_t data value write
00208  *
00209  * @return status - SystemVerilog status 0 = ok, 1 = error
00210  *
00211  */
00212 
00213 int32_t VL53L0X_write_word(uint8_t address,  uint8_t index, uint16_t  data);
00214 
00215 
00216 /**
00217  * @brief  Writes a single dword (32-bit unsigned) to the device
00218  *
00219  * Manages the big-endian nature of the device (first byte written is the MS byte).
00220  * Uses SystemVerilog Write Multi task.
00221  *
00222  * @code
00223  *
00224  * Example:
00225  *
00226  * uint32_t nvm_data = 0x0004;
00227  *
00228  * int status = VL53L0X_write_dword(NVM_CTRL__DATAIN_MMM, nvm_data);
00229  *
00230  * @endcode
00231  *
00232  * @param  address - uint8_t device address value
00233  * @param  index - uint8_t register index value
00234  * @param  data  - uint32_t data value to write
00235  *
00236  * @return status - SystemVerilog status 0 = ok, 1 = error
00237  *
00238  */
00239 
00240 int32_t VL53L0X_write_dword(uint8_t address, uint8_t index, uint32_t  data);
00241 
00242 
00243 
00244 /**
00245  * @brief  Reads a single byte from the device
00246  *
00247  * Uses SystemVerilog Read Byte task.
00248  *
00249  * @code
00250  *
00251  * Example:
00252  *
00253  * uint8_t device_status = 0;
00254  *
00255  * int status = VL53L0X_read_byte(STATUS, &device_status);
00256  *
00257  * @endcode
00258  *
00259  * @param  address - uint8_t device address value
00260  * @param  index  - uint8_t register index value
00261  * @param  pdata  - pointer to uint8_t data value
00262  *
00263  * @return status - SystemVerilog status 0 = ok, 1 = error
00264  *
00265  */
00266 
00267 int32_t VL53L0X_read_byte(uint8_t address,  uint8_t index, uint8_t  *pdata);
00268 
00269 
00270 /**
00271  * @brief  Reads a single word (16-bit unsigned) from the device
00272  *
00273  * Manages the big-endian nature of the device (first byte read is the MS byte).
00274  * Uses SystemVerilog Read Multi task.
00275  *
00276  * @code
00277  *
00278  * Example:
00279  *
00280  * uint16_t timeout = 0;
00281  *
00282  * int status = VL53L0X_read_word(TIMEOUT_OVERALL_PERIODS_MSB, &timeout);
00283  *
00284  * @endcode
00285  *
00286  * @param  address - uint8_t device address value
00287  * @param  index  - uint8_t register index value
00288  * @param  pdata  - pointer to uint16_t data value
00289  *
00290  * @return status - SystemVerilog status 0 = ok, 1 = error
00291  *
00292  */
00293 
00294 int32_t VL53L0X_read_word(uint8_t address,  uint8_t index, uint16_t *pdata);
00295 
00296 
00297 /**
00298  * @brief  Reads a single dword (32-bit unsigned) from the device
00299  *
00300  * Manages the big-endian nature of the device (first byte read is the MS byte).
00301  * Uses SystemVerilog Read Multi task.
00302  *
00303  * @code
00304  *
00305  * Example:
00306  *
00307  * uint32_t range_1 = 0;
00308  *
00309  * int status = VL53L0X_read_dword(RANGE_1_MMM, &range_1);
00310  *
00311  * @endcode
00312  *
00313  * @param  address - uint8_t device address value
00314  * @param  index - uint8_t register index value
00315  * @param  pdata - pointer to uint32_t data value
00316  *
00317  * @return status - SystemVerilog status 0 = ok, 1 = error
00318  *
00319  */
00320 
00321 int32_t VL53L0X_read_dword(uint8_t address, uint8_t index, uint32_t *pdata);
00322 
00323 
00324 /**
00325  * @brief  Implements a programmable wait in us
00326  *
00327  * Wrapper for SystemVerilog Wait in micro seconds task
00328  *
00329  * @param  wait_us - integer wait in micro seconds
00330  *
00331  * @return status - SystemVerilog status 0 = ok, 1 = error
00332  *
00333  */
00334 
00335 int32_t VL53L0X_platform_wait_us(int32_t wait_us);
00336 
00337 
00338 /**
00339  * @brief  Implements a programmable wait in ms
00340  *
00341  * Wrapper for SystemVerilog Wait in milli seconds task
00342  *
00343  * @param  wait_ms - integer wait in milli seconds
00344  *
00345  * @return status - SystemVerilog status 0 = ok, 1 = error
00346  *
00347  */
00348 
00349 int32_t VL53L0X_wait_ms(int32_t wait_ms);
00350 
00351 
00352 /**
00353  * @brief Set GPIO value
00354  *
00355  * @param  level  - input  level - either 0 or 1
00356  *
00357  * @return status - SystemVerilog status 0 = ok, 1 = error
00358  *
00359  */
00360 
00361 int32_t VL53L0X_set_gpio(uint8_t  level);
00362 
00363 
00364 /**
00365  * @brief Get GPIO value
00366  *
00367  * @param  plevel - uint8_t pointer to store GPIO level (0 or 1)
00368  *
00369  * @return status - SystemVerilog status 0 = ok, 1 = error
00370  *
00371  */
00372 
00373 int32_t VL53L0X_get_gpio(uint8_t *plevel);
00374 
00375 /**
00376  * @brief Release force on GPIO
00377  *
00378  * @return status - SystemVerilog status 0 = ok, 1 = error
00379  *
00380  */
00381 
00382 int32_t VL53L0X_release_gpio(void);
00383 
00384 
00385 /**
00386 * @brief Get the frequency of the timer used for ranging results time stamps
00387 *
00388 * @param[out] ptimer_freq_hz : pointer for timer frequency
00389 *
00390 * @return status : 0 = ok, 1 = error
00391 *
00392 */
00393 
00394 int32_t VL53L0X_get_timer_frequency(int32_t *ptimer_freq_hz);
00395 
00396 /**
00397 * @brief Get the timer value in units of timer_freq_hz (see VL53L0X_get_timestamp_frequency())
00398 *
00399 * @param[out] ptimer_count : pointer for timer count value
00400 *
00401 * @return status : 0 = ok, 1 = error
00402 *
00403 */
00404 
00405 int32_t VL53L0X_get_timer_value(int32_t *ptimer_count);
00406 
00407 
00408 
00409 
00410 
00411 #ifdef __cplusplus
00412 }
00413 #endif
00414 
00415 #endif //_VL53L0X_I2C_PLATFORM_H_
00416 
00417