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..bebc127e --- /dev/null +++ b/docs/tutorials/pi-hats/class-d-audio-amplifier-hat.mdx @@ -0,0 +1,493 @@ +--- +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. + +## 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. + +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 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..e322b0a7 --- /dev/null +++ b/docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx @@ -0,0 +1,312 @@ +--- +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 + +## 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. + +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 */