Skip to content

Latest commit

 

History

History
95 lines (52 loc) · 5.57 KB

bh1750.md

File metadata and controls

95 lines (52 loc) · 5.57 KB
Raw

BH1750 Driver

The Rohm Semiconductor BH1750 is a compact illumination sensor, capable of reading lux values with 16 bit resolution. The BH1750 can be integrated directly into your circuit designs, but is more typlically supplied via a development board for integration with your projects.

The BH1750 supports the 2-pin I2C interface, and the BH1750 AtomVM driver makes use of this interface to communicate with the sensor to yeild lux measurements. Users may select any supported I2C GPIO pins on your device to integrate with the sensor.

The BH1750 Driver supports two modes of operation:

  • One-time measurements -- call the driver to take a measurement, and process the result. The sensor will go into sleep mode after taking a reading. Ideal for power-sensitive applications.
  • Continuous measurements -- Initialize the driver to supply a continuous stream of measurements at a specified interval. This mode of operation is only recommended for applications that have a reliable power source.

The BH1750 Driver also supports 3 levels of resolution:

  • (High) 1 lux resolution in the range {1..65535}
  • (High2) .5 lux resolution in the range TBD
  • (Low) 4 lux resolution in the range TBD

Finally, the sensitivity of the BH1750 can be adjusted, which can be especially useful for low-light scenarios.

Currently, the BH1750 driver is only tested on the ESP32 platform.

Programming Manual

The BH1750 Driver is designed to provide a simple, easy to use interface for taking luminosity measurements for your AtomVM application. This section describes the BH1750 driver API, as encapsulated in the bh1750 Erlang module.

Lifecycle

An instance of the BH1750 driver is created using an instance of the I2CBus service. Start by initializing an I2Cbus using the i2c_bus module, specifying the sda and scl pins in a map structure:

{ok, I2CBus} = i2c_bus:start(#{
    sda => 21,
    scl => 22
}),

You can then use the bh1750:start/1 and bh1750:start/2 functions to start an instance of the BH1750 driver:

{ok BH} = bh1750:start(I2CBus),
...

The return value includes a reference to the driver, which is used in subsequent operations.

The arity-2 version of the start function allows additional parameters to be specified, in a manner described in more detail below.

Note. The I2CBus instance may be used to initialize other I2C devices that are multiplexed on the same I2C bus.

To delete an instance of the driver, use the bh1750:stop/1 function.

Note. This function is not well tested and its use may result in a memory leak.

One-Time vs Continuous Mode

The BH1750 driver can operate in one-time or continuos mode. In one-time mode, the application must poll the driver for a reading, whereas in continuous mode, the driver will periodically send the owning process a reading as a message.

The advantage to one-time mode is that the BH1750 sensor will enter sleep mode once a reading is taken, so it is ideal for low-power applications. In continuous mode, the device will continue to draw power.

The default operational mode (without explicit configuration) is one-time.

To configure continuous mode, add the tuple {mode, continuous} to the Options properties list to the bh1750:start/2 function. By default, in continuous mode, the driver will send a reading to the process that started the driver every 5 seconds.

To specify a different process to which to send messages, add the tuple {owner, Pid} to the Options parameter to the bh1750:start/2 function, where Pid is the erlang process id of the owning process.

To specify a different update interval for continuous mode, add the tuple {update_interval_ms, UpdateIntervalMs} to the Options parameter to the bh1750:start/2 function, where UpdateIntervalMs is the desired update interval (in milliseconds).

Note. In continuous mode, the update interval will include an additional 16-120 millisecond delay, depending on the specified resolution and sensitivity, described in more detail below.

Specifying a value outside of the above range will result in a bardarg exception.

Readings

Readings are obtained in one-time mode via a call to the bh1750:take_reading/0 function. In continuous mode, readings are sent periodically to the process that "owns" the driver instance, in a manner described above.

Readings are represented as a tuple containing an integral and fractional part, where the fractional part is a tuple containing a numerator and denominator. The denominator is always a power of 10, e.g.,

 {153, {33, 100}}

Resolution

Resolution of BH1750 readings can be controlled by adding the tuple {resolution, R} to the Options parameter to the bh1750:start/3 function, where R can take the following atom values:

  • low -- 4 lux resolution
  • high (default) -- 1 lux resolution
  • high2 -- 0.5 lux resolution

Specifying a value outside of the above range will result in a bardarg exception.

Sensitivity

The sensitivity of the BH1750 can be controlled by adding the tuple {mtreg, S} to the Options parameter to the bh1750:start/3 function, where S can take be an integer value between 31 and 254 (inclusive). The default value for this parameter is 69.

Specifying a value outside of the above range will result in a bardarg exception.

BH1750 Example

The BH1750 driver includes an example program illustrating use of the BH1750 driver. See the README for information about how to build, flash, and run this exmaple program.