VL6180X API IntegrationGuide

VL6180X API IntegrationGuide
VL6180X API Integration Guide
History
Version
Date
Comments
1.0
11 August 2015
Initial
1.1
13 October 2015 API 3.2.0 update : errorStatus 17 removed
2
VL6180X API Description
Integration
Set of documented C functions
To enable development of end-user applications through simple
& high level functions : Init, Prepare, Range, Als, etc…
Structured in a way it is easily portable
Through a well isolated platform layer (mainly for low level i2C
access).
Validated on Nucleo pack
NUCLEO STM32F401RE & L053R8 with X-NUCLEO-6180XA1
Expansion Board
ALS, Ranging, and multi-satellites examples
Two examples : RangingAndAls & RangingWithSatellites
example codes with pre-compiled binaries and Keil & IAR
projects
3
API Integration Procedure
Discover
Play
Port Single
Device
Select operating
mode
Tune for your
application
Port Multiple
Devices
4
Discover
API Benefits
• Getting ranging from an I2C-based device looks simple
but Time-Of-Flight technology is complex
• API is there to :
• Keep your application simple
• Ensure best performances of VL6180X device whatever the
conditions
• Ease VL6180X device integration into your platform
• API is a mandatory SW layer that implements extra
features which may be key for your applications (see
the “Tune for your application section”)
• Ranging scaling
• Wrap-around filter
• Dmax estimation
5
Discover
API Documentation
• Unzip VL6180X_API_x.x.x_Mass_Market.zip
• Read API documentation in docs directory
• chm
• html
• Focus your attention on following pages in this
order
• Main Page
• Examples
• Modules
6
Discover
API Functions
• API functions are grouped in different modules
•
•
•
•
API Low level functions
API High level functions
Configuration
Platform
• Only 3 API functions are enough to get a ranging measure
from the device
• VL6180x_InitData()
• VL6180x_Prepare()
• VL6180x_RangePollMeasurement()
• Always read errorStatus returned by range
measurement functions to know if the returned measure
is valid or not (see the “Tune for your application”
section)
7
Discover
API Static Configuration
• API static configuration is gathered in a single vl6180x_cfg.h that
customer should not modify (ST guarantees the device
performances only with the static configuration provided in this file)
Definition
Proximity Ranging+ALS
(VL6180X)
VL6180x_UPSCALE_SUPPORT
-1
VL6180x_ALS_SUPPORT
1
VL6180x_HAVE_DMAX_RANGING
1
VL6180x_WRAP_AROUND_FILTER_SUPPORT
1
VL6180x_EXTENDED_RANGE
0
• See next slide for more details on each parameter…
8
Discover
Proximity+ALS configuration
• Proximity+ALS configuration
• #define VL6180x_UPSCALE_SUPPORT -1
• Default scaling is x1 to enable ranging up to 200 mm
• The minus (-1) means it is also possible to change the scaling (to x2 or x3) through the
VL6180x_UpscaleSetScaling() API function call to extend ranging capabilities. Note that
ranging performances (max distance, accuracy) with scaling x2 or x3 are not guaranteed by
ST with VL6180X device (only with VL6180 device)
• #define VL6180x_ALS_SUPPORT 1
• ALS feature is enabled so all ALS-related functions of the API are compiled and can be used
in the application.
• #define VL6180x_HAVE_DMAX_RANGING 1
• Enable Dmax calculation for ranging applications. Even if this macro is set to 1, it is possible
to disable this feature with the VL6180x_DMaxSetState() API function in case application
does not need Dmax (to avoid useless calculation in the API). Setting this macro to 0 could
also help to reduce the code size if it is a concern.
• #define VL6180x_WRAP_AROUND_FILTER_SUPPORT 1
• Wrap-around filter (WAF) is enabled to filter potential wrong distances that may be reported
(if WAF is off) with high reflective targets (like mirror) placed between 60 cm and 1.2 m from
the device. If scaling factor is maintained at x1 (proximity ranging application), WAF should
probably be disabled using the VL6180x_FilterSetState() API function. For higher scaling
factors, WAF should probably be maintained enabled.
• #define VL6180x_EXTENDED_RANGE 1
• Set the device in a configuration which allows to increase scaling factor from x1 to x2 or x3
9
Discover
API code samples
• Have a look at the various examples from the API documentation
• Click on the file to open source code
• Source code is located in example/code_samples directory
10
Discover
Simple ranging
• Simple Ranging : this is the code that will run in
customer application !
11
API Integration Procedure
Discover
Play
Port Single
Device
Select operating
mode
Tune for your
application
Port Multiple
Devices
12
Play
Nucleo examples
• API package contains several “applications” examples which can
be compiled and executed on a Nucleo F401 board equipped with
X-NUCLEO-6180XA1 expansion board (P-NUCLEO-6180X1 pack)
• See in example\Nucleo\Projects\Multi\Examples\VL6180X
• RangingAndALS
• Simple demo displaying on the 4-digit display the distance (in mm) from a target
(Ranging) or the Lux level (ALS)
• CodeSamples
• This is a single demo gathering all sample codes execution. Pressing the blue
button allows to go from one sample code to the next one
• RangingWithSatellites
• Demo showing how to get ranging from up to 4 devices (satellites) on the same I2C
bus
13
Play
RangingAndALS Nucleo example
• Documentation is in the docs directory
• P-NUCLEO-6180X1*.pdf
• Focus on VL6180X Nucleo pack software installation chapter
• The demo is already pre-compiled so you simply need to connect Nucleo
board to your PC through USB and drag&drop the demo binary
• From example\Nucleo\Projects\Multi\Examples\VL6180X\RangingAndALS\Bin
• To Nucleo image
• Demo will start !
• Read documentation to get more details about the various modes of the
demo
• Ranging with various scaling factors : x1, x2, x3, Automatic
• Ranging with alarm mode
• ALS
14
Play
CodeSamples Nucleo example
• All sample codes are gathered in a single
demo/project
• example\Nucleo\Projects\Multi\Examples\VL6180X\
CodeSamples
• Following slides describe in details how to
• Compile this project
• Flash Nucleo board
• Execute and debug (breakpoint) each sample code
15
Play
CodeSamples : Install Keil
• Install latest version (5.x) of Keil uVision IDE
from ARM (www.keil.com)
• Download MDK-ARM
• The free Lite Edition is enough (code and data size
limited to 32 KB)
• Once installed, double-click on this file to open
the project in Keil
• example\Nucleo\Projects\Multi\Examples\VL6180X\
CodeSamples\MDK-ARM\STM32F401RENucleo\STM32F401Nucleo-Sample.uvprojx
16
Play
CodeSamples : Open Project
• The project is already configured and is ready
to be compiled
17
Play
CodeSamples : See Project config
• Project configuration can be seen as follows
1. Right-click on the project
2. Options for Target ‘xxx’…
3. See project configuration window
1
2
3
18
Play
CodeSamples : Compile
• Compile the project by clicking on one of the
Build buttons
Build
Rebuild (clean and build)
19
Play
CodeSamples : Flash the board
• Connect Nucleo board to PC through USB cable
• Flash the board with the compiled code by clicking
on the Download button
Download
20
Play
CodeSamples : Start the demo
• Once code is downloaded, press the reset
black button to start the demo
Reset
• Read CodeSamples demo User Manual to get more details on
various modes
21
Play
CodeSamples : Debug the demo
• Alternatively, run the demo with the debugger
1.
2.
3.
4.
Press Start/Stop debug button
Double click on any code lines to set a breakpoint
Run the demo by pressing the run button
Demo will stop at the breakpoint and you can step into/over functions
1
3
4
2
22
Play
CodeSamples : Analyze the code
• Using Keil (or any other IDE) is great to analyze
the code and jump from functions to functions
1.
2.
3.
Select a function with the mouse
Right-Click and select Go To Definition Of…
This will open the function implementation
1
2
23
API Integration Procedure
Discover
Play
Port Single
Device
Select operating
mode
Tune for your
application
Port Multiple
Devices
24
Port Single
Device
Port API
• Following slides describe step-by-step the procedure to port the API code onto customer
platform
• Pre-requisites/Assumptions
•
•
•
•
Customer CPU supports standard C code compiling (C99)
Porting is done by a SW engineer familiar with targeted CPU, compiler and toolchain
I2C low-level C driver (read/write) is already available and validated for the targeted paltform
A dummy ranging project is already created by customer and is able to do simple I2C read/write
access through the I2C low-level driver
• Purpose is to upgrade the customer ranging project so that it can run a basic ranging
operation (SimpleRaning sample code) with a single VL6180X device connected on I2C
bus of the CPU
25
Port Single
Device
Port API : Step 1
• Unzip VL6180X_API_x.x.x_Mass_Market.zip
• Copy following files into the customer ranging project (most probably in some Include
and Src directories)
• API core (must never be modified by customer)
• core/inc/vl6180x_api.h
• core/inc/vl6180x_def.h
• API static configuration (should not be modified by customer)
• config/extended_range/vl6180x_cfg.h
• API platform-dependent files (must be modified by customer)
• platform/template/vl6180x_platform.h
• platform/template/vl6180x_types.h
• platform/cci-i2c/vl6180x_i2c.h and platform/cci-i2c/vl6180x_i2c.c
• Modify the customer ranging project so that new files are compiled when project is built
• Add this line in main.c file to include API definitions
• #include “vl6180x_api.h”
• Compile the customer ranging project
• There will be some compiling errors
• This is expected and fixing these errors is part of the API porting flow
• See next slides…
26
Port Single
Device
Port API : Step 2
• vl6180x_platform.h
• Some includes like <unistd.h> or <pthread.h> could not be found in the targeted
platform. If this is the case, remove them (needed only for advance usage of the API)
• By default, API is configured/optimized to handle a single VL6180X device on the
bus
• #define VL6180x_SINGLE_DEVICE_DRIVER 1
• VL6180xDev_t is a generic device type which does the link between API and
platform abstraction layer. All API functions take as input a variable of this type which
is passed from functions to functions down to customer I2C low-level driver
• By default, VL6180xDev_t is defined as uint8_t and is meant to host the device I2C address
• API polling functions (such as VL6180x_RangePollMeasurement()) rely on the
VL6180x_PollDelay() function defined in vl6180x_platform.h. Depending on
customer platform constraints (multi-thread, RTOS, …), this function/macro can be
adapted by customer
• By default, VL6180x_PollDelay() does nothing
• Most of the API functions have a basic logging mechanism that can be enabled for
debugging purpose (function entry/exit). This logging mechanism is implemented
through several macros that should be defined in vl6180x_platform.h
• By default VL6180X_LOG_ENABLE macro is set to 0, meaning logging is disabled so no
need to concentrate on the logging macros now
• [New in API 3.1.0] Two macros called VL6180x_HAVE_MULTI_READ and
VL6180x_CACHED_REG are defined and set to 1 by default. This allows to improve
speed performance of post-processing operations made in the API by using multi
read I2C transfers
27
Port Single
Device
Port API : Step 3
• vl6180x_types.h
• This file holds basic type definitions that may require modifications
• By default it relies on
• <stdint.h> for signed and unsigned 8/16/32 bits types
• <stddeh.h> for NULL definition
• If the 2 above files are provided by the compiler, it is enough to include
them, otherwise, customer must define the types for his platform
• #include <linux/types.h> for instance for Linux
• At this stage, all compiling errors should be fixed. Let’s focus now
on remaining linking errors
• Undefined symbol VL6180x_I2CRead (referred from vl6180x_i2c.o)
• Undefined symbol VL6180x_I2CWrite (referred from vl6180x_i2c.o).
28
Port Single
Device
Port API : Step 4
• All API functions rely on a set of 8 read/write functions (CCI-like interface)
•
•
•
•
•
•
•
•
VL6180x_WrByte()
VL6180x_WrWord()
VL6180x_WrDWord()
VL6180x_UpdateByte()
VL6180x_RdByte()
VL6180x_RdWord()
VL6180x_RdDWord()
VL6180x_RdMulti() only if VL6180x_HAVE_MULTI_READ is set to 1 in vl6180x_platform.h
• In case customer I2C driver is CCI compliant, customer can simply call its CCI functions from the 7
functions above
• In case customer I2C driver exposes low level/raw I2C commands, a CCI to I2C translation layer is
proposed by ST in the vl6180x_i2c.c file. This implementation relies on two I2C raw access functions
that must be implemented by customer (to make the link with customer I2C driver)
• VL6180x_I2CRead(VL6180xDev_t dev, uint8_t* buff, uint8_t len)
• VL6180x_I2CWrite(VL6180xDev_t dev, uint8_t* buff, uint8_t len)
• If the proposed implementation of the 8 above functions is not adapted to customer I2C driver,
customer can adapt them
• At this stage, all compiling and linking errors should be fixed : API is ported !
• Time to start using it (see next slide)
29
Port Single
Device
Port API : Step 5
• Insert this code (from example/code_samples/vl6180x_simple_ranging.c) in the project
and call the Sample_SimpleRanging() function from main.c file
• Implement following functions (see examples for Nucleo)
•
•
•
•
•
MyDev_Init()
MyDev_SetChipEnable()
MyDev_uSleep()
MyDev_ShowRange()
MyDev_ShowErr()
30
API Integration Procedure
Discover
Play
Port Single
Device
Select operating
mode
Tune for your
application
Port Multiple
Devices
31
Port
Multiple
Devices
How to control several devices ?
• Assumptions
• API has already been ported following the 5 steps described above (single
device)
• Several devices are connected to the same I2C bus of host CPU
• Each VL6180X device can be put out of reset separately by the CPU
• The procedure consists in initializing each device one by one and
for each to change its I2C address so that it can be accessed by
the CPU with a dedicated address
• Before applying this procedure, API platform layer must be slightly
adapted for multi-device support
• See next slides…
32
Port
Multiple
Devices
Adapt API platform layer for multi-devices
• In vl6180x_platform.h API file
• Set VL6180x_SINGLE_DEVICE_DRIVER macro to 0 so that API
implementation will be automatically adapted to a multi-device
context
• #define VL6180x_SINGLE_DEVICE_DRIVER 0
• Define VL6180xDev_t type as a structure pointer holding any data
required for multi-device management. A mandatory field is an
instance of VL6180xDevData containing ST API private data
• Here is an example
33
Port
Multiple
Devices
Multi device init sequence
• Pseudo-code shown here is extracted from
RangingWithSatellites Nucleo main.c file
• First, reset of devices:
34
Port
Multiple
Devices
Multi device init sequence
Optional
35
API Integration Procedure
Discover
Play
Port Single
Device
Select operating
mode
Tune for your
application
Port Multiple
Devices
36
Select
operating
mode
Select best VL6180X operating mode
• VL6180X device can operate in 2 different modes
• Single shot measurement
• RangeReady known from register polling
• Continuous measurement
• RangeReady known from interrupt generated by the device
• Warning : WAF not functional in this mode !
• Based on these 2 modes, VL6180X API exposes 3 different operating
modes
• Polling
• Interrupt
• Asynchronous
37
Select
operating
mode
API operating
mode
VL6180X operating modes
Description
API functions
VL6180X
mode
Comments
Polling
Host call a
blocking API
function that
requests single
shot
measurements
and waits for the
result
VL6180x_RangePollMeasurement
Single Shot
Recommended for
first API porting or
debug : simple but
CPU is blocked during
ranging
Interrupt
Host programs
the device in
continuous mode
and ranging
results are
retrieved from
interrupts
VL6180x_RangeSetInterMeasPeriod
VL6180x_SetupGPIO1
VL6180x_RangeConfigInterrupt
VL6180x_RangeStartContinuousMode
VL6180x_RangeGetMeasurement
VL6180x_ClearAllInterrupt
Continuous
Recommended for
User Detection
applications where
CPU is interrupted by
VL6180X so can be
asleep when no
target is detected
(power saving)
Asynchronous /
FreeRunning
Host requests a
single shot
measurement
and regularly
check if result is
ready or not
VL6180x_RangeStartSingleShot
VL6180x_RangeGetMeasurementIfReady
Single Shot
Recommended for
AF-Assist
applications,
Android OS-based
system where CPU is
synchronized by
EOF/SOF from
camera or by a timer
so that top application
controls measurement
periods
38
Select
operating
mode
Polling mode
CPU
VL6180X
InitData(), Prepare()
RangePollMeasurement()
RangePollMeasurement()
Ranging
RangePollMeasurement()
Ranging
 Easy to use
 CPU busy
