Sense.ACP

TMD3725 ambient-light, RGB colour & proximity sensor.

Platform-agnostic driver for the ams/OSRAM TMD3725 ALS/Color/Proximity module on Sense.ACP. Provides RGBC ambient-light sensing (four 16-bit data converters — Clear/Red/Green/Blue) plus an integrated IR-LED proximity engine with an 8-bit result.

Examples

Quick start

  #include "core.h"
  #include "core_tiles.h"
  #include "tile_sense_acp.h"

  tile_t acp;
  tile_sense_acp_init(core_tiles_pal(&core_i2c1), 0, &acp, NULL);

  uint16_t clear = tile_sense_acp_get_clear(&acp);
  uint8_t  prox  = tile_sense_acp_get_proximity(&acp);

API reference

Initialization

tile_sense_acp_find

uint8_t tile_sense_acp_find(tiles_pal_t *hal, uint8_t instance)

Check if a Sense.ACP is present on the bus.

hal: Platform HAL handle.
instance: Address selector — only 0 is valid (fixed address 0x39).

Returns 1 if the device ACKs and its ID register reads 0xE4, else 0.

tile_sense_acp_init

void tile_sense_acp_init(tiles_pal_t *hal, uint8_t instance, tile_t *tile, const sense_acp_cfg_t *cfg)

Probes the device, verifies the ID register, programs ALS gain + integration time and proximity gain + LED drive, then powers on the requested engines (PON is asserted together with AEN so the chip's auto-zero runs before the first ALS measurement). Sets tile state to READY on success, ERROR otherwise.

hal: Platform HAL handle.
instance: Address selector — only 0 is valid (fixed address 0x39).
tile: Tile handle to initialise.
cfg: Configuration (NULL for defaults).

Lifecycle

tile_sense_acp_sleep

Studio

void tile_sense_acp_sleep(tile_t *tile)

Power down the sensor (clears PON/AEN/PEN).

tile: Initialised tile handle.

tile_sense_acp_wake

Studio

void tile_sense_acp_wake(tile_t *tile)

Resume from sleep, restoring the engines enabled at init.

tile: Sleeping tile handle.

Runtime

tile_sense_acp_get_clear

Studio

uint16_t tile_sense_acp_get_clear(tile_t *tile)

Read the Clear (unfiltered) channel — overall ambient light.

tile: Initialised tile handle.

Returns 16-bit Clear channel count.

tile_sense_acp_get_red

Studio

uint16_t tile_sense_acp_get_red(tile_t *tile)

Read the Red channel count.

tile: Initialised tile handle.

Returns 16-bit Red channel count.

tile_sense_acp_get_green

Studio

uint16_t tile_sense_acp_get_green(tile_t *tile)

Read the Green channel count.

tile: Initialised tile handle.

Returns 16-bit Green channel count.

tile_sense_acp_get_blue

Studio

uint16_t tile_sense_acp_get_blue(tile_t *tile)

Read the Blue channel count.

tile: Initialised tile handle.

Returns 16-bit Blue channel count.

tile_sense_acp_get_proximity

Studio

uint8_t tile_sense_acp_get_proximity(tile_t *tile)

Read the proximity result (larger = closer object).

tile: Initialised tile handle.

Returns 8-bit proximity count.

tile_sense_acp_get_status

Studio

uint8_t tile_sense_acp_get_status(tile_t *tile)

Use the TMD3725_ST_* masks — e.g. ASAT (ALS saturation), PSAT (proximity saturation), AINT/PINT (threshold interrupts pending).

tile: Initialised tile handle.

Returns Raw STATUS byte.

Config

tile_sense_acp_set_als_gain

Studio

void tile_sense_acp_set_als_gain(tile_t *tile, sense_acp_als_gain_t gain)

Set the ALS/Color gain.

tile: Initialised tile handle.
gain: ALS gain selection (sense_acp_als_gain_t).

tile_sense_acp_set_integration_time

Studio

void tile_sense_acp_set_integration_time(tile_t *tile, uint8_t atime)

Integration time is (atime + 1) x 2.78 ms; the maximum ALS count scales with it (1024 per 2.78 ms step, saturating at 65535). For example 0x00 = 2.8 ms, 0x2F = ~133 ms (default), 0xFF = ~719 ms.

tile: Initialised tile handle.
atime: Raw ATIME register value (0-255).

tile_sense_acp_set_prox_gain

Studio

void tile_sense_acp_set_prox_gain(tile_t *tile, sense_acp_prox_gain_t gain)

Set the proximity IR-sensor gain.

tile: Initialised tile handle.
gain: Proximity gain selection (sense_acp_prox_gain_t).

tile_sense_acp_set_prox_drive_ma

Studio

void tile_sense_acp_set_prox_drive_ma(tile_t *tile, uint8_t ma)

The LED current is programmed in ~6 mA steps: i_LED = 6 x (PLDRIVE + 1), so the request is clamped to 6-192 mA and rounded down to the nearest step. Actual current is factory-trimmed to normalise IR intensity, so treat the value as approximate.

tile: Initialised tile handle.
ma: Desired LED drive current in milliamps (6-192).

gapThreshold interrupts (ALS / proximity INT pin)Driver-deferred AND definition-gated. The TMD3725 asserts its INT pin (open-drain, active-low) when the Clear channel or the proximity result crosses the AILT/AIHT or PILT/PIHT thresholds past the PERS persistence count. The tile routes INT to pad 7, but Sense-ACP-b.json does not declare that pad, so Studio cannot wire it as an event source. Polled reads (get_clear / get_proximity) cover the same ground for v1 — a DSL comparison yields "near/far" without the INT path. Closing this needs the tile definition updated to declare pad 7 = INT, then a follow-up pass to expose the threshold/PERS/INTENAB registers and a tile event.

Driver gaps · 2

Chip capabilities this driver doesn’t expose yet.

advancedIlluminance (lux) and correlated colour temperatureOut of scope for an integer driver. Converting RGBC counts to lux or CCT requires the device-specific calibration coefficients from the ams application note plus floating-point maths. This driver exposes the raw per-channel counts (clear/red/green/blue); compute lux/CCT on the host where floats and calibration data are available.

nicheWait state, proximity offset calibration, IR-channel muxDeferred, not gated. The wait feature (WEN/WTIME/WLONG idle timing), the proximity offset-cancellation engine (POFFSET + CALIB autozero), and the IR_TO_GREEN mux (route the IR photodiode into the green data converter) are left at sane power-on defaults and not surfaced. A later pass can expose them if a use-case needs them.

Enums

sense_acp_als_gain_t

ALS/Color gain (CFG1 AGAIN[1:0]).

SENSE_ACP_ALS_GAIN_1X: 1x.
SENSE_ACP_ALS_GAIN_4X: 4x.
SENSE_ACP_ALS_GAIN_16X: 16x (default).
SENSE_ACP_ALS_GAIN_64X: 64x.

sense_acp_prox_gain_t

Proximity IR-sensor gain (PCFG1 PGAIN[7:6]).

SENSE_ACP_PROX_GAIN_1X: 1x.
SENSE_ACP_PROX_GAIN_2X: 2x.
SENSE_ACP_PROX_GAIN_4X: 4x (default).
SENSE_ACP_PROX_GAIN_8X: 8x.

Constants

TILE_SENSE_ACP_VERSION_MAJOR	1
TILE_SENSE_ACP_VERSION_MINOR	0
TILE_SENSE_ACP_VERSION_PATCH	0
TMD3725_I2C_ADDR	0x39	Fixed 7-bit I2C address (only value).
TMD3725_ID_VALUE	0xE4	ID register (0x92) reset/expected value.