X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=README;h=684a48206102355d40777b06c73d933b7bbd5351;hb=17681c535d524b699a014b3274686c9acd2ef4b5;hp=a6a89d2441f4f70d0f7bb3ddb237c60ef2c4d993;hpb=497c77e8ef3f02db8047b5ae49f445283b96f7e6;p=kiibohd-controller.git diff --git a/README b/README index a6a89d2..684a482 100644 --- a/README +++ b/README @@ -1,7 +1,20 @@ 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 @@ -15,6 +28,11 @@ 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) @@ -47,11 +65,16 @@ First make sure Cygwin is installed - http://www.cygwin.com/ - 32bit or 64bit is - 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 - 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) @@ -59,6 +82,7 @@ Install the PJRC Virtual Serial Port Driver: Next, install the compiler(s) you want. + --------- | AVR GCC | --------- @@ -68,8 +92,8 @@ You just need the Atmel AVR 8-bit Toolchain. The latest should be fine, as of wr 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). @@ -86,7 +110,9 @@ 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. +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). @@ -264,6 +290,36 @@ To load the newly built firmware: +---------------------- +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 ---------------------- @@ -271,7 +327,8 @@ Windows Building From this directory. mkdir build cd build -wincmake -G "Unix Makefiles" .. +wincmake .. +make Example output: @@ -345,6 +402,14 @@ 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 @@ -353,7 +418,15 @@ 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 @@ -370,7 +443,7 @@ This allows for you to use a generic serial terminal to debug/control the keyboa ------- 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 +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.) @@ -382,19 +455,35 @@ screen /dev/ttyACM0 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: +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). + -screen /dev/ttyS3 +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... -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. - +I recommend screen (can be installed via Macports). +screen /dev/tty.