Repository Layout

• src/pcb2fritzing/: Main Python package.
• src/pcb2fritzing/core/: Extraction and conversion logic.
• src/pcb2fritzing/kicad/: KiCad extension/plugin integration code.
• PROJECT_TRACKER.md: Ongoing development checklist and focus tracking.
• references/fritzing-parts/: .fzp reference files.
• references/kicad-exports/: KiCad export SVG references.
• references/kicad-projects/: KiCad project references for parser/converter development.
• references/samples/: Misc sample and sketch artifacts.
• scripts/build_kicad10_dist.py: Build script for KiCad 10 distribution artifacts.
• dist/: Built KiCad extension artifacts (generated).
• docs/KICAD10_EXTENSION_INSTALL.md: KiCad 10 extension install instructions.

Development Setup

python3 -m venv .venv
. .venv/bin/activate
pip install -e src
pip install -e "src[dev]"

CLI Execution

pcb2fritzing path/to/board.kicad_pcb --out-dir build/fritzing-part

Override the default board-derived part/package name:

pcb2fritzing path/to/board.kicad_pcb --out-dir build/fritzing-part --part-name my-custom-part

For now, this creates placeholder output to validate project wiring and flow. It also writes an intermediate model file: board_model.json. It now also writes a connector model file: fritzing_connectors.json. It also writes a starter Fritzing part file named after the board, e.g. my-board.fzp. It also writes placeholder SVG view files: icon.svg, breadboard.svg, schematic.svg, pcb.svg. It writes a validation report: artifact_validation.json. It writes a shareable package named after the board, e.g. my-board.fzpz.

Fritzing metadata fields can be customized from the KiCad plugin dialog:

• Part Family (default: KiCad2Fritzing Generated)
• Part Type (default: Custom PCB)

These values are written into the generated .fzp under <properties> and influence how Fritzing categorizes and indexes the part.

KiCad plugin dialog behavior (current):

• Generate runs export without closing the dialog; use Close to dismiss it.
• Output messages shows step-by-step diagnostics during export.
• Save... writes diagnostics to a text file for troubleshooting.
• In 3D render mode, 2D silkscreen overlays are removed before embedding the 3D render to avoid ghosting/double text.

Known rendering caveat (pads/pins):

• In 3D render mode, pad/pin colours shown in Fritzing can appear different from the colour picker values.
• This is usually a viewer/compositing effect from embedded 3D imagery and anti-aliasing, not an extra SVG overlay object on top of the pads.
• The generated breadboard.svg can still contain the requested connector pin fill/stroke values even when the on-screen result looks more orange or brighter than expected.
• If colour fidelity is critical, compare the generated SVG element attributes and test at multiple zoom levels before assuming export data is incorrect.

The current 3D render mode uses KiCad's basic 3D viewer output.

Performance note: Generating the Fritzing part with 3D render enabled can take a significant amount of time — typically 30–90 seconds or more depending on board complexity, hardware, and whether KiCad's 3D model cache is warm. This is expected behaviour; the plugin is waiting for kicad-cli to complete a full 3D render. If the export dialog appears unresponsive during this step, allow it time to finish before assuming it has stalled.

KiCad Plugin

The plugin runs from the KiCad PCB Editor toolbar button. It reads the current open board and emits Fritzing artifacts to the selected output directory.

The plugin uses the KiCad IPC API (plugin.json manifest, kicad-python client) and is compatible with KiCad 10.0.1 and later. The SWIG Python bindings are not used.

Note: Tools → External Plugins in KiCad 10.x is populated only by SWIG ActionPlugin registrations. The IPC toolbar button is the sole entry point for this plugin; it does not appear in that menu.

KiCad 10 Extension Packaging And Install

Build distribution artifacts:

python3 scripts/build_kicad10_dist.py

Generated artifacts:

• dist/pcb2fritzing-pcm/
• dist/PCB2FritzingPart-pcm.zip
• dist/metadata.json (registry metadata for KiCad plugin repositories)

Build Configuration

Before building a release, copy scripts/build_config.json.example to scripts/build_config.json and update with your details:

cp scripts/build_config.json.example scripts/build_config.json
# Edit scripts/build_config.json with your username, author, and platform metadata.

Important: Configurable fields in build_config.json:

