ST VD6283 User manual

Introduction
VD6283 is an ambient light sensor with a flicker extraction engine.
The purpose of this user manual is to describe the integration model and the set of functions to use the VD6283 bare driver.
References
• UM2867 - Getting started with the STMicroelectronics X-CUBE-ALS software package for STM32CubeMX
• DS13735 - Hybrid filter multispectral sensor with light flicker engine
Getting started with VD6283 multispectral sensor application programming
interface
UM2878
User manual
UM2878 - Rev 1 - June 2021
For further information contact your local STMicroelectronics sales office.
www.st.com

1VD6283 system overview
VD6283 system is composed of the VD6283 module and a driver running on the host.
Figure 1. VD6283 system
This document describes the driver functions accessible to the Host, to control the device and get:
• ALS value
• CCT / Lux calculation
• Flicker extraction
This driver is OS agnostic, meaning that it can be integrated in a SW stack of any customer platform without any
modification.
The bare driver is an implementation of a set of functions required to use the VD6283 device. It makes minimal
assumptions on the OS integration and services. As such, sequencing of actions, execution/threading model,
platform adaptation, and device structure allocation are not part of the bare driver implementation but left open to
the integrator.
The sequencing of bare driver calls must follow a set of rules, defined in this document.
UM2878
VD6283 system overview
UM2878 - Rev 1 page 2/27

2Description of modes
The VD6383 device supports several modes that are described in the following diagrams. The diagrams in the
following sections show two channels, blue and red, enabled as an example to describe the device behavior.
2.1 Synchronous mode without intermeasurement period
The following diagram shows how to use the bare driver to collect light count values in synchronous mode without
any intermeasurement.
Figure 2. Bare driver signals without intermeasurement period
UM2878
Description of modes
UM2878 - Rev 1 page 3/27

2.2 Synchronous gated mode with intermeasurement period
The following diagram shows how to use the bare driver to collect light count values in synchronous mode with an
intermeasurment period.
Figure 3. Bare driver signals with intermeasurement period
UM2878
Synchronous gated mode with intermeasurement period
UM2878 - Rev 1 page 4/27

2.3 Single shot
The following diagram shows how to use the bare driver to collect light count values in a single shot mode.
Figure 4. Bare driver signals in single shot
UM2878
Single shot
UM2878 - Rev 1 page 5/27

3Bare driver basic functions
3.1 Power modes
The device supports the following three different power modes:
• OFF: State of the device when the device is not powered
• IDLE: This is the state of the device when not measuring the ambient light events and not detecting flicker.
On this device Idle and stopped are the same states. Powering on the device and calling the STALS_init
function sets the device in IDLE mode.
• STARTED: The device is running light count events and/or flicker detection. Power consumption can be
reduced by setting an intermeasurement period with the STALS_SetInterMeasurementTime function for the
light count measurement
Figure 5. Power modes
3.2 STALS API definition
3.2.1 STALS_ErrCode_t STALS_GetVersion
STALS_ErrCode_t STALS_GetVersion (uint32_t *pVersion, uint32_t *pRevision)
This function provides the driver version of the VD6283.
Table 1. Parameters
Parameter Description
pVersion Pointer on a value that contains the version of the driver once this function is called
pRevision Pointer on a value that contains the revision of the driver once this function is called
Note: The MAJOR number of version sits in the upper 16 bits of *pVersion. The MINOR number of version sits in the
lower 16 bits of *pVersion. The *pRevision value contains the revision of the driver.
Table 2. Return values
Return value Description
STALS_NO_ERROR Success
STALS_ERROR_INVALID_PARAMS At least one of the provided parameters to the function is invalid
UM2878
Bare driver basic functions
UM2878 - Rev 1 page 6/27

3.2.2 STALS_ErrCode_t STALS_Init
STALS_ErrCode_t STALS_Init(char *pDeviceName, void *pClient, void **pHandle )
This function initializes the STALS driver.
Table 3. Parameters
Parameter Description
pDeviceName Name of the device. Shall be VD6283
pClient Pointer on a client specific platform specific structure, provided up to the underlying
platform adaptation layers
pHandle Pointer on an opaque pointer to be used as the id of the instance of the driver
Note: If the slave address is set to the default address of the device, then the GPIO pin does not need to be set to
low. To set a new I2C slave address, the GPIO1 pin MUST be set to low. The Init function then performs an I2C
transaction with this I2C slave address. As this transaction is the first one after the power up of the device, it will
set this new slave address and all further I2C address shall be performed with this I2C slave address.
A call to the STALS_Init function shall be done to set the VD6283 device in IDLE mode.
The VD6283 device needs a delay between powering it and calling STALS_Init. Please refer to the device user
manual for more details.
Table 4. Return values
Return value Description
STALS_NO_ERROR Success
STALS_ERROR_INIT Could not initialize the driver
STALS_ERROR_INVALID_PARAMS At least one of the provided parameters to the function is invalid
STALS_ERROR_WRITE Could not write any data into the device through I2C
3.2.3 STALS_ErrCode_t STALS_Term
STALS_ErrCode_t STALS_Term (void *pHandle)
This function terminates the provided STALS driver instance.
Table 5. Parameters
Parameter Description
pHandle Opaque pointer used as the id of the instance of the driver
Table 6. Return values
Return value Description
STALS_NO_ERROR Success
STALS_ERROR_INVALID_PARAMS At least one of the provided parameters to the function is invalid
UM2878
STALS API definition
UM2878 - Rev 1 page 7/27

