1.. zephyr:code-sample:: bme280
2   :name: BME280 humidity and pressure sensor
3   :relevant-api: sensor_interface
4
5   Get temperature, pressure, and humidity data from a BME280 sensor.
6
7Overview
8********
9
10This sample shows how to use the Zephyr :ref:`sensor` API driver for the
11`Bosch BME280`_ environmental sensor.
12
13.. _Bosch BME280:
14   https://www.bosch-sensortec.com/products/environmental-sensors/humidity-sensors-bme280/
15
16The sample periodically reads temperature, pressure and humidity data from the
17first available BME280 device discovered in the system. The sample checks the
18sensor in polling mode (without interrupt trigger).
19
20Building and Running
21********************
22
23The sample can be configured to support BME280 sensors connected via either I2C
24or SPI. Configuration is done via :ref:`devicetree <dt-guide>`. The devicetree
25must have an enabled node with ``compatible = "bosch,bme280";``. See
26:dtcompatible:`bosch,bme280` for the devicetree binding and see below for
27examples and common configurations.
28
29If the sensor is not built into your board, start by wiring the sensor pins
30according to the connection diagram given in the `BME280 datasheet`_ at
31page 38.
32
33.. _BME280 datasheet:
34   https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bme280-ds002.pdf
35
36Boards with a built-in BME280
37=============================
38
39Your board may have a BME280 node configured in its devicetree by default. Make
40sure this node has ``status = "okay";``, then build and run with:
41
42.. zephyr-app-commands::
43   :zephyr-app: samples/sensor/bme280
44   :goals: build flash
45   :board: adafruit_feather_m0_basic_proto
46
47BME280 via Arduino SPI pins
48===========================
49
50If you wired the sensor to a SPI peripheral on an Arduino header, build and
51flash with:
52
53.. zephyr-app-commands::
54   :zephyr-app: samples/sensor/bme280
55   :goals: build flash
56   :gen-args: -DDTC_OVERLAY_FILE=arduino_spi.overlay
57
58The devicetree overlay :zephyr_file:`samples/sensor/bme280/arduino_spi.overlay`
59works on any board with a properly configured Arduino pin-compatible SPI
60peripheral.
61
62BME280 via Arduino I2C pins
63===========================
64
65If you wired the sensor to an I2C peripheral on an Arduino header, build and
66flash with:
67
68.. zephyr-app-commands::
69   :zephyr-app: samples/sensor/bme280
70   :goals: build flash
71   :gen-args: -DDTC_OVERLAY_FILE=arduino_i2c.overlay
72
73The devicetree overlay :zephyr_file:`samples/sensor/bme280/arduino_i2c.overlay`
74works on any board with a properly configured Arduino pin-compatible I2C
75peripheral.
76
77BME280 via Raspberry Pi Pico
78============================
79
80The default assignment of the built-in spi0 device on the :zephyr:board:`rpi_pico` is
81to GPIO16 through GPIO19.  With the sensor wired to those lines, build and
82flash with:
83
84.. zephyr-app-commands::
85   :zephyr-app: samples/sensor/bme280
86   :goals: build flash
87   :board: rpi_pico
88
89An alternative is to use PIO serving as an SPI device.  The devicetree
90overlay :zephyr_file:`samples/sensor/bme280/rpi_pico_spi_pio.overlay`
91demonstrates using PIO SPI with the sensor wired to arbitrary GPIO pins.
92Build and flash with:
93
94.. zephyr-app-commands::
95   :zephyr-app: samples/sensor/bme280
96   :goals: build flash
97   :board: rpi_pico
98   :gen-args: -DDTC_OVERLAY_FILE=rpi_pico_spi_pio.overlay
99
100Note that miso-gpios, mosi-gpios, and clk-gpios need to be assigned to the
101selected PIO device in pinctrl, while cs-gpios should not;  chip select is
102controlled by the SPI context and must operate as a conventional GPIO pin,
103not under control of PIO.
104
105Board-specific overlays
106=======================
107
108If your board's devicetree does not have a BME280 node already, you can create
109a board-specific devicetree overlay adding one in the :file:`boards` directory.
110See existing overlays for examples.
111
112The build system uses these overlays by default when targeting those boards, so
113no ``DTC_OVERLAY_FILE`` setting is needed when building and running.
114
115For example, to build for the :zephyr:board:`adafruit_feather_m0_basic_proto` using the
116:zephyr_file:`samples/sensor/bme280/boards/adafruit_feather_m0_basic_proto.overlay`
117overlay provided with this sample:
118
119.. zephyr-app-commands::
120   :zephyr-app: samples/sensor/bme280
121   :goals: build flash
122   :board: adafruit_feather_m0_basic_proto
123
124Sample Output
125=============
126
127The sample prints output to the serial console. BME280 device driver messages
128are also logged. Refer to your board's documentation for information on
129connecting to its serial console.
130
131Here is example output for the default application settings, assuming that only
132one BME280 sensor is connected to the standard Arduino I2C pins:
133
134.. code-block:: none
135
136   [00:00:00.379,760] <dbg> BME280.bme280_init: initializing "BME280_SPI" on bus "SPI_3"
137   [00:00:00.379,821] <dbg> BME280.bme280_init: bad chip id 0xff
138   [00:00:00.379,821] <dbg> BME280.bme280_init: initializing "BME280_I2C" on bus "I2C_0"
139   [00:00:00.380,340] <dbg> BME280.bme280_init: ID OK
140   [00:00:00.385,559] <dbg> BME280.bme280_init: BME280_I2C OK
141   *** Booting Zephyr OS build zephyr-v2.4.0-2940-gbb732ada394f  ***
142   Found device BME280_I2C, getting sensor data
143   temp: 20.260000; press: 99.789019; humidity: 46.458984
144   temp: 20.260000; press: 99.789480; humidity: 46.424804
145   temp: 20.250000; press: 99.789246; humidity: 46.423828
146
147Here is example output for the default application settings, assuming that two
148different BME280 sensors are connected to the standard Arduino I2C and SPI pins:
149
150.. code-block:: none
151
152   [00:00:00.377,777] <dbg> BME280.bme280_init: initializing "BME280_SPI" on bus "SPI_3"
153   [00:00:00.377,838] <dbg> BME280.bme280_init: ID OK
154   [00:00:00.379,608] <dbg> BME280.bme280_init: BME280_SPI OK
155   [00:00:00.379,638] <dbg> BME280.bme280_init: initializing "BME280_I2C" on bus "I2C_0"
156   [00:00:00.380,126] <dbg> BME280.bme280_init: ID OK
157   [00:00:00.385,345] <dbg> BME280.bme280_init: BME280_I2C OK
158   *** Booting Zephyr OS build zephyr-v2.4.0-2940-gbb732ada394f  ***
159   Found device BME280_I2C, getting sensor data
160   temp: 20.150000; press: 99.857675; humidity: 46.447265
161   temp: 20.150000; press: 99.859121; humidity: 46.458984
162   temp: 20.150000; press: 99.859234; humidity: 46.469726
163
164That the driver logs include a line saying ``BME280_I2C OK`` in both cases, but
165``BME280_SPI OK`` is missing when that device is not connected.
166