From b9d10e454b2395b4767e6c33903b4a58a2f7ab71 Mon Sep 17 00:00:00 2001 From: Molham Date: Sat, 23 May 2026 10:52:12 +0200 Subject: [PATCH 1/2] docs: add i2c environmental sensor hat tutorial --- .../pi-hats/i2c-environmental-sensor-hat.mdx | 249 ++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx 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..0e850f8e --- /dev/null +++ b/docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx @@ -0,0 +1,249 @@ +--- +title: Building an I2C Environmental Sensor HAT +description: >- + Build a Raspberry Pi HAT with a BME280 temperature, humidity, and pressure + sensor, I2C pull-ups, an optional OLED header, and an external expansion header. +--- + +import CircuitPreview from "@site/src/components/CircuitPreview" +import TscircuitIframe from "@site/src/components/TscircuitIframe" + +## Overview + +This tutorial walks through a compact Raspberry Pi HAT for logging temperature, relative humidity, and barometric pressure with a BME280 over I2C. The design includes the support parts that make an I2C sensor board reliable in the field: local decoupling, SDA/SCL pull-up resistors, an optional OLED display header, and a keyed external header for mounting the sensor away from the Pi. + + ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +) +`} /> + +## What you will build + +The HAT exposes one BME280 sensor on the Pi's primary I2C bus and provides a second 4-pin I2C header for either a small SSD1306 OLED or a remote sensor pod. The Pi supplies 3.3 V power, so all parts on the bus must be 3.3 V compatible. + +### Bill of materials + +| Ref | Part | Notes | +| --- | --- | --- | +| U1 | BME280 environmental sensor | Temperature, humidity, and pressure sensor in I2C mode | +| R1, R2 | 4.7 kΩ resistors | Pull SDA and SCL up to 3.3 V | +| C1 | 100 nF capacitor | High-frequency local decoupling near U1 | +| C2 | 1 µF capacitor | Bulk decoupling for the sensor/header area | +| J1 | 1x4 2.54 mm header | Optional OLED display: VCC, GND, SCL, SDA | +| J2 | 1x4 2.54 mm header | External I2C sensor/probe connection | + +## Step 1: Start with the Raspberry Pi HAT outline + +Use `RaspberryPiHatBoard` so the circuit has the Pi 40-pin header and the standard HAT board outline. + +```tsx +import { RaspberryPiHatBoard } from "@tscircuit/common" + +export default () => ( + + {/* Sensor circuit goes here */} + +) +``` + +## Step 2: Add the BME280 in I2C mode + +The BME280 can speak SPI or I2C. For this HAT we tie `CSB` high to select I2C mode and tie `SDO` low so the sensor uses the common `0x76` I2C address. Tie `SDO` high instead if you need the alternate `0x77` address. + + ( + + + + + + + + + +) +`} /> + +## Step 3: Add I2C pull-up resistors + +I2C lines are open-drain, so the bus needs pull-ups. Use 4.7 kΩ as a good default for a short Pi HAT. If you add long cables or several modules, verify rise time with an oscilloscope and consider stronger pull-ups such as 2.2 kΩ. + +```tsx + + + + + + +``` + +## Step 4: Add decoupling capacitors + +Place a 100 nF capacitor within a few millimeters of the BME280 supply pin and add a 1 µF capacitor nearby for the optional OLED/external header load. + +```tsx + + + + + + +``` + +## Step 5: Add optional OLED and external headers + +Use the same pin order on both headers so a cable can be shared between the optional OLED and an external sensor pod: `VCC`, `GND`, `SCL`, `SDA`. Mark pin 1 clearly on the silkscreen. + +```tsx + + +``` + +## PCB layout guidance + +- Keep the BME280 away from voltage regulators, the Pi CPU, LEDs, and other warm parts so temperature readings are not biased. +- Put ventilation slots or keep-out copper near the sensor if the enclosure is sealed. +- Route SDA and SCL as short, parallel-but-not-overlapping traces with a continuous ground reference. +- Place R1/R2 near the Pi header or near the middle of the bus; place C1 directly next to U1. +- If J2 leaves the enclosure, add ESD protection and keep the cable short to avoid I2C signal integrity problems. + +## Raspberry Pi software setup + +Enable I2C and confirm the device is visible: + +```bash +sudo raspi-config nonint do_i2c 0 +sudo reboot +sudo apt-get install -y i2c-tools python3-pip +i2cdetect -y 1 +``` + +You should see the BME280 at `0x76` if `SDO` is tied to ground, or `0x77` if `SDO` is tied to 3.3 V. + +### Python logging example + +```python +import time +import board +import busio +import adafruit_bme280.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 estimate: {bme280.altitude:.1f} m") + time.sleep(2) +``` + +Install the library with: + +```bash +pip3 install adafruit-circuitpython-bme280 +``` + +## Bring-up checklist + +1. Power the Pi with the HAT attached and measure 3.3 V on U1 before installing an OLED. +2. Run `i2cdetect -y 1` and verify that only the expected addresses appear. +3. Touch the BME280 gently and confirm temperature rises, then breathe near the board and confirm humidity rises. +4. If an OLED is installed, confirm it uses a different I2C address, commonly `0x3c`. +5. Compare pressure readings against a local weather station and set `sea_level_pressure` for accurate altitude estimates. + +## Next improvements + +- Add a Qwiic/Stemma QT connector for plug-in I2C accessories. +- Add a small cut-out or thermal isolation slot around the BME280 for better ambient temperature accuracy. +- Add a second address-select jumper so multiple sensor HATs can share the same bus during testing. From eff0887832ff826c6c2d56a0fb776d59ce83bea9 Mon Sep 17 00:00:00 2001 From: Molham Date: Sat, 23 May 2026 12:03:38 +0200 Subject: [PATCH 2/2] fix docs feedback for I2C sensor tutorial --- .../pi-hats/i2c-environmental-sensor-hat.mdx | 64 ++++++++++++------- 1 file changed, 40 insertions(+), 24 deletions(-) diff --git a/docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx b/docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx index 0e850f8e..ee8afe6d 100644 --- a/docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx +++ b/docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx @@ -10,7 +10,7 @@ import TscircuitIframe from "@site/src/components/TscircuitIframe" ## Overview -This tutorial walks through a compact Raspberry Pi HAT for logging temperature, relative humidity, and barometric pressure with a BME280 over I2C. The design includes the support parts that make an I2C sensor board reliable in the field: local decoupling, SDA/SCL pull-up resistors, an optional OLED display header, and a keyed external header for mounting the sensor away from the Pi. +This tutorial walks through a compact Raspberry Pi HAT for logging temperature, relative humidity, and barometric pressure with a BME280 over I2C. The design uses a common 3.3 V BME280 breakout/module footprint so the tutorial stays buildable without hand-soldering the bare LGA sensor. It includes the support parts that make an I2C sensor board reliable in the field: local decoupling, SDA/SCL pull-up resistors, an optional OLED display header, and an unkeyed external 1x4 header for mounting the sensor away from the Pi. ( ( - - @@ -94,7 +90,7 @@ The HAT exposes one BME280 sensor on the Pi's primary I2C bus and provides a sec | Ref | Part | Notes | | --- | --- | --- | -| U1 | BME280 environmental sensor | Temperature, humidity, and pressure sensor in I2C mode | +| U1 | BME280 3.3 V I2C breakout/module | Temperature, humidity, and pressure sensor; use a module with `VCC`, `GND`, `SCL`, and `SDA` pins | | R1, R2 | 4.7 kΩ resistors | Pull SDA and SCL up to 3.3 V | | C1 | 100 nF capacitor | High-frequency local decoupling near U1 | | C2 | 1 µF capacitor | Bulk decoupling for the sensor/header area | @@ -117,7 +113,7 @@ export default () => ( ## Step 2: Add the BME280 in I2C mode -The BME280 can speak SPI or I2C. For this HAT we tie `CSB` high to select I2C mode and tie `SDO` low so the sensor uses the common `0x76` I2C address. Tie `SDO` high instead if you need the alternate `0x77` address. +The bare BME280 is an LGA sensor with separate supply and mode pins, but this tutorial targets the common 3.3 V I2C breakout/module version. Use a module that already straps the sensor for I2C and exposes `VCC`, `GND`, `SCL`, and `SDA`. Most modules default to address `0x76`; some expose an address jumper for `0x77`. ( @@ -136,15 +132,13 @@ export default () => ( - - ) `} /> ## Step 3: Add I2C pull-up resistors -I2C lines are open-drain, so the bus needs pull-ups. Use 4.7 kΩ as a good default for a short Pi HAT. If you add long cables or several modules, verify rise time with an oscilloscope and consider stronger pull-ups such as 2.2 kΩ. +I2C lines are open-drain, so the bus needs pull-ups. Use 4.7 kΩ as a good default for a short Pi HAT. Many BME280 breakouts and OLED modules already include onboard SDA/SCL pull-ups; if J1 or J2 connects to those modules, leave R1/R2 unpopulated as DNP or remove the duplicate module pull-ups so the effective bus resistance does not become too strong. If you add long cables or several modules, verify rise time with an oscilloscope and adjust the installed pull-up value. ```tsx @@ -170,7 +164,7 @@ Place a 100 nF capacitor within a few millimeters of the BME280 supply pin and a ## Step 5: Add optional OLED and external headers -Use the same pin order on both headers so a cable can be shared between the optional OLED and an external sensor pod: `VCC`, `GND`, `SCL`, `SDA`. Mark pin 1 clearly on the silkscreen. +Use the same pin order on both unkeyed headers so a cable can be shared between the optional OLED and an external sensor pod: `VCC`, `GND`, `SCL`, `SDA`. Mark pin 1 clearly on the silkscreen, and use keyed cables or a keyed connector footprint if field mis-plugging is likely. ```tsx