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

3.2.10 STALS_ErrCode_t STALS_GetUid
STALS_ErrCode_t STALS_GetUid (void *pHandle, char **pUid)
This function returns the device unique id. Unique id is a null terminated string.
Table 19. Parameters
Parameter Description
pHandle Opaque pointer used as the id of the instance of the driver
pUid Pointer on a char pointer in which address of uid string will be set
Table 20. Return values
Return value Description
STALS_NO_ERROR Success
STALS_ERROR_INVALID_PARAMS At least one of the provided parameters is invalid
3.2.11 STALS_ErrCode_t STALS_SetGain
STALS_ErrCode_t STALS_SetGain (void *pHandle, enum STALS_Channel_Id_t ChannelId, uint16_t Gain,
uint16_t *pAppliedGain)
This function sets an analog gain on the provided channel id.
Note: The gain impacts the signal output amplitude, but not the values returned by STALS_GetFlicker, unless the gain
exceeds a maximum value that will flatten the signal output because of its impact on saturation.
Table 21. Parameters
Parameter Description
pHandle Opaque pointer used as the id of the instance of the driver
ChannelId This id identifies the channel number. See Section 3.5.1 STALS_Channel_Id_t
Gain Gain in 8.8 fixed point unit
pAppliedGain Pointer in which the value of the actual gain applied in the device is returned. Value
in 8.8 fixed point unit
Table 22. 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 Gain can not be set when the device is running
STALS_ERROR_WRITE Could not write any data in the device through I2C
STALS_ERROR_READ Could not read any data from the device through I2C
UM2878
STALS API definition
UM2878 - Rev 1 page 11/27

3.2.12 STALS_ErrCode_t STALS_GetGain
STALS_ErrCode_t STALS_GetGain (void *pHandle, enum STALS_Channel_Id_t ChannelId, uint16_t
*pAppliedGain)
This function gets the actual gain applied in the device.
Table 23. Parameters
Parameter Description
pHandle Opaque pointer used as the id of the instance of the driver
ChannelId This id identifies the channel number. See Section 3.5.1 STALS_Channel_Id_t
pAppliedGain Pointer in which the value of the actual gain applied in the device is returned. Value
in 8.8 fixed point unit
Table 24. 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.13 STALS_ErrCode_t STALS_SetFlickerOutputType
STALS_ErrCode_t STALS_SetFlickerOutputType (void *pHandle, enum STALS_FlickerOutputType_t
FlickerOutputType)
This function sets the gpio settings of GPIO2 and GPIO1 according to FlickerOutputType.
Note that those parameters are effectively applied when flicker is started.
Table 25. Parameters
Parameters Description
pHandle Opaque pointer used as the id of the instance of the driver
FlickerOutputType Data output type for the flicker mode. See
Section 3.5.7 STALS_FlickerOutputType_t
Table 26. Return values
Return values 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 to the device through I2C
STALS_ERROR_READ Could not read any data from the device through I2C
UM2878
STALS API definition
UM2878 - Rev 1 page 12/27

3.2.14 STALS_ErrCode_t STALS_Start
STALS_ErrCode_t STALS_Start (void *pHandle, enum STALS_Mode_t Mode, uint8_t Channels)
This function starts the device.
Table 27. Parameters
Parameter Description
pHandle Opaque pointer used as the id of the instance of the driver
Mode
Mode shall be STALS_MODE_ALS_SINGLE_SHOT,
STALS_MODE_ALS_SYNCHRONOUS or STALS_MODE_FLICKER. See
Section 3.5.6 enum STALS_Mode_t
Channels For the ALS modes, this is an OR value of the STALS_Channel_Id_t channels. For
the flicker mode, this is one of the STALS_Channel_Id_t channels.
Note: As the ALS and FLICKER modes can run independently, two consecutive calls to this START function with
STALS_MODE_ALS_SYNCHRONOUS and STALS_MODE_FLICKER modes are permitted.
Example to activate RGB channel:
void *hdl;
...
STALS_Start (hdl, STALS_MODE_ALS_SINGLE_SHOT, STALS_CHANNEL_1 | STALS_CHANNEL_3 |
STALS_CHANNEL_4)
3.2.15 STALS_ErrCode_t STALS_Stop
STALS_ErrCode_t STALS_Stop (void *pHandle, enum STALS_Mode_t Mode )
This function stops the device.
Table 28. Parameters
Parameter Description
pHandle Opaque pointer used as the id of the instance of the driver
Mode
Mode shall be STALS_MODE_ALS_SINGLE_SHOT,
STALS_MODE_ALS_SYNCHRONOUS or STALS_MODE_FLICKER. See
Section 3.5.6 enum STALS_Mode_t
Table 29. 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_ALREADY_NOT_STARTED The device is not running the provided mode
STALS_ERROR_WRITE Could not write any data in the device through I2C
UM2878
STALS API definition
UM2878 - Rev 1 page 13/27

