diff --git a/docs/contributing/overview-of-projects.md b/docs/contributing/overview-of-projects.md index c13af95c..177e204e 100644 --- a/docs/contributing/overview-of-projects.md +++ b/docs/contributing/overview-of-projects.md @@ -4,17 +4,57 @@ sidebar_position: 2 description: Explore the key tscircuit repositories including core libraries, tools, and web components that power the ecosystem. --- -| Repo | Description | Open Issues | -| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| [tscircuit/core](https://github.com/tscircuit/core) | Core library that powers tscircuit, handles conversion of React components into circuit boards | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/core)](https://github.com/tscircuit/core/issues) | -| [tscircuit/schematic-symbols](https://github.com/tscircuit/schematic-symbols) | Library of schematic symbols used across tscircuit | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/schematic-symbols)](https://github.com/tscircuit/schematic-symbols/issues) | -| [tscircuit/footprinter](https://github.com/tscircuit/footprinter) | Generates PCB footprints from string descriptions | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/footprinter)](https://github.com/tscircuit/footprinter/issues) | -| [tscircuit/circuit-to-svg](https://github.com/tscircuit/circuit-to-svg) | Converts Circuit JSON into SVG files | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/circuit-to-svg)](https://github.com/tscircuit/circuit-to-svg/issues) | -| [tscircuit/circuit-json](https://github.com/tscircuit/circuit-json) | Underlying assembly language format that represents tscircuit circuits | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/circuit-json)](https://github.com/tscircuit/circuit-json/issues) | -| [tscircuit/tscircuit.com](https://github.com/tscircuit/tscircuit.com) | Main website and circuit board editor | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/tscircuit.com)](https://github.com/tscircuit/tscircuit.com/issues) | -| [tscircuit/cli](https://github.com/tscircuit/cli) | Main development tool for tscircuit, provides local development server and package management | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/cli)](https://github.com/tscircuit/cli/issues) | -| [tscircuit/runframe](https://github.com/tscircuit/runframe) | React component to preview and run tscircuit circuits | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/runframe)](https://github.com/tscircuit/runframe/issues) | -| [tscircuit/pcb-viewer](https://github.com/tscircuit/pcb-viewer) | React component for viewing PCBs | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/pcb-viewer)](https://github.com/tscircuit/pcb-viewer/issues) | -| [tscircuit/3d-viewer](https://github.com/tscircuit/3d-viewer) | React component for viewing 3D previews | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/3d-viewer)](https://github.com/tscircuit/3d-viewer/issues) | -| [tscircuit/props](https://github.com/tscircuit/props) | Specification for the definitions of every React component supported by tscircuit | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/props)](https://github.com/tscircuit/props/issues) | -| [tscircuit/easyeda-converter](https://github.com/tscircuit/easyeda-converter) | Command line utility for converting JLCPCB footprints to tscircuit | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/easyeda-converter)](https://github.com/tscircuit/easyeda-converter/issues) | +tscircuit is spread across many focused repositories. This page groups them by +area so you can quickly find where to contribute. + +## Core Libraries + +These repos form the foundation that everything else builds on. + +| Repo | Description | Open Issues | +| ---- | ----------- | ----------- | +| [tscircuit/core](https://github.com/tscircuit/core) | Core library — converts React components into Circuit JSON (schematic, PCB, BOM) | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/core)](https://github.com/tscircuit/core/issues) | +| [tscircuit/circuit-json](https://github.com/tscircuit/circuit-json) | The intermediate "assembly language" format all tscircuit tools share | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/circuit-json)](https://github.com/tscircuit/circuit-json/issues) | +| [tscircuit/props](https://github.com/tscircuit/props) | TypeScript type definitions and prop specs for every tscircuit React component | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/props)](https://github.com/tscircuit/props/issues) | + +## Rendering & Viewers + +These repos turn Circuit JSON into visual output (SVG, React viewers, 3D). + +| Repo | Description | Open Issues | +| ---- | ----------- | ----------- | +| [tscircuit/circuit-to-svg](https://github.com/tscircuit/circuit-to-svg) | Converts Circuit JSON into schematic and PCB SVG images | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/circuit-to-svg)](https://github.com/tscircuit/circuit-to-svg/issues) | +| [tscircuit/schematic-symbols](https://github.com/tscircuit/schematic-symbols) | SVG schematic symbols library (resistors, capacitors, ICs, …) used by circuit-to-svg | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/schematic-symbols)](https://github.com/tscircuit/schematic-symbols/issues) | +| [tscircuit/pcb-viewer](https://github.com/tscircuit/pcb-viewer) | React component for interactive PCB viewing | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/pcb-viewer)](https://github.com/tscircuit/pcb-viewer/issues) | +| [tscircuit/3d-viewer](https://github.com/tscircuit/3d-viewer) | React component for 3D PCB and component previews | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/3d-viewer)](https://github.com/tscircuit/3d-viewer/issues) | +| [tscircuit/runframe](https://github.com/tscircuit/runframe) | React component that runs tscircuit code and shows live schematic/PCB/3D previews | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/runframe)](https://github.com/tscircuit/runframe/issues) | + +## Autorouting + +| Repo | Description | Open Issues | +| ---- | ----------- | ----------- | +| [tscircuit/autorouting](https://github.com/tscircuit/autorouting) | Collection of PCB autorouting algorithms (IjumpAstar, MultilayerIjump, …) | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/autorouting)](https://github.com/tscircuit/autorouting/issues) | + +## Component Libraries & Footprints + +| Repo | Description | Open Issues | +| ---- | ----------- | ----------- | +| [tscircuit/footprinter](https://github.com/tscircuit/footprinter) | Generates PCB footprints from concise string descriptions (e.g. `"soic8"`) | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/footprinter)](https://github.com/tscircuit/footprinter/issues) | +| [tscircuit/easyeda-converter](https://github.com/tscircuit/easyeda-converter) | Imports EasyEDA/JLCPCB component data and converts it to tscircuit footprints | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/easyeda-converter)](https://github.com/tscircuit/easyeda-converter/issues) | +| [tscircuit/jlcsearch](https://github.com/tscircuit/jlcsearch) | Searchable JLCPCB component database with REST API | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/jlcsearch)](https://github.com/tscircuit/jlcsearch/issues) | + +## Developer Tools & Web Apps + +| Repo | Description | Open Issues | +| ---- | ----------- | ----------- | +| [tscircuit/tscircuit.com](https://github.com/tscircuit/tscircuit.com) | Main web editor at tscircuit.com — share and publish circuit snippets | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/tscircuit.com)](https://github.com/tscircuit/tscircuit.com/issues) | +| [tscircuit/cli](https://github.com/tscircuit/cli) | Local development CLI — `tsci dev` spins up a live-reload circuit preview server | [![GitHub issues](https://img.shields.io/github/issues/tscircuit/cli)](https://github.com/tscircuit/cli/issues) | + +## Where to Start + +- **Fix a bug in schematic rendering** → [circuit-to-svg](https://github.com/tscircuit/circuit-to-svg) or [schematic-symbols](https://github.com/tscircuit/schematic-symbols) +- **Add a missing component prop** → [props](https://github.com/tscircuit/props) then [core](https://github.com/tscircuit/core) +- **Improve the PCB viewer UI** → [pcb-viewer](https://github.com/tscircuit/pcb-viewer) +- **Add a footprint** → [footprinter](https://github.com/tscircuit/footprinter) +- **Work on autorouting algorithms** → [autorouting](https://github.com/tscircuit/autorouting) +- **New to tscircuit?** → [getting-started-as-a-contributor](./getting-started-as-a-contributor.md) diff --git a/docs/tutorials/esp32-module-schematic.mdx b/docs/tutorials/esp32-module-schematic.mdx new file mode 100644 index 00000000..09d54536 --- /dev/null +++ b/docs/tutorials/esp32-module-schematic.mdx @@ -0,0 +1,404 @@ +--- +title: ESP32 WiFi Module Reference Schematic +description: >- + Build a complete ESP32-WROOM-32 reference schematic using tscircuit. Covers + the module, USB-UART bridge, power regulation, and programming interface. +--- + +## Overview + +In this tutorial, we will design a **schematic-only** reference circuit for an +**ESP32-WROOM-32** based WiFi development board. This is the same class of +circuit found on popular ESP32 devkits like the NodeMCU-ESP32 and ESP-WROVER-KIT. + +The schematic includes: +- **ESP32-WROOM-32 module** (the core WiFi/BT SoC + antenna) +- **CH340C USB-UART bridge** for programming over USB +- **USB Type-C connector** for power and serial communication +- **AMS1117-3.3 LDO regulator** to drop USB 5V to 3.3V +- **Reset (EN) and Boot (IO0) buttons** for the standard Espressif programming sequence +- **Decoupling capacitors** on all power rails + +All JLCPCB part numbers are chosen to use components readily available from their +Basic/Extended parts library. + +We use `routingDisabled` throughout so this tutorial stays focused on the +schematic logic — no PCB layout is required. + +--- + +## Bill of Materials + +| Ref | Part | Description | JLCPCB# | +|-----|------|-------------|---------| +| U1 | ESP32-WROOM-32 | WiFi+BT module, 38-pin | C95209 | +| U2 | CH340C | USB-UART bridge, SOP-16 | C84681 | +| U3 | AMS1117-3.3 | 3.3V LDO, SOT-223 | C6186 | +| J1 | USB-C 2.0 | Power + data connector | C165948 | +| SW1 | 3x4x2mm tactile | EN (reset) button | C318884 | +| SW2 | 3x4x2mm tactile | IO0 (boot) button | C318884 | +| C1–C4 | 100nF 0402 | Decoupling caps | C307331 | +| C5 | 10µF 0805 | Bulk cap, USB input | C15850 | +| C6 | 10µF 0805 | Bulk cap, 3.3V rail | C15850 | +| R1 | 10kΩ 0402 | EN pull-up | C25744 | +| R2 | 10kΩ 0402 | IO0 pull-up | C25744 | + +--- + +## Schematic Design + +import TscircuitIframe from "@site/src/components/TscircuitIframe" + + { + return ( + + + {/* ── ESP32-WROOM-32 module ─────────────────────────────────── */} + + + {/* ── CH340C USB-UART Bridge ────────────────────────────────── */} + + + {/* ── AMS1117-3.3 LDO Regulator ────────────────────────────── */} + + + {/* ── USB-C Connector ───────────────────────────────────────── */} + + + {/* ── EN (Reset) Button ─────────────────────────────────────── */} + + + {/* ── IO0 (Boot) Button ─────────────────────────────────────── */} + + + {/* ── EN pull-up (R1: 10k) ──────────────────────────────────── */} + + + {/* ── IO0 pull-up (R2: 10k) ─────────────────────────────────── */} + + + {/* ── Decoupling caps on 3V3 rail ───────────────────────────── */} + + + + {/* ── Bulk cap on 3V3 output ────────────────────────────────── */} + + + {/* ── Decoupling caps on CH340C ─────────────────────────────── */} + + + + {/* ── Bulk cap on USB 5V input ──────────────────────────────── */} + + + {/* ── Power net connections ─────────────────────────────────── */} + {/* USB-C power in */} + + + + {/* LDO: 5V in, 3.3V out */} + + + + + {/* ESP32 power */} + + + + + + {/* CH340C power */} + + + + {/* USB data lines: USB-C → CH340C */} + + + + {/* Serial crossover: CH340C TX → ESP32 RX, CH340C RX → ESP32 TX */} + + + + {/* Auto-reset wiring: DTR/RTS → EN/IO0 via transistors (simplified) */} + + + + + ) +} +`} /> + +--- + +## How It Works + +### Power Supply Chain + +``` +USB-C (5V) ──► AMS1117-3.3 (LDO) ──► 3.3V rail ──► ESP32 + CH340C +``` + +The USB-C connector provides 5V from the host computer. The AMS1117-3.3 LDO +regulator drops this to the 3.3V required by the ESP32 module and CH340C chip. +Bulk capacitors (C5 on 5V, C6 on 3.3V) stabilize each rail; small 100nF +decoupling caps (C1–C4) sit close to each IC power pin to suppress high-frequency noise. + +### USB-to-Serial Programming + +The **CH340C** (U2) acts as a bridge between the USB 2.0 full-speed data lines +and the ESP32's UART0 (`TXD0`/`RXD0`). The cross-wired connection is intentional: +the CH340C's `TXD` (transmit) goes to the ESP32's `RXD0` (receive), and vice versa. + +### Reset and Boot Sequence + +Espressif modules enter **bootloader mode** by: +1. Pulling `IO0` (GPIO0) LOW before reset +2. Releasing the `EN` (chip-enable / reset) line HIGH + +This is normally automated via the CH340C's `DTR#` and `RTS#` signals and a pair +of NPN transistors (omitted here for schematic clarity — see +[Espressif's auto-download circuit](https://docs.espressif.com/projects/esptool/en/latest/esp8266/reference/reset-sequence.html) +for the full circuit). + +The manual buttons `SW1` (EN) and `SW2` (IO0) let you trigger this sequence by +hand: +1. Hold SW2 (IO0) to pull GPIO0 low +2. Press and release SW1 (EN) to reset the chip +3. Release SW2 — ESP32 starts in download mode + +Pull-up resistors R1 and R2 (10kΩ each) ensure both lines default HIGH when +the buttons are released. + +### ESP32-WROOM-32 Module + +The WROOM-32 is a **complete module** — it integrates the bare ESP32 SoC, 4MB +of SPI flash, a PCB antenna, RF matching network, and shielding can. You connect +only the functional I/O pins you need; the module handles the RF side internally. + +Key pins to be aware of: + +| Pin | Function | +|-----|----------| +| `EN` | Active-high chip enable / reset (pull HIGH, button to GND) | +| `IO0 (GPIO0)` | Boot mode select; LOW during reset enters bootloader | +| `TXD0 / RXD0` | UART0 — primary serial console and firmware download port | +| `3V3` | 3.3V power input | +| `GND` | Ground (multiple pins, all must be connected) | + +--- + +## Extending the Design + +Once the basic schematic is working you can add: + +- **Status LED** — a 3.3V-tolerant LED + series resistor on any GPIO (e.g. GPIO2, which is the + onboard LED on most NodeMCU boards) +- **Battery charger** — a TP4056-based LiPo charger feeding the 3.7V battery into the 5V rail + through a boost converter +- **Sensor headers** — I²C (GPIO21/22) or SPI (GPIO18/19/23) pin headers for adding external + sensors without reflowing the board +- **Auto-reset circuit** — NPN transistors (BC817/MMBT3904) on `DTR#` and `RTS#` to + automate bootloader entry from `esptool` + +--- + +## Resources + +- [ESP32-WROOM-32 Datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_en.pdf) +- [CH340C Datasheet](https://www.wch-ic.com/downloads/CH340DS1_PDF.html) +- [AMS1117 Datasheet](http://www.advanced-monolithic.com/pdf/ds1117.pdf) +- [Espressif Programming Guide — Boot Mode](https://docs.espressif.com/projects/esptool/en/latest/esp8266/reference/reset-sequence.html) +- [JLCPCB Part: C95209 (ESP32-WROOM-32)](https://jlcpcb.com/parts/componentSearch?searchTxt=C95209)