keyboard/teensy_lc_onekey/instructions.md

   1 # Teensy LC, 3.0, 3.1, 3.2 support
   2
   3 These ARM Teensies are now supported through [chibios](http://chibios.org).
   4
   5 You'll need to install an ARM toolchain, for instance from [gcc ARM embedded](https://launchpad.net/gcc-arm-embedded) website, or using your favourite package manager. After installing, you should be able to run `arm-none-eabi-gcc -v` in the command prompt and get sensible output. This toolchain is used instead of `avr-gcc`, which is only for AVR chips. Naturally you'll also need the usual development tools (e.g. `make`), just as in the AVR setting.
   6
   7 You'll need this fork/branch of TMK. If you're reading this from your own hard drive, then you already have it ;) Anyway, you can get a zip from [here](https://https://github.com/flabbergast/tmk_keyboard/archive/chibios.zip) {or clone this repo from github and checkout the `chibios` branch}.
   8
   9 Next, you'll need ChibiOS. The current release (3.0.2) does not have sufficient Kinetis support, so you'll need to get a patched version from [my fork](https://github.com/flabbergast/ChibiOS/tree/kinetis): you can download a current tree zipped from [here](https://github.com/flabbergast/ChibiOS/archive/kinetis.zip) {or clone that repo from github and checkout the `kinetis` branch}. Unpack the zip, rename the newly created `ChibiOS-kinetis` to `chibios`, and move it to `tmk/tool/chibios/` (so that the ChibiOS files reside in `tmk/tool/chibios/chibios`).
  10
  11 This should be it. Running `make` in `keyboard/teensy_lc_onekey` should create a working firmware in `build/`, called `ch.hex`.
  12
  13 For more notes about the ChibiOS backend in TMK, see `tmk_core/protocol/chibios/README.md`.
  14
  15 ## About this onekey example
  16
  17 It's set up for Teensy LC. To use 3.x, you'll need to edit the `Makefile` (and comment out one line in `mcuconf.h`). A sample makefile for Teensy 3.0 is provided as `Makefile.3.0`, can be used without renaming with `make -f Makefile.3.0`.
  18
  19 ## Credits
  20
  21 TMK itself is written by hasu, original sources [here](https://github.com/tmk/tmk_keyboard).
  22
  23 The USB support for Kinetis MCUs is due to RedoX. His ChibiOS fork is also [on github](https://github.com/RedoXyde/ChibiOS); but it doesn't include Teensy LC definitions.
  24
  25 ## Features that are not implemented yet
  26
  27 Currently only the more fancy suspend features are not there (i.e. "breathing" LED during suspend, power saving during suspend, sending a wakeup packet). The rest should work fine (reports either way are welcome).
  28
  29 # Matrix programming notes
  30
  31 The notes below explain what commands can be used to examine and set the status of Teensy pins.
  32
  33 ## ChibiOS pin manipulation basics
  34
  35 ### Pins
  36
  37 Each pin sits on a "port", each of which comprises at most 32 individual pins.
  38 So for instance "PTC5" from Kinetis manual/datasheet refers to port C (or GPIOA), pin 5. Most functions dealing with pins take 2 parameters which specify the pin -- the first being the port, the second being the pin number.
  39
  40 Within ChibiOS, there are definitions which simplify this a bit for the Teensies. `TEENSY_PINn_IOPORT` represents the port of the MCU's pin connected Teensy's PIN `n`, and `TEENSY_PINn` represents its MCU's pin number.
  41
  42 ### Mode
  43
  44 A MCU pin can be in several modes. The basic command to set a pin mode is
  45
  46         palSetPadMode(TEENSY_PINn_IOPORT, TEENSY_PINn, PAL_MODE_INPUT_PULLUP);
  47
  48 The last parameter is the mode. For keyboards, the usual ones that are used are `PAL_MODE_INPUT_PULLUP` (input with a pullup), `PAL_MODE_INPUT_PULLDOWN` (input with a pulldown), `PAL_MODE_INPUT` (input floating, a.k.a. Hi-Z), `PAL_MODE_OUTPUT_PUSHPULL` (output in the Arduino sense -- can be then set HIGH or LOW).
  49
  50 ### Setting
  51
  52 Pins are set HIGH (after they've been put into `OUTPUT_PUSHPULL` mode) by
  53
  54         palSetPad(TEENSY_PINn_IOPORT, TEENSY_PINn);
  55
  56 or set LOW by
  57
  58         palClearPad(TEENSY_PINn_IOPORT, TEENSY_PINn);
  59
  60 Toggling can be done with
  61
  62         palTogglePad(TEENSY_PINn_IOPORT, TEENSY_PINn);
  63
  64 Alternatively, you can use
  65
  66         palWritePad(TEENSY_PINn_IOPORT, TEENSY_PINn, bit);
  67
  68 where `bit` is either `PAL_LOW` or `PAL_HIGH` (i.e. `0` or `1`).
  69
  70 ### Reading
  71
  72 Reading pin status is done with
  73
  74         palReadPad(TEENSY_PINn_IOPORT, TEENSY_PINn);
  75
  76 The function returns either `PAL_HIGH` (actually `1`) or `PAL_LOW` (actually `0`).
  77
  78 ### Further docs
  79
  80 All the commands that are available for pin manipulation through ChibiOS HAL are documented in [ChibiOS PAL driver docs](http://chibios.sourceforge.net/docs3/hal/group___p_a_l.html).