API Reference

adafruit_as7343

CircuitPython driver for the ams OSRAM AS7343 14-channel spectral sensor.

  • Author(s): Tim Cocks

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_as7343.AS7343(i2c_bus: I2C, address: int = _AS7343_I2C_ADDRESS)

CircuitPython driver for the ams OSRAM AS7343 14-channel spectral sensor.

Parameters:

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

  • address (int) – I2C address. Defaults to 0x39.

Quickstart: Importing and using the device

import board
from adafruit_as7343 import AS7343

i2c = board.I2C()
sensor = AS7343(i2c)
readings = sensor.all_channels

Note

The AS7343 has two register banks selected by bit 4 of CFG0 (0xBF):

  • Bank 0 (default, REG_BANK=0): registers at 0x80 and above.

  • Bank 1 (REG_BANK=1): registers at 0x58–0x7F (ID, REVID, AUXID, GPIO, CFG10, CFG12).

CFG0 itself is always accessible in both bank modes and is used to switch between them via _set_bank().

property all_channels: List[int]

Trigger a measurement and return all channel readings.

Starts a single measurement, waits for AVALID (fires after all auto-SMUX cycles complete), then returns a list of 16-bit readings. The list length matches the current smux_mode: 6, 12, or 18 values.

Uses read_timeout as the maximum number of milliseconds to wait for data ready.

Returns:

List of channel counts in the order defined by Channel.

Raises:

TimeoutError – If data is not ready within read_timeout ms.

property astep: int

Integration step size (ASTEP), 0–65534.

Integration time (ms) = (atime + 1) × (astep + 1) × 2.78 µs. 65535 is reserved by hardware.

property auto_zero_frequency: int

Cycles between automatic zero-offset calibration runs (0–255).

  • 0 — auto-zero disabled (not recommended)

  • 1 — every measurement cycle

  • 255 — only before the very first measurement (default)

property aux_id: int

0 of AUXID register).

Type:

Auxiliary ID (bits 3

clear_status() → None

Clear all status flags in the STATUS register (write-to-clear).

property data_ready: bool

True when a complete set of channel data is available (AVALID).

property flicker_detection_enabled: bool

True when flicker detection is enabled.

property flicker_frequency: int

Detected mains flicker frequency.

Returns a FlickerFreq value:

  • FlickerFreq.NONE — no flicker detected

  • FlickerFreq.HZ100 — 100 Hz

  • FlickerFreq.HZ120 — 120 Hz

Bit layout of FD_STATUS: - bit 0: 100 Hz detected flag - bit 1: 120 Hz detected flag - bit 2: 100 Hz valid flag - bit 3: 120 Hz valid flag

property flicker_status: int

Raw value of the FD_STATUS register (0xE3).

property gain: int

Analogue gain for spectral measurements.

Must be a Gain value, e.g. Gain.X256. Default is Gain.X256 (256×).

property gpio_inverted: bool

True when GPIO polarity is inverted.

property gpio_output_mode: bool

True when the GPIO pin is configured as an output.

Set to False to switch to input mode.

property gpio_value: bool

GPIO pin state.

When in output mode, read back the driven value. When in input mode, read the external signal level.

property integration_time_ms: float

Calculated integration time in milliseconds (read-only).

(atime + 1) × (astep + 1) × 2.78 µs

property led_current_ma: int

LED drive current in milliamps.

Valid range: 4–258 mA (even values only; hardware steps of 2 mA). Formula: current_mA = 4 + (register_value × 2)

property part_id: int

Part ID register value (should be 0x81 for AS7343).

property persistence: int

Interrupt persistence filter (0–15).

Number of consecutive out-of-threshold measurements required before the interrupt flag is asserted. 0 = trigger every cycle.

read_channel(channel: int) → int

Read a single spectral channel by index.

Reads ASTATUS to latch data, then reads the specific channel register. Use Channel constants to specify the channel.

Parameters:

channel (int) – Channel index (a Channel constant, 0–17).

Returns:

16-bit channel count.

property revision_id: int

0 of REVID register).

