Crate ph_veml7700_als

Expand description

§ph-veml7700-als

An async, allocation-free no_std VEML7700 ambient-light driver over a caller-provided embedded-hal-async I²C bus.

[!WARNING] Lifecycle: Incubating. Distribution: Published on crates.io as the 0.1.0-incubating.1 prerelease. Verification: Driver-versus-model agreement is bounded to the traces in the verification record. No physical-hardware or calibrated-optical evidence has been recorded.

The driver keeps board policy with the application and avoids hidden cached device state. It distinguishes observational snapshots from a controlled one-shot capture, preserves partial-operation context in errors, and exposes nominal integer scaling without presenting it as calibrated system lux.

§Usage

The application supplies its platform’s async I²C bus and delay provider:

use embedded_hal_async::{delay::DelayNs, i2c::I2c};
use ph_veml7700_als::{MeasurementConfig, Veml7700};

async fn sample<I2C, D>(i2c: I2C, delay: &mut D)
where
    I2C: I2c,
    D: DelayNs,
{
    let mut sensor = Veml7700::new(i2c);
    sensor.probe().await.expect("VEML7700 probe failed");

    let measurement = sensor
        .measure_once(delay, MeasurementConfig::maximum_range_start())
        .await
        .expect("measurement failed");

    let _counts = measurement.als.counts();
}

The generated API documentation owns exact operation behavior, errors, timing, and cancellation semantics. Data-sheet and hardware provenance remain in the shared evidence registry and are cited from the API by stable S-nn rather than copied here.

Important current limits: nominal micro-lux is not product calibration; maximum code alone does not prove optical overrange; and threshold flag qualification has no timing guarantee. The independent model returns an unsupported result where shared evidence cannot justify an oracle instead of manufacturing coverage.

§Features

Default features are empty. defmt adds defmt::Format implementations to public values and errors; firmware supplies its own logger and panic symbols.

§Installing

cargo add ph-veml7700-als@0.1.0-incubating.1

Name the prerelease explicitly. Cargo will not select 0.1.0-incubating.1 from a plain 0.1 requirement, so a dependency without a prerelease in its own version requirement resolves to nothing.

Availability on crates.io is a distribution fact and nothing more. It does not imply complete model conformance, physical observation, hardware qualification, or promotion out of Incubating; the status disclosure above still governs.

§Requirements

Rust 1.92.0, Edition 2024
embedded-hal-async 1.0

Model-conformance and package-verification details live in the repository’s verification record. A successful build or model trace does not establish board wiring, bus integrity, optical performance, or silicon qualification.

Licensed under MIT.

Structs§

AlsCounts: Raw ambient-light-channel counts (S-32).
ConfigurationSnapshot: Decoded configuration-register snapshot.
DeviceId: Decoded VEML7700 ID register.
DeviceSnapshot: Read-only diagnostic snapshot that does not claim fresh optical data.
MeasurementCapture: Measurement captured after a controlled configuration and requested wait.
MeasurementConfig: Gain and integration-time pair defining one measurement domain.
MeasurementTiming: Timing requested by a complete one-shot measurement.
MicroLux: Nominal illuminance represented in micro-lux.
NominalScale: Nominal scale for one gain/integration-time pair.
PowerSavingConfig: Desired power-saving configuration.
PowerSavingSnapshot: Decoded power-saving register.
SnapshotMeasurement: Diagnostic register snapshot with no freshness guarantee.
ThresholdMonitorConfig: Complete monitored domain for the VEML7700’s polled threshold feature.
ThresholdMonitorError: Threshold-monitor programming failure.
ThresholdStatus: Raw decoded threshold-flag observation (S-38).
Thresholds: Raw ALS low/high thresholds.
Veml7700: Async VEML7700 driver owning one I²C resource.
WhiteCounts: Raw white-channel counts (S-33).

Enums§

BusContext: Exact register-level bus context.
ConfigDecodeError: Failure decoding a configuration register.
ConfigurationError: Configuration failure independent of the transport.
Error: Ordinary driver failure preserving the concrete I²C error.
Gain: Driver gain-codec reaction to S-14.
IntegrationTime: Driver integration-codec reaction to S-15.
MeasureOnceError: Complete one-shot-measurement failure.
MeasureStage: Stage of a complete one-shot measurement.
MeasurementPairCoherence: Coherence qualification for an ALS/white pair.
Operation: High-level operation associated with a bus failure.
Persistence: Threshold persistence protect number (ALS_PERS).
PowerSavingDecodeError: Failure decoding the power-saving register.
PowerSavingMode: Driver power-saving codec reaction to S-20.
PowerState: Driver power-state codec reaction to S-17.
ProbeError: Probe-specific failure.
ThresholdMonitorStage: Stage of threshold-monitor programming.
ThresholdMonitorState: Driver monitor-enable codec reaction to S-17.
ThresholdStatusDecodeError: Failure decoding the threshold-status register.

Constants§

I2C_ADDRESS: Driver address selection (S-05).
INTEGRATION_TOLERANCE_PERCENT: Integration-time tolerance magnitude used by this driver’s policy (S-24, S-55).
MEASUREMENT_MARGIN_US: Additional software margin beyond wake-up and maximum integration time.
WAKE_UP_DELAY_US: Minimum wake-up delay before measurement timing begins (S-23).