Release version 1.0

Author: sevmeyer

CHANGELOG.md

@@ -1,23 +1,4 @@
-0.3.0 (2022-09-16)
-------------------
+1.0 (2023-10-04)
+----------------
 
-- Implement programmatic construction of 3D printable body
-- Revise layout and layers
-- Add negative tilt for better ergonomics
-- Remove middle arrow keys in favor of layering
-- Remove generated files from repository in favor of release downloads
-- Switch to the CERN-OHL-W license
-
-0.2.0 (2020-10-12)
-------------------
-
-- Extend finger plates towards the middle to simplify the body
-- Add tent crease between pinky and ring finger to reduce height
-- Revise layout and layers
-- Remove unnecessary middle keys
-- Use 1.25u caps for the thumbs to improve comfort and homing accuracy
-
-0.1.0 (2020-07-02)
-------------------
-
-- Initial laser-cut aluminium plates glued on hand-made cork body
+- First release

LICENSE.txt

@@ -1,3 +1,13 @@
+https://github.com/sevmeyer/chrumm-keyboard/
+  ___ _   _ ____  _   _ __  __ __  __
+.' __| |_| |  _ '| | | |  \/  |  \/  |
+| |__|  _  | |_) | |_| | |\/| | |\/| |
+'.___|_| |_|_| \_\.___.|_|  |_|_|  |_|
+
+Copyright 2023 Severin Meyer
+Licensed under CERN-OHL-W v2 or later
+
+
 CERN Open Hardware Licence Version 2 - Weakly Reciprocal
 
 

README.md

@@ -1,139 +1,126 @@
 Chrumm keyboard
 ===============
 
-Chrumm is an ergonomic keyboard prototype, influenced by many
-open hardware projects of the mechanical keyboard community,
-including the [Ergodox], [Dactyl], [Sofle], [Pteron],
-and the works of [Bastardkb].
+Chrumm is an open-hardware ergonomic keyboard,
+made of a 3D-printable body, a bendable PCB,
+and custom firmware for the Raspberry Pi Pico.
 
-The default STL files can be downloaded from the [releases] page.
+This repository contains all relevant source files.
+The generated files can be downloaded from the [releases] page.
 
-**Important:** This project is not yet complete.
-A PCB and new firmware is in the works.
-The default configuration may change.
+I share these files in the hope that they are useful, or
+at least interesting to others. Keep in mind that this is
+a free, do-it-yourself project. What you see is what you get.
+Make sure to check the license.
 
-![Photo of the assembled body](images/body-outside.jpg)
+[releases]: https://github.com/sevmeyer/chrumm-keyboard/releases/
 
-![Photo of the inside](images/body-inside.jpg)
+![Front view of the finished keyboard](images/front.jpg)
 
-[Ergodox]: https://www.ergodox.io/
-[Dactyl]: https://github.com/adereth/dactyl-keyboard
-[Sofle]: https://github.com/josefadamcik/SofleKeyboard
-[Pteron]: https://github.com/FSund/pteron-keyboard
-[Bastardkb]: https://bastardkb.com/
-[releases]: https://github.com/sevmeyer/chrumm-keyboard/releases
-[firmware]: https://github.com/sevmeyer/chrumm-firmware
+![Inside view with installed electronics](images/inside.jpg)
 
 
 Features
 --------
 
-- Reasonably standard layout
-- Columnar stagger
-- Integrated split, tent, and tilt angles
-- Separate tenting for fingers, pinky, and thumb
-- Narrow size to make room for the mouse
-- Firmly attached palm rests
-- Single body and controller
-- Central rotary encoder
-- Designed for FFF 3D printing
-- Parametric construction with Python
-
-
-Printing
---------
-
-I sliced the parts with [PrusaSlicer] and printed them on
-a Prusa Mini+ with PLA filament. Check the prusa directory
-for the configuration files. Other printers and filaments
-may require different settings.
-
-[PrusaSlicer]: https://www.prusa3d.com/prusaslicer/
-
-
-#### Body
-
-The body requires supports on the underside of the key plates,
-split brackets, encoder, and cable hook. The switch notches
-should print fine without supports.
+Chrumm features a column staggered layout with simple thumb clusters.
+The right side has an additional column, to better approximate
+the standard ANSI layout, and to provide dedicated arrow keys.
+A central encoder allows for rotational input.
 
-- Layer height: 0.15mm
-- Perimeters: 2
-- Solid layers: 5 bottom, 5 top
-- Infill: 15% rectilinear
-- Aligned rectilinear top infill (looks nice)
+The body is a robust monoblock without visible screws. It has
+integrated split, tent, and tilt angles, similar to commercial
+ergonomic boards. The palm rests and the USB cable are firmly
+attached, so that everything can be moved around without hassle.
 
