a2nr
/
velxio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
velxio/docs/wiki/component-datasheets.md

18 KiB
Raw Blame History

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
  2. TL;DR
  3. Where the files live & how they are named
  4. Finding a component's id
  5. Front-matter: brand & buy link
  6. The Markdown body
  7. What the panel shows (doc vs metadata)
  8. Full annotated example
  9. Step-by-step: add a datasheet
  10. Writing tips
  11. File reference
  12. 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

---
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). 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:

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

B. Use the checklist at the bottom of this page, 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.

---
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:

---
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). 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)

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)
  • 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
  • potentiometer — Potentiometer
  • 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
  • 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)
  • dht22 — DHT22
  • hc-sr04 — HC-SR04
  • mpu6050 — MPU6050
  • ntc-temperature-sensor — NTC Temperature Sensor
  • photodiode — Photodiode
  • photoresistor-sensor — Photoresistor Sensor
  • pir-motion-sensor — PIR Motion Sensor