From 65b833473a033e958006fd8b093e439e0210e007 Mon Sep 17 00:00:00 2001 From: arcsur Date: Tue, 23 Jan 2018 16:55:18 +0800 Subject: [PATCH] BME680 sensor component documentation (#4432) * Added documentation for BME680 sensor platform * Removed yr sensor from configuration.yaml example * Implemented pull request review comments. --- source/_components/sensor.bme680.markdown | 222 ++++++++++++++++++++++ 1 file changed, 222 insertions(+) create mode 100644 source/_components/sensor.bme680.markdown diff --git a/source/_components/sensor.bme680.markdown b/source/_components/sensor.bme680.markdown new file mode 100644 index 00000000000..e6978a3f0f9 --- /dev/null +++ b/source/_components/sensor.bme680.markdown @@ -0,0 +1,222 @@ +--- +layout: page +title: "BME680 Sensor" +description: "Instructions on how to integrate a BME680 sensor into Home Assistant." +date: 2018-01-16 00:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: raspberry-pi.png +ha_category: Sensor +ha_release: 0.62 +ha_iot_class: "Local Push" +--- + + +The `bme680` sensor platform allows you to read temperature, humidity, pressure and gas resistance values of a [Bosch BME680 Environmental sensor](https://cdn-shop.adafruit.com/product-files/3660/BME680.pdf) connected via an [I2C](https://en.wikipedia.org/wiki/I²C) bus (SDA, SCL pins). It allows you to use all the operation modes of the sensor described in its datasheet. In addition, it includes a basic air quality calculation that uses gas resistance and humidity measurements to calculate a percentage based air quality measurement. + +Tested devices: + +- [Raspberry Pi](https://www.raspberrypi.org/) + +To use your BME680 sensor in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +sensor: + - platform: bme680 +``` + +{% configuration %} +name: + description: The name of the sensor + required: false + default: BME680 Sensor + type: string +i2c_bus: + description: I2C bus that the sensor is connected to. + required: false + default: 1 + type: int +i2c_address: + description: I2C address of the sensor. It is 0x76 or 0x77. + required: false + default: 0x77 + type: int +monitored_conditions: + description: Conditions to monitor. + required: false + default: + - temperature + - humidity + - pressure + - airquality + type: list + keys: + temperature: + description: Monitor temperature. + humidity: + description: Monitor relative humidity. + pressure: + description: Monitor pressure. + gas: + description: Monitor gas resistance values on the VOC sensor. + airquality: + description: Monitor air quality using the values of humidity and gas resistance and calculate a percentage based air quality measurement. +oversampling_temperature: + description: Oversampling multiplier as described in the sensor datasheet. Can be 0 (no sampling), 1, 2, 4, 8, or 16. + required: false + default: 8 + type: int +oversampling_pressure: + description: Oversampling multiplier as described in the sensor datasheet. Can be 0 (no sampling), 1, 2, 4, 8, or 16. + required: false + default: 2 + type: int +oversampling_humidity: + description: Oversampling multiplier as described in the sensor datasheet. Can be 0 (no sampling), 1, 2, 4, 8, or 16. + required: false + default: 4 + type: int +filter_size: + description: IIR filter size as described in the sensor datasheet. Can be 0 (off), 1, 3, 7, 15, 31, 63 or 127. + required: false + default: 3 + type: int +gas_heater_temperature: + description: The temperature to heat the hotplate to for gas resistance measurements as described in the sensor datasheet. Can be between 200-400°C. + required: false + default: 320 + type: int +gas_heater_duration: + description: The duration to heat the hotplate in milliseconds for gas resistance measurements as described in the sensor datasheet. Can be between 1-4032 ms. In reality, you will likely need between 80-100ms to reach a stable temperature. Using a duration greater than 1000ms is inadvisable as it will essentially result in the heater being continually on due to the 1-second update interval. + required: false + default: 150 + type: int +aq_burn_in_time: + description: The duration to perform gas resistance measurements to establish a stable baseline measurements for Air Quality calculations in seconds. The burn in time is only performed when the sensor component is first initialized. + required: false + default: 300 + type: int +aq_humidity_baseline: + description: The baseline *ideal* relative humidity value for the air quality calculations. + required: false + default: 40 + type: int +aq_humidity_bias: + description: The bias for humidity to the gas resistance measurement in the air quality calculations expressed as a percentage of the total calculation e.g. 25% hudidtity to 75% gas. + required: false + default: 25 + type: int +{% endconfiguration %} + +## {% linkable_title Full Examples %} + +If you want to specify the working mode of the digital sensor or need to change the default I2C address (which is 0x77), add more details to the `configuration.yaml` file: + +```yaml +# Example of customized configuration.yaml entry +sensor: + - platform: bme680 + name: BME680 Sensor + i2c_bus: 1 + i2c_address: 0x77 + monitored_conditions: + - temperature + - humidity + - pressure + - gas + - airquality + oversampling_temperature: 8 + oversampling_humidity: 2 + oversampling_pressure: 4 + filter_size: 3 + gas_heater_temperature: 320 + gas_heater_duration: 150 + aq_burn_in_time: 300 + aq_humidity_baseline: 40 + aq_humidity_bias: 25 +``` + +## {% linkable_title Customizing the sensor data %} + +Give the values friendly names and icons, add the following to your `customize:` section. + +```yaml +# Example configuration.yaml entry +customize: + sensor.bme680_sensor_temperature: + icon: mdi:thermometer + friendly_name: Temperature + sensor.bme680_sensor_humidity: + icon: mdi:water + friendly_name: Humidity + sensor.bme680_sensor_pressure: + icon: mdi:gauge + friendly_name: Pressure + sensor.bme680_sensor_air_quality: + icon: mdi:blur + friendly_name: Air Quality +``` + +To create a group, add the following to your `group` section. + +```yaml +# Example configuration.yaml entry +group: + climate: + name: Climate + entities: + - sensor.bme680_sensor_temperature + - sensor.bme680_sensor_humidity + - sensor.bme680_sensor_pressure + - sensor.bme680_sensor_air_quality +``` + +## {% linkable_title Directions for installing SMBus support on Raspberry Pi %} + +Enable I2C interface with the Raspberry Pi configuration utility: + +```bash +# pi user environment: Enable I2C interface +$ sudo raspi-config +``` + +Select `Interfacing options->I2C` choose `` and hit `Enter`, then go to `Finish` and you'll be prompted to reboot. + +Install dependencies to use the `smbus-cffi` module and add your _homeassistant_ user to 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 +``` + +### {% linkable_title 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: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- +30: -- -- -- -- -- -- -- -- -- -- -- -- 3c -- -- -- +40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- +50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- +60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- +70: -- -- -- -- -- -- -- 76 +``` + +So you can see the sensor address that you are looking for is **0x76** (there is another I2C device on that Raspberry Pi).