Ergogen Helper Scripts

Scripts that make working a little bit easier with ergogen (an ergonomic keyboard generator).

The most useful function is that it allows you to restore traces / routing after you re-generate your PCB with ergogen.

1. Installation
   1. Add this repo as a submodule
   2. How to update the submodule
   3. How to clone your ergogen repo
2. Usage
   1. Ergogen Helper Script
      1. Update PCB
      2. Copy Traces
      3. Lock Traces
   2. Makefiles

Installation

Add this repo as a submodule

Add this repo as a git submodule to your ergogen project...

git submodule add git@github.com:infused-kim/kb_ergogen_helper.git resources/kb_ergogen_helper/

Make sure to use the same path resources/kb_ergogen_helper/ or adjust the path in your Makefile later.

That's it, the scripts are now part of your ergogen project.

How to update the submodule

If you want to update to a newer version of this repo...

# Pull updates inside the submodule repo
cd resources/kb_ergogen_helper/
git checkout main
git pull

# Update the submodule in the parent repo
cd ..
git add .
git commit -m "Updated ergogen-helper submodule"

How to clone your ergogen repo

Users who clone your ergogen repo, must also update the submodule. So you should instruct them to either clone with the --recursive mode...

git clone --recursive git@github.com:your-user/your-keyboard.git

Or do init and update the submodules in a repo that was already cloned repo without the --recursive argument...

git clone git@github.com:your-user/your-keyboard.git
cd your-keyboard
git submodule init && git submodule update

Git will load exactly the same version of this helper as the one you used. So you don't need to worry about accidental updates to incompatible future versions.

Usage

Ergogen Helper Script

The python helper script uses the official KiCad python library to make all operations.

Therefore you have to run it using a python environment that has the pcbnew package. The easiest way to do this is to run the script using the python environment that comes bundled with every KiCad install.

On macOS with KiCad 7 you can find it in: /Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3

You can then just run the script:

❯ /Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 resources/kb_ergogen_helper/ergogen_helper.py --help
usage: ergogen_helper.py [-h] [-n BACKUP_NAME] [-b] {copy-traces,lock-traces,update-pcb} ...

Utility to make ergogen keyboard development easier.

optional arguments:
  -h, --help            show this help message and exit
  -n BACKUP_NAME, --backup-name BACKUP_NAME
                        String to append to the filename of the backup (default: orig)
  -b, --no-backup       Skip backup of PCB (default: False)

command:
  {copy-traces,lock-traces,update-pcb}
    copy-traces         Copy traces from source PCB to destination PCB
    lock-traces         Sets all traces inside a KiCad PCB file to locked.
    update-pcb          Update KiCad pcb from v5 to v7 by opening it and saving it again.

In the following examples, I will ommit the full path to the KiCad python binary and instead just use python3.

Note that the --backup-name and --no-backup options can be used with all of the commands. But you have to put them before the command argument.

Update PCB

Ergogen v4 currently generates PCB files in the KiCad v5 format. Every time you open the file, KiCad converts it and then bothers you about needing to save and overwrite the file.

If you run this command as part of your build process, you won't be bothered by KiCad about saving the file when you re-open the PCB file anymore (unless you make actual changes to it in KiCad).

This will also automatically backup the original file that was generated by ergogen to your_pcb_orig.kicad_pcb.

You can skip the backup with the --no-backup option.

❯ python3 resources/kb_ergogen_helper/ergogen_helper.py update-pcb -h
usage: ergogen_helper.py update-pcb [-h] pcb_path

positional arguments:
  pcb_path    The KiCad PCB file path.

optional arguments:
  -h, --help  show this help message and exit

Copy Traces

If you add traces to your PCB in KiCad, ergogen knows nothing about them. So, the next time you run ergogen, it wipes out all your traces.

This command allows you to restore the traces after you re-generate your PCB with ergogen.

It also skips traces if they already exists in the destination PCB so that you can run it multiple times without worry.

❯ python3 resources/kb_ergogen_helper/ergogen_helper.py copy-traces -h
usage: ergogen_helper.py copy-traces [-h] [-u] src_pcb_path dst_pcb_path

positional arguments:
  src_pcb_path         The source PCB file path.
  dst_pcb_path         The destination PCB file path.

optional arguments:
  -h, --help           show this help message and exit
  -u, --unlocked-only  Skip locked traces and only copy unlocked ones (default: False)

Lock Traces

This command will simply mark all traces in the PCB as locked.

This is useful if you are using ergogen footprints that add traces automatically (such as my nice_nano_pretty footprint).

An example build process could be...

• Backup existing pcb files
• Run ergogen
• Lock traces in the ergogen generated file
• Restore only unlocked traces from the previous backup

This way if you move a footprint that contains ergogen-generated traces, you won't end up with two sets of traces for that footprint.

❯ python3 resources/kb_ergogen_helper/ergogen_helper.py lock-traces -h
usage: ergogen_helper.py lock-traces [-h] pcb_path

positional arguments:
  pcb_path    The KiCad PCB file path.

optional arguments:
  -h, --help  show this help message and exit

Makefiles

The best way to run everything I described above is by using a Makefile.

Check out Makefile.example for guidance.

Copy it into the root of your ergogen project. Adjust the variables at the top and then run make help.

It will show you all available commands and a description of what they do.

The help is created with the help of makefile_help.sh.