--- title: Bosch BME280 Environmental Sensor description: Instructions on how to integrate a BME280 sensor into Home Assistant. ha_category: - DIY ha_release: 0.48 ha_iot_class: Local Push ha_domain: bme280 ha_platforms: - sensor --- The Bosch BME280 integration allows you to read temperature, humidity and pressure values of a [Bosch BME280 Environmental sensor](https://cdn-shop.adafruit.com/datasheets/BST-BME280_DS001-10.pdf) connected via [I2c](https://en.wikipedia.org/wiki/I²C) bus (SDA, SCL pins) or connected via SPI. It allows you to use all the operation modes of the sensor described in its datasheet. ## Configuration To use your BME280 sensor in your installation, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry bme280: - name: Ambient ``` {% configuration %} name: description: The name of the sensor. required: false default: BME280 Sensor type: string i2c_address: description: I2c address of the sensor. It is 0x76 or 0x77. required: false default: 0x76 type: string i2c_bus: description: I2c bus where the sensor is. required: false default: 1, for Raspberry Pi 2 and 3. type: integer operation_mode: description: Power mode for the sensor. Use 2 for forced mode or 3 for normal mode. required: false default: 3 type: integer time_standby: description: Standby time in ms for normal mode of operation as described in the sensor datasheet. required: false default: 5 type: integer 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: 1 type: integer 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: 1 type: integer 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: 1 type: integer filter_mode: description: IIR filter coefficient as described in the sensor datasheet. required: false default: 0 type: integer delta_temperature: description: Absolute delta for temperature correction. required: false default: 0 type: float monitored_conditions: description: Conditions to monitor. Available conditions are *temperature*, *humidity* and *pressure*. required: false default: All three conditions type: list spi_bus: description: sensor SPI bus number. required: false type: integer spi_dev: description: sensor SPI device number. required: false type: integer {% endconfiguration %} ## Full Examples If you want to specify the working mode of the digital sensor or need to change the default I2c address (which is 0x76), add more details to the `configuration.yaml` file: ```yaml # Example of customized configuration.yaml entry bme280: - name: Ambient i2c_address: 0x77 operation_mode: 2 # forced mode time_standby: 5 oversampling_temperature: 4 oversampling_pressure: 4 oversampling_humidity: 4 delta_temperature: -0.5 monitored_conditions: - temperature - humidity - pressure scan_interval: 40 ``` This sensor is somehow famous for generating relatively high temperature measurements compared to other sensors (it looks like self-heating does not feel good for some encapsulations). If you experience this problem, you can define an absolute delta of temperature correction using a negative number. ## 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.ambient_temperature: icon: mdi:thermometer friendly_name: "Temperature" sensor.ambient_humidity: icon: mdi:weather-rainy friendly_name: "Humidity" sensor.ambient_pressure: icon: mdi:gauge friendly_name: "Pressure" ``` To create a group, add the following to your `groups` section. ```yaml # Example configuration.yaml entry group: ambient_sensor: name: BME280 Environment sensor entities: - sensor.ambient_temperature - sensor.ambient_humidity - sensor.ambient_pressure ``` ## Directions for installing smbus support on Raspberry Pi
This section only applies to devices running the Home Assistant Core installation method.
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 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 **0x77** (there are more i2c sensors in that Raspberry Pi). ## SPI Support Alternatively, this integration can also be used with SPI. ### Config example ```yaml # Example of customized configuration.yaml entry bme280: - name: Stary_Oskol spi_bus: 0 spi_dev: 1 time_standby: 5 oversampling_temperature: 4 oversampling_pressure: 4 oversampling_humidity: 4 monitored_conditions: - temperature - humidity - pressure scan_interval: 40 ``` ## Directions for installing SPI support on Raspberry Pi
This section only applies to devices running the Home Assistant Core installation method.
Enable SPI interface with the Raspberry Pi: ```bash sudo groupadd spi # Add homeassistant user to the spi group sudo usermod -a -G spi user # Add udev rules sudo echo 'SUBSYSTEM=="spidev", GROUP="spi", MODE="0660"' > /etc/udev/rules.d/77-spi.rules # apply changes without logout newgrp spi sudo udevadm control --reload-rules && udevadm trigger ``` ```bash sudo echo 'dtparam=spi=on' >> /boot/firmware/config.txt sudo echo 'dtoverlay=spi1-3cs' >> /boot/firmware/config.txt sudo reboot ``` ### Check the spi devices ```bash ls /dev/spidev* /dev/spidev0.0 /dev/spidev0.1 /dev/spidev1.0 /dev/spidev1.1 /dev/spidev1.2 ``` ## Connect sensors ### SPI0 (available on J8/P1 headers on all Raspberry Pi versions) |SPI Function|Header Pin|Broadcom Pin Name|Broadcom Pin Function| |------------|----------|-----------------|---------------------| |MOSI |19 |GPIO10 |SPI0_MOSI |MISO |21 |GPIO09 |SPI0_MISO |SCLK |23 |GPIO11 |SPI0_SCLK |CE0 |24 |GPIO08 |SPI0_CE0_N |CE1 |26 |GPIO07 |SPI0_CE1_N ### SPI1 (available only on 40-pin J8 header) |SPI Function|Header Pin|Broadcom Pin Name|Broadcom Pin Function| |------------|----------|-----------------|---------------------| |MOSI |38 |GPIO20 |SPI1_MOSI |MISO |35 |GPIO19 |SPI1_MISO |SCLK |40 |GPIO21 |SPI1_SCLK |CE0 |12 |GPIO18 |SPI1_CE0_N |CE1 |11 |GPIO17 |SPI1_CE1_N |CE2 |36 |GPIO16 |SPI1_CE2_N