TCS3448 Arduino Driver

https://github.com/welcometotheroot/tcs3448
Admin
A standalone Arduino driver for the ams OSRAM TCS3448 multi-spectral sensor, providing calibrated...
Tokens:1,627
Snippets:18
Trust Score:2.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initialization

Source: https://github.com/welcometotheroot/tcs3448/blob/main/README.md

Methods to initialize the sensor with or without an interrupt pin.

```APIDOC
## begin(wire, intPin)
### Description
Initialise with interrupt pin (active-low, FALLING edge).

## begin(wire)
### Description
Initialise in polling mode — no interrupt pin required.
```

--------------------------------

### Perform flash metering

Source: https://github.com/welcometotheroot/tcs3448/blob/main/README.md

Switches to fast integration mode for capturing short-duration light events. Remember to resume normal integration after the capture.

```cpp
TCS3448::setFastIntegration();      // ~8ms integration, auto-gain disabled
// ... capture flash ...
TCS3448::resumeNormalIntegration(); // restore previous integration time + auto-gain
```

--------------------------------

### Initialize and poll sensor data

Source: https://github.com/welcometotheroot/tcs3448/blob/main/README.md

Standard polling implementation using the Wire library. Requires a successful begin() call before reading data.

```cpp
#include <Wire.h>
#include <tcs3448.h>

void setup() {
  Serial.begin(115200);
  Wire.begin();
  if (!TCS3448::begin(Wire)) {
    Serial.println("TCS3448 not found — check wiring.");
    while (true) {}
  }
}

void loop() {
  if (!TCS3448::isDataReady()) return;

  TCS3448Data d;
  if (TCS3448::read(d)) {
    Serial.print("F1 405nm: ");
    Serial.print(d.f1_405nm, 4);
    Serial.println(" mW/cm²");
  }
}
```

--------------------------------

### Diagnostics

Source: https://github.com/welcometotheroot/tcs3448/blob/main/README.md

Methods for device diagnostics.

```APIDOC
## getDeviceId(id)
### Description
Read the device ID register (0x81 for AS7343; TCS3448 may differ).
```

--------------------------------

### Configure interrupt-driven data ready

Source: https://github.com/welcometotheroot/tcs3448/blob/main/README.md

Configures the sensor to use an external interrupt pin. Requires an external pull-up resistor as the pin is active-low and open-drain.

```cpp
static constexpr uint8_t INT_PIN = 2;  // active-low, open-drain, FALLING edge

TCS3448::begin(Wire, INT_PIN);  // isDataReady() returns true once the ISR fires
```

--------------------------------

### Data Acquisition

Source: https://github.com/welcometotheroot/tcs3448/blob/main/README.md

Methods for checking data readiness and reading sensor values.

```APIDOC
## isDataReady()
### Description
Interrupt mode: true once the ISR fired. Polling mode: reads STATUS2.AVALID.

## setDataReady()
### Description
Called from the ISR — marks data as ready.

## clearDataReady()
### Description
Clears the data-ready flag without reading.

## read(data)
### Description
Read one complete cycle into TCS3448Data. Returns false on I2C error.

## checkSaturation()
### Description
Returns true if any channel saturated on the last read().

## readRawAll(counts[18])
### Description
Read all 18 raw DATA registers in auto-SMUX order.
```

--------------------------------

### Flash Metering

Source: https://github.com/welcometotheroot/tcs3448/blob/main/README.md

Methods for handling flash-based measurement scenarios.

```APIDOC
## setFastIntegration()
### Description
Switch to ~8ms integration and disable auto-gain.

## resumeNormalIntegration()
### Description
Restore prior integration time and re-enable auto-gain.

## restartMeasurement()
### Description
Toggle SP_EN to re-sync the integration window.
```

--------------------------------

### Integration Time

Source: https://github.com/welcometotheroot/tcs3448/blob/main/README.md

Methods to configure and retrieve integration timing parameters.

```APIDOC
## setIntegrationTime(atime, astep)
### Description
Set ATIME/ASTEP. t_int = (atime+1)×(astep+1)×2.78µs.

## getIntegrationTimeMs()
### Description
Current integration time in milliseconds.

## getAdcFullScale()
### Description
ADC full scale: min((ATIME+1)×(ASTEP+1), 65535).

## getAtime() / getAstep()
### Description
Current ATIME / ASTEP register values.
```

--------------------------------

### Hardware Flicker Detection

Source: https://github.com/welcometotheroot/tcs3448/blob/main/README.md

Methods to enable and read flicker detection data.

```APIDOC
## beginFlickerDetection()
### Description
Enable the on-chip flicker engine (FD channel / ADC5).

## stopFlickerDetection()
### Description
Disable the flicker engine.

## readFlickerStatus(d100, d120)
### Description
Read 100Hz / 120Hz flicker detection results.
```

--------------------------------

### Gain Control

Source: https://github.com/welcometotheroot/tcs3448/blob/main/README.md

Methods to manage sensor gain settings.

```APIDOC
## setGain(code)
### Description
Set the shared gain code (0x00–0x0C).

## getGainCode()
### Description
Return the currently commanded gain code.

## setAutoGainEnabled(enabled)
### Description
Enable/disable the per-cycle auto-gain loop.
```

--------------------------------

### Spectral Threshold Interrupt

Source: https://github.com/welcometotheroot/tcs3448/blob/main/README.md

Methods to configure spectral threshold interrupts.

```APIDOC
## setSpectralThreshold(channel, low, high)
### Description
16-bit threshold; channel 0–5 selects the driving ADC channel.

## setSpectralPersistence(n)
### Description
APERS: 0 = every cycle; 1–15 = N consecutive out-of-range cycles.
```

--------------------------------

### TCS3448Data struct definition

Source: https://github.com/welcometotheroot/tcs3448/blob/main/README.md

Represents the spectral data output from the TCS3448 sensor, including irradiance values, gain, saturation status, and raw ADC counts.

```cpp
struct TCS3448Data {
  float f1_405nm, f2_425nm, fz_450nm, f3_475nm, f4_515nm, f5_550nm;
  float fy_555nm, fxl_600nm, f6_640nm, f7_690nm, f8_745nm, nir_855nm;  // mW/cm²

  int gain;          // effective gain multiplier actually used (e.g. 16); 0 = 0.5×
  bool saturated;    // true if any channel saturated this cycle
  uint16_t rawCounts[12];  // raw 16-bit ADC counts, same channel order as above
};
```
Tokens:
Raw