kb_builder

kb_builder is the original engine that ran builder.swillkb.com. That service has been completely rewritten in Golang, but this project is still a useful environment to hack on.

This tool uses the JSON layout generated by the Keyboard Layout Editor. There are a lot of hidden features that you can do when building plates. Check the ? next to the Plate Layout text field in the UI for more details.

Here are the features that are exposed. The following features can be applied by modifying the source copied from the keyboard layout editor. All of these features are applied to individual keys by adding or modifying the object before the key. EG: rotate switch for "Enter" would be done by entering {_r:90},"Enter".

{_t:<cutout>}: Change switch cutout type. mx, alpsmx, mx-open, mx-open-rotatable, or alps. EG: {_t:"mx"},""
{_s:<stab>}: Change stabilizer cutout type. cherry, costar, cherry-costar, alps, or matias. EG: {_s:"costar"},""
{_k:<mm>}: Specify a kerf value for this specific switch/stabilizer cutout which overrides the default. Values are in mm (without the * unit). EG: {_k:0.05},""
{_r:<degrees>}: Rotate the switch cutout independent of the stabilizer cutout (assuming there is one). EG: {_r:90},""
{_rs:<degrees>}: Rotate the stabilizer cutout independent of the switch cutout. EG: {_rs:180},""
{_co:<mm>}: Specify that this switch is offset within the stabilizer. EG: {_co:9.525},""

This tool is implemented as both a webserver which exposes a UI to be consumed in the browser and a CLI that can be run from the shell. The web server is not fit for actual web traffic because it can not handle drawing more than one layout at a time. This however should not be a limitiation for personal use.

At this time the CLI is more fully-featured than the Web UI. That is considered a bug and is being worked on. If you think you can help submit a pull request. :)

Global Keyboard Properties

Your layout can include a dictionary as one row to set global keyboard options. The available options are documented here.

Default Properties:

{
    "name": <sha_hash_of_layout>,
    "case_type": "none",
    "key_spacing": 19.05,
    "switch": "mx",
    "stabilizer": "cherry",
    "layers": {
        'switch': {}
    }
}

name

Setting this value sets the name your plate files will be exported to. The filename will be {name}/{layer}_layer.{format}.

case_type

none: Cut each layer with no screw holes
poker: Cut each layer with screw holes to fit a poker-style 60% case
sandwich: Cut each layer with screw holes designed for a sandwich style case

corner_type

If specified, cut the corners so they are not 90 degrees.

Available corner_types:

round: Rounded corners.
bevel: Cut off corners with 45 degree angles.

corner_radius

The radius for rounded or beveled corners.

feet

Specify the case foot properties. This should be a dictionary with "width" at minimum. The following values are available:

width: How wide the feet will be. They will end up ~10-18mm wider to account for the hex ends. Required.
screw_offset: How far out from center to place the screw holes on the feet. Defaults to width-3.
draw_offset: Offset from center where the feet are drawn. Defaults to [0,0]
top_foot: The x,y offset from center for the top foot. Defaults to [0,-25]
bottom_foot: The x,y offset from center for the bottom foot. Defaults to [0,25]

Example:

    "feet": {
        "width": 240,
        "draw_offset": [30,0],
        "top_foot": [0,-25],
        "bottom_foot": [0,25]
    }

kerf

Adjust the drawing to account for the width of the cutting instrument. If this is set to a non-zero value the drawing will be generated so that a cutting implement this many MM wide can trace the center of the lines and the plate will come out to exactly the right dimensions.

key_spacing

How much space (in MM) between switch centers.

padding

This sets the padding for both width and height. This is how wide the "open" ond "closed" layers will end up. It should be a two item list consisting of: [width,height]

Exmaple: "padding": [4,4]

pcb_padding

This is to accommodate the PCB for both width and height. It should be a two item list consisting of: [width,height]

Example: "pcb_padding": [4,4]

screw

Specify the properties for the screw holes. Only used by sandwich cases. The following values are available:

count: The number of screw holes to put into the case. Must be set to an even integer >= 4. Default: 4
offset: The distance from the edge of the plate to place the screw holes. Default: 4 * radius (Warning: Not yet implemented)
radius: The radius in MM for the screw holes. Default: 2

Example:

    "screw": {
        "count": 6,
        "radius": 5
    }

stabilizer

What type of stabilizer this plate/case uses.

Available stabilizers:

alps: Traditional alps-style stabilizers
cherry: Cherry plate or PCB mount stabilizers
cherry-costar: Cherry and costar compatible stabilizers
costar: Costar stabilizers
matias: Alps stibilizers for 2U/2.25U/2.75U keys, Costar for larger keys

switch

What type of switch cutout to use on this plate/case.

Available switches:

alps
alpsmx
mx
mx-open
mx-open-rotatable

