d405af0435
Instructions: - Windows virtual serial port - Mac OSX virtual serial port - Mac OSX firmware loading instructions - Initial Mac OSX building instructions - Initial Bootloader make and installation instructions for Linux
490 lines
16 KiB
Plaintext
490 lines
16 KiB
Plaintext
The Kiibohd Controller
|
|
----------------------
|
|
|
|
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
|
|
|
|
|
|
|
|
----------------------
|
|
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) (Sourcery CodeBench Lite for ARM EABI
|
|
(http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/)
|
|
- arm-none-eabi
|
|
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)
|
|
|
|
|
|
|
|
----------------------
|
|
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
|
|
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 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".
|
|
|
|
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
|
|
----------------------
|
|
|
|
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)
|
|
# "mk20dx256" # Teensy 3.1 (arm)
|
|
)
|
|
|
|
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}/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" )
|
|
|
|
##| Uses the key index and potentially applies special conditions to it, mapping it to a usb key code
|
|
set( MacroModule "buffer" )
|
|
|
|
##| Sends the current list of usb key codes through USB HID
|
|
set( OutputModule "pjrc" )
|
|
|
|
##| Debugging source to use, each module has it's own set of defines that it sets
|
|
set( DebugModule "full" )
|
|
|
|
|
|
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>
|
|
|
|
|
|
|
|
----------------------
|
|
Linux Building
|
|
----------------------
|
|
|
|
From this directory.
|
|
mkdir build
|
|
cd build
|
|
cmake ..
|
|
make
|
|
|
|
|
|
Example output:
|
|
|
|
[master]: cmake .. [...sy/avr-capsense-haata/build](hyatt@901Mas:pts/4)
|
|
-- Compiler Family:
|
|
avr
|
|
-- MCU Selected:
|
|
at90usb1286
|
|
-- Detected Scan Module Source Files:
|
|
Scan/avr-capsense/scan_loop.c
|
|
-- Detected Macro Module Source Files:
|
|
Macro/buffer/macro.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
|
|
-- Generating done
|
|
-- Build files have been written to: /home/hyatt/Source/Teensy/avr-capsense-haata/build
|
|
[master]: make [...sy/avr-capsense-haata/build](hyatt@901Mas:pts/4)
|
|
Scanning dependencies of target kiibohd.elf
|
|
[ 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/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
|
|
Creating load file for Flash: kiibohd.hex
|
|
Creating Extended Listing: kiibohd.lss
|
|
Creating Symbol Table: kiibohd.sym
|
|
[ 87%] Built target kiibohd.elf
|
|
Scanning dependencies of target SizeAfter
|
|
[100%] Size after generation:
|
|
text data bss dec hex filename
|
|
0 6112 0 6112 17e0 kiibohd.hex
|
|
5792 320 852 6964 1b34 kiibohd.elf
|
|
[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:
|
|
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 ..
|
|
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
|
|
----------------------
|
|
|
|
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: <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 |
|
|
----------
|
|
|
|
I recommend screen (can be installed via Macports).
|
|
screen /dev/tty.<usb something>
|