From 503deec3c41c346dbfc2f439a702f877bd6fade9 Mon Sep 17 00:00:00 2001 From: Molham Date: Sat, 23 May 2026 10:24:45 +0200 Subject: [PATCH] docs: add i2c environmental sensor hat tutorial --- bun.lock | 1 + .../pi-hats/i2c-environmental-sensor-hat.mdx | 256 ++++++++++++++++++ 2 files changed, 257 insertions(+) create mode 100644 docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx diff --git a/bun.lock b/bun.lock index 74d488f7..0a4bd604 100644 --- a/bun.lock +++ b/bun.lock @@ -1,5 +1,6 @@ { "lockfileVersion": 1, + "configVersion": 0, "workspaces": { "": { "name": "docs", diff --git a/docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx b/docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx new file mode 100644 index 00000000..ee930655 --- /dev/null +++ b/docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx @@ -0,0 +1,256 @@ +--- +title: Building an I2C Environmental Sensor HAT +description: >- + Build a Raspberry Pi HAT with a BME280 environmental sensor, I2C pull-ups, + optional OLED display, and an external expansion header. +--- + +import CircuitPreview from "@site/src/components/CircuitPreview" +import TscircuitIframe from "@site/src/components/TscircuitIframe" + +## Overview + +This tutorial shows how to build a compact Raspberry Pi HAT for measuring temperature, humidity, and barometric pressure with a BME280 sensor. The board also includes I2C pull-up resistors, local decoupling, an optional SSD1306-style OLED header, and an external I2C header for chaining another module. + + ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +) +`} /> + +## Circuit Requirements + +The HAT needs to: + +- Use the Raspberry Pi I2C bus: `GPIO_2` for SDA and `GPIO_3` for SCL +- Power the BME280 from the 3.3V rail +- Add 4.7k pull-up resistors on SDA and SCL +- Add 100nF and 1µF decoupling capacitors close to the sensor +- Tie `CSB` high so the BME280 runs in I2C mode +- Tie `SDO` low for the default I2C address `0x76` +- Expose the same I2C bus on optional OLED and external expansion headers + +## Bill of Materials + +| Ref | Part | Suggested value | Notes | +| --- | --- | --- | --- | +| U1 | BME280 | Bosch BME280 | Temperature, humidity, pressure sensor | +| R1, R2 | Pull-up resistors | 4.7k, 0402 | SDA and SCL pull-ups to 3.3V | +| C1 | Decoupling capacitor | 100nF, 0402 | Place close to BME280 power pins | +| C2 | Bulk capacitor | 1µF, 0603 | Smooths local 3.3V rail noise | +| J1 | OLED header | 1x4, 2.54mm | Optional SSD1306-style display | +| J2 | External I2C header | 1x4, 2.54mm | Expansion connector | + +## Step 1: Add the HAT Board and BME280 + +Start with the Raspberry Pi HAT board and place the BME280 near an edge or vent slot so it can sense ambient air rather than heat from the Pi. + + ( + + + +) +`} /> + +## Step 2: Wire the I2C Bus + +Connect Raspberry Pi `GPIO_2` to BME280 `SDI` for SDA, and `GPIO_3` to `SCK` for SCL. Add one pull-up resistor from each line to 3.3V. + +```tsx + + + + + + +``` + +## Step 3: Set the BME280 Address + +For I2C mode, tie `CSB` high. Tie `SDO` low to use address `0x76`; tie it high instead if another device already uses that address. + +```tsx + + +``` + +## Step 4: Add Optional OLED and Expansion Headers + +The OLED and external header share SDA, SCL, 3.3V, and ground. Use only one set of pull-ups on the whole bus; do not duplicate pull-ups on every module unless the total resistance stays safe for the bus speed. + +```tsx + + + +``` + +## PCB Layout Guidance + +- Keep SDA and SCL short and route them as a pair where possible. +- Place `R1` and `R2` near the Pi header or near the first sensor on the bus. +- Put `C1` within a few millimeters of the BME280 power pins. +- Keep the BME280 away from regulators, power resistors, LEDs, and the Raspberry Pi CPU area. +- Add small air slots or edge placement if the enclosure may trap heat. +- Label the OLED and external headers with `GND`, `VCC`, `SCL`, and `SDA` on silkscreen. + +## Raspberry Pi Setup + +Enable I2C on Raspberry Pi OS: + +```bash +sudo raspi-config +# Interface Options -> I2C -> Enable +sudo reboot +``` + +Check that the sensor appears on the bus: + +```bash +sudo apt-get install -y i2c-tools +sudo i2cdetect -y 1 +``` + +You should see the BME280 at `0x76` or `0x77`. + +## Python Example + +Install the CircuitPython BME280 driver: + +```bash +python3 -m pip install adafruit-circuitpython-bme280 +``` + +Read temperature, humidity, and pressure: + +```python +import time +import board +import busio +from adafruit_bme280 import basic as adafruit_bme280 + +i2c = busio.I2C(board.SCL, board.SDA) +bme280 = adafruit_bme280.Adafruit_BME280_I2C(i2c, address=0x76) +bme280.sea_level_pressure = 1013.25 + +while True: + print(f"Temperature: {bme280.temperature:.1f} °C") + print(f"Humidity: {bme280.relative_humidity:.1f} %") + print(f"Pressure: {bme280.pressure:.1f} hPa") + print(f"Altitude: {bme280.altitude:.1f} m") + time.sleep(2) +``` + +## Troubleshooting + +| Problem | Check | +| --- | --- | +| No device in `i2cdetect` | Confirm I2C is enabled, SDA/SCL are not swapped, and pull-ups are present | +| Device appears at `0x77` | `SDO` is high; update software address or tie `SDO` low | +| Readings drift high | Move the BME280 away from heat sources and improve airflow | +| OLED works but BME280 does not | Confirm both devices have unique I2C addresses | +| Bus unreliable with long wires | Lower I2C speed or use stronger pull-ups such as 2.2k | + +## Next Steps + +- Add a small OLED page showing live readings. +- Log readings to InfluxDB, SQLite, or a CSV file. +- Add a STEMMA/Qwiic connector for plug-in I2C sensors. +- Compare readings with a reference thermometer and apply calibration offsets in software.