Type:

Revision ID (bits 2

property smux_mode: int

Auto-SMUX channel cycling mode.

Must be a SmuxMode value:

  • SmuxMode.CH6 — 6 channels

  • SmuxMode.CH12 — 12 channels

  • SmuxMode.CH18 — 18 channels (default)

property status: int

Raw value of the main STATUS register (0x93).

Warning

Writing this register clears the status flags. Use clear_status() to explicitly clear all flags.

property system_interrupt_enabled: bool

True when the system interrupt is enabled.

property threshold_channel: int

ADC channel (0–5) used for spectral interrupt threshold comparison.

Note

Hardware testing shows this register has no observed effect — threshold comparison always targets CH0 regardless of this setting. Read/write works correctly but the value is not acted upon by the hardware.

class adafruit_as7343.CV

Constant-value helper used as an enum base class.

Subclasses define integer class attributes; is_valid() and get_name() provide validation and reverse-lookup.

classmethod get_name(value: int) → str

Return the attribute name whose value equals value.

classmethod is_valid(value: int) → bool

Return True if value is a defined member of this class.

class adafruit_as7343.Channel

Spectral channel index within the 18-channel auto-SMUX data array.

The index corresponds to the order in which data appears in the output buffer returned by AS7343.all_channels in SmuxMode.CH18 mode.

Setting

Index

Centre wavelength

Channel.FZ

0

450 nm (blue)

Channel.FY

1

555 nm (yellow-green)

Channel.FXL

2

600 nm (orange)

Channel.NIR

3

855 nm (near-IR)

Channel.VIS_TL_0

4

Clear, top-left, cycle 1

Channel.VIS_BR_0

5

Clear, btm-right, cycle 1

Channel.F2

6

425 nm (violet-blue)

Channel.F3

7

475 nm (blue-cyan)

Channel.F4

8

515 nm (green)

Channel.F6

9

640 nm (red)

Channel.VIS_TL_1

10

Clear, top-left, cycle 2

Channel.VIS_BR_1

11

Clear, btm-right, cycle 2

Channel.F1

12

405 nm (violet)

Channel.F7

13

690 nm (deep red)

Channel.F8

14

745 nm (near-IR edge)

Channel.F5

15

550 nm (green-yellow)

Channel.VIS_TL_2

16

Clear, top-left, cycle 3

Channel.VIS_BR_2

17

Clear, btm-right, cycle 3
class adafruit_as7343.FlickerFreq

Flicker detection result values returned by AS7343.flicker_frequency.

Setting

Meaning

FlickerFreq.NONE

No flicker detected

FlickerFreq.HZ100

100 Hz mains flicker

FlickerFreq.HZ120

120 Hz mains flicker
class adafruit_as7343.Gain

Spectral measurement analogue gain settings for CFG1 register bits 4:0.

Higher gain increases sensitivity for low-light conditions but may saturate in bright environments.

Setting

Gain

Gain.X0_5

0.5×

Gain.X1

1×

Gain.X2

2×

Gain.X4

4×

Gain.X8

8×

Gain.X16

16×

Gain.X32

32×

Gain.X64

64×

Gain.X128

128×

Gain.X256

256× ★

Gain.X512

512×

Gain.X1024

1024×

Gain.X2048

2048×

★ Default after AS7343.__init__().

class adafruit_as7343.SmuxMode

Auto-SMUX channel-cycling mode settings for CFG20 register bits 6:5.

The auto-SMUX hardware automatically cycles through multiple SMUX configurations in a single measurement trigger, accumulating data for more spectral channels per access of AS7343.all_channels.

Setting

Channels measured

SmuxMode.CH6

6 channels (1 SMUX cycle)

SmuxMode.CH12

12 channels (2 SMUX cycles)

SmuxMode.CH18

18 channels (3 SMUX cycles) ★

★ Default after AS7343.__init__().