Statistics
| Branch: | Tag: | Revision:

amiro-lld / include / VL53L0X / v1 / Api_vl53l0x / core / inc / vl53l0x_api.h @ 6ebebd4d

History | View | Annotate | Download (73.3 KB)

1 6ebebd4d Andre Raming
/*******************************************************************************
2
 Copyright � 2016, STMicroelectronics International N.V.
3
 All rights reserved.
4

5
 Redistribution and use in source and binary forms, with or without
6
 modification, are permitted provided that the following conditions are met:
7
 * Redistributions of source code must retain the above copyright
8
 notice, this list of conditions and the following disclaimer.
9
 * Redistributions in binary form must reproduce the above copyright
10
 notice, this list of conditions and the following disclaimer in the
11
 documentation and/or other materials provided with the distribution.
12
 * Neither the name of STMicroelectronics nor the
13
 names of its contributors may be used to endorse or promote products
14
 derived from this software without specific prior written permission.
15

16
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18
 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
19
 NON-INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS ARE DISCLAIMED.
20
 IN NO EVENT SHALL STMICROELECTRONICS INTERNATIONAL N.V. BE LIABLE FOR ANY
21
 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23
 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24
 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
26
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27
 *****************************************************************************/
28
29
#ifndef _VL53L0X_API_H_
30
#define _VL53L0X_API_H_
31
32
33
34
#include "vl53l0x_api_strings.h"
35
#include "vl53l0x_def.h"
36
#include "vl53l0x_platform.h"
37
38
//#include "alld_vl53l0x.h"
39
40
41
#ifdef __cplusplus
42
extern "C"
43
{
44
#endif
45
46
//#ifdef _MSC_VER
47
//#   ifdef VL53L0X_API_EXPORTS
48
//#       define VL53L0X_API  __declspec(dllexport)
49
//#   else
50
//#       define VL53L0X_API
51
//#   endif
52
//#else
53
#define VL53L0X_API
54
//#endif
55
56
57
58
#define USE_I2C_2V8
59
60
/** @defgroup VL53L0X_cut11_group VL53L0X cut1.1 Function Definition
61
 *  @brief    VL53L0X cut1.1 Function Definition
62
 *  @{
63
 */
64
65
/** @defgroup VL53L0X_general_group VL53L0X General Functions
66
 *  @brief    General functions and definitions
67
 *  @{
68
 */
69
70
/**
71
 * @brief Return the VL53L0X PAL Implementation Version
72
 *
73
 * @note This function doesn't access to the device
74
 *
75
 * @param   pVersion              Pointer to current PAL Implementation Version
76
 * @return  VL53L0X_ERROR_NONE     Success
77
 * @return  "Other error code"    See ::VL53L0X_Error
78
 */
79
VL53L0X_API VL53L0X_Error VL53L0X_GetVersion(VL53L0X_Version_t *pVersion);
80
81
/**
82
 * @brief Return the PAL Specification Version used for the current
83
 * implementation.
84
 *
85
 * @note This function doesn't access to the device
86
 *
87
 * @param   pPalSpecVersion       Pointer to current PAL Specification Version
88
 * @return  VL53L0X_ERROR_NONE        Success
89
 * @return  "Other error code"    See ::VL53L0X_Error
90
 */
91
VL53L0X_API VL53L0X_Error VL53L0X_GetPalSpecVersion(
92
    VL53L0X_Version_t *pPalSpecVersion);
93
94
/**
95
 * @brief Reads the Product Revision for a for given Device
96
 * This function can be used to distinguish cut1.0 from cut1.1.
97
 *
98
 * @note This function Access to the device
99
 *
100
 * @param   Dev                 Device Handle
101
 * @param   pProductRevisionMajor  Pointer to Product Revision Major
102
 * for a given Device
103
 * @param   pProductRevisionMinor  Pointer to Product Revision Minor
104
 * for a given Device
105
 * @return  VL53L0X_ERROR_NONE      Success
106
 * @return  "Other error code"  See ::VL53L0X_Error
107
 */
108
VL53L0X_API VL53L0X_Error VL53L0X_GetProductRevision(VL53L0X_DEV Dev,
109
    uint8_t *pProductRevisionMajor, uint8_t *pProductRevisionMinor);
110
111
/**
112
 * @brief Reads the Device information for given Device
113
 *
114
 * @note This function Access to the device
115
 *
116
 * @param   Dev                 Device Handle
117
 * @param   pVL53L0X_DeviceInfo  Pointer to current device info for a given
118
 *  Device
119
 * @return  VL53L0X_ERROR_NONE   Success
120
 * @return  "Other error code"  See ::VL53L0X_Error
121
 */
122
VL53L0X_API VL53L0X_Error VL53L0X_GetDeviceInfo(VL53L0X_DEV Dev,
123
    VL53L0X_DeviceInfo_t *pVL53L0X_DeviceInfo);
124
125
/**
126
 * @brief Read current status of the error register for the selected device
127
 *
128
 * @note This function Access to the device
129
 *
130
 * @param   Dev                   Device Handle
131
 * @param   pDeviceErrorStatus    Pointer to current error code of the device
132
 * @return  VL53L0X_ERROR_NONE     Success
133
 * @return  "Other error code"    See ::VL53L0X_Error
134
 */
135
VL53L0X_API VL53L0X_Error VL53L0X_GetDeviceErrorStatus(VL53L0X_DEV Dev,
136
    VL53L0X_DeviceError *pDeviceErrorStatus);
137
138
/**
139
 * @brief Human readable Range Status string for a given RangeStatus
140
 *
141
 * @note This function doesn't access to the device
142
 *
143
 * @param   RangeStatus         The RangeStatus code as stored on
144
 * @a VL53L0X_RangingMeasurementData_t
145
 * @param   pRangeStatusString  The returned RangeStatus string.
146
 * @return  VL53L0X_ERROR_NONE   Success
147
 * @return  "Other error code"  See ::VL53L0X_Error
148
 */
149
VL53L0X_API VL53L0X_Error VL53L0X_GetRangeStatusString(uint8_t RangeStatus,
150
    char *pRangeStatusString);
151
152
/**
153
 * @brief Human readable error string for a given Error Code
154
 *
155
 * @note This function doesn't access to the device
156
 *
157
 * @param   ErrorCode           The error code as stored on ::VL53L0X_DeviceError
158
 * @param   pDeviceErrorString  The error string corresponding to the ErrorCode
159
 * @return  VL53L0X_ERROR_NONE   Success
160
 * @return  "Other error code"  See ::VL53L0X_Error
161
 */
162
VL53L0X_API VL53L0X_Error VL53L0X_GetDeviceErrorString(
163
    VL53L0X_DeviceError ErrorCode, char *pDeviceErrorString);
164
165
/**
166
 * @brief Human readable error string for current PAL error status
167
 *
168
 * @note This function doesn't access to the device
169
 *
170
 * @param   PalErrorCode       The error code as stored on @a VL53L0X_Error
171
 * @param   pPalErrorString    The error string corresponding to the
172
 * PalErrorCode
173
 * @return  VL53L0X_ERROR_NONE  Success
174
 * @return  "Other error code" See ::VL53L0X_Error
175
 */
176
VL53L0X_API VL53L0X_Error VL53L0X_GetPalErrorString(VL53L0X_Error PalErrorCode,
177
    char *pPalErrorString);
178
179
/**
180
 * @brief Human readable PAL State string
181
 *
182
 * @note This function doesn't access to the device
183
 *
184
 * @param   PalStateCode          The State code as stored on @a VL53L0X_State
185
 * @param   pPalStateString       The State string corresponding to the
186
 * PalStateCode
187
 * @return  VL53L0X_ERROR_NONE     Success
188
 * @return  "Other error code"    See ::VL53L0X_Error
189
 */
190
VL53L0X_API VL53L0X_Error VL53L0X_GetPalStateString(VL53L0X_State PalStateCode,
191
    char *pPalStateString);
192
193
/**
194
 * @brief Reads the internal state of the PAL for a given Device
195
 *
196
 * @note This function doesn't access to the device
197
 *
198
 * @param   Dev                   Device Handle
199
 * @param   pPalState             Pointer to current state of the PAL for a
200
 * given Device
201
 * @return  VL53L0X_ERROR_NONE     Success
202
 * @return  "Other error code"    See ::VL53L0X_Error
203
 */
204
VL53L0X_API VL53L0X_Error VL53L0X_GetPalState(VL53L0X_DEV Dev,
205
    VL53L0X_State *pPalState);
206
207
/**
208
 * @brief Set the power mode for a given Device
209
 * The power mode can be Standby or Idle. Different level of both Standby and
210
 * Idle can exists.
211
 * This function should not be used when device is in Ranging state.
212
 *
213
 * @note This function Access to the device
214
 *
215
 * @param   Dev                   Device Handle
216
 * @param   PowerMode             The value of the power mode to set.
217
 * see ::VL53L0X_PowerModes
218
 *                                Valid values are:
219
 *                                VL53L0X_POWERMODE_STANDBY_LEVEL1,
220
 *                                VL53L0X_POWERMODE_IDLE_LEVEL1
221
 * @return  VL53L0X_ERROR_NONE                  Success
222
 * @return  VL53L0X_ERROR_MODE_NOT_SUPPORTED    This error occurs when PowerMode
223
 * is not in the supported list
224
 * @return  "Other error code"    See ::VL53L0X_Error
225
 */
226
VL53L0X_API VL53L0X_Error VL53L0X_SetPowerMode(VL53L0X_DEV Dev,
227
    VL53L0X_PowerModes PowerMode);
228
229
/**
230
 * @brief Get the power mode for a given Device
231
 *
232
 * @note This function Access to the device
233
 *
234
 * @param   Dev                   Device Handle
235
 * @param   pPowerMode            Pointer to the current value of the power
236
 * mode. see ::VL53L0X_PowerModes
237
 *                                Valid values are:
238
 *                                VL53L0X_POWERMODE_STANDBY_LEVEL1,
239
 *                                VL53L0X_POWERMODE_IDLE_LEVEL1
240
 * @return  VL53L0X_ERROR_NONE     Success
241
 * @return  "Other error code"    See ::VL53L0X_Error
242
 */
243
VL53L0X_API VL53L0X_Error VL53L0X_GetPowerMode(VL53L0X_DEV Dev,
244
    VL53L0X_PowerModes *pPowerMode);
245
246
/**
247
 * Set or over-hide part to part calibration offset
248
 * \sa VL53L0X_DataInit()   VL53L0X_GetOffsetCalibrationDataMicroMeter()
249
 *
250
 * @note This function Access to the device
251
 *
252
 * @param   Dev                                Device Handle
253
 * @param   OffsetCalibrationDataMicroMeter    Offset (microns)
254
 * @return  VL53L0X_ERROR_NONE                  Success
255
 * @return  "Other error code"                 See ::VL53L0X_Error
256
 */
257
VL53L0X_API VL53L0X_Error VL53L0X_SetOffsetCalibrationDataMicroMeter(
258
    VL53L0X_DEV Dev, int32_t OffsetCalibrationDataMicroMeter);
259
260
/**
261
 * @brief Get part to part calibration offset
262
 *
263
 * @par Function Description
264
 * Should only be used after a successful call to @a VL53L0X_DataInit to backup
265
 * device NVM value
266
 *
267
 * @note This function Access to the device
268
 *
269
 * @param   Dev                                Device Handle
270
 * @param   pOffsetCalibrationDataMicroMeter   Return part to part
271
 * calibration offset from device (microns)
272
 * @return  VL53L0X_ERROR_NONE                  Success
273
 * @return  "Other error code"                 See ::VL53L0X_Error
274
 */
275
VL53L0X_API VL53L0X_Error VL53L0X_GetOffsetCalibrationDataMicroMeter(
276
    VL53L0X_DEV Dev, int32_t *pOffsetCalibrationDataMicroMeter);
277
278
/**
279
 * Set the linearity corrective gain
280
 *
281
 * @note This function Access to the device
282
 *
283
 * @param   Dev                                Device Handle
284
 * @param   LinearityCorrectiveGain            Linearity corrective
285
 * gain in x1000
286
 * if value is 1000 then no modification is applied.
287
 * @return  VL53L0X_ERROR_NONE                  Success
288
 * @return  "Other error code"                 See ::VL53L0X_Error
289
 */
290
VL53L0X_API VL53L0X_Error VL53L0X_SetLinearityCorrectiveGain(VL53L0X_DEV Dev,
291
    int16_t LinearityCorrectiveGain);
292
293
/**
294
 * @brief Get the linearity corrective gain
295
 *
296
 * @par Function Description
297
 * Should only be used after a successful call to @a VL53L0X_DataInit to backup
298
 * device NVM value
299
 *
300
 * @note This function Access to the device
301
 *
302
 * @param   Dev                                Device Handle
303
 * @param   pLinearityCorrectiveGain           Pointer to the linearity
304
 * corrective gain in x1000
305
 * if value is 1000 then no modification is applied.
306
 * @return  VL53L0X_ERROR_NONE                  Success
307
 * @return  "Other error code"                 See ::VL53L0X_Error
308
 */
309
VL53L0X_API VL53L0X_Error VL53L0X_GetLinearityCorrectiveGain(VL53L0X_DEV Dev,
310
    uint16_t *pLinearityCorrectiveGain);
311
312
/**
313
 * Set Group parameter Hold state
314
 *
315
 * @par Function Description
316
 * Set or remove device internal group parameter hold
317
 *
318
 * @note This function is not Implemented
319
 *
320
 * @param   Dev      Device Handle
321
 * @param   GroupParamHold   Group parameter Hold state to be set (on/off)
322
 * @return  VL53L0X_ERROR_NOT_IMPLEMENTED        Not implemented
323
 */
324
VL53L0X_API VL53L0X_Error VL53L0X_SetGroupParamHold(VL53L0X_DEV Dev,
325
    uint8_t GroupParamHold);
326
327
/**
328
 * @brief Get the maximal distance for actual setup
329
 * @par Function Description
330
 * Device must be initialized through @a VL53L0X_SetParameters() prior calling
331
 * this function.
332
 *
333
 * Any range value more than the value returned is to be considered as
334
 * "no target detected" or
335
 * "no target in detectable range"\n
336
 * @warning The maximal distance depends on the setup
337
 *
338
 * @note This function is not Implemented
339
 *
340
 * @param   Dev      Device Handle
341
 * @param   pUpperLimitMilliMeter   The maximal range limit for actual setup
342
 * (in millimeter)
343
 * @return  VL53L0X_ERROR_NOT_IMPLEMENTED        Not implemented
344
 */
345
VL53L0X_API VL53L0X_Error VL53L0X_GetUpperLimitMilliMeter(VL53L0X_DEV Dev,
346
    uint16_t *pUpperLimitMilliMeter);
347
348
349
/**
350
 * @brief Get the Total Signal Rate
351
 * @par Function Description
352
 * This function will return the Total Signal Rate after a good ranging is done.
353
 *
354
 * @note This function access to Device
355
 *
356
 * @param   Dev      Device Handle
357
 * @param   pTotalSignalRate   Total Signal Rate value in Mega count per second
358
 * @return  VL53L0X_ERROR_NONE     Success
359
 * @return  "Other error code"    See ::VL53L0X_Error
360
 */
361
VL53L0X_Error VL53L0X_GetTotalSignalRate(VL53L0X_DEV Dev,
362
    FixPoint1616_t *pTotalSignalRate);
363
364
/** @} VL53L0X_general_group */
365
366
/** @defgroup VL53L0X_init_group VL53L0X Init Functions
367
 *  @brief    VL53L0X Init Functions
368
 *  @{
369
 */
370
371
/**
372
 * @brief Set new device address
373
 *
374
 * After completion the device will answer to the new address programmed.
375
 * This function should be called when several devices are used in parallel
376
 * before start programming the sensor.
377
 * When a single device us used, there is no need to call this function.
378
 *
379
 * @note This function Access to the device
380
 *
381
 * @param   Dev                   Device Handle
382
 * @param   DeviceAddress         The new Device address
383
 * @return  VL53L0X_ERROR_NONE     Success
384
 * @return  "Other error code"    See ::VL53L0X_Error
385
 */
386
VL53L0X_API VL53L0X_Error VL53L0X_SetDeviceAddress(VL53L0X_DEV Dev,
387
    uint8_t DeviceAddress);
388
389
/**
390
 *
391
 * @brief One time device initialization
392
 *
393
 * To be called once and only once after device is brought out of reset
394
 * (Chip enable) and booted see @a VL53L0X_WaitDeviceBooted()
395
 *
396
 * @par Function Description
397
 * When not used after a fresh device "power up" or reset, it may return
398
 * @a #VL53L0X_ERROR_CALIBRATION_WARNING meaning wrong calibration data
399
 * may have been fetched from device that can result in ranging offset error\n
400
 * If application cannot execute device reset or need to run VL53L0X_DataInit
401
 * multiple time then it  must ensure proper offset calibration saving and
402
 * restore on its own by using @a VL53L0X_GetOffsetCalibrationData() on first
403
 * power up and then @a VL53L0X_SetOffsetCalibrationData() in all subsequent init
404
 * This function will change the VL53L0X_State from VL53L0X_STATE_POWERDOWN to
405
 * VL53L0X_STATE_WAIT_STATICINIT.
406
 *
407
 * @note This function Access to the device
408
 *
409
 * @param   Dev                   Device Handle
410
 * @return  VL53L0X_ERROR_NONE     Success
411
 * @return  "Other error code"    See ::VL53L0X_Error
412
 */
413
VL53L0X_API VL53L0X_Error VL53L0X_DataInit(VL53L0X_DEV Dev);
414
415
/**
416
 * @brief Set the tuning settings pointer
417
 *
418
 * This function is used to specify the Tuning settings buffer to be used
419
 * for a given device. The buffer contains all the necessary data to permit
420
 * the API to write tuning settings.
421
 * This function permit to force the usage of either external or internal
422
 * tuning settings.
423
 *
424
 * @note This function Access to the device
425
 *
426
 * @param   Dev                             Device Handle
427
 * @param   pTuningSettingBuffer            Pointer to tuning settings buffer.
428
 * @param   UseInternalTuningSettings       Use internal tuning settings value.
429
 * @return  VL53L0X_ERROR_NONE     Success
430
 * @return  "Other error code"    See ::VL53L0X_Error
431
 */
432
VL53L0X_API VL53L0X_Error VL53L0X_SetTuningSettingBuffer(VL53L0X_DEV Dev,
433
    uint8_t *pTuningSettingBuffer, uint8_t UseInternalTuningSettings);
434
435
/**
436
 * @brief Get the tuning settings pointer and the internal external switch
437
 * value.
438
 *
439
 * This function is used to get the Tuning settings buffer pointer and the
440
 * value.
441
 * of the switch to select either external or internal tuning settings.
442
 *
443
 * @note This function Access to the device
444
 *
445
 * @param   Dev                        Device Handle
446
 * @param   ppTuningSettingBuffer      Pointer to tuning settings buffer.
447
 * @param   pUseInternalTuningSettings Pointer to store Use internal tuning
448
 *                                     settings value.
449
 * @return  VL53L0X_ERROR_NONE          Success
450
 * @return  "Other error code"         See ::VL53L0X_Error
451
 */
452
VL53L0X_API VL53L0X_Error VL53L0X_GetTuningSettingBuffer(VL53L0X_DEV Dev,
453
    uint8_t **ppTuningSettingBuffer, uint8_t *pUseInternalTuningSettings);
454
455
/**
456
 * @brief Do basic device init (and eventually patch loading)
457
 * This function will change the VL53L0X_State from
458
 * VL53L0X_STATE_WAIT_STATICINIT to VL53L0X_STATE_IDLE.
459
 * In this stage all default setting will be applied.
460
 *
461
 * @note This function Access to the device
462
 *
463
 * @param   Dev                   Device Handle
464
 * @return  VL53L0X_ERROR_NONE     Success
465
 * @return  "Other error code"    See ::VL53L0X_Error
466
 */
467
VL53L0X_API VL53L0X_Error VL53L0X_StaticInit(VL53L0X_DEV Dev);
468
469
/**
470
 * @brief Wait for device booted after chip enable (hardware standby)
471
 * This function can be run only when VL53L0X_State is VL53L0X_STATE_POWERDOWN.
472
 *
473
 * @note This function is not Implemented
474
 *
475
 * @param   Dev      Device Handle
476
 * @return  VL53L0X_ERROR_NOT_IMPLEMENTED Not implemented
477
 *
478
 */
479
VL53L0X_API VL53L0X_Error VL53L0X_WaitDeviceBooted(VL53L0X_DEV Dev);
480
481
/**
482
 * @brief Do an hard reset or soft reset (depending on implementation) of the
483
 * device \nAfter call of this function, device must be in same state as right
484
 * after a power-up sequence.This function will change the VL53L0X_State to
485
 * VL53L0X_STATE_POWERDOWN.
486
 *
487
 * @note This function Access to the device
488
 *
489
 * @param   Dev                   Device Handle
490
 * @return  VL53L0X_ERROR_NONE     Success
491
 * @return  "Other error code"    See ::VL53L0X_Error
492
 */
493
VL53L0X_API VL53L0X_Error VL53L0X_ResetDevice(VL53L0X_DEV Dev);
494
495
/** @} VL53L0X_init_group */
496
497
/** @defgroup VL53L0X_parameters_group VL53L0X Parameters Functions
498
 *  @brief    Functions used to prepare and setup the device
499
 *  @{
500
 */
501
502
/**
503
 * @brief  Prepare device for operation
504
 * @par Function Description
505
 * Update device with provided parameters
506
 * @li Then start ranging operation.
507
 *
508
 * @note This function Access to the device
509
 *
510
 * @param   Dev                   Device Handle
511
 * @param   pDeviceParameters     Pointer to store current device parameters.
512
 * @return  VL53L0X_ERROR_NONE     Success
513
 * @return  "Other error code"    See ::VL53L0X_Error
514
 */
515
VL53L0X_API VL53L0X_Error VL53L0X_SetDeviceParameters(VL53L0X_DEV Dev,
516
    const VL53L0X_DeviceParameters_t *pDeviceParameters);
517
518
/**
519
 * @brief  Retrieve current device parameters
520
 * @par Function Description
521
 * Get actual parameters of the device
522
 * @li Then start ranging operation.
523
 *
524
 * @note This function Access to the device
525
 *
526
 * @param   Dev                   Device Handle
527
 * @param   pDeviceParameters     Pointer to store current device parameters.
528
 * @return  VL53L0X_ERROR_NONE     Success
529
 * @return  "Other error code"    See ::VL53L0X_Error
530
 */
531
VL53L0X_API VL53L0X_Error VL53L0X_GetDeviceParameters(VL53L0X_DEV Dev,
532
    VL53L0X_DeviceParameters_t *pDeviceParameters);
533
534
/**
535
 * @brief  Set a new device mode
536
 * @par Function Description
537
 * Set device to a new mode (ranging, histogram ...)
538
 *
539
 * @note This function doesn't Access to the device
540
 *
541
 * @param   Dev                   Device Handle
542
 * @param   DeviceMode            New device mode to apply
543
 *                                Valid values are:
544
 *                                VL53L0X_DEVICEMODE_SINGLE_RANGING
545
 *                                VL53L0X_DEVICEMODE_CONTINUOUS_RANGING
546
 *                                VL53L0X_DEVICEMODE_CONTINUOUS_TIMED_RANGING
547
 *                                VL53L0X_DEVICEMODE_SINGLE_HISTOGRAM
548
 *                                VL53L0X_HISTOGRAMMODE_REFERENCE_ONLY
549
 *                                VL53L0X_HISTOGRAMMODE_RETURN_ONLY
550
 *                                VL53L0X_HISTOGRAMMODE_BOTH
551
 *
552
 *
553
 * @return  VL53L0X_ERROR_NONE               Success
554
 * @return  VL53L0X_ERROR_MODE_NOT_SUPPORTED This error occurs when DeviceMode is
555
 *                                          not in the supported list
556
 */
557
VL53L0X_API VL53L0X_Error VL53L0X_SetDeviceMode(VL53L0X_DEV Dev,
558
    VL53L0X_DeviceModes DeviceMode);
559
560
/**
561
 * @brief  Get current new device mode
562
 * @par Function Description
563
 * Get actual mode of the device(ranging, histogram ...)
564
 *
565
 * @note This function doesn't Access to the device
566
 *
567
 * @param   Dev                   Device Handle
568
 * @param   pDeviceMode           Pointer to current apply mode value
569
 *                                Valid values are:
570
 *                                VL53L0X_DEVICEMODE_SINGLE_RANGING
571
 *                                VL53L0X_DEVICEMODE_CONTINUOUS_RANGING
572
 *                                VL53L0X_DEVICEMODE_CONTINUOUS_TIMED_RANGING
573
 *                                VL53L0X_DEVICEMODE_SINGLE_HISTOGRAM
574
 *                                VL53L0X_HISTOGRAMMODE_REFERENCE_ONLY
575
 *                                VL53L0X_HISTOGRAMMODE_RETURN_ONLY
576
 *                                VL53L0X_HISTOGRAMMODE_BOTH
577
 *
578
 * @return  VL53L0X_ERROR_NONE                   Success
579
 * @return  VL53L0X_ERROR_MODE_NOT_SUPPORTED     This error occurs when
580
 * DeviceMode is not in the supported list
581
 */
582
VL53L0X_API VL53L0X_Error VL53L0X_GetDeviceMode(VL53L0X_DEV Dev,
583
    VL53L0X_DeviceModes *pDeviceMode);
584
585
/**
586
 * @brief  Sets the resolution of range measurements.
587
 * @par Function Description
588
 * Set resolution of range measurements to either 0.25mm if
589
 * fraction enabled or 1mm if not enabled.
590
 *
591
 * @note This function Accesses the device
592
 *
593
 * @param   Dev               Device Handle
594
 * @param   Enable            Enable high resolution
595
 *
596
 * @return  VL53L0X_ERROR_NONE               Success
597
 * @return  "Other error code"              See ::VL53L0X_Error
598
 */
599
VL53L0X_API VL53L0X_Error VL53L0X_SetRangeFractionEnable(VL53L0X_DEV Dev,
600
    uint8_t Enable);
601
602
/**
603
 * @brief  Gets the fraction enable parameter indicating the resolution of
604
 * range measurements.
605
 *
606
 * @par Function Description
607
 * Gets the fraction enable state, which translates to the resolution of
608
 * range measurements as follows :Enabled:=0.25mm resolution,
609
 * Not Enabled:=1mm resolution.
610
 *
611
 * @note This function Accesses the device
612
 *
613
 * @param   Dev               Device Handle
614
 * @param   pEnable           Output Parameter reporting the fraction enable state.
615
 *
616
 * @return  VL53L0X_ERROR_NONE                   Success
617
 * @return  "Other error code"                  See ::VL53L0X_Error
618
 */
619
VL53L0X_API VL53L0X_Error VL53L0X_GetFractionEnable(VL53L0X_DEV Dev,
620
    uint8_t *pEnable);
621
622
/**
623
 * @brief  Set a new Histogram mode
624
 * @par Function Description
625
 * Set device to a new Histogram mode
626
 *
627
 * @note This function doesn't Access to the device
628
 *
629
 * @param   Dev                   Device Handle
630
 * @param   HistogramMode         New device mode to apply
631
 *                                Valid values are:
632
 *                                VL53L0X_HISTOGRAMMODE_DISABLED
633
 *                                VL53L0X_DEVICEMODE_SINGLE_HISTOGRAM
634
 *                                VL53L0X_HISTOGRAMMODE_REFERENCE_ONLY
635
 *                                VL53L0X_HISTOGRAMMODE_RETURN_ONLY
636
 *                                VL53L0X_HISTOGRAMMODE_BOTH
637
 *
638
 * @return  VL53L0X_ERROR_NONE                   Success
639
 * @return  VL53L0X_ERROR_MODE_NOT_SUPPORTED     This error occurs when
640
 * HistogramMode is not in the supported list
641
 * @return  "Other error code"    See ::VL53L0X_Error
642
 */
643
VL53L0X_API VL53L0X_Error VL53L0X_SetHistogramMode(VL53L0X_DEV Dev,
644
    VL53L0X_HistogramModes HistogramMode);
645
646
/**
647
 * @brief  Get current new device mode
648
 * @par Function Description
649
 * Get current Histogram mode of a Device
650
 *
651
 * @note This function doesn't Access to the device
652
 *
653
 * @param   Dev                   Device Handle
654
 * @param   pHistogramMode        Pointer to current Histogram Mode value
655
 *                                Valid values are:
656
 *                                VL53L0X_HISTOGRAMMODE_DISABLED
657
 *                                VL53L0X_DEVICEMODE_SINGLE_HISTOGRAM
658
 *                                VL53L0X_HISTOGRAMMODE_REFERENCE_ONLY
659
 *                                VL53L0X_HISTOGRAMMODE_RETURN_ONLY
660
 *                                VL53L0X_HISTOGRAMMODE_BOTH
661
 * @return  VL53L0X_ERROR_NONE     Success
662
 * @return  "Other error code"    See ::VL53L0X_Error
663
 */
664
VL53L0X_API VL53L0X_Error VL53L0X_GetHistogramMode(VL53L0X_DEV Dev,
665
    VL53L0X_HistogramModes *pHistogramMode);
666
667
/**
668
 * @brief Set Ranging Timing Budget in microseconds
669
 *
670
 * @par Function Description
671
 * Defines the maximum time allowed by the user to the device to run a
672
 * full ranging sequence for the current mode (ranging, histogram, ASL ...)
673
 *
674
 * @note This function Access to the device
675
 *
676
 * @param   Dev                                Device Handle
677
 * @param MeasurementTimingBudgetMicroSeconds  Max measurement time in
678
 * microseconds.
679
 *                                   Valid values are:
680
 *                                   >= 17000 microsecs when wraparound enabled
681
 *                                   >= 12000 microsecs when wraparound disabled
682
 * @return  VL53L0X_ERROR_NONE             Success
683
 * @return  VL53L0X_ERROR_INVALID_PARAMS   This error is returned if
684
 MeasurementTimingBudgetMicroSeconds out of range
685
 * @return  "Other error code"            See ::VL53L0X_Error
686
 */
687
VL53L0X_API VL53L0X_Error VL53L0X_SetMeasurementTimingBudgetMicroSeconds(
688
    VL53L0X_DEV Dev, uint32_t MeasurementTimingBudgetMicroSeconds);
689
690
/**
691
 * @brief Get Ranging Timing Budget in microseconds
692
 *
693
 * @par Function Description
694
 * Returns the programmed the maximum time allowed by the user to the
695
 * device to run a full ranging sequence for the current mode
696
 * (ranging, histogram, ASL ...)
697
 *
698
 * @note This function Access to the device
699
 *
700
 * @param   Dev                                    Device Handle
701
 * @param   pMeasurementTimingBudgetMicroSeconds   Max measurement time in
702
 * microseconds.
703
 *                                   Valid values are:
704
 *                                   >= 17000 microsecs when wraparound enabled
705
 *                                   >= 12000 microsecs when wraparound disabled
706
 * @return  VL53L0X_ERROR_NONE                      Success
707
 * @return  "Other error code"                     See ::VL53L0X_Error
708
 */
709
VL53L0X_API VL53L0X_Error VL53L0X_GetMeasurementTimingBudgetMicroSeconds(
710
    VL53L0X_DEV Dev, uint32_t *pMeasurementTimingBudgetMicroSeconds);
711
712
/**
713
 * @brief Gets the VCSEL pulse period.
714
 *
715
 * @par Function Description
716
 * This function retrieves the VCSEL pulse period for the given period type.
717
 *
718
 * @note This function Accesses the device
719
 *
720
 * @param   Dev                      Device Handle
721
 * @param   VcselPeriodType          VCSEL period identifier (pre-range|final).
722
 * @param   pVCSELPulsePeriod        Pointer to VCSEL period value.
723
 * @return  VL53L0X_ERROR_NONE        Success
724
 * @return  VL53L0X_ERROR_INVALID_PARAMS  Error VcselPeriodType parameter not
725
 *                                       supported.
726
 * @return  "Other error code"           See ::VL53L0X_Error
727
 */
728
VL53L0X_API VL53L0X_Error VL53L0X_GetVcselPulsePeriod(VL53L0X_DEV Dev,
729
    VL53L0X_VcselPeriod VcselPeriodType, uint8_t *pVCSELPulsePeriod);
730
731
/**
732
 * @brief Sets the VCSEL pulse period.
733
 *
734
 * @par Function Description
735
 * This function retrieves the VCSEL pulse period for the given period type.
736
 *
737
 * @note This function Accesses the device
738
 *
739
 * @param   Dev                       Device Handle
740
 * @param   VcselPeriodType              VCSEL period identifier (pre-range|final).
741
 * @param   VCSELPulsePeriod          VCSEL period value
742
 * @return  VL53L0X_ERROR_NONE            Success
743
 * @return  VL53L0X_ERROR_INVALID_PARAMS  Error VcselPeriodType parameter not
744
 *                                       supported.
745
 * @return  "Other error code"           See ::VL53L0X_Error
746
 */
747
VL53L0X_API VL53L0X_Error VL53L0X_SetVcselPulsePeriod(VL53L0X_DEV Dev,
748
    VL53L0X_VcselPeriod VcselPeriodType, uint8_t VCSELPulsePeriod);
749
750
/**
751
 * @brief Sets the (on/off) state of a requested sequence step.
752
 *
753
 * @par Function Description
754
 * This function enables/disables a requested sequence step.
755
 *
756
 * @note This function Accesses the device
757
 *
758
 * @param   Dev                          Device Handle
759
 * @param   SequenceStepId                 Sequence step identifier.
760
 * @param   SequenceStepEnabled          Demanded state {0=Off,1=On}
761
 *                                       is enabled.
762
 * @return  VL53L0X_ERROR_NONE            Success
763
 * @return  VL53L0X_ERROR_INVALID_PARAMS  Error SequenceStepId parameter not
764
 *                                       supported.
765
 * @return  "Other error code"           See ::VL53L0X_Error
766
 */
767
VL53L0X_API VL53L0X_Error VL53L0X_SetSequenceStepEnable(VL53L0X_DEV Dev,
768
    VL53L0X_SequenceStepId SequenceStepId, uint8_t SequenceStepEnabled);
769
770
/**
771
 * @brief Gets the (on/off) state of a requested sequence step.
772
 *
773
 * @par Function Description
774
 * This function retrieves the state of a requested sequence step, i.e. on/off.
775
 *
776
 * @note This function Accesses the device
777
 *
778
 * @param   Dev                    Device Handle
779
 * @param   SequenceStepId         Sequence step identifier.
780
 * @param   pSequenceStepEnabled   Out parameter reporting if the sequence step
781
 *                                 is enabled {0=Off,1=On}.
782
 * @return  VL53L0X_ERROR_NONE            Success
783
 * @return  VL53L0X_ERROR_INVALID_PARAMS  Error SequenceStepId parameter not
784
 *                                       supported.
785
 * @return  "Other error code"           See ::VL53L0X_Error
786
 */
787
VL53L0X_API VL53L0X_Error VL53L0X_GetSequenceStepEnable(VL53L0X_DEV Dev,
788
    VL53L0X_SequenceStepId SequenceStepId, uint8_t *pSequenceStepEnabled);
789
790
/**
791
 * @brief Gets the (on/off) state of all sequence steps.
792
 *
793
 * @par Function Description
794
 * This function retrieves the state of all sequence step in the scheduler.
795
 *
796
 * @note This function Accesses the device
797
 *
798
 * @param   Dev                          Device Handle
799
 * @param   pSchedulerSequenceSteps      Pointer to struct containing result.
800
 * @return  VL53L0X_ERROR_NONE            Success
801
 * @return  "Other error code"           See ::VL53L0X_Error
802
 */
803
VL53L0X_API VL53L0X_Error VL53L0X_GetSequenceStepEnables(VL53L0X_DEV Dev,
804
    VL53L0X_SchedulerSequenceSteps_t *pSchedulerSequenceSteps);
805
806
/**
807
 * @brief Sets the timeout of a requested sequence step.
808
 *
809
 * @par Function Description
810
 * This function sets the timeout of a requested sequence step.
811
 *
812
 * @note This function Accesses the device
813
 *
814
 * @param   Dev                          Device Handle
815
 * @param   SequenceStepId               Sequence step identifier.
816
 * @param   TimeOutMilliSecs             Demanded timeout
817
 * @return  VL53L0X_ERROR_NONE            Success
818
 * @return  VL53L0X_ERROR_INVALID_PARAMS  Error SequenceStepId parameter not
819
 *                                       supported.
820
 * @return  "Other error code"           See ::VL53L0X_Error
821
 */
822
VL53L0X_API VL53L0X_Error VL53L0X_SetSequenceStepTimeout(VL53L0X_DEV Dev,
823
    VL53L0X_SequenceStepId SequenceStepId, FixPoint1616_t TimeOutMilliSecs);
824
825
/**
826
 * @brief Gets the timeout of a requested sequence step.
827
 *
828
 * @par Function Description
829
 * This function retrieves the timeout of a requested sequence step.
830
 *
831
 * @note This function Accesses the device
832
 *
833
 * @param   Dev                          Device Handle
834
 * @param   SequenceStepId               Sequence step identifier.
835
 * @param   pTimeOutMilliSecs            Timeout value.
836
 * @return  VL53L0X_ERROR_NONE            Success
837
 * @return  VL53L0X_ERROR_INVALID_PARAMS  Error SequenceStepId parameter not
838
 *                                       supported.
839
 * @return  "Other error code"           See ::VL53L0X_Error
840
 */
841
VL53L0X_API VL53L0X_Error VL53L0X_GetSequenceStepTimeout(VL53L0X_DEV Dev,
842
    VL53L0X_SequenceStepId SequenceStepId,
843
    FixPoint1616_t *pTimeOutMilliSecs);
844
845
/**
846
 * @brief Gets number of sequence steps managed by the API.
847
 *
848
 * @par Function Description
849
 * This function retrieves the number of sequence steps currently managed
850
 * by the API
851
 *
852
 * @note This function Accesses the device
853
 *
854
 * @param   Dev                          Device Handle
855
 * @param   pNumberOfSequenceSteps       Out parameter reporting the number of
856
 *                                       sequence steps.
857
 * @return  VL53L0X_ERROR_NONE            Success
858
 * @return  "Other error code"           See ::VL53L0X_Error
859
 */
860
VL53L0X_API VL53L0X_Error VL53L0X_GetNumberOfSequenceSteps(VL53L0X_DEV Dev,
861
    uint8_t *pNumberOfSequenceSteps);
862
863
/**
864
 * @brief Gets the name of a given sequence step.
865
 *
866
 * @par Function Description
867
 * This function retrieves the name of sequence steps corresponding to
868
 * SequenceStepId.
869
 *
870
 * @note This function doesn't Accesses the device
871
 *
872
 * @param   SequenceStepId               Sequence step identifier.
873
 * @param   pSequenceStepsString         Pointer to Info string
874
 *
875
 * @return  VL53L0X_ERROR_NONE            Success
876
 * @return  "Other error code"           See ::VL53L0X_Error
877
 */
878
VL53L0X_API VL53L0X_Error VL53L0X_GetSequenceStepsInfo(
879
    VL53L0X_SequenceStepId SequenceStepId, char *pSequenceStepsString);
880
881
/**
882
 * Program continuous mode Inter-Measurement period in milliseconds
883
 *
884
 * @par Function Description
885
 * When trying to set too short time return  INVALID_PARAMS minimal value
886
 *
887
 * @note This function Access to the device
888
 *
889
 * @param   Dev                                  Device Handle
890
 * @param   InterMeasurementPeriodMilliSeconds   Inter-Measurement Period in ms.
891
 * @return  VL53L0X_ERROR_NONE                    Success
892
 * @return  "Other error code"                   See ::VL53L0X_Error
893
 */
894
VL53L0X_API VL53L0X_Error VL53L0X_SetInterMeasurementPeriodMilliSeconds(
895
    VL53L0X_DEV Dev, uint32_t InterMeasurementPeriodMilliSeconds);
896
897
/**
898
 * Get continuous mode Inter-Measurement period in milliseconds
899
 *
900
 * @par Function Description
901
 * When trying to set too short time return  INVALID_PARAMS minimal value
902
 *
903
 * @note This function Access to the device
904
 *
905
 * @param   Dev                                  Device Handle
906
 * @param   pInterMeasurementPeriodMilliSeconds  Pointer to programmed
907
 *  Inter-Measurement Period in milliseconds.
908
 * @return  VL53L0X_ERROR_NONE                    Success
909
 * @return  "Other error code"                   See ::VL53L0X_Error
910
 */
911
VL53L0X_API VL53L0X_Error VL53L0X_GetInterMeasurementPeriodMilliSeconds(
912
    VL53L0X_DEV Dev, uint32_t *pInterMeasurementPeriodMilliSeconds);
913
914
/**
915
 * @brief Enable/Disable Cross talk compensation feature
916
 *
917
 * @note This function is not Implemented.
918
 * Enable/Disable Cross Talk by set to zero the Cross Talk value
919
 * by using @a VL53L0X_SetXTalkCompensationRateMegaCps().
920
 *
921
 * @param   Dev                       Device Handle
922
 * @param   XTalkCompensationEnable   Cross talk compensation
923
 *  to be set 0=disabled else = enabled
924
 * @return  VL53L0X_ERROR_NOT_IMPLEMENTED   Not implemented
925
 */
926
VL53L0X_API VL53L0X_Error VL53L0X_SetXTalkCompensationEnable(VL53L0X_DEV Dev,
927
    uint8_t XTalkCompensationEnable);
928
929
/**
930
 * @brief Get Cross talk compensation rate
931
 *
932
 * @note This function is not Implemented.
933
 * Enable/Disable Cross Talk by set to zero the Cross Talk value by
934
 * using @a VL53L0X_SetXTalkCompensationRateMegaCps().
935
 *
936
 * @param   Dev                        Device Handle
937
 * @param   pXTalkCompensationEnable   Pointer to the Cross talk compensation
938
 *  state 0=disabled or 1 = enabled
939
 * @return  VL53L0X_ERROR_NOT_IMPLEMENTED   Not implemented
940
 */
941
VL53L0X_API VL53L0X_Error VL53L0X_GetXTalkCompensationEnable(VL53L0X_DEV Dev,
942
    uint8_t *pXTalkCompensationEnable);
943
944
/**
945
 * @brief Set Cross talk compensation rate
946
 *
947
 * @par Function Description
948
 * Set Cross talk compensation rate.
949
 *
950
 * @note This function Access to the device
951
 *
952
 * @param   Dev                            Device Handle
953
 * @param   XTalkCompensationRateMegaCps   Compensation rate in
954
 *  Mega counts per second (16.16 fix point) see datasheet for details
955
 * @return  VL53L0X_ERROR_NONE              Success
956
 * @return  "Other error code"             See ::VL53L0X_Error
957
 */
958
VL53L0X_API VL53L0X_Error VL53L0X_SetXTalkCompensationRateMegaCps(VL53L0X_DEV Dev,
959
    FixPoint1616_t XTalkCompensationRateMegaCps);
960
961
/**
962
 * @brief Get Cross talk compensation rate
963
 *
964
 * @par Function Description
965
 * Get Cross talk compensation rate.
966
 *
967
 * @note This function Access to the device
968
 *
969
 * @param   Dev                            Device Handle
970
 * @param   pXTalkCompensationRateMegaCps  Pointer to Compensation rate
971
 in Mega counts per second (16.16 fix point) see datasheet for details
972
 * @return  VL53L0X_ERROR_NONE              Success
973
 * @return  "Other error code"             See ::VL53L0X_Error
974
 */
975
VL53L0X_API VL53L0X_Error VL53L0X_GetXTalkCompensationRateMegaCps(VL53L0X_DEV Dev,
976
    FixPoint1616_t *pXTalkCompensationRateMegaCps);
977
978
/**
979
 * @brief Set Reference Calibration Parameters
980
 *
981
 * @par Function Description
982
 * Set Reference Calibration Parameters.
983
 *
984
 * @note This function Access to the device
985
 *
986
 * @param   Dev                            Device Handle
987
 * @param   VhvSettings                    Parameter for VHV
988
 * @param   PhaseCal                       Parameter for PhaseCal
989
 * @return  VL53L0X_ERROR_NONE              Success
990
 * @return  "Other error code"             See ::VL53L0X_Error
991
 */
992
VL53L0X_API VL53L0X_Error VL53L0X_SetRefCalibration(VL53L0X_DEV Dev,
993
    uint8_t VhvSettings, uint8_t PhaseCal);
994
995
/**
996
 * @brief Get Reference Calibration Parameters
997
 *
998
 * @par Function Description
999
 * Get Reference Calibration Parameters.
1000
 *
1001
 * @note This function Access to the device
1002
 *
1003
 * @param   Dev                            Device Handle
1004
 * @param   pVhvSettings                   Pointer to VHV parameter
1005
 * @param   pPhaseCal                      Pointer to PhaseCal Parameter
1006
 * @return  VL53L0X_ERROR_NONE              Success
1007
 * @return  "Other error code"             See ::VL53L0X_Error
1008
 */
1009
VL53L0X_API VL53L0X_Error VL53L0X_GetRefCalibration(VL53L0X_DEV Dev,
1010
    uint8_t *pVhvSettings, uint8_t *pPhaseCal);
1011
1012
/**
1013
 * @brief  Get the number of the check limit managed by a given Device
1014
 *
1015
 * @par Function Description
1016
 * This function give the number of the check limit managed by the Device
1017
 *
1018
 * @note This function doesn't Access to the device
1019
 *
1020
 * @param   pNumberOfLimitCheck           Pointer to the number of check limit.
1021
 * @return  VL53L0X_ERROR_NONE             Success
1022
 * @return  "Other error code"            See ::VL53L0X_Error
1023
 */
1024
VL53L0X_API VL53L0X_Error VL53L0X_GetNumberOfLimitCheck(
1025
    uint16_t *pNumberOfLimitCheck);
1026
1027
/**
1028
 * @brief  Return a description string for a given limit check number
1029
 *
1030
 * @par Function Description
1031
 * This function returns a description string for a given limit check number.
1032
 * The limit check is identified with the LimitCheckId.
1033
 *
1034
 * @note This function doesn't Access to the device
1035
 *
1036
 * @param   Dev                           Device Handle
1037
 * @param   LimitCheckId                  Limit Check ID
1038
 (0<= LimitCheckId < VL53L0X_GetNumberOfLimitCheck() ).
1039
 * @param   pLimitCheckString             Pointer to the
1040
 description string of the given check limit.
1041
 * @return  VL53L0X_ERROR_NONE             Success
1042
 * @return  VL53L0X_ERROR_INVALID_PARAMS   This error is
1043
 returned when LimitCheckId value is out of range.
1044
 * @return  "Other error code"            See ::VL53L0X_Error
1045
 */
1046
VL53L0X_API VL53L0X_Error VL53L0X_GetLimitCheckInfo(VL53L0X_DEV Dev,
1047
    uint16_t LimitCheckId, char *pLimitCheckString);
1048
1049
/**
1050
 * @brief  Return a the Status of the specified check limit
1051
 *
1052
 * @par Function Description
1053
 * This function returns the Status of the specified check limit.
1054
 * The value indicate if the check is fail or not.
1055
 * The limit check is identified with the LimitCheckId.
1056
 *
1057
 * @note This function doesn't Access to the device
1058
 *
1059
 * @param   Dev                           Device Handle
1060
 * @param   LimitCheckId                  Limit Check ID
1061
 (0<= LimitCheckId < VL53L0X_GetNumberOfLimitCheck() ).
1062
 * @param   pLimitCheckStatus             Pointer to the
1063
 Limit Check Status of the given check limit.
1064
 * LimitCheckStatus :
1065
 * 0 the check is not fail
1066
 * 1 the check if fail or not enabled
1067
 *
1068
 * @return  VL53L0X_ERROR_NONE             Success
1069
 * @return  VL53L0X_ERROR_INVALID_PARAMS   This error is
1070
 returned when LimitCheckId value is out of range.
1071
 * @return  "Other error code"            See ::VL53L0X_Error
1072
 */
1073
VL53L0X_API VL53L0X_Error VL53L0X_GetLimitCheckStatus(VL53L0X_DEV Dev,
1074
    uint16_t LimitCheckId, uint8_t *pLimitCheckStatus);
1075
1076
/**
1077
 * @brief  Enable/Disable a specific limit check
1078
 *
1079
 * @par Function Description
1080
 * This function Enable/Disable a specific limit check.
1081
 * The limit check is identified with the LimitCheckId.
1082
 *
1083
 * @note This function doesn't Access to the device
1084
 *
1085
 * @param   Dev                           Device Handle
1086
 * @param   LimitCheckId                  Limit Check ID
1087
 *  (0<= LimitCheckId < VL53L0X_GetNumberOfLimitCheck() ).
1088
 * @param   LimitCheckEnable              if 1 the check limit
1089
 *  corresponding to LimitCheckId is Enabled
1090
 *                                        if 0 the check limit
1091
 *  corresponding to LimitCheckId is disabled
1092
 * @return  VL53L0X_ERROR_NONE             Success
1093
 * @return  VL53L0X_ERROR_INVALID_PARAMS   This error is returned
1094
 *  when LimitCheckId value is out of range.
1095
 * @return  "Other error code"            See ::VL53L0X_Error
1096
 */
1097
VL53L0X_API VL53L0X_Error VL53L0X_SetLimitCheckEnable(VL53L0X_DEV Dev,
1098
    uint16_t LimitCheckId, uint8_t LimitCheckEnable);
1099
1100
/**
1101
 * @brief  Get specific limit check enable state
1102
 *
1103
 * @par Function Description
1104
 * This function get the enable state of a specific limit check.
1105
 * The limit check is identified with the LimitCheckId.
1106
 *
1107
 * @note This function Access to the device
1108
 *
1109
 * @param   Dev                           Device Handle
1110
 * @param   LimitCheckId                  Limit Check ID
1111
 *  (0<= LimitCheckId < VL53L0X_GetNumberOfLimitCheck() ).
1112
 * @param   pLimitCheckEnable             Pointer to the check limit enable
1113
 * value.
1114
 *  if 1 the check limit
1115
 *        corresponding to LimitCheckId is Enabled
1116
 *  if 0 the check limit
1117
 *        corresponding to LimitCheckId is disabled
1118
 * @return  VL53L0X_ERROR_NONE             Success
1119
 * @return  VL53L0X_ERROR_INVALID_PARAMS   This error is returned
1120
 *  when LimitCheckId value is out of range.
1121
 * @return  "Other error code"            See ::VL53L0X_Error
1122
 */
1123
VL53L0X_API VL53L0X_Error VL53L0X_GetLimitCheckEnable(VL53L0X_DEV Dev,
1124
    uint16_t LimitCheckId, uint8_t *pLimitCheckEnable);
1125
1126
/**
1127
 * @brief  Set a specific limit check value
1128
 *
1129
 * @par Function Description
1130
 * This function set a specific limit check value.
1131
 * The limit check is identified with the LimitCheckId.
1132
 *
1133
 * @note This function Access to the device
1134
 *
1135
 * @param   Dev                           Device Handle
1136
 * @param   LimitCheckId                  Limit Check ID
1137
 *  (0<= LimitCheckId < VL53L0X_GetNumberOfLimitCheck() ).
1138
 * @param   LimitCheckValue               Limit check Value for a given
1139
 * LimitCheckId
1140
 * @return  VL53L0X_ERROR_NONE             Success
1141
 * @return  VL53L0X_ERROR_INVALID_PARAMS   This error is returned when either
1142
 *  LimitCheckId or LimitCheckValue value is out of range.
1143
 * @return  "Other error code"            See ::VL53L0X_Error
1144
 */
1145
VL53L0X_API VL53L0X_Error VL53L0X_SetLimitCheckValue(VL53L0X_DEV Dev,
1146
    uint16_t LimitCheckId, FixPoint1616_t LimitCheckValue);
1147
1148
/**
1149
 * @brief  Get a specific limit check value
1150
 *
1151
 * @par Function Description
1152
 * This function get a specific limit check value from device then it updates
1153
 * internal values and check enables.
1154
 * The limit check is identified with the LimitCheckId.
1155
 *
1156
 * @note This function Access to the device
1157
 *
1158
 * @param   Dev                           Device Handle
1159
 * @param   LimitCheckId                  Limit Check ID
1160
 *  (0<= LimitCheckId < VL53L0X_GetNumberOfLimitCheck() ).
1161
 * @param   pLimitCheckValue              Pointer to Limit
1162
 *  check Value for a given LimitCheckId.
1163
 * @return  VL53L0X_ERROR_NONE             Success
1164
 * @return  VL53L0X_ERROR_INVALID_PARAMS   This error is returned
1165
 *  when LimitCheckId value is out of range.
1166
 * @return  "Other error code"            See ::VL53L0X_Error
1167
 */
1168
VL53L0X_API VL53L0X_Error VL53L0X_GetLimitCheckValue(VL53L0X_DEV Dev,
1169
    uint16_t LimitCheckId, FixPoint1616_t *pLimitCheckValue);
1170
1171
/**
1172
 * @brief  Get the current value of the signal used for the limit check
1173
 *
1174
 * @par Function Description
1175
 * This function get a the current value of the signal used for the limit check.
1176
 * To obtain the latest value you should run a ranging before.
1177
 * The value reported is linked to the limit check identified with the
1178
 * LimitCheckId.
1179
 *
1180
 * @note This function Access to the device
1181
 *
1182
 * @param   Dev                           Device Handle
1183
 * @param   LimitCheckId                  Limit Check ID
1184
 *  (0<= LimitCheckId < VL53L0X_GetNumberOfLimitCheck() ).
1185
 * @param   pLimitCheckCurrent            Pointer to current Value for a
1186
 * given LimitCheckId.
1187
 * @return  VL53L0X_ERROR_NONE             Success
1188
 * @return  VL53L0X_ERROR_INVALID_PARAMS   This error is returned when
1189
 * LimitCheckId value is out of range.
1190
 * @return  "Other error code"            See ::VL53L0X_Error
1191
 */
1192
VL53L0X_API VL53L0X_Error VL53L0X_GetLimitCheckCurrent(VL53L0X_DEV Dev,
1193
    uint16_t LimitCheckId, FixPoint1616_t *pLimitCheckCurrent);
1194
1195
/**
1196
 * @brief  Enable (or disable) Wrap around Check
1197
 *
1198
 * @note This function Access to the device
1199
 *
1200
 * @param   Dev                    Device Handle
1201
 * @param   WrapAroundCheckEnable  Wrap around Check to be set
1202
 *                                 0=disabled, other = enabled
1203
 * @return  VL53L0X_ERROR_NONE      Success
1204
 * @return  "Other error code"     See ::VL53L0X_Error
1205
 */
1206
VL53L0X_API VL53L0X_Error VL53L0X_SetWrapAroundCheckEnable(VL53L0X_DEV Dev,
1207
        uint8_t WrapAroundCheckEnable);
1208
1209
/**
1210
 * @brief  Get setup of Wrap around Check
1211
 *
1212
 * @par Function Description
1213
 * This function get the wrapAround check enable parameters
1214
 *
1215
 * @note This function Access to the device
1216
 *
1217
 * @param   Dev                     Device Handle
1218
 * @param   pWrapAroundCheckEnable  Pointer to the Wrap around Check state
1219
 *                                  0=disabled or 1 = enabled
1220
 * @return  VL53L0X_ERROR_NONE       Success
1221
 * @return  "Other error code"      See ::VL53L0X_Error
1222
 */
1223
VL53L0X_API VL53L0X_Error VL53L0X_GetWrapAroundCheckEnable(VL53L0X_DEV Dev,
1224
        uint8_t *pWrapAroundCheckEnable);
1225
1226
/**
1227
 * @brief   Set Dmax Calibration Parameters for a given device
1228
 * When one of the parameter is zero, this function will get parameter
1229
 * from NVM.
1230
 * @note This function doesn't Access to the device
1231
 *
1232
 * @param   Dev                    Device Handle
1233
 * @param   RangeMilliMeter        Calibration Distance
1234
 * @param   SignalRateRtnMegaCps   Signal rate return read at CalDistance
1235
 * @return  VL53L0X_ERROR_NONE      Success
1236
 * @return  "Other error code"     See ::VL53L0X_Error
1237
 */
1238
VL53L0X_API VL53L0X_Error VL53L0X_SetDmaxCalParameters(VL53L0X_DEV Dev,
1239
        uint16_t RangeMilliMeter, FixPoint1616_t SignalRateRtnMegaCps);
1240
1241
/**
1242
 * @brief  Get Dmax Calibration Parameters for a given device
1243
 *
1244
 *
1245
 * @note This function Access to the device
1246
 *
1247
 * @param   Dev                     Device Handle
1248
 * @param   pRangeMilliMeter        Pointer to Calibration Distance
1249
 * @param   pSignalRateRtnMegaCps   Pointer to Signal rate return
1250
 * @return  VL53L0X_ERROR_NONE       Success
1251
 * @return  "Other error code"      See ::VL53L0X_Error
1252
 */
1253
VL53L0X_API VL53L0X_Error VL53L0X_GetDmaxCalParameters(VL53L0X_DEV Dev,
1254
    uint16_t *pRangeMilliMeter, FixPoint1616_t *pSignalRateRtnMegaCps);
1255
1256
/** @} VL53L0X_parameters_group */
1257
1258
/** @defgroup VL53L0X_measurement_group VL53L0X Measurement Functions
1259
 *  @brief    Functions used for the measurements
1260
 *  @{
1261
 */
1262
1263
/**
1264
 * @brief Single shot measurement.
1265
 *
1266
 * @par Function Description
1267
 * Perform simple measurement sequence (Start measure, Wait measure to end,
1268
 * and returns when measurement is done).
1269
 * Once function returns, user can get valid data by calling
1270
 * VL53L0X_GetRangingMeasurement or VL53L0X_GetHistogramMeasurement
1271
 * depending on defined measurement mode
1272
 * User should Clear the interrupt in case this are enabled by using the
1273
 * function VL53L0X_ClearInterruptMask().
1274
 *
1275
 * @warning This function is a blocking function
1276
 *
1277
 * @note This function Access to the device
1278
 *
1279
 * @param   Dev                  Device Handle
1280
 * @return  VL53L0X_ERROR_NONE    Success
1281
 * @return  "Other error code"   See ::VL53L0X_Error
1282
 */
1283
VL53L0X_API VL53L0X_Error VL53L0X_PerformSingleMeasurement(VL53L0X_DEV Dev);
1284
1285
/**
1286
 * @brief Perform Reference Calibration
1287
 *
1288
 * @details Perform a reference calibration of the Device.
1289
 * This function should be run from time to time before doing
1290
 * a ranging measurement.
1291
 * This function will launch a special ranging measurement, so
1292
 * if interrupt are enable an interrupt will be done.
1293
 * This function will clear the interrupt generated automatically.
1294
 *
1295
 * @warning This function is a blocking function
1296
 *
1297
 * @note This function Access to the device
1298
 *
1299
 * @param   Dev                  Device Handle
1300
 * @param   pVhvSettings         Pointer to vhv settings parameter.
1301
 * @param   pPhaseCal            Pointer to PhaseCal parameter.
1302
 * @return  VL53L0X_ERROR_NONE    Success
1303
 * @return  "Other error code"   See ::VL53L0X_Error
1304
 */
1305
VL53L0X_API VL53L0X_Error VL53L0X_PerformRefCalibration(VL53L0X_DEV Dev,
1306
    uint8_t *pVhvSettings, uint8_t *pPhaseCal);
1307
1308
/**
1309
 * @brief Perform XTalk Measurement
1310
 *
1311
 * @details Measures the current cross talk from glass in front
1312
 * of the sensor.
1313
 * This functions performs a histogram measurement and uses the results
1314
 * to measure the crosstalk. For the function to be successful, there
1315
 * must be no target in front of the sensor.
1316
 *
1317
 * @warning This function is a blocking function
1318
 *
1319
 * @warning This function is not supported when the final range
1320
 * vcsel clock period is set below 10 PCLKS.
1321
 *
1322
 * @note This function Access to the device
1323
 *
1324
 * @param   Dev                  Device Handle
1325
 * @param   TimeoutMs            Histogram measurement duration.
1326
 * @param   pXtalkPerSpad        Output parameter containing the crosstalk
1327
 * measurement result, in MCPS/Spad. Format fixpoint 16:16.
1328
 * @param   pAmbientTooHigh      Output parameter which indicate that
1329
 * pXtalkPerSpad is not good if the Ambient is too high.
1330
 * @return  VL53L0X_ERROR_NONE    Success
1331
 * @return  VL53L0X_ERROR_INVALID_PARAMS vcsel clock period not supported
1332
 * for this operation. Must not be less than 10PCLKS.
1333
 * @return  "Other error code"   See ::VL53L0X_Error
1334
 */
1335
VL53L0X_API VL53L0X_Error VL53L0X_PerformXTalkMeasurement(VL53L0X_DEV Dev,
1336
    uint32_t TimeoutMs, FixPoint1616_t *pXtalkPerSpad,
1337
    uint8_t *pAmbientTooHigh);
1338
1339
/**
1340
 * @brief Perform XTalk Calibration
1341
 *
1342
 * @details Perform a XTalk calibration of the Device.
1343
 * This function will launch a ranging measurement, if interrupts
1344
 * are enabled an interrupt will be done.
1345
 * This function will clear the interrupt generated automatically.
1346
 * This function will program a new value for the XTalk compensation
1347
 * and it will enable the cross talk before exit.
1348
 * This function will disable the VL53L0X_CHECKENABLE_RANGE_IGNORE_THRESHOLD.
1349
 *
1350
 * @warning This function is a blocking function
1351
 *
1352
 * @note This function Access to the device
1353
 *
1354
 * @note This function change the device mode to
1355
 * VL53L0X_DEVICEMODE_SINGLE_RANGING
1356
 *
1357
 * @param   Dev                  Device Handle
1358
 * @param   XTalkCalDistance     XTalkCalDistance value used for the XTalk
1359
 * computation.
1360
 * @param   pXTalkCompensationRateMegaCps  Pointer to new
1361
 * XTalkCompensation value.
1362
 * @return  VL53L0X_ERROR_NONE    Success
1363
 * @return  "Other error code"   See ::VL53L0X_Error
1364
 */
1365
VL53L0X_API VL53L0X_Error VL53L0X_PerformXTalkCalibration(VL53L0X_DEV Dev,
1366
    FixPoint1616_t XTalkCalDistance,
1367
    FixPoint1616_t *pXTalkCompensationRateMegaCps);
1368
1369
/**
1370
 * @brief Perform Offset Calibration
1371
 *
1372
 * @details Perform a Offset calibration of the Device.
1373
 * This function will launch a ranging measurement, if interrupts are
1374
 * enabled an interrupt will be done.
1375
 * This function will clear the interrupt generated automatically.
1376
 * This function will program a new value for the Offset calibration value
1377
 * This function will disable the VL53L0X_CHECKENABLE_RANGE_IGNORE_THRESHOLD.
1378
 *
1379
 * @warning This function is a blocking function
1380
 *
1381
 * @note This function Access to the device
1382
 *
1383
 * @note This function does not change the device mode.
1384
 *
1385
 * @param   Dev                  Device Handle
1386
 * @param   CalDistanceMilliMeter     Calibration distance value used for the
1387
 * offset compensation.
1388
 * @param   pOffsetMicroMeter  Pointer to new Offset value computed by the
1389
 * function.
1390
 *
1391
 * @return  VL53L0X_ERROR_NONE    Success
1392
 * @return  "Other error code"   See ::VL53L0X_Error
1393
 */
1394
VL53L0X_API VL53L0X_Error VL53L0X_PerformOffsetCalibration(VL53L0X_DEV Dev,
1395
    FixPoint1616_t CalDistanceMilliMeter, int32_t *pOffsetMicroMeter);
1396
1397
/**
1398
 * @brief Start device measurement
1399
 *
1400
 * @details Started measurement will depend on device parameters set through
1401
 * @a VL53L0X_SetParameters()
1402
 * This is a non-blocking function.
1403
 * This function will change the VL53L0X_State from VL53L0X_STATE_IDLE to
1404
 * VL53L0X_STATE_RUNNING.
1405
 *
1406
 * @note This function Access to the device
1407
 *
1408

1409
 * @param   Dev                  Device Handle
1410
 * @return  VL53L0X_ERROR_NONE                  Success
1411
 * @return  VL53L0X_ERROR_MODE_NOT_SUPPORTED    This error occurs when
1412
 * DeviceMode programmed with @a VL53L0X_SetDeviceMode is not in the supported
1413
 * list:
1414
 *                                   Supported mode are:
1415
 *                                   VL53L0X_DEVICEMODE_SINGLE_RANGING,
1416
 *                                   VL53L0X_DEVICEMODE_CONTINUOUS_RANGING,
1417
 *                                   VL53L0X_DEVICEMODE_CONTINUOUS_TIMED_RANGING
1418
 * @return  VL53L0X_ERROR_TIME_OUT    Time out on start measurement
1419
 * @return  "Other error code"   See ::VL53L0X_Error
1420
 */
1421
VL53L0X_API VL53L0X_Error VL53L0X_StartMeasurement(VL53L0X_DEV Dev);
1422
1423
/**
1424
 * @brief Stop device measurement
1425
 *
1426
 * @details Will set the device in standby mode at end of current measurement\n
1427
 *          Not necessary in single mode as device shall return automatically
1428
 *          in standby mode at end of measurement.
1429
 *          This function will change the VL53L0X_State from VL53L0X_STATE_RUNNING
1430
 *          to VL53L0X_STATE_IDLE.
1431
 *
1432
 * @note This function Access to the device
1433
 *
1434
 * @param   Dev                  Device Handle
1435
 * @return  VL53L0X_ERROR_NONE    Success
1436
 * @return  "Other error code"   See ::VL53L0X_Error
1437
 */
1438
VL53L0X_API VL53L0X_Error VL53L0X_StopMeasurement(VL53L0X_DEV Dev);
1439
1440
/**
1441
 * @brief Return Measurement Data Ready
1442
 *
1443
 * @par Function Description
1444
 * This function indicate that a measurement data is ready.
1445
 * This function check if interrupt mode is used then check is done accordingly.
1446
 * If perform function clear the interrupt, this function will not work,
1447
 * like in case of @a VL53L0X_PerformSingleRangingMeasurement().
1448
 * The previous function is blocking function, VL53L0X_GetMeasurementDataReady
1449
 * is used for non-blocking capture.
1450
 *
1451
 * @note This function Access to the device
1452
 *
1453
 * @param   Dev                    Device Handle
1454
 * @param   pMeasurementDataReady  Pointer to Measurement Data Ready.
1455
 *  0=data not ready, 1 = data ready
1456
 * @return  VL53L0X_ERROR_NONE      Success
1457
 * @return  "Other error code"     See ::VL53L0X_Error
1458
 */
1459
VL53L0X_API VL53L0X_Error VL53L0X_GetMeasurementDataReady(VL53L0X_DEV Dev,
1460
    uint8_t *pMeasurementDataReady);
1461
1462
/**
1463
 * @brief Wait for device ready for a new measurement command.
1464
 * Blocking function.
1465
 *
1466
 * @note This function is not Implemented
1467
 *
1468
 * @param   Dev      Device Handle
1469
 * @param   MaxLoop    Max Number of polling loop (timeout).
1470
 * @return  VL53L0X_ERROR_NOT_IMPLEMENTED   Not implemented
1471
 */
1472
VL53L0X_API VL53L0X_Error VL53L0X_WaitDeviceReadyForNewMeasurement(VL53L0X_DEV Dev,
1473
    uint32_t MaxLoop);
1474
1475
/**
1476
 * @brief Retrieve the Reference Signal after a measurements
1477
 *
1478
 * @par Function Description
1479
 * Get Reference Signal from last successful Ranging measurement
1480
 * This function return a valid value after that you call the
1481
 * @a VL53L0X_GetRangingMeasurementData().
1482
 *
1483
 * @note This function Access to the device
1484
 *
1485
 * @param   Dev                      Device Handle
1486
 * @param   pMeasurementRefSignal    Pointer to the Ref Signal to fill up.
1487
 * @return  VL53L0X_ERROR_NONE        Success
1488
 * @return  "Other error code"       See ::VL53L0X_Error
1489
 */
1490
VL53L0X_API VL53L0X_Error VL53L0X_GetMeasurementRefSignal(VL53L0X_DEV Dev,
1491
    FixPoint1616_t *pMeasurementRefSignal);
1492
1493
/**
1494
 * @brief Retrieve the measurements from device for a given setup
1495
 *
1496
 * @par Function Description
1497
 * Get data from last successful Ranging measurement
1498
 * @warning USER should take care about  @a VL53L0X_GetNumberOfROIZones()
1499
 * before get data.
1500
 * PAL will fill a NumberOfROIZones times the corresponding data
1501
 * structure used in the measurement function.
1502
 *
1503
 * @note This function Access to the device
1504
 *
1505
 * @param   Dev                      Device Handle
1506
 * @param   pRangingMeasurementData  Pointer to the data structure to fill up.
1507
 * @return  VL53L0X_ERROR_NONE        Success
1508
 * @return  "Other error code"       See ::VL53L0X_Error
1509
 */
1510
VL53L0X_API VL53L0X_Error VL53L0X_GetRangingMeasurementData(VL53L0X_DEV Dev,
1511
    VL53L0X_RangingMeasurementData_t *pRangingMeasurementData);
1512
1513
/**
1514
 * @brief Retrieve the measurements from device for a given setup
1515
 *
1516
 * @par Function Description
1517
 * Get data from last successful Histogram measurement
1518
 * @warning USER should take care about  @a VL53L0X_GetNumberOfROIZones()
1519
 * before get data.
1520
 * PAL will fill a NumberOfROIZones times the corresponding data structure
1521
 * used in the measurement function.
1522
 *
1523
 * @note This function is not Implemented
1524
 *
1525
 * @param   Dev                         Device Handle
1526
 * @param   pHistogramMeasurementData   Pointer to the histogram data structure.
1527
 * @return  VL53L0X_ERROR_NOT_IMPLEMENTED   Not implemented
1528
 */
1529
VL53L0X_API VL53L0X_Error VL53L0X_GetHistogramMeasurementData(VL53L0X_DEV Dev,
1530
    VL53L0X_HistogramMeasurementData_t *pHistogramMeasurementData);
1531
1532
/**
1533
 * @brief Performs a single ranging measurement and retrieve the ranging
1534
 * measurement data
1535
 *
1536
 * @par Function Description
1537
 * This function will change the device mode to VL53L0X_DEVICEMODE_SINGLE_RANGING
1538
 * with @a VL53L0X_SetDeviceMode(),
1539
 * It performs measurement with @a VL53L0X_PerformSingleMeasurement()
1540
 * It get data from last successful Ranging measurement with
1541
 * @a VL53L0X_GetRangingMeasurementData.
1542
 * Finally it clear the interrupt with @a VL53L0X_ClearInterruptMask().
1543
 *
1544
 * @note This function Access to the device
1545
 *
1546
 * @note This function change the device mode to
1547
 * VL53L0X_DEVICEMODE_SINGLE_RANGING
1548
 *
1549
 * @param   Dev                       Device Handle
1550
 * @param   pRangingMeasurementData   Pointer to the data structure to fill up.
1551
 * @return  VL53L0X_ERROR_NONE         Success
1552
 * @return  "Other error code"        See ::VL53L0X_Error
1553
 */
1554
VL53L0X_API VL53L0X_Error VL53L0X_PerformSingleRangingMeasurement(VL53L0X_DEV Dev,
1555
    VL53L0X_RangingMeasurementData_t *pRangingMeasurementData);
1556
1557
/**
1558
 * @brief Performs a single histogram measurement and retrieve the histogram
1559
 * measurement data
1560
 *   Is equivalent to VL53L0X_PerformSingleMeasurement +
1561
 *   VL53L0X_GetHistogramMeasurementData
1562
 *
1563
 * @par Function Description
1564
 * Get data from last successful Ranging measurement.
1565
 * This function will clear the interrupt in case of these are enabled.
1566
 *
1567
 * @note This function is not Implemented
1568
 *
1569
 * @param   Dev                        Device Handle
1570
 * @param   pHistogramMeasurementData  Pointer to the data structure to fill up.
1571
 * @return  VL53L0X_ERROR_NOT_IMPLEMENTED   Not implemented
1572
 */
1573
VL53L0X_API VL53L0X_Error VL53L0X_PerformSingleHistogramMeasurement(VL53L0X_DEV Dev,
1574
    VL53L0X_HistogramMeasurementData_t *pHistogramMeasurementData);
1575
1576
/**
1577
 * @brief Set the number of ROI Zones to be used for a specific Device
1578
 *
1579
 * @par Function Description
1580
 * Set the number of ROI Zones to be used for a specific Device.
1581
 * The programmed value should be less than the max number of ROI Zones given
1582
 * with @a VL53L0X_GetMaxNumberOfROIZones().
1583
 * This version of API manage only one zone.
1584
 *
1585
 * @param   Dev                           Device Handle
1586
 * @param   NumberOfROIZones              Number of ROI Zones to be used for a
1587
 *  specific Device.
1588
 * @return  VL53L0X_ERROR_NONE             Success
1589
 * @return  VL53L0X_ERROR_INVALID_PARAMS   This error is returned if
1590
 * NumberOfROIZones != 1
1591
 */
1592
VL53L0X_API VL53L0X_Error VL53L0X_SetNumberOfROIZones(VL53L0X_DEV Dev,
1593
    uint8_t NumberOfROIZones);
1594
1595
/**
1596
 * @brief Get the number of ROI Zones managed by the Device
1597
 *
1598
 * @par Function Description
1599
 * Get number of ROI Zones managed by the Device
1600
 * USER should take care about  @a VL53L0X_GetNumberOfROIZones()
1601
 * before get data after a perform measurement.
1602
 * PAL will fill a NumberOfROIZones times the corresponding data
1603
 * structure used in the measurement function.
1604
 *
1605
 * @note This function doesn't Access to the device
1606
 *
1607
 * @param   Dev                   Device Handle
1608
 * @param   pNumberOfROIZones     Pointer to the Number of ROI Zones value.
1609
 * @return  VL53L0X_ERROR_NONE     Success
1610
 */
1611
VL53L0X_API VL53L0X_Error VL53L0X_GetNumberOfROIZones(VL53L0X_DEV Dev,
1612
    uint8_t *pNumberOfROIZones);
1613
1614
/**
1615
 * @brief Get the Maximum number of ROI Zones managed by the Device
1616
 *
1617
 * @par Function Description
1618
 * Get Maximum number of ROI Zones managed by the Device.
1619
 *
1620
 * @note This function doesn't Access to the device
1621
 *
1622
 * @param   Dev                    Device Handle
1623
 * @param   pMaxNumberOfROIZones   Pointer to the Maximum Number
1624
 *  of ROI Zones value.
1625
 * @return  VL53L0X_ERROR_NONE      Success
1626
 */
1627
VL53L0X_API VL53L0X_Error VL53L0X_GetMaxNumberOfROIZones(VL53L0X_DEV Dev,
1628
    uint8_t *pMaxNumberOfROIZones);
1629
1630
/** @} VL53L0X_measurement_group */
1631
1632
/** @defgroup VL53L0X_interrupt_group VL53L0X Interrupt Functions
1633
 *  @brief    Functions used for interrupt managements
1634
 *  @{
1635
 */
1636
1637
/**
1638
 * @brief Set the configuration of GPIO pin for a given device
1639
 *
1640
 * @note This function Access to the device
1641
 *
1642
 * @param   Dev                   Device Handle
1643
 * @param   Pin                   ID of the GPIO Pin
1644
 * @param   Functionality         Select Pin functionality.
1645
 *  Refer to ::VL53L0X_GpioFunctionality
1646
 * @param   DeviceMode            Device Mode associated to the Gpio.
1647
 * @param   Polarity              Set interrupt polarity. Active high
1648
 *   or active low see ::VL53L0X_InterruptPolarity
1649
 * @return  VL53L0X_ERROR_NONE                            Success
1650
 * @return  VL53L0X_ERROR_GPIO_NOT_EXISTING               Only Pin=0 is accepted.
1651
 * @return  VL53L0X_ERROR_GPIO_FUNCTIONALITY_NOT_SUPPORTED    This error occurs
1652
 * when Functionality programmed is not in the supported list:
1653
 *                             Supported value are:
1654
 *                             VL53L0X_GPIOFUNCTIONALITY_OFF,
1655
 *                             VL53L0X_GPIOFUNCTIONALITY_THRESHOLD_CROSSED_LOW,
1656
 *                             VL53L0X_GPIOFUNCTIONALITY_THRESHOLD_CROSSED_HIGH,
1657
 VL53L0X_GPIOFUNCTIONALITY_THRESHOLD_CROSSED_OUT,
1658
 *                               VL53L0X_GPIOFUNCTIONALITY_NEW_MEASURE_READY
1659
 * @return  "Other error code"    See ::VL53L0X_Error
1660
 */
1661
VL53L0X_API VL53L0X_Error VL53L0X_SetGpioConfig(VL53L0X_DEV Dev, uint8_t Pin,
1662
    VL53L0X_DeviceModes DeviceMode, VL53L0X_GpioFunctionality Functionality,
1663
    VL53L0X_InterruptPolarity Polarity);
1664
1665
/**
1666
 * @brief Get current configuration for GPIO pin for a given device
1667
 *
1668
 * @note This function Access to the device
1669
 *
1670
 * @param   Dev                   Device Handle
1671
 * @param   Pin                   ID of the GPIO Pin
1672
 * @param   pDeviceMode           Pointer to Device Mode associated to the Gpio.
1673
 * @param   pFunctionality        Pointer to Pin functionality.
1674
 *  Refer to ::VL53L0X_GpioFunctionality
1675
 * @param   pPolarity             Pointer to interrupt polarity.
1676
 *  Active high or active low see ::VL53L0X_InterruptPolarity
1677
 * @return  VL53L0X_ERROR_NONE                            Success
1678
 * @return  VL53L0X_ERROR_GPIO_NOT_EXISTING               Only Pin=0 is accepted.
1679
 * @return  VL53L0X_ERROR_GPIO_FUNCTIONALITY_NOT_SUPPORTED   This error occurs
1680
 * when Functionality programmed is not in the supported list:
1681
 *                      Supported value are:
1682
 *                      VL53L0X_GPIOFUNCTIONALITY_OFF,
1683
 *                      VL53L0X_GPIOFUNCTIONALITY_THRESHOLD_CROSSED_LOW,
1684
 *                      VL53L0X_GPIOFUNCTIONALITY_THRESHOLD_CROSSED_HIGH,
1685
 *                      VL53L0X_GPIOFUNCTIONALITY_THRESHOLD_CROSSED_OUT,
1686
 *                      VL53L0X_GPIOFUNCTIONALITY_NEW_MEASURE_READY
1687
 * @return  "Other error code"    See ::VL53L0X_Error
1688
 */
1689
VL53L0X_API VL53L0X_Error VL53L0X_GetGpioConfig(VL53L0X_DEV Dev, uint8_t Pin,
1690
    VL53L0X_DeviceModes *pDeviceMode,
1691
    VL53L0X_GpioFunctionality *pFunctionality,
1692
    VL53L0X_InterruptPolarity *pPolarity);
1693
1694
/**
1695
 * @brief Set low and high Interrupt thresholds for a given mode
1696
 * (ranging, ALS, ...) for a given device
1697
 *
1698
 * @par Function Description
1699
 * Set low and high Interrupt thresholds for a given mode (ranging, ALS, ...)
1700
 * for a given device
1701
 *
1702
 * @note This function Access to the device
1703
 *
1704
 * @note DeviceMode is ignored for the current device
1705
 *
1706
 * @param   Dev              Device Handle
1707
 * @param   DeviceMode       Device Mode for which change thresholds
1708
 * @param   ThresholdLow     Low threshold (mm, lux ..., depending on the mode)
1709
 * @param   ThresholdHigh    High threshold (mm, lux ..., depending on the mode)
1710
 * @return  VL53L0X_ERROR_NONE    Success
1711
 * @return  "Other error code"   See ::VL53L0X_Error
1712
 */
1713
VL53L0X_API VL53L0X_Error VL53L0X_SetInterruptThresholds(VL53L0X_DEV Dev,
1714
    VL53L0X_DeviceModes DeviceMode, FixPoint1616_t ThresholdLow,
1715
    FixPoint1616_t ThresholdHigh);
1716
1717
/**
1718
 * @brief  Get high and low Interrupt thresholds for a given mode
1719
 *  (ranging, ALS, ...) for a given device
1720
 *
1721
 * @par Function Description
1722
 * Get high and low Interrupt thresholds for a given mode (ranging, ALS, ...)
1723
 * for a given device
1724
 *
1725
 * @note This function Access to the device
1726
 *
1727
 * @note DeviceMode is ignored for the current device
1728
 *
1729
 * @param   Dev              Device Handle
1730
 * @param   DeviceMode       Device Mode from which read thresholds
1731
 * @param   pThresholdLow    Low threshold (mm, lux ..., depending on the mode)
1732
 * @param   pThresholdHigh   High threshold (mm, lux ..., depending on the mode)
1733
 * @return  VL53L0X_ERROR_NONE   Success
1734
 * @return  "Other error code"  See ::VL53L0X_Error
1735
 */
1736
VL53L0X_API VL53L0X_Error VL53L0X_GetInterruptThresholds(VL53L0X_DEV Dev,
1737
    VL53L0X_DeviceModes DeviceMode, FixPoint1616_t *pThresholdLow,
1738
    FixPoint1616_t *pThresholdHigh);
1739
1740
/**
1741
 * @brief Return device stop completion status
1742
 *
1743
 * @par Function Description
1744
 * Returns stop completiob status.
1745
 * User shall call this function after a stop command
1746
 *
1747
 * @note This function Access to the device
1748
 *
1749
 * @param   Dev                    Device Handle
1750
 * @param   pStopStatus            Pointer to status variable to update
1751
 * @return  VL53L0X_ERROR_NONE      Success
1752
 * @return  "Other error code"     See ::VL53L0X_Error
1753
 */
1754
VL53L0X_API VL53L0X_Error VL53L0X_GetStopCompletedStatus(VL53L0X_DEV Dev,
1755
    uint32_t *pStopStatus);
1756
1757
1758
/**
1759
 * @brief Clear given system interrupt condition
1760
 *
1761
 * @par Function Description
1762
 * Clear given interrupt(s).
1763
 *
1764
 * @note This function Access to the device
1765
 *
1766
 * @param   Dev                  Device Handle
1767
 * @param   InterruptMask        Mask of interrupts to clear
1768
 * @return  VL53L0X_ERROR_NONE    Success
1769
 * @return  VL53L0X_ERROR_INTERRUPT_NOT_CLEARED    Cannot clear interrupts
1770
 *
1771
 * @return  "Other error code"   See ::VL53L0X_Error
1772
 */
1773
VL53L0X_API VL53L0X_Error VL53L0X_ClearInterruptMask(VL53L0X_DEV Dev,
1774
    uint32_t InterruptMask);
1775
1776
/**
1777
 * @brief Return device interrupt status
1778
 *
1779
 * @par Function Description
1780
 * Returns currently raised interrupts by the device.
1781
 * User shall be able to activate/deactivate interrupts through
1782
 * @a VL53L0X_SetGpioConfig()
1783
 *
1784
 * @note This function Access to the device
1785
 *
1786
 * @param   Dev                    Device Handle
1787
 * @param   pInterruptMaskStatus   Pointer to status variable to update
1788
 * @return  VL53L0X_ERROR_NONE      Success
1789
 * @return  "Other error code"     See ::VL53L0X_Error
1790
 */
1791
VL53L0X_API VL53L0X_Error VL53L0X_GetInterruptMaskStatus(VL53L0X_DEV Dev,
1792
    uint32_t *pInterruptMaskStatus);
1793
1794
/**
1795
 * @brief Configure ranging interrupt reported to system
1796
 *
1797
 * @note This function is not Implemented
1798
 *
1799
 * @param   Dev                  Device Handle
1800
 * @param   InterruptMask         Mask of interrupt to Enable/disable
1801
 *  (0:interrupt disabled or 1: interrupt enabled)
1802
 * @return  VL53L0X_ERROR_NOT_IMPLEMENTED   Not implemented
1803
 */
1804
VL53L0X_API VL53L0X_Error VL53L0X_EnableInterruptMask(VL53L0X_DEV Dev,
1805
    uint32_t InterruptMask);
1806
1807
/** @} VL53L0X_interrupt_group */
1808
1809
/** @defgroup VL53L0X_SPADfunctions_group VL53L0X SPAD Functions
1810
 *  @brief    Functions used for SPAD managements
1811
 *  @{
1812
 */
1813
1814
/**
1815
 * @brief  Set the SPAD Ambient Damper Threshold value
1816
 *
1817
 * @par Function Description
1818
 * This function set the SPAD Ambient Damper Threshold value
1819
 *
1820
 * @note This function Access to the device
1821
 *
1822
 * @param   Dev                           Device Handle
1823
 * @param   SpadAmbientDamperThreshold    SPAD Ambient Damper Threshold value
1824
 * @return  VL53L0X_ERROR_NONE             Success
1825
 * @return  "Other error code"            See ::VL53L0X_Error
1826
 */
1827
VL53L0X_API VL53L0X_Error VL53L0X_SetSpadAmbientDamperThreshold(VL53L0X_DEV Dev,
1828
    uint16_t SpadAmbientDamperThreshold);
1829
1830
/**
1831
 * @brief  Get the current SPAD Ambient Damper Threshold value
1832
 *
1833
 * @par Function Description
1834
 * This function get the SPAD Ambient Damper Threshold value
1835
 *
1836
 * @note This function Access to the device
1837
 *
1838
 * @param   Dev                           Device Handle
1839
 * @param   pSpadAmbientDamperThreshold   Pointer to programmed
1840
 *                                        SPAD Ambient Damper Threshold value
1841
 * @return  VL53L0X_ERROR_NONE             Success
1842
 * @return  "Other error code"            See ::VL53L0X_Error
1843
 */
1844
VL53L0X_API VL53L0X_Error VL53L0X_GetSpadAmbientDamperThreshold(VL53L0X_DEV Dev,
1845
    uint16_t *pSpadAmbientDamperThreshold);
1846
1847
/**
1848
 * @brief  Set the SPAD Ambient Damper Factor value
1849
 *
1850
 * @par Function Description
1851
 * This function set the SPAD Ambient Damper Factor value
1852
 *
1853
 * @note This function Access to the device
1854
 *
1855
 * @param   Dev                           Device Handle
1856
 * @param   SpadAmbientDamperFactor       SPAD Ambient Damper Factor value
1857
 * @return  VL53L0X_ERROR_NONE             Success
1858
 * @return  "Other error code"            See ::VL53L0X_Error
1859
 */
1860
VL53L0X_API VL53L0X_Error VL53L0X_SetSpadAmbientDamperFactor(VL53L0X_DEV Dev,
1861
    uint16_t SpadAmbientDamperFactor);
1862
1863
/**
1864
 * @brief  Get the current SPAD Ambient Damper Factor value
1865
 *
1866
 * @par Function Description
1867
 * This function get the SPAD Ambient Damper Factor value
1868
 *
1869
 * @note This function Access to the device
1870
 *
1871
 * @param   Dev                           Device Handle
1872
 * @param   pSpadAmbientDamperFactor      Pointer to programmed SPAD Ambient
1873
 * Damper Factor value
1874
 * @return  VL53L0X_ERROR_NONE             Success
1875
 * @return  "Other error code"            See ::VL53L0X_Error
1876
 */
1877
VL53L0X_API VL53L0X_Error VL53L0X_GetSpadAmbientDamperFactor(VL53L0X_DEV Dev,
1878
    uint16_t *pSpadAmbientDamperFactor);
1879
1880
/**
1881
 * @brief Performs Reference Spad Management
1882
 *
1883
 * @par Function Description
1884
 * The reference SPAD initialization procedure determines the minimum amount
1885
 * of reference spads to be enables to achieve a target reference signal rate
1886
 * and should be performed once during initialization.
1887
 *
1888
 * @note This function Access to the device
1889
 *
1890
 * @note This function change the device mode to
1891
 * VL53L0X_DEVICEMODE_SINGLE_RANGING
1892
 *
1893
 * @param   Dev                          Device Handle
1894
 * @param   refSpadCount                 Reports ref Spad Count
1895
 * @param   isApertureSpads              Reports if spads are of type
1896
 *                                       aperture or non-aperture.
1897
 *                                       1:=aperture, 0:=Non-Aperture
1898
 * @return  VL53L0X_ERROR_NONE            Success
1899
 * @return  VL53L0X_ERROR_REF_SPAD_INIT   Error in the Ref Spad procedure.
1900
 * @return  "Other error code"           See ::VL53L0X_Error
1901
 */
1902
VL53L0X_API VL53L0X_Error VL53L0X_PerformRefSpadManagement(VL53L0X_DEV Dev,
1903
    uint32_t *refSpadCount, uint8_t *isApertureSpads);
1904
1905
/**
1906
 * @brief Applies Reference SPAD configuration
1907
 *
1908
 * @par Function Description
1909
 * This function applies a given number of reference spads, identified as
1910
 * either Aperture or Non-Aperture.
1911
 * The requested spad count and type are stored within the device specific
1912
 * parameters data for access by the host.
1913
 *
1914
 * @note This function Access to the device
1915
 *
1916
 * @param   Dev                          Device Handle
1917
 * @param   refSpadCount                 Number of ref spads.
1918
 * @param   isApertureSpads              Defines if spads are of type
1919
 *                                       aperture or non-aperture.
1920
 *                                       1:=aperture, 0:=Non-Aperture
1921
 * @return  VL53L0X_ERROR_NONE            Success
1922
 * @return  VL53L0X_ERROR_REF_SPAD_INIT   Error in the in the reference
1923
 *                                       spad configuration.
1924
 * @return  "Other error code"           See ::VL53L0X_Error
1925
 */
1926
VL53L0X_API VL53L0X_Error VL53L0X_SetReferenceSpads(VL53L0X_DEV Dev,
1927
    uint32_t refSpadCount, uint8_t isApertureSpads);
1928
1929
/**
1930
 * @brief Retrieves SPAD configuration
1931
 *
1932
 * @par Function Description
1933
 * This function retrieves the current number of applied reference spads
1934
 * and also their type : Aperture or Non-Aperture.
1935
 *
1936
 * @note This function Access to the device
1937
 *
1938
 * @param   Dev                          Device Handle
1939
 * @param   refSpadCount                 Number ref Spad Count
1940
 * @param   isApertureSpads              Reports if spads are of type
1941
 *                                       aperture or non-aperture.
1942
 *                                       1:=aperture, 0:=Non-Aperture
1943
 * @return  VL53L0X_ERROR_NONE            Success
1944
 * @return  VL53L0X_ERROR_REF_SPAD_INIT   Error in the in the reference
1945
 *                                       spad configuration.
1946
 * @return  "Other error code"           See ::VL53L0X_Error
1947
 */
1948
VL53L0X_API VL53L0X_Error VL53L0X_GetReferenceSpads(VL53L0X_DEV Dev,
1949
    uint32_t *refSpadCount, uint8_t *isApertureSpads);
1950
1951
/** @} VL53L0X_SPADfunctions_group */
1952
1953
/** @} VL53L0X_cut11_group */
1954
1955
#ifdef __cplusplus
1956
}
1957
#endif
1958
1959
#endif /* _VL53L0X_API_H_ */