X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=README;h=27df1cb83e5bb35507ffea3a82bacd8bacc9e16b;hb=38266ca2ccb4e76d6827e893ce57cc1dbf3fba88;hp=629799b812386b2d1a1293463817fd0c170ab837;hpb=ead6521b9d6ea259934d511a2b9d306d0d360574;p=kiibohd-controller.git diff --git a/README b/README index 629799b..27df1cb 100644 --- a/README +++ b/README @@ -15,98 +15,98 @@ 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) -- 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 +- libusb1.0 +- libusb1.0-devel - ### - Compiler Family - # +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: + alias wincmake="PATH='/cygdrive/c/Program Files (x86)/CMake 2.8'/bin:\"${PATH}\" cmake" - #| 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 +Next, install the compiler(s) you want. - set( COMPILER_FAMILY "avr" ) + --------- +| AVR GCC | + --------- -Just change the COMPILER_FAMILY variable to whatever you are trying to build for. +You just need the Atmel AVR 8-bit Toolchain. The latest should be fine, as of writing it was 3.4.3. -NOTE: If you change this option, you will *may* to delete the build directory that is created in the Building sections below. +http://www.atmel.com/tools/atmelavrtoolchainforwindows.aspx +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). ----------------------- -Selecting Microcontroller ----------------------- + ---------- +| ARM EABI | + ---------- -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). +Download the latest version of Mentor Graphics Sourcery CodeBench ARM EABI. -Open up avr.cmake (or arm.cmake) in your favourite text editor. -You are looking for: +http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/ - ### - # Atmel Defines and Linker Options - # +Use the installer and make sure you add the binaries to your path within the installer. - #| 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* +---------------------- +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: ### - # 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. @@ -123,7 +123,7 @@ The Kiibohd Controller is designed around a set of 4 types of modules that corre - 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". @@ -132,12 +132,14 @@ A matrix Scan Module may inherit from the matrix module to scan keypress from a 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. @@ -147,7 +149,7 @@ The Debug Module enables various things like the Teensy LED on errors, debug ter -Open up setup.cmake in your favourite text editor. +Open up CMakeLists.txt in your favourite text editor. Look for: ### @@ -159,7 +161,7 @@ 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" ) @@ -168,7 +170,7 @@ Look for: 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" ) @@ -204,8 +206,8 @@ Example output: 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 @@ -216,8 +218,8 @@ Example output: [ 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 @@ -241,7 +243,6 @@ Linux Loading Firmware 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. -(TODO, not complete, avr and arm are different currently, need to be unified) ./load @@ -250,7 +251,61 @@ It uses sudo, so make sure you have the priviledges. Windows Building ---------------------- -TODO +From this directory. +mkdir build +cd build +wincmake -G "Unix Makefiles" .. + + +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 @@ -271,11 +326,32 @@ Mac OS X Loading Firmware TODO - ---------------------- -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. + +sudo screen /dev/ttyACM0 + + + --------- +| Windows | + --------- + +TODO Probably COM1, but not exactly sure. Tera Term. + + + ---------- +| Mac OS X | + ---------- +TODO (What is the usual device name). screen if possible.