API Reference

adafruit_opt4048

CircuitPython driver library for the Adafruit OPT4048 breakout board, a high-speed, high-precision tristimulus XYZ color sensor.

  • Author(s): Tim C

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_opt4048.CV

Constant value class helper for enums.

classmethod get_name(value) → str

Get the name for a given value

classmethod is_valid(value: int) → bool

Validate that a given value is a member

class adafruit_opt4048.ConversionTime

Available conversion time settings for the OPT4048 sensor.

These control the device conversion time per channel as described in datasheet page 29.

Setting

Time

ConversionTime.TIME_600US

600 microseconds

ConversionTime.TIME_1MS

1 millisecond

ConversionTime.TIME_1_8MS

1.8 milliseconds

ConversionTime.TIME_3_4MS

3.4 milliseconds

ConversionTime.TIME_6_5MS

6.5 milliseconds

ConversionTime.TIME_12_7MS

12.7 milliseconds

ConversionTime.TIME_25MS

25 milliseconds

ConversionTime.TIME_50MS

50 milliseconds

ConversionTime.TIME_100MS

100 milliseconds

ConversionTime.TIME_200MS

200 milliseconds

ConversionTime.TIME_400MS

400 milliseconds

ConversionTime.TIME_800MS

800 milliseconds
class adafruit_opt4048.FaultCount

Available fault count settings for the OPT4048 sensor.

Controls how many consecutive fault events are needed to trigger an interrupt.

Setting

Count

FaultCount.COUNT_1

1 fault count (default)

FaultCount.COUNT_2

2 consecutive faults

FaultCount.COUNT_4

4 consecutive faults

FaultCount.COUNT_8

8 consecutive faults
class adafruit_opt4048.IntConfig

Interrupt configuration settings for the OPT4048 sensor.

Controls the interrupt mechanism after end of conversion.

Setting

Configuration

IntConfig.SMBUS_ALERT

SMBUS Alert

IntConfig.DATA_READY_NEXT

INT Pin data ready for next chan

IntConfig.DATA_READY_ALL

INT Pin data ready for all chans
class adafruit_opt4048.Mode

Available operating mode settings for the OPT4048 sensor.

Controls the device mode of operation as described in datasheet page 29.

Setting

Mode

Mode.POWERDOWN

Power-down mode

Mode.AUTO_ONESHOT

Auto-range one-shot

Mode.ONESHOT

One-shot mode

Mode.CONTINUOUS

Continuous mode
class adafruit_opt4048.OPT4048(i2c_bus, address=_OPT4048_DEFAULT_ADDR)

Library for the OPT4048 Tristimulus XYZ Color Sensor

Parameters:

  • i2c_bus (I2C) – The I2C bus the device is connected to

  • address (int) – The I2C device address. Defaults to 0x44

Quickstart: Importing and using the device

Here is an example of using the OPT4048. First you will need to import the libraries to use the sensor

import board
from adafruit_opt4048 import OPT4048

Once this is done you can define your board.I2C object and define your sensor object

i2c = board.I2C()  # uses board.SCL and board.SDA
sensor = OPT4048(i2c)

Now you have access to the color data

x, y, z, w = sensor.color_data
property all_channels

Read all four channels, verify CRC, and return raw ADC code values.

Reads registers for channels 0-3 in one burst, checks the CRC bits for each, and computes the raw ADC code values.

Returns:

Tuple of 4 raw channel values (X, Y, Z, W) if successful

Return type:

Tuple[int, int, int, int]

Raises:

RuntimeError – If CRC check fails for any channel

calculate_color_temperature(cie_x, cie_y)

Calculate the correlated color temperature (CCT) in Kelvin.

Uses McCamy’s approximation formula to calculate CCT from CIE 1931 x,y coordinates. This is accurate for color temperatures between 2000K and 30000K.

Formula: n = (x - 0.3320) / (0.1858 - y) CCT = 437 * n^3 + 3601 * n^2 + 6861 * n + 5517

Parameters:

  • cie_x (float) – CIE x chromaticity coordinate

  • cie_y (float) – CIE y chromaticity coordinate

Returns:

The calculated color temperature in Kelvin

Return type:

float

property cie

Calculate CIE chromaticity (x, y) and LUX.

CIE values are calculated from the x, y, z value from the xyz() function. LUX value estimated using the OPT4048 raw values together transformation matrix from the datasheet.

Returns:

Tuple (cie_x, cie_y, lux)

Return type:

Tuple[float, float, float]

property conversion_time

Get the current conversion time setting for the OPT4048 sensor.

Returns the current conversion time setting from the ConversionTime enum. This controls the device conversion time per channel.

See the ConversionTime class for valid values: - ConversionTime.TIME_600US: 600 microseconds - ConversionTime.TIME_1MS: 1 millisecond - ConversionTime.TIME_1_8MS: 1.8 milliseconds - ConversionTime.TIME_3_4MS: 3.4 milliseconds - ConversionTime.TIME_6_5MS: 6.5 milliseconds - ConversionTime.TIME_12_7MS: 12.7 milliseconds - ConversionTime.TIME_25MS: 25 milliseconds - ConversionTime.TIME_50MS: 50 milliseconds - ConversionTime.TIME_100MS: 100 milliseconds - ConversionTime.TIME_200MS: 200 milliseconds - ConversionTime.TIME_400MS: 400 milliseconds - ConversionTime.TIME_800MS: 800 milliseconds

