diff --git a/docs/contributing/contributor-repository-map.md b/docs/contributing/contributor-repository-map.md new file mode 100644 index 00000000..1cd2f6b7 --- /dev/null +++ b/docs/contributing/contributor-repository-map.md @@ -0,0 +1,116 @@ +--- +title: Contributor Repository Map +description: Learn which tscircuit repository to contribute to based on the part of the ecosystem you want to improve. +sidebar_position: 4 +--- + +tscircuit is split across many focused repositories. This map helps you decide +where to open an issue or pull request when you want to improve a specific part +of the ecosystem. + +If you are new to tscircuit, start with +[Getting Started as a Contributor](./getting-started-as-a-contributor.md) first, +then use this page to choose the right repository for your change. + +## Start Here + +| Goal | Best repository | Good first contribution type | +| ------------------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| Add or fix a schematic symbol | [tscircuit/schematic-symbols](https://github.com/tscircuit/schematic-symbols) | Add missing symbols, fix pin labels, improve tests | +| Add or fix a PCB footprint generator | [tscircuit/footprinter](https://github.com/tscircuit/footprinter) | Add footprint strings, fix dimensions, add examples | +| Improve the local developer workflow | [tscircuit/cli](https://github.com/tscircuit/cli) | Fix command output, improve errors, add CLI options | +| Improve the website or online editor | [tscircuit/tscircuit.com](https://github.com/tscircuit/tscircuit.com) | Fix UI bugs, improve editor flows, polish onboarding | +| Fix circuit compilation behavior | [tscircuit/core](https://github.com/tscircuit/core) | Add failing tests, fix generated Circuit JSON, improve React component behavior | +| Update component prop definitions | [tscircuit/props](https://github.com/tscircuit/props) | Add prop types, clarify component APIs, improve validation | +| Improve generated SVG output | [tscircuit/circuit-to-svg](https://github.com/tscircuit/circuit-to-svg) | Fix schematic or PCB SVG rendering, add visual fixtures | +| Improve the data format itself | [tscircuit/circuit-json](https://github.com/tscircuit/circuit-json) | Clarify schemas, add fields, improve type coverage | + +## Core Circuit Model + +Use these repositories when your change affects how circuits are represented, +compiled, or validated. + +| Repository | Owns | Choose this repo when | +| ------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | +| [tscircuit/core](https://github.com/tscircuit/core) | React-to-circuit compilation, component behavior, board generation | A circuit compiles incorrectly, a React component produces wrong output, or generated schematics/PCBs are structurally wrong | +| [tscircuit/props](https://github.com/tscircuit/props) | Public prop definitions for tscircuit components | A component accepts the wrong props, a prop is missing, or API documentation generated from props is incomplete | +| [tscircuit/circuit-json](https://github.com/tscircuit/circuit-json) | The shared data format used between tools | The schema needs a new field, a type is unclear, or multiple tools disagree about valid Circuit JSON | + +Core changes usually need tests that show the exact input circuit and expected +Circuit JSON output. If you are unsure whether a bug belongs in `core` or +`circuit-json`, start from `core` when the problem appears while writing +tscircuit code. + +## Symbols, Footprints, and Electronic Parts + +Use these repositories when your change improves how real electronic parts are +described or rendered. + +| Repository | Owns | Choose this repo when | +| --------------------------------------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| [tscircuit/schematic-symbols](https://github.com/tscircuit/schematic-symbols) | Reusable schematic symbols | A symbol is missing, visually wrong, mislabeled, or has incorrect pin order | +| [tscircuit/footprinter](https://github.com/tscircuit/footprinter) | Text-based footprint generation | A footprint string should generate pads differently, support a new package, or reject invalid dimensions | +| [tscircuit/easyeda-converter](https://github.com/tscircuit/easyeda-converter) | Converting EasyEDA/JLCPCB data into tscircuit formats | Imported JLCPCB or EasyEDA parts produce incorrect tscircuit output | +| [tscircuit/kicad-component-converter](https://github.com/tscircuit/kicad-component-converter) | Converting KiCad components | KiCad symbols or footprints do not convert cleanly into tscircuit-compatible data | +| [tscircuit/jlcsearch](https://github.com/tscircuit/jlcsearch) | Searching JLCPCB parts and metadata | Search results, part metadata, or JLCPCB integration behavior is wrong | + +These are often the best repositories for first contributions because fixes can +be verified with small visual fixtures and examples. + +## Rendering and Viewers + +Use these repositories when the underlying circuit data is correct, but the +preview or exported visual output is wrong. + +| Repository | Owns | Choose this repo when | +| ----------------------------------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------- | +| [tscircuit/circuit-to-svg](https://github.com/tscircuit/circuit-to-svg) | SVG generation for schematics and PCBs | Circuit JSON is correct, but the generated SVG is misplaced, missing labels, or visually incorrect | +| [tscircuit/pcb-viewer](https://github.com/tscircuit/pcb-viewer) | Interactive PCB viewing React components | A PCB preview interaction, layer display, zoom, or rendered board view is wrong | +| [tscircuit/3d-viewer](https://github.com/tscircuit/3d-viewer) | 3D board previews | The 3D model, camera, rendering, or component placement in 3D is wrong | +| [tscircuit/runframe](https://github.com/tscircuit/runframe) | Embedded runnable tscircuit previews | A page or app needs to run and preview tscircuit code inside a React component | + +For rendering bugs, include a minimal Circuit JSON fixture or tscircuit snippet +plus a screenshot of the expected and actual output. + +## User-Facing Tools + +Use these repositories when your change affects how users create, edit, preview, +or share circuits. + +| Repository | Owns | Choose this repo when | +| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| [tscircuit/cli](https://github.com/tscircuit/cli) | Local commands such as project creation, development server, and package workflows | A local command fails, output is confusing, or project setup needs improvement | +| [tscircuit/tscircuit.com](https://github.com/tscircuit/tscircuit.com) | Main website, online editor, dashboard, and hosted user experience | A website flow, editor interaction, account page, or hosted circuit experience needs work | +| [tscircuit/runframe](https://github.com/tscircuit/runframe) | Embeddable runtime preview frame | A docs page, website, or external app needs a live tscircuit preview | + +If a bug appears both locally and on the website, check whether the same circuit +fails in the CLI. If it does, the root cause is often in `core`, `props`, or a +renderer. If it only fails on the website, start with `tscircuit.com`. + +## Importers, Exporters, and Autorouting + +Use these repositories when your change is about moving between tscircuit and +other electronics formats or tools. + +| Repository | Owns | Choose this repo when | +| --------------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [tscircuit/dsn-converter](https://github.com/tscircuit/dsn-converter) | DSN format conversion | DSN import or export output is wrong | +| [tscircuit/easyeda-converter](https://github.com/tscircuit/easyeda-converter) | EasyEDA and JLCPCB conversion | EasyEDA/JLCPCB source data converts incorrectly | +| [tscircuit/kicad-component-converter](https://github.com/tscircuit/kicad-component-converter) | KiCad conversion | KiCad component data does not map correctly into tscircuit | +| [tscircuit/autorouting](https://github.com/tscircuit/autorouting) | Routing algorithms and route generation experiments | Traces are routed poorly, a routing fixture fails, or an autorouter behavior needs improvement | + +Converter issues are easiest to review when the pull request includes the source +file, the current converted output, and the expected converted output. + +## How to Choose the Right Repository + +1. Reproduce the problem with the smallest possible circuit or input file. +2. Decide whether the issue is data, behavior, visual output, or user interface. +3. Use the tables above to pick the repository that owns that layer. +4. Search existing issues in that repository before opening a new one. +5. Include a minimal reproduction, screenshots when visual, and the expected + behavior. + +When in doubt, open the issue where the problem first becomes visible to users +and mention any lower-level repository you suspect. Maintainers can move the +discussion, but a clear reproduction makes the report useful immediately. diff --git a/docs/contributing/overview-of-projects.md b/docs/contributing/overview-of-projects.md index c13af95c..cf86b64b 100644 --- a/docs/contributing/overview-of-projects.md +++ b/docs/contributing/overview-of-projects.md @@ -4,17 +4,22 @@ sidebar_position: 2 description: Explore the key tscircuit repositories including core libraries, tools, and web components that power the ecosystem. --- +This page lists the major public repositories in the tscircuit ecosystem. If you +are choosing where to make a contribution, see the +[Contributor Repository Map](./contributor-repository-map.md) for a practical +guide to which repository owns each part of the project. + | 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/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/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) | diff --git a/docs/contributing/user-facing-tools.md b/docs/contributing/user-facing-tools.md new file mode 100644 index 00000000..b8a3ea0c --- /dev/null +++ b/docs/contributing/user-facing-tools.md @@ -0,0 +1,131 @@ +--- +title: User-Facing Tools +sidebar_position: 3 +description: Learn which tscircuit tools users interact with directly and where each tool fits in the design workflow. +--- + +tscircuit is made of several packages and applications, but most users only +need a small set of tools while designing, previewing, routing, importing, and +sharing circuit boards. + +## Tool Map + +| Tool | What users use it for | Where it fits | +| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------- | +| [tscircuit.com](https://tscircuit.com) | Writing circuits in the online editor, previewing boards, sharing snippets, and ordering prototypes | The primary browser-based product | +| [tsci CLI](https://github.com/tscircuit/cli) | Creating local projects, running a local preview server, exporting fabrication files, and publishing packages | Local development and automation | +| [RunFrame](https://github.com/tscircuit/runframe) | Embedding runnable tscircuit examples inside documentation, apps, and playgrounds | Interactive previews inside React apps | +| [PCB Viewer](https://github.com/tscircuit/pcb-viewer) | Displaying rendered PCB layers and inspecting board geometry | Board visualization | +| [3D Viewer](https://github.com/tscircuit/3d-viewer) | Showing a 3D preview of assembled boards | Mechanical and assembly review | +| [Autorouting.com](https://autorouting.com) | Routing traces automatically and experimenting with autorouting algorithms | Routing assistance | +| [JLCPCB Search](https://jlcsearch.tscircuit.com) | Finding JLCPCB parts and importing component data into a tscircuit project | Component sourcing | +| [Footprinter](https://github.com/tscircuit/footprinter) | Generating footprint definitions from compact footprint strings | Footprint authoring | +| [Converters](#converters) | Importing or exporting formats such as KiCad, EasyEDA, DSN, and Circuit JSON | Moving designs between ecosystems | + +## Online Editor + +The online editor at [tscircuit.com](https://tscircuit.com) is the fastest +place to try tscircuit. Users can edit TypeScript circuit code, preview the +schematic, PCB, and 3D assembly, then share the result as a snippet. + +Use the online editor when you want to: + +- Start a board without installing local tooling +- Share a minimal reproduction in an issue or discussion +- Import a template board or component and adjust it visually +- Download fabrication files for a prototype + +## Command Line + +The [`tsci`](https://github.com/tscircuit/cli) command line tool is the main +local workflow for tscircuit projects. It is useful when a board needs to live +in a repository, use multiple files, run in CI, or generate repeatable build +artifacts. + +Common commands include: + +| Command | Purpose | +| --------------------------- | --------------------------------------------------- | +| `tsci init` | Create a new tscircuit project | +| `tsci dev` | Start a local development server with live previews | +| `tsci build` | Build a project and generate artifacts | +| `tsci export` | Export fabrication files or other output formats | +| `tsci push` | Publish a package or project | +| `tsci add` / `tsci install` | Add packages, GitHub libraries, or KiCad libraries | + +## Embeddable Viewers + +tscircuit exposes viewer packages so other apps and docs can render circuit +outputs without rebuilding the whole editor. + +| Package | Use it when | +| ------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| [runframe](https://github.com/tscircuit/runframe) | You need an interactive code-and-preview frame, such as examples inside docs | +| [pcb-viewer](https://github.com/tscircuit/pcb-viewer) | You only need to render PCB layers from Circuit JSON | +| [3d-viewer](https://github.com/tscircuit/3d-viewer) | You need a 3D board or assembly preview | +| [circuit-to-svg](https://github.com/tscircuit/circuit-to-svg) | You need SVG output for schematics, PCBs, or documentation assets | + +These tools are usually fed by +[Circuit JSON](https://github.com/tscircuit/circuit-json), the intermediate +format produced by tscircuit. + +## Routing and Layout + +[Autorouting.com](https://autorouting.com) and the tscircuit autorouting +packages help users route traces automatically. This is useful for quick +iterations, early board layout, and reproducing autorouter bugs. + +When working on routing issues, include: + +- A link to the tscircuit snippet or project +- The Circuit JSON or minimal circuit code +- Screenshots of the problematic route +- Any expected constraints, such as board size, layer count, or keep-out areas + +## Parts and Footprints + +tscircuit has several tools for turning real-world parts into usable circuit +components. + +| Tool | Purpose | +| ------------------------------------------------------------------- | ------------------------------------------------------------ | +| [JLCPCB Search](https://jlcsearch.tscircuit.com) | Search JLCPCB components and use part data while designing | +| [footprinter](https://github.com/tscircuit/footprinter) | Generate footprints from concise footprint strings | +| [props](https://github.com/tscircuit/props) | Defines the supported React component props across tscircuit | +| [schematic-symbols](https://github.com/tscircuit/schematic-symbols) | Provides symbols used in schematic rendering | + +## Converters + +Converters help users move designs and component data between tscircuit and +other electronics tools. + +| Converter | Purpose | +| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| [kicad-component-converter](https://github.com/tscircuit/kicad-component-converter) | Convert KiCad component data for use in tscircuit | +| [easyeda-converter](https://github.com/tscircuit/easyeda-converter) | Convert EasyEDA and JLCPCB component data | +| [dsn-converter](https://github.com/tscircuit/dsn-converter) | Convert Specctra DSN files for routing and visualization workflows | +| [circuit-json](https://github.com/tscircuit/circuit-json) | Use the shared intermediate representation for rendered circuits | + +## Core Libraries + +Most users do not import core libraries directly unless they are building tools +around tscircuit. Contributors should still know where the main pieces live: + +| Repository | Role | +| --------------------------------------------------------- | -------------------------------------------------------------------- | +| [core](https://github.com/tscircuit/core) | Converts React component trees into Circuit JSON | +| [props](https://github.com/tscircuit/props) | Defines component prop types and shared schemas | +| [circuit-json](https://github.com/tscircuit/circuit-json) | Defines the output format used by viewers, exporters, and converters | +| [math-utils](https://github.com/tscircuit/math-utils) | Shared geometry and layout helpers | + +## Choosing the Right Tool + +| Goal | Start with | +| ---------------------------------- | --------------------------------------------------- | +| Try tscircuit for the first time | [tscircuit.com](https://tscircuit.com) | +| Build a real project locally | `tsci init` and `tsci dev` | +| Share a bug reproduction | A tscircuit snippet or a small GitHub repo | +| Preview a board inside another app | RunFrame, PCB Viewer, or 3D Viewer | +| Import a part from JLCPCB | JLCPCB Search or the EasyEDA converter | +| Debug routing | Autorouting.com plus a minimal Circuit JSON example | +| Contribute to the ecosystem | Start with the related repository in the tool map | diff --git a/docs/elements/connector.mdx b/docs/elements/connector.mdx index 8a5a60d3..bf775e1e 100644 --- a/docs/elements/connector.mdx +++ b/docs/elements/connector.mdx @@ -14,6 +14,9 @@ Connectors support: - Schematic pin styling and arrangement controls - Optional connector `standard` hints (currently `"usb_c"` and `"m2"`) +For a complete board-level example of the M.2 connector standard, see +[Using SparkFun MicroMod M.2 Connectors](../tutorials/using-sparkfun-micromod-m2-connectors.mdx). + import CircuitPreview from "@site/src/components/CircuitPreview" ## Standard Connector Example diff --git a/docs/tutorials/draw-any-letter-with-leds.mdx b/docs/tutorials/draw-any-letter-with-leds.mdx new file mode 100644 index 00000000..36808cf1 --- /dev/null +++ b/docs/tutorials/draw-any-letter-with-leds.mdx @@ -0,0 +1,241 @@ +--- +title: Draw Any Letter With LEDs +description: Build a reusable LedLetter component that lays out capital A-Z letters with 0603 LEDs and one resistor per LED. +--- + +import TscircuitIframe from "@site/src/components/TscircuitIframe" + +## Overview + +This tutorial shows how to create a reusable `LedLetter` component. The component +takes a capital letter, converts it into a 5 by 7 pixel font, and places one LED +for every lit pixel. + +The intended usage is: + +```tsx + +``` + +The component below supports capital `A` through `Z`, uses small SMD LEDs, and +adds one current-limiting resistor for every LED. The PCB layout is generated +from simple grid math, and the schematic is automatically spread into readable +rows so larger letters do not stack every LED and resistor in one place. + + + +const FONT: PixelFont = { + A: ["01110", "10001", "10001", "11111", "10001", "10001", "10001"], + B: ["11110", "10001", "10001", "11110", "10001", "10001", "11110"], + C: ["01111", "10000", "10000", "10000", "10000", "10000", "01111"], + D: ["11110", "10001", "10001", "10001", "10001", "10001", "11110"], + E: ["11111", "10000", "10000", "11110", "10000", "10000", "11111"], + F: ["11111", "10000", "10000", "11110", "10000", "10000", "10000"], + G: ["01111", "10000", "10000", "10011", "10001", "10001", "01111"], + H: ["10001", "10001", "10001", "11111", "10001", "10001", "10001"], + I: ["11111", "00100", "00100", "00100", "00100", "00100", "11111"], + J: ["00111", "00010", "00010", "00010", "10010", "10010", "01100"], + K: ["10001", "10010", "10100", "11000", "10100", "10010", "10001"], + L: ["10000", "10000", "10000", "10000", "10000", "10000", "11111"], + M: ["10001", "11011", "10101", "10101", "10001", "10001", "10001"], + N: ["10001", "11001", "10101", "10011", "10001", "10001", "10001"], + O: ["01110", "10001", "10001", "10001", "10001", "10001", "01110"], + P: ["11110", "10001", "10001", "11110", "10000", "10000", "10000"], + Q: ["01110", "10001", "10001", "10001", "10101", "10010", "01101"], + R: ["11110", "10001", "10001", "11110", "10100", "10010", "10001"], + S: ["01111", "10000", "10000", "01110", "00001", "00001", "11110"], + T: ["11111", "00100", "00100", "00100", "00100", "00100", "00100"], + U: ["10001", "10001", "10001", "10001", "10001", "10001", "01110"], + V: ["10001", "10001", "10001", "10001", "10001", "01010", "00100"], + W: ["10001", "10001", "10001", "10101", "10101", "10101", "01010"], + X: ["10001", "10001", "01010", "00100", "01010", "10001", "10001"], + Y: ["10001", "10001", "01010", "00100", "00100", "00100", "00100"], + Z: ["11111", "00001", "00010", "00100", "01000", "10000", "11111"], +} + +type Pixel = { + row: number + col: number +} + +const getPixelsForLetter = (letter: string): Pixel[] => { + const rows = FONT[letter.toUpperCase()] + if (!rows) { + throw new Error("LedLetter only supports capital A-Z letters") + } + + const pixels: Pixel[] = [] + rows.forEach((rowPattern, row) => { + rowPattern.split("").forEach((cell, col) => { + if (cell === "1") { + pixels.push({ row, col }) + } + }) + }) + + return pixels +} + +type LedLetterProps = { + letter: string + power: string + gnd: string + name?: string + pcbX?: number + pcbY?: number + schX?: number + schY?: number + pitch?: number + ledFootprint?: "0402" | "0603" + resistorFootprint?: "0402" | "0603" + resistance?: string +} + +export const LedLetter = ({ + letter, + power, + gnd, + name = "LEDLETTER", + pcbX = 0, + pcbY = 0, + schX = 0, + schY = 0, + pitch = 3, + ledFootprint = "0603", + resistorFootprint = "0603", + resistance = "1k", +}: LedLetterProps) => { + const pixels = getPixelsForLetter(letter) + const columns = 5 + const rows = 7 + const schematicColumns = 8 + + return ( + <> + {pixels.map(({ row, col }, index) => { + const componentNumber = index + 1 + const ledName = name + "_D" + componentNumber + const resistorName = name + "_R" + componentNumber + const ledPcbX = pcbX + (col - (columns - 1) / 2) * pitch + const ledPcbY = pcbY + ((rows - 1) / 2 - row) * pitch + const resistorPcbX = ledPcbX - pitch * 0.42 + const schematicX = schX + (index % schematicColumns) * 2 + const schematicY = schY - Math.floor(index / schematicColumns) * 1.4 + + return ( + + + + + + + + ) + })} + + ) +} + +export default () => ( + + + + + +) +`} /> + +## How the layout works + +The font is a small `Record` where each letter is seven rows +tall and five columns wide. Each `1` becomes an LED. Each `0` is left empty. + +For every lit pixel, the component calculates the PCB position like this: + +```ts +const ledPcbX = pcbX + (col - (columns - 1) / 2) * pitch +const ledPcbY = pcbY + ((rows - 1) / 2 - row) * pitch +``` + +That keeps the letter centered around `pcbX` and `pcbY`, regardless of which +letter is selected. Increasing `pitch` makes the letter larger. Decreasing it +makes the LEDs tighter. + +## Current limiting + +Every LED gets its own resistor: + +```tsx + + + +``` + +This makes the electrical path: + +```txt +power -> resistor -> LED -> ground +``` + +The default is a `1k` resistor and `0603` footprints for both the LED and the +resistor. You can switch to `0402` parts when you want a smaller, denser letter: + +```tsx + +``` + +## Reusing the component + +Use a different `name` for every instance so the generated component names stay +unique: + +```tsx + + +``` + +The same font map can be adjusted later if you want a more rounded or condensed +style. The placement math does not need to change because it only depends on the +row and column of each lit pixel. diff --git a/docs/tutorials/using-sparkfun-micromod-m2-connectors.mdx b/docs/tutorials/using-sparkfun-micromod-m2-connectors.mdx new file mode 100644 index 00000000..e89f65f9 --- /dev/null +++ b/docs/tutorials/using-sparkfun-micromod-m2-connectors.mdx @@ -0,0 +1,241 @@ +--- +title: Using SparkFun MicroMod M.2 Connectors +description: Document the MicroMod connector pins, carrier-board responsibilities, and tscircuit patterns for building boards around SparkFun MicroMod processor modules. +--- + +SparkFun MicroMod processor boards plug into a 75-position M.2 edge connector. +The connector lets you design one carrier board and swap processor modules, as +long as your carrier follows the MicroMod signal assignments and voltage rules. + +This guide shows how to model that connector in tscircuit, how to name the most +important nets, and what to check before routing a carrier board. + +## References + +Keep these SparkFun references open while you build a carrier: + +- [MicroMod interface pin descriptions](https://cdn.sparkfun.com/assets/learn_tutorials/1/2/0/6/SparkFun_MicroMod_Interface_v1.0_-_Pin_Descriptions.pdf) +- [MicroMod M.2 pinout](https://cdn.sparkfun.com/assets/learn_tutorials/1/2/0/6/SparkFun_MicroMod_Interface_v1.0_-_Pinout.pdf) +- [MicroMod graphical datasheet](https://cdn.sparkfun.com/assets/learn_tutorials/1/1/8/9/MicroMod_General_Pinout_v10_Graphical_Datasheet.pdf) +- [SparkFun MicroMod overview](https://www.sparkfun.com/micromod) +- [Getting started with MicroMod](https://learn.sparkfun.com/tutorials/getting-started-with-micromod) + +## Connector Model + +Use `` for the physical connector and add MicroMod +pin labels for the nets your carrier uses. You do not have to label every pin on +the first pass, but naming power, USB, reset, boot, and the buses you route makes +the design much easier to review. + +```tsx +export default () => ( + + + +); +``` + +The labels above follow the MicroMod pinout from the processor-board point of +view. In tscircuit, prefer net names that are legal identifiers and easy to +search, such as `USB_D_P` instead of `USB_D+`, `RESET_N` instead of `RESET#`, +and `3V3` instead of `3.3V`. + +## Carrier Board Responsibilities + +A MicroMod carrier board is not just a breakout. The carrier owns the physical +connectors, power input, pullups, and protection around the processor module. + +| Area | Carrier-board guidance | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| Main power | Provide a stable 3.3 V rail on `3V3` and route all `GND` pins to the ground return. | +| USB power | Route `USB_VIN` only where the processor module needs USB 5 V. Treat it as a USB 2.0 4.8-5.2 V input. | +| Enable | If you use `3V3_EN`, add the carrier-side pullup and clamp expected by the MicroMod spec. | +| RTC backup | `RTC_3V_BATT` is optional and may be left unconnected when your carrier does not provide a coin cell or backup battery. | +| Reset and boot | `RESET_N` and `BOOT` are open-drain active-low signals. Use momentary buttons to ground when you want physical reset or boot-mode controls. | +| I2C | Put I2C pullups on the carrier, because the spec describes the I2C lines as open drain with carrier-board pullups. | +| Analog inputs | Keep `A0`, `A1`, and battery sense signals inside the processor module's 0-3.3 V input range. | +| Differential USB | Route `USB_D_P` and `USB_D_N` as a matched pair and avoid long stubs. | + +## Routing Common Carrier Features + +### USB-C For Device USB + +Most MicroMod carriers expose USB for power, programming, or serial output. +Keep the USB connector close enough that `USB_D_P` and `USB_D_N` can route +cleanly. + +```tsx +export default () => ( + + + + + + + + + +); +``` + +### Reset And Boot Buttons + +Reset and boot are active-low, open-drain style signals. A simple carrier can +bring each one to a normally-open pushbutton that shorts the signal to ground. + +```tsx +export default () => ( + + + + + + + + + + + +); +``` + +### I2C Peripheral Bus + +The primary I2C bus is useful for sensors, displays, and carrier-board +peripherals. Add pullups on the carrier and connect peripheral pins to the +MicroMod `I2C_SDA` and `I2C_SCL` nets. + +```tsx +export default () => ( + + + + + + + + + + + + + +); +``` + +## Pin Planning Checklist + +Before you start routing, decide which MicroMod groups your carrier actually +needs. + +| Need | Prefer these MicroMod nets | +| --------------------------------- | ----------------------------------------------------------------------------- | +| USB device/programming | `USB_D_P`, `USB_D_N`, `USB_VIN`, `GND` | +| Debug/programming | `SWDIO`, `SWDCK`, `GND`, optionally `RESET_N` | +| Primary serial | `UART_TX1`, `UART_RX1`, optionally `UART_RTS1`, `UART_CTS1` | +| Sensors and low-speed peripherals | `I2C_SDA`, `I2C_SCL`, optionally `I2C_INT_N` | +| Fast peripherals | `SPI_COPI`, `SPI_CIPO`, `SPI_SCK`, `SPI_CS_N` | +| SDIO or secondary SPI | `SPI_SCK1`, `SPI_COPI1`, `SPI_CIPO1`, `SPI_CS1_N`, `SDIO_DATA1`, `SDIO_DATA2` | +| Audio or PDM microphone | `AUD_MCLK`, `AUD_OUT`, `AUD_IN`, `AUD_LRCLK`, `AUD_BCLK` | +| Camera-style signals | `CAM_MCLK`, `CAM_PCLK`, `CAM_HSYNC`, `CAM_VSYNC`, `CAM_TRIG` | +| Simple controls | `D0`, `D1`, `G0` through `G11`, `PWM0`, `PWM1` | +| Analog sensing | `A0`, `A1`, `BATT_VIN_DIV3` | + +Unused MicroMod pins can usually remain unconnected on the carrier, but avoid +reusing a pin for a different purpose than the MicroMod spec unless the +processor module explicitly supports that alternate function. + +## Review Checklist + +Before sending a MicroMod carrier for fabrication, check: + +- Every `3V3` and `GND` pin has a clear connection to the carrier power system. +- USB differential traces are short, paired, and not routed through unnecessary + vias. +- I2C pullups are present on the carrier when I2C is used. +- `RESET_N` and `BOOT` buttons pull to ground, not to 3.3 V. +- Analog inputs never exceed 3.3 V. +- The board outline and keepout around the M.2 connector leave room for the + MicroMod module to insert and sit flat. +- Optional signals such as RTC backup, secondary I2C, SDIO, audio, camera, and + CAN are only routed when the carrier actually supports them. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index f9d2099a..f82388aa 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -42,7 +42,7 @@ const config: Config = { docs: { sidebarPath: "./sidebars.ts", routeBasePath: "/", // Serve docs at root - editUrl: "https://github.com/tscircuit/docs/tree/main/", + editUrl: "https://github.com/tscircuit/docs/edit/main/", breadcrumbs: false, }, theme: { @@ -179,8 +179,8 @@ const config: Config = { }, { to: "https://blog.tscircuit.com", label: "Blog", position: "left" }, { - to: "https://tscircuit.com", - label: "Use Online", + to: "https://tscircuit.com/editor", + label: "Try Online", position: "left", }, diff --git a/src/theme/DocItem/Layout/styles.module.css b/src/theme/DocItem/Layout/styles.module.css index a89053ed..c9d64f1d 100644 --- a/src/theme/DocItem/Layout/styles.module.css +++ b/src/theme/DocItem/Layout/styles.module.css @@ -40,6 +40,9 @@ @media (min-width: 997px) { .docItemCol { - max-width: 75% !important; + flex: 0 1 1000px !important; + max-width: 1000px !important; + margin-left: auto; + margin-right: auto; } }