README

PHP Package for the VEML7000 ambient light sensor.

Compatible I2C Interfaces

The VEML7000 communicates with your device over I2C, the InterIntegrated Circuit Protocol.

You can interface with a VEML7000 with this package the following ways:

A Linux Single-Board Computer's exposed GPIO pins using the dedicated I2C SDA/SCL pins
An MPSSE-enabled USB-to-Serial device such as an FT232H generally using D0 and SCL and D1 for SDA connected to nearly any Linux or MacOS USB port.

Dependencies

This package makes use of modules within:

The ScrapyardIO Framework

This package also requires one of the following extensions in order to interface with I2C

In addition, an extension wrapper package is needed

For ext-posi

For ext-ftdi

Installing from Composer

Inside the root of your PHP Project, simply require the VEML7000 package from composer

composer require dept-of-scrapyard-robotics/veml7000

Framework Configuration

If you would like to use the ScrapyardIO Framework to bootstrap your sensor without wasting lines configuring your sensor right in the script you can add your desired configuration to scrapyard-io.php, such as in this example:

use DeptOfScrapyardRobotics\Sensors\VEML7000\VEML7000\VEML7000;

return [
    'boards' => [
        'veml7000-native' => [
            'class_name' => VEML7000::class,
            'connection' => [
                'driver' => 'native',
            ],
            'startup' => [
                'i2c' => [
                    'chip_device' => 1,
                    'slave_address' => 0x10,
                ],
            ],
        ],
        'veml7000-usb' => [
            'class_name' => VEML7000::class,
            'connection' => [
                'driver' => 'usb',
            ],
            'startup' => [
                'i2c' => [
                    'chip_device' => 'ft232h',
                    'slave_address' => 0x10,
                ],
            ],
        ]              
    ]   
];

The keys you choose to represent the integrated circuit's definition are up to you.

To bootstrap quickly using a ScrapyardIO AmbientLightSensor object you can start with the following:

use RealityInterface\Sensors\Applied\AmbientLighting\AmbientLightSensor;

$veml7000 = AmbientLightSensor::using('veml7000-native');

$lux = $veml7000->getLuminance();

Basic Usage

To use the sensor directly without the framework simply do the following:

use DeptOfScrapyardRobotics\Sensors\VEML7000\VEML7000\VEML7000;
use DeptOfScrapyardRobotics\Sensors\VEML7000\VEML7000\Enums\VEML7000I2CAddress;

$native_sensor = VEML7000::connection('native')
    ->i2c(1, VEML7000I2CAddress::DEFAULT->value)
    ->create();
    
$lux = $native_sensor->lux;

Advanced Usage

Gain and integration time both influence sensitivity and exposure:

Gain controls amplification of the light signal.
Integration time controls how long the sensor accumulates light before a reading.

The VEML7000 also provides power-saving controls and interrupt threshold controls through the same property-based API:

use DeptOfScrapyardRobotics\Sensors\VEML7000\VEML7000\Enums\VEML7000Gain;
use DeptOfScrapyardRobotics\Sensors\VEML7000\VEML7000\Enums\VEML7000IntegrationTime;
use DeptOfScrapyardRobotics\Sensors\VEML7000\VEML7000\Enums\VEML7000Mode;

$native_sensor->light_gain = VEML7000Gain::DOUBLE;
$native_sensor->light_integration_time = VEML7000IntegrationTime::MS400;
$native_sensor->light_psm = VEML7000Mode::PSM_1000;
$native_sensor->light_psm_en = true;

When using the sensor directly, you can also read active values:

$gain = $native_sensor->light_gain;
$integration_time = $native_sensor->light_integration_time;
$resolution = $native_sensor->resolution;
$autolux = $native_sensor->autolux;

Injected into the Framework

To inject into the framework, that is, bootstrap the device directly then pass it off to an AmbientLightSensor object simply do the following:

use DeptOfScrapyardRobotics\Sensors\VEML7000\VEML7000\VEML7000;
use DeptOfScrapyardRobotics\Sensors\VEML7000\VEML7000\Enums\VEML7000I2CAddress;
use RealityInterface\Sensors\Applied\AmbientLighting\AmbientLightSensor;

$usb_sensor = VEML7000::connection('usb')
    ->i2c('ft232h', VEML7000I2CAddress::DEFAULT->value)
    ->create();
    
$als = AmbientLightSensor::as($usb_sensor);

$lux = $als->getLuminance();

Calibration

To calibrate the sensor on the chip, you will need a reference sensor, that is shown to give out reliable Luminance readings.

Bootstrap or inject the sensor into an AmbientLightSensor object.
Make sure your sensor and the reference sensor are looking at the same target
use the getLuminance method on the VEML7000 at the same time as you pull a measurement from the reference.
Use the AmbientLightSensor's calibrate method

Refer to this simulated example

use RealityInterface\Sensors\Applied\AmbientLighting\AmbientLightSensor;

$veml7000 = AmbientLightSensor::using('veml7000-native');

// Simulated out-of-scope event measuring both sensors at the same time
$current_lux = $veml7000->getLuminance();
$ref = (int) "your-reference-lux";

// Add the values from your calibration session here. 
$veml7000 = $veml7000->calibrate($ref, $current_lux);

// The output of getLuminance() will now be adjusted with your compensation factor
// computed from the calibration.
$adjusted_lux = $veml7000->getLuminance();

Sensor API

The getters and setters in this API interface with the device directly (register reads/writes), so you can use simple property access while still working against the chip itself.

Readable Properties (Getters)

$sensor->light
Reads ALS output.
$sensor->white
Reads white channel output.
$sensor->light_interrupt
Gets whether ALS interrupt generation is enabled.
$sensor->light_integration_time (VEML7000IntegrationTime)
Gets ALS integration time.
$sensor->light_high_threshold
Gets ALS high threshold.
$sensor->light_low_threshold
Gets ALS low threshold.
$sensor->light_interrupt_high
Gets high-threshold interrupt status.
$sensor->light_interrupt_low
Gets low-threshold interrupt status.
$sensor->light_psm (VEML7000Mode)
Gets power saving mode.
$sensor->light_psm_en
Gets whether power saving mode is enabled.
$sensor->psm_value
Gets PSM value in milliseconds (500, 1000, 2000, 4000).
$sensor->light_gain (VEML7000Gain)
Gets ALS gain.
$sensor->light_shutdown
Gets shutdown state.
$sensor->resolution
Gets lux-per-count resolution based on current gain and integration time.
$sensor->lux
Reads lux using current configuration.
$sensor->autolux
Reads lux using automatic gain/integration tuning logic.

Writable Properties (Setters)

$sensor->light_interrupt = true;
Enables or disables ALS interrupt generation.
$sensor->light_integration_time = VEML7000IntegrationTime::MS100;
Sets ALS integration time.
$sensor->light_high_threshold = 12000;
Sets ALS high threshold.
$sensor->light_low_threshold = 300;
Sets ALS low threshold.
$sensor->light_psm = VEML7000Mode::PSM_1000;
Sets power saving mode.
$sensor->light_psm_en = true;
Enables or disables power saving mode.
$sensor->psm_value = 1000;
Sets power saving mode by millisecond value (500, 1000, 2000, 4000).
$sensor->light_gain = VEML7000Gain::NORMAL;
Sets ALS gain.
$sensor->light_shutdown = false;
Toggles ALS shutdown.

dept-of-scrapyard-robotics / veml7000

Maintainers

Package info

Statistics

Security