Velxio ships with **150+ interactive electronic components** across 11 categories. Most come from the upstream [wokwi-elements](https://github.com/wokwi/wokwi-elements) library; the rest are Velxio-native parts (logic gates, instruments, op-amps, transistors, e-paper panels, custom chips).
Every component can be placed on the canvas, wired, rotated, configured, and (for analog parts) co-simulated by the on-board **ngspice** engine.
Wires route orthogonally and snap to the 20px grid. Segments can be dragged perpendicular to their orientation to clean up the layout. Parallel wires automatically offset to avoid overlap.
---
## Catalog (current counts)
Category breakdown straight from `frontend/public/components-metadata.json`:
| Other | 19 | Power supplies, GND rails, breadboards, terminal blocks, EEPROM (24Cxx I2C, 25-series SPI), RFID RC522, fingerprint, GPS, RTC (DS1307, DS3231), custom-chip placeholders |
**Total: 152 components.** The number ticks up over time as new chips, sensors, and instruments land.
---
## Velxio-native components (not in wokwi-elements)
These are defined in `scripts/component-overrides.json` (under `_customComponents`) and built into the catalog at generation time. See [Custom components in the metadata generator](./wiki/component-metadata-generator.md) for the full schema.
### Instruments
| Component | Purpose | Notes |
|-----------|---------|-------|
| **Voltmeter** | DC voltage between two probes | Reads from the live ngspice solution every frame |
| **Ammeter** | Current through a series leg | Inserts a 0Ω current-sense source in the netlist |
Every component on the canvas falls into one of three buckets, transparently:
1.**Pure digital** — LED, button, 7-segment, LCD, NeoPixel. State is driven by `PartSimulationRegistry` (output components) or by injected pin events (input components). MCU pin → component.
1.**Pure analog** — op-amp, transistor, diode, resistor, capacitor, voltmeter. Modeled as SPICE cards by `NetlistBuilder`, solved by the ngspice-WASM engine every frame.
1.**Mixed** — MCU board pins. Each enabled digital pin appears in the netlist as a Thevenin source (0V or VCC, output impedance set by the port driver model). The MCU's ADCs read back the live SPICE node voltage on `analogRead()`.
This is why a potentiometer wired to A0 works without a `setAnalog()` call: the canvas builds a real voltage divider, ngspice solves the node voltage, and the ADC injection pipe samples that voltage on every conversion. Wire an op-amp follower in between and it still works.
Toggle the engine on or off with the **electrical-sim** toggle in the toolbar (lazy-loads the ~39 MB ngspice WASM bundle on first enable). See the [Electrical Simulation User Guide](./wiki/electrical-simulation-user-guide.md) for the full analog workflow.
---
## Custom chips (write your own component)
Velxio ships a custom-chip SDK so you can model parts that aren't in the catalog. Write the chip in C, compile to WebAssembly, drop it on the canvas, wire it up. The gallery includes 30+ ready-to-load examples:
See [Custom Chips — Developer Guide](./CUSTOM_CHIPS.md), [API Reference](./wiki/custom-chips-api-reference.md), and [Examples](./wiki/custom-chips-examples.md).
---
## Property Dialog
Click any component to open its property dialog. Properties vary by part, but common ones:
| Property | Applies to | Description |
|----------|------------|-------------|
| Arduino Pin | Digital input / output | The digital or analog pin this part connects to (when not wired) |
| Color | LEDs, wires | RGB hex value for the visual |
| Value | Resistor, capacitor, inductor, op-amp | Component value (10kΩ, 100nF, …) |
1. Implement it as a Web Component (`class extends HTMLElement`, `attachShadow`, `pinInfo` getter). See `Esp32Element.ts`, `Bmp280Element.ts`, or `LogicGateElements.ts` for templates.
2. Register the custom element with `customElements.define('velxio-…', FooElement)`.
3. Add the entry to `scripts/component-overrides.json` under `_customComponents`.
4. (Optional) Register a behavior in `PartSimulationRegistry` if the component reacts to pin state changes (output) or fires events (input).
**Important:** boards and any component that needs wire connections **must be a real Web Component, not a React SVG.** The wire system reads `element.pinInfo` from the rendered DOM — React SVGs have no `pinInfo` and wires snap to (0, 0) of the parent. See the rule in `CLAUDE.md` (§6a).
