@TildeWill's ergogen PCB footprints

Warning

These footprints have only been partially tested and are still under active development. Use them at your own risk.

1. Installation
   1. How to add the footprints as a local git submodule
   2. How to add the footprints as a GitHub Codespaces git submodule
   3. How to use the footprints in your ergogen config
   4. How to clone your ergogen repo
   5. How to update footprints dependencies
   6. How to remove footprints dependencies
2. How to design or modify ergogen footprints
3. Licenses and recognition

Installation

How to add the footprints as a local git submodule

Warning

If you are using GitHub Codespaces, skip the following instructions and go to the next section.

If you have git setup on your local environment with SSH credentials, you can add the library as a git submodule. To use custom footprint, ergogen requires them to be located under a folder named footprints placed alongside a config.yaml file containing the board definition.

Assuming the above files are located at ./ergogen from the git folder root, then you can use this command to add the footprints into a tildewill folder in the right location:

git submodule add git@github.com:tildewill/ergogen_footprints.git ergogen/footprints/tildewill

Note that you can customize tildewill to be whatever name you choose. Just make sure to refer to the custom name in your YAML file.

How to add the footprints as a GitHub Codespaces git submodule

Due to the limitations on how GitHub Codespaces handle submodules, use this command instead of the one above:

git submodule add https://github.com/tildewill/ergogen_footprints.git ergogen/footprints/tildewill

How to use the footprints in your ergogen config

Assuming you used ergogen/footprints/tildewill as the destination folder for the submodule, you will be able to refer to any footprint contained in that folder as tildewill/[footprint_filename], which would look something like this:

[...]
pcbs:
  your_keyboard:
    outlines:
      [...]
    footprints:
      nice_nano:
        what: tildewill/nice_nano
        [...]

How to clone your ergogen repo

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

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

Alternative they can init and update the submodules in a repo that was already cloned without the --recursive argument:

git submodule update --init --recursive --remote

How to update footprints dependencies

When you add a submodule, it won't automatically be updated, meaning that you will maintain files as long as you don't take specific actions. This is great to avoid having to deal with unforseen changes in the source.

Should you however want to update your footprint dependencies, you can run the following command:

git submodule update --recursive --remote

This will fetch and checkout the latest commits in the source repo and pull the files so they are available.

Be aware that you will need to commit the submodule update change, or it will revert with a subsequent pull. To do so you can run these commands:

# First add the updated submodule to the staged files
git add ergogen/footprints/tildewill
# Then commit the staged files to persist the update
git commit -m "Update footprint submodule"

How to remove footprints dependencies

If you do not longer need the footprint submodule and want to remove it from your repository, you can simply run this command:

git rm ergogen/footprints/tildewill

This will update the .gitmodules file to remove the submodule reference and remove the submodule directory. Make sure to commit and push the change for it to be persisted and propagated, or it will revert with a subsequent pull:

git commit -m "Remove footprint submodule"

How to design or modify ergogen footprints

@infused-kim wrote a guide on how to convert KiCad footprints to ergogen, which has been extensively used to create original ergogen footprints in this repository.

Licenses and recognition

Furthermore, all of the work I've done wouldn't have been possible without the inspiration or direct reference to the work done by:

• @ceoloide for documenting this pattern for external footprints so well and their excellent ergogen boards
• @flatfootfox for the Ergogen v4 introductory articles
• MrZealot / @ergogen for ergogen itself and building an amazing community
• @benvallack for the great keeb content on YouTube