velxio/docs/wiki/component-datasheets.md

# Component Datasheets (Hover Panel)

How to author the Markdown "datasheet" files that show up in the floating
panel when you hover a component in the **Add Component** picker.

This is a **manual, content-only** task: you drop a `.md` file in the right
folder and it appears on hover. No build step, no code changes, no
regeneration.

---

## Table of Contents

1. [What this is](#what-this-is)
2. [TL;DR](#tldr)
3. [Where the files live & how they are named](#where-the-files-live--how-they-are-named)
4. [Finding a component's `id`](#finding-a-components-id)
5. [Front-matter: brand & buy link](#front-matter-brand--buy-link)
6. [The Markdown body](#the-markdown-body)
7. [What the panel shows (doc vs metadata)](#what-the-panel-shows-doc-vs-metadata)
8. [Full annotated example](#full-annotated-example)
9. [Step-by-step: add a datasheet](#step-by-step-add-a-datasheet)
10. [Writing tips](#writing-tips)
11. [File reference](#file-reference)
12. [Appendix: component checklist](#appendix-component-checklist)

---

## What this is

When you hover a card in the component picker, a floating "datasheet" panel
appears next to it. It has two data sources:

- **Auto-generated metadata** (name, category, pin count, default properties,
  tags) — always present, comes from `components-metadata.json`.
- **A hand-authored Markdown datasheet** (optional) — the richer prose,
  pinout table, wiring tips, plus the component **brand** and a **Buy** link.

This page is about that second part. If a component has no datasheet file, the
panel still works — it just falls back to the thin auto-generated description.

---

## TL;DR

Create one file:

```
frontend/src/components/component-docs/<category>/<id>.md
```

```markdown
---
brand: Aosong (AM2302)
buy: https://www.example.com/product/dht22
---
Short overview of what the part is and how it works.

| Pin | Role |
| --- | --- |
| VCC | 3.3–5 V supply |
| DATA | single-wire data (needs pull-up) |
| GND | ground |

- A couple of **spec** bullets.

**Tip:** one practical wiring hint.
```

Save, refresh the editor, hover the card. Done.

---

## Where the files live & how they are named

```
frontend/src/components/
└── component-docs/
    ├── README.md            ← short in-repo reminder of this format
    ├── sensors/
    │   ├── hc-sr04.md
    │   └── dht22.md
    ├── output/
    │   └── led.md
    ├── input/
    │   ├── potentiometer.md
    │   └── pushbutton.md
    └── displays/
        └── ssd1306.md
```

Two rules:

1. **The file name must be `<id>.md`** where `<id>` is the component's id
   from the metadata (see [below](#finding-a-components-id)). This is the only
   thing that links a doc to a component. `hc-sr04.md` → the `hc-sr04`
   component.

2. **The `<category>` folder is just for tidiness.** The loader matches docs
   by file name and *ignores the folder*, so moving `led.md` from `output/` to
   `misc/` would not break the link. Still, please file each doc under the
   component's own category so the tree stays navigable:

   | Folder | Category |
   | --- | --- |
   | `analog/` | Analog (diodes, transistors, op-amps, regulators, batteries…) |
   | `boards/` | Boards |
   | `displays/` | Displays (LCD, OLED, ePaper, TFT) |
   | `electromech/` | Electromechanical (relays, motor drivers) |
   | `input/` | Input (buttons, pots, switches, keypads, encoders) |
   | `logic/` | Logic (gates, flip-flops, 74HC ICs, custom chips) |
   | `motors/` | Motors (servo, stepper, drivers) |
   | `other/` | Other (7-seg, joystick, RTC, NeoPixel matrix…) |
   | `output/` | Output (LED, RGB LED, buzzer, bar graph) |
   | `passive/` | Passive (resistors, capacitors, inductors, IR) |
   | `sensors/` | Sensors |

> There is no `communication/` folder in use yet; if you document an I²C/SPI
> part that is categorised as `communication`, create the folder to match.

---

## Finding a component's `id`

The `id` is **not** the display name — it is the stable slug in the metadata.
Two easy ways to find it:

**A. Search the metadata file.** Open
`frontend/public/components-metadata.json` and search for the display name; the
`"id"` field next to it is what you want:

```json
{
  "id": "hc-sr04",
  "tagName": "wokwi-hc-sr04",
  "name": "HC-SR04",
  "category": "sensors"
}
```

**B. Use the checklist** at the [bottom of this page](#appendix-component-checklist),
which lists every component's id grouped by category (and marks the ones that
already have a datasheet).

Ids are lowercase-kebab. A few examples:

| Display name | `id` | File |
| --- | --- | --- |
| LED | `led` | `output/led.md` |
| HC-SR04 | `hc-sr04` | `sensors/hc-sr04.md` |
| 2N2222 (NPN BJT) | `bjt-2n2222` | `analog/bjt-2n2222.md` |
| Resistor 10 kΩ | `resistor-10k` | `passive/resistor-10k.md` |
| SSD1306 OLED (I2C) | `ssd1306-i2c` | `displays/ssd1306-i2c.md` |

---

## Front-matter: brand & buy link

A doc may start with a small `---`-delimited block giving the manufacturer and
a purchase URL. **Both fields are optional.** When present, the panel shows a
`by <brand>` line under the title and a **Buy** button in the footer.

```markdown
---
brand: Aosong (AM2302)
buy: https://www.example.com/product/dht22
---
Body starts on the line after the closing ---.
```

Rules:

- `brand` — plain text (manufacturer / brand / part family).
- `buy` — **must be `http://` or `https://`**. Any other scheme (e.g.
  `javascript:`) is ignored for safety and the button won't render.
- The closing `---` must be on its own line.
- If you omit the whole block, the file is treated as pure Markdown body.

> The seeded docs use vendor **search** URLs (e.g. an Amazon search) as
> placeholders. Replace them with the real product page or your affiliate link.

---

## The Markdown body

Everything after the front-matter is rendered with **GitHub-Flavoured
Markdown** (via `react-markdown` + `remark-gfm`). Supported:

- **Bold**, `inline code`, and links.
- Bullet and numbered lists.
- **Tables** (great for pinouts).
- Headings (`##`), blockquotes.

**Not** supported (by design):

- **Raw HTML** is not rendered (it's escaped). Use Markdown only.
- Images. Keep datasheets textual — the panel is a small popover.

A good datasheet is short and scannable — a one-line overview, a pinout table,
a few spec bullets, and one wiring tip. The panel scrolls, so longer docs are
fine, but front-load the essentials.

---

## What the panel shows (doc vs metadata)

The panel is assembled like this, top to bottom:

```
┌─────────────────────────────────────┐
│ [thumb]  Name                        │  ← from metadata
│          CATEGORY · N pins           │  ← from metadata
│          by <brand>                  │  ← from doc front-matter
├─────────────────────────────────────┤
│ <your Markdown datasheet body>       │  ← from doc  (replaces the thin
│                                      │     auto-generated description)
├─────────────────────────────────────┤
│ PROPERTIES                           │  ← from metadata (always)
│ color        red                     │
│ brightness   1                       │
├─────────────────────────────────────┤
│ tag  tag  tag                        │  ← from metadata
├─────────────────────────────────────┤
│                        [  Buy  ]     │  ← from doc front-matter `buy`
└─────────────────────────────────────┘
```

**Takeaway:** the **Properties** list (with default values) is rendered
automatically from metadata *below* your text. **Don't repeat property
defaults in the body** — spend the words on what the JSON can't express: how
the part works, its pinout, and wiring gotchas.

---

## Full annotated example

`frontend/src/components/component-docs/sensors/hc-sr04.md`:

```markdown
---
brand: Generic (HC-SR04)
buy: https://www.amazon.com/s?k=HC-SR04+ultrasonic+sensor
---
HC-SR04 ultrasonic distance sensor. Fire a 10 µs pulse on **TRIG**, then
measure the HIGH width on **ECHO** — distance = time × 0.0343 / 2 (cm).

| Pin | Role |
| --- | --- |
| VCC | 5 V supply |
| TRIG | trigger input (10 µs pulse) |
| ECHO | echo output (width ∝ distance) |
| GND | ground |

- Range **2 cm – 400 cm**, beam ~15°.
- ECHO is a **5 V** signal — level-shift before a 3.3 V board (ESP32/Pico).

**Tip:** `pulseIn(ECHO, HIGH)` returns microseconds; divide by 58 for cm.
```

Which renders as: title + `SENSORS` + pin count badge, a `by Generic
(HC-SR04)` line, the overview paragraph, the pinout table, the two spec
bullets, the tip with inline code, the auto Properties list, tags, and a blue
**Buy** button.

---

## Step-by-step: add a datasheet

1. **Find the id** of the component (see
   [Finding a component's id](#finding-a-components-id)). Say it's `relay`.
2. **Pick the category folder** — Relay is `electromech`, so the path is
   `frontend/src/components/component-docs/electromech/relay.md`.
3. **Create the file.** Add the optional front-matter, then the body
   (overview → pinout table → specs → tip).
4. **Save.** In dev (`npm run dev`) the change hot-reloads. If the editor was
   already open, just **refresh** — the doc is loaded lazily on first hover and
   cached.
5. **Verify.** Open **Add Component**, hover the Relay card, confirm the
   datasheet, brand line, and Buy button look right.

That's it — no registration, no generator run, no code edit. The loader
(`componentDocs.ts`) discovers every `component-docs/**/*.md` automatically via
`import.meta.glob`.

---

## Writing tips

- **Lead with one sentence** that says what the part is and its core behaviour.
- **Always include a pinout table** — it's the single most useful thing the
  metadata lacks.
- **Bold the numbers** that matter (voltages, currents, ranges).
- **One `**Tip:**`** at the end with the most common wiring gotcha
  (pull-ups, series resistors, level shifting, decoupling…).
- **Don't restate the Properties defaults** — they render automatically.
- **Keep it under ~15 lines** of body where you can. Scannable beats complete.
- Use real units and symbols (`Ω`, `µF`, `≈`) — UTF-8 is fine.

---

## File reference

| File | Role |
| --- | --- |
| `frontend/src/components/component-docs/<category>/<id>.md` | The datasheets you author |
| `frontend/src/components/component-docs/README.md` | Short in-repo reminder of this format |
| `frontend/src/components/componentDocs.ts` | Loader — globs the docs, parses front-matter, caches |
| `frontend/src/components/ComponentInfoPanel.tsx` | The hover panel that renders it |
| `frontend/public/components-metadata.json` | Source of the `id`, name, category, properties (generated — do not hand-edit; see [Component Metadata Generator](component-metadata-generator.md)) |

---

## Appendix: component checklist

Every component id, grouped by category. `[x]` = already has a datasheet,
`[ ]` = still needs one. Snapshot of **153 components, 6 documented**.

> To regenerate this list, list the ids in `components-metadata.json` and check
> which have a matching file under `component-docs/`.

#### analog (31)
- [ ] `battery-9v` — 9V Battery
- [ ] `battery-aa` — AA Battery (1.5V)
- [ ] `battery-coin-cell` — Coin Cell (CR2032, 3V)
- [ ] `bjt-2n2222` — 2N2222 (NPN BJT)
- [ ] `bjt-2n3055` — 2N3055 (NPN Power BJT)
- [ ] `bjt-2n3906` — 2N3906 (PNP BJT)
- [ ] `bjt-bc547` — BC547 (NPN BJT)
- [ ] `bjt-bc557` — BC557 (PNP BJT)
- [ ] `diode` — Diode (generic)
- [ ] `diode-1n4007` — 1N4007 (1 kV Rectifier)
- [ ] `diode-1n4148` — 1N4148 (Small-Signal Diode)
- [ ] `diode-1n5817` — 1N5817 (Schottky 20V)
- [ ] `diode-1n5819` — 1N5819 (Schottky 40V)
- [ ] `mosfet-2n7000` — 2N7000 (N-MOSFET)
- [ ] `mosfet-fqp27p06` — FQP27P06 (P-MOSFET)
- [ ] `mosfet-irf540` — IRF540 (N-MOSFET Power)
- [ ] `mosfet-irf9540` — IRF9540 (P-MOSFET)
- [ ] `opamp-ideal` — Ideal Op-Amp
- [ ] `opamp-lm324` — LM324 (Quad Op-Amp)
- [ ] `opamp-lm358` — LM358 (Dual Op-Amp)
- [ ] `opamp-lm741` — LM741 (Op-Amp)
- [ ] `opamp-tl072` — TL072 (JFET Op-Amp)
- [ ] `opto-4n25` — 4N25 (Optocoupler)
- [ ] `opto-pc817` — PC817 (Optocoupler)
- [ ] `power-supply` — Regulated Power Supply
- [ ] `reg-7805` — 7805 (+5V Linear Regulator)
- [ ] `reg-7812` — 7812 (+12V Linear Regulator)
- [ ] `reg-7905` — 7905 (−5V Linear Regulator)
- [ ] `reg-lm317` — LM317 (Adjustable Linear Regulator)
- [ ] `signal-generator` — Signal Generator
- [ ] `zener-1n4733` — 1N4733 (5.1 V Zener)

#### boards (4)
- [ ] `arduino-mega` — Arduino Mega
- [ ] `arduino-nano` — Arduino Nano
- [ ] `arduino-uno` — Arduino Uno
- [ ] `esp32-devkit-v1` — ESP32 Devkit V1

#### displays (16)
- [ ] `epaper-1in54-bw` — ePaper 1.54" (200×200, B/W)
- [ ] `epaper-2in13-bw` — ePaper 2.13" (250×122, B/W)
- [ ] `epaper-2in13-bwr` — ePaper 2.13" (250×122, B/W/Red)
- [ ] `epaper-2in9-bw` — ePaper 2.9" (296×128, B/W)
- [ ] `epaper-2in9-bwr` — ePaper 2.9" (296×128, B/W/Red)
- [ ] `epaper-4in2-bw` — ePaper 4.2" (400×300, B/W)
- [ ] `epaper-5in65-7c` — ePaper 5.65" (600×448, ACeP 7-colour)
- [ ] `epaper-7in5-bw` — ePaper 7.5" (800×480, B/W)
- [ ] `ili9341` — ILI9341
- [ ] `lcd1602` — LCD1602
- [ ] `lcd1602-i2c` — LCD 16x2 (I2C)
- [ ] `lcd2004` — LCD2004
- [ ] `lcd2004-i2c` — LCD 20x4 (I2C)
- [x] `ssd1306` — SSD1306
- [ ] `ssd1306-i2c` — SSD1306 OLED (I2C)
- [ ] `ssd1306-spi` — SSD1306 OLED (SPI)

#### electromech (2)
- [ ] `motor-driver-l293d` — L293D (Dual H-Bridge Motor Driver)
- [ ] `relay` — Relay (SPDT)

#### input (6)
- [ ] `dip-switch-8` — DIP Switch 8
- [ ] `ky-040` — KY-040 Rotary Encoder
- [ ] `membrane-keypad` — Membrane Keypad
- [x] `potentiometer` — Potentiometer
- [x] `pushbutton` — Pushbutton
- [ ] `slide-switch` — Slide Switch

#### logic (25)
- [ ] `flip-flop-d` — D Flip-Flop
- [ ] `flip-flop-jk` — JK Flip-Flop
- [ ] `flip-flop-t` — T Flip-Flop
- [ ] `ic-74hc00` — 74HC00 (Quad 2-input NAND)
- [ ] `ic-74hc02` — 74HC02 (Quad 2-input NOR)
- [ ] `ic-74hc04` — 74HC04 (Hex Inverter)
- [ ] `ic-74hc08` — 74HC08 (Quad 2-input AND)
- [ ] `ic-74hc14` — 74HC14 (Hex Schmitt Inverter)
- [ ] `ic-74hc32` — 74HC32 (Quad 2-input OR)
- [ ] `ic-74hc86` — 74HC86 (Quad 2-input XOR)
- [ ] `logic-gate-and` — AND Gate
- [ ] `logic-gate-and-3` — AND Gate (3-input)
- [ ] `logic-gate-and-4` — AND Gate (4-input)
- [ ] `logic-gate-nand` — NAND Gate
- [ ] `logic-gate-nand-3` — NAND Gate (3-input)
- [ ] `logic-gate-nand-4` — NAND Gate (4-input)
- [ ] `logic-gate-nor` — NOR Gate
- [ ] `logic-gate-nor-3` — NOR Gate (3-input)
- [ ] `logic-gate-nor-4` — NOR Gate (4-input)
- [ ] `logic-gate-not` — NOT Gate (Inverter)
- [ ] `logic-gate-or` — OR Gate
- [ ] `logic-gate-or-3` — OR Gate (3-input)
- [ ] `logic-gate-or-4` — OR Gate (4-input)
- [ ] `logic-gate-xnor` — XNOR Gate
- [ ] `logic-gate-xor` — XOR Gate

#### motors (4)
- [ ] `a4988` — A4988 Stepper Driver
- [ ] `biaxial-stepper` — Biaxial Stepper
- [ ] `servo` — Servo
- [ ] `stepper-motor` — Stepper Motor

#### other (18)
- [ ] `7segment` — 7 Segment
- [ ] `analog-joystick` — Analog Joystick
- [ ] `big-sound-sensor` — Big Sound Sensor
- [ ] `ds1307` — DS1307
- [ ] `flame-sensor` — Flame Sensor
- [ ] `gas-sensor` — Gas Sensor
- [ ] `heart-beat-sensor` — Heart Beat Sensor
- [ ] `hx711` — HX711
- [ ] `ks2e-m-dc5` — KS2E-M-DC5
- [ ] `led-ring` — LED Ring
- [ ] `microsd-card` — microSD Card
- [ ] `nano-rp2040-connect` — Nano RP2040 Connect
- [ ] `neopixel-matrix` — NeoPixel Matrix
- [ ] `pushbutton-6mm` — Pushbutton 6mm
- [ ] `rotary-dialer` — Rotary Dialer
- [ ] `slide-potentiometer` — Slide Potentiometer
- [ ] `small-sound-sensor` — Small Sound Sensor
- [ ] `tilt-switch` — Tilt Switch

#### output (5)
- [ ] `buzzer` — Buzzer
- [x] `led` — LED
- [ ] `led-bar-graph` — Led Bar Graph
- [ ] `neopixel` — Neopixel
- [ ] `rgb-led` — RGB Led

#### passive (34)
- [ ] `cap-100n` — Cap. 100 nF
- [ ] `cap-100p` — Cap. 100 pF
- [ ] `cap-10n` — Cap. 10 nF
- [ ] `cap-10p` — Cap. 10 pF
- [ ] `cap-1n` — Cap. 1 nF
- [ ] `cap-1u` — Cap. 1 µF
- [ ] `cap-22p` — Cap. 22 pF
- [ ] `cap-elec-1000u` — Electrolytic 1000 µF
- [ ] `cap-elec-100u` — Electrolytic 100 µF
- [ ] `cap-elec-10u` — Electrolytic 10 µF
- [ ] `cap-elec-1u` — Electrolytic 1 µF
- [ ] `cap-elec-470u` — Electrolytic 470 µF
- [ ] `cap-elec-47u` — Electrolytic 47 µF
- [ ] `capacitor` — Cap. ceramic (custom)
- [ ] `capacitor-electrolytic` — Electrolytic Cap. (custom)
- [ ] `franzininho` — Franzininho
- [ ] `ind-100u` — Inductor 100 µH
- [ ] `ind-10m` — Inductor 10 mH
- [ ] `ind-1m` — Inductor 1 mH
- [ ] `inductor` — Inductor (custom)
- [ ] `ir-receiver` — IR Receiver
- [ ] `ir-remote` — IR Remote
- [ ] `resistor` — Resistor (custom)
- [ ] `resistor-100k` — Resistor 100 kΩ
- [ ] `resistor-10k` — Resistor 10 kΩ
- [ ] `resistor-1k` — Resistor 1 kΩ
- [ ] `resistor-1m` — Resistor 1 MΩ
- [ ] `resistor-220` — Resistor 220 Ω
- [ ] `resistor-22k` — Resistor 22 kΩ
- [ ] `resistor-2k2` — Resistor 2.2 kΩ
- [ ] `resistor-330` — Resistor 330 Ω
- [ ] `resistor-470` — Resistor 470 Ω
- [ ] `resistor-47k` — Resistor 47 kΩ
- [ ] `resistor-4k7` — Resistor 4.7 kΩ

#### sensors (8)
- [ ] `bmp280` — BMP280 (Pressure + Temp)
- [x] `dht22` — DHT22
- [x] `hc-sr04` — HC-SR04
- [ ] `mpu6050` — MPU6050
- [ ] `ntc-temperature-sensor` — NTC Temperature Sensor
- [ ] `photodiode` — Photodiode
- [ ] `photoresistor-sensor` — Photoresistor Sensor
- [ ] `pir-motion-sensor` — PIR Motion Sensor