a2nr
/
velxio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
velxio/docs/components.md

9.0 KiB
Raw Blame History

Components Reference

Velxio ships with 150+ interactive electronic components across 11 categories. Most come from the upstream 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.

Adding Components

  1. Click the + Add Component button on the simulation canvas.
  2. Use search or browse by category in the picker.
  3. Click a component to place it on the canvas.
  4. Drag to reposition, click to open the Property Dialog (color, pin assignment, value, rotate, delete).
  5. Double-click to open the Pin Selector for explicit pin-to-board mapping.

Connecting Components

  1. Click a pin on any component — a wire starts from that pin.
  2. Click a destination pin to complete the connection.
  3. Wires are color-coded by signal type:
Color Signal type
Red VCC (power)
Black GND (ground)
Blue Analog
Green Digital
Purple PWM
Gold I2C (SDA/SCL)
Orange SPI (MOSI/MISO/SCK)
Cyan USART (TX/RX)

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:

Category Count Examples
Boards 4 Arduino Uno, Mega, Nano, ATtiny85 footprint stand-ins
Displays 16 LCD 16x2, LCD 20x4, 7-segment (1/2/4 digits), SSD1306 OLED, ST7735, ILI9341 TFT, NeoPixel matrix, ring, strip, e-paper panels
Sensors 8 DHT11/22, HC-SR04, PIR, photoresistor, MPU6050, BMP280, NTC thermistor, IR receiver
Input 5 Pushbutton, slide switch, DIP switch, rotary encoder, analog joystick
Output 5 LED, RGB LED, LED bar graph, buzzer, servo
Motors 3 Servo, DC motor, stepper
Logic 25 74HC00 series gates, 74HC595 shift reg, 74HC165, 74HC138, 4017, 4051, 4094, D/JK flip-flops, multiplexers, decoders
Analog 31 Op-amps (LM358, TL081, LM741, …), comparators, voltage references, function gen, voltmeter, ammeter, oscilloscope probes
Passive 34 Resistors, capacitors (electrolytic / ceramic / film), inductors, diodes (1N4148, 1N4007, Zener, Schottky, LED), transistors (NPN/PNP/2N2222/BC547/MOSFET N/P), potentiometers, trimmers
Electromech 2 Relay (SPDT), reed switch
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 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
Oscilloscope Multi-channel waveform capture 4 channels, trigger source, time/div, voltage/div, logic-analyzer mode
Function Generator Sine / square / triangle / sawtooth out Configurable freq, amplitude, DC offset, duty cycle

The instruments are pure analog UI surfaces — drop them on the canvas, wire the probes, and the values update in real time. No code change required.

Logic gates (discrete)

AND, NAND, OR, NOR, XOR, XNOR, NOT, Buffer — each as its own canvas component (separate from the 74HC IC variants).

Power & connectors

Power supply (configurable V), GND rail, 5V rail, 3V3 rail, terminal blocks, breadboards (full + half + mini), DIP/SOP/QFP footprints for custom-chip placeholders.

Analog vs digital co-simulation

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.
  2. Pure analog — op-amp, transistor, diode, resistor, capacitor, voltmeter. Modeled as SPICE cards by NetlistBuilder, solved by the ngspice-WASM engine every frame.
  3. 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 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:

  • Glue logic — inverter, XOR, pulse counter, latch
  • Shift registers — SN74HC595, CD4094
  • Memory — 24C01 / 24LC256 I2C EEPROM, 32K/1M parallel ROM, 64K parallel RAM
  • Vintage CPUs — Intel 4001, 4002, 4004, 4040, 8080, 8086, 8251, 8253, 8255, 8259
  • Vintage CPUs (alt path) — Z80, i8080 REPL/counter variants
  • I/O expanders — PCF8574, MCP3008
  • RTC — DS3231

See Custom Chips — Developer Guide, API Reference, and Examples.

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, …)
Protocol LCD, OLED, EEPROM I2C address, SPI bus selector
Rotation Any Rotate 90° / 180° / 270°
Delete Any Remove the component (also cascades wire removal)

Component metadata pipeline

frontend/public/components-metadata.json is generated by scripts/generate-component-metadata.ts. Direct edits get wiped on the next regen.

  • wokwi-elements components — auto-discovered by scanning third-party/wokwi-elements/src/ (clone optional; the npm package doesn't ship the source).
  • Velxio-native components — defined under _customComponents in scripts/component-overrides.json.
  • wokwi-elements with richer UI controls — keyed override in the same file patches properties + defaultValues.

To regenerate after editing the override file:

cd frontend
npm run generate:metadata

Full pipeline reference: Component metadata generator.

Adding a new component

For a wokwi-elements part: it's auto-picked up on the next metadata regen — no code changes needed in Velxio.

For a Velxio-native part:

  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).
  5. Run npm run generate:metadata.

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

See also