3.2.4 STALS_ErrCode_t STALS_GetChannelColor
STALS_ErrCode_t STALS_GetChannelColor (void *pHandle, enum STALS_Channel_Id_t ChannelId, enum
STALS_Color_Id_t *pColor)
This function returns the color filter of the provided channel identifier.
Table 7. Parameters
Parameters Description
pHandle Opaque pointer used as the id of the instance of the driver
ChannelId See Section 3.5.1 Channel Id. Permitted values are 0 up to
STALS_ALS_MAX_CHANNELS - 1
pColor Pointer on a value in which the color of the channel is returned
Table 8. Return values
Return values Description
STALS_NO_ERROR Success
STALS_ERROR_INVALID_PARAMS At least one of the provided parameters to the function is invalid
3.2.5 STALS_ErrCode_t STALS_SetExposureTime
STALS_ErrCode_t STALS_SetExposureTime (void *pHandle, uint32_t ExpoTimeInUs, uint32_t
*pAppliedExpoTimeUs)
This function sets the exposure time in the device, after having tuned to the closest value that the device can
support.
Note that a fixed readout period of ~6 ms takes place just after exposure time. This is needed by the device to set
the event count values in the registers. It also returns the actual applied value in the device.
For VD6283 possible values are multiples of 1.6 ms with a range of 1.6 ms to 1.6 s.
Note: Exposure time is irrelevant for flicker detection.
Table 9. Parameters
Parameter Description
pHandle Opaque pointer used as the id of the instance of the driver
ExpoTimeInUs Exposure time in microseconds
pAppliedExpoTimeUs Pointer on in which the value of the actual exposure time is returned
Table 10. Return values
Return value Description
STALS_NO_ERROR Success
STALS_ERROR_INVALID_PARAMS At least one of the provided parameters to the function is invalid
STALS_ERROR_ALREADY_STARTED Exposure can not be set when the device is running
STALS_ERROR_WRITE Could not write any data in the device through I2C
UM2878
STALS API definition
UM2878 - Rev 1 page 8/27

3.2.6 STALS_ErrCode_t STALS_GetExposureTime
STALS_ErrCode_t STALS_GetExposureTime (void *pHandle, uint32_t *pAppliedExpoTimeUs)
This function returns the actual exposure time.
Table 11. Parameters
Parameters Description
pHandle Opaque pointer used as the id of the instance of the driver
pAppliedExpoTimeUs Pointer in which the value of the actual exposure time is returned
Table 12. Return values
Return values Description
STALS_NO_ERROR Success
STALS_ERROR_INVALID_PARAMS At least one of the provided parameters to the function is invalid
3.2.7 STALS_ErrCode_t STALS_SetInterMeasurementTime
STALS_ErrCode_t STALS_SetInterMeasurementTime (void *pHandle, uint32_t InterMeasurmentInUs, uint32_t
*pAppliedInterMeasurmentInUs)
This function sets an intermeasurement time into the device, after having tuned to the closest value that the
device can support.
It also returns the actual applied value in the device
Table 13. Parameters
Parameters Description
pHandle Opaque pointer used as the id of the instance of the driver
InterMeasurmentInUs Intermeasurement value in micro seconds
pAppliedInterMeasurmentInUs Pointer in which the value of the actual intermeasurement time is returned
Table 14. Return values
Return values Description
STALS_NO_ERROR Success
STALS_ERROR_INVALID_PARAMS At least one of the provided parameters to the function is invalid
STALS_ERROR_ALREADY_STARTED Intermeasurement can not be set when the device is running
STALS_ERROR_WRITE Could not write any data on the device through I2C
UM2878
STALS API definition
UM2878 - Rev 1 page 9/27

3.2.8 STALS_ErrCode_t STALS_GetInterMeasurementTime
STALS_ErrCode_t STALS_GetInterMeasurementTime (void *pHandle, uint32_t *pAppliedInterMeasurmentInUs)
This function returns the actual intermeasurement.
Table 15. Parameters
Parameter Description
pHandle Opaque pointer used as the id of the instance of the driver
pAppliedInterMeasurmentInUs Pointer in which the value of the actual intermeasurement time is returned
Table 16. Return values
Return value Description
STALS_NO_ERROR Success
STALS_ERROR_INVALID_PARAMS At least one of the provided parameters to the function is invalid
3.2.9 STALS_ErrCode_t STALS_GetProductVersion
STALS_ErrCode_t STALS_GetProductVersion (void *pHandle, uint8_t *pDeviceID, uint8_t *pRevisionID)
This function returns the version of the device.
Table 17. Parameters
Parameter Description
pHandle Handle on the driver instance
pDeviceID Pointer in which the ID of the device is returned
pRevisionID Pointer in which the revision of the device is returned
Table 18. Return values
Return value Description
STALS_NO_ERROR Success
STALS_ERROR_INVALID_PARAMS At least one of the provided parameters is invalid
STALS_ERROR_WRITE Could not write any data on the device through I2C
UM2878
STALS API definition
UM2878 - Rev 1 page 10/27