README.md

Keyboard Compiler Scripts

Scripts for major keyboards designed using the Kiibohd firmware. Please refer to <script> --help for specific details.

Refer to the wiki on setting up your system for compiling. Docker is the recommended environment for manually compiling firmware and running tests.

Build Steps

• Enable the pipenv pipenv install then pipenv shell. You'll get an error complaining about kll missing if you do not do this. There are other ways to get kll in your path (e.g. pip install kll). You will have to remember to keep kll up to date as well (the pipenv will handle this for you).
• Try to build once to make sure your system is setup correctly
• Add any .kll files in the build directory you want
• Edit <script> to include the new .kll files
• Rebuild

Example

./infinity.bash

Projects

• ergodox.bash (Infinity Ergodox, builds both sides)

  • ergodox-l.bash (Left Side)
  • ergodox-r.bash (Right Side)

• infinity.bash (Infinity Keyboard, defaults to Alphabet)

  • infinity.alphabet.bash (Alphabet Layout)
  • infinity.hacker.bash (Hacker Layout)
  • infinity.standard.bash (Standard Layout)

• infinity_led.bash (Infinity Keyboard with LED backlight support (MD1.1), defaults to Alphabet)

  • infinity_led.alphabet.bash (Alphabet Layout)
  • infinity_led.hacker.bash (Hacker Layout)
  • infinity_led.standard.bash (Standard Layout)

• k-type.bash (K-Type Keyboard, Production)

• whitefox.bash (WhiteFox Keyboard, defaults to TrueFox)

  • whitefox.aria.bash (Aria Layout)
  • whitefox.iso.bash (ISO Layout)
  • whitefox.jackofalltrades.bash (Jack Of All Trades Layout)
  • whitefox.truefox.bash (TrueFox Layout)
  • whitefox.vanilla.bash (Vanilla Layout)
  • whitefox.winkeyless.bash (Winkeyless Layout)

Extra files

• cmake.bash (Used by the compilation script, does nothing on it's own)
• common.bash (Script used during CI and testing)
• icpad.bash
• ic_keyboards.bash (Script used during CI and testing)
• k-type.p2.bash (K-Type Prototype 2)
• k-type.p3.bash (K-Type Prototype 3)
• kira.bash
• others.bash (Script used during CI and testing)
• ps2_converter.bash (PS2 Converter for Teensy 3.1/3.2)
• template.bash (Example template for new keyboards)

Tests

• Testing/klltest.bash (Automated KLL Trigger:Result test, uses input KLL files to build test)
• Testing/macrotest.bash (Basic host-side unit-tests)
• Testing/mk20test.bash (mk20dx128vlh7 test build)
• Testing/mk22test.bash (mk22fx512avlh12 test build)
• Testing/mk64test.bash (mk64fx512 Teensy 3.5 test build)
• Testing/mk66test.bash (mk66fx1m0 Teensy 3.6 test build)
• Testing/none.bash (Sanity build using mk20dx128vlf5, useful base for MCU porting)
• Testing/nrf52832.bash (nrf52832 test build)
• Testing/sam4sd32c.bash (sam4sd32c test build)
• Testing/template.bash (Example test template)
• Testing/uartout.bash (Test mk20dx128vlf5 with uartOut Output Module)
• Testing/usbxuart.bash (Test mk20dx128vlf5 with USBxUART Output Module)

Self-Testing a KLL Layout

It's possible to self-test KLL files before loading them onto your keyboard to look for any bugs or functional issues. Normally this isn't required, but it is extremely helpful in isolating bugs to specific KLL expressions. These tests are run automatically for the default layouts, but your own layout may have untested expressions (as it's not possible to test every permutation easily).

Docker is the recommended testing environment. However, as long as your environment is setup correctly running the self-test is quite easy. It runs on Linux, macOS and Cygwin (though Cygwin is tricky to setup and doesn't work well on Travis-CI), just make sure you've installed all the dependencies mentioned in the wiki.

Make sure you can run klltest.bash first before trying out custom KLL layouts.

cd Testing
./klltest.bash

Running just the host-side KLL test script. You can find the test scripts here. In most cases you'll want to use kll.py.

EnableHostOnlyBuild=true HostTest=kll.py ./whitefox.truefox.bash

If there are no errors, then the KLL layout files have no known bugs. Now, if you do find an error, please file an Issue, making sure to include your environment, command you ran, the error message as well as the custom KLL files that were used.

It's also possible to pre-check a firmware build using host-side KLL first.

EnableHostBuild=true HostTest=kll.py ./whitefox.truefox.bash

Example Usage with Web-Configurator Layout Files

An example of how to use these scripts to compile KLL files from the Ergodox configurator

1. Download firmware from GUI.

2. On the cmd line do git clone https://github.com/kiibohd/controller.git

3. create a directory for your layout in controller/kll/layouts called "mine" (just a suggestion)

4. move *.kll files from firmware download into controller/kll/layouts/mine

5. update the BuildPaths and DefaultMap and PartialMaps in ergodox-l.bash and ergodox-r.bash

   1. BuildPath="my_layout-l"
   2. DefaultMap="mine/MDErgo1-Default-0 lcdFuncMap"
   3. PartialMaps[1]="mine/MDErgo1-Default-1 lcdFuncMap"
   4. Repeat PartialMaps[] with a sequential number for each layer you have
   5. BuildPath="my_layout-r"
   6. Take note that all layouts will need the lcdFuncMap added for ErgoDox

6. cd into controller/Keyboards

7. run ./ergodox.bash

8. Upload kiibohd.dfu.bin to the keyboard.