BREADS definitions, specifications, schemas, templates, and reusable CI infrastructure for BREADS-compatible hardware repos.
spec/— Human-readable specifications and BREADS terminologyschemas/— JSON Schemas for manifest validation (machine-readable)templates/— Copy-paste manifest templates for new repos.github/workflows/— Reusable CI workflows (KiBot, docs deployment, manifest validation)scripts/— Build and validation helper scripts
Start with spec/terminology.md for the active
definitions of BREAD, BREADS, Slices, Loaves, and Grains.
For Slice firmware, spec/slice/firmware.md defines
what every Slice's firmware does the same way, and
spec/firmware-layering.md sets out where shared
firmware code lives and what may depend on what.
BREAD started as an open-source hardware project on OSF. See
CITATION.md for how to cite it, the papers and thesis behind
it, and which OSF page each Slice came from.
See Slice_TEMP_NANO_S2L-r2 for an example of the required auxiliary and template files.
Results of testing a Slice on real hardware go in that Slice's docs/bench/:
see spec/slice/bench-records.md and
templates/bench-record.md.
This repo contains reusable workflows, specifications, and scripts for BREADS-compatible hardware repos. It is not meant to be triggered directly.
To use in other repos, copy templates/docs-pipeline.yml
to .github/workflows/docs-pipeline.yml. It wires up board validation, KiBot ERC/DRC,
and the docs site, and it runs on pull requests as well as pushes — hardware checks
that only run after merge cannot stop anything from breaking.
Board repos also need templates/hardware.Makefile at
hardware/Makefile, and templates/gitignore at .gitignore.
scripts/upgrade_kicad10.sh <repo> # flatpak KiCad by default
KICAD_CLI=kicad-cli scripts/upgrade_kicad10.sh <repo> # native installUses KiCad's own kicad-cli sch upgrade / pcb upgrade. Lossless and idempotent —
safe to re-run, including on boards already migrated.
sch upgrade does not cascade into hierarchical sub-sheets. Upgrading only the
root sheet leaves every sub-sheet on the old format, which looks migrated and is not.
This script upgrades every sheet it finds.
It only migrates the file format. It does not fix broken library references,
re-link footprints from the schematic, or fix annotation errors — run
validate_board.py afterwards to see what is still wrong.
validate-board.yml checks that a board is
actually aligned with BREADS, not merely that it opens in KiCad:
| Check | Why |
|---|---|
| KiCad 10 file format | A board saved by KiCad 9 opens fine; the version stamp is the only signal. |
footprint_symbol_mismatch severity is error |
KiCad's default is warning, and KiBot's DRC preflight only fails on errors — so schematic_parity: true runs the check and can never fail it. |
| Every library reference resolves | KiCad embeds footprint geometry in the .kicad_pcb, so a board renders and fabricates long after its library reference has rotted. |
hardware/Makefile targets not swapped |
KiBot's -s skips the named preflight, so drc: kibot -s drc skips DRC. |
.gitignore ignores .history/ |
KiCad 10's Local History git_repository_init()s <project>/.history. It is a nested git repo; the .gitignore KiCad writes inside it governs KiCad's history repo, not yours. Committing it adds a broken gitlink. |
Run it locally:
python3 scripts/validate_board.py <repo> --master-lib <KiCad-Master-Lib>A green Validate Board is the definition of "this board is done".