velxio/docs/wiki/component-datasheets.md

495 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.35 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