property fault_count

Get the current fault count setting.

Returns the current fault count setting from the FaultCount enum. This controls how many consecutive measurements must be above/below thresholds before an interrupt is triggered.

See the FaultCount class for valid values: - FaultCount.COUNT_1: 1 fault count (default) - FaultCount.COUNT_2: 2 consecutive faults - FaultCount.COUNT_4: 4 consecutive faults - FaultCount.COUNT_8: 8 consecutive faults

property flags

Get the current status flags.

Reads the status register (0x0C) to determine the current state of various flags. Reading this register also clears latched interrupt flags.

Returns:

8-bit value where: - bit 0 (0x01): FLAG_L - Flag low (measurement below threshold) - bit 1 (0x02): FLAG_H - Flag high (measurement above threshold) - bit 2 (0x04): CONVERSION_READY_FLAG - Conversion complete - bit 3 (0x08): OVERLOAD_FLAG - Overflow condition

Return type:

int

init()

Initialize the sensor and verify the device ID

property interrupt_config

Get the current interrupt configuration.

Returns the current interrupt configuration mode. See IntConfig class for valid values.

property interrupt_direction

Get the current interrupt direction setting.

Returns True if interrupts are generated when measurement > high threshold, False if interrupts are generated when measurement < low threshold.

property interrupt_latch

Get the current interrupt latch setting.

Returns True if interrupts are latched (interrupt flag remains active until register is read), False if interrupts are transparent (interrupt flag is updated with each measurement).

property interrupt_polarity

Get the current interrupt pin polarity setting.

Returns True if interrupts are active-high (1 = interrupt active), False if interrupts are active-low (0 = interrupt active).

property mode

Get the current operating mode setting for the OPT4048 sensor.

Returns the current operating mode setting from the Mode enum. This controls the device operating mode.

See the Mode class for valid values: - Mode.POWERDOWN: Power-down mode - Mode.AUTO_ONESHOT: Auto-range one-shot mode - Mode.ONESHOT: One-shot mode - Mode.CONTINUOUS: Continuous mode

property normalized_xyz

Normalize XYZ values so their sum becomes 1.0.

This removes brightness influence and keeps the values in a valid range.

Returns:

Tuple (Xn, Yn, Zn)

Return type:

Tuple[float, float, float]

property quick_wake

Get the current state of the Quick Wake feature.

Quick Wake controls whether the sensor powers down completely in one-shot mode. When enabled, the sensor doesn’t power down all circuits in one-shot mode, allowing faster wake-up from standby with a penalty in power consumption compared to full standby mode.

Returns True if Quick Wake is enabled, False if disabled.

property range

Get the current range setting for light measurements.

Returns the current range setting from the Range enum. This controls the full-scale light level range of the device.

See the Range class for valid values: - Range.RANGE_2K: 2.2 klux - Range.RANGE_4K: 4.5 klux - Range.RANGE_9K: 9 klux - Range.RANGE_18K: 18 klux - Range.RANGE_36K: 36 klux - Range.RANGE_72K: 72 klux - Range.RANGE_144K: 144 klux - Range.AUTO: Auto-range

property rgb

convert xyz value to rgb and return illuminance (lux) value.

Based on the XYZ normalized value from normalizedtosum(). reference: https://www.oceanopticsbook.info/view/photometry-and-visibility/from-xyz-to-rgb

Returns:

Tuple (r, g, b, lux)

Return type:

Tuple[int, int, int, float]

property threshold_channel

Get the channel currently used for threshold comparison.

Returns the channel number (0-3) currently used for threshold comparison: - 0 = Channel 0 (X) - 1 = Channel 1 (Y) - 2 = Channel 2 (Z) - 3 = Channel 3 (W)

property threshold_high

Get the current high threshold value.

Returns the current high threshold value as a 32-bit integer. This value determines when a high threshold interrupt is generated when interrupt_direction is True.

property threshold_low

Get the current low threshold value.

Returns the current low threshold value as a 32-bit integer. This value determines when a low threshold interrupt is generated when interrupt_direction is False.

property xyz

Calculate CIE XYZ tristimulus values from raw sensor channels.

Uses the 3 channel of OPT4048 outputs and applies the transformation matrix from the datasheet.

Returns:

Tuple of (X, Y, Z) tristimulus values

Return type:

Tuple[float, float, float]

class adafruit_opt4048.Range

Available range settings for the OPT4048 sensor.

Full-scale light level ranges as described in datasheet page 29.

Setting

Range Value

Range.RANGE_2K

2.2 klux

Range.RANGE_4K

4.5 klux

Range.RANGE_9K

9 klux

Range.RANGE_18K

18 klux

Range.RANGE_36K

36 klux

Range.RANGE_72K

72 klux

Range.RANGE_144K

144 klux

Range.AUTO

Auto-range