3.2.16 STALS_ErrCode_t STALS_GetAlsValues
STALS_ErrCode_t STALS_GetAlsValues (void *pHandle, uint8_t Channels, struct STALS_Als_t *pAlsValue,
uint8_t *pMeasureValid)
This function provides the event count values for the selected channels.
Table 30. Parameters
Parameter Description
pHandle Opaque pointer used as the id of the instance of the driver
Channels An OR value of the STALS_Channel_Id_t that sets the channels from which the
event count values are to be retrieved. See Section 3.5.1 STALS_Channel_Id_t
pAlsValue Pointer on a structure storing the counted event values
pMeasureValid Pointer on a flag indicating if the measurement is valid
Table 31. Return values
Reutrn value Description
STALS_NO_ERROR Success
STALS_ERROR_INVALID_PARAMS At least one of the provided parameters to the function is invalid
STALS_ERROR_WRITE Could not write any data in the device through I2C
STALS_ERROR_READ Could not read any data from the device through I2C
3.2.17 STALS_ErrCode_t STALS_GetFlickerFrequency
STALS_ErrCode_t STALS_GetFlickerFrequency (void *pHandle, struct STALS_FlickerInfo_t *pFlickerInfo)
This function returns the flicker main harmonic frequency.
Table 32. Parameters
Parameter Description
pHandle Opaque pointer used as the id of the instance of the driver
pFlickerInfo A pointer on an STALS_FlickerInfo_t structure
Table 33. Return values
Return value Description
STALS_NO_ERROR_FNCT_DEPRECA
TED Function not supported
UM2878
STALS API definition
UM2878 - Rev 1 page 14/27

3.2.18 STALS_ErrCode_t STALS_SetControl
STALS_ErrCode_t STALS_SetControl (void *pHandle, enum STALS_Control_Id_t ControlId, uint32_t
ControlValue )
This function sets a control to the STALS driver.
Table 34. Parameters
Parameter Description
pHandle Opaque pointer used as the id of the instance of the driver
ControlId Identifier of the params. See Section 3.5.5 enum STALS_Control_Id_t
ControlValue The value of the control
The following is an example pedestal:
AC_MODE (register 0x31) Pedestal on/off
0: pedestal added to help flicker detection in very low DC conditions
1: remove pedestal feature
• To enable the pedestal : STALS_SetControl(pHandle, STALS_PEDESTAL_ENABLE,
STALS_CONTROL_ENABLE);
• To disable the pedestal : STALS_SetControl(pHandle, STALS_PEDESTAL_ENABLE,
STALS_CONTROL_DISABLE);
AC_PEDESTAL (register 0x32) pedestal_value Pedestal_value (default = 5)
• To set pedestal value to 3: STALS_SetControl(pHandle, STALS_PEDESTAL_VALUE, 3);
Table 35. Return values
Return value Description
STALS_NO_ERROR Success
STALS_ERROR_INVALID_PARAMS At least one of the provided parameters is invalid
STALS_ERROR_FNCT_DEPRECATED ALS_AUTOGAIN_CTRL is deprecated
3.2.19 STALS_ErrCode_t STALS_GetControl
STALS_ErrCode_t STALS_GetControl (void *pHandle, enum STALS_Control_Id_t ControlId, uint32_t
*pControlValue)
This function gets a control from the STALS driver.
Table 36. Parameters
Parameter Description
pHandle Opaque pointer used as the id of the instance of the driver
ControlId Identifier of the parameters. See Section 3.5.5 STALS_Control_Id_t
pControlValue Pointer on a parameter in which the parameter value is set
Table 37. Return values
Return value Description
STALS_NO_ERROR Success
STALS_ERROR_INVALID_PARAMS At least one of the provided parameters is invalid
STALS_ERROR_FNCT_DEPRECATED ALS_AUTOGAIN_CTRL is deprecated
UM2878
STALS API definition
UM2878 - Rev 1 page 15/27

