Tutorial: I2C Environmental Sensor Module

docs/tutorials/pi-hats/class-d-audio-amplifier-hat.mdx

@@ -0,0 +1,106 @@
+---
+title: Class D Audio Amplifier HAT
+description: Build a Class D Audio Amplifier HAT with PAM8403 for 3W per channel stereo output.
+---
+
+## Overview
+
+This tutorial shows you how to build a Class D Audio Amplifier HAT using the PAM8403 chip, delivering 3W per channel of stereo audio output with volume control and speaker terminals.
+
+## What You'll Need
+
+- PAM8403 Class D amplifier chip
+- Volume control potentiometer (10k)
+- Speaker terminals (2-pin, screw type)
+- Input filtering capacitors
+- Power supply decoupling capacitors
+- 3.5mm audio input jack
+
+## Circuit Design
+
+import TscircuitIframe from "@site/src/components/TscircuitIframe"
+
+<TscircuitIframe defaultView="3d" code={`
+
+export default () => {
+  return (
+    <board width="65mm" height="56mm">
+      {/* Audio Input Jack */}
+      <chip name="J1" footprint="audio-jack-3.5mm" pcbX={-25} pcbY={0}
+        connections={{ L: "net.AUDL", R: "net.AUDR", GND: "net.GND" }}
+      />
+      {/* Volume Control */}
+      <chip name="RV1" footprint="potentiometer-10k" pcbX={-10} pcbY={15}
+        connections={{ pin1: "net.AUDL", pin2: "net.VOL_L", pin3: "net.GND" }}
+      />
+      <chip name="RV2" footprint="potentiometer-10k" pcbX={-10} pcbY={-15}
+        connections={{ pin1: "net.AUDR", pin2: "net.VOL_R", pin3: "net.GND" }}
+      />
+      {/* PAM8403 Amplifier */}
+      <chip name="U1" footprint="sop-16" pcbX={5} pcbY={0}
+        connections={{
+          INL: "net.VOL_L", INR: "net.VOL_R",
+          OUTL_P: "net.SP_L_P", OUTL_N: "net.SP_L_N",
+          OUTR_P: "net.SP_R_P", OUTR_N: "net.SP_R_N",
+          VDD: "net.VCC", GND: "net.GND"
+        }}
+      />
+      {/* Output Filter Inductors */}
+      <chip name="L1" footprint="inductor-0805" pcbX={15} pcbY={8} />
+      <chip name="L2" footprint="inductor-0805" pcbX={15} pcbY={-8} />
+      {/* Decoupling Capacitors */}
+      <capacitor name="C1" capacitance="100uF" footprint="1206" pcbX={5} pcbY={12} />
+      <capacitor name="C2" capacitance="1uF" footprint="0402" pcbX={8} pcbY={12} />
+      {/* Speaker Terminals */}
+      <chip name="J2" footprint="screw-terminal-2pin" pcbX={25} pcbY={8}
+        connections={{ pin1: "net.SP_L_P", pin2: "net.SP_L_N" }}
+      />
+      <chip name="J3" footprint="screw-terminal-2pin" pcbX={25} pcbY={-8}
+        connections={{ pin1: "net.SP_R_P", pin2: "net.SP_R_N" }}
+      />
+    </board>
+  )
+}
+`} />
+
+## Step-by-Step Instructions
+
+### 1. Audio Input
+Place a 3.5mm audio jack at the edge of the board. This accepts stereo line-level input from any audio source.
+
+### 2. Volume Control
+Add dual 10k potentiometers for left and right channel volume control. Wire them as voltage dividers between the audio input and ground.
+
+### 3. PAM8403 Amplifier
+The PAM8403 is a 3W+3W Class D amplifier. Place it centrally with adequate copper pour for heat dissipation. It operates on 5V supply.
+
+### 4. Output LC Filter
+Class D amplifiers require output inductors to filter the PWM switching waveform. Use ferrite bead inductors on each output.
+
+### 5. Power Supply Decoupling
+Add a 100uF bulk capacitor and 1uF ceramic capacitor near the PAM8403 VDD pin to prevent supply ripple.
+
+### 6. Speaker Terminals
+Use screw terminals for speaker connections, supporting 4-8 ohm speakers rated for at least 3W.
+
+## Specifications
+
+- **Supply Voltage:** 5V DC
+- **Output Power:** 3W per channel (4 ohm load)
+- **Efficiency:** >85% (Class D)
+- **THD+N:** <0.2% at 1W
+- **Frequency Response:** 20Hz - 20kHz
+
+## Testing
+
+1. Connect 5V power supply (capable of at least 2A)
+2. Connect 4-8 ohm speakers to terminal blocks
+3. Feed audio signal via 3.5mm jack
+4. Adjust volume potentiometers
+5. Verify clean audio output with no audible distortion
+
+## Safety Notes
+
+- Do not short speaker outputs
+- Use speakers rated for at least 3W
+- Keep audio input traces away from output traces to prevent oscillation