layers

Setting up a layers dictionary allows you to specify which layers will be drawn, as well setting values for that layer. There are a few options that apply to every layer, and some options that only apply to certain layers. If you don't specify any layers, only a switch plate will be generated.

Available layers:

simple: Only the outline of the plate and screw holes. Can be used as a blank canvas.
bottom: A bottom plate. Can optionally add USB and foot cutouts.
closed: A plate with a cutout in the middle to make a frame out of.
open: A closed plate with a cutout to accommodate a USB plug and/or cord.
reinforcing: A switch plate with larger cutouts to go between the switch plate and PCB. Can be used to provide more support when a 1.5mm acrylic plate is to be cut.
switch: The plate that switches snap into.
top: A plate to sit on top of the switch plate for people who do not want the floating keys look.

layer -> inset

When set to true, the outline for this layer will be identical to the interior cutout on a "closed" layer. This will allow the plate to be inset within an open or closed layer.

No screw holes will be drawn.

If both inset and oversize are set, and oversize is a positive value, the plate will not fit within the open/closed layer.

layer -> holes

The holes list allows you to specify holes to be cut in this layer. If you place a hole inside an existing cutout the hole will not appear on the final drawing.

This should be a list of lists, with each internal list consisting of [x,y,radius]. The x,y coordinates are measured in MM from the top left corner. (NOTE: This will change to be from the center of the layout in a future release.)

You may specify this for any layer.

layer -> polygons

The polygons list allows you to specify polygons to be cut in this layer. If you place a polygon inside an existing cutout it will not appear on the final drawing.

This should be a list of list of lists. The innermost list is an individual polygon coordinate (x,y). The middle list is a list of polygon coordinates- the first and last element should normally be the same point.

You may specify this for any layer.

layer -> oversize

If this is set to a non-zero value this layer will be made that many MM bigger, while keeping the screw holes in the same location relative to the center of the plate.

You may specify this for any layer.

layer -> usb_cutout

If set to true the USB cutout will be included on this layer.

layer -> thickness

How thick this plate should be.

Default for each plate:

simple: 3mm
bottom: 3mm
middle: 9mm
reinforcing: 3mm
switch: 1.5mm
top: 3mm

usb

This is a dictionary that sets the properties for the USB cutout.

Options:

inner_width: How wide the cutout should be on the interior edge of the plate.
outer_width: How wide the cutout should be on the exterior edge of the plate.
height: How far below the "outer_width" line to extend the cutout on the bottom layer.
offset: How for from the center-point to place the USB cutout.

Example:

{
    'inner_width': 10,
    'outer_width': 15,
    'height': 5,
    'offset': 25
}

Keyboard Properties Example

This dictionary sets every available option.

{
    "name": "example_keyboard",
    "case_type": "sandwich",
    "corner_type": "round",
    "corner_radius": 4,
    "feet": {
      "width": 250,
      "draw_offset": [-20,0],
      "screw_offset": 60,
      "top_foot": [0,-32.25],
      "bottom_foot": [0,25]
    },
    "kerf": 0.1,
    "key_spacing": 19,
    "padding": [10,10],
    "pcb_padding": [2,5],
    "screw" {
        "count": 8,
        "radius": 2,
    },
    "switch": "alps",
    "stabilizer": "matias",
    "layers": {
        "simple": {
            "holes": [[5,5,2]],
            "polygons": [[[1,1], [-1,1], [-1,-1], [-1,1], [1,1]]]
        },
        "bottom": {
            "holes": [[5,5,2]],
            "polygons": [[[1,1], [-1,1], [-1,-1], [-1,1], [1,1]]],
            "screw": {
              "radius": 1.5
            },
            "usb_cutout": true
        },
        "middle": {
            "holes": [[5,5,2]],
            "oversize": 3,
            "polygons: [[[1,1], [-1,1], [-1,-1], [-1,1], [1,1]]],
            "usb_cutout": true
        },
        "reinforcing": {
            "inset": True,
            "holes": [[5,5,2]],
            "polygons": [[[1,1], [-1,1], [-1,-1], [-1,1], [1,1]]],
            "usb_cutout": false
        },
        "switch": {
            "holes": [[5,5,2]],
            "polygons": [[[1,1], [-1,1], [-1,-1], [-1,1], [1,1]]],
            "usb_cutout": true
        },
        "top": {
            "holes": [[5,5,2]],
            "polygons": [[[1,1], [-1,1], [-1,-1], [-1,1], [1,1]]],
            "usb_cutout": true
        }
    },
    "usb": {
      "inner_width": 11,
      "outer_width": 16,
      "height": 5,
      "offset": 135
    }
}

Installation and Configuration

