Klavgen: handwired keyboard generator

Klavgen is a handwired keyboard generator written in Python, on top of CadQuery. It produces keyboards (like on the left) and optionally makes handwiring easy and organized via switch holders (on the right):

<p align="center"> <img src="img/klavyl/front.png" alt="Klavyl" width="350"/> <img src="img/switch_holders.jpg" alt="Switch holders after soldering" width="350"/> </p>

Note: Klavgen is heavily work-in-progress and lots of stuff may not be working. If you experience issues, please submit a Github issue.

Klavgen benefits:

• Generates the full keyboard, including plate, bottom, palm rests and holders for the controller and TRRS/USBC jack
• All models are optimized for home FDM printing with no supports
• Produces slim keyboards: only 11 mm high in the default configuration
• Support Kailh hotswap sockets, with support for MX switches (and very early experimental support for Choc)
• Makes it easy to solder things, and requires no glue whatsoever
• Uses uninsulated wires, thus no tedious wire stripping
• Makes it easy to reposition the keys after making the keyboard
• Produces a sturdy build that doesn't flex when typed on

The last 5 benefits are achieved by optionally using switch holders (MX/Choc) that organize the wires, hold the Kailh sockets and diodes, support the switches, enable soldering everything in place, and allow moving keys later (they even have wire slack so that you can space keys further apart).

Klavgen can also skip the usage of switch holders to generate just a case with normal switch holes.

Note: Choc support is very early and not well tested.

Limitations:

• Configuring a keyboard requires code, it's not as easy as YAML
• Docs are scarce (as you'll see below)

What's new

• Jun 7, 2022: Add support for not using switch holders, therefore generating simple switch holes
• May 20, 2022: Add experimental support for Choc switches; refactor switch holder generation
• May 10, 2022: Improve generation from KLE (http://www.keyboard-layout-editor.com/) (thanks @Tructruc) and support case geometry via the new case_extras parameter
• Apr 25, 2022: Add example STLs and improce docs
• Mar 31, 2022: Initial check-in

Example STL outputs

See the example_stls directory for example STL outputs. These were generated by example.py, see more about that below.

| Component | STL file (for MX build) | Preview | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Bottom | keyboard_bottom.stl | <p align="center"><img src="img/components/bottom.png" alt="Bottom" width="300"/></p> | | Top plate: flat with simple holes so that it can be made with a laser cutter or a CNC machine | keyboard_top.stl | <p align="center"><img src="img/components/top.png" alt="Top" width="300"/></p> | | Palm rest: attaches to the bottom via connectors (can also be fused with the bottom, see below) | palm_rest.stl | <p align="center"><img src="img/components/palm_rest.png" alt="Palm rest back" width="300"/></p> | | Switch holder: Holds the Kailh hotswap socket (MX or Choc) and allows you to solder the diode, column and row wires in-place. These should be printed in ABS since the soldering iron will be close. | switch_holder.stl | <p align="center"><img src="img/components/switch_holder.png" alt="Switch holder" width="200"/></p> | | Pro Micro controller holder: holds the Arduino Pro Micro | controller_holder.stl | <p align="center"><img src="img/components/controller_holder.png" alt="Pro Micro holder" width="200"/></p> | | TRRS jack holder: holds the TRRS jack (if not using USBC) | trrs_jack_holder.stl | <p align="center"><img src="img/components/trrs_jack_holder.png" alt="TRRS jack holder" width="150"/></p> | | USBC jack holder: holds the USBC jack (if not using TRRS) | usbc_jack_holder.stl | <p align="center"><img src="img/components/usbc_jack_holder.png" alt="USBC jack holder" width="150"/></p> | | Connector: connects the palm rest to the bottom | connector.stl | <p align="center"><img src="img/components/connector.png" alt="Connector" width="150"/></p> |

Keyboards generated with Klavgen

Klavyl

Klavyl is my personal keyboard, a modification to Redox. It uses most of Klavgen's capabilities, including screw holes, manually defined case outlines, Pro Micro and USBC jack cutouts and holders, and palm rests. Check out the repo for the full config.

<p align="center"> <img src="img/klavyl/front.png" alt="Klavyl" width="700"/> </p>

Installing

1. Install CadQuery

Install Miniconda and create an environment for CadQuery, following the official instructions.

2. Get comfortable using CadQuery

Get familiar with either of CadQuery's UIs: CQ-editor or jupyter-cadquery (which I prefer).

Ensure that you know how to view objects returned from code, using show_object() in CQ-editor or show() in Jupyter Lab (from jupyter_cadquery.cadquery).

3. Download Klavgen

Klavgen is not yet packaged, so you need to download and use it locally within a project (clone or download and extract the ZIP file; example assumes cloning).

git clone git@github.com:klavgen/klavgen.git

Start your project in the klavgen repo directory. This is where you'll have to write your scripts for now, since you need to import the klavgen package (which is in a sub-dir):

WARNING!!!

CadQuery is very finicky when it comes to filleting (the fillet() command), and sometimes when it comes to shelling (the shell() command). Klavgen tries to provide helpful error messages when CadQuery fails, please follow them. In general, it is highly recommended to always provide the case_extras parameter or use a Patch object to define the outline of your case to ensure there are no small features or holes that can trip filleting or shelling.

If rendering fails in a shell, you should try render_case() with debug=True, which skips the shell step.

The 2 most important fillet settings, CaseConfig.side_fillet and CaseConfig.palm_rests_top_fillet are disabled by default, which makes default keyboards ugly.

These are the main gotchas:

• Shelling fails because your case is not continuous (e.g. the thumb cluster doesn't connect to the main body), has very sharp corners, or has small features.
• Filleting fails because the object has features smaller than the fillet size.
• Filleting succeeds but produces an invalid shape that later on causes errors when operated on (e.g. via a .cut()).

Tutorial

Note that all the show() commands below are meant to illustrate the use in Jupyter Lab. If you use CQ-editor, the commands may differ.

1. Generate a 1-key keyboard case

Run the following code to generate a single-key keyboard (example_1__single_key_render.py):

from klavgen import *

keys = [Key(x=0, y=0)]

case_result = render_case(keys=keys)

The render_case() method is the method you'll use most often while designing the keyboard. It returns a fairly complex RenderCaseResult object which tracks the full progress of the keyboard construction to help you in fixing issues.

Note: You can pass in a RenderCaseResult object as the result parameter. Then, render_case() will save intermediate objects to the passed-in variable while rendering is taking place, allowing you to observe what happened if rendering raises an exception.

Here, we'll only focus on these 3 keys part in the result object:

• case_result.top is the top plate (show(case_result.top))

<p align="center"> <img src="img/simple/simp