<!--
SPDX-FileCopyrightText: 2026 Ben Youngblood

SPDX-License-Identifier: Apache-2.0
-->

# STK31862

[![Hex version](https://img.shields.io/hexpm/v/stk31862.svg "Hex version")](https://hex.pm/packages/stk31862)
[![API docs](https://img.shields.io/hexpm/v/stk31862.svg?label=docs "API docs")](https://hexdocs.pm/stk31862)

<!-- MODULEDOC -->

Use the [Sensortek STK31862 ambient light sensor](https://www.sensortek.com.tw) in
Elixir.

The STK31862 is an integrated ambient-light-to-digital converter with an I²C
interface. It pairs a human-eye-response photodiode (the "ALS" channel) with an
unfiltered clear photodiode (the "C" channel) and reports both as 16-bit values.
This library talks to it over [Circuits.I2C](https://hex.pm/packages/circuits_i2c)
and converts the ALS reading to lux.

The sensor's fixed 7-bit I²C address is `0x45`.

## Usage

```elixir
iex> {:ok, als} = STK31862.start_link(bus_name: "i2c-1")
{:ok, #PID<0.2190.0>}

iex> STK31862.get_config(als)
{:ok, %{gain: :gain_1x, integration_time: :it_100ms, persistence: :persistence_1, c_gain: :gain_1x}}

iex> STK31862.set_config(als, gain: :gain_16x, integration_time: :it_200ms)
{:ok, %{gain: :gain_16x, integration_time: :it_200ms, persistence: :persistence_1, c_gain: :gain_1x}}

iex> STK31862.measure(als)
{:ok,
 %STK31862.Measurement{
   light_lux: 412.5,
   als_raw: 47142,
   c_raw: 11203,
   saturated?: false,
   timestamp_ms: -576460731
 }}
```

### Configuration values

* `:gain` and `:c_gain` — `:gain_1x`, `:gain_4x`, `:gain_16x`, `:gain_64x`, `:gain_128x`
* `:integration_time` — `:it_3_125ms`, `:it_6_25ms`, `:it_12_5ms`, `:it_25ms`,
  `:it_50ms`, `:it_100ms`, `:it_200ms`, `:it_400ms`
* `:persistence` — `:persistence_1`, `:persistence_2`, `:persistence_4`, `:persistence_8`

Invalid values are rejected with an error such as `{:error, {:invalid_gain, :nope}}`.

Larger gain and longer integration time give finer resolution (more lux per
count) but saturate sooner in bright light. Pick a combination that keeps
`als_raw` comfortably below full scale (`65535`) for your expected light level.
When `saturated?` is `true` the reading is invalid — lower the gain or shorten
the integration time.

### Lux accuracy note

The datasheet only specifies lux-per-count at the special 128× gain, and the
ALS-channel table in datasheet rev 0.9.4 is internally inconsistent for
integration times of 25 ms and longer (each entry is half of the value implied
by the geometric pattern that the C channel follows). This library reproduces
the datasheet values verbatim. For accurate absolute lux you should calibrate
against a reference light source for your chosen gain/integration-time settings.

<!-- MODULEDOC -->

For details, see the [API reference](https://hexdocs.pm/stk31862/api-reference.html).

## Installation

The package can be installed by adding `stk31862` to your list of dependencies
in `mix.exs`:

```elixir
def deps do
  [
    {:stk31862, "~> 0.1.0"}
  ]
end
```

## AI Usage Disclosure

The initial implementation of this library was authored largely by Claude Opus 4.8.