README

PHP Package for the BH1750 ambient light sensor.

Compatible I2C Interfaces

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

You can interface with a BH1750 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 BH1750 package from composer

composer require dept-of-scrapyard-robotics/bh1750

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\BH1750\BH1750\BH1750;

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

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;

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

$lux = $bh1750->getLuminance();

Basic Usage

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

use DeptOfScrapyardRobotics\Sensors\BH1750\BH1750\BH1750;
use DeptOfScrapyardRobotics\Sensors\BH1750\BH1750\Enums\BH1750I2CAddress;

$native_sensor = BH1750::connection('native')
    ->i2c(1, BH1750I2CAddress::ADDR_GROUNDED->value)
    ->create();
    
$lux = $native_sensor->lux;

Advanced Usage

Mode and resolution both influence how the BH1750 takes readings:

Mode controls whether the device is continuously sampling, in one-shot, or shutdown.
Resolution controls measurement precision and conversion behavior.

The BH1750 packs mode and resolution into a settings byte. You can directly read and write that settings value, or send control commands to the chip:

use DeptOfScrapyardRobotics\Sensors\BH1750\BH1750\Enums\BH1750WriteRegister;

$settings = $native_sensor->_settings;

$native_sensor->_settings = 0x10;
$native_sensor->_write = BH1750WriteRegister::RESET;

When using the sensor directly, you can also inspect the raw reading:

$raw = $native_sensor->_raw_reading;

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\BH1750\BH1750\BH1750;
use DeptOfScrapyardRobotics\Sensors\BH1750\BH1750\Enums\BH1750I2CAddress;
use RealityInterface\Sensors\Applied\AmbientLighting\AmbientLightSensor;

$usb_sensor = BH1750::connection('usb')
    ->i2c('ft232h', BH1750I2CAddress::ADDR_GROUNDED->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 BH1750 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;

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

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

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

// The output of getLuminance() will now be adjusted with your compensation factor
// computed from the calibration.
$adjusted_lux = $bh1750->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->lux
Reads the sensor and calculates lux from the measurement output.
$sensor->_settings
Reads the current settings byte used for mode and resolution.
$sensor->_raw_reading
Reads and returns the raw 16-bit light value from the device.

Writable Properties (Setters)

$sensor->_settings = 0x10;
Writes a settings byte directly to the device.
$sensor->_write = BH1750WriteRegister::RESET;
Sends a direct command register write (POWER_DOWN, POWER_ON, RESET).

dept-of-scrapyard-robotics / bh1750

Maintainers

Package info

Statistics

Security