3.3 STALS.h file reference
3.3.1 Data structures
• struct STALS_FlickerInfo_t
This structure contains the fields filled by the driver and which contain the discovered information related to
the flicker.
• struct STALS_Als_t
This structure defines the parameters which provide the event counts values of the last light integration, for
the selected channels.
3.3.2 Macros
• #define STALS_ALS_MAX_CHANNELS 6
3.3.3 Enumerations
• enum STALS_Channel_Id_t {
STALS_CHANNEL_1 = 0x01, STALS_CHANNEL_2 = 0x02, STALS_CHANNEL_3 = 0x04,
STALS_CHANNEL_4 = 0x08, STALS_CHANNEL_5 = 0x10, STALS_CHANNEL_6 = 0x20 }
Constants listing the channels of the device.
• enum STALS_Color_Id_t {
STALS_COLOR_IR = 0x01, STALS_COLOR_RED = 0x02, STALS_COLOR_GREEN = 0x03,
STALS_COLOR_BLUE = 0x04, STALS_COLOR_UV = 0x05, STALS_COLOR_CLEAR = 0x06,
STALS_COLOR_CLEAR_IR_CUT = 0x07, STALS_COLOR_DARK = 0x08, STALS_COLOR_INVALID =
0xFF }
Constants listing the color light.
• enum STALS_ErrCode_t {
STALS_NO_ERROR = 0, STALS_ERROR_INVALID_PARAMS, STALS_ERROR_INIT,
STALS_ERROR_TIME_OUT, STALS_ERROR_INVALID_DEVICE_ID, STALS_ERROR_WRITE,
STALS_ERROR_READ, STALS_ERROR_ALREADY_STARTED, STALS_ERROR_NOT_STARTED,
STALS_ERROR_NOT_SUPPORTED, STALS_ERROR_FNCT_DEPRECATED,
STALS_ERROR_LAST_ERROR_CODE }
This enumeration is aimed at defining the different errors that can be returned by the STALS driver.
• enum STALS_Control_t { STALS_CONTROL_DISABLE = 0, STALS_CONTROL_ENABLE = 1 }
This enumeration is aimed at defining the Enable and disable flags.
• enum STALS_Control_Id_t {
STALS_PEDESTAL_ENABLE = 0, STALS_PEDESTAL_VALUE = 1, STALS_OUTPUT_DARK_ENABLE = 3,
STALS_SDA_DRIVE_VALUE_MA = 4, STALS_SATURATION_VALUE = 5, STALS_ALS_AUTOGAIN_CTRL
= 6, STALS_OTP_USAGE_ENABLE = 128, STALS_WA_STATE = 129 }
This enumeration is aimed at defining the different parameters identifiers.
• enum STALS_Mode_t { STALS_MODE_ALS_SINGLE_SHOT = 0, STALS_MODE_ALS_SYNCHRONOUS=
1, STALS_MODE_FLICKER = 2 }
This enumeration is aimed at defining the different behavior modes of the STALS device.
• enum STALS_FlickerOutputType_t {
STALS_FLICKER_OUTPUT_ANALOG = 0, STALS_FLICKER_OUTPUT_ANALOG_CFG_1 = 0,
STALS_FLICKER_OUTPUT_DIGITAL_PDM = 1, STALS_FLICKER_OUTPUT_ANALOG_CFG_2 = 2,
STALS_FLICKER_OUTPUT_ZC_CFG_1 = 3, STALS_FLICKER_OUTPUT_ZC_CFG_2 = 4 }
UM2878
STALS.h file reference
UM2878 - Rev 1 page 16/27

