From 830acf63f98da4bcf03036f85d70f60971451603 Mon Sep 17 00:00:00 2001 From: SimplyRayYZL Date: Wed, 20 May 2026 14:11:03 +0300 Subject: [PATCH 1/2] Add I2C Environmental Sensor Module tutorial --- .../i2c-environmental-sensor-module.mdx | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/tutorials/i2c-environmental-sensor-module.mdx diff --git a/docs/tutorials/i2c-environmental-sensor-module.mdx b/docs/tutorials/i2c-environmental-sensor-module.mdx new file mode 100644 index 0000000..a3d265b --- /dev/null +++ b/docs/tutorials/i2c-environmental-sensor-module.mdx @@ -0,0 +1,71 @@ +--- +title: Building an I2C Environmental Sensor Module +description: Build a BME280 temperature, humidity, and pressure sensor module with I2C pull-ups and an optional OLED connector. +--- + +## Overview + +This tutorial builds a compact BME280 environmental sensor module. The board exposes power, ground, SDA, and SCL on a header, includes pull-up resistors for the I2C bus, and adds an optional connector for a small I2C OLED display. + +## Requirements + +- BME280 sensor for temperature, humidity, and pressure. +- 4-pin host header with GND, VCC, SDA, and SCL. +- 4.7 kΩ pull-up resistors on SDA and SCL. +- 100 nF decoupling capacitor near the sensor. +- Optional OLED header on the same I2C bus. + +## I2C pull-up explanation + +I2C devices pull the bus low but do not actively drive it high. Pull-up resistors return SDA and SCL to VCC when the bus is idle. For a short 3.3 V sensor module, 4.7 kΩ is a practical default. + +## Step 1: Add the sensor + +```tsx +export default () => ( + + + +) +``` + +## Step 2: Add the host header and pull-ups + +```tsx + + + +``` + +## Step 3: Add optional OLED expansion + +```tsx + +``` + +## Complete example + +```tsx +export default () => ( + + + + + + + + + + + + +) +``` + +## Layout and bring-up checklist + +- Place the BME280 away from regulators and other heat sources. +- Keep the decoupling capacitor close to the sensor power pins. +- Label GND, VCC, SDA, and SCL on both headers. +- Scan the I2C bus after assembly and confirm the expected BME280 address. +- Compare sensor readings against a known reference during first test. From 1443d08cad0358b4c58738c4070780a5941d9a29 Mon Sep 17 00:00:00 2001 From: SimplyRayYZL Date: Wed, 20 May 2026 11:54:39 +0000 Subject: [PATCH 2/2] Expand I2C environmental sensor tutorial --- .../i2c-environmental-sensor-module.mdx | 181 ++++++++++++++---- 1 file changed, 140 insertions(+), 41 deletions(-) diff --git a/docs/tutorials/i2c-environmental-sensor-module.mdx b/docs/tutorials/i2c-environmental-sensor-module.mdx index a3d265b..75b7ee7 100644 --- a/docs/tutorials/i2c-environmental-sensor-module.mdx +++ b/docs/tutorials/i2c-environmental-sensor-module.mdx @@ -1,71 +1,170 @@ --- title: Building an I2C Environmental Sensor Module -description: Build a BME280 temperature, humidity, and pressure sensor module with I2C pull-ups and an optional OLED connector. +description: Build a BME280 temperature, humidity, and pressure module with I2C pull-ups, host header, optional OLED header, code examples, and layout guidance. --- +import CircuitPreview from "@site/src/components/CircuitPreview" + ## Overview -This tutorial builds a compact BME280 environmental sensor module. The board exposes power, ground, SDA, and SCL on a header, includes pull-up resistors for the I2C bus, and adds an optional connector for a small I2C OLED display. +This tutorial builds a compact I2C environmental sensor module around the BME280. The board exposes power, ground, SDA, and SCL on a host header, adds the pull-up resistors required by I2C, includes local decoupling near the sensor, and provides an optional second I2C header for a small OLED display. -## Requirements +The module is intended for 3.3 V systems. Many BME280 parts are not 5 V tolerant, so only connect the header to a 3.3 V microcontroller or add level shifting before using a 5 V host. -- BME280 sensor for temperature, humidity, and pressure. -- 4-pin host header with GND, VCC, SDA, and SCL. -- 4.7 kΩ pull-up resistors on SDA and SCL. -- 100 nF decoupling capacitor near the sensor. -- Optional OLED header on the same I2C bus. +## Requirements -## I2C pull-up explanation +- BME280 sensor for temperature, humidity, and barometric pressure. +- 4-pin host header: `GND`, `VCC`, `SDA`, `SCL`. +- 4.7 kΩ pull-up resistors from `SDA` and `SCL` to `VCC`. +- 100 nF decoupling capacitor near the BME280 power pins. +- Optional 4-pin OLED header on the same I2C bus. +- Clear silkscreen labels for both headers. -I2C devices pull the bus low but do not actively drive it high. Pull-up resistors return SDA and SCL to VCC when the bus is idle. For a short 3.3 V sensor module, 4.7 kΩ is a practical default. +## I2C and BME280 integration notes -## Step 1: Add the sensor +I2C devices pull the bus low but do not actively drive it high. Pull-up resistors return `SDA` and `SCL` to `VCC` when the bus is idle. For a short 3.3 V board, 4.7 kΩ is a practical default. If the host board already has strong pull-ups, you can mark `R1` and `R2` as do-not-populate. -```tsx -export default () => ( - - - -) -``` +The BME280 commonly responds at I2C address `0x76` or `0x77`, depending on the state of the `SDO` address-select pin. Tie `SDO` to ground for `0x76` or to `VCC` for `0x77`. -## Step 2: Add the host header and pull-ups +## Step 1: Add the BME280 sensor ```tsx - - - + ``` -## Step 3: Add optional OLED expansion +`CSB` is tied high so the part stays in I2C mode. `SDI` is used as `SDA`, and `SCK` is used as `SCL`. + +## Step 2: Add headers and pull-ups ```tsx - + + + + ``` -## Complete example +## Schematic and 3D preview -```tsx + ( - - - - - + + + + + - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + ) +`} /> + +## Bill of materials + +| Ref | Part | Notes | +| --- | --- | --- | +| U1 | BME280 | Temperature, humidity, pressure sensor | +| J1 | 4-pin header | Host connection: GND, VCC, SDA, SCL | +| J2 | 4-pin header | Optional OLED expansion header | +| R1/R2 | 4.7 kΩ resistors | I2C pull-ups to VCC | +| C1 | 100 nF capacitor | Local sensor decoupling | + +## Microcontroller code examples + +### Arduino / ESP32 + +```cpp +#include +#include + +Adafruit_BME280 bme; + +void setup() { + Serial.begin(115200); + Wire.begin(); + if (!bme.begin(0x76)) { + Serial.println("BME280 not found; try address 0x77"); + while (1) delay(10); + } +} + +void loop() { + Serial.print("Temperature C: "); + Serial.println(bme.readTemperature()); + Serial.print("Humidity %: "); + Serial.println(bme.readHumidity()); + Serial.print("Pressure hPa: "); + Serial.println(bme.readPressure() / 100.0F); + delay(1000); +} ``` -## Layout and bring-up checklist +### Raspberry Pi Python + +```python +import time +import board +import adafruit_bme280.basic as adafruit_bme280 + +i2c = board.I2C() +bme280 = adafruit_bme280.Adafruit_BME280_I2C(i2c, address=0x76) + +while True: + print(f"Temp: {bme280.temperature:.1f} C") + print(f"Humidity: {bme280.relative_humidity:.1f} %") + print(f"Pressure: {bme280.pressure:.1f} hPa") + time.sleep(1) +``` + +## PCB layout guidance + +- Place `C1` within a few millimeters of the BME280 `VDD` and `GND` pins. +- Keep the sensor away from hot regulators, LEDs, processors, and board edges with strong airflow. +- Route `SDA` and `SCL` together and keep them short. +- Put the host header at the edge of the board and label every pin on silkscreen. +- If you add an OLED, remember it shares the same bus and must not conflict with the BME280 address. + +## Bring-up checklist -- Place the BME280 away from regulators and other heat sources. -- Keep the decoupling capacitor close to the sensor power pins. -- Label GND, VCC, SDA, and SCL on both headers. -- Scan the I2C bus after assembly and confirm the expected BME280 address. -- Compare sensor readings against a known reference during first test. +1. Verify the host is 3.3 V before connecting the module. +2. Use an I2C scanner and confirm the BME280 appears at `0x76` or `0x77`. +3. Confirm temperature, humidity, and pressure readings change plausibly. +4. If the bus does not scan, check pull-ups and confirm `CSB` is tied high for I2C mode. +5. If readings are warm, move the module away from heat sources or add airflow isolation.