diff --git a/docs/tutorials/arduino-uno-atmega328p-schematic.mdx b/docs/tutorials/arduino-uno-atmega328p-schematic.mdx new file mode 100644 index 0000000..026ccfa --- /dev/null +++ b/docs/tutorials/arduino-uno-atmega328p-schematic.mdx @@ -0,0 +1,283 @@ +--- +title: Arduino Uno ATmega328P Schematic Tutorial +description: Build a complete Arduino Uno compatible board from scratch using tscircuit — ATmega328P, USB interface, power regulation, and I/O headers. +--- + +## Overview + +This tutorial guides you through designing a complete Arduino Uno compatible board using tscircuit. The Arduino Uno is one of the most popular microcontroller boards, and understanding its circuit design is foundational for electronics engineers. + +import TscircuitIframe from "@site/src/components/TscircuitIframe" + +## System Architecture + +The Arduino Uno consists of four main subsystems: + +1. **MCU**: ATmega328P — the heart of the board +2. **USB Interface**: ATmega16U2 — USB-to-serial conversion +3. **Power**: 5V regulator and auto-switching (USB/external) +4. **I/O**: Digital/analog pin headers, ICSP connectors + +## Components + +| Ref | Part | Description | Footprint | +|-----|------|-------------|-----------| +| U1 | ATmega328P-PU | Main MCU, 32KB Flash, 2KB SRAM | `dip-28` | +| U2 | ATmega16U2 | USB-to-Serial interface | `tqfp-32` | +| U3 | NCP1117-5.0 | 5V LDO regulator | `sot-223` | +| J1 | USB-B | USB Type-B connector | `usb-b` | +| Y1 | 16 MHz Crystal | MCU clock source | `hc49` | +| R1 | Reset pull-up | 10kΩ resistor | `0805` | +| C1-C3 | Decoupling caps | 100nF ceramic | `0805` | +| C4 | Crystal load (×2) | 22pF ceramic | `0805` | +| LED_P | Power LED | Green indicator | `0805` | +| LED_L | D13 LED | Yellow activity LED | `0805` | +| JP1-JP4 | Pin headers | Digital/Analog I/O | `pin_header_1x15` | + +## Step 1: ATmega328P MCU + +The ATmega328P is an 8-bit AVR microcontroller with 32KB of flash memory: + +```tsx + +``` + +### Key Pin Assignments + +| Pin | Function | Description | +|-----|----------|-------------| +| 1 | RESET | Active-low reset, pulled up to 5V | +| 2-4 | PD0-PD2 | Digital I/O 0-2 (RX, TX, INT0) | +| 5-6 | PD3-PD4 | Digital I/O 3-4 (INT1, XCK) | +| 7-8 | VCC/GND | Power supply | +| 9-10 | PB6-PB7 | XTAL1/XTAL2 (crystal oscillator) | +| 11-13 | PB0-PB2 | Digital I/O 8-10 (SPI) | +| 14-17 | PB3-PB5 | Digital I/O 11-13 (SPI, PWM) | +| 18-19 | XTAL2/GND | Crystal and ground | +| 20 | AVCC | ADC power supply (connect to VCC) | +| 21 | AREF | ADC reference voltage | +| 22-27 | PC0-PC5 | Analog inputs A0-A5 | +| 28 | VCC | Power supply | + +## Step 2: 16 MHz Crystal Oscillator + +The ATmega328P requires an external 16 MHz crystal for clock generation: + +```tsx + + + + + + + + + + + +``` + +## Step 3: Reset Circuit + +The reset circuit ensures the MCU starts in a known state: + +```tsx + + + + + + + +``` + +The pull-up resistor keeps RESET high during normal operation. The capacitor provides noise filtering. + +## Step 4: Power Regulation + +The Arduino can be powered via USB or an external barrel jack (7-12V): + +```tsx + + + + + + + + + + + + + +``` + +## Step 5: LED Indicators + +```tsx + + + + + + + + + + + + + +``` + +## Step 6: Pin Headers + +```tsx + + + + +``` + +### Digital I/O Mapping + +| Header Pin | ATmega328P Pin | Arduino Pin | +|------------|----------------|-------------| +| JP1:1 | PD0 | D0 (RX) | +| JP1:2 | PD1 | D1 (TX) | +| JP1:3 | PD2 | D2 | +| JP1:4 | PD3 | D3 (PWM) | +| JP1:5 | PD4 | D4 | +| JP1:6 | PD5 | D5 (PWM) | +| JP1:7 | PD6 | D6 (PWM) | +| JP1:8 | PD7 | D7 | + +## Complete Circuit + +```tsx +export default () => { + return ( + + {/* ATmega328P MCU */} + + + {/* 16 MHz Crystal */} + + + + + {/* Reset Circuit */} + + + + {/* Power Regulator */} + + + + + {/* LEDs */} + + + + + + {/* Pin Headers */} + + + + + + ) +} +``` + + { + return ( + + + + + + + + + + + + + + + + ) +} +`} /> + +## PCB Layout Guidelines + +### Power Traces +- **5V supply**: Minimum 0.5mm width for 500mA current +- **3.3V supply**: Minimum 0.3mm width +- **GND plane**: Solid ground plane on bottom layer + +### Crystal Routing +- **Keep traces short**: Under 10mm from crystal to MCU pins +- **Guard ring**: Route ground pour around crystal traces +- **No vias**: Avoid vias in crystal signal paths + +### Decoupling Capacitors +- **Placement**: Within 2mm of MCU power pins +- **Trace width**: 0.3mm minimum +- **Via placement**: Use multiple vias for ground connections + +## Manufacturing Files + +```bash +# Generate Gerbers +tsci build --gerber + +# Generate BOM +tsci build --bom + +# Generate Assembly +tsci build --pick-and-place +``` + +## Cost Estimate + +| Component | Unit Cost | Qty | Total | +|-----------|-----------|-----|-------| +| ATmega328P-PU | $1.80 | 1 | $1.80 | +| ATmega16U2 | $1.20 | 1 | $1.20 | +| NCP1117-5.0 | $0.20 | 1 | $0.20 | +| USB-B Connector | $0.15 | 1 | $0.15 | +| 16 MHz Crystal | $0.15 | 1 | $0.15 | +| Passives (×15) | $0.02 | 15 | $0.30 | +| Pin Headers (×4) | $0.10 | 4 | $0.40 | +| PCB (2-layer) | $1.00 | 1 | $1.00 | +| **Total** | | | **$5.20** | + +## Summary + +You've designed a complete Arduino Uno compatible board covering: +- ATmega328P MCU configuration +- 16 MHz crystal oscillator circuit +- Reset circuit with noise filtering +- Power regulation and filtering +- LED indicators for status and activity +- Pin header layout matching Arduino Uno form factor +- Manufacturing file generation + +This design is fully compatible with the Arduino IDE and bootloader. diff --git a/docs/tutorials/building-a-simple-usb-flashlight.mdx b/docs/tutorials/building-a-simple-usb-flashlight.mdx index bdf3473..5e171eb 100644 --- a/docs/tutorials/building-a-simple-usb-flashlight.mdx +++ b/docs/tutorials/building-a-simple-usb-flashlight.mdx @@ -1,42 +1,326 @@ ---- -title: Building a Simple USB Flashlight -description: Learn how to build a simple USB-powered flashlight circuit using tscircuit with a push button, LED, and USB-C connector. ---- - -## Overview - -This tutorial will walk you through building a simple USB flashlight using -tscircuit. - -import TscircuitIframe from "@site/src/components/TscircuitIframe" - - { - return ( - - - .pos", pin2: "net.VBUS" }} - pcbX={0} - pcbY={-1} - /> - - - - - - - ) -} -`} /> +--- +title: Building a Simple USB Flashlight (Complete Guide) +description: Step-by-step tutorial to build a USB-powered flashlight circuit using tscircuit — components, schematic, PCB layout, and manufacturing. +--- + +## Overview + +This tutorial walks you through building a simple USB-powered flashlight using tscircuit. You'll learn how to design a circuit that takes 5V from a USB-C connector, uses a push button for on/off control, drives an LED through a current-limiting resistor, and lays it out as a manufacturable PCB. + +import TscircuitIframe from "@site/src/components/TscircuitIframe" + +## Components + +| Ref | Part | Description | Footprint | +|-----|------|-------------|-----------| +| J1 | USB-C Receptacle | USB Type-C connector for 5V power | `smd-usb-c` | +| SW1 | Tactile Push Button | Momentary SPST switch for on/off | `pushbutton` | +| LED1 | Red LED | 0603 surface-mount indicator LED | `0603` | +| R1 | 150Ω Resistor | Current limiting resistor for LED | `0603` | + +## Circuit Theory + +The circuit is straightforward: + +1. **USB-C Power**: The USB-C connector provides 5V on VBUS and a ground reference on GND +2. **Push Button**: Acts as a switch between VBUS and the LED circuit +3. **Current Limiting**: The 150Ω resistor limits LED current to approximately 20mA +4. **LED Indicator**: The red LED illuminates when the button is pressed + +### Current Calculation + +Using Ohm's Law: `I = (V_source - V_LED) / R` + +For a red LED with forward voltage ~2.0V: +`I = (5.0V - 2.0V) / 150Ω = 20mA` + +This is the typical operating current for a standard 0603 indicator LED. + +## Step 1: USB-C Connector + +Start with the USB-C receptacle. We use the community-sourced `@tsci/seveibar.smd-usb-c` component: + +```tsx +import { SmdUsbC } from "@tsci/seveibar.smd-usb-c" + + +``` + +Key points: +- Both GND pins are tied to the ground net +- Both VBUS pins are tied to the power net +- `pcbY={-10}` places it at the board edge for connector access +- `schX={-4}` positions it on the left side of the schematic + +## Step 2: Push Button Switch + +The push button connects between VBUS and the rest of the circuit: + +```tsx + .pos", + }} + pcbX={0} + pcbY={-1} +/> +``` + +When pressed, pin1 connects to pin2, completing the circuit from VBUS through the LED. + +## Step 3: LED and Current-Limiting Resistor + +```tsx + + + .pin2", + neg: ".LED1 > .pos", + }} +/> +``` + +The resistor is placed in series with the LED to limit current. Without it, the LED would draw excessive current and burn out. + +## Step 4: Ground Return Path + +```tsx + +``` + +The LED's cathode connects to ground, completing the circuit. + +## Step 5: Complete Circuit + +Here's the full circuit file: + +```tsx +import { SmdUsbC } from "@tsci/seveibar.smd-usb-c" + +export default () => { + return ( + + + .pos", + }} + pcbX={0} + pcbY={-1} + /> + .pin2", + neg: ".LED1 > .pos", + }} + /> + + + ) +} +``` + + { + return ( + + + .pos" }} + pcbX={0} + pcbY={-1} + /> + + + + + + + ) +} +`} /> + +## PCB Layout Considerations + +### Board Dimensions +- **Width**: 12mm — narrow enough to fit in a pen-sized housing +- **Height**: 30mm — provides enough space for all components with good spacing + +### Component Placement +- USB-C at the bottom edge (-10mm) for external access +- Push button in the middle for easy pressing +- LED at the top (12mm) as the light source +- Resistor between button and LED in the current path + +### Trace Routing +The tscircuit autorouter handles the connections, but you can also manually route traces: + +```tsx + + + +``` + +Use wider traces (0.5mm) for power connections and standard width (0.3mm) for signal lines. + +## Schematic View + +The schematic shows the circuit topology clearly: + +``` +USB-C VBUS ──┬── SW1 ── R1 ── LED1 ── GND + │ +USB-C GND ───┴──────────────────────── +``` + +- Current flows from VBUS through the button when pressed +- The resistor limits current to the LED +- The return path goes through ground + +## Building and Testing + +### Local Development + +```bash +# Create a new tscircuit project +mkdir usb-flashlight && cd usb-flashlight +tsci init + +# Save the circuit file +# (copy the circuit code into index.circuit.tsx) + +# Build the project +tsci build + +# View in browser +tsci preview +``` + +### Generate Manufacturing Files + +```bash +# Generate Gerber files for PCB fabrication +tsci build --gerber + +# Generate BOM (Bill of Materials) +tsci build --bom + +# Generate pick-and-place file +tsci build --pick-and-place +``` + +## Cost Estimate + +| Component | Unit Cost | Quantity | Total | +|-----------|-----------|----------|-------| +| USB-C Receptacle | $0.15 | 1 | $0.15 | +| Tactile Push Button | $0.05 | 1 | $0.05 | +| Red LED 0603 | $0.02 | 1 | $0.02 | +| Resistor 150Ω 0603 | $0.01 | 1 | $0.01 | +| PCB (2-layer) | $0.50 | 1 | $0.50 | +| **Total** | | | **$0.73** | + +At scale (1000+ units), the per-unit cost drops below $0.30. + +## Extensions + +Once you have the basic flashlight working, try these modifications: + +### Multiple LEDs +```tsx + + + + +``` + +### Different LED Colors +```tsx + + + +``` + +### Add a Capacitor for Persistence +Add a small capacitor to keep the LED lit briefly after releasing the button: + +```tsx + +``` + +## Summary + +You've built a complete USB-powered flashlight circuit using tscircuit, covering: +- Component selection and specification +- Circuit theory and current calculations +- Complete circuit implementation in TSX +- PCB layout with proper component placement +- Manufacturing file generation +- Cost analysis +- Extension ideas for more advanced versions + +This project demonstrates tscircuit's ability to handle everything from simple LED circuits to complex multi-layer PCB designs. diff --git a/docs/tutorials/class-d-audio-amplifier-hat.mdx b/docs/tutorials/class-d-audio-amplifier-hat.mdx new file mode 100644 index 0000000..0941ee6 --- /dev/null +++ b/docs/tutorials/class-d-audio-amplifier-hat.mdx @@ -0,0 +1,347 @@ +--- +title: Building a Class D Audio Amplifier HAT Tutorial +description: Learn how to design a Raspberry Pi HAT-compatible Class D audio amplifier using tscircuit — TPA2016D2, I2S interface, power filtering, and speaker output stage. +--- + +## Overview + +This tutorial covers designing a Raspberry Pi Zero/4 compatible Class D Audio Amplifier HAT using tscircuit. You'll learn about Class D amplification principles, I2S digital audio interface, power supply filtering, and thermal management for audio circuits. + +import TscircuitIframe from "@site/src/components/TscircuitIframe" + +## Project Specifications + +| Parameter | Value | +|-----------|-------| +| Board Size | 65mm × 56mm (Pi HAT form factor) | +| Output Power | 2× 3W into 4Ω, 2× 1.5W into 8Ω | +| Power Supply | 5V from Raspberry Pi GPIO or barrel jack | +| Audio Interface | I2S (PCM5102A DAC) | +| Amplifier IC | TPA2016D2 (Class D) | + +## Components + +| Ref | Part | Description | Footprint | +|-----|------|------------|-----------| +| U1 | TPA2016D2 | 2-channel Class D amplifier | `qfn-32` | +| U2 | PCM5102A | I2S DAC | `qfn-28` | +| J1 | 40-pin GPIO Header | Raspberry Pi HAT compatible | `raspberry-pi-hat-40pin` | +| J2 | Screw Terminal | Speaker output L | `screw_terminal_2pin` | +| J3 | Screw Terminal | Speaker output R | `screw_terminal_2pin` | +| J4 | Barrel Jack | 5V external power | `barrel_jack` | +| C1 | Input filter cap | 100nF ceramic | `0805` | +| C2-C5 | Supply bypass caps | 100nF + 10µF | `0805`/`0805` | +| C6-C7 | Output coupling caps | 470µF electrolytic | `through_hole_electrolytic` | +| L1-L2 | Output inductors | 10µH ferrite | `1210` | +| R1-R2 | Input resistors | 10kΩ | `0805` | +| LED1 | Power indicator | Green LED | `0805` | + +## Class D Amplifier Theory + +Class D amplifiers use pulse-width modulation (PWM) to amplify audio signals: + +1. **Input**: Analog audio signal +2. **Modulation**: Compares audio to high-frequency triangle wave (~384kHz) +3. **Output**: PWM stream that varies duty cycle with audio amplitude +4. **Filtering**: LC low-pass filter removes switching frequency +5. **Speaker**: Smooth current drives the speaker + +**Advantages over Class AB**: +- Efficiency up to 90% (vs ~60% for Class AB) +- Less heat dissipation +- Smaller form factor +- Longer battery life in portable applications + +## Step 1: PCM5102A I2S DAC + +The PCM5102A is a high-performance stereo DAC with hardware I2S interface: + +```tsx + + + + + + + + /* Ground SCK for hardware I2S mode */ + + + + /* I2S format */ +``` + +### PCM5102A Pin Configuration + +| Pin | Function | Connection | +|-----|----------|------------| +| VCC | 3.3V supply | LDO output | +| GND | Ground | System ground | +| SCK | System clock | Ground (use PLL) | +| BCK | Bit clock | From Pi I2S | +| LRCK | Left/Right clock | From Pi I2S | +| DIN | Audio data input | From Pi I2S | +| FMT | Format select | 3.3V (I2S) | +| XSMT | Soft mute control | 3.3V (unmuted) | + +## Step 2: TPA2016D2 Class D Amplifier + +The TPA2016D2 provides 2×3W output with integrated feedback: + +```tsx + + +/* Power supply connections */ + + + + + +``` + +### Input Filtering + +```tsx + + + + + + + + + + + + + +``` + +### Output LC Low-Pass Filter + +Each channel requires an LC filter to remove the PWM switching frequency: + +```tsx + + + + + + + + /* Left speaker + */ + + + + + /* Right speaker + */ + + +``` + +## Step 3: Raspberry Pi GPIO Header + +```tsx + + +/* I2S signals from Pi */ + /* I2S BCK */ + /* I2S LRCK */ + /* I2S DIN */ + +/* Power from Pi */ + + + + +/* ID EEPROM (optional for auto-config) */ + + +``` + +## Step 4: Power Supply Design + +### 3.3V LDO for DAC + +```tsx + + + + + + + + + + + +``` + +### Power Filtering + +```tsx + + + + + + +``` + +## Step 5: Power LED + +```tsx + + + + + + +``` + +## Complete Circuit + +```tsx +export default () => { + return ( + + {/* DAC - PCM5102A */} + + + {/* Amplifier - TPA2016D2 */} + + + {/* Power - 3.3V LDO */} + + + {/* Pi GPIO Header */} + + + {/* Speaker Terminals */} + + + + {/* Output Inductors */} + + + + {/* Power LED */} + + + + {/* Bypass Capacitors */} + + + ) +} +``` + + { + return ( + + + + + + + + + + + + + ) +} +`} /> + +## Thermal Considerations + +Class D amplifiers generate heat based on output power and speaker load: + +| Output Power | Into 4Ω | Into 8Ω | Thermal Design | +|-------------|---------|---------|----------------| +| 0.5W | 85°C | 80°C | No heatsink needed | +| 1.5W | 95°C | 88°C | Heatsink recommended | +| 3W | 115°C | 95°C | Large heatsink required | + +**Thermal pad connection**: Connect the TPA2016D2 thermal pad to a large copper area or dedicated heatsink pad. + +## PCB Layout Guidelines + +### High-Current Paths +- **Speaker output traces**: Minimum 1mm width for 3W operation +- **Power traces**: 0.5mm minimum from 5V supply +- **Use fills**: Pour copper on output stage for heat dissipation + +### Signal Integrity +- **Keep digital and analog grounds separate** +- **Short I2S traces**: Keep BCK/LRCK/DIN under 50mm +- **Decoupling**: Place caps within 2mm of each power pin + +### EMI Considerations +- **Output filters**: Place close to amplifier outputs +- **Ferrite beads**: Consider adding on power input +- **Ground plane**: Solid ground under entire board + +## Raspberry Pi Software Configuration + +Add to `/boot/config.txt`: + +``` +dtoverlay=hifiberry-dac +``` + +Or for specific DAC: + +``` +dtoverlay=rpi-dac +``` + +Test with: + +```bash +aplay -l # List audio devices +speaker-test -c 2 # Test audio output +``` + +## Cost Estimate + +| Component | Unit Cost | Qty | Total | +|-----------|-----------|-----|-------| +| TPA2016D2 | $1.80 | 1 | $1.80 | +| PCM5102A | $1.20 | 1 | $1.20 | +| MCP1700-330E | $0.25 | 1 | $0.25 | +| Passives (×15) | $0.02 | 15 | $0.30 | +| Inductors 10µH | $0.15 | 2 | $0.30 | +| Electrolytic caps | $0.10 | 2 | $0.20 | +| Connectors | $0.50 | 3 | $1.50 | +| PCB (4-layer) | $2.00 | 1 | $2.00 | +| **Total** | | | **$7.55** | + +## Summary + +You've designed a complete Class D Audio Amplifier HAT covering: +- Class D amplification theory and PWM modulation +- I2S digital audio interface with PCM5102A DAC +- TPA2016D2 amplifier with output filtering +- Raspberry Pi HAT form factor with GPIO header +- Thermal management for audio circuits +- Software configuration for Linux + +This HAT is ready for integration with any Raspberry Pi project requiring high-quality audio output. diff --git a/docs/tutorials/esp32-pcb-layout-routing.mdx b/docs/tutorials/esp32-pcb-layout-routing.mdx new file mode 100644 index 0000000..bdab417 --- /dev/null +++ b/docs/tutorials/esp32-pcb-layout-routing.mdx @@ -0,0 +1,329 @@ +--- +title: ESP32 PCB Layout and Routing Tutorial +description: Learn how to design a complete ESP32 development board with tscircuit — component placement, trace routing, USB connectivity, and manufacturing. +--- + +## Overview + +This tutorial covers designing a complete ESP32 development board using tscircuit. You'll learn professional PCB layout techniques including component placement, power trace routing, USB differential pairs, crystal oscillator placement, and antenna keepout zones. + +import TscircuitIframe from "@site/src/components/TscircuitIframe" + +## Project Specifications + +| Parameter | Value | +|-----------|-------| +| Board Size | 30mm × 60mm | +| Layers | 2-layer (Top/Bottom) | +| Target | ESP32-WROOM-32 development board | +| USB | USB-C for programming and power | +| Voltage Regulator | 5V to 3.3V LDO (AMS1117-3.3) | +| Programming | Auto-reset via DTR/RTS from USB-UART | + +## Components + +| Ref | Part | Description | Footprint | +|-----|------|-------------|-----------| +| U1 | ESP32-WROOM-32 | Dual-core MCU with WiFi/BT | `esp32-wroom-32` | +| J1 | USB-C Receptacle | USB Type-C for power/programming | `smd-usb-c` | +| U2 | CH340G | USB-to-Serial bridge | `sop-16` | +| U3 | AMS1117-3.3 | 3.3V LDO regulator | `sot-223` | +| Y1 | 32.768 kHz Crystal | RTC clock oscillator | `3215_smd` | +| Y2 | 40 MHz Crystal | Main MCU oscillator | `2520_smd` | +| C1-C4 | Decoupling caps | 100nF ceramic capacitors | `0402` | +| R1-R6 | Pull-up/pull-down | 10kΩ resistors | `0402` | +| LED1 | Power indicator | Green status LED | `0603` | +| LED2 | TX indicator | Yellow activity LED | `0603` | +| SW1 | Reset button | Tactile push button | `pushbutton` | +| SW2 | Boot button | Tactile push button | `pushbutton` | + +## Step 1: Power Architecture + +The ESP32 requires a stable 3.3V supply. We use an AMS1117-3.3 LDO regulator: + +```tsx + + + + + + + + +``` + +### Decoupling Capacitors + +Each power pin on the ESP32 needs a 100nF decoupling capacitor placed as close as possible: + +```tsx + + + + +``` + +**Rule of thumb**: Place decoupling caps within 2mm of the power pin they're decoupling. + +## Step 2: ESP32 Module Placement + +The ESP32-WROOM-32 should be placed with the antenna overhanging the board edge for optimal WiFi performance: + +```tsx + +``` + +### Critical Placement rules: + +1. **Antenna keepout**: No copper pour within 15mm of the antenna area +2. **Ground plane**: Solid ground plane under the module +3. **Crystal proximity**: Place 40MHz crystal within 5mm of OSC pins +4. **Flash memory**: Keep high-speed signals away from the antenna side + +## Step 3: USB-C and CH340G Circuit + +The CH340G provides USB-to-serial conversion for programming: + +```tsx +import { SmdUsbC } from "@tsci/seveibar.smd-usb-c" + + .d-", + D2: ".U2 > .d+", + }} + pcbX={-25} + pcbY={0} +/> + + +``` + +### Auto-Reset Circuit + +The ESP32 needs an auto-reset circuit for programming. Connect CH340G DTR and RTS to ESP32 EN and GPIO0: + +```tsx + + + + + + + +``` + +## Step 4: Crystal Oscillators + +### 40 MHz Main Crystal + +```tsx + + + + + + + + + +``` + +### 32.768 kHz RTC Crystal + +```tsx + + + + +``` + +## Step 5: LED Indicators + +```tsx + + + + + + +``` + +## Step 6: Reset and Boot Buttons + +```tsx + + + + + + + + +``` + +## Complete Circuit + +```tsx +import { SmdUsbC } from "@tsci/seveibar.smd-usb-c" + +export default () => { + return ( + + {/* ESP32 Module */} + + + {/* USB-C Connector */} + + + {/* CH340G USB-UART */} + + + {/* AMS1117-3.3 Voltage Regulator */} + + + {/* Power LED */} + + + + {/* Reset Button */} + + + {/* Boot Button */} + + + {/* 40 MHz Crystal */} + + + {/* 32.768 kHz Crystal */} + + + {/* Decoupling Capacitors */} + + + + + + ) +} +``` + + { + return ( + + + + + + + + + + + + + ) +} +`} /> + +## PCB Layout Rules + +### Power Traces +- **5V input**: Minimum 0.5mm trace width (500mA current) +- **3.3V output**: Minimum 0.3mm trace width (ESP32 peak ~500mA) +- **GND plane**: Use a solid ground plane on the bottom layer + +### Signal Traces +- **UART (TX/RX)**: 0.2mm traces, keep short +- **SPI**: 0.2mm traces, controlled impedance not needed at ESP32 speeds +- **I2C**: 0.2mm traces with 4.7kΩ pull-ups + +### USB Differential Pair +- **D+/D-**: Route as differential pair with 90Ω impedance +- **Length matching**: Keep length difference under 5mm +- **Ground reference**: Solid ground plane underneath + +### Antenna Guidelines +- **Keepout zone**: 15mm no-copper zone around antenna +- **No vias**: No vias under or near the antenna +- **Ground plane**: Cut out ground plane in antenna area + +## Manufacturing Files + +```bash +# Generate Gerbers +tsci build --gerber + +# Generate BOM +tsci build --bom + +# Generate Assembly +tsci build --pick-and-place +``` + +## Cost Estimate + +| Component | Unit Cost | Qty | Total | +|-----------|-----------|-----|-------| +| ESP32-WROOM-32 | $2.50 | 1 | $2.50 | +| CH340G | $0.30 | 1 | $0.30 | +| AMS1117-3.3 | $0.15 | 1 | $0.15 | +| USB-C Receptacle | $0.15 | 1 | $0.15 | +| Crystals (×2) | $0.20 | 2 | $0.40 | +| Passives (×20) | $0.01 | 20 | $0.20 | +| PCB (2-layer) | $1.00 | 1 | $1.00 | +| **Total** | | | **$4.70** | + +## Summary + +You've designed a complete ESP32 development board covering: +- Power architecture with LDO regulation +- USB-C connectivity with CH340G programming +- Auto-reset circuit for seamless flashing +- Crystal oscillators for MCU timing +- PCB layout rules for WiFi performance +- Manufacturing file generation + +This board is ready for production and can be manufactured at any standard PCB fab house. diff --git a/docs/tutorials/i2c-environmental-sensor-module.mdx b/docs/tutorials/i2c-environmental-sensor-module.mdx new file mode 100644 index 0000000..79934c5 --- /dev/null +++ b/docs/tutorials/i2c-environmental-sensor-module.mdx @@ -0,0 +1,353 @@ +--- +title: Building an I2C Environmental Sensor Module Tutorial +description: Learn how to design a multi-sensor environmental monitoring module using tscircuit — BME280 (temp/humidity/pressure), CCS811 (CO2/VOC), I2C bus design, and enclosure considerations. +--- + +## Overview + +This tutorial covers designing a comprehensive environmental monitoring sensor module using tscircuit. You'll learn about I2C communication, multi-sensor integration, environmental sensing principles, and low-power design for battery-operated applications. + +import TscircuitIframe from "@site/src/components/TscircuitIframe" + +## Project Specifications + +| Parameter | Value | +|-----------|-------| +| Board Size | 25mm × 35mm | +| Power Supply | 3.3V regulated | +| Communication | I2C (SDA/SCL) | +| Sensors | BME280 + CCS811 | +| Interface | Qwiic/Stemma QT compatible | + +## Sensors Overview + +### BME280 (Bosch) + +Measures temperature, humidity, and barometric pressure: + +| Parameter | Range | Accuracy | +|-----------|-------|----------| +| Temperature | -40°C to +85°C | ±1°C | +| Humidity | 0-100% RH | ±3% | +| Pressure | 300-1100 hPa | ±1 hPa | + +### CCS811 (AMS) + +Measures carbon dioxide (CO2) and volatile organic compounds (VOCs): + +| Parameter | Range | Accuracy | +|-----------|-------|----------| +| eCO2 | 400-8192 ppm | ±50 ppm | +| TVOC | 0-1187 ppb | — | + +## Components + +| Ref | Part | Description | Footprint | +|-----|------|------------|-----------| +| U1 | BME280 | Temp/Humidity/Pressure | `lga-8` | +| U2 | CCS811 | CO2/VOC Sensor | `mlga-10` | +| U3 | AP2112-3.3 | 3.3V LDO regulator | `sot-23-5` | +| J1 | Qwiic Connector | I2C + Power | `jst-ph-4pin` | +| J2 | Optional Header | Breadboard pins | `pin_header_1x4` | +| C1 | Input capacitor | 10µF | `0805` | +| C2 | Output capacitor | 10µF | `0805` | +| R1 | I2C pull-up | 4.7kΩ | `0805` | +| R2 | I2C pull-up | 4.7kΩ | `0805` | +| LED1 | Power LED | Blue | `0805` | + +## Step 1: BME280 Sensor + +The BME280 uses an I2C interface with selectable address (0x76 or 0x77): + +```tsx + + +/* BME280 Pinout */ + + + + + /* I2C mode */ + /* Address 0x76 */ +``` + +### BME280 Mounting Considerations + +The BME280 should be mounted with the sensing element exposed to air: + +1. **Top side**: Keep the port hole unobstructed +2. **No conformal coating**: Over the sensor +3. **Isolation**: Separate from heated components + +## Step 2: CCS811 Sensor + +The CCS811 requires a burn-in period and periodic baseline resets: + +```tsx + + +/* CCS811 Pinout */ + + + + + /* Wake pin low */ + + /* Hardware reset */ +``` + +### CCS811 Environmental Considerations + +The CCS811 is sensitive to: +- **Temperature changes**: Allow 20 minutes warm-up +- **High humidity**: Can affect readings temporarily +- **Airflow**: Needs fresh air for accurate VOC measurements + +## Step 3: I2C Bus Design + +### Address Configuration + +```tsx +/* BME280: SDO grounded = 0x76 */ +/* CCS811: Addr pin = low = 0x5A */ + + + + + + + + +``` + +### I2C Pull-Up Resistor Selection + +| Bus Speed | Min R (mA) | Max R (kΩ) | +|-----------|------------|------------| +| 100kHz | 1kΩ | 10kΩ | +| 400kHz | 2kΩ | 4kΩ | +| 1MHz | 1kΩ | 2kΩ | + +We use 4.7kΩ for standard 100kHz operation with 2 sensors. + +## Step 4: Qwiic/Stemma QT Connector + +```tsx + + +/* Qwiic pinout: 1=GND, 2=3V3, 3=SDA, 4=SCL */ + + + + +``` + +## Step 5: Power Supply + +```tsx + + + + + + + + + + + + + +``` + +## Step 6: Power LED + +```tsx + + + + + + +``` + +## Complete Circuit + +```tsx +export default () => { + return ( + + {/* BME280 - Temp/Humidity/Pressure */} + + + {/* CCS811 - CO2/VOC */} + + + {/* 3.3V LDO */} + + + {/* Qwiic Connector */} + + + {/* Power LED */} + + + + {/* Bypass Capacitors */} + + + + ) +} +``` + + { + return ( + + + + + + + + + ) +} +`} /> + +## Arduino Code Example + +```cpp +#include +#include +#include "CCS811.h" + +Adafruit_BME280 bme; +CCS811 ccs811; + +void setup() { + Serial.begin(115200); + Wire.begin(); + + // Initialize BME280 + if (!bme.begin(0x76)) { + Serial.println("BME280 not found!"); + } + + // Initialize CCS811 + ccs811.begin(); +} + +void loop() { + // Read BME280 + float temp = bme.readTemperature(); + float hum = bme.readHumidity(); + float pres = bme.readPressure() / 100.0F; + + // Read CCS811 + ccs811.readData(); + int co2 = ccs811.geteCO2(); + int tvoc = ccs811.getTVOC(); + + Serial.print("Temp: "); Serial.print(temp, 1); Serial.println(" C"); + Serial.print("Humidity: "); Serial.print(hum, 1); Serial.println(" %"); + Serial.print("Pressure: "); Serial.print(pres, 1); Serial.println(" hPa"); + Serial.print("CO2: "); Serial.print(co2); Serial.println(" ppm"); + Serial.print("TVOC: "); Serial.print(tvoc); Serial.println(" ppb"); + + delay(1000); +} +``` + +## Python (Raspberry Pi) Example + +```python +import smbus2 +import bme280 +import ccs811 +import time + +bus = smbus2.SMBus(1) + +# Initialize BME280 +calibration_params = bme280.load_calibration_params(bus, 0x76) + +# Initialize CCS811 +sensor = ccs811.CCS811(bus, 0x5a) +time.sleep(1) # Wait for sensor to warm up + +while True: + # Read BME280 + data = bme280.read(bus, 0x76, calibration_params) + print(f"Temp: {data.temperature:.1f} C") + print(f"Humidity: {data.humidity:.1f} %") + print(f"Pressure: {data.pressure:.1f} hPa") + + # Read CCS811 + if sensor.data_ready: + print(f"CO2: {sensor.co2} ppm") + print(f"TVOC: {sensor.tvoc} ppb") + + time.sleep(1) +``` + +## Enclosure Design + +### Ventilation Requirements +- **Sensor area**: Include ventilation holes near sensors +- **Size**: Minimum 2mm diameter holes +- **Pattern**: Staggered pattern to prevent dust ingress +- **Location**: Bottom of enclosure for convection + +### Material Considerations +- **Avoid**: ABS plastic can outgas VOCs +- **Preferred**: Acrylic, aluminum, or ABS with outgassing period +- **Sealing**: Use silicone gaskets for weatherproofing + +## PCB Layout Guidelines + +### Sensor Placement +- **Keep sensors away from heat sources**: MCU, voltage regulator +- **Consider airflow**: Position sensors in natural airflow path +- **Separation**: Keep BME280 and CCS811 at least 5mm apart + +### Power Design +- **Low noise**: CCS811 is sensitive to supply noise +- **Decoupling**: Use ceramic capacitors near each sensor +- **Ground plane**: Solid ground under sensor area + +## Cost Estimate + +| Component | Unit Cost | Qty | Total | +|-----------|-----------|-----|-------| +| BME280 | $2.50 | 1 | $2.50 | +| CCS811 | $3.00 | 1 | $3.00 | +| AP2112-3.3 | $0.25 | 1 | $0.25 | +| Qwiic connector | $0.30 | 1 | $0.30 | +| Passives | $0.05 | 5 | $0.25 | +| PCB (2-layer) | $0.50 | 1 | $0.50 | +| **Total** | | | **$6.80** | + +## Summary + +You've designed a complete environmental sensor module covering: +- I2C communication with multiple sensors +- BME280 temperature, humidity, and pressure sensing +- CCS811 CO2 and VOC detection +- Qwiic/Stemma QT compatibility +- Power supply design with filtering +- Arduino and Python code examples +- Enclosure design for sensor accuracy + +This module is ready for integration into environmental monitoring projects, smart home systems, or air quality monitoring applications. diff --git a/docs/tutorials/usb-power-delivery-trigger-hat.mdx b/docs/tutorials/usb-power-delivery-trigger-hat.mdx new file mode 100644 index 0000000..6ad93f3 --- /dev/null +++ b/docs/tutorials/usb-power-delivery-trigger-hat.mdx @@ -0,0 +1,401 @@ +--- +title: Building a USB Power Delivery Trigger HAT Tutorial +description: Learn how to design a USB Power Delivery (PD) trigger module using tscircuit — FUSB302 PD controller, voltage negotiation, sink profiles, and power routing for Raspberry Pi projects. +--- + +## Overview + +This tutorial covers designing a USB Power Delivery trigger module that negotiates power from USB-C sources and provides regulated voltage to Raspberry Pi projects. You'll learn about USB PD protocols, sink negotiation, power path design, and current monitoring. + +import TscircuitIframe from "@site/src/components/TscircuitIframe" + +## Project Specifications + +| Parameter | Value | +|-----------|-------| +| Board Size | 25mm × 25mm | +| Input | USB-C PD (5V/9V/12V/15V/20V) | +| Output | 5V @ 3A or negotiated voltage | +| PD Controller | FUSB302BMPX | +| Protocol | USB Power Delivery 3.0 | + +## USB Power Delivery Basics + +USB PD allows devices to negotiate power delivery beyond the standard 5V: + +### Voltage Profiles + +| Profile | Voltage | Max Current | Typical Use | +|---------|---------|-------------|-------------| +| 0 | 5V | 3A | Standard USB | +| 1 | 9V | 3A | Tablets, quick charge | +| 2 | 12V | 3A | Laptops, monitors | +| 3 | 15V | 3A | Larger laptops | +| 4 | 20V | 5A | Docking stations | + +### Sink Request Example + +```cpp +// Request 20V @ 3A from PD source +PDO_t request[] = { + { .fixed: { .voltage = 5000, .max_current = 3000 } }, // 5V @ 3A fallback + { .fixed: { .voltage = 20000, .max_current = 3000 } }, // 20V @ 3A preferred +}; +``` + +## Components + +| Ref | Part | Description | Footprint | +|-----|------|------------|-----------| +| U1 | FUSB302BMPX | USB PD sink controller | `qfn-24` | +| U2 | MP2491C | 3.3V/5V buck converter | `qfn-16` | +| J1 | USB-C Receptacle | USB-C connector | `usb-c-16pin` | +| J2 | 40-pin Header | Raspberry Pi HAT compatible | `raspberry-pi-hat-40pin` | +| L1 | Power inductor | 10µH 4A | `srn6045` | +| C1 | Input capacitor | 10µF | `0805` | +| C2 | Output capacitor | 22µF | `0805` | +| C3 | Bypass cap | 100nF | `0805` | +| R1 | Current sense | 10mΩ | `1206` | +| R2-R3 | Voltage divider | 100k/100k | `0805` | +| LED1 | PD active | Yellow | `0805` | +| LED2 | Power good | Green | `0805` | + +## Step 1: FUSB302B PD Controller + +The FUSB302B handles all USB PD protocol communication: + +```tsx + + +/* USB-C CC pins for PD negotiation */ + + + +/* I2C interface to host MCU */ + + + +/* Power supply */ + + + + +/* Interrupt output */ + +``` + +### CC Pin Configuration + +USB-C uses CC pins for: +1. **Cable orientation detection**: Determines plug orientation +2. **PD negotiation**: Communicates power capabilities +3. **VConn**: Powers cable electronics (not used in sink) + +```tsx +/* CC1 and CC2 connect to USB-C receptacle CC pins */ +/* Rp (source terminator) is inside the USB-C connector */ +``` + +## Step 2: Buck Converter for 5V Regulation + +The MP2491C provides efficient 5V from higher PD voltages: + +```tsx + + + + +/* Input capacitor */ + + +/* Output capacitor */ + + + + + + + +``` + +## Step 3: USB-C Receptacle + +```tsx + + +/* Power pins */ + + + +/* CC pins for PD */ + + + +/* USB 2.0 data (not used for PD only) */ +/* D+ and D+ not needed for PD trigger */ +``` + +## Step 4: Voltage and Current Monitoring + +### Output Voltage Feedback + +```tsx + + + + + + +``` + +### Output Current Sensing + +```tsx + + + + +``` + +## Step 5: Status LEDs + +```tsx + + + + + + + + + /* PD active indicator */ + + + + /* Power good */ +``` + +## Step 6: Raspberry Pi Header + +```tsx + + +/* 5V power output */ + + + +/* Ground */ + + + +/* I2C for PD status */ + + + +/* GPIO for PD interrupt */ + +``` + +## Complete Circuit + +```tsx +export default () => { + return ( + + {/* FUSB302B PD Controller */} + + + {/* MP2491C Buck Converter */} + + + {/* USB-C Receptacle */} + + + {/* Power Inductor */} + + + {/* Capacitors */} + + + + {/* Status LEDs */} + + + + + + {/* Current Sense */} + + + ) +} +``` + + { + return ( + + + + + + + + + + + ) +} +`} /> + +## Firmware (Arduino Example) + +```cpp +#include +#include + +FUSB302 pd; +float voltage = 0; +float current = 0; + +void setup() { + Serial.begin(115200); + Wire.begin(); + + pd.begin(); + pd.setMessageCallback([](PDMessage msg) { + if (msg.type == PD_SOURCE_CAPABILITIES) { + // Received source capabilities + for (int i = 0; i < msg.num_pdos; i++) { + PDO_t pdo = msg.pdos[i]; + if (pdo.fixed.voltage == 20000) { // 20V available + // Request 20V @ 3A + pd.requestPower(20000, 3000); + break; + } + } + } + }); +} + +void loop() { + pd.processMessages(); + + // Read voltage and current + voltage = readVoltage(); + current = readCurrent(); + + Serial.print("Voltage: "); Serial.print(voltage / 1000, 2); Serial.println(" V"); + Serial.print("Current: "); Serial.print(current / 1000, 2); Serial.println(" A"); + + delay(1000); +} +``` + +## Python (Raspberry Pi) Example + +```python +import smbus2 +import time + +# FUSB302 I2C address +FUSB302_ADDR = 0x22 + +def init_pd(): + bus = smbus2.SMBus(1) + # Initialize FUSB302 + bus.write_byte_data(FUSB302_ADDR, 0x0B, 0x01) # Control register + bus.write_byte_data(FUSB302_ADDR, 0x0C, 0x03) # Power register + return bus + +def request_20v(bus): + # Send PD sink request for 20V @ 3A + # This is a simplified example - real implementation + # requires proper PD protocol handling + print("Requesting 20V from PD source...") + +def read_voltage(bus): + # Read voltage from ADC or PD controller + # Return voltage in millivolts + return 5000 + +def read_current(bus): + # Read current from ADC + # Return current in milliamps + return 0 + +bus = init_pd() +request_20v(bus) + +while True: + voltage = read_voltage(bus) + current = read_current(bus) + power = (voltage * current) / 1000000 + print(f"V: {voltage/1000:.2f}V | I: {current/1000:.2f}A | P: {power:.2f}W") + time.sleep(1) +``` + +## PCB Layout Guidelines + +### High-Current Paths +- **VBUS traces**: Minimum 1.5mm for 3A current +- **Ground plane**: Solid ground under entire board +- **Via stitching**: Multiple vias for current return + +### Thermal Management +- **Buck converter**: Large copper area for thermal pad +- **Inductor**: Keep away from temperature-sensitive components +- **LED placement**: Visible indicators away from heat sources + +### PD Signal Integrity +- **CC traces**: 0.2mm, keep short (< 20mm) +- **Decoupling**: 100nF near FUSB302 VBus pin +- **Ground reference**: Solid ground under PD controller + +## Cost Estimate + +| Component | Unit Cost | Qty | Total | +|-----------|-----------|-----|-------| +| FUSB302BMPX | $1.50 | 1 | $1.50 | +| MP2491C | $0.80 | 1 | $0.80 | +| USB-C Receptacle | $0.20 | 1 | $0.20 | +| Power Inductor | $0.30 | 1 | $0.30 | +| Passives (×8) | $0.02 | 8 | $0.16 | +| Capacitors (×3) | $0.05 | 3 | $0.15 | +| Current Sense | $0.10 | 1 | $0.10 | +| LEDs (×2) | $0.02 | 2 | $0.04 | +| PCB (2-layer) | $0.50 | 1 | $0.50 | +| **Total** | | | **$3.75** | + +## Summary + +You've designed a complete USB Power Delivery trigger module covering: +- USB PD 3.0 protocol and sink negotiation +- FUSB302B PD controller integration +- MP2491C buck converter for voltage regulation +- USB-C receptacle with CC pin management +- Current and voltage monitoring +- Status LED indicators +- Firmware examples for Arduino and Raspberry Pi + +This module enables Raspberry Pi projects to draw power from USB-C PD sources, allowing use of modern USB-C chargers and power banks for higher power applications.