diff options
Diffstat (limited to 'clef/README.md')
| -rw-r--r-- | clef/README.md | 196 |
1 files changed, 196 insertions, 0 deletions
diff --git a/clef/README.md b/clef/README.md index 780fa8e..19520b9 100644 --- a/clef/README.md +++ b/clef/README.md @@ -1,3 +1,199 @@ # clef My kicad templates, libraries, and sheets. + +Comes with a Nix function to process a KiCad project into: + +- Board SVGs +- Board 3d model (.glb, .step) +- Schematic PDF, SVGs +- Fabrication files (using kikit) + - Currently untested — I had to use Fabrication Toolkit on my last + project +- Panelized board (using kikit) + - Also minimal testing + +Example output for [ocularium](https://pub.npry.dev/ocularium), which provides +the content for [this blog post](https://blog.npry.dev/resenv/ocularium): + +```bash +$ nix build .# && nix run nixpkgs#tree result +result +└── share + └── npry + └── ocularium + ├── fab + │ ├── bom.csv + │ ├── gerbers.zip + │ └── pos.csv + ├── model + │ ├── okm.glb + │ └── okm.step + ├── schematic + │ ├── schematic.pdf + │ └── svg + │ ├── IO.svg + │ ├── MCU.svg + │ ├── Power.svg + │ ├── root.svg + │ └── Sensors.svg + └── svg + ├── back.mirror.svg + ├── back.svg + ├── front.mirror.svg + ├── front.svg + ├── in1.mirror.svg + ├── in1.svg + ├── in2.mirror.svg + └── in2.svg + +8 directories, 19 files +``` + +## usage: subtree + +I currently include this repo as a [git +_subtree_](https://manpages.debian.org/testing/git-man/git-subtree.1.en.html) +in kicad projects that use it: + +```bash +# to init: +$ git subtree add --squash --prefix clef https://pub.npry.dev/clef master + +# then to update: +$ git subtree pull --squash --prefix clef https://pub.npry.dev/clef master +``` + +Submodules are closer to what I want semantically, but I consider them too +fragile to use. + +## nix + +The flake provides `pkgs.clef`, a function building a derivation that contains +the processed content. + +Please be aware that complete functionality will involve rebuilding a couple +of large derivations from source (KiCad, occt and dependents) until I get +around to upstreaming my overlays. + +### example + +```nix +# flake.nix +{ + inputs = { + nixpkgs.url = "github:nixos/nixpkgs/release-24.05"; + flake-utils.url = "github:numtide/flake-utils/main"; + + clef = { + url = "git+https://pub.npry.dev/clef"; + + # or if using subtree/submodules: + # url = "path:clef"; + + inputs.nixpkgs.follows = "nixpkgs"; + flake-utils.follows = "flake-utils"; + }; + }; + + outputs = { nixpkgs, clef }: (flake-utils.lib.eachDefaultSystem (system: let + pkgs = import nixpkgs { + overlays = [ + # NB: This causes another independent nixpkgs eval -- it's just: + # + # final: prev: { inherit (clef.packages.${prev.system}) clef; } + # + # This is the easiest way to get started, and if you don't know or + # care why you don't want to eval nixpkgs multiple times, this is + # probably what you want. + # + # If you are looking for a more efficient nixpkgs config, see the + # flake source for notes -- currently you need to include + # clef.overlays.kicad and clef.overlays.nix-filter. + clef.default + ]; + }; + + clefDrv = pkgs.clef { + name = "my_board"; + + # Kicad project directory. Automatically filtered by clef to + # kicad-relevant files. + src = ./.; + + main_pcb = "my_pcb.kicad_pcb"; + main_sch = "my_sch.kicad_sch"; + + outPath = "share/npry/example"; + + layers = 4; + + # Parameters to `kikit panelize -p`. Only required if you want + # to panelize or tile your board. + panelizeConfigs = [ + ":jlcTooling" + ./kikit/jlc_frame.json + ]; + }; + + in { + packages = { + # The main derivation has all of the processed output in it -- + # gerbers, 3d files, SVGs, schematic PDFs, and a panelized + # board (if configured). They are found in the `outPath` you + # configure in the argument attrs. + default = clefDrv; + + # You can use `passthru` attributes to access individual components + # of the build. Outputs are all found as subdirs of + # `share/npry/clef`. + inherit (clefDrv) models; + + # `panelSrc` has the panelized kicad project (new .kicad_pcb with + # the original .kicad_sch and .kicad_pro). + panelizedProject = clefDrv.panelSrc; + + # `panel` is the result of calling `clef` with `src = panelSrc;`, + # i.e. 3d models, fabrication outputs, and so on for the + # panelized board. + inherit (clefDrv) panel; + + # If for you need a recursive panelization, you can in + # principle do that: + panelPanel = (clefDrv.panel.override { + panelizeConfigs = [ ":jlcTooling" ./my_nested_panel_config.json ]; + }).panel; + }; + })); +} +``` + +### direct `callPackage` + +The individual component derivations are intentionally written to be usable +directly: + +```nix +pkgs.callPackage "${clef}/nix/model.nix" { + src = ./.; + pcb_path = "my_pcb.kicad_pcb"; +} +``` + +Bear in mind that you will need the relevant overlays in the calling `nixpkgs` +for this usage mode: + +- `models` needs `clef.overlays.kicad` (adds RapidJSON support to occt, + enabling glb export) +- `fab` wants `clef.overlays.kicad` for a newer version of kikit +- Everything needs `nix-filter`. + +Output for the individual derivations will be found in subdirectories of +`share/npry/clef`, with filenames normalized. + +## etymology + +French: "key", pronounced like "clay". (Cognate with the "clef" of "treble +clef", "bass clef" ~> "treble key", "bass key"). + +Train of thought: KiCad's "Ki" -> "key" -> "clef". |