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

Table of contents

Other ST Microcontroller manuals

Popular Microcontroller manuals by other brands

AMS

AMS AS7261 Demo Kit user guide

Novatek

Novatek NT6861 manual

Espressif Systems

Espressif Systems ESP8266 SDK AT Instruction Set

Nuvoton

Nuvoton ISD61S00 ChipCorder Design guide

STMicrolectronics

STMicrolectronics ST7 Assembler Linker user manual

Texas Instruments

Texas Instruments Chipcon CC2420DK user manual

Lantronix

Lantronix Intrinsyc Open-Q 865XR SOM user guide

NEC

NEC 78GK0S/K 1+ Series Application note

Mikroe

Mikroe SEMITECH N-PLC Click Application note

Intel

Intel Agilex user guide

Cypress

Cypress CY4607 HX2VL quick start guide

DIGITAL-LOGIC

DIGITAL-LOGIC MICROSPACE manual

Texas Instruments

Texas Instruments TMS320F2837 D Series Workshop Guide and Lab Manual

CYPRES

CYPRES CY14NVSRAMKIT-001 user guide

Texas Instruments

Texas Instruments INA-DUAL-2AMP-EVM user guide

Espressif Systems

Espressif Systems ESP8266EX Programming guide

Abov

Abov AC33M8128L user manual

Laird

Laird BL654PA user guide