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://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.4) 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`. Similarly for Teensy 3.2, there's `Makefile.3.2`.
  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 (power saving during suspend). 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).