These depend a bit on which targets you are trying to build, but the general one:
- cmake (2.8 and higher)
-- Teensy Loader (http://pjrc.com/teensy/loader.html)
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)
+- avr-gcc (~4.8.0)
+- avr-binutils (~2.23.2)
+- avr-libc (~1.8.0)
-ARM Specific (Teensy 3.0) (Sourcery CodeBench Lite for ARM EABI
+ARM Specific (Teensy 3.0/3.1) (Sourcery CodeBench Lite for ARM EABI
(http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/)
- arm-none-eabi
-- TODO?
+OR
+- arm-none-eabi-gcc
+- arm-none-eaby-binutils
+(I've actually had some issues with Sourcery CodeBench on Linux, so I often just use these)
----------------------
-Selecting Architecture
+Windows Setup
----------------------
-This is where you choose which architecture you want to build for.
-The options are:
- - Teensy 1.0 (Not tested)
- - Teensy 1.0++ (Not tested)
- - Teensy 2.0
- - Teensy 2.0++
- - Teensy 3.0
+Compiling on Windows does work, just it's a bunch more work.
-Open up CMakeLists.txt in your favourite text editor.
-You are looking for:
+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
- ###
- Compiler Family
- #
+Please note, I use cygwin term exclusively for any command line options. Unless mentioned otherwise use it.
+Do NOT use CMD or Powershell.
- #| Specify the compiler family to use
- #| Currently only supports AVR and ARM
- #| "avr" # Teensy 1.0
- #| "avr" # Teensy 2.0
- #| "avr" # Teensy++ 1.0
- #| "avr" # Teensy++ 2.0
- #| "arm" # Teensy 3.0
+Also install the Windows version of CMake - http://cmake.org/cmake/resources/software.html
+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 2.8'/bin:\"${PATH}\" cmake" >> ~/.bashrc
- set( COMPILER_FAMILY "avr" )
+Install the PJRC Virtual Serial Port Driver:
+(http://pjrc.com/teensy/serial_install.exe)
+Next, install the compiler(s) you want.
-Just change the COMPILER_FAMILY variable to whatever you are trying to build for.
-NOTE: If you change this option, you will *may* to delete the build directory that is created in the Building sections below.
+ ---------
+| 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)
-----------------------
-Selecting Microcontroller
-----------------------
+Extract the files to a directory, say C:\avr8-gnu-toolchain. Then copy all the folders in that directory to the Cygwin directory.
+Mine is C:\cygwin64.
+(You can also just setup the paths, but this is faster/simpler. Might screw up your Cygwin though).
-Even if you selected the "avr" family of microcontroller architectures, you will still need to specify a target microcontroller (or once more ARM microcontrollers are supported).
-Open up avr.cmake (or arm.cmake) in your favourite text editor.
-You are looking for:
+ ----------
+| ARM EABI |
+ ----------
+
+Download the latest version of Mentor Graphics Sourcery CodeBench ARM EABI.
+
+http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/
+
+Look for "Download the EABI Release".
+Enter your info to get the download link.
+Select the most recent download.
+Then download the "IA32 Windows Installer".
+
+Use the installer and make sure you add the binaries to your path within the installer.
- ###
- # Atmel Defines and Linker Options
- #
- #| MCU Name
- #| You _MUST_ set this to match the board you are using
- #| type "make clean" after changing this, so all files will be rebuilt
- #|
- #| "at90usb162" # Teensy 1.0
- #| "atmega32u4" # Teensy 2.0
- #| "at90usb646" # Teensy++ 1.0
- #| "at90usb1286" # Teensy++ 2.0
- set( MCU "at90usb1286" )
+----------------------
+Selecting Microcontroller
+----------------------
-*OR*
+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:
###
- # ARM Defines and Linker Options
+ # Chip Selection
#
- #| Chip Name (Linker)
- #| You _MUST_ set this to match the board you are using
- #| type "make clean" after changing this, so all files will be rebuilt
+ #| 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
#|
- #| "mk20dx128" # Teensy 3.0
-
- set( CHIP "mk20dx128" )
-
+ 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)
+ # "mk20dx256" # Teensy 3.1 (arm)
+ )
-Just change the CHIP variable to the microcontroller you are trying to build for.
+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.
- Scan Module
- Macro Module
-- USB Module
+- Output Module
- Debug Module
The Scan Module is where the most interesting stuff happens. These modules take in "keypress data".
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 a USB scan code.
+
+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 USB Module is the output module of the microcontroller. Currently USB is the only output protocol.
+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.
-Open up setup.cmake in your favourite text editor.
+Open up CMakeLists.txt in your favourite text editor.
Look for:
###
#| 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,USB,Debug}/module.txt for information on the modules and how to create new ones
+ #| Please look at the {Scan,Macro,Output,Debug}/module.txt 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 "avr-capsense" )
set( MacroModule "buffer" )
##| Sends the current list of usb key codes through USB HID
- set( USBModule "pjrc" )
+ set( OutputModule "pjrc" )
##| Debugging source to use, each module has it's own set of defines that it sets
set( DebugModule "full" )
Scan/avr-capsense/scan_loop.c
-- Detected Macro Module Source Files:
Macro/buffer/macro.c
- -- Detected USB Module Source Files:
- USB/pjrc/usb_com.c;USB/pjrc/avr/usb_keyboard_debug.c
+ -- Detected Output Module Source Files:
+ Output/pjrc/usb_com.c;Output/pjrc/avr/usb_keyboard_debug.c
-- Detected Debug Module Source Files:
Debug/full/../led/led.c;Debug/full/../print/print.c
-- Configuring done
[ 12%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.o
[ 25%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/avr-capsense/scan_loop.c.o
[ 37%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/buffer/macro.c.o
- [ 50%] Building C object CMakeFiles/kiibohd.elf.dir/USB/pjrc/usb_com.c.o
- [ 62%] Building C object CMakeFiles/kiibohd.elf.dir/USB/pjrc/avr/usb_keyboard_debug.c.o
+ [ 50%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrc/usb_com.c.o
+ [ 62%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrc/avr/usb_keyboard_debug.c.o
[ 75%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.o
[ 87%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.o
Linking C executable kiibohd.elf
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.
-It uses sudo, so make sure you have the priviledges.
+Either run it with sudo, or install the 98-kiibohd.rules to /etc/udev/rules.d
+ and run: udevadm control --reload-rules
+
-(TODO, not complete, avr and arm are different currently, need to be unified)
+To load the newly built firmware:
./load
Windows Building
----------------------
-TODO
+From this directory.
+mkdir build
+cd build
+wincmake -G "Unix Makefiles" ..
+make
+
+
+Example output:
+
+ $ cmake -G "Unix Makefiles" ..
+ -- Compiler Family:
+ avr
+ -- MCU Selected:
+ atmega32u4
+ -- CPU Selected:
+ megaAVR
+ -- Detected Scan Module Source Files:
+ Scan/SKM67001/../matrix/matrix_scan.c;Scan/SKM67001/../matrix/scan_loop.c
+ -- Detected Macro Module Source Files:
+ Macro/PartialMap/macro.c
+ -- Detected Output Module Source Files:
+ Output/pjrcUSB/output_com.c;Output/pjrcUSB/avr/usb_keyboard_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 "1.7.9")
+ -- Configuring done
+ -- Generating done
+ -- Build files have been written to: C:/cygwin64/home/jacob.alexander/src/capsense-beta/build
+
+ jacob.alexander@JALEXANDER2-LT ~/src/capsense-beta/build
+ $ make
+ Scanning dependencies of target kiibohd.elf
+ [ 10%] Building C object CMakeFiles/kiibohd.elf.dir/main.c.obj
+ [ 20%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/matrix/matrix_scan.c.obj
+ [ 30%] Building C object CMakeFiles/kiibohd.elf.dir/Scan/matrix/scan_loop.c.obj
+ [ 40%] Building C object CMakeFiles/kiibohd.elf.dir/Macro/PartialMap/macro.c.obj
+ [ 50%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/output_com.c.obj
+ [ 60%] Building C object CMakeFiles/kiibohd.elf.dir/Output/pjrcUSB/avr/usb_keyboard_serial.c.obj
+ [ 70%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/cli/cli.c.obj
+ [ 80%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/led/led.c.obj
+ [ 90%] Building C object CMakeFiles/kiibohd.elf.dir/Debug/print/print.c.obj
+ Linking C executable kiibohd.elf
+ Creating load file for Flash: kiibohd.hex
+ Creating Extended Listing: kiibohd.lss
+ Creating Symbol Table: kiibohd.sym
+ [ 90%] Built target kiibohd.elf
+ Scanning dependencies of target SizeAfter
+ [100%] Size after generation
+ Flash Usage: data (hex)
+ RAM Usage: data (elf)
+ text data bss dec hex filename
+ 0 9738 0 9738 260a kiibohd.hex
+ 7982 1756 264 10002 2712 kiibohd.elf
+ [100%] Built target SizeAfter
+
+
----------------------
Windows Loading Firmware
----------------------
-TODO
+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
TODO
+
+
----------------------
Mac OS X Loading Firmware
----------------------
----------------------
-Debugging
+Virtual Serial Port - CLI
----------------------
-TODO
+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).
+
+screen /dev/ttyS3
+(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...
+
+putty works well when using DTR/DSR or RTS/CTS flow control.
+
+
+ ----------
+| Mac OS X |
+ ----------
+TODO (What is the usual device name). screen if possible.