VL6180X 官网API移植过程

UM1876 User manual Getting started with VL6180X proximity, gesture, ambient light sensor software expansion for STM32Cube

7 Application programming interface (API)

The VL6180X API is a set of C functions controlling the VL6180X (init, ranging, ALS,…) to enable the development of end-user applications. This API is structured in a way it can be compiled on any kind of platforms through a well isolated platform layer (mainly for low level I2C access). Several code examples are provided to show how to use API and perform ranging and ALS measures. A complete Nucleo F401 + VL6180X expansion board project is also provided (Keil IDE required to compile the project) as well as the pre-compiled binary that can be directly used.

API download

To download VL6180X API:

• on st.com, search for “VL6180X”
• on next page select: “VL6180X”
• On next page select “design resources”
• On “design resources” page select “STSW-IMG003”
• On next page “download”

Quick start guide for API integration

API documentation is in the “docs” folder and is available in two formats:

• API_Documentation_proximity.chm
• API_Documentation_proximity.html

The VL6180X API is integrated in a software project in two steps
1. Developer has to add/link the files listed in Table 8 and in Figure 65 to his source and include code path. Some files may require modifications to comply with the final application or the hardware/software capabilities.

2. To manage the data communication between the VL6180X and the host, the developer has to design a camera control interface (CCI) register communication driver.
The API low-level functions rely on the following set of 7 read & write functions which perform CCI register access to the device:
        VL6180x_WrByte(); VL6180x_WrWord(); VL6180x_WrDWord();VL6180x_UpdateByte(); VL6180x_RdByte(); VL6180x_RdWord();VL6180x_RdDWord().
To implement these 7 functions, it is recommended to use vl6180x_i2c.c and vl6180x_i2c.h files in platform/cci_i2c directory (see Figure 65)

Note: Detailed information on these functions can be found in section Modules/CCI to RAW I2C translation layer of the API_Documentation_(version)_proximity.chm delivery

---

en.STSW-IMG003\STSW-IMG003_VL6180X_API_3.2.2_Mass_Market\docs\VL6180X_API_IntegrationGuide

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…

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. The user must implement this function accordingly, 1 ms delay is the recommended value.
    • • By default, VL6180x_PollDelay() is dummy
  • • 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 

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). 

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) 

Port API : Step 5

• • Insert this code (from example/code_samples/vl6180x_simple_ranging.c) in the projectand 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()