add BH1750 light sensor platform doc (#2821)

* add BH1750 light sensor platform doc

* don't repeat errors!

* review fixes

* add `multiplier` parameter
This commit is contained in:
Eugenio Panadero 2017-06-22 09:05:58 +02:00 committed by Fabian Affolter
parent 3881bff74c
commit 2094220a42

View File

@ -0,0 +1,95 @@
---
layout: page
title: "BH1750 Light sensor"
description: "Instructions how to integrate a BH1750 light sensor in a Raspberry PI into Home Assistant."
date: 2017-06-10 00:00
sidebar: true
comments: false
sharing: true
footer: true
logo: raspberry-pi.png
ha_category: Sensor
ha_release: 0.47
ha_iot_class: "Local Push"
---
The `bh1750` sensor platform allows you to read the ambient light level in lux from a [BH1750FVI sensor](http://cpre.kmutnb.ac.th/esl/learning/bh1750-light-sensor/bh1750fvi-e_datasheet.pdf) connected via [I2c](https://en.wikipedia.org/wiki/I²C) bus (SDA, SCL pins) to your [Raspberry Pi](https://www.raspberrypi.org/). It allows you to use all the resolution modes of the sensor described in its datasheet.
To use your BH1750 sensor in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
sensor:
- platform: BH1750
```
Or, if you want to specify the resolution mode of the digital sensor or need to change the default I2c address (which is 0x23), add more details to the yaml config.
The sensor can work with resolutions of 0.5 lx (high res mode 1), 1 lx (high res mode 2) or 4 lx (low res mode), and make measurements continuously or one time each call. To set any of these operation modes, select one of these combinations: `continuous_low_res_mode`, `continuous_high_res_mode_2`, `continuous_high_res_mode_1`, `one_time_high_res_mode_1`, `one_time_high_res_mode_2`, `one_time_low_res_mode`.
```yaml
# Example of customized configuration.yaml entry
sensor:
- platform: bh1750
name: Ambient light
i2c_address: 0x5C
operation_mode: one_time_high_res_mode_1
measurement_delay_ms: 200
scan_interval: 25
```
Configuration variables:
- **name** (*Optional*): The name of the sensor
- **i2c_address** (*Optional*): I2c address of the sensor. It is 0x23 or 0x5C.
- **i2c_bus** (*Optional*): I2c bus where the sensor is. Defaults to 1, for Raspberry Pi 2 and 3.
- **operation_mode** (*Optional*): Working mode for the sensor. Defaults to `continuous_high_res_mode_1` for continuous measurement and 1 lx resolution.
- **measurement_delay_ms** (*Optional*): Delay time in ms for waiting the sensor to get the measure. Defaults to 120 ms.
- **multiplier** (*Optional*): Correction coefficient to multiply the measured light level. Value between 0.1 and 10. Default is 1.
### Directions for installing smbus support on Raspberry Pi:
Enable I2c interface with the Raspberry Pi config utility:
```bash
# pi user environment: Enable i2c interface
sudo raspi-config
```
Select `Interfacing options->I2C` choose `<Yes>` and hit `Enter`, then go to `Finish` and you'll be prompted to reboot.
Install dependencies for use the `smbus-cffi` module and enable your _homeassistant_ user to join the _i2c_ group:
```bash
# pi user environment: Install i2c dependencies and utilities
sudo apt-get install build-essential libi2c-dev i2c-tools python-dev libffi-dev
# pi user environment: Add homeassistant user to the i2c group
sudo addgroup homeassistant i2c
# pi user environment: Reboot Raspberry Pi to apply changes
sudo reboot
```
###### Check the i2c address of the sensor
After installing `i2c-tools`, a new utility is available to scan the addresses of the connected sensors:
```bash
/usr/sbin/i2cdetect -y 1
```
It will output a table like this:
```text
0 1 2 3 4 5 6 7 8 9 a b c d e f
00: -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: -- -- -- 23 -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: 40 -- -- -- -- -- UU -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: -- -- -- -- -- -- -- 77
```
So you can see the sensor address what you are looking for is **0x23** (there are more i2c sensors in that Raspberry Pi).