-![Supported faces of left body](images/slicer-body.png)
+The STL files are generated programmatically, with a pure
+Python package that has no dependencies. They are optimized
+for FFF 3D printing. Most parts are printed sideways, to
+produce a smooth surface without the need of post-processing.
+Custom supports minimize the print time and filament cost.
 
+The body houses two reversible, bendable, interconnected PCBs.
+They are powered by a Raspberry Pi Pico.
 
-#### Floor
 
-- Layer height: 0.2mm
-- Perimeters: 2
-- Solid layers: 4 bottom, 6 top
-- Infill: 15% rectilinear
-
-
-#### Palm rests
+Credit
+------
 
-The palm rests should be printed sideways, with their inward
-side on the printbed. This ensures that the curved top shell
-is as smooth and robust as possible.
+Chrumm would not exist without the shared knowledge of the
+mechanical keyboard community.
 
-- Layer height: 0.2mm
-- Perimeters: 3
-- Solid layers: 4 bottom, 0 top (rely on overlapping perimeters)
-- Infill: 15% gyroid (omnidirectional strength)
+I found inspiration on [Reddit], [KBD.news], [geekhack], and
+learned a lot from the [PCB guides] by ai03 and Ruiqi Mao, the
+[Keyboard posts] by Masterzen, and the [Matrix Help] by Dave Dribin.
 
-![Sliced left palm rest](images/slicer-palm.png)
+The layout and body is influenced by projects like the [Ergodox],
+[Dactyl], [Sofle], [Pteron], and everything from [Bastardkb].
+I also used established open hardware repositories for reference,
+including the [UHK60], [Skeletyl], [Sofle], [Corne], and [Torn].
 
+[Reddit]: https://old.reddit.com/r/ErgoMechKeyboards+MechanicalKeyboards/
+[KBD.news]: https://kbd.news/
+[geekhack]: https://geekhack.org
+[PCB guides]: https://wiki.ai03.com/books/pcb-design
+[Keyboard posts]: https://www.masterzen.fr/tag/#mechanical-keyboards
+[Matrix Help]: https://www.dribin.org/dave/keyboard/one_html/
+[Ergodox]: https://www.ergodox.io/
+[Dactyl]: https://github.com/adereth/dactyl-keyboard
+[Sofle]: https://github.com/josefadamcik/SofleKeyboard
+[Pteron]: https://github.com/FSund/pteron-keyboard
+[Bastardkb]: https://bastardkb.com/
+[UHK60]: https://github.com/UltimateHackingKeyboard/uhk60v1-electronics
+[Skeletyl]: https://github.com/Bastardkb/Skeletyl-PCB-plate
+[Corne]: https://github.com/foostan/crkbd
+[Torn]: https://github.com/rtitmuss/torn
 
-#### Encoder knob
 
-The encoder knob is printed upside down. It should be solid,
-without infill, to evenly distribute torsional stress.
+Layout
+------
 
-- Layer height: 0.15mm
-- Perimeters: 99
+![Default logical layout with two layers](images/layout.svg)
 
 
-Assembly
+Material
 --------
 
-Electronic parts:
-
-- 72x MX compatible switch
-- 1x EC11 rotary encoder, 12.5x13.2mm, 15mm flatted shaft (D shape), M7 nut mount
-    - Bourns PEC11R-4215F-N0024  (24 detents)
-    - Bourns PEC11R-4115F-N0018  (18 detents)
-    - Bourns PEC11R-4015F-N0024  (no detents)
-    - ...
+Mechanical:
 
-Assembly parts:
+- 12x Threaded insert, M3, 4mm hole diameter, max 5.7mm length
+- 12x Countersunk screw, M3, 8mm total length, ISO 10642
+-  7x Hex nut with nylon insert, M3, ISO 10511
+-  2x Hex nut with nylon insert, M2
+-  7x Socket head cap screw, M3, 8mm thread length, ISO 4762 (*)
+-  2x Socket head cap screw, M2, 6mm thread length, ISO 4762
+-  2x Ziptie, 2mm width, 1mm thickness
+- 14x 3M Bumpon SJ5302, hemispherical, 8mm diameter, 2mm height
+-  2x Artificial leather, ~190x130mm, max 1.2mm thickness
+- Glue for artificial leather on printed filament
 
-- 12x Heat set insert, M3, 4mm length (not longer)
-- 12x Countersunk head screws, ISO 10642, M3, 6mm length
-- Zip ties, 2mm width, 1mm thick
-- Anti-slip rubber feet or foam layer
+Electronic:
 