Display in Slide Show mode
39
Select
operating
mode
Interrupt mode
CPU
VL6180X
InitData(), Prepare()
RangeStartContinuousMode()
Ranging
Idle or other tasks
(and wait for VL6180X interrupt)
Ranging
Idle or other tasks
(and wait for VL6180X interrupt)
Ranging
Idle or other tasks
(and wait for VL6180X interrupt)
 CPU free during ranging
 Interrupt to be managed
GPIO1 INT
RangeGetMeasurement()
Display in Slide Show mode
40
Select
operating
mode
Asynchronous mode
CPU
VL6180X
InitData(), Prepare()
RangeStartSingleShot()
Ranging
Ranging
EXT interrupt
(every x ms)
Idle or other tasks
(and wait for interrupt)
Ranging
Ranging
YES
RangeGetMeas
urementIfReady
()
 CPU free during ranging
 Asynchronous behaviour
NO
Display in Slide Show mode
41
API Integration Procedure
Discover
Play
Port Single
Device
Select operating
mode
Tune for your
application
Port Multiple
Devices
42
Tune for
your
application
Make use of API error codes
• List of API Ranging measurement functions returning errorStatus in the Range structure (pRangeData):
•
•
•
VL6180x_RangePollMeasurement (VL6180xDev_t dev, VL6180x_RangeData_t *pRangeData)
VL6180x_RangeGetMeasurementIfReady (VL6180xDev_t dev, VL6180x_RangeData_t *pRangeData)
VL6180x_RangeGetMeasurement (VL6180xDev_t dev, VL6180x_RangeData_t *pRangeData)
• When calling one of the 3 “Ranging measurment” API functions, application must check the Range.errorStatus before
using the returned distance
•
•
If Range.errorStatus is null, returned distance is valid
Otherwise, application can use the Range.errorStatus value to known the reason for not getting a valid distance and try to
“guess” where the target could be
• It is strongly recommended that application calls the VL6180x_RangeGetMeasurementIfReady() API function to get
ranging data as this is the function which is able to return all supported errorStatus…
43
Tune for
your
application
API errorStatus codes
Valid distance
Shall not occur during ranging, can happen
only after boot-up if device is defective
Happens only if ECE check is enable, meaning
that device detected that no target is present
(ECE is off by default in extended-range)
Not valid target detected after maximum
convergence time
Too much ambient light detected
Distance filtered by WAF
[Added in API 3.1.0] WAF decision on-going
[Removed in API 3.2.0]
[New in API 3.1.0] Ranging data not ready
44
Tune for
your
application
Ranging API error status codes
(details)
• Error 8 : No Target Ignore
• Error 12 or 14 : Ranging underflow
• This could happen if target is very close (0 to 10 mm) and offset is not correctly
set-up, leading to a small negative value (user putting finger on device)
• This might also happens when a bright target is very far (between 1.2m and 1.5
m) but this will most probably be filtered by WAF => error 16
• Differentiation between the 2 cases can be done by checking the return signal
rate
• Error 13 or 15 : Ranging overflow
• Theoretically, this error happens when the target is detected by the device but is
placed at a high distance resulting in internal variables/registers overflow
• This means the target in at > 55cm distance
• As a side effect, this error can also happen in case of high compensated xTalk
and when no target is detected : because of high xTalk, signal rate could be
higher than 0.175 Mcps and lower than xTalk : this shall never happen because
signaRate=xTalk+targetSIgnalRate, but due to noise introduced by xTalk
compensation, this could happen and this error could be generated
0 No Error
1 VCSEL Continuity Test
2 VCSEL Watching Test
3 VCSEL Watchdog
4 PLL1 Lock
5 PLL2 Lock
6 ECE
7 Max Convergence
8 No Target Ignore
11 Max Signal To Noise Ratio
Raw Ranging Algo
12
Underflow
13 Raw Ranging Algo Overflow
14 Ranging Algo Underflow
15 Ranging Algo Overflow
16 Measure filtered (WAF)
18 Range Data Not Ready
45
Tune for
your
application
Ranging API error codes
(details)
• Error 16 : Filtered by post-processing (WAF)
• This error happens when WAF detects a target in a wrap-around
condition so instead of returning a wrong (largely under-estimated)
distance, this error code is returned
• When this error is returned, application knows that a bright target is
between 60 cm and 120 cm
• Error 18 : ranging data not ready [New in API 3.1.0]
• This error is returned by the VL6180x_RangeGetMeasurementIfReady()
API function when new ranging sample data is not ready
• Application must simply wait a bit and call again
VL6180x_RangeGetMeasurementIfReady()
0 No Error
1 VCSEL Continuity Test
2 VCSEL Watching Test
3 VCSEL Watchdog
4 PLL1 Lock
5 PLL2 Lock
6 ECE
7 Max Convergence
8 No Target Ignore
11 Max Signal To Noise Ratio
Raw Ranging Algo
12
Underflow
13 Raw Ranging Algo Overflow
14 Ranging Algo Underflow
15 Ranging Algo Overflow
16 Measure filtered (WAF)
18 Range Data Not Ready
46
Tune for
your
application
Scaling factor
• VL6180X default scaling factor is x1 (defined in API static
configuration) which allows max ranging capabilities to up to
~200 (100 mm being guaranteed by specification)
• Scaling factor could be increased to x2 or even x3 to extend
ranging capabilities of the device (but not guaranteed by ST)
• A single API function allows to change the scaling factor of the
device : VL6180x_UpscaleSetScaling()
• Offset and xTalk calibration procedures depend on the used
scaling factor so API calibration functions are also provided
to manage this dependency transparently for the application
• VL6180x_SetOffsetCalibrationData()
• VL6180x_SetXTalkCompensationRate()
47
Tune for
your
application
Wrap-Around Filter (WAF)
• This is an effect linked to the ratio between the VCSEL pulse period and
the photon return pulse
• High reflective targets (like mirrors) placed at far distance (>60cm) from
VL6180X could still produce enough return signal for VL6180X to declare
a valid target and meat the wrap-around condition resulting in a wrong
(under-estimated) returned distance
• WAF implemented in API is able to automatically detect that a target is in
the WA conditions and is able to filter it by returning an invalid distance
(error status 16) instead of a wrong under-estimated one
• A dedicated error code is returned by the API
• 16 : Measure filtered by WAF
VCSEL Pulse
Associated return
photon
Return Photons
48
Tune for
your
application
Dmax
Dmax estimation
• A target placed in front of VL6180X may not be detected because it is too
far for the given ambient light conditions (too high)
• When ambient light level increases, max detection range (Dmax) decreases
• When no target is detected (no valid distance), VL6180X API is able to
estimate Dmax being defined as
• The maximum distance up to which a 17% target would have been detected with the
current ambient light level
• When no target is detected by VL6180X, the application can interpret the
Dmax value as follows
• No target is detected and there is no 17% (or above) target between 0 and Dmax
mm
• This could be used by Hybrid AF algorithm to start a standard full search
from Dmax (to infinity) to reduce the focus time when target is too far from
VL6180X
• Dmax calculation constraints & limitations
• A correction factor is applied to slightly under-estimate the returned Dmax value:
since it can be important to ensure Dmax is never over-estimated.
• Dmax is estimated for a 17% reflectance target. This means that if the real target has
a lower reflectance (black target for instance), Dmax calculated by the API could be
overestimated.
49
DONE 
From API 3.0.2 to API 3.1.0
Porting Guide
• Adapt application code to the new behavior of the
VL6180x_RangeGetMeasurementIfReady() API function
• In API 3.0.2, “Data not Ready” was returned in the function status
• In API 3.1.0, “Data not Ready” is returned in the Range.errorStatus as 18 code
• See API sample code : vl6180x_freeruning_ranging.c
• Optionally, add following macros in vl6180x_platform.h file to benefit from
the new “Cached Register” feature based on I2C multi read (to speed-up
ranging thanks to I2C multi read operations)
• #define VL6180x_HAVE_MULTI_READ 1
• #define VL6180x_CACHED_REG 1
• Adapt application to take benefit from new error status returned by the
VL6180x_RangeGetMeasurementIfReady() function
• 17 : WAF decision on-going
• Application should not take drastic decision
• 18 : Data not read
52
From API 3.1.0 to API 3.2.0
Porting Guide
• Adapt application in case errorStatus 17 is
used
• This errorStatus code is not produced anymore by
API 3.2.0 so application can not rely on it anymore
54
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement