|
|
@@ -1,750 +0,0 @@ |
|
|
|
The Kiibohd Controller |
|
|
|
====================== |
|
|
|
|
|
|
|
This README is a bit long, just look at the sections you are interested in. |
|
|
|
You only need to install avr-gcc if you want to build for the Teensy 2.0/2.0++. |
|
|
|
Everything else needs an arm-none-eabi-gcc compiler (e.g. Infinity keyboard, |
|
|
|
Teensy 3.0/3.1, McHCK). |
|
|
|
|
|
|
|
Linux is the ideal build environment (preferably recent'ish). In the near |
|
|
|
future I'll make available an Arch Linux VM for building/manufacturing tests. |
|
|
|
|
|
|
|
Building on Mac should be ok for 99% of users with Macports or Homebrew. For |
|
|
|
Homebrew, use `brew tap PX4/homebrew-px4` to get the arm-none-eabi-gcc installer. |
|
|
|
The dfu Bootloader will not build correctly with the old version of |
|
|
|
arm-none-eabi-gcc that Macports currently has (4.7.3). This is due to a bug |
|
|
|
with lto (link time optimizations) which makes the resulting binary too big to |
|
|
|
fit on the chip (must be less than 4096 Bytes). |
|
|
|
|
|
|
|
Building on Windows should also be fine for 99% of users, but takes a bunch of |
|
|
|
work to setup (because Windows is a crappy dev environment). Cygwin is |
|
|
|
currently required along with some non-Cygwin compilers and utilities (because |
|
|
|
they are not available for Cygwin). The dfu Bootloader will not build because |
|
|
|
of a Make 3.81+ bug/feature that removed support for non-Unix (Windows) |
|
|
|
filenames as dependencies of targets. If you [replace the version of Make in |
|
|
|
Cygwin](http://stackoverflow.com/questions/601516/cygwin-make-error-target-pattern-contains-no) |
|
|
|
it should work. However, make sure that the flash size is no larger than 4096 |
|
|
|
Bytes or the bootloader will not work. Things will likely break if there are |
|
|
|
**SPACES IN YOUR PATHS**. I install cygwin to `C:\cygwin64`. If you are brave |
|
|
|
and have programming knowledge, I will accept patches to fix any issues |
|
|
|
regarding spaces in paths. |
|
|
|
|
|
|
|
Please give authors credit for modules used if you use in a distributed |
|
|
|
product :D |
|
|
|
|
|
|
|
|
|
|
|
General Dependencies |
|
|
|
-------------------- |
|
|
|
|
|
|
|
Below listed are the Arch Linux pacman names, AUR packages may be required. |
|
|
|
|
|
|
|
These depend a bit on which targets you are trying to build, but the general |
|
|
|
one: |
|
|
|
|
|
|
|
- cmake (2.8 and higher) |
|
|
|
- git |
|
|
|
- ctags (recommended, not required) |
|
|
|
- python3 |
|
|
|
- libusb1.0 (and -devel) |
|
|
|
- make |
|
|
|
|
|
|
|
AVR Specific (Teensy 1.0/++,2.0/++) (try to use something recent, suggested |
|
|
|
versions below) |
|
|
|
|
|
|
|
- avr-gcc (~4.8.0) |
|
|
|
- avr-binutils (~2.23.2) |
|
|
|
- avr-libc (~1.8.0) |
|
|
|
|
|
|
|
ARM Specific (Teensy 3.0/3.1, Infinity Keyboard, McHCK) |
|
|
|
|
|
|
|
- Arch Linux / Mac Ports |
|
|
|
- arm-none-eabi-gcc |
|
|
|
- arm-none-eabi-binutils |
|
|
|
|
|
|
|
- Windows (https://launchpad.net/gcc-arm-embedded/+download) |
|
|
|
- gcc-arm-none-eabi (win32.zip) |
|
|
|
|
|
|
|
|
|
|
|
Windows Setup |
|
|
|
------------- |
|
|
|
|
|
|
|
Compiling on Windows does work, just it's a bunch more work. |
|
|
|
|
|
|
|
First make sure Cygwin is installed - http://www.cygwin.com/ - 32bit or 64bit |
|
|
|
is fine. Make sure the following are installed: |
|
|
|
|
|
|
|
- make |
|
|
|
- git (needed for some compilation info) |
|
|
|
- cmake |
|
|
|
- gcc-core |
|
|
|
- gcc-g++ |
|
|
|
- libusb1.0 |
|
|
|
- libusb1.0-devel |
|
|
|
- python3 |
|
|
|
- ctags (recommended, not required) |
|
|
|
|
|
|
|
Please note, I use cygwin term exclusively for any command line options. |
|
|
|
Unless mentioned otherwise, use it. Do NOT use CMD or Powershell. |
|
|
|
|
|
|
|
Also install the [Windows version of CMake](http://cmake.org/cmake/resources/software.html) |
|
|
|
(3+ is ideal) - Select "Do not add CMake to system PATH". This is in addition |
|
|
|
to the Cygwin version. This is an easier alternative to installing another C |
|
|
|
compiler. Add the following line to your .bashrc, making sure the CMake path |
|
|
|
is correct: |
|
|
|
|
|
|
|
echo "alias wincmake=\"PATH='/cygdrive/c/Program Files (x86)/CMake'/bin:'${PATH}' cmake -G 'Unix Makefiles'\"" >> ~/.bashrc |
|
|
|
|
|
|
|
Install the [PJRC Virtual Serial Port Driver](http://pjrc.com/teensy/serial_install.exe). |
|
|
|
|
|
|
|
Next, install the compiler(s) you want. |
|
|
|
|
|
|
|
|
|
|
|
### AVR GCC |
|
|
|
|
|
|
|
You just need the |
|
|
|
[Atmel AVR 8-bit Toolchain](http://www.atmel.com/tools/atmelavrtoolchainforwindows.aspx). |
|
|
|
The latest should be fine, as of writing it was 3.4.3. |
|
|
|
|
|
|
|
Extract the files to a directory, say `C:\avr8-gnu-toolchain`. Then copy all |
|
|
|
the folders in that directory to the Cygwin `/usr/local` directory. Mine is |
|
|
|
`C:\cygwin64\usr\local`. (You can also just setup the paths, but this is |
|
|
|
faster/simpler. Might screw up your Cygwin though). |
|
|
|
|
|
|
|
|
|
|
|
### ARM EABI |
|
|
|
|
|
|
|
Download the latest |
|
|
|
[GNU Tools for Embedded Processors |
|
|
|
gcc-arm-none-eabi](https://launchpad.net/gcc-arm-embedded/+download). |
|
|
|
|
|
|
|
Download `gcc-arm-none-eabi*win32.zip`. |
|
|
|
|
|
|
|
Then extract all the folders/files in the zip to the Cygwin `/usr/local` |
|
|
|
directory. Mine is `C:\cygwin64\usr\local`. Or, you can setup paths using |
|
|
|
the installer (you have to be more careful, avoid spaces in paths). |
|
|
|
|
|
|
|
|
|
|
|
CMake Info |
|
|
|
---------- |
|
|
|
|
|
|
|
One of the big benefits of using CMake is the ability to build multiple |
|
|
|
configurations (for different microcontrollers) at the same time. The |
|
|
|
following sections explain in detail what each CMakeLists.txt configuration |
|
|
|
option does and what you can change it to. However, it is possible to |
|
|
|
configure each of these options using the `-D` command line flag. |
|
|
|
|
|
|
|
For example, to build the Infinity Keyboard default configuration: |
|
|
|
|
|
|
|
```bash |
|
|
|
$ mkdir build_infinity |
|
|
|
$ cd build_infinity |
|
|
|
$ cmake -DCHIP=mk20dx128vlf5 -DScanModule=MD1 -DMacroModule=PartialMap \ |
|
|
|
-DOutputModule=pjrcUSB -DDebugModule=full -DBaseMap=defaultMap \ |
|
|
|
-DDefaultMap="md1Overlay stdFuncMap" -DPartialMaps="hhkbpro2" \ |
|
|
|
.. |
|
|
|
$ make |
|
|
|
``` |
|
|
|
|
|
|
|
CMake defaults to the values specified in CMakeLists.txt if not overridden via |
|
|
|
the command line. |
|
|
|
|
|
|
|
> NOTE: On Windows, you will have to use "wincmake" instead of "cmake". |
|
|
|
|
|
|
|
|
|
|
|
Selecting Microcontroller |
|
|
|
------------------------- |
|
|
|
|
|
|
|
This is where you select the chip you want to compile for. The build system |
|
|
|
will automatically select the compiler needed to compile for your chip. |
|
|
|
|
|
|
|
Open up CMakeLists.txt in your favourite text editor. You are looking for: |
|
|
|
|
|
|
|
```cmake |
|
|
|
### |
|
|
|
# Chip Selection |
|
|
|
# |
|
|
|
|
|
|
|
#| You _MUST_ set this to match the microcontroller you are trying to compile for |
|
|
|
#| You _MUST_ clean the build directory if you change this value |
|
|
|
#| |
|
|
|
set( CHIP |
|
|
|
# "at90usb162" # Teensy 1.0 (avr) |
|
|
|
# "atmega32u4" # Teensy 2.0 (avr) |
|
|
|
# "at90usb646" # Teensy++ 1.0 (avr) |
|
|
|
# "at90usb1286" # Teensy++ 2.0 (avr) |
|
|
|
# "mk20dx128" # Teensy 3.0 (arm) |
|
|
|
"mk20dx128vlf5" # McHCK mk20dx128vlf5 |
|
|
|
# "mk20dx256" # Teensy 3.1 (arm) |
|
|
|
CACHE STRING "Microcontroller Chip" ) |
|
|
|
``` |
|
|
|
|
|
|
|
Just uncomment the chip you want, and comment out the old one. |
|
|
|
|
|
|
|
> NOTE: If you change this option, you will *need* to delete the build |
|
|
|
> directory that is created in the Building sections below. |
|
|
|
|
|
|
|
|
|
|
|
Selecting Modules |
|
|
|
----------------- |
|
|
|
|
|
|
|
> WARNING: Not all modules are compatible, and some modules may have |
|
|
|
> dependencies on other modules. |
|
|
|
|
|
|
|
This is where the options start getting interesting. The Kiibohd Controller |
|
|
|
is designed around a set of 4 types of modules that correspond to different |
|
|
|
functionality: |
|
|
|
|
|
|
|
- Scan Module |
|
|
|
- Macro Module |
|
|
|
- Output Module |
|
|
|
- Debug Module |
|
|
|
|
|
|
|
The Scan Module is where the most interesting stuff happens. These modules |
|
|
|
take in "keypress data". A converter Scan Module will interpret a protocol |
|
|
|
into key press/releases. A matrix Scan Module may inherit from the matrix |
|
|
|
module to scan keypress from a matrix This module just has to give |
|
|
|
press/release codes, but does have some callback control to other modules |
|
|
|
depending on the lifecycle for press/release codes (this can be very |
|
|
|
complicated depending on the protocol). Each Scan Module has it's own default |
|
|
|
keymap/modifier map. (TODO recommend keymap changing in the Macro Module). |
|
|
|
|
|
|
|
Some scan modules have very specialized hardware requirements, each module |
|
|
|
directory should have at least a link to the needed parts and/or schematics |
|
|
|
(TODO!). |
|
|
|
|
|
|
|
The Macro Module takes care of the mapping of the key press/release code into |
|
|
|
an Output (USB) scan code. Any layering, macros, keypress |
|
|
|
intelligence/reaction is done here. |
|
|
|
|
|
|
|
The Output Module is the module dealing with output from the microcontroller. |
|
|
|
Currently USB is the only output protocol. Different USB output |
|
|
|
implementations are available, pjrc being the safest/least featureful one. |
|
|
|
Debug capabilities may depend on the module selected. |
|
|
|
|
|
|
|
The Debug Module enables various things like the Teensy LED on errors, debug |
|
|
|
terminal output. (TODO get true UART working in avr, not just arm) |
|
|
|
|
|
|
|
Open up CMakeLists.txt in your favourite text editor. Look for: |
|
|
|
|
|
|
|
```cmake |
|
|
|
### |
|
|
|
# Project Modules |
|
|
|
# |
|
|
|
|
|
|
|
#| Note: This is the only section you probably want to modify |
|
|
|
#| Each module is defined by it's own folder (e.g. Scan/Matrix represents the "Matrix" module) |
|
|
|
#| All of the modules must be specified, as they generate the sources list of files to compile |
|
|
|
#| Any modifications to this file will cause a complete rebuild of the project |
|
|
|
|
|
|
|
#| Please look at the {Scan,Macro,Output,Debug} for information on the modules and how to create new ones |
|
|
|
|
|
|
|
##| Deals with acquiring the keypress information and turning it into a key index |
|
|
|
set( ScanModule "MD1" |
|
|
|
CACHE STRING "Scan Module" ) |
|
|
|
|
|
|
|
##| Provides the mapping functions for DefaultMap and handles any macro processing before sending to the OutputModule |
|
|
|
set( MacroModule "PartialMap" |
|
|
|
CACHE STRING "Macro Module" ) |
|
|
|
|
|
|
|
##| Sends the current list of usb key codes through USB HID |
|
|
|
set( OutputModule "pjrcUSB" |
|
|
|
CACHE STRING "Output Module" ) |
|
|
|
|
|
|
|
##| Debugging source to use, each module has it's own set of defines that it sets |
|
|
|
set( DebugModule "full" |
|
|
|
CACHE STRING "Debug Module" ) |
|
|
|
``` |
|
|
|
|
|
|
|
Look at each module individually for it's requirements. There is |
|
|
|
chip/architecture dependency checking but some permutations of modules may not |
|
|
|
be tested/compile. |
|
|
|
|
|
|
|
There are also CMake options for temporarily selecting modules. But it's |
|
|
|
easier to just edit the file. e.g. `cmake -DScanModuleOverride=<module name>`. |
|
|
|
|
|
|
|
|
|
|
|
Keymap Configuration |
|
|
|
-------------------- |
|
|
|
|
|
|
|
This is where you define the layout for your keyboard. |
|
|
|
Currently, the only way to define kebyoard layouts is using [KLL](https://www.overleaf.com/read/zzqbdwqjfwwf). |
|
|
|
|
|
|
|
KLL is built up of 3 different kinds of keymaps in total. |
|
|
|
The BaseMap, DefaultMap and PartialMaps. |
|
|
|
|
|
|
|
For each type of keymap, it is possible to combine multiple .kll files together to create new ones using |
|
|
|
the compiler. The order of the files matter, as the right-most file will overwrite any setting in the |
|
|
|
previous files. |
|
|
|
|
|
|
|
> NOTE: Each keymap is done after the entire file is processed. This means that within the file the order |
|
|
|
> of assignment doesa *not* matter (if you assign the same thing twice, then yes the most recent one |
|
|
|
> takes priority). |
|
|
|
|
|
|
|
|
|
|
|
BaseMap defines what the keyboard can do. This includes specific capabilities of the keyboard (such as USB), |
|
|
|
the mapping of Scan Codes to USB Codes and any specific configurations for the keyboard. |
|
|
|
In general, the BaseMap rarely needs to be changed. Usually only when adding a new keyboard to the firmware |
|
|
|
does the Basemap need any modification. |
|
|
|
The BaseMap is what both DefaultMap and PartialMaps are based upon. This allows for a common reference |
|
|
|
when defining custom keymappings. |
|
|
|
|
|
|
|
> NOTE: Don't use defaultMap.kll to change your layouts. This will work, but they will not be portable. |
|
|
|
|
|
|
|
|
|
|
|
The DefaultMap is the normal state of the keyboard, i.e. your default layer. |
|
|
|
Using the BaseMap as a base, the DefaultMap is a modification of the BaseMap to what the keyboard should do. |
|
|
|
Since the DefaultMap uses USB Code to USB Code translations, this means that keymaps used for one keyboard |
|
|
|
will work with another keyboard. |
|
|
|
For example, I use Colemak, so this means I only have to define Colemak once for every keyboard that supports |
|
|
|
the kiibohd firmware. This is possible because every BaseMap defines the keyboard as a US ANSI like keyboard |
|
|
|
layout. |
|
|
|
The DefaultMap can also be thought of as Layer 0. |
|
|
|
|
|
|
|
|
|
|
|
PartialMaps are optional keymaps that can be "stacked" on top of the DefaultMap. |
|
|
|
They can be dynamically swapped out using the layer control capabilities: |
|
|
|
|
|
|
|
- layerLatch( `<layer number>` ) |
|
|
|
- layerLock( `<layer number>` ) |
|
|
|
- layerShift( `<layer number>` ) |
|
|
|
|
|
|
|
layerShift is usually what you want as it works just like a standard shift key. |
|
|
|
layerLock is similar to the CapsLock key. While layerLatch is a latch, where only the next key you press |
|
|
|
will use that layer (e.g. stickykeys). |
|
|
|
|
|
|
|
A unique aspect of KLL layers is that it's a true stack of layers. |
|
|
|
When a layer is activated, only the keys that are specified by the layer will change. |
|
|
|
This means, if you define a layer that only sets `CapsLock -> LCtrl` and `LCtrl->Capslock` only those keys |
|
|
|
will change when you active the layer. All the other keys will use the layer that is "underneath" to |
|
|
|
lookup the keypress (usually the DefaultMap). |
|
|
|
|
|
|
|
This means that you can combine .kll files statically using the compiler or dynamically using the firmware. |
|
|
|
|
|
|
|
You can set the max number of layers by changing the `stateWordSize` define in one of your kll files. |
|
|
|
By default it is set to 8 in Macro/PartialMap/capabilities.kll. This means you can have up to 256 layers |
|
|
|
total (this includes the DefaultMap). |
|
|
|
You can increase this number to either 16 or 32 (this will use more Flash and RAM btw) which will give you |
|
|
|
2^16 and 2^32 possible layers respectively (65 535 and 4 294 967 295). |
|
|
|
|
|
|
|
|
|
|
|
```cmake |
|
|
|
### |
|
|
|
# Keymap Configuration (do not include the .kll extension) |
|
|
|
# |
|
|
|
|
|
|
|
#| Do not include the .kll extension |
|
|
|
#| * BaseMap maps the native keyboard scan codes to USB Codes so the layout is compatible with all other layouts |
|
|
|
#| * DefaultMap allows the default keymap to be modified from the BaseMap |
|
|
|
#| * PartialMaps is a set of dynamically set layers (there is no limit, but too many may use up too much RAM...) |
|
|
|
#| BaseMap generally does not need to be changed from "defaultMap" |
|
|
|
#| |
|
|
|
#| Syntax: |
|
|
|
#| myMap |
|
|
|
#| * defines a single .kll layout file, double-quotes are needed to distinguish between layers |
|
|
|
#| "myMap specialLayer" |
|
|
|
#| * defines myMap to be the main layout, then replace specialLayers on top of it |
|
|
|
#| |
|
|
|
#| - Only for PartialMaps - |
|
|
|
#| "myMap specialLayer" "myMap colemak" dvorak |
|
|
|
#| * As before, but also generates a second layer at index 2 and third at index 3 |
|
|
|
#| |
|
|
|
#| NOTE: Remember to add key(s) to enable each Partial Layer |
|
|
|
#| NOTE2: Layers are always based up the BaseMap (which should be an ANSI-like mapping) |
|
|
|
#| NOTE3: Compiler looks in kll/layouts and the build directory for layout files (precedence on build directory) |
|
|
|
|
|
|
|
##| Set the base keyboard .kll map, defaults to "defaultMap" if not found |
|
|
|
##| Looks in Scan/<Module Name> for the available BaseMaps |
|
|
|
set( BaseMap "defaultMap" |
|
|
|
CACHE STRING "KLL BaseMap/Scancode Keymapping" ) |
|
|
|
|
|
|
|
##| Layer additonal .kll maps on the BaseMap, layers are in order from 1st to nth |
|
|
|
##| Can be set to "" |
|
|
|
set( DefaultMap "md1Overlay stdFuncMap" |
|
|
|
CACHE STRING "KLL DefaultMap" ) |
|
|
|
|
|
|
|
##| ParitalMaps available on top of the BaseMap. See above for syntax on specifying multiple layers vs. layering |
|
|
|
##| Can be set to "" |
|
|
|
set( PartialMaps "hhkbpro2" |
|
|
|
CACHE STRING "KLL PartialMaps/Layer Definitions" ) |
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
Linux Building |
|
|
|
-------------- |
|
|
|
|
|
|
|
From this directory. |
|
|
|
|
|
|
|
```bash |
|
|
|
$ mkdir build |
|
|
|
$ cd build |
|
|
|
$ cmake .. |
|
|
|
$ make |
|
|
|
``` |
|
|
|
|
|
|
|
Example output: |
|
|
|
|
|
|
|
``` |
|
|
|
$ cmake .. |
|
|
|
arm |
|
|
|
mk20dx128vlf5 |
|
|
|
mk20dx |
|
|
|
cortex-m4 |
|
|
|
Lib/mk20dx.c;Lib/delay.c |
|
|
|
dfu |
|
|
|
Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c |
|
|
|
Macro/PartialMap/macro.c |
|
|
|
Output/pjrcUSB/output_com.c;Output/pjrcUSB/arm/usb_desc.c;Output/pjrcUSB/arm/usb_dev.c; |
|
|
|
Output/pjrcUSB/arm/usb_keyboard.c;Output/pjrcUSB/arm/usb_mem.c;Output/pjrcUSB/arm/usb_serial.c |
|
|
|
Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c |
|
|
|
Current branch master is up to date. |
|
|
|
/home/hyatt/Source/controller/Macro/PartialMap/capabilities.kll |
|
|
|
/home/hyatt/Source/controller/Output/pjrcUSB/capabilities.kll |
|
|
|
/home/hyatt/Source/controller/Scan/MD1/defaultMap.kll |
|
|
|
/home/hyatt/Source/controller/kll/layouts/md1Overlay.kll |
|
|
|
/home/hyatt/Source/controller/kll/layouts/stdFuncMap.kll |
|
|
|
/home/hyatt/Source/controller/kll/layouts/hhkbpro2.kll |
|
|
|
[master]: make [~/Source/controller/build](hyatt@x230mas:pts/6) |
|
|
|
[ 5%] Generating KLL Layout |
|
|
|
Scanning dependencies of target kiibohd.elf |
|
|
|
[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o |
|
|
|
[ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.o |
|
|
|
[ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.o |
|
|
|
[ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.o |
|
|
|
[ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.o |
|
|
|
[ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.o |
|
|
|
[ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.o |
|
|
|
[ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.o |
|
|
|
[ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.o |
|
|
|
[ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.o |
|
|
|
[ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.o |
|
|
|
[ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.o |
|
|
|
[ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.o |
|
|
|
[ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.o |
|
|
|
[ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.o |
|
|
|
Linking C executable kiibohd.elf |
|
|
|
[ 94%] Built target kiibohd.elf |
|
|
|
Scanning dependencies of target SizeAfter |
|
|
|
[100%] Chip usage for mk20dx128vlf5 |
|
|
|
SRAM: 32% 5384/16384 bytes |
|
|
|
Flash: 18% 23384/126976 bytes |
|
|
|
[100%] Built target SizeAfter |
|
|
|
``` |
|
|
|
|
|
|
|
Linux Loading Firmware |
|
|
|
---------------------- |
|
|
|
|
|
|
|
First place the keyboard into re-flash mode. This can be done either by |
|
|
|
pressing the re-flash button on the PCB/Teensy. Or by entering the Kiibohd |
|
|
|
Virtual Serial Port and using the 'reload' command. |
|
|
|
|
|
|
|
The `load` script that is created during the build can load the firmware over |
|
|
|
USB. Either run it with sudo, or install the `98-kiibohd.rules` to |
|
|
|
`/etc/udev/rules.d` and run: `udevadm control --reload-rules`. |
|
|
|
|
|
|
|
To load the newly built firmware: `./load`. |
|
|
|
|
|
|
|
|
|
|
|
Linux Building Bootloader |
|
|
|
------------------------- |
|
|
|
|
|
|
|
> NOTE: Does not apply to Teensy based builds. |
|
|
|
|
|
|
|
From this directory. |
|
|
|
|
|
|
|
```bash |
|
|
|
$ cd Bootloader |
|
|
|
$ mkdir build |
|
|
|
$ cd build |
|
|
|
$ cmake .. |
|
|
|
$ make |
|
|
|
``` |
|
|
|
|
|
|
|
Example output: |
|
|
|
|
|
|
|
```bash |
|
|
|
$ cmake .. |
|
|
|
arm |
|
|
|
mk20dx128vlf5 |
|
|
|
mk20dx |
|
|
|
cortex-m4 |
|
|
|
Lib/mk20dx.c;Lib/delay.c |
|
|
|
dfu |
|
|
|
main.c;dfu.c;dfu.desc.c;flash.c;kinetis.c;usb.c |
|
|
|
[master]: make [~/Source/controller/Bootloader/build](hyatt@x230mas:pts/6) |
|
|
|
Scanning dependencies of target kiibohd_bootloader.elf |
|
|
|
[ 11%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/main.c.o |
|
|
|
[ 22%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/dfu.c.o |
|
|
|
[ 33%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/dfu.desc.c.o |
|
|
|
[ 44%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/flash.c.o |
|
|
|
[ 55%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/kinetis.c.o |
|
|
|
[ 66%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/usb.c.o |
|
|
|
[ 77%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/home/hyatt/Source/controller/Lib/mk20dx.c.o |
|
|
|
[ 88%] Building C object CMakeFiles/kiibohd_bootloader.elf.dir/home/hyatt/Source/controller/Lib/delay.c.o |
|
|
|
Linking C executable kiibohd_bootloader.elf |
|
|
|
[ 88%] Built target kiibohd_bootloader.elf |
|
|
|
Scanning dependencies of target SizeAfter |
|
|
|
[100%] Chip usage for mk20dx128vlf5 |
|
|
|
SRAM: 19% 3176/16384 bytes |
|
|
|
Flash: 2% 3736/126976 bytes |
|
|
|
[100%] Built target SizeAfter |
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
Linux Loading Bootloader |
|
|
|
------------------------ |
|
|
|
|
|
|
|
> NOTE: Does not apply to Teensy based builds. |
|
|
|
|
|
|
|
It's recommended to use an SWD-type flasher like a Bus Pirate. There is a |
|
|
|
convenience script for loading the firmware once the system is setup. |
|
|
|
|
|
|
|
```bash |
|
|
|
$ cd Bootloader/Scripts |
|
|
|
$ ./swdLoad.bash |
|
|
|
``` |
|
|
|
|
|
|
|
The above script requires Ruby, Ruby serial port module, git, and a |
|
|
|
`/dev/buspirate` udev rule. |
|
|
|
|
|
|
|
Additional Notes: |
|
|
|
|
|
|
|
* https://github.com/mchck/mchck/wiki/Getting-Started (See Bus-Pirate section) |
|
|
|
* https://wiki.archlinux.org/index.php/Bus_pirate |
|
|
|
|
|
|
|
|
|
|
|
Windows Building |
|
|
|
---------------- |
|
|
|
|
|
|
|
From this directory. |
|
|
|
|
|
|
|
```bash |
|
|
|
$ mkdir build |
|
|
|
$ cd build |
|
|
|
$ wincmake .. |
|
|
|
$ make |
|
|
|
``` |
|
|
|
|
|
|
|
Example output: |
|
|
|
|
|
|
|
```bash |
|
|
|
$ wincmake .. |
|
|
|
arm |
|
|
|
mk20dx128vlf5 |
|
|
|
mk20dx |
|
|
|
cortex-m4 |
|
|
|
Lib/mk20dx.c;Lib/delay.c |
|
|
|
dfu |
|
|
|
Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c |
|
|
|
Macro/PartialMap/macro.c |
|
|
|
Output/pjrcUSB/output_com.c;Output/pjrcUSB/arm/usb_desc.c;Output/pjrcUSB/arm/usb_dev.c;Output/pjrcUSB/arm/usb_keyboard.c;Output/pjrcUSB/arm/usb_mem.c;Output/pjrcUSB/arm/usb_serial.c |
|
|
|
Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c |
|
|
|
Current branch master is up to date. |
|
|
|
C:/cygwin64/home/Jacob/controller/Macro/PartialMap/capabilities.kll |
|
|
|
C:/cygwin64/home/Jacob/controller/Output/pjrcUSB/capabilities.kll |
|
|
|
C:/cygwin64/home/Jacob/controller/Scan/MD1/defaultMap.kll |
|
|
|
C:/cygwin64/home/Jacob/controller/kll/layouts/md1Overlay.kll |
|
|
|
C:/cygwin64/home/Jacob/controller/kll/layouts/stdFuncMap.kll |
|
|
|
C:/cygwin64/home/Jacob/controller/kll/layouts/hhkbpro2.kll |
|
|
|
|
|
|
|
$ make |
|
|
|
[ 5%] Generating KLL Layout |
|
|
|
Scanning dependencies of target kiibohd.elf |
|
|
|
[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.obj |
|
|
|
[ 17%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/mk20dx.c.obj |
|
|
|
[ 23%] Building C object CMakeFiles/kiibohd.elf.dir/Lib/delay.c.obj |
|
|
|
[ 29%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MD1/scan_loop.c.obj |
|
|
|
[ 35%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/MatrixARM/matrix_scan.c.obj |
|
|
|
[ 41%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.obj |
|
|
|
[ 47%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.obj |
|
|
|
[ 52%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_desc.c.obj |
|
|
|
[ 58%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_dev.c.obj |
|
|
|
[ 64%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_keyboard.c.obj |
|
|
|
[ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_mem.c.obj |
|
|
|
[ 76%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/arm/usb_serial.c.obj |
|
|
|
[ 82%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.obj |
|
|
|
[ 88%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.obj |
|
|
|
[ 94%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.obj |
|
|
|
Linking C executable kiibohd.elf |
|
|
|
[ 94%] Built target kiibohd.elf |
|
|
|
Scanning dependencies of target SizeAfter |
|
|
|
[100%] Chip usage for mk20dx128vlf5 |
|
|
|
SRAM: 32% 5384/16384 bytes |
|
|
|
Flash: 18% 23296/126976 bytes |
|
|
|
[100%] Built target SizeAfter |
|
|
|
``` |
|
|
|
|
|
|
|
### NOTES: |
|
|
|
|
|
|
|
If you get the following error, you have not setup wincmake correctly: |
|
|
|
|
|
|
|
```bash |
|
|
|
$ make |
|
|
|
[ 5%] Generating KLL Layout |
|
|
|
Scanning dependencies of target kiibohd.elf |
|
|
|
[ 11%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o |
|
|
|
../main.c:28:19: fatal error: macro.h: No such file or directory |
|
|
|
#include <macro.h> |
|
|
|
^ |
|
|
|
compilation terminated. |
|
|
|
CMakeFiles/kiibohd.elf.dir/build.make:67: recipe for target 'CMakeFiles/kiibohd.elf.dir/main.c.o' failed |
|
|
|
make[2]: *** [CMakeFiles/kiibohd.elf.dir/main.c.o] Error 1 |
|
|
|
CMakeFiles/Makefile2:98: recipe for target 'CMakeFiles/kiibohd.elf.dir/all' failed |
|
|
|
make[1]: *** [CMakeFiles/kiibohd.elf.dir/all] Error 2 |
|
|
|
Makefile:75: recipe for target 'all' failed |
|
|
|
make: *** [all] Error 2 |
|
|
|
``` |
|
|
|
|
|
|
|
If you have already added the line to your `~/.bashrc` try restarting your |
|
|
|
cygwin shell. |
|
|
|
|
|
|
|
|
|
|
|
Windows Loading Firmware |
|
|
|
------------------------ |
|
|
|
|
|
|
|
First place the keyboard into re-flash mode. This can be done either by |
|
|
|
pressing the re-flash button on the PCB/Teensy. Or by entering the Kiibohd |
|
|
|
Virtual Serial Interface and using the `reload` command. |
|
|
|
|
|
|
|
The `load` script that is created during the build can load the firmware over |
|
|
|
USB. |
|
|
|
|
|
|
|
To load the newly built firmware: `./load` |
|
|
|
|
|
|
|
Be patient the couple of times, Windows is slow at installing drivers... |
|
|
|
|
|
|
|
|
|
|
|
Mac OS X Building |
|
|
|
----------------- |
|
|
|
|
|
|
|
From this directory. |
|
|
|
|
|
|
|
```bash |
|
|
|
$ mkdir build |
|
|
|
$ cd build |
|
|
|
$ cmake .. |
|
|
|
$ make |
|
|
|
``` |
|
|
|
|
|
|
|
Example output: |
|
|
|
|
|
|
|
> TODO |
|
|
|
|
|
|
|
|
|
|
|
Mac OS X Loading Firmware |
|
|
|
------------------------- |
|
|
|
|
|
|
|
First place the keyboard into re-flash mode. This can be done either by |
|
|
|
pressing the re-flash button on the PCB/Teensy. Or by entering the Kiibohd |
|
|
|
Virtual Serial Port and using the `reload` command. |
|
|
|
|
|
|
|
The `load` script that is created during the build can load the firmware over |
|
|
|
USB. |
|
|
|
|
|
|
|
To load the newly built firmware: `./load`. |
|
|
|
|
|
|
|
|
|
|
|
Virtual Serial Port - CLI |
|
|
|
------------------------- |
|
|
|
|
|
|
|
Rather than use a special program that can interpret Raw HID, this controller exposes a USB Serial CDC endpoint. |
|
|
|
This allows for you to use a generic serial terminal to debug/control the keyboard firmware (e.g. Tera Term, minicom, screen) |
|
|
|
|
|
|
|
|
|
|
|
### Linux |
|
|
|
|
|
|
|
I generally use screen. You will need sudo/root priviledges if you haven't |
|
|
|
installed the `98-kiibohd.rules` file to `/etc/udev/rules.d`. |
|
|
|
|
|
|
|
``` |
|
|
|
$ screen /dev/ttyACM0 |
|
|
|
# (Might be ACM1, ACM2, etc.) |
|
|
|
``` |
|
|
|
|
|
|
|
### Windows |
|
|
|
|
|
|
|
Make sure the Teensy Virtual Serial Port driver is installed. If possible use |
|
|
|
screen (as part of Cygwin). Check which COM port the virtual serial port has |
|
|
|
been assigned to: `Device Manager->Ports (COM & LPT)->Teensy USB Serial`. In |
|
|
|
brackets it will say which COM port (e.g. COM3) |
|
|
|
|
|
|
|
putty works well when using DTR/DSR or RTS/CTS flow control. |
|
|
|
|
|
|
|
| Setting | Value | |
|
|
|
| --------------- | ------------------------------------- | |
|
|
|
| Connection type | Serial | |
|
|
|
| Serial line | Your COM port, e.g. COM3 | |
|
|
|
| Speed | doesn't matter, it's auto-negotiated | |
|
|
|
|
|
|
|
Under `Category->Connections->Serial`: `Flow control: DTR/DSR`. |
|
|
|
|
|
|
|
If stuff is hard to read (you have a dumb colour scheme): |
|
|
|
`Category->Window->Colours->Use system color`. That seems to make text at |
|
|
|
least readable |
|
|
|
|
|
|
|
> I use a custom colour scheme that makes each colour easy to see. |
|
|
|
> -HaaTa. |
|
|
|
|
|
|
|
Unfortunately, screen for Cygwin seems to be broken for serial ports, but you |
|
|
|
can try it... |
|
|
|
|
|
|
|
```bash |
|
|
|
$ screen /dev/ttyS2 |
|
|
|
# Might be a different file, ttyS0, ttyACM0, ttyUSB0, etc. |
|
|
|
``` |
|
|
|
|
|
|
|
Gnu screen doesn't seem to echo all the characters (it works though). |
|
|
|
I believe it's a problem with stty, but I don't know how to fix it... |
|
|
|
|
|
|
|
### Mac OS X |
|
|
|
|
|
|
|
I recommend screen (can be installed via Macports). |
|
|
|
|
|
|
|
```bash |
|
|
|
$ screen /dev/tty.<usb something> |
|
|
|
``` |