STK31862 (stk31862 v0.1.0)

Use the Sensortek STK31862 ambient light sensor 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 and converts the ALS reading to lux.

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

Usage

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.

Summary

Types

config()

Sensor configuration map, as returned by get_config/1.

gain()

ALS/C gain setting. :gain_128x is the special DX128 gain.

integration_time()

ALS integration time setting. The atom names spell the time in milliseconds, e.g. :it_3_125ms is 3.125 ms and :it_100ms is 100 ms. Longer times give finer resolution.

option()

STK31862 GenServer start options.

persistence()

Out-of-window interrupt persistence: how many consecutive out-of-window conversions must occur before the interrupt is asserted.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear_interrupt(server \\ __MODULE__)

Clears a pending ALS out-of-window interrupt flag.

get_config(server \\ __MODULE__)

Returns the current configuration map: :gain, :integration_time, :persistence and :c_gain.

get_thresholds(server \\ __MODULE__)

Returns the ALS out-of-window low and high thresholds.

measure(server \\ __MODULE__)

Returns the latest measurement.

read_product_id(server \\ __MODULE__)

Reads the product ID register.

reset(server \\ __MODULE__)

Software-resets the sensor and re-applies the current configuration.

set_config(server \\ __MODULE__, changes)

Updates the configuration.

set_data_ready_interrupt(server \\ __MODULE__, enabled?)

Enables or disables the ALS data-ready interrupt.

set_thresholds(server \\ __MODULE__, low, high)

Sets the ALS out-of-window low and high thresholds (raw counts).

set_window_interrupt(server \\ __MODULE__, enabled?)

Enables or disables the ALS out-of-window interrupt.

start_link(options \\ [])

Starts a GenServer that manages a STK31862 sensor.

Types

config()

@type config() :: %{
  gain: gain(),
  integration_time: integration_time(),
  persistence: persistence(),
  c_gain: gain()
}

Sensor configuration map, as returned by get_config/1.

set_config/2 accepts the same fields (as a map or keyword list); any field left out keeps its current value.

:gain - ALS gain (see gain/0)
:integration_time - ALS integration time (see integration_time/0)
:persistence - out-of-window interrupt persistence (see persistence/0)
:c_gain - C-channel gain (see gain/0)

gain()

@type gain() :: :gain_1x | :gain_4x | :gain_16x | :gain_64x | :gain_128x

ALS/C gain setting. :gain_128x is the special DX128 gain.

integration_time()

@type integration_time() ::
  :it_3_125ms
  | :it_6_25ms
  | :it_12_5ms
  | :it_25ms
  | :it_50ms
  | :it_100ms
  | :it_200ms
  | :it_400ms

ALS integration time setting. The atom names spell the time in milliseconds, e.g. :it_3_125ms is 3.125 ms and :it_100ms is 100 ms. Longer times give finer resolution.

option()

@type option() ::
  {:name, atom()}
  | {:bus_name, String.t()}
  | {:bus_address, 69}
  | {:retries, non_neg_integer()}
  | {:poll_interval_ms, pos_integer()}
  | {:gain, gain()}
  | {:integration_time, integration_time()}
  | {:persistence, persistence()}

STK31862 GenServer start options.

:name - a name for the GenServer
:bus_name - which I2C bus to use (e.g., "i2c-1", the default)
:bus_address - the I2C address (the STK31862 is fixed at 0x45)
:retries - the number of I2C retries before failing (defaults to none)
:poll_interval_ms - how often to poll the sensor (defaults to 1000)
:gain - ALS gain (defaults to :gain_1x)
:integration_time - ALS integration time (defaults to :it_100ms)
:persistence - out-of-window interrupt persistence (defaults to :persistence_1)

persistence()

@type persistence() ::
  :persistence_1 | :persistence_2 | :persistence_4 | :persistence_8

Out-of-window interrupt persistence: how many consecutive out-of-window conversions must occur before the interrupt is asserted.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear_interrupt(server \\ MODULE)

@spec clear_interrupt(GenServer.server()) :: :ok | {:error, any()}

Clears a pending ALS out-of-window interrupt flag.

get_config(server \\ MODULE)

@spec get_config(GenServer.server()) :: {:ok, config()} | {:error, any()}

Returns the current configuration map: :gain, :integration_time, :persistence and :c_gain.

get_thresholds(server \\ MODULE)

@spec get_thresholds(GenServer.server()) ::
  {:ok, %{low: 0..65535, high: 0..65535}} | {:error, any()}

Returns the ALS out-of-window low and high thresholds.

measure(server \\ MODULE)

@spec measure(GenServer.server()) :: {:ok, STK31862.Measurement.t()} | {:error, any()}

Returns the latest measurement.

{:error, :no_measurement} is returned until the first reading completes.

read_product_id(server \\ MODULE)

@spec read_product_id(GenServer.server()) :: {:ok, 0..255} | {:error, any()}

Reads the product ID register.

reset(server \\ MODULE)

@spec reset(GenServer.server()) :: :ok | {:error, any()}

Software-resets the sensor and re-applies the current configuration.

set_config(server \\ MODULE, changes)

@spec set_config(GenServer.server(), keyword() | map()) ::
  {:ok, config()} | {:error, any()}

Updates the configuration.

changes may set :gain, :integration_time, :persistence and :c_gain.

iex> STK31862.set_config(server, gain: :gain_16x, integration_time: :it_200ms)

set_data_ready_interrupt(server \\ MODULE, enabled?)

@spec set_data_ready_interrupt(GenServer.server(), boolean()) :: :ok | {:error, any()}

Enables or disables the ALS data-ready interrupt.

set_thresholds(server \\ MODULE, low, high)

@spec set_thresholds(GenServer.server(), 0..65535, 0..65535) :: :ok | {:error, any()}

Sets the ALS out-of-window low and high thresholds (raw counts).

set_window_interrupt(server \\ MODULE, enabled?)

@spec set_window_interrupt(GenServer.server(), boolean()) :: :ok | {:error, any()}

Enables or disables the ALS out-of-window interrupt.

start_link(options \\ [])

@spec start_link([option()]) :: GenServer.on_start()

Starts a GenServer that manages a STK31862 sensor.