application programming interface ... - S · PDF fileWorld smallest Time-of-Flight ranging and...

Click here to load reader

  • date post

    05-Feb-2018
  • Category

    Documents

  • view

    234
  • download

    0

Embed Size (px)

Transcript of application programming interface ... - S · PDF fileWorld smallest Time-of-Flight ranging and...

  • June 2016 DocID029105 Rev 1 1/2626

    UM2039User Manual

    World smallest Time-of-Flight ranging and gesture detection sensorApplication Programming Interface

    IntroductionVL53L0X is a ranging and gesture detection sensor.

    The purpose of this User Manual is to describe the Application Programming Interface (API), and the calibration procedures from a user perspective.

    The API is a turnkey solution. It consists of a set of C functions which enables fast development of end user applications, without the complication of direct multiple register access. The API is structured in a way that it can be compiled on any kind of platform through a well isolated platform layer.

    The API package allows the user to take full benefit of VL53L0X capabilities

    Figure 1. VL53L0X ranging sensor module

    References1. VL53L0X Datasheet (DS11555)

    www.st.com

    http://www.st.com

  • Contents UM2039

    2/26 DocID029105 Rev 1

    Contents

    1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

    2 Initial customer manufacturing calibration . . . . . . . . . . . . . . . . . . . . . . . 52.1 Data init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

    2.2 Static Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

    2.3 Reference SPADs calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.3.1 Reference SPADs calibration procedure . . . . . . . . . . . . . . . . . . . . . . . . . 6

    2.4 Ref (temperature) calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.4.1 Ref calibration procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

    2.5 Offset calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.5.1 Offset calibration procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

    2.6 Cross-talk calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.6.1 Cover window impact on ranging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

    2.6.2 Cross-talk calibration distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

    2.6.3 Cross-talk calibration procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

    3 Range profile phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.1 Initialization/calibration phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

    3.2 Ranging phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

    4 System initialization/calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.1 Data init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

    4.2 Static Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

    4.3 Load calibration data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.3.1 Reference SPADs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

    4.3.2 Ref calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

    4.3.3 Offset calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

    4.3.4 Cross-talk correction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

    4.4 Device mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

    4.5 Polling and interrupt mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

    5 Ranging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155.1 Start a measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

  • DocID029105 Rev 1 3/26

    UM2039 Contents

    26

    5.1.1 Start measurement only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

    5.1.2 Start measurement and wait for data ready . . . . . . . . . . . . . . . . . . . . . . 15

    5.1.3 Start measurement, wait for data ready and report the data . . . . . . . . . 15

    5.2 Stop a measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

    5.3 Get a result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165.3.1 Host polling to get the result status . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

    5.3.2 Get measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

    6 API useful additional functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176.1 Overall timing budget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

    6.2 Limit settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

    6.3 Timed ranging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

    6.4 API versions and product revision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

    6.5 API state and API error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

    6.6 I2C device address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

    6.7 Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

    6.8 Interrupt settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

    7 Example API range profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227.1 High accuracy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

    7.2 Long range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

    7.3 High speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

    8 Acronyms and abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

    9 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

  • Overview UM2039

    4/26 DocID029105 Rev 1

    1 Overview

    VL53L0X API is based on Photonic Abstraction Layer (PAL) specification. API is defined as the implementation of the PAL.

    The API exposes high level functions to be used by the customer application to control the device.

    Note: Full API documentation is available, as part of the API package, in chm and pdf formats.

  • DocID029105 Rev 1 5/26

    UM2039 Initial customer manufacturing calibration

    26

    2 Initial customer manufacturing calibration

    There is an initial, once only, calibration step required that should be applied at customer level during the manufacturing process. This flow takes into account all parameters (cover glass, temperature & voltage) from the application.

    The customer manufacturing calibration flow is described in Figure 2 below.

    Figure 2. Customer manufacturing calibration flow

    The following sections detail the API function calls required to perform the initial system calibration.

    2.1 Data initVL53L0X_DataInit() function is called one time, and it performs the device initialization.

    To be called once and only once after device is brought out of reset.

    StaticInit

    DataInit

    Key

    Host calls API function

    Host action Target needed

    * : Timings are given for information only, they can vary depending on the Host capabilities

    CalibrationData result

    Calibration data

    Calibration data

    Calibration data

    Calibration data

    Device initialization

    SPADs calibration

    Temperature calibration

    Offset calibration

    CrossTalk calibration

    ~40ms*

    ~10ms*

    ~40ms*

    ~300ms*

    ~1sec*

    Calibration data - Host

  • Initial customer manufacturing calibration UM2039

    6/26 DocID029105 Rev 1

    2.2 Static InitVL53L0X_StaticInit() function allows to load device settings specific for a given use case.

    2.3 Reference SPADs calibrationIn order to optimize the dynamic of the system, the reference SPADs have to be calibrated.

    This step is performed on the bare modules during Final Module Test at STMicroelectronics, and the calibration data (SPAD numbers and type) are stored into the device NVM.

    In case a cover glass is used on top of VL53L0X, the reference SPADs have to be re-calibrated by the customer.

    Reference SPAD calibration needs to be done only once during the initial manufacturing calibration, calibration data should then be stored on the Host.

    When calibration is performed and calibration data is available on the Host, the data can be loaded without re-performing the calibration.

    These functions can be called after VL53L0X_StaticInit(). It has to be done before Ref Calibration, VL53L0X_PerformRefCalibration().

    2.3.1 Reference SPADs calibration procedureNo particular conditions have to be used. The calibration does not require specific target or lighting conditions. The following procedure has to be performed: Call VL53L0X_PerformRefSpadManagement()

    This function outputs the number and type of referenc