From df3d7460dc977fb329127c687b49b292d83f8a68 Mon Sep 17 00:00:00 2001 From: b3417 <120667073+b3417@users.noreply.github.com> Date: Fri, 12 Jun 2026 17:52:37 -0600 Subject: [PATCH 1/4] docs: add class d audio amplifier hat tutorial This tutorial details the construction of a Raspberry Pi HAT utilizing the PAM8403 stereo Class D amplifier, including features like volume control and audio integration. --- class-d-audio-amplifier-hat.mdx | 440 ++++++++++++++++++++++++++++++++ 1 file changed, 440 insertions(+) create mode 100644 class-d-audio-amplifier-hat.mdx diff --git a/class-d-audio-amplifier-hat.mdx b/class-d-audio-amplifier-hat.mdx new file mode 100644 index 0000000..8ea1729 --- /dev/null +++ b/class-d-audio-amplifier-hat.mdx @@ -0,0 +1,440 @@ +--- +title: Building a Class D Audio Amplifier HAT +description: >- + This tutorial walks through a Raspberry Pi HAT based on the PAM8403 stereo + Class D amplifier, with volume control, speaker terminals, and Raspberry Pi + audio integration. +--- + +## Overview + +This tutorial shows how to build a Raspberry Pi HAT around a PAM8403-based +stereo Class D amplifier stage. The design focuses on the parts that matter in +practice: line-level stereo input, volume control, speaker terminals, and solid +power decoupling for the 5V rail. + +import CircuitPreview from "@site/src/components/CircuitPreview" +import TscircuitIframe from "@site/src/components/TscircuitIframe" + + ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +) +`} /> + +## Why Class D? + +The PAM8403 is a 3W stereo Class D amplifier. In practice, that means: + +- high efficiency compared with linear audio amplifiers +- low heat for a compact HAT enclosure +- direct drive for small speakers without a bulky output filter +- enough power for desk speakers, media boxes, and audio add-ons + +The official Diodes page for the part is here: [PAM8403](https://www.diodes.com/part/view/PAM8403). + +## Circuit Requirements + +Our HAT needs to: + +- accept stereo line-level audio from the Raspberry Pi or an external DAC +- provide independent or shared volume control +- drive left and right speakers from the amplifier outputs +- stay stable on the Pi's 5V rail with nearby decoupling capacitors + +## Building the Circuit Step by Step + +### Step 1: Place the HAT board and amplifier stage + +The base of the design is the Raspberry Pi HAT form factor plus the PAM8403 +amplifier block. + + ( + + + +) +`} /> + +### Step 2: Add the stereo input and volume control + +For a clean layout, the tutorial uses one volume trimmer per channel. The audio +source enters through a 3-pin connector, then each channel passes through a +coupling capacitor and a potentiometer before reaching the amplifier input. + + ( + + + + + + + + + + + + + + + + + + + + + +) +`} /> + +### Step 3: Add the speaker terminals + +Class D outputs should go to the speaker terminals directly. Do not tie either +speaker lead to ground. + + ( + + + + + + + + + + + +) +`} /> + +### Step 4: Add decoupling and power + +The amplifier needs a clean 5V supply. Put a small ceramic capacitor and a +larger bulk capacitor close to the amplifier power pins. + + ( + + + + + + + + + + + + + +) +`} /> + +## Understanding the Amplifier + +Class D amplifiers work by switching their output stage rapidly instead of +running it in a linear region. The speaker and output network average those +switching pulses back into audio, which is why the part is efficient and runs +cooler than many linear designs. + +The practical takeaway is simple: use short speaker traces, give the chip good +decoupling, and keep the speaker outputs floating. The outputs are not meant to +be shorted to ground. + +## Raspberry Pi Integration + +The HAT itself uses the Pi's 40-pin header for power and mounting. For audio, +the safest assumption is line-level stereo input from the Pi's audio path or an +external DAC. If you want a self-contained product, you can swap the input +header for a jack or DAC module without changing the rest of the amplifier +section. + +Practical connections to keep in mind: + +- 5V and ground come from the HAT header +- the audio source should stay line-level, not speaker-level +- the amplifier output goes only to speakers +- a mute or enable GPIO can be added later if you want software control + +## Audio Configuration Guide + +On Raspberry Pi OS, make sure audio output is enabled and test the source before +you blame the amplifier. + +1. Open `raspi-config` and enable the relevant audio output. +2. Confirm the device tree and firmware audio settings are active. +3. Test playback with a sine wave or a short WAV file. +4. If the output sounds weak, check the source level before increasing gain in + the amplifier path. + +For a production board, double-check the exact PAM8403 package pinout against +the datasheet for the chip variant you source. + +## Next Steps + +- add a mute pin or GPIO-controlled enable line +- swap the input header for a 3.5 mm jack footprint +- add silkscreen labels for the left and right speaker channels +- pair the HAT with a small enclosure and panel-mounted terminals From 415d4ef2987bd2d4832abf0229804dd7a5e965fe Mon Sep 17 00:00:00 2001 From: b3417 <120667073+b3417@users.noreply.github.com> Date: Fri, 12 Jun 2026 17:54:08 -0600 Subject: [PATCH 2/4] docs: add class d audio amplifier hat tutorial This tutorial provides detailed steps to build a Raspberry Pi HAT using the PAM8403 stereo Class D amplifier. It includes circuit requirements, component placements, and integration with the Raspberry Pi. --- .../pi-hats/class-d-audio-amplifier-hat.mdx | 440 ++++++++++++++++++ 1 file changed, 440 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 0000000..8ea1729 --- /dev/null +++ b/docs/tutorials/pi-hats/class-d-audio-amplifier-hat.mdx @@ -0,0 +1,440 @@ +--- +title: Building a Class D Audio Amplifier HAT +description: >- + This tutorial walks through a Raspberry Pi HAT based on the PAM8403 stereo + Class D amplifier, with volume control, speaker terminals, and Raspberry Pi + audio integration. +--- + +## Overview + +This tutorial shows how to build a Raspberry Pi HAT around a PAM8403-based +stereo Class D amplifier stage. The design focuses on the parts that matter in +practice: line-level stereo input, volume control, speaker terminals, and solid +power decoupling for the 5V rail. + +import CircuitPreview from "@site/src/components/CircuitPreview" +import TscircuitIframe from "@site/src/components/TscircuitIframe" + + ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +) +`} /> + +## Why Class D? + +The PAM8403 is a 3W stereo Class D amplifier. In practice, that means: + +- high efficiency compared with linear audio amplifiers +- low heat for a compact HAT enclosure +- direct drive for small speakers without a bulky output filter +- enough power for desk speakers, media boxes, and audio add-ons + +The official Diodes page for the part is here: [PAM8403](https://www.diodes.com/part/view/PAM8403). + +## Circuit Requirements + +Our HAT needs to: + +- accept stereo line-level audio from the Raspberry Pi or an external DAC +- provide independent or shared volume control +- drive left and right speakers from the amplifier outputs +- stay stable on the Pi's 5V rail with nearby decoupling capacitors + +## Building the Circuit Step by Step + +### Step 1: Place the HAT board and amplifier stage + +The base of the design is the Raspberry Pi HAT form factor plus the PAM8403 +amplifier block. + + ( + + + +) +`} /> + +### Step 2: Add the stereo input and volume control + +For a clean layout, the tutorial uses one volume trimmer per channel. The audio +source enters through a 3-pin connector, then each channel passes through a +coupling capacitor and a potentiometer before reaching the amplifier input. + + ( + + + + + + + + + + + + + + + + + + + + + +) +`} /> + +### Step 3: Add the speaker terminals + +Class D outputs should go to the speaker terminals directly. Do not tie either +speaker lead to ground. + + ( + + + + + + + + + + + +) +`} /> + +### Step 4: Add decoupling and power + +The amplifier needs a clean 5V supply. Put a small ceramic capacitor and a +larger bulk capacitor close to the amplifier power pins. + + ( + + + + + + + + + + + + + +) +`} /> + +## Understanding the Amplifier + +Class D amplifiers work by switching their output stage rapidly instead of +running it in a linear region. The speaker and output network average those +switching pulses back into audio, which is why the part is efficient and runs +cooler than many linear designs. + +The practical takeaway is simple: use short speaker traces, give the chip good +decoupling, and keep the speaker outputs floating. The outputs are not meant to +be shorted to ground. + +## Raspberry Pi Integration + +The HAT itself uses the Pi's 40-pin header for power and mounting. For audio, +the safest assumption is line-level stereo input from the Pi's audio path or an +external DAC. If you want a self-contained product, you can swap the input +header for a jack or DAC module without changing the rest of the amplifier +section. + +Practical connections to keep in mind: + +- 5V and ground come from the HAT header +- the audio source should stay line-level, not speaker-level +- the amplifier output goes only to speakers +- a mute or enable GPIO can be added later if you want software control + +## Audio Configuration Guide + +On Raspberry Pi OS, make sure audio output is enabled and test the source before +you blame the amplifier. + +1. Open `raspi-config` and enable the relevant audio output. +2. Confirm the device tree and firmware audio settings are active. +3. Test playback with a sine wave or a short WAV file. +4. If the output sounds weak, check the source level before increasing gain in + the amplifier path. + +For a production board, double-check the exact PAM8403 package pinout against +the datasheet for the chip variant you source. + +## Next Steps + +- add a mute pin or GPIO-controlled enable line +- swap the input header for a 3.5 mm jack footprint +- add silkscreen labels for the left and right speaker channels +- pair the HAT with a small enclosure and panel-mounted terminals From 91ce834d0fd8c5b4d96ca3742d775af8e82e246d Mon Sep 17 00:00:00 2001 From: b3417 <120667073+b3417@users.noreply.github.com> Date: Fri, 12 Jun 2026 17:55:19 -0600 Subject: [PATCH 3/4] docs: remove misplaced root copy of class d tutorial --- class-d-audio-amplifier-hat.mdx | 440 -------------------------------- 1 file changed, 440 deletions(-) delete mode 100644 class-d-audio-amplifier-hat.mdx diff --git a/class-d-audio-amplifier-hat.mdx b/class-d-audio-amplifier-hat.mdx deleted file mode 100644 index 8ea1729..0000000 --- a/class-d-audio-amplifier-hat.mdx +++ /dev/null @@ -1,440 +0,0 @@ ---- -title: Building a Class D Audio Amplifier HAT -description: >- - This tutorial walks through a Raspberry Pi HAT based on the PAM8403 stereo - Class D amplifier, with volume control, speaker terminals, and Raspberry Pi - audio integration. ---- - -## Overview - -This tutorial shows how to build a Raspberry Pi HAT around a PAM8403-based -stereo Class D amplifier stage. The design focuses on the parts that matter in -practice: line-level stereo input, volume control, speaker terminals, and solid -power decoupling for the 5V rail. - -import CircuitPreview from "@site/src/components/CircuitPreview" -import TscircuitIframe from "@site/src/components/TscircuitIframe" - - ( - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -) -`} /> - -## Why Class D? - -The PAM8403 is a 3W stereo Class D amplifier. In practice, that means: - -- high efficiency compared with linear audio amplifiers -- low heat for a compact HAT enclosure -- direct drive for small speakers without a bulky output filter -- enough power for desk speakers, media boxes, and audio add-ons - -The official Diodes page for the part is here: [PAM8403](https://www.diodes.com/part/view/PAM8403). - -## Circuit Requirements - -Our HAT needs to: - -- accept stereo line-level audio from the Raspberry Pi or an external DAC -- provide independent or shared volume control -- drive left and right speakers from the amplifier outputs -- stay stable on the Pi's 5V rail with nearby decoupling capacitors - -## Building the Circuit Step by Step - -### Step 1: Place the HAT board and amplifier stage - -The base of the design is the Raspberry Pi HAT form factor plus the PAM8403 -amplifier block. - - ( - - - -) -`} /> - -### Step 2: Add the stereo input and volume control - -For a clean layout, the tutorial uses one volume trimmer per channel. The audio -source enters through a 3-pin connector, then each channel passes through a -coupling capacitor and a potentiometer before reaching the amplifier input. - - ( - - - - - - - - - - - - - - - - - - - - - -) -`} /> - -### Step 3: Add the speaker terminals - -Class D outputs should go to the speaker terminals directly. Do not tie either -speaker lead to ground. - - ( - - - - - - - - - - - -) -`} /> - -### Step 4: Add decoupling and power - -The amplifier needs a clean 5V supply. Put a small ceramic capacitor and a -larger bulk capacitor close to the amplifier power pins. - - ( - - - - - - - - - - - - - -) -`} /> - -## Understanding the Amplifier - -Class D amplifiers work by switching their output stage rapidly instead of -running it in a linear region. The speaker and output network average those -switching pulses back into audio, which is why the part is efficient and runs -cooler than many linear designs. - -The practical takeaway is simple: use short speaker traces, give the chip good -decoupling, and keep the speaker outputs floating. The outputs are not meant to -be shorted to ground. - -## Raspberry Pi Integration - -The HAT itself uses the Pi's 40-pin header for power and mounting. For audio, -the safest assumption is line-level stereo input from the Pi's audio path or an -external DAC. If you want a self-contained product, you can swap the input -header for a jack or DAC module without changing the rest of the amplifier -section. - -Practical connections to keep in mind: - -- 5V and ground come from the HAT header -- the audio source should stay line-level, not speaker-level -- the amplifier output goes only to speakers -- a mute or enable GPIO can be added later if you want software control - -## Audio Configuration Guide - -On Raspberry Pi OS, make sure audio output is enabled and test the source before -you blame the amplifier. - -1. Open `raspi-config` and enable the relevant audio output. -2. Confirm the device tree and firmware audio settings are active. -3. Test playback with a sine wave or a short WAV file. -4. If the output sounds weak, check the source level before increasing gain in - the amplifier path. - -For a production board, double-check the exact PAM8403 package pinout against -the datasheet for the chip variant you source. - -## Next Steps - -- add a mute pin or GPIO-controlled enable line -- swap the input header for a 3.5 mm jack footprint -- add silkscreen labels for the left and right speaker channels -- pair the HAT with a small enclosure and panel-mounted terminals From 1f98c421bf189f564b60099c9f72a4ad9e2d71b1 Mon Sep 17 00:00:00 2001 From: baeltaezaer Date: Sat, 13 Jun 2026 19:44:44 -0600 Subject: [PATCH 4/4] 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 0000000..d31ce43 --- /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 02ac18d..0122780 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 */