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".
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.
projects / kiibohd-controller.git / blobdiff