3.3.4 Functions
• STALS_ErrCode_t STALS_Init (char *pDeviceName, void *pClient, void **pHandle)
This function initializes the STALS driver.
• STALS_ErrCode_t STALS_Term (void *pHandle)
This function terminates the provided STALS driver instance.
• STALS_ErrCode_t STALS_GetVersion (uint32_t *pVersion, uint32_t *pRevision)
This function returns the bare driver version
• 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.
• STALS_ErrCode_t STALS_SetExposureTime (void *pHandle, uint32_t ExpoTimeInUs, uint32_t *pApplied
ExpoTimeUs)
This function sets the exposure time into the device, after having tuned to the closest value that the device
can support.
• STALS_ErrCode_t STALS_GetExposureTime (void *pHandle, uint32_t *pAppliedExpoTimeUs)
This function returns the actual exposure time.
• STALS_ErrCode_t STALS_SetInterMeasurementTime (void *pHandle, uint32_t InterMeasurmentInUs,
uint32_t *pAppliedInterMeasurmentInUs)
This function sets an inter measurement time into the device, after having tuned to the closest value that the
device can support.
• STALS_ErrCode_t STALS_GetInterMeasurementTime (void *pHandle, uint32_t *pAppliedInter
MeasurmentInUs)
This function returns the actual inter measurement.
• STALS_ErrCode_t STALS_GetProductVersion (void *pHandle, uint8_t *pDeviceID, uint8_t *pRevisionID)
This function returns the version of the device.
• STALS_ErrCode_t STALS_SetGain (void *pHandle, enum STALS_Channel_Id_t ChannelId, uint16_t Gain,
uint16_t *pAppliedGain)
This function sets an analog gain on the provided channel id.
• STALS_ErrCode_t STALS_GetGain (void *pHandle, enum STALS_Channel_Id_t ChannelId, uint16_t
*pAppliedGain)
This function gets the actual gain applied in the device.
• STALS_ErrCode_t STALS_SetFlickerOutputType (void *pHandle, enum STALS_FlickerOutputType_t
FlickerOutputType)
This function sets the GPIO settings for GPIO2 and GPIO1 according to FlickerOutputType.
• STALS_ErrCode_t STALS_Start (void *pHandle, enum STALS_Mode_t Mode, uint8_t Channels)
This function starts the device.
• STALS_ErrCode_t STALS_Stop (void *pHandle, enum STALS_Mode_t Mode)
This function stops the device.
• STALS_ErrCode_t STALS_GetAlsValues (void *pHandle, uint8_t Channels, struct STALS_Als_t *pAlsValue,
uint8_t *pMeasureValid)
This function provides the event counts values for the selected channels.
• STALS_ErrCode_t STALS_GetFlickerFrequency (void *pHandle, struct STALS_FlickerInfo_t *pFlickerInfo)
This function gets the flicker main harmonic frequency.
• STALS_ErrCode_t STALS_SetControl (void *pHandle, enum STALS_Control_Id_t ControlId, uint32_t
ControlValue)
This function sets a control to the STALS driver.
• STALS_ErrCode_t STALS_GetControl (void *pHandle, enum STALS_Control_Id_t ControlId, uint32_t
*pControlValue)
This function gets a control from the STALS driver.
• STALS_ErrCode_t STALS_GetUid (void * pHandle, char *pUid)
This function returns the device unique id.
UM2878
STALS.h file reference
UM2878 - Rev 1 page 17/27

3.4 Macro definition documentation
3.4.1 #define STALS_ALS_MAX_CHANNELS 6
Constants number of channels of the STALS
3.5 Enumeration type documentation
3.5.1 enum STALS_Channel_Id_t
Constants listing the channels of the device.
Enumerator
STALS_CHANNEL_1 lists the value of channel 1
STALS_CHANNEL_2 lists the value of channel 2
STALS_CHANNEL_3 lists the value of channel 3
STALS_CHANNEL_4 lists the value of channel 4
STALS_CHANNEL_5 lists the value of channel 5
STALS_CHANNEL_6 lists the value of channel 6
Table 38. VD6283 channel code
Channel number Filter color
Channel 1 Red
Channel 2 Visible
Channel 3 Blue
Channel 4 Green
Channel 5 IR
Channel 6 Clear
3.5.2 enum STALS_Color_Id_t
Constants listing the color light. This is used by the STALS_GetChannelColor function to get what color filters set
on the channels
Enumerator
STALS_COLOR_IR indicates color IR is set
STALS_COLOR_RED indicates color RED is set
STALS_COLOR_GREEN indicates color GREEN is set
STALS_COLOR_BLUE indicates color BLUE is set
STALS_COLOR_UV indicates UV filter - not available on VD6283
STALS_COLOR_CLEAR indicates clear filter is set
STALS_COLOR_CLEAR_IR_CUT indicates clear filter with ir cut is set
STALS_COLOR_DARK indicates opaque filter is set
STALS_COLOR_INVALID indicates channel is invalid and cannot be used
UM2878
Macro definition documentation
UM2878 - Rev 1 page 18/27

