The Kiibohd Controller
----------------------
-TODO, write some insightful/informative :P
+This README is a bit long, just look at the sections you are interested in.
+Linux is the ideal build environment (preferably recent'ish).
+
+
+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.
+
Please give authors credit for modules used if you use in a distributed product :D
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)
+- 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)
+- avr-gcc (~4.8.0)
+- avr-binutils (~2.23.2)
+- avr-libc (~1.8.0)
ARM Specific (Teensy 3.0/3.1) (Sourcery CodeBench Lite for ARM EABI
- git (needed for some compilation info)
- cmake
- gcc-core
-- gcc-g++ or gcc-c++
+- gcc-g++
+- libusb1.0
+- libusb1.0-devel
+- python3
+- ctags (recommended, not required)
-And make sure CMake is *NOT* installed through Cygwin. This is extremely important.
-If this is not possible, you'll have to play with your paths in Cygwin to prioritize the Windows version of CMake.
+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
+Also install the Windows version of CMake (3+ is ideal) - 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:
- alias wincmake="PATH='/cygdrive/c/Program Files (x86)/CMake 2.8'/bin:\"${PATH}\" cmake"
+ 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 directory.
-Mine is C:\cygwin64.
+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).
http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/
-Use the installer and make sure you add the binaries to your path within the installer.
-
-
-
-----------------------
-Selecting Architecture
-----------------------
-
-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
- - Teensy 3.1
-
-Open up CMakeLists.txt in your favourite text editor.
-You are looking for:
-
- ###
- Compiler Family
- #
-
- #| 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
- #| "arm" # Teensy 3.1
-
- set( COMPILER_FAMILY "avr" )
-
-
-Just change the COMPILER_FAMILY variable to whatever you are trying to build for.
+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".
-NOTE: If you change this option, you will *may* to delete the build directory that is created in the Building sections below.
+Then copy all the folders/files installed (e.g. C:\Users\Haata\MentorGraphics\Sourcery_CodeBench_Lite_for_ARM_EABI\) to Cygwin /usr/local directory.
+Mine is C:\cygwin64\usr\local.
+Or, you can setup paths using the installer (you have to be more careful though).
Selecting Microcontroller
----------------------
-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).
+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 avr.cmake (or arm.cmake) in your favourite text editor.
+Open up CMakeLists.txt in your favourite text editor.
You are looking for:
###
- # 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" )
-
-*OR*
-
- ###
- # 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
- #| "mk20dx256" # Teensy 3.1
-
- 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.
-Open up setup.cmake in your favourite text editor.
+Open up CMakeLists.txt in your favourite text editor.
Look for:
###
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
+
+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:
+TODO
+
+
+
+----------------------
+Linux Loading Bootloader
+----------------------
+
+*NOTE* Does not apply to Teensy based builds.
+
+It's recommended to use an SWD-type flasher like a Bus Pirate.
+TODO
+(Guidelines here https://github.com/mchck/mchck/wiki/Getting-Started)
+
+
+
----------------------
Windows Building
----------------------
From this directory.
mkdir build
cd build
-wincmake -G "Unix Makefiles" ..
+wincmake ..
+make
Example output:
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
----------------------
+From this directory.
+mkdir build
+cd build
+cmake ..
+make
+
+
+Example output:
TODO
+
+
----------------------
Mac OS X 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 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
+
----------------------
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
-sudo screen /dev/ttyACM0
+screen /dev/ttyACM0
+(Might be ACM1, ACM2, etc.)
---------
| Windows |
---------
-TODO Probably COM1, but not exactly sure. Tera Term.
+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: <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 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 |
----------
-TODO (What is the usual device name). screen if possible.
-
+I recommend screen (can be installed via Macports).
+screen /dev/tty.<usb something>
projects / kiibohd-controller.git / blobdiff