# Minimig project notes

The AmiCube-style hierarchy was built from the original GitLab revision
`1a30d220e7fdfb857ca4780d531a2604b5337407`. The frozen KiCad files, native netlist,
PDF and ERC report are retained in `hierarchy/baseline/` for comparison.

## Structure

`Minimig198itx.kicad_sch` is the system overview. Its five sections are Power,
FPGA, Control, Interfaces and Mechanical. Circuit sheets use A4 landscape,
explicit section links, named bus interfaces and consistent signal tables.
The original 208-pin FPGA drawing is divided into six functional units; original
pin names, numbers, electrical types, strap connections and net assignments
are preserved. This drawing grouping does not claim to represent silicon banks.

All 33 pages use A4 landscape. The final pages 29–33 are documentation sheets:

1. Top assembly
2. Bottom assembly
3. Layer stackup
4. Routing guide
5. Power and buses

The complete PDF is `Minimig198itx-schematics.pdf`. Public documentation,
PDF schematics, iBOM, manufacturing exports and offline bundles are linked from
[The Source](https://www.minimig.ca/minimig-source-code/#minimig-198itx).
The [presentation](https://www.minimig.ca/presentations/minimig/) provides all five
A4 board-guide previews and the same download links. Editable KiCad files remain
internal; publishing the exported documents is separate from a Git push.

## Consolidated layout (17 October 2026)

The previous 46-sheet layout is reduced to 33 without changing physical pin
connectivity. Intermediate CPU, ARM, memory, FPGA-unit, regulator and VGA
overview pages have been removed. The retained section pages link directly to
their circuits. The following circuits now share sheets:

- All three regulated rails.
- MC68000, supply bypass and bus pull-ups; all five bus translators.
- ARM controller, crystal, PLL RC network and local controls.
- FPGA power pins and all associated bypass capacitor banks.
- VGA DAC, sync and bypass capacitors.
- Mounting holes/fiducials and the mechanical/documentation index.

SRAM bypass parts sit below their associated memory devices. ATX, CPU, SRAM
and UART pins have outward-facing net labels with explicit wire stubs. The
serial charge-pump capacitors are separated from the dense pin fan-out.
Repeated PWR_FLAG value text is hidden while the electrical flags remain.
Legends list signals shared between sheets rather than internal node paths.

The five documentation pages are reflowed for A4 with readable text, a reserved
title-block area and calibrated 1:2 assembly plans. Top/bottom images retain
the native CAD pixels and transparency, are trimmed to their nontransparent
extent (including protruding connectors), and include explicit 300 dpi metadata.
`board_drawings/assets/render-framing.json` records the PCB-outline calibration.
PCB schematic associations and net-name metadata follow the new hierarchy;
PCB geometry, models, project settings and libraries are preserved.

## Portable libraries

Both library tables resolve through `${KIPRJMOD}`:

- `libraries/symbols/Precision-Arrays-Minimig.kicad_sym` contains 54 cached-source symbol definitions.
- `libraries/footprints/Precision-Arrays-Minimig.pretty` contains 344 exact variants for all 392 PCB footprints, including graphics. Source instances sharing a legacy library ID sometimes differ; those variants remain separate.
- `libraries/models/` contains all 40 original model mappings, their exact-stem companion files and existing license notices: 64 model files and six notices for 358 placements.

The original `Libs/` and manufacturing archives remain as historical source
material. Active symbols, footprints and model paths use `libraries/`.
Third-party assets retain their included licenses and original authors' rights.

## Preservation and checks

`hierarchy/verification.json` records the independent audit. It confirms all
403 net partitions across 1,623 physical pins, all 380 component references and
values, and all 208 FPGA pin definitions. The PCB retains every footprint,
pad, segment, arc, via, zone, position, layer and model transform. Only local
library IDs, relative model filenames, schematic associations and corresponding
net-name metadata changed. Native global continuations remove the original
root-sheet slash prefix from named local nets; electrical pin partitions and
PCB net codes are unchanged. The source spelling `FPG_A19` is retained.

The original ERC report had 758 findings. The reorganized project has two:
J12 pin P4 (VDD) lacks an output-power driver, and the original wire UUID
`9a6260ea-76d8-418e-8217-5f4bb330ae2a` has an open endpoint. Both are inherited
source conditions, not silently repaired circuit changes. This is a layout and
library-preservation update, not electrical or manufacturing sign-off.

Run from the project root with Python 3 and KiCad 10:

```sh
python3 tools/localize_models.py --verify
kicad-python tools/localize_footprints.py --verify
kicad-cli sch export netlist --format kicadxml -o documentation/hierarchy/netlist.xml Minimig198itx.kicad_sch
python3 tools/verify_project.py
kicad-cli sch erc --format json -o documentation/hierarchy/erc.json Minimig198itx.kicad_sch
```

## Rebuilding the original hierarchy

The conversion tools deliberately rebuild from the frozen original. They are
historical migration tools, not a routine refresh command. Do not run them over
the current layout or subsequent circuit edits. Regular design work proceeds
directly in KiCad. `polish_schematic.py`, `consolidate_schematic.py` and
`finish_schematic_layout.py` record the layout migration steps and require native
netlist/ERC review when used on a reconstructed original hierarchy.

Refresh documentation and exports from the current saved project:

```sh
python3 tools/board_documentation.py
kicad-cli sch export pdf -o documentation/Minimig198itx-schematics.pdf Minimig198itx.kicad_sch
kicad-cli sch export netlist --format kicadxml -o documentation/hierarchy/netlist.xml Minimig198itx.kicad_sch
kicad-cli sch erc --format json -o documentation/hierarchy/erc.json Minimig198itx.kicad_sch
python3 tools/verify_project.py
```

The documentation generator requires Pillow, Inkscape, Poppler and KiCad's
Python bindings. `kicad-python` is the default launcher; `KICAD_PYTHON` may point
to another launcher. See `board_drawings/README.txt` for packaged render details.

For a faithful native 3D export, prepare an isolated staging PCB:

```sh
python3 tools/localize_models.py --export-stage /tmp/Minimig198itx-export.kicad_pcb
```

The staging helper resolves exact STEP companions explicitly. KiCad's automatic
WRL substitution drops F1's nonuniform saved scale; the explicit path preserves
it. The packaged active PCB retains the original model type and transforms.
The local-model export audit found byte-identical geometry across all 364 native
mesh groups. Native web assets preserve 63,725 silkscreen triangles and all 46
original double-sided materials.