-Additional parts if the body is split:
+-  2x PCB
+-  1x Raspberry Pi Pico, SC0915, without pre-soldered headers
+-  1x USB cable, A to micro-B with small head, shielded, max 4mm diameter
+- 64x Diode, 1N4148, DO-35 through-hole format
+- 64x MX switch
+-  1x Bourns PEC11R-4215F-N0024 rotary encoder, 15mm flatted D-shaft
+-  1x TE Flexstrip FSN-22A-8, 0.1" pitch, 2" length, 8 conductors (**)
+-  1x TE Flexstrip FSN-22A-5, 0.1" pitch, 2" length, 5 conductors (**)
+-  1x TE Flexstrip FSN-23A-3, 0.1" pitch, 3" length, 3 conductors (**)
 
-- 5x Nylon insert locknut, ISO 10511, M3
-- 5x Button head screws, ISO 7380-1, M3, 8mm length
+(*) Some of the screws are difficult to reach and
+require a ball-point driver, or a short-armed key.
 
-Note that the tenting of the body makes it difficult
-to reach the button head screws in a straight line.
-Use a ball-point driver, or a short-armed key.
+(**) It might be cheaper to buy strips with
+more conductors and cut them apart as needed.
 
 
-Layout
+Images
 ------
 
-![Default key layout](images/layout-default.svg)
+![Print and assembly of the body](images/body.jpg)
 
-For the thumb clusters, I recommend upside-down, 1.25u,
-bottom-row caps from a cylindrical profile (Cherry, OEM).
-With a bit of improvisation, the caps can be sourced from
-a single tenkeyless (TKL) set:
+![Palm rests wrapped with artificial leather](images/palms.jpg)
 
-![Keycap allocation](images/layout-caps.svg)
+![Preparation and installation of the PCB](images/pcb.jpg)

source/.flake8 body/.flake8

@@ -1,7 +1,5 @@
 __pycache__/
 *.py[cod]
-
 *.3mf
-*.gcode
 *.stl
-*.zip
+*.kicad_mod

.gitignore body/.gitignore

@@ -0,0 +1,87 @@
+Chrumm keyboard STL generator
+=============================
+
+The STL files are generated with the `chrumm` package for Python 3.7+.
+It has no dependencies and does not need to be compiled or installed.
+Run it as a command-line tool from this directory:
+
+    python3 -m chrumm --help
+
+To generate the default STL files:
+
+    python3 -m chrumm chrumm.json
+
+To speed up the triangulation during development:
+
+    python3 -m chrumm chrumm.json draft.json
+
+
+Parameters
+----------
+
+The configuration parameters are provided via JSON files.
+If a parameter appears multiple times, then its latest value
+is used. Distances are given in millimeters, angles in degrees.
+
+#### PCB compatibility
+
+Unlike the body, the PCB is manually edited and not programmatic.
+Changes to the body parameters may not be compatible with the PCB.
+A flattened KiCad footprint (.kicad_mod) is generated to help with
+the placement of the switches and screws on the PCB.
+
+#### Parameter validation
+
+The generator does not validate all of the parameters.
+Most importantly, chamfers and switch notches are not
+taken into account when placing the walls. Make sure
+that the switch margin parameter provides enough room.
+
+The generator should produce reasonable results for
+split, tent, and tilt angles up to about 20 degrees.
+Results may vary for more extreme angles.
+
+#### Layout
+
+The `layout.fingerStaggers` matrix represents the
+offset of each key relative to its ortholinear position.
+
+The matrix is a list of rows. Each row contains four
+sublists, to represent the sections of the keyboard
+(left pinky, left alnum, right alnum, right pinky).
+Each section contains key offset coordinates.
+A coordinate can be an empty list (key omitted), a single
+number (y offset), or a list of two numbers (x and y offset).
+
+Each section must have at least two key coordinates.
+All rows must have the same column structure.
+
+#### Omit items
+
+Chamfers can be turned off by setting them to `0`.
+The value of the following parameters can be set
+to `false` in order to omit them from the output:
+
+    bracket
+    bumper
+    cable
+    encoder
+    floor.hexHoles
+    knob
+    palm
+    pcb
+    pcb.mount
+    support
+    switch.clipNotch
+
+
+Print
+-----
+
+I printed the parts on a Prusa Mini, with PLA filament,
+on a smooth PEI sheet. The gcode was generated with
+[PrusaSlicer] 2.6.0. The 3MF files with the exact settings
+are available on the [releases] page.
+
+[PrusaSlicer]: https://www.prusa3d.com/prusaslicer/
+[releases]: https://github.com/sevmeyer/chrumm-keyboard/releases