# 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".