Skip to content

Complete the USB Flashlight tutorial (fixes #555) #597

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pxtung299-bot wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Complete the USB Flashlight tutorial (fixes #555) #597

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
270 changes: 232 additions & 38 deletions docs/tutorials/building-a-simple-usb-flashlight.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,42 +1,236 @@
---
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"

<TscircuitIframe defaultView="3d" code={`

import { SmdUsbC } from "@tsci/seveibar.smd-usb-c"

export default () => {
return (
<board width="12mm" height="30mm">
<SmdUsbC
description: Learn how to build a USB-powered LED flashlight PCB using tscircuit, step by step.
---

# Building a Simple USB Flashlight

In this tutorial we will design a USB-powered LED flashlight as a printed circuit board (PCB).
By the end you will have a complete, working schematic and PCB layout that you can send straight
to a board house.

This is a great first project because it uses only three components and introduces the core
tscircuit elements you will use in almost every design: a connector, a resistor, and an LED.

---

## What You Will Build

A tiny PCB that plugs into any USB-A port. The 5 V supply from the USB bus powers a white LED
through a current-limiting resistor. No firmware, no microcontroller — just light.

**Components**

| Part | Value / Part | tscircuit element |
|------|-------------|-------------------|
| USB-A connector (male) | USB-A through-hole | `<connector />` |
| Current-limiting resistor | 68 Ω, 0402 | `<resistor />` |
| White LED | Generic 0402 white | `<led />` |

---

## How the Circuit Works

USB supplies 5 V on pin 1 (VBUS) and ground on pin 4 (GND).

A white LED typically has a forward voltage (V_f) of about 3.0 V–3.4 V and wants roughly
20 mA of current. We choose R so that:

```
R = (V_supply − V_f) / I_led
R = (5 V − 3.2 V) / 0.020 A
R ≈ 90 Ω → use standard value 68 Ω (gives ~26 mA, fine for a bright flash)
```

The circuit is simply: **VBUS → R1 → LED anode → LED cathode → GND**.

---

## Step 1 — Create a New Project

If you haven't installed tscircuit yet, follow the [Quickstart CLI guide](../intro/quickstart-cli)
or use the [online editor](https://tscircuit.com) to follow along in your browser.

```bash
tsci init usb-flashlight
cd usb-flashlight
tsci dev
```

Open `lib/MyCircuit.tsx` in your editor. You will see a blank board template.

---

## Step 2 — Add the USB Connector

A USB-A male connector exposes four pins. We only need **pin 1 (VBUS, +5 V)** and
**pin 4 (GND)**. In tscircuit we declare it with `<connector />` and assign net labels
to the pins we care about:

```tsx
import { connector, resistor, led, board, trace } from "@tscircuit/core"

export default () => (
<board width="20mm" height="15mm">
<connector
name="J1"
footprint="usb_a_male_th"
pinLabels={{
pin1: "VBUS",
pin4: "GND",
}}
pcbX={-7}
pcbY={0}
/>
</board>
)
```

> **Tip:** `footprint="usb_a_male_th"` selects a through-hole USB-A male footprint from the
> built-in footprint library. You can browse available footprints at
> [tscircuit.com/footprints](https://tscircuit.com).

After saving, you should see the connector appear on the PCB preview in your browser.

---

## Step 3 — Add the Current-Limiting Resistor

Place a 68 Ω 0402 resistor to the right of the connector. Its left pin (`pin1`) will connect
to VBUS, and its right pin (`pin2`) will go to the LED:

```tsx
<resistor
name="R1"
resistance="68"
footprint="0402"
pcbX={0}
pcbY={0}
/>
```

---

## Step 4 — Add the LED

Place a 0402 white LED to the right of the resistor. The **anode** (`pin1`) connects to R1,
and the **cathode** (`pin2`) connects to GND:

```tsx
<led
name="LED1"
color="white"
footprint="0402"
pcbX={7}
pcbY={0}
/>
```

---

## Step 5 — Connect the Components with Traces

Now wire everything together. tscircuit traces are declared by listing the net path using
dot notation `ComponentName.pinLabel`:

```tsx
{/* VBUS from USB connector pin 1 to resistor pin 1 */}
<trace from="J1.VBUS" to="R1.pin1" />

{/* R1 pin 2 to LED anode */}
<trace from="R1.pin2" to="LED1.pin1" />

{/* LED cathode back to GND on USB connector pin 4 */}
<trace from="LED1.pin2" to="J1.GND" />
```

---

## Full Circuit Code

Putting it all together:

```tsx
import { connector, resistor, led, board, trace } from "@tscircuit/core"

export default () => (
<board width="20mm" height="15mm">
{/* USB-A Male Connector */}
<connector
name="J1"
connections={{ GND1: "net.GND", GND2: "net.GND", VBUS1: "net.VBUS", VBUS2: "net.VBUS" }}
pcbY={-10}
schX={-4}
footprint="usb_a_male_th"
pinLabels={{
pin1: "VBUS",
pin4: "GND",
}}
pcbX={-7}
pcbY={0}
/>

{/* 68 Ω current-limiting resistor */}
<resistor
name="R1"
resistance="68"
footprint="0402"
pcbX={0}
pcbY={0}
/>
<pushbutton
name="SW1"
footprint="pushbutton"
layer="top"
connections={{ pin1: ".R1 > .pos", pin2: "net.VBUS" }}
pcbX={0}
pcbY={-1}
/>
<led name="LED" color="red" footprint="0603" pcbY={12} />

<resistor name="R1" footprint="0603" resistance="1k" pcbY={7} />
<trace from=".R1 .neg" to=".LED .pos" />
<trace from=".LED .neg" to="net.GND" />
</board>
)
}
`} />

{/* White LED */}
<led
name="LED1"
color="white"
footprint="0402"
pcbX={7}
pcbY={0}
/>

{/* Traces */}
<trace from="J1.VBUS" to="R1.pin1" />
<trace from="R1.pin2" to="LED1.pin1" />
<trace from="LED1.pin2" to="J1.GND" />
</board>
)
```

---

## Step 6 — Preview and Verify

The `tsci dev` server shows three tabs: **Schematic**, **PCB**, and **3D**.

Check the following:

- **Schematic**: The net from J1 pin 1 flows through R1 and then through LED1 to GND. No
unconnected pins ("ratsnest" lines) should remain.
- **PCB**: All three components fit within the 20 × 15 mm board outline. All traces are routed
(no airwires).
- **3D**: The USB connector overhangs the board edge slightly — this is normal for a plug-style
connector.
If you see any ratsnest (unrouted) lines, double-check the `from` / `to` pin names in your
`<trace />` elements.

---

## Step 7 — Export and Order

When you are happy with the design, export Gerber files for fabrication:

```bash
tsci export --format gerber
```

The files land in `./output/gerbers/`. Zip the folder and upload it to your preferred PCB
manufacturer (JLCPCB, PCBWay, OSH Park, etc.). A standard 5-board run of this simple design
typically costs under $5 including shipping.

---

## What's Next?

- Add a push-button switch between VBUS and R1 to turn the light on and off
(`<pushbutton />` element).
- Swap the single LED for three LEDs in parallel (each with its own 100 Ω resistor) for a
brighter beam.
- Try the [Building a 3×5 LED Matrix](./building-led-matrix) tutorial to scale up to a full
dot-matrix display.