diff --git a/README b/README deleted file mode 100644 index 48a30d2..0000000 --- a/README +++ /dev/null @@ -1,632 +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 (haven't tried Brew). -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 it should work (e.g. http://stackoverflow.com/questions/601516/cygwin-make-error-target-pattern-contains-no). -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-eaby-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 (3+ is ideal) - http://cmake.org/cmake/resources/software.html -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. The latest should be fine, as of writing it was 3.4.3. - -http://www.atmel.com/tools/atmelavrtoolchainforwindows.aspx -(Atmel AVR 8-bit Toolchain 3.4.3 - Windows) - -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: - -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: - - ### - # 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: - - ### - # 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= - - - ----------------------- -Linux Building ----------------------- - -From this directory. -mkdir build -cd build -cmake .. -make - - -Example output: - - [master]: cmake .. [~/Source/controller/build](hyatt@x230mas:pts/6) - -- Compiler Family: - arm - -- Chip Selected: - mk20dx128vlf5 - -- Chip Family: - mk20dx - -- CPU Selected: - cortex-m4 - -- Compiler Source Files: - Lib/mk20dx.c;Lib/delay.c - -- Bootloader Type: - dfu - -- Detected Scan Module Source Files: - Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c - -- Detected Macro Module Source Files: - Macro/PartialMap/macro.c - -- Detected Output Module Source Files: - 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 - -- Detected Debug Module Source Files: - Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c - -- Found Git: /usr/bin/git (found version "2.2.1") - -- Found Ctags: /usr/bin/ctags (found version "5.8") - -- Checking for latest kll version: - Current branch master is up to date. - -- Detected Layout Files: - /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 - -- Configuring done - -- Generating done - -- Build files have been written to: /home/hyatt/Source/controller/build - [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. -cd Bootloader -mkdir build -cd build -cmake .. -make - -Example output: - - [master]: cmake .. [~/Source/controller/Bootloader/build](hyatt@x230mas:pts/6) - -- Compiler Family: - arm - -- Chip Selected: - mk20dx128vlf5 - -- Chip Family: - mk20dx - -- CPU Selected: - cortex-m4 - -- Compiler Source Files: - Lib/mk20dx.c;Lib/delay.c - -- Bootloader Type: - dfu - -- Bootloader Source Files: - main.c;dfu.c;dfu.desc.c;flash.c;kinetis.c;usb.c - -- Found Git: /usr/bin/git (found version "2.2.1") - -- Found Ctags: /usr/bin/ctags (found version "5.8") - -- Configuring done - -- Generating done - -- Build files have been written to: /home/hyatt/Source/controller/Bootloader/build - [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. - -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. -mkdir build -cd build -wincmake .. -make - - -Example output: - - $ wincmake .. - -- Compiler Family: - arm - -- Chip Selected: - mk20dx128vlf5 - -- Chip Family: - mk20dx - -- CPU Selected: - cortex-m4 - -- Compiler Source Files: - Lib/mk20dx.c;Lib/delay.c - -- Bootloader Type: - dfu - -- Detected Scan Module Source Files: - Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c - -- Detected Macro Module Source Files: - Macro/PartialMap/macro.c - -- Detected Output Module Source Files: - 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 - -- Detected Debug Module Source Files: - Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c - -- Found Git: C:/cygwin64/bin/git.exe (found version "2.1.1") - -- Found Ctags: C:/cygwin64/bin/ctags.exe (found version "5.8") - -- Checking for latest kll version: - Current branch master is up to date. - -- Detected Layout Files: - 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 - -- Configuring done - -- Generating done - -- Build files have been written to: C:/cygwin64/home/Jacob/controller/build - - Jacob@DenPC ~/controller/build - $ 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: - -$ 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 - ^ -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. -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. -Connection type: Serial -Serial line: -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 colur -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... -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). -screen /dev/tty. - diff --git a/README.markdown b/README.markdown new file mode 100644 index 0000000..8907cb4 --- /dev/null +++ b/README.markdown @@ -0,0 +1,643 @@ +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 (haven't tried +Brew). 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-eaby-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=`. + + +Linux Building +-------------- + +From this directory. + +```bash +$ mkdir build +$ cd build +$ cmake .. +$ make +``` + +Example output: + +``` +$ cmake .. +-- Compiler Family: +arm +-- Chip Selected: +mk20dx128vlf5 +-- Chip Family: +mk20dx +-- CPU Selected: +cortex-m4 +-- Compiler Source Files: +Lib/mk20dx.c;Lib/delay.c +-- Bootloader Type: +dfu +-- Detected Scan Module Source Files: +Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c +-- Detected Macro Module Source Files: +Macro/PartialMap/macro.c +-- Detected Output Module Source Files: +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 +-- Detected Debug Module Source Files: +Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c +-- Found Git: /usr/bin/git (found version "2.2.1") +-- Found Ctags: /usr/bin/ctags (found version "5.8") +-- Checking for latest kll version: +Current branch master is up to date. +-- Detected Layout Files: +/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 +-- Configuring done +-- Generating done +-- Build files have been written to: /home/hyatt/Source/controller/build +[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 .. +-- Compiler Family: +arm +-- Chip Selected: +mk20dx128vlf5 +-- Chip Family: +mk20dx +-- CPU Selected: +cortex-m4 +-- Compiler Source Files: +Lib/mk20dx.c;Lib/delay.c +-- Bootloader Type: +dfu +-- Bootloader Source Files: +main.c;dfu.c;dfu.desc.c;flash.c;kinetis.c;usb.c +-- Found Git: /usr/bin/git (found version "2.2.1") +-- Found Ctags: /usr/bin/ctags (found version "5.8") +-- Configuring done +-- Generating done +-- Build files have been written to: /home/hyatt/Source/controller/Bootloader/build +[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 .. +-- Compiler Family: +arm +-- Chip Selected: +mk20dx128vlf5 +-- Chip Family: +mk20dx +-- CPU Selected: +cortex-m4 +-- Compiler Source Files: +Lib/mk20dx.c;Lib/delay.c +-- Bootloader Type: +dfu +-- Detected Scan Module Source Files: +Scan/MD1/scan_loop.c;Scan/MD1/../MatrixARM/matrix_scan.c +-- Detected Macro Module Source Files: +Macro/PartialMap/macro.c +-- Detected Output Module Source Files: +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 +-- Detected Debug Module Source Files: +Debug/full/../cli/cli.c;Debug/full/../led/led.c;Debug/full/../print/print.c +-- Found Git: C:/cygwin64/bin/git.exe (found version "2.1.1") +-- Found Ctags: C:/cygwin64/bin/ctags.exe (found version "5.8") +-- Checking for latest kll version: +Current branch master is up to date. +-- Detected Layout Files: +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 +-- Configuring done +-- Generating done +-- Build files have been written to: C:/cygwin64/home/Jacob/controller/build + +$ 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 + ^ +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. +```