ChibiOS/EX  1.2.0
vl53l0x.h
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2016..2018 Edoardo Lombardi, Rocco Marco Guglielmi
3 
4  This file is part of ChibiOS.
5 
6  ChibiOS is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 3 of the License, or
9  (at your option) any later version.
10 
11  ChibiOS is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  GNU General Public License for more details.
15 
16  You should have received a copy of the GNU General Public License
17  along with this program. If not, see <http://www.gnu.org/licenses/>.
18 
19 */
20 
21 /**
22  * @file vl53l0x.h
23  * @brief VL53L0X MEMS interface module header.
24  *
25  * @addtogroup VL53L0X
26  * @ingroup EX_ST
27  * @{
28  */
29 #ifndef _VL53L0X_H_
30 #define _VL53L0X_H_
31 
32 #include "ex_rangefinder.h"
33 
34 /*===========================================================================*/
35 /* Driver constants. */
36 /*===========================================================================*/
37 
38 /**
39  * @name Version identification
40  * @{
41  */
42 /**
43  * @brief VL53L0X driver version string.
44  */
45 #define EX_VL53L0X_VERSION "1.0.0"
46 
47 /**
48  * @brief VL53L0X driver version major number.
49  */
50 #define EX_VL53L0X_MAJOR 1
51 
52 /**
53  * @brief VL53L0X driver version minor number.
54  */
55 #define EX_VL53L0X_MINOR 0
56 
57 /**
58  * @brief VL53L0X driver version patch number.
59  */
60 #define EX_VL53L0X_PATCH 0
61 /** @} */
62 
63 /**
64  * @brief VL53L0X rangefinder subsystem characteristics.
65  * @note Sensitivity is expressed as hPa/LSB whereas hPa stand for
66  * hectopascal.
67  * @note Bias is expressed as hPa.
68  *
69  * @{
70  */
71 #define VL53L0X_RANGE_NUMBER_OF_AXES 1U
72 
73 /* CHTODO: Check this. */
74 #define VL53L0X_RANGE_SENS 0.00024414f
75 #define VL53L0X_RANGE_BIAS 0.0f
76 /** @} */
77 
78 /**
79  * @name VL53L0X register addresses
80  * @{
81  */
82 #define VL53L0X_REG_SYSRANGE_START 0x00
83 #define VL53L0X_REG_SYSTEM_SEQUENCE_CONFIG 0x01
84 #define VL53L0X_REG_SYSTEM_INTERMEASUREMENT_PERIOD 0x04
85 #define VL53L0X_REG_SYSTEM_RANGE_CONFIG 0x09
86 #define VL53L0X_REG_SYSTEM_INTERRUPT_CONFIG_GPIO 0x0A
87 #define VL53L0X_REG_SYSTEM_INTERRUPT_CLEAR 0x0B
88 #define VL53L0X_REG_SYSTEM_THRESH_HIGH 0x0C
89 #define VL53L0X_REG_SYSTEM_THRESH_LOW 0x0E
90 
91 #define VL53L0X_REG_RESULT_INTERRUPT_STATUS 0x13
92 #define VL53L0X_REG_RESULT_RANGE_STATUS 0x14
93 
94 #define VL53L0X_REG_CROSSTALK_COMPENSATION_PEAK_RATE_MCPS 0x20
95 #define VL53L0X_REG_PRE_RANGE_CONFIG_MIN_SNR 0x27
96 #define VL53L0X_REG_ALGO_PART_TO_PART_RANGE_OFFSET_MM 0x28
97 #define VL53L0X_REG_ALGO_PHASECAL_LIM 0x30
98 #define VL53L0X_REG_ALGO_PHASECAL_CONFIG_TIMEOUT 0x30
99 #define VL53L0X_REG_GLOBAL_CONFIG_VCSEL_WIDTH 0x32
100 #define VL53L0X_REG_HISTOGRAM_CONFIG_INITIAL_PHASE_SELECT 0x33
101 
102 #define VL53L0X_REG_FINAL_RANGE_CONFIG_MIN_COUNT_RATE_RTN_LIMIT 0x44
103 #define VL53L0X_REG_FINAL_RANGE_CONFIG_VALID_PHASE_LOW 0x47
104 #define VL53L0X_REG_FINAL_RANGE_CONFIG_VALID_PHASE_HIGH 0x48
105 #define VL53L0X_REG_DYNAMIC_SPAD_NUM_REQUESTED_REF_SPAD 0x4E
106 #define VL53L0X_REG_DYNAMIC_SPAD_REF_EN_START_OFFSET 0x4F
107 
108 #define VL53L0X_REG_PRE_RANGE_CONFIG_VCSEL_PERIOD 0x50
109 #define VL53L0X_REG_PRE_RANGE_CONFIG_TIMEOUT_MACROP_HI 0x51
110 #define VL53L0X_REG_PRE_RANGE_CONFIG_TIMEOUT_MACROP_LO 0x52
111 #define VL53L0X_REG_HISTOGRAM_CONFIG_READOUT_CTRL 0x55
112 #define VL53L0X_REG_PRE_RANGE_CONFIG_VALID_PHASE_LOW 0x56
113 #define VL53L0X_REG_PRE_RANGE_CONFIG_VALID_PHASE_HIGH 0x57
114 
115 #define VL53L0X_REG_MSRC_CONFIG_CONTROL 0x60
116 #define VL53L0X_REG_PRE_RANGE_CONFIG_SIGMA_THRESH_HI 0x61
117 #define VL53L0X_REG_PRE_RANGE_CONFIG_SIGMA_THRESH_LO 0x62
118 #define VL53L0X_REG_PRE_RANGE_MIN_COUNT_RATE_RTN_LIMIT 0x64
119 #define VL53L0X_REG_FINAL_RANGE_CONFIG_MIN_SNR 0x67
120 
121 #define VL53L0X_REG_FINAL_RANGE_CONFIG_VCSEL_PERIOD 0x70
122 #define VL53L0X_REG_FINAL_RANGE_CONFIG_TIMEOUT_MACROP_HI 0x71
123 #define VL53L0X_REG_FINAL_RANGE_CONFIG_TIMEOUT_MACROP_LO 0x72
124 
125 #define VL53L0X_REG_POWER_MANAGEMENT_GO1_POWER_FORCE 0x80
126 #define VL53L0X_REG_SYSTEM_HISTOGRAM_BIN 0x81
127 #define VL53L0X_REG_GPIO_HV_MUX_ACTIVE_HIGH 0x84
128 #define VL53L0X_REG_VHV_CONFIG_PAD_SCL_SDA__EXTSUP_HV 0x89
129 #define VL53L0X_REG_I2C_SLAVE_DEVICE_ADDRESS 0x8A
130 
131 #define VL53L0X_REG_GLOBAL_CONFIG_SPAD_ENABLES_REF_0 0xB0
132 #define VL53L0X_REG_GLOBAL_CONFIG_SPAD_ENABLES_REF_1 0xB1
133 #define VL53L0X_REG_GLOBAL_CONFIG_SPAD_ENABLES_REF_2 0xB2
134 #define VL53L0X_REG_GLOBAL_CONFIG_SPAD_ENABLES_REF_3 0xB3
135 #define VL53L0X_REG_GLOBAL_CONFIG_SPAD_ENABLES_REF_4 0xB4
136 #define VL53L0X_REG_GLOBAL_CONFIG_SPAD_ENABLES_REF_5 0xB5
137 #define VL53L0X_REG_GLOBAL_CONFIG_REF_EN_START_SELECT 0xB6
138 #define VL53L0X_REG_RESULT_PEAK_SIGNAL_RATE_REF 0xB6
139 #define VL53L0X_REG_RESULT_CORE_AMBIENT_WINDOW_EVENTS_RTN 0xBC
140 #define VL53L0X_REG_SOFT_RESET_GO2_SOFT_RESET_N 0xBF
141 
142 #define VL53L0X_REG_RESULT_CORE_RANGING_TOTAL_EVENTS_RTN 0xC0
143 #define VL53L0X_REG_IDENTIFICATION_MODEL_ID 0xC0
144 #define VL53L0X_REG_IDENTIFICATION_REVISION_ID 0xC2
145 
146 #define VL53L0X_REG_RESULT_CORE_AMBIENT_WINDOW_EVENTS_REF 0xD0
147 #define VL53L0X_REG_RESULT_CORE_RANGING_TOTAL_EVENTS_REF 0xD4
148 
149 #define VL53L0X_REG_OSC_CALIBRATE_VAL 0xF8
150 /** @} */
151 
152 /**
153  * @name VL53L0X_INT_CFG register bits definitions
154  * @{
155  */
156 #define VL53L0X_INT_CFG_MASK 0xFF
157 #define VL53L0X_INT_CFG_PHE (1 << 0)
158 #define VL53L0X_INT_CFG_PLE (1 << 1)
159 #define VL53L0X_INT_CFG_LIR (1 << 2)
160 #define VL53L0X_INT_CFG_DIFF_EN (1 << 3)
161 #define VL53L0X_INT_CFG_RESET_AZ (1 << 4)
162 #define VL53L0X_INT_CFG_AUTOZERO (1 << 5)
163 #define VL53L0X_INT_CFG_RESET_ARP (1 << 6)
164 #define VL53L0X_INT_CFG_AUTORIFP (1 << 7)
165 /** @} */
166 
167 /**
168  * @name VL53L0X_CTRL_REG1 register bits definitions
169  * @{
170  */
171 #define VL53L0X_CTRL_REG1_MASK 0x7F
172 #define VL53L0X_CTRL_REG1_SIM (1 << 0)
173 #define VL53L0X_CTRL_REG1_BDU (1 << 1)
174 #define VL53L0X_CTRL_REG1_LPFP_CFG (1 << 2)
175 #define VL53L0X_CTRL_REG1_LPFP_EN (1 << 3)
176 #define VL53L0X_CTRL_REG1_ODR0 (1 << 4)
177 #define VL53L0X_CTRL_REG1_ODR1 (1 << 5)
178 #define VL53L0X_CTRL_REG1_ODR2 (1 << 6)
179 /** @} */
180 
181 /**
182  * @name VL53L0X_CTRL_REG2 register bits definitions
183  * @{
184  */
185 #define VL53L0X_CTRL_REG2_MASK 0xFD
186 #define VL53L0X_CTRL_REG2_ONE_SHOT (1 << 0)
187 #define VL53L0X_CTRL_REG2_SWRESET (1 << 2)
188 #define VL53L0X_CTRL_REG2_I2C_DIS (1 << 3)
189 #define VL53L0X_CTRL_REG2_IF_ADD_INC (1 << 4)
190 #define VL53L0X_CTRL_REG2_STOP_ON_FTH (1 << 5)
191 #define VL53L0X_CTRL_REG2_FIFO_EN (1 << 6)
192 #define VL53L0X_CTRL_REG2_BOOT (1 << 7)
193 /** @} */
194 
195 /**
196  * @name VL53L0X_CTRL_REG3 register bits definitions
197  * @{
198  */
199 #define VL53L0X_CTRL_REG3_MASK 0xFF
200 #define VL53L0X_CTRL_REG3_INT_S1 (1 << 0)
201 #define VL53L0X_CTRL_REG3_INT_S2 (1 << 1)
202 #define VL53L0X_CTRL_REG3_DRDY (1 << 2)
203 #define VL53L0X_CTRL_REG3_F_OVR (1 << 3)
204 #define VL53L0X_CTRL_REG3_F_FTH (1 << 4)
205 #define VL53L0X_CTRL_REG3_F_FSS5 (1 << 5)
206 #define VL53L0X_CTRL_REG3_PP_OD (1 << 6)
207 #define VL53L0X_CTRL_REG3_INT_H_L (1 << 7)
208 /** @} */
209 
210 /**
211  * @name VL53L0X_INT_SRC register bits definitions
212  * @{
213  */
214 #define VL53L0X_INT_SRC_MASK 0x87
215 #define VL53L0X_INT_SRC_PH (1 << 0)
216 #define VL53L0X_INT_SRC_PL (1 << 1)
217 #define VL53L0X_INT_SRC_IA (1 << 2)
218 #define VL53L0X_INT_SRC_BOOT_STATUS (1 << 8)
219 /** @} */
220 
221 /*===========================================================================*/
222 /* Driver pre-compile time settings. */
223 /*===========================================================================*/
224 
225 /**
226  * @name Configuration options
227  * @{
228  */
229 /**
230  * @brief VL53L0X I2C interface switch.
231  * @details If set to @p TRUE the support for I2C is included.
232  * @note The default is @p TRUE.
233  */
234 #if !defined(VL53L0X_USE_I2C) || defined(__DOXYGEN__)
235 #define VL53L0X_USE_I2C TRUE
236 #endif
237 
238 /**
239  * @brief VL53L0X shared I2C switch.
240  * @details If set to @p TRUE the device acquires I2C bus ownership
241  * on each transaction.
242  * @note The default is @p FALSE. Requires I2C_USE_MUTUAL_EXCLUSION.
243  */
244 #if !defined(VL53L0X_SHARED_I2C) || defined(__DOXYGEN__)
245 #define VL53L0X_SHARED_I2C FALSE
246 #endif
247 
248 /**
249  * @brief VL53L0X advanced configurations switch.
250  * @details If set to @p TRUE more configurations are available.
251  * @note The default is @p FALSE.
252  */
253 #if !defined(VL53L0X_USE_ADVANCED) || defined(__DOXYGEN__)
254 #define VL53L0X_USE_ADVANCED FALSE
255 #endif
256 /** @} */
257 
258 /*===========================================================================*/
259 /* Derived constants and error checks. */
260 /*===========================================================================*/
261 
262 #if VL53L0X_USE_I2C && !HAL_USE_I2C
263 #error "VL53L0X_USE_I2C requires HAL_USE_I2C"
264 #endif
265 
266 #if VL53L0X_SHARED_I2C && !I2C_USE_MUTUAL_EXCLUSION
267 #error "VL53L0X_SHARED_I2C requires I2C_USE_MUTUAL_EXCLUSION"
268 #endif
269 
270 /*===========================================================================*/
271 /* Driver data structures and types. */
272 /*===========================================================================*/
273 
274 /**
275  * @name VL53L0X data structures and types.
276  * @{
277  */
278 /**
279  * @brief Structure representing a VL53L0X driver.
280  */
281 typedef struct VL53L0XDriver VL53L0XDriver;
282 
283 /**
284  * @brief VL53L0X slave address
285  */
286 typedef enum {
287  VL53L0X_SAD_DEFAULT = 0x29, /**< Default slave address */
288 }vl53l0x_sad_t;
289 
290 /**
291  * @brief Driver state machine possible states.
292  */
293 typedef enum {
294  VL53L0X_UNINIT = 0, /**< Not initialized. */
295  VL53L0X_STOP = 1, /**< Stopped. */
296  VL53L0X_READY = 2, /**< Ready. */
297 } vl53l0x_state_t;
298 
299 /**
300  * @brief VL53L0X configuration structure.
301  */
302 typedef struct {
303 #if VL53L0X_USE_I2C || defined(__DOXYGEN__)
304  /**
305  * @brief I2C driver associated to this VL53L0X.
306  */
307  I2CDriver *i2cp;
308  /**
309  * @brief I2C configuration associated to this VL53L0X.
310  */
311  const I2CConfig *i2ccfg;
312  /**
313  * @brief VL53L0X slave address
314  */
315  vl53l0x_sad_t slaveaddress;
316 #endif /* VL53L0X_USE_I2C */
317 #if VL53L0X_USE_ADVANCED || defined(__DOXYGEN__)
318  /**
319  * @brief Dummy placeholder
320  */
321 #endif
322 } VL53L0XConfig;
323 
324 /**
325  * @brief @p VL53L0X specific methods.
326  * @note No methods so far, just a common ancestor interface.
327  */
328 #define _vl53l0x_methods_alone
329 
330 /**
331  * @brief @p VL53L0X specific methods with inherited ones.
332  */
333 #define _vl53l0x_methods \
334  _base_object_methods \
335  _vl53l0x_methods_alone
336 
337 /**
338  * @extends BaseObjectVMT
339  *
340  * @brief @p VL53L0X virtual methods table.
341  */
342 struct VL53L0XVMT {
343  _vl53l0x_methods
344 };
345 
346 /**
347  * @brief @p VL53L0XDriver specific data.
348  */
349 #define _vl53l0x_data \
350  /* Driver state.*/ \
351  vl53l0x_state_t state; \
352  /* Current configuration data.*/ \
353  const VL53L0XConfig *config; \
354  /* RangeFinder subsystem axes number.*/ \
355  size_t rangeaxes;
356 
357 /**
358  * @brief VL53L0X 2-axis rangemeter/thermometer class.
359  */
360 struct VL53L0XDriver {
361  /** @brief Virtual Methods Table.*/
362  const struct VL53L0XVMT *vmt;
363  /** @brief Base rangemeter interface.*/
364  BaseRangeFinder range_if;
365  _vl53l0x_data
366 };
367 /** @} */
368 
369 /*===========================================================================*/
370 /* Driver macros. */
371 /*===========================================================================*/
372 
373 /**
374  * @brief Return the number of axes of the BaseRangeFinder.
375  *
376  * @param[in] devp pointer to @p VL53L0XDriver.
377  *
378  * @return the number of axes.
379  *
380  * @api
381  */
382 #define vl53l0xRangeFinderGetAxesNumber(devp) \
383  rangemeterGetAxesNumber(&((devp)->range_if))
384 
385 /**
386  * @brief Retrieves raw data from the BaseRangeFinder.
387  * @note This data is retrieved from MEMS register without any algebraical
388  * manipulation.
389  * @note The axes array must be at least the same size of the
390  * BaseRangeFinder axes number.
391  *
392  * @param[in] devp pointer to @p VL53L0XDriver.
393  * @param[out] axes a buffer which would be filled with raw data.
394  *
395  * @return The operation status.
396  * @retval MSG_OK if the function succeeded.
397  * @retval MSG_RESET if one or more I2C errors occurred, the errors can
398  * be retrieved using @p i2cGetErrors().
399  * @retval MSG_TIMEOUT if a timeout occurred before operation end.
400  *
401  * @api
402  */
403 #define vl53l0xRangeFinderReadRaw(devp, axes) \
404  rangemeterReadRaw(&((devp)->range_if), axes)
405 
406 /**
407  * @brief Retrieves cooked data from the BaseRangeFinder.
408  * @note Final data is expressed as mm.
409  * @note The axes array must be at least the same size of the
410  * BaseRangeFinder axes number.
411  *
412  * @param[in] devp pointer to @p VL53L0XDriver.
413  * @param[out] axes a buffer which would be filled with cooked data.
414  *
415  * @return The operation status.
416  * @retval MSG_OK if the function succeeded.
417  * @retval MSG_RESET if one or more I2C errors occurred, the errors can
418  * be retrieved using @p i2cGetErrors().
419  * @retval MSG_TIMEOUT if a timeout occurred before operation end.
420  *
421  * @api
422  */
423 #define vl53l0xRangeFinderReadCooked(devp, axes) \
424  rangemeterReadCooked(&((devp)->range_if), axes)
425 
426 /*===========================================================================*/
427 /* External declarations. */
428 /*===========================================================================*/
429 
430 #ifdef __cplusplus
431 extern "C" {
432 #endif
433  void vl53l0xObjectInit(VL53L0XDriver *devp);
434  void vl53l0xStart(VL53L0XDriver *devp, const VL53L0XConfig *config);
435  void vl53l0xStop(VL53L0XDriver *devp);
436 #ifdef __cplusplus
437 }
438 #endif
439 
440 #endif /* _VL53L0X_H_ */
441 
442 /** @} */
443 
VL53L0X_STOP
@ VL53L0X_STOP
Definition: vl53l0x.h:295
VL53L0XConfig::i2ccfg
const I2CConfig * i2ccfg
I2C configuration associated to this VL53L0X.
Definition: vl53l0x.h:311
vl53l0x_state_t
vl53l0x_state_t
Driver state machine possible states.
Definition: vl53l0x.h:293
VL53L0X_READY
@ VL53L0X_READY
Definition: vl53l0x.h:296
BaseRangeFinder
Base rangefinder class.
Definition: ex_rangefinder.h:86
VL53L0XDriver::vmt
const struct VL53L0XVMT * vmt
Virtual Methods Table.
Definition: vl53l0x.h:362
VL53L0XDriver
VL53L0X 2-axis rangemeter/thermometer class.
Definition: vl53l0x.h:360
VL53L0XDriver::range_if
BaseRangeFinder range_if
Base rangemeter interface.
Definition: vl53l0x.h:364
VL53L0X_UNINIT
@ VL53L0X_UNINIT
Definition: vl53l0x.h:294
VL53L0XConfig::i2cp
I2CDriver * i2cp
I2C driver associated to this VL53L0X.
Definition: vl53l0x.h:307
ex_rangefinder.h
Generic rangefinder interface header.
VL53L0XConfig
VL53L0X configuration structure.
Definition: vl53l0x.h:302
VL53L0XConfig::slaveaddress
vl53l0x_sad_t slaveaddress
VL53L0X slave address.
Definition: vl53l0x.h:315
VL53L0X_SAD_DEFAULT
@ VL53L0X_SAD_DEFAULT
Definition: vl53l0x.h:287
VL53L0XVMT
VL53L0X virtual methods table.
Definition: vl53l0x.h:342
_vl53l0x_methods
#define _vl53l0x_methods
VL53L0X specific methods with inherited ones.
Definition: vl53l0x.h:333
_vl53l0x_data
#define _vl53l0x_data
VL53L0XDriver specific data.
Definition: vl53l0x.h:349
vl53l0x_sad_t
vl53l0x_sad_t
VL53L0X slave address.
Definition: vl53l0x.h:286