LLUPS

LLUPS — Lithium Li-ion Universal Power Supply

Status: Draft / Untested — Schematic and layout are procedurally generated and have not been fabricated or validated on hardware. Review all design choices and run DRC before ordering boards.

A compact PCB module providing regulated 5V and 3.3V power from two 18650 Li-ion cells (1S2P), charged via USB-C with passthrough capability.

Specs

Getting Started

# Clone with submodules
git clone --recurse-submodules https://github.com/laforestlabs/LLUPS.git
cd LLUPS

# If already cloned without submodules
git submodule update --init --recursive

# Install KiCraft tooling (required for all CLI commands)
pip install -e KiCraft/

# Or with GUI support
pip install -e "KiCraft/[gui]"

Requirements:

• Python 3.10+
• KiCad 9 with pcbnew Python bindings
• FreeRouting JAR (for automated routing)
• KiCraft submodule (included, installed via pip above)

Core Files

LLUPS.kicad_pro          # KiCad 9 project
LLUPS.kicad_sch          # Schematic
LLUPS.kicad_pcb          # PCB layout
generate_project.py      # Regenerates project artifacts
spec.md                  # Design specification
BOM.csv / BOM.xlsx       # Bill of materials
KiCraft/                 # KiCraft tooling (git submodule) — https://github.com/laforestlabs/KiCraft

Regenerating

python3 generate_project.py

Requires KiCad 9 CLI tools (kicad-cli) for netlist export.

Running the Optimizer

autoexperiment LLUPS.kicad_pcb --rounds 100

The optimizer iterates placement and routing, keeping candidates that improve the overall score and discarding the rest. The best layout is saved to LLUPS_best.kicad_pcb.

Search Space Flags

# Full exploration: unlock all footprints + vary board size over 150 rounds
autoexperiment LLUPS.kicad_pcb \
  --rounds 150 --unlock-all --board-size-search

Experiment Manager GUI

A standalone NiceGUI web app for configuring, running, monitoring, and analyzing experiments.

# Install KiCraft with GUI dependencies (first time only)
pip install -e "KiCraft/[gui]"

# Launch the GUI
python3 -m kicraft.gui
# then open http://localhost:8080

GUI Tabs

Experiment data is stored in .experiments/llups.db (SQLite). Existing JSONL logs are auto-imported on first launch.

Monitoring Your Run

All monitoring is read-only — it reads output files and never interferes with the experiment. Zero performance impact.

During a run — pick any of these (in a second terminal):

# Experiment Manager GUI (recommended — includes live charts + analysis)
python3 -m kicraft.gui

# Or: one-line terminal status
watch -n2 cat .experiments/run_status.txt

# Or: leave the HTML report open; it rebuilds after each round and refreshes itself
xdg-open report.html

After a run:

# Animated layout evolution
xdg-open .experiments/progress.gif

# Score dashboard (PNG)
xdg-open .experiments/experiments_dashboard.png

# Interactive HTML report (richest view; rebuilt live during the run and finalized at the end)
generate-report .experiments/ -o report.html
xdg-open report.html

For monitoring during a run, the KiCraft GUI (python -m kicraft.gui) is the primary tool — it shows live per-leaf round progress, score plots, render thumbnails, and per-component pin controls. The CLI artifacts above (run_status.txt, progress.gif, experiments_dashboard.png, report.html) are still produced for headless workflows.

Architecture & Scoring

• docs/architecture.md — system diagrams and layer responsibilities
• docs/footprint-layout.md — placement engine details
• docs/auto-trace.md — routing engine details
• docs/scoring.md — scoring formulas and weight breakdowns

Static QA score (independent of the optimizer):

score-layout LLUPS.kicad_pcb

KiCraft CLI Commands

Automation commands using the KiCad 9 pcbnew Python API, provided by the KiCraft submodule:

All available as CLI commands after pip install -e KiCraft/.

Subcircuits Workflow

The hierarchical/subcircuits redesign is currently focused on a real leaf-first routing flow:

1. parse the true schematic hierarchy from LLUPS.kicad_sch
2. extract each leaf sheet into a local board state
3. stamp a real KiCad leaf board under .experiments/subcircuits/<slug>/
4. validate the stamped pre-route leaf board before routing
5. route the leaf through the real FreeRouting path
6. validate the routed leaf artifact before accepting it
7. persist accepted routed copper canonically in solved_layout.json

Current verification command:

solve-subcircuits LLUPS.kicad_sch \
  --pcb LLUPS.kicad_pcb \
  --rounds 1 \
  --route

Leaf render diagnostics

Each leaf artifact may now include a small visual diagnostic bundle under:

.experiments/subcircuits/<slug>/renders/

These diagnostics are intended for debugging real stamped/routed leaf boards, not for demo polish. The preferred artifact set is:

• pre_route_copper_both.png
• pre_route_front_all.png
• pre_route_drc.json
• pre_route_drc_overlay.png when coordinate-bearing violations exist
• routed_copper_both.png
• routed_front_all.png
• routed_drc.json
• routed_drc_overlay.png when coordinate-bearing violations exist
• pre_vs_routed_contact_sheet.png

This makes it easier to answer:

• is the stamped pre-route leaf board already illegal?
• are footprints or edge-coupled connectors misaligned to Edge.Cuts?
• did FreeRouting add meaningful copper?
• did routing improve or worsen the board visually?

Current status

The subcircuit pipeline is functional: all 6 LLUPS leaves solve, route, and pass acceptance gates. Parent composition assembles the leaves and routes interconnects via FreeRouting. The pipeline runs to completion without Python exceptions and produces human-inspectable output. The parent acceptance gate currently rejects due to FreeRouting routing quality (a tuning target, not a functional gap). See ROADMAP.md for detailed phase status.

License

GPLv3 — see LICENSE.