docs/tutorials/pi-hats/i2c-environmental-sensor-hat.mdx

@@ -0,0 +1,93 @@
+---
+title: I2C Environmental Sensor Module
+description: Build an I2C Environmental Sensor Module with BME280 for temperature, humidity, and pressure readings.
+---
+
+## Overview
+
+This tutorial guides you through building an I2C Environmental Sensor Module using the BME280 sensor, capable of measuring temperature, humidity, and atmospheric pressure. An optional OLED display shows real-time readings.
+
+## What You'll Need
+
+- BME280 sensor (temperature, humidity, pressure)
+- I2C pull-up resistors (4.7k)
+- Optional SSD1306 OLED display
+- Pin header for external connection
+- Decoupling capacitors
+
+## Circuit Design
+
+import TscircuitIframe from "@site/src/components/TscircuitIframe"
+
+<TscircuitIframe defaultView="3d" code={`
+
+export default () => {
+  return (
+    <board width="40mm" height="30mm">
+      {/* BME280 Environmental Sensor */}
+      <chip name="U1" footprint="lga-8" pcbX={0} pcbY={0}
+        connections={{ SDA: "net.SDA", SCL: "net.SCL", VDD: "net.VCC", GND: "net.GND" }}
+      />
+      {/* I2C Pull-up Resistors */}
+      <resistor name="R1" resistance="4.7k" footprint="0402" pcbX={-8} pcbY={5} />
+      <resistor name="R2" resistance="4.7k" footprint="0402" pcbX={-5} pcbY={5} />
+      {/* Optional OLED Display */}
+      <chip name="U2" footprint="oled-ssd1306" pcbX={10} pcbY={0}
+        connections={{ SDA: "net.SDA", SCL: "net.SCL", VDD: "net.VCC", GND: "net.GND" }}
+      />
+      {/* Decoupling Capacitor */}
+      <capacitor name="C1" capacitance="100nF" footprint="0402" pcbX={-8} pcbY={-5} />
+      <capacitor name="C2" capacitance="1uF" footprint="0402" pcbX={-5} pcbY={-5} />
+      {/* Pin Header */}
+      <chip name="J1" footprint="pin-header-6" pcbX={15} pcbY={8}
+        connections={{ pin1: "net.VCC", pin2: "net.GND", pin3: "net.SDA", pin4: "net.SCL" }}
+      />
+    </board>
+  )
+}
+`} />
+
+## Step-by-Step Instructions
+
+### 1. BME280 Sensor Placement
+Place the BME280 sensor in an LGA-8 footprint at the center of the board. Ensure adequate airflow around the sensor for accurate readings.
+
+### 2. I2C Pull-up Resistors
+Add 4.7k pull-up resistors on both SDA and SCL lines. These are essential for proper I2C communication. Connect them between the I2C lines and VCC.
+
+### 3. Power Supply Filtering
+Place 100nF and 1uF decoupling capacitors close to the BME280 VDD pin to filter power supply noise.
+
+### 4. Optional OLED Display
+Mount an SSD1306 128x64 OLED display sharing the same I2C bus. It connects to the same SDA/SCL lines with no additional components needed.
+
+### 5. Pin Header
+Add a 6-pin header for external connections: VCC, GND, SDA, SCL, and two spare pins for additional sensors.
+
+## Software Setup
+
+```python
+# Raspberry Pi I2C Setup
+import board
+import adafruit_bme280
+
+i2c = board.I2C()
+sensor = adafruit_bme280.Adafruit_BME280_I2C(i2c)
+
+print(f"Temperature: {sensor.temperature:.1f} C")
+print(f"Humidity: {sensor.humidity:.1f} %")
+print(f"Pressure: {sensor.pressure:.1f} hPa")
+```
+
+## Calibration
+
+- For accurate altitude readings, calibrate the pressure sensor to your local sea-level pressure
+- Allow 5 minutes warm-up time for stable temperature readings
+- Avoid placing near heat-generating components
+
+## Testing
+
+1. Power on the module (3.3V)
+2. Run `i2cdetect -y 1` to verify BME280 at address 0x76 or 0x77
+3. Read sensor values and verify they match ambient conditions
+4. If using OLED, verify display shows correct readings

