fix folder name
[tmk_keyboard.git] / keyboard / teensy_lc_onekey / instructions.md
CommitLineData
c61210cf 1# Teensy LC, 3.0, 3.1, 3.2 support
2
82e8e6fb 3These ARM Teensies are now supported through [ChibiOS](http://chibios.org).
c61210cf 4
5You'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
be9c2935 7Next, you'll need ChibiOS. For Teensies, you'll need code from two repositories: [chibios-main](https://github.com/ChibiOS/ChibiOS) and [chibios-contrib](https://github.com/ChibiOS/ChibiOS-Contrib).
8If you're not using git, you can just download a [zip of chibios from here](https://github.com/ChibiOS/ChibiOS/archive/a7df9a891067621e8e1a5c2a2c0ceada82403afe.zip), unpack the zip, and rename/move the unpacked directory (named `ChibiOS-<long_hash_here>`) to `tmk_core/tool/chibios/ChibiOS` (so that the file `tmk_core/tool/chibios/ChibiOS/license.txt` exists). Now the same procedure with a [zip of chibios-contrib from here](https://github.com/ChibiOS/ChibiOS-Contrib/archive/e1311c4db6cd366cf760673f769e925741ac0ad3.zip): unpack and move `ChibiOS-Contrib-<long_hash_here>` to `tmk_core/tool/chibios/ChibiOS-Contrib`.
b25da7a5 9
b25faf87 10If you're using git, you can just clone the two repos inside `tmk_core/tool/chibios`: [chibios](https://github.com/ChibiOS/ChibiOS) and [chibios-contrib](https://github.com/ChibiOS/ChibiOS-Contrib).
82e8e6fb 11
12(Why do we need chibios-contrib? Well, the main repo focuses on STM32 chips, and Freescale/NXP Kinetis chips are supported via the Contrib repository.)
c61210cf 13
be9c2935 14This should be it.
15
16Running `make` in `keyboard/teensy_lc_onekey` should create a working firmware in `build/`, called `ch.hex`.
c61210cf 17
18For more notes about the ChibiOS backend in TMK, see `tmk_core/protocol/chibios/README.md`.
19
20## About this onekey example
21
0998a993 22It'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`.
c61210cf 23
24## Credits
25
c1c8e079 26TMK itself is written by hasu, original sources [here](https://github.com/tmk/tmk_keyboard).
27
c61210cf 28The 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.
29
30## Features that are not implemented yet
31
0998a993 32Currently only the more fancy suspend features are not there (power saving during suspend). The rest should work fine (reports either way are welcome).
c61210cf 33
34# Matrix programming notes
35
36The notes below explain what commands can be used to examine and set the status of Teensy pins.
37
38## ChibiOS pin manipulation basics
39
40### Pins
41
42Each pin sits on a "port", each of which comprises at most 32 individual pins.
43So 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.
44
45Within 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.
46
47### Mode
48
49A MCU pin can be in several modes. The basic command to set a pin mode is
50
51 palSetPadMode(TEENSY_PINn_IOPORT, TEENSY_PINn, PAL_MODE_INPUT_PULLUP);
52
53The 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).
54
55### Setting
56
57Pins are set HIGH (after they've been put into `OUTPUT_PUSHPULL` mode) by
58
59 palSetPad(TEENSY_PINn_IOPORT, TEENSY_PINn);
60
61or set LOW by
62
63 palClearPad(TEENSY_PINn_IOPORT, TEENSY_PINn);
64
aa2c5682 65Toggling can be done with
66
67 palTogglePad(TEENSY_PINn_IOPORT, TEENSY_PINn);
68
69Alternatively, you can use
70
71 palWritePad(TEENSY_PINn_IOPORT, TEENSY_PINn, bit);
72
73where `bit` is either `PAL_LOW` or `PAL_HIGH` (i.e. `0` or `1`).
74
c61210cf 75### Reading
76
77Reading pin status is done with
78
79 palReadPad(TEENSY_PINn_IOPORT, TEENSY_PINn);
80
81The function returns either `PAL_HIGH` (actually `1`) or `PAL_LOW` (actually `0`).
aa2c5682 82
83### Further docs
84
85All 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).
Imprint / Impressum