• username: GitHub username (used in plugin identifier and URLs)
• author_name: Your full name (displayed in KiCad plugin metadata)
• contact_web: Your contact URL (e.g., GitHub project page)
• release_status: Plugin status ("development" or "stable")
• kicad_version: Minimum KiCad version declared in PCM metadata (e.g., "10.0"). This is informational only — the package always uses the IPC runtime, which is compatible with KiCad 10.0.1+ and 11.0+.
• release_asset_name: Release asset filename (defaults to PCB2FritzingPart-pcm.zip)
• tags: Plugin category tags
• platforms: Supported platforms (["linux", "macos", "windows"])

Release-derived values are set by CI at build time from the Git tag:

• version
• release_tag
• download_url

Fields NOT required (auto-computed from artifacts):

• download_sha256 — Computed from ZIP file
• download_size — Computed from ZIP file
• install_size — Computed from exploded package

Version Format

KiCad PCM requires versions to match the schema: ^\d{1,4}(\.\d{1,4}(\.\d{1,6})?)?$

Valid version examples:

• "0" – Single component
• "1.2" – Major.minor
• "0.1.0" – Major.minor.patch (recommended)
• "1000.9999.999999" – Maximum bounds

Invalid version examples (will be rejected):

• "0.1.0-beta" – Pre-release suffix not allowed
• "1.0.0-rc1" – Release candidate not allowed
• "v1.0.0" – Leading v not allowed

The build script validates version format on every build and will fail with a helpful error if the format is incorrect.

Install the plugin via KiCad's Plugin and Content Manager (PCM): Manage → Install from File… and select the .zip.

Install path on macOS (PCM managed):

• ~/Library/Application Support/kicad/10.0/3rdparty/plugins/

Detailed install steps are in:

• docs/KICAD10_EXTENSION_INSTALL.md

Next Steps

• Capture and reproduce board-specific compatibility issues with minimal fixtures.
• Add targeted failing tests before each board-specific fix.
• Harden parser coverage for board/footprint edge cases (text, layers, geometry variants).
• Validate connector IDs/names/mappings on at least two real board designs.
• Validate generated .fzp schema assumptions against actual Fritzing import behavior.
• Add CLI parity flags for plugin metadata controls (--part-family, --part-type).
• Add round-trip checks using Fritzing import/export where practical.
• Expand plugin behavior and end-to-end integration tests.
• Add CI to run tests automatically on push/PR.

Testing

Run tests from repository root:

. .venv/bin/activate
pytest

Current tests cover:

• Placeholder extractor output creation.
• Intermediate board model and connector model generation.
• Minimal .fzp generation from connector model.
• Placeholder SVG generation and connector ID consistency validation.
• CLI argument parsing and output generation flow.

Optional external-project integration test (disabled by default):

This test can clone a KiCad project repo at test time, parse it, and validate generated artifacts without storing the project in this repository.

The test reads a local secret config at tests/external_projects.local.json and runs one case per enabled entry. Add or remove projects there, or point K2F_EXTERNAL_PROJECTS_CONFIG at another JSON file with the same shape.

A public sample is provided at tests/external_projects.sample.json. Copy it to tests/external_projects.local.json and edit it for your own projects.

Each project entry supports:

• name for the pytest test id.
• repo_url for the Git URL.
• branch for the target branch.
• enabled to temporarily disable an entry without deleting it.
• repo_subdir and board_rel_path for projects that keep the KiCad board in a subfolder or specific file.

Example with LoudMouth k10_update:

. .venv/bin/activate
RUN_EXTERNAL_PROJECT_TESTS=1 \
pytest tests/test_external_projects.py -q

Useful optional variables:

• K2F_EXTERNAL_PROJECTS_CONFIG to use a different JSON config file.
• K2F_EXTERNAL_REPO_URL and K2F_EXTERNAL_REPO_BRANCH to override the config for a one-off run.
• K2F_EXTERNAL_REPO_SUBDIR to limit search to a folder inside the cloned repo.
• K2F_EXTERNAL_BOARD_PATH to target a specific .kicad_pcb file relative to that folder.

Rendering tuning:

• K2F_SILK_TEXT_SCALE adjusts silkscreen text size in generated SVGs (default 1.15). Example: K2F_SILK_TEXT_SCALE=1.22 for slightly larger board labels.

Fritzing Import Notes

• If you previously imported early generated parts and see startup warnings from Fritzing local parts scanning, remove stale pcb2fritzing.* entries from:
  • ~/Library/Application Support/Fritzing/Fritzing/local_parts/user/
• Re-import a newly generated .fzpz from this version to refresh metadata with required family/type properties.