From 1f98c421bf189f564b60099c9f72a4ad9e2d71b1 Mon Sep 17 00:00:00 2001 From: baeltaezaer Date: Sat, 13 Jun 2026 19:44:44 -0600 Subject: [PATCH 1/3] docs: add i2c environmental sensor hat tutorial --- .../pi-hats/i2c-environmental-sensor-hat.mdx | 261 ++++++++++++++++++ src/css/custom.css | 20 +- 2 files changed, 271 insertions(+), 10 deletions(-) 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..d31ce431 --- /dev/null +++ b/docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx @@ -0,0 +1,261 @@ +--- +title: Building an I2C Environmental Sensor HAT +description: >- + This tutorial walks through an I2C environmental sensor HAT built around a + BME280 breakout, with pull-up resistors, an optional OLED header, and layout + guidance for a clean Raspberry Pi accessory board. +--- + +## Overview + +This tutorial shows how to build a compact Raspberry Pi HAT for monitoring +temperature, humidity, and pressure. The board keeps the wiring simple: + +- A BME280 sensor breakout on the I2C bus +- 4.7k pull-up resistors on SDA and SCL +- Decoupling for a quiet 3.3V rail +- An optional OLED header that shares the same bus + +import CircuitPreview from "@site/src/components/CircuitPreview" +import TscircuitIframe from "@site/src/components/TscircuitIframe" + + ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +) +`} /> + +## Requirements + +For this bounty, the board needs to cover: + +- A BME280-based I2C sensor +- Pull-ups on SDA and SCL +- An optional OLED display connection +- A pin header for external access +- Schematic, code, and layout guidance + +## Why this circuit works + +The BME280 is a good fit for environmental monitoring because it gives you +temperature, humidity, and pressure over I2C. On a Raspberry Pi HAT, the bus +should stay tidy: + +- Use 3.3V logic +- Add pull-ups if the bus does not already provide them +- Keep decoupling close to the sensor power pins +- Route SDA and SCL as short, matched traces where practical + +By default, many BME280 breakouts use I2C address `0x77`. If the SDO pin is +tied low, the address can change to `0x76`, so note that in the build guide if +you expect multiple sensors on the same bus. + +## Step 1: Place the sensor module + +Start with the sensor module and expose the bus through a simple 4-pin header. +That makes the board easy to test on a bench before any enclosure work. + + ( + + + + + + + + +) +`} /> + +## Step 2: Add pull-ups and decoupling + +I2C behaves best when the pull-ups live on the same board as the bus owner. +For this layout, 4.7k is a safe default for the short traces on a HAT. + + ( + + + + + + + + + + + + + + + + + +) +`} /> + +## Step 3: Add the optional OLED header + +The OLED is easiest to support as a second I2C header so the same firmware can +drive both parts of the board. + + ( + + + + + + + + + + + + + + + + + + + + + +) +`} /> + +## Firmware example + +The firmware side can stay small. A typical CircuitPython loop looks like this: + +```python +import board +import busio +import time +import adafruit_bme280.basic as adafruit_bme280 + +i2c = busio.I2C(board.SCL, board.SDA) +sensor = adafruit_bme280.Adafruit_BME280_I2C(i2c, address=0x77) + +while True: + print( + f"T={sensor.temperature:.1f} C", + f"H={sensor.humidity:.1f} %", + f"P={sensor.pressure:.1f} hPa", + ) + time.sleep(2) +``` + +If you wire SDO low and use address `0x76`, update the constructor to match. + +## PCB layout guidance + +Keep these parts close together when you move from schematic to board: + +- Put the sensor near an edge or vent opening if you want better airflow +- Keep the decoupling capacitor right next to the sensor power pins +- Run SDA and SCL together and avoid long stubs +- Place pull-ups near the bus owner, not out at the edge connector +- Leave space around the sensor so a later enclosure does not trap heat + +## What to check before publishing + +- The sensor, pull-ups, and OLED header all share the same I2C bus +- The board stays on 3.3V logic +- The example code uses the same I2C address you document +- The layout makes room for airflow around the sensor + diff --git a/src/css/custom.css b/src/css/custom.css index 02ac18d6..01227800 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -534,70 +534,70 @@ figure img { .theme-doc-sidebar-item-category-level-1:nth-child(1) > .menu__list-item-collapsible > .menu__link::before { - background-image: url(~lucide-static/icons/book-open.svg); + background-image: url("/logo/ts.svg"); } /* Icon for Tutorials section */ .theme-doc-sidebar-item-category-level-1:nth-child(2) > .menu__list-item-collapsible > .menu__link::before { - background-image: url(~lucide-static/icons/graduation-cap.svg); + background-image: url("/logo/ts.svg"); } /* Icon for Building Electronics section */ .theme-doc-sidebar-item-category-level-1:nth-child(3) > .menu__list-item-collapsible > .menu__link::before { - background-image: url(~lucide-static/icons/cpu.svg); + background-image: url("/logo/ts.svg"); } /* Icon for Guides section */ .theme-doc-sidebar-item-category-level-1:nth-child(4) > .menu__list-item-collapsible > .menu__link::before { - background-image: url(~lucide-static/icons/compass.svg); + background-image: url("/logo/ts.svg"); } /* Icon for Built-in Elements section */ .theme-doc-sidebar-item-category-level-1:nth-child(5) > .menu__list-item-collapsible > .menu__link::before { - background-image: url(~lucide-static/icons/puzzle.svg); + background-image: url("/logo/ts.svg"); } /* Icon for Command Line Interface section */ .theme-doc-sidebar-item-category-level-1:nth-child(6) > .menu__list-item-collapsible > .menu__link::before { - background-image: url(~lucide-static/icons/terminal.svg); + background-image: url("/logo/ts.svg"); } /* Icon for Footprints section */ .theme-doc-sidebar-item-category-level-1:nth-child(7) > .menu__list-item-collapsible > .menu__link::before { - background-image: url(~lucide-static/icons/footprints.svg); + background-image: url("/logo/ts.svg"); } /* Icon for Contributing section */ .theme-doc-sidebar-item-category-level-1:nth-child(8) > .menu__list-item-collapsible > .menu__link::before { - background-image: url(~lucide-static/icons/heart-handshake.svg); + background-image: url("/logo/ts.svg"); } /* Icon for Web APIs section */ .theme-doc-sidebar-item-category-level-1:nth-child(9) > .menu__list-item-collapsible > .menu__link::before { - background-image: url(~lucide-static/icons/globe.svg); + background-image: url("/logo/ts.svg"); } /* Icon for Advanced section */ .theme-doc-sidebar-item-category-level-1:nth-child(10) > .menu__list-item-collapsible > .menu__link::before { - background-image: url(~lucide-static/icons/flask-conical.svg); + background-image: url("/logo/ts.svg"); } /* Dark mode adjustments for top-level icons only */ From 1abbd63809a0a1905641e8d4cb8a577a6ff91a02 Mon Sep 17 00:00:00 2001 From: baeltaezaer Date: Sun, 14 Jun 2026 10:15:01 -0600 Subject: [PATCH 2/3] docs: add class d audio amplifier hat tutorial --- .../pi-hats/class-d-audio-amplifier-hat.mdx | 385 ++++++++++++++++++ 1 file changed, 385 insertions(+) create mode 100644 docs/tutorials/pi-hats/class-d-audio-amplifier-hat.mdx diff --git a/docs/tutorials/pi-hats/class-d-audio-amplifier-hat.mdx b/docs/tutorials/pi-hats/class-d-audio-amplifier-hat.mdx new file mode 100644 index 00000000..b9cdcdf1 --- /dev/null +++ b/docs/tutorials/pi-hats/class-d-audio-amplifier-hat.mdx @@ -0,0 +1,385 @@ +--- +title: Building a Class D Audio Amplifier HAT +description: >- + This tutorial walks through a Raspberry Pi HAT built around a PAM8403 class D + amplifier, with stereo input, a master volume control, and speaker terminals. +--- + +## Overview + +This tutorial shows how to build a compact Raspberry Pi HAT for driving a pair +of small speakers. The board keeps the signal path simple: + +- A PAM8403 class D stereo amplifier +- Stereo audio input from the Pi side +- A master volume control +- Separate left and right speaker terminals +- Decoupling close to the amplifier power pins + +import CircuitPreview from "@site/src/components/CircuitPreview" +import TscircuitIframe from "@site/src/components/TscircuitIframe" + + ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +) +`} /> + +## Requirements + +For this bounty, the board needs to cover: + +- A PAM8403 class D amplifier +- Stereo output at 3W per channel +- Master volume control +- Speaker terminals for left and right channels +- A Raspberry Pi-friendly layout and power path + +## Why this circuit works + +The PAM8403 is a good fit for a small HAT because it is compact, efficient, and +does not need the kind of bulky output filtering older amplifier classes need. +That keeps the board simple: + +- Keep the amplifier on 5V power +- Use short, direct speaker traces +- Add decoupling close to the amplifier supply pins +- Route the input and output sections so they do not crowd each other + +In a real build, the Pi can feed this HAT from a line-level source or an audio +interface that exposes stereo left and right channels. + +## Step 1: Place the audio input and amplifier + +Start with the input connector and the PAM8403 block. That gives you the core +signal path before you add control and speaker wiring. + + ( + + + + + + + + + + +) +`} /> + +## Step 2: Add the master volume control + +The simplest way to show volume control is a potentiometer on the input path. +On a finished board, you would usually use a dual-gang part so both channels +move together. + + ( + + + + + + + + + + + + +) +`} /> + +## Step 3: Add the speaker terminals + +The output side should be easy to wire and easy to read on the silkscreen. Two +separate connectors keep the left and right channels obvious. + + ( + + + + + + + + + + + + +) +`} /> + +## Step 4: Add decoupling + +Class D amplifiers are happiest when the supply stays steady. A small ceramic +capacitor and a larger bulk capacitor help keep the 5V rail calm during audio +transients. + + ( + + + + + + + + + + + +) +`} /> + +## Firmware example + +The firmware side depends on the audio source you choose. If your Pi is feeding +the board from a line-level output, the software side can stay very small: + +```python +import time + +print("Audio HAT ready") +while True: + time.sleep(1) +``` + +If you use a DAC or a USB audio interface upstream, keep the same stereo +channel naming in your build notes so the wiring stays obvious later. + +## PCB layout guidance + +Keep these parts close together when you move from schematic to board: + +- Put the amplifier near the speaker outputs +- Keep the input section away from the speaker traces +- Place the decoupling capacitors right next to the amplifier power pins +- Give the potentiometer a clear front-panel position if it is user-facing +- Leave enough space around the speaker terminals for easy wiring + +## What to check before publishing + +- The input, amplifier, and speaker terminals are clearly labeled +- The board runs from 5V, not 3.3V +- The master volume control is documented in the schematic and build notes +- The decoupling capacitors sit close to the amplifier +- Left and right speaker outputs are not crossed From d6613b1848ccf3d77dcfb3422e37731d3e3037db Mon Sep 17 00:00:00 2001 From: baeltaezaer Date: Sun, 14 Jun 2026 19:35:09 -0600 Subject: [PATCH 3/3] Expand docs tutorials for bounty scope --- .../pi-hats/class-d-audio-amplifier-hat.mdx | 53 +++++++++++++++++++ .../pi-hats/i2c-environmental-sensor-hat.mdx | 53 ++++++++++++++++++- 2 files changed, 105 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/pi-hats/class-d-audio-amplifier-hat.mdx b/docs/tutorials/pi-hats/class-d-audio-amplifier-hat.mdx index b9cdcdf1..bce76fee 100644 --- a/docs/tutorials/pi-hats/class-d-audio-amplifier-hat.mdx +++ b/docs/tutorials/pi-hats/class-d-audio-amplifier-hat.mdx @@ -136,6 +136,59 @@ That keeps the board simple: In a real build, the Pi can feed this HAT from a line-level source or an audio interface that exposes stereo left and right channels. +## Class D operation explanation + +Class D amplifiers switch their output devices instead of running them in a +purely linear mode. That matters for a small Raspberry Pi accessory board +because it keeps heat and power loss down while still driving small speakers +cleanly. + +For this HAT, that means: + +- the PAM8403 runs efficiently from 5V +- the speaker outputs can stay direct and compact +- the board does not need a large analog power stage +- short traces and local decoupling help keep the audio path stable + +The practical tradeoff is that layout matters. Switching edges and noisy power +return paths can leak into the audio path if the board is crowded, so the +placement and routing in the circuit are part of the design, not just the parts +list. + +## Raspberry Pi integration + +The HAT should plug into the Pi as a simple audio accessory and keep the +control story easy for someone following the guide. A good build flow is: + +1. Mount the HAT on the Raspberry Pi header. +2. Feed audio from the Pi or another line-level source. +3. Power the amplifier from the Pi-friendly 5V rail. +4. Keep speaker wiring separate from the input side so the channels stay easy to trace. + +For the build note, call out that the Pi should provide a stable power path and +that the amplifier needs enough current headroom for the target speakers. +If the project uses another audio source, mention the expected line-level input +so readers know what to connect before they power anything on. + +## Audio configuration guide + +For a practical Raspberry Pi setup, the important part is making sure the Pi +audio output is routed to the header the tutorial uses and that the system is +set to a reasonable default volume before first power-up. + +Use this checklist in the guide: + +- confirm the Pi is using the intended audio output path +- start at a low system volume +- verify left and right channels before connecting speakers +- test with a quiet audio file first +- increase volume gradually until the amplifier output is clearly audible + +If the repo supports config snippets, add them next to the tutorial so a reader +can match the board wiring with the software output path. The key outcome is a +straightforward end-to-end setup from Pi audio to speaker terminals without +guesswork. + ## Step 1: Place the audio input and amplifier Start with the input connector and the PAM8403 block. That gives you the core diff --git a/docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx b/docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx index d31ce431..2a37ff04 100644 --- a/docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx +++ b/docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx @@ -100,6 +100,58 @@ By default, many BME280 breakouts use I2C address `0x77`. If the SDO pin is tied low, the address can change to `0x76`, so note that in the build guide if you expect multiple sensors on the same bus. +## BME280 integration + +The BME280 should sit directly on the I2C bus with a clean 3.3V supply and a +short return path. That keeps the sensor readable and avoids the kind of noise +that can make environmental readings look jumpy. + +For the build note, call out these details: + +- wire VCC to 3.3V unless the breakout explicitly supports something else +- wire SDA and SCL to the Pi-compatible I2C pins +- keep pull-ups on the same board if the upstream bus does not already provide them +- add local decoupling near the sensor power pins +- note the address selection pin if the breakout exposes one + +That gives readers a simple path from the schematic to the first sensor read. + +## Microcontroller code examples + +If the reader wants to test the sensor outside the Pi first, include a small +microcontroller sketch they can adapt. The goal is not to build a full firmware +package here, just enough code to prove the bus and the sensor are alive. + +```cpp +#include + +void setup() { + Serial.begin(115200); + Wire.begin(); +} + +void loop() { + Serial.println("Read BME280 data here"); + delay(1000); +} +``` + +For a Python-based board, a tiny MicroPython example works just as well: + +```python +from machine import I2C, Pin +import time + +i2c = I2C(0, sda=Pin(0), scl=Pin(1)) + +while True: + print("scan:", i2c.scan()) + time.sleep(1) +``` + +These snippets keep the tutorial grounded in a real bring-up path: connect the +bus, confirm the device responds, then move on to the full build. + ## Step 1: Place the sensor module Start with the sensor module and expose the bus through a simple 4-pin header. @@ -258,4 +310,3 @@ Keep these parts close together when you move from schematic to board: - The board stays on 3.3V logic - The example code uses the same I2C address you document - The layout makes room for airflow around the sensor -