Install this one a Ubuntu VM on your laptop with either VirtualBox or VMware Fusion. I have had trouble getting the FreeCAD lib to work correctly on Mac OSX, so if you get it working, please contribute some documentation. For now I only describe Ubuntu install instructions.

Install the dependencies

$ sudo apt-get install software-properties-common
$ sudo add-apt-repository ppa:freecad-maintainers/freecad-daily
$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt-get -y install unzip build-essential freecad git python-pip python-dev python-flask
$ sudo pip install cadquery hjson
$ sudo pip install nose2 cov-core  # Optional, used for unit testing

Install the Draft-dxf-importer

This is a quick start guide. Review the full docs here

$ cd ~/
$ freecad
	# note the version number
	# download the appropriate version from here: 
	# 	https://github.com/yorikvanhavre/Draft-dxf-importer
	# i will assume freecad version v16 and the latest importer (v15)
$ wget https://github.com/yorikvanhavre/Draft-dxf-importer/archive/1.38.zip
$ unzip 1.38.zip
	# this will create the 'Draft-dxf-importer-1.38/' directory
$ cp Draft-dxf-importer-1.38/* /root/.FreeCAD/
	# Note: we are putting this import into the 'root' users '.FreeCAD' 
	#	not your users because we are running with 'sudo'

Get the source

$ git clone https://github.com/swill/kb_builder.git ~/kb_builder

Testing the tool (optional)

If you want to run the included unit/integration tests you can use nose2.

$ cd ~/kb_builder
$ nose2

There will be a lot of output, and at the end it will print OK. If it instead prints out FAILED you may have a problem with your environment.

Running the tool

There are two ways to use the tool. You can use the Web UI through your browser, or the CLI in Terminal.

Using the Web Frontend

$ cd ~/kb_builder
$ ./kb_web

Accessing the UI

I am assuming most people will be using VirtualBox, so here are some additional details for viewing the UI from the host machine as well as instructions for how to SSH into the box.

# Power off the VM.
# Set: VM > Settings > Network > Attached to: => Bridged Adapter
# Power on the VM.
$ ifconfig
	# record the <IP> address
# The web UI will be available on: http://<IP>
# You can SSH to the VM with: ssh your_user@<IP>

Using the CLI

If you don't want to fire up the web interface you can generate files locally using the CLI. There are lots of options for tweaking your plate and generating cases, please review "./kb_cli -h" to see all the options you can set.

In the simplest case you simply run "./kb_cli -f " to generate a plate:

zwhite@ubuntu:~/kb_builder$ ./kb_cli -f cnc_pad.kle
FreeCAD 0.16, Libs: 0.16R5701 (Git)
...
Writing STEP file......
Face...

*******************************************************************
******        Statistics on Transfer (Write)                 ******

*******************************************************************
******        Transfer Mode = 0  I.E.  As Is       ******
******        Transferring Shape, ShapeType = 0                      ******
** WorkSession : Sending all data
 Step File Name : /home/zwhite/kb_builder/static/exports/switch_cnc_pad.kle.stp(15006 ents)  Write  Done
saving......
processing Shape				(99.0 %)
successfully exported /home/zwhite/kb_builder/static/exports/switch_cnc_pad.kle.dxf
**** Overall plate size: 103.25 x 103.25 mm
*** Files exported for plate switch
* static/exports/switch_cnc_pad.kle.js
* static/exports/switch_cnc_pad.kle.brp
* static/exports/switch_cnc_pad.kle.stp
* static/exports/switch_cnc_pad.kle.stl
* static/exports/switch_cnc_pad.kle.dxf
* static/exports/switch_cnc_pad.kle.json

License

kb_builder builts keyboard plate and case CAD files using JSON(-like) input.

Copyright (C) 2015  Will Stevens (swill)

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
src/kb_builder		src/kb_builder
static		static
templates		templates
test_exports		test_exports
.gitignore		.gitignore
LICENSE.txt		LICENSE.txt
README.md		README.md
kb_cli		kb_cli
kb_web		kb_web
nose2.cfg		nose2.cfg
test_all_shapes.kle		test_all_shapes.kle
test_numpad.kle		test_numpad.kle

License

skullydazed/kb_builder

Folders and files

Latest commit

History

Repository files navigation

kb_builder

Global Keyboard Properties

name

case_type

corner_type

corner_radius

feet

kerf

key_spacing

padding

pcb_padding

screw

stabilizer

switch

layers

layer -> inset

layer -> holes

layer -> polygons

layer -> oversize

layer -> usb_cutout

layer -> thickness

usb

Keyboard Properties Example

Installation and Configuration

Install the dependencies

Install the Draft-dxf-importer

Get the source

Testing the tool (optional)

Running the tool

Using the Web Frontend

Accessing the UI

Using the CLI

License

About

Resources

License

Stars

Watchers

Forks

Languages