docs/tutorials/pi-hats/usb-power-delivery-trigger-hat.mdx

@@ -0,0 +1,88 @@
+---
+title: USB Power Delivery Trigger HAT
+description: Build a USB Power Delivery Trigger HAT with voltage negotiation using the FP28XX/CH224K controller.
+---
+
+## Overview
+
+This tutorial walks you through building a USB Power Delivery (PD) Trigger HAT for Raspberry Pi using tscircuit. The HAT negotiates voltages from 5V to 20V via USB PD and provides terminal block outputs with status indication.
+
+## What You'll Need
+
+- USB PD controller (FP28XX, CH224K, or PD2001)
+- USB-C connector
+- Terminal blocks for power output
+- Status LEDs
+- Filtering capacitors (100uF, 10uF)
+- Pull-up/pull-down resistors for PD negotiation
+
+## Circuit Design
+
+import TscircuitIframe from "@site/src/components/TscircuitIframe"
+
+<TscircuitIframe defaultView="3d" code={`
+
+export default () => {
+  return (
+    <board width="65mm" height="56mm">
+      {/* USB-C Input Connector */}
+      <chip name="U1" footprint="usb-c" pcbX={-25} pcbY={0}
+        connections={{ VBUS: "net.VBUS", GND: "net.GND", CC1: "net.CC1", CC2: "net.CC2" }}
+      />
+      {/* USB PD Controller - CH224K */}
+      <chip name="U2" footprint="esso-16" pcbX={0} pcbY={0}
+        connections={{ VBUS: "net.VBUS", GND: "net.GND", CC1: "net.CC1", CC2: "net.CC2" }}
+      />
+      {/* Voltage Select Resistors */}
+      <resistor name="R1" resistance="10k" footprint="0402" pcbX={5} pcbY={8} />
+      <resistor name="R2" resistance="10k" footprint="0402" pcbX={8} pcbY={8} />
+      {/* Output Filter Capacitors */}
+      <capacitor name="C1" capacitance="100uF" footprint="1206" pcbX={15} pcbY={-5} />
+      <capacitor name="C2" capacitance="10uF" footprint="0805" pcbX={20} pcbY={-5} />
+      {/* Status LED */}
+      <led name="D1" color="green" footprint="0603" pcbX={25} pcbY={5} />
+      <resistor name="R4" resistance="1k" footprint="0402" pcbX={25} pcbY={10} />
+      {/* Terminal Block Output */}
+      <chip name="J2" footprint="screw-terminal-2pin" pcbX={25} pcbY={0} />
+    </board>
+  )
+}
+`} />
+
+## Step-by-Step Instructions
+
+### 1. USB-C Input
+Place the USB-C connector at one edge of the board. This serves as the power input and PD communication interface.
+
+### 2. PD Controller
+The CH224K USB PD controller handles voltage negotiation. Connect CC1/CC2 lines from the USB-C connector to the controller for PD communication.
+
+### 3. Voltage Selection
+Configure the desired output voltage (5V, 9V, 12V, 15V, or 20V) using pull-down resistors on the CFG pins:
+- **5V:** CFG1=Low, CFG2=Low, CFG3=Low
+- **9V:** CFG1=High, CFG2=Low, CFG3=Low
+- **12V:** CFG1=Low, CFG2=High, CFG3=Low
+- **15V:** CFG1=High, CFG2=High, CFG3=Low
+- **20V:** CFG1=Low, CFG2=Low, CFG3=High
+
+### 4. Output Filtering
+Add bulk (100uF) and decoupling (10uF) capacitors on the output to reduce voltage ripple.
+
+### 5. Status LED
+Add a green LED with a 1k current-limiting resistor to indicate when power is active.
+
+### 6. Terminal Block Output
+Use a 2-pin screw terminal for the regulated output, making it easy to connect external devices.
+
+## Testing
+
+1. Connect a USB-C PD power supply to the input
+2. Verify the negotiated voltage on the terminal block with a multimeter
+3. Check the status LED illuminates
+4. Measure output ripple under load (should be <100mV)
+
+## Safety Notes
+
+- Ensure adequate trace width for higher currents (use 2oz copper for 20V/3A)
+- Add a polyfuse on the output for overcurrent protection
+- Keep PD communication traces short and away from high-current paths