3.5.3 enum STALS_ErrCode_t
This enumeration is aimed at defining the different errors that can be returned by the STALS driver.
Enumerator
STALS_NO_ERROR indicates no error
STALS_ERROR_INVALID_PARAMS indicates provided parameters are invalid
STALS_ERROR_INIT indicates error in the initialization of the VD6283 device
STALS_ERROR_TIME_OUT indicates a time out has expired before an operation was completed
STALS_ERROR_INVALID_DEVICE_ID indicates the provided device identifier is invalid
STALS_ERROR_WRITE indicates the trial to write on the I2C bus has failed
STALS_ERROR_READ indicates the trial to read from the I2C bus has failed
STALS_ERROR_ALREADY_STARTED indicates the device is already started
STALS_ERROR_NOT_STARTED indicates the device is not started
STALS_ERROR_NOT_SUPPORTED indicates the called function is not supported, likely because not yet
implemented
STALS_ERROR_FNCT_DEPRECATED indicates the called function is deprecated
STALS_ERROR_LAST_ERROR_CODE
3.5.4 enum STALS_Control_t
This enumeration is aimed at defining the Enable and disable flags.
Enumerator
STALS_CONTROL_DISABLE disables the feature
STALS_CONTROL_ENABLE enables the feature
3.5.5 enum STALS_Control_Id_t
This enumeration is aimed at defining the different parameters identifiers.
Enumerator
STALS_PEDESTAL_ENABLE Control to be used to enable or disable the pedestal
• To enable the pedestal : STALS_SetControl(pHandle, STALS_PEDESTAL_ENABLE,
STALS_CONTROL_ENABLE);
• To disable the pedestal : STALS_SetControl(pHandle, STALS_PEDESTAL_ENABLE,
STALS_CONTROL_DISABLE);
• To know if the pedestal is enabled : enum STALS_Control_t Flag; STALS_GetControl(pHandle,
STALS_PEDESTAL_ENABLE, &Flag);
STALS_PEDESTAL_VALUE Control to set the value of the pedestal
For example : STALS_SetControl(pHandle, STALS_PEDESTAL_VALUE, 6);
STALS_OUTPUT_DARK_ENABLE Control to set if dark is output. For VD6283 dark count will be output on
channel 2.
STALS_SDA_DRIVE_VALUE_MA Control to set drive current in sda pad in mA when device is driving sda line.
Possible values for VD6283 are 4, 8, 12, 16, 20 mA.
STALS_SATURATION_VALUE Control to read saturation counter value.
STALS_ALS_AUTOGAIN_CTRL Control to configure als autogain feature. This enum's value is deprecated when
using STALS_SetControl or STALS_GetControl
STALS_OTP_USAGE_ENABLE Control to set if OTP information is used by driver. It is enabled by default.
Unless you are sure of the actions, do not change this value.
For example : STALS_SetControl(pHandle, STALS_OTP_USAGE_ENABLE, STALS_CONTROL_DISABLE).
STALS_WA_STATE Control to get/set workaround state:
• use STALS_SetControl() to enable/disable given workaround. Msb bit of ControlValue control if wa is
enabled or disabled. Others bits are the wa number.
UM2878
Enumeration type documentation
UM2878 - Rev 1 page 19/27

• use STALS_GetControl() to get wa status. pControlValue is then an in/out parameter. You call it with the wa
for which you want to know state. On exit you read msb bit to know wa status.
3.5.6 enum STALS_Mode_t
This enumeration is aimed at defining the different behavior modes of the STALS device.
Enumerator
STALS_MODE_ALS_SINGLE_SHOT Single shot mode. In this mode, the STALS records and accumulates the
light for 1 single period.
The STALS driver client is responsible for starting the next integration period, by calling the STALS_Start function
again
STALS_MODE_ALS_SYNCHRONOUS Synchronous mode. This mode, is a continuous measurement mode
meaning that this needs to be stopped by calling STALS_Stop. But a handshake is necessary to have
the registers updated with the values of the on going measurement. This handshake is performed by the
STALS_GetAlsValues function.
Two options are available for the handshake
• by I2C reading. In this case the AC data is available on the GPIO1 pin
• by interrupt acknowledgment. In this case the AC data is NOT available
STALS_MODE_FLICKER Flicker mode. This mode outputs PDM on the GPIO1 or GPIO2 pin.
3.5.7 enum STALS_FlickerOutputType_t
Enumerator
STALS_FLICKER_OUTPUT_ANALOG Analog. DEPRECATED, use
STALS_FLICKER_OUTPUT_ANALOG_CFG_1 instead.
STALS_FLICKER_OUTPUT_ANALOG_CFG_1 Analog. PDM is output to GPIO1 through pad internal resistance.
STALS_FLICKER_OUTPUT_DIGITAL_PDM PDM Digital. This modes needs an external clock to feed the
device through the corresponding pin.
STALS_FLICKER_OUTPUT_ANALOG_CFG_2 Analog. PDM is output to GPIO2.
STALS_FLICKER_OUTPUT_ZC_CFG_1 Zero crossing. Zero crossing is output to GPIO1.
UM2878
Enumeration type documentation
UM2878 - Rev 1 page 20/27