if you compare split_util.h with the original project by ahtn, the
address we look for isLeftHand config went from addr 7 to addr 10
(decimal). The EEP files were not updated.
EE_HANDS should not be enabled by default since it's more confusing for
most users
The previous two options were COL2ROW, ROW2COL; this adds CUSTOM_MATRIX
to disable the built-in matrix scanning code.
Most notably, this obviates the need to set MATRIX_ROW_PINS or
MATRIX_COL_PINS.
since the keycode for a tap dance process gets process only after the
TAPPING_TERM timeout, you really only have ONESHOT_TIMEOUT -
TAPPING_TERM time to tap or double tap on the key. This fix save the
oneshot_mods into the action.state structure and applies the mods with
the keycode when it's registered. It also unregisters the mod when the
the tap dance process gets reset.
The oneshot cancellation code do not depend on the
action_tapping_process and since process_record get called via the
action_tapping_process logic moved the oneshot cancellation code into
the action_exec function just before the action_tapping_process call
Scenario:
Locking the KC_LSHIFT, and then using a tap dance key that registers a
S(KC_9) will unregister the KC_LSHIFT.
The tap dance or any keycode that is registered should not have the
side effect of cancelling a locked moditifier. We should be using a
similar logic as the TMK codes in tmk_core/comman/action.c:158.
A macro key can now be easily set to act as a modifier on hold, and
press a shifted key when tapped. Or to switch layers when held, and
again press a shifted key when tapped.
Various other helper defines have been created which send macros when
the key is pressed, released and tapped, cleaning up the
action_get_macro function inside keymap definitions.
The layer switching macros require a GCC extension - 'compound
statements enclosed within parentheses'. The use of this extension is
already present within the macro subsystem of this project, so its use
in this commit should not cause any additional issues.
MACRO_NONE had to be cast to a (macro_t*) to suppress compiler
warnings within some tapping macros.
* master:
Clarify license on abnt2 keymap (#1038)
replace jackhumbert with qmk
Add gitter image, start update to qmk org
Remove COLEMAK from preonic_keycodes enum
layer defines to enum
Update readme for smt Preonic keymap
Add smt keymap for Preonic
updated all the other keymaps to support the new changes.
fix: infinity60 keyboard was not using quantum features.
Compare Makefile with itself instead of using `--help`
In register_code16 and unregister_code16 we call register_code and
unregister_code twice, once for the mods and once for the keycode.
The (un)register_code have many check to see that keycode we have sent
however because we know that we are sending it a mods key, why not
just skip all of it and call (un)register_mods instead. This will skip
alot of checks and should speedup the loop a little.
the quantum matrix codes where not being initialized or/and called
so no feature of the quantum firmware could be used. These codes have
been added and now we can enjoy the quantum firmware goodness.
* Add HOME/END keys as upper/lower on arrow-up/down
* Reduce .hex file size by turning off unneeded options
* Put digit keypad onto left hand upon RAISE; this will sometimes be preferable to double-hits of right hand
* Moved duplicated defines out of inappropriate source files (matrix
pins in keymap subdirectory)
* Eliminated default keymap directory
* Hardcoded serial keymap to use serial defines and EE_CONFIG
* Hardcoded i2c keymap to use i2c defines
- Swiss German Ergodox layout:
Added ENTER key to left keyboard half on media layer
such that the enter key is available on both halves to
be able to flash both halves without an additional keyboard.
- Add Swiss German layout for Ergodox Infinity based on default
layout for Ergodox EZ.
- Minor changes in the event loop to prevent flashing display
background lights.
Since we can't read the real_mods and oneshot_mods static variable
directly within the update_user_visualizer_state
function (Threading and serial link). We are know storing the mods
states in the visualizer_keyboard_status_t structure. We can now
display the status of the modifier keys on the LCD display.
After setting a ONESHOT_TIMEOUT value, the oneshot layer state would
not expire without an event being triggered (key pressed). The reason
was that in the process_record function we would return priort to
execute the process_action function if it detected a NOEVENT cycle. The
process_action contained the codes to timeout the oneshot layer state.
The codes to clear the oneshot layer state have been move just in
front of where we check for the NOEVENT cycle in the process_record
function.
Removed Alt on base layer, replaced with Function layer.
Moved function keys to left hand. Added mouse keys to right hand on the function layer.
Moved middle click on gaming layer to be consistent with mouse layer.
Added macro _USER. Macro contents are not implemented yet.
new file: keyboards/ergodox/keymaps/ishigoya-jp/img/keyboard-layout-jpL.png
new file: keyboards/ergodox/keymaps/ishigoya-jp/img/keyboard-layout-numL.png
modified: keyboards/ergodox/keymaps/ishigoya-jp/keymap.c
new file: keyboards/ergodox/keymaps/ishigoya-jp/readme.md
Fix memory leaks by using stack instead of malloc
Reduce memory usage by having less temporary bufffers
Remove warnings by adding includes
Decrease code size by 608 bytes (mostly due to not linking malloc)
More robust handling of buffer overflows
Miscellaneous
=============
* `µ` can now be entered with UCIS.
* `™` can now be entered with UCIS.
Tools
=====
* `tools/hid-commands` can now find Banshee, and prefers it over Kodi.
* `tools/hid-commands` can now find Chrome too, not juts Chromium.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
There are a lot of PS/2 commands, some are vendor/device specific, so we
provide a weak ps2_mouse_init_user() to be implemented in each keyboard
that need it.
There are a lot of PS/2 commands, some are vendor/device specific, so we
provide a weak ps2_mouse_init_user() to be implemented in each keyboard
that need it.
There are now 3 potential locations to send HID reports:
1. USB
2. The bluefruit easy key
3. Adafruit BLE
Generally speaking, if USB is connected then we should prefer to
send the reports there; it is generally the best channel for this.
The bluefruit module has no feedback about bluetooth connectivity
so the code must speculatively send reports over both USB and bluetooth.
The BLE module has connectivity feedback. In general we want to
prefer to send HID reports over USB while connected there, even
if BLE is connected. Except that it is convenient to force them
over BLE while testing the implementation.
This policy has been extracted out into a where_to_send function
which returns a bitmask of which of the channels should be used.
This implements some helper functions that allow sending key reports
to an SPI based Bluetooth Low Energy module, such as the Adafruit
Feather 32u4 Bluefruit LE.
There is some plumbing required in lufa.c to enable this; that
is in a follow-on commit.
Unlike the arduino functions, these don't take abstract pin numbers,
they take pin labels like `B0`. Also, rather than taking very
generic parameter names, these take slightly more descriptive
enum values.
These improve the clarity of code that would otherwise be inscrutable
bit manipulation in tersely named port register names.
Adopt the macros for saving/restoring the interrupt state
that are provided by the avr gcc environment.
Removing intialization of the timer value; this shaves off
a few bytes because globals are default initialized to zero.
Define a default TAPPING_TERM in quantum.c, for keyboards that do not
have it set. Fixes the CI failure.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
When one holds a Space Cadet shift, to have it act as a shift, so that
mouse behaviour changes, when released without any other key pressed, it
still registers a paren. To remedy this, add a hold timeout: if the key
is held longer than TAPPING_TERM, it will not register the parens.
Fixes#884, with the side-effect of not being able to have parens
trigger the OS-side repeat anymore.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Plover's steno support likes quasi-qwerty, and gaming likes qwerty,
and I like dvorak, so... what if I could have it all?
Signed-off-by: seebs <seebs@seebs.net>
At this point, I consider the batch scripts @IBNobody and I worked on to mostly be a failure. They've proven to be unreliable, too dependent on the environment they're being run in, and I've seen far too many examples of people having frustrating issues with them that I haven't been able to help them with. They can also produce misleading and confusing error messages. I've been pointing people to use the WSL for a while now. Eventually, I think we should make a proper replacement for the batch scripts, possibly with an environment in msys2. For now, the WSL method in Windows 10 is far more reliable, and is easy to set up.
I also cleaned up some things in the WSL instructions themselves.
new file: keyboards/lets_splitv2/Makefile
new file: keyboards/lets_splitv2/config.h
new file: keyboards/lets_splitv2/i2c.c
new file: keyboards/lets_splitv2/i2c.h
new file: keyboards/lets_splitv2/imgs/split-keyboard-i2c-schematic.png
new file: keyboards/lets_splitv2/imgs/split-keyboard-serial-schematic.png
new file: keyboards/lets_splitv2/keymaps/default/keymap.c
new file: keyboards/lets_splitv2/lets_split.c
new file: keyboards/lets_splitv2/lets_split.h
new file: keyboards/lets_splitv2/matrix.c
new file: keyboards/lets_splitv2/pro_micro.h
new file: keyboards/lets_splitv2/readme.md
new file: keyboards/lets_splitv2/serial.c
new file: keyboards/lets_splitv2/serial.h
new file: keyboards/lets_splitv2/split_util.c
new file: keyboards/lets_splitv2/split_util.h
new file: keyboards/maxipad/Makefile
new file: keyboards/maxipad/config.h
new file: keyboards/maxipad/keymaps/default/Makefile
new file: keyboards/maxipad/keymaps/default/config.h
new file: keyboards/maxipad/keymaps/default/keymap.c
new file: keyboards/maxipad/keymaps/default/readme.md
new file: keyboards/maxipad/maxipad.c
new file: keyboards/maxipad/maxipad.h
new file: keyboards/maxipad/readme.md
* upstream/master: (1239 commits)
Update ez.c
removes planck/rev3 temporarily
Move hand_swap_config to ez.c, removes error for infinity
Update Makefile
ergodox: Update algernon's keymap to v1.9
Added VS Code dir to .gitignore
Support the Pegasus Hoof controller.
[Jack & Erez] Simplifies and documents TO
add readme
use wait_ms instead of _delay_ms
add messenger
init keymap
Add example keymap
Adding whiskey_tango_foxtrot_capslock ergodox keymap
Unicode map framework. Allow unicode up to 0xFFFFF using separate mapping table
CIE 1931 dim curve
Apply the dim curve to the RGB output
Update the Cluecard readme files
Tune snake and knight intervals for Cluecard
Tunable RGB light intervals
...
Overall changes
===============
* `F12` was replaced by an `Fx` key, that activate the **Media** layer
as a one-shot layer, and also `Alt` as a one-shot modifier.
Base layer changes
==================
* The `Media Stop` key is now a tap-dance key, and resets the device for
programming on the fourth tap.
Miscellaneous
=============
* `π` can now be entered with UCIS.
* `🐁` can now be entered with UCIS.
Tools
=====
* The `tools/layer-notify` tool was removed, it was an example, which I
don't use.
`tools/hid-commands`
--------------------
* Now looks at the `DISABLE_APPSEL_START` environment value, and does
not display an AppSel notification if it is non-empty.
* Will attempt to re-program the keyboard when receiving a `reflash`
command.
* No longer tries to select Emacs 24 on `APPSEL_EMACS`, rather, it goes
for any Emacs.
* The `APPSEL_MUSIC` command now includes Kodi in the list too, as the
last choice.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Rewrote QWERTY to make it a first-class citizen instead of just a glorified game layer.
Added a lot of keys to Extend layer to bring it in line with my Atreus.
Plenty of other changes too.
ADORE
-----
* Major rearrangements were made, to reduce pinky use, and to balance
out the hand usage.
Tools
-----
* The `hid-commands` tool will now display a notification when
the **AppSel** layer is triggered.
* The `log-to-heatmap.py` tool now treats the innermost keys on the
bottom row as thumb keys, as far as statistics are concerned.
Miscellaneous
-------------
* Fixed the **Steno** toggle key.
* My wife is now present on the keyboard too.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Overall changes
===============
* The number row has been completely rearranged on both the **Base** and
the **ADORE** layers.
* The number/function key behavior was changed: function keys are now on
the **Media**.
* The `:`/`;` and `-`/`_` keys were put back to their thumb position on
the bottom row, on both the **Base** and **ADORE** layers.
* The bottom large keys on the inner side of each half now function as
[tmux](http://tmux.github.io/) keys: the left to send the prefix, the
right to send the `display-panes` key. The left also doubles as a GNU
screen prefix key, and sends `C-a` when double tapped.
* A number of functions, such as the **AppSel** layer, now require the
`hid-commands` tool to be running, with the output of `hid_listen`
being piped to it.
ADORE
=====
* `Y` and `X` have been swapped again.
Media/Navigation layer
======================
* The function keys are now on this layer.
* Mouse keys have been removed.
* Media start/stop/prev/next have been removed.
* `Print screen` has been removed.
* There is only one screen lock key now.
Heatmap
=======
* Fixed a few issues in the finger-stats calculation.
* The tool now also timestamps and saves all input lines to a logfile,
which it loads on start, allowing one to continue the collection after
upgrading the tool.
* The heatmap tool will now colorize the stats by default.
* The periodic stats are now printed in a more compact format.
Tools
=====
* Added a new tool, `tools/layer-notify` that listens to layer change
events on the HID console, and pops up a notification on layer
changes.
* Another new tool, `tools/text-to-log.py` has been added that converts
arbitrary text to a keylogger output, which can be fed to the heatmap
generator.
* A number of features have been moved to the `tools/hid-commands`
utility. These generally are OS dependent, and are easier to implement
on the software side.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
User print disables the normal print messages in the body of QMK/TMK
code and is meant as a lightweight alternative to NOPRINT. Use it when
you only want to do a spot of debugging but lack flash resources for
allowing all of the codebase to print (and store their wasteful
strings).
- remove media-space and media-shift-space; put a play/pause key at media-m instead
- add print screen, scroll lock, and pause/break to the media layer
And in the readme:
- don't say we don't have any Windows-specific keys
- add mnemonics for thumb-alt and thumb-ctrl positioning
There was an odd case, which confused the hell out of tap-dance: suppose
you had a number of tap-dance keys, on a layer, and as part of the
tap-dance, you turned that layer off - or had it on one-shot to begin
with. In this case, the keydown event would trigger the tap-dance key,
but the keyup would not. This had two funky consequences:
- tap-dance did not correctly register that the dance has ended.
- pressing any other tap-dance key would interrupt the previous
tap-dance, and potentially input unwanted characters.
To fix this, we simply do not start a tap-dance sequence on keyup, only
when it is pressed. This way the previous sequence has enough time to
time-out and finish properly, and we don't get confused.
This fixesalgernon/ergodox-layout#107.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
There may be cases where one would like to know the current Unicode
input mode, without having to keep track of it themselves. Add a
function that does just this.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
During the build system refactor, support for enabling UCIS seems to
have been lost. This little patch adds that back, so that keymaps using
UCIS can be compiled again.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
* Switched Tab and Super on the default layout
* Moved Shift on Extend to pinky
* Moved Caps Lock to upper right corner
* Moved gaming toggle to avoid blocking Escape
Major changes include:
Base layer changes
------------------
* The parentheses & bracket keys have been merged: tapping them results
in `[` or `{` (if it was shifted), double tapping leads to `(`.
* The `:;` and `-_` keys are now available on the base layer, on
their **ADORE** location, too, just below `[{(`/`]})`.
* The `Apps` key has been replaced by `F12`.
* The `-`/`_` is no longer a tap-dance key.
ADORE layer changes
-------------------
* Adjustments were made to the **ADORE** layer, to separate some
inconvenient combinations.
Miscellaneous changes
---------------------
* `LEAD u` now starts the symbolic unicode input system, instead of the
OS-one.
* The mouse acceleration keys on the **Navigation and Media* layer have
been turned into toggles: tap them once to turn them on, until tapped
again. Tapping an accelerator button will turn all the others off.
* When the **ARROW** layer is on, the *red* and *blue* LEDs light up
now.
Heatmap
-------
* The built-in keylogger has been greatly enhanced, it now outputs the
pressed state, and the layer (Dvorak or ADORE). As such, the
`ADORE_AUTOLOG` option has been removed, instead there is
`AUTOLOG_ENABLE` now, which when enabled, makes the keylogger start
when the keyboard boots. It defaults to off.
* The heatmap generator received a lot of updates.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
In order to not declare the same variable in multiple objects (which
happens when building UCIS-enabled keymap for both the ErgoDox EZ and
the ErgoDox Infinity), move the declaration to the .c file, and keep
only an extern reference in the header.
Many thanks to @fredizzimo for spotting the error in Travis, and
suggesting the fix.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
When running make from either a keyboard folder or a subproject
it runs all keymaps for all subprojects and the selected subproject
respectively. Without this fix, the same doesn't happen if your
run make clean for example. As it would just provide you with an
error message. Now this will work as expected.
This adds an action, `ACTION_SWAP_HANDS`, that swaps the the keys on the keyboard across a keymap-defined hemisphere in order to support one-hand typing without requiring a separate one-handed layer. See updated `doc/keymap.md` for more information.
It has been required for a while now, and now actually checked in
the makefiles. Before, if you didn't have it installed it would
just recompile everything.
The readme hasn't been updated to reflect this, I think we need
to go through that separately, and see what's really needed. Or
just instruct people to run the batch scripts.
A single keyboard is always by default compiled in verbose mode.
While multiple keyboards are compiled in silent mode. This can be
overriden by the silent variable from the command line
These functions register not only the 8bit keycode, but the modifiers
too. It doesn't handle the full range of the upper 8bits, just the mods,
but that's a good start.
Changed the tap-dance pair functions to use these, so one can do:
`ACTION_TAP_DANCE_DOUBLE (KC_COLN, KC_SCLN)`
...and that will do the right thing.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
This reworks how the tap-dance feature works: instead of one global
state, we have a state for each tap-dance key, so we can cancel them
when another tap-dance key is in flight. This fixes#527.
Since we have a state for each key, we can avoid situation where a keyup
would mess with our global state. This fixes#563.
And while here, we also make sure to fire events only once, and this
fixes#574.
There is one breaking change, though: tap-dance debugging support was
removed, because dumping the whole state would increase the firmware
size too much. Any keymap that made use of this, will have to be
updated (but there's no such keymap in the repo).
Also, there's a nice trick used in this rework: we need to iterate
through tap_dance_actions in a few places, to check for timeouts, and so
on. For this, we'd need to know the size of the array. We can't discover
that at compile-time, because tap-dance gets compiled separately. We'd
like to avoid having to terminate the list with a sentinel value,
because that would require updates to all keymaps that use the feature.
So, we keep track of the highest tap-dance code seen so far, and iterate
until that index.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Include `action_tapping.h`, so the keymap does not have to define a
`TAPPING_TERM` for us, and we can use the default.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
When entering unicode codes, use some delay, so the OS has time to
process the information. This is not needed on all systems, but some
seem to require it.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
It turns out that register_hex32 did not work reliably, and some systems
only allow 7 chars after the unicode magic sequence, while others allow
8. To remedy the situation, store the codes as strings, and type those
in instead of doing bit shifting magic.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Extract out the part of `qk_ucis_start` that inputs the placeholder
symbol, and make it weak, so it can be overridden.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
If the symbol name being entered is longer than the max, stop recording
it, and stop processing keycodes apart from the ones that can delete,
finish or cancel the sequence.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
The purpose of this change is to allow keymaps to specify a dictionary
of unicode symbol name to code mappings, and let the person at the
keyboard enter unicode symbols by name.
This is done by having a way to trigger unicode symbol input mode, when
all keys are cached until Esc, Enter or Space are pressed. Once that
happens, we try to look up the symbol from our lookup table. If found,
we erase back, and type the unicode magic in to get that symbol. If not
found, we still erase back, start unicode input mode, and replay what
the user typed in.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
This moves the unicode input start / end sequences into their own
functions, so keymaps and other functionality can build on it too.
At the same time, it changes how the Linux variant works, to match
reality: CTRL+SHIFT must be unregistered too, and we close the thing
with a Space instead.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
All keymaps that were included in VinnyCordeiro's repository were ported to QMK.
Main Readme was copied over from VC's repo, slightly altered.
Main Makefile was updated to reflect VC's original configuration.
Small changes in felix keymap.
In the header, this was defined as `set_unicode_input_mode`, but the
implementation had `set_unicode_mode` for a name. Changed the
implementation to match the header.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Major changes include:
* The **1HAND** layer has been removed.
* A `Delete` key is now available on the right thumb cluster.
* The **ADORE** layer received a major update, see the updated layout
image.
* It is now possible to enable automatic logging for the **ADORE**
layer, by setting the `ADORE_AUTOLOG` makefile variable to `yes` when
compiling the keymap. It is off by default.
* The `~` key and the `Media Next/Prev` key have been swapped on
the **base** layer.
* On the **ARROW** layer, `Backspace` has been replaced by `Enter`.
* There is some experimental support for entering Unicode symbols.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Instead of using a thumb shift, I was given the idea of using the pinky keys as dual-role keys that also send the Shift keypress.
This gives me a Shift key on each hand again, but it will make me learn to Shift with opposite hands after all.
* Adding my own keymaps to the following keyboards:
Planck, Preonic, Atreus, Ergodox
* Delete dvorak.png
Not reflective of my layout.
* Delete readme.md
file cleanup, removing file that doesn't apply to my layout.
* Delete old_keymap.c
file cleanup
* Delete README.md
file clean up.
* Delete README.md
file cleanup
* Delete keymap.c
file cleanup
* Changed behavior of _DVORAK layout's KC_RSFT to SFT_T(KC_ENT) for flexibility's sake.
Updated the rest of the keymap to reflect the current (as of 19:37 on 08 Aug 2018) default
layout and default makefile.
Checking for ARCH is not good enough, since some subprojects define it.
Ergodox Ez for example. The leads to running the make from
keyboards/ergodox/ez failing. The keyboard makefile will not be included
in that case, and therefore not the CUSTOM_MATRIX either.
Furthermore the output files are read from many different .build
directories, so it doesn't fail deterministically. For example on the
Travis CI the compilation passes, since there's no outdated objects that
needs recompilation.
Some links were still pointing to `/keyboards/ergodox_ez`, while the
directory is `/keyboards/erdogox` now.
Not all references have been updated, and some of the text here and
there may need updating to mention the ErgoDox Infinity too, but that's
out of the scope for this quick fix.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
* When toggling the key logging on or off, the LEDs will do a little dance.
* The keylogger is now optional, but enabled by default. Use `KEYLOGGER_ENABLE=no` on the `make` command line to disable it.
* The `TAB`/`ARRW` key was turned into a tap-dance key, allowing one to toggle the **ARROW** layer on by double-tapping, and as such, avoid the need to hold the key.
* The `-`/`_` key was turned into a tap-dance key too.
* There is now a way to travel time with the keyboard, toggle the feature on by hitting `LEAD t`.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Instead of `&& false`, explicitly `exit 1` to make the rules using these macros
fail. This fixes#571, and likely breaks Travis badly.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Atreus: Removed home row Shift. It's under the thumb anyway. Also replaced dual modifier keys with macro keys (cut, copy, paste, undo).
Ergodox: Made Colemak the default layer instead of Dvorak. Also began the process of bringing it in line with the Atreus layout I've been working on.
Removes a number of duplicated code, by passing actions around instead
of keycodes, so the various dance action functions do not have to look
up the action, but the caller does that for them.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Refactored the code a little, so all callbacks now receive a `user_data`
pointer, which can be anything. As an example, the key pairs from
`ACTION_TAP_DANCE_DOUBLE` now use this, and custom, built-in functions.
This makes it easier to extend the tap dance functionality, and also
simplifies the code a little.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
With this change, tap dance will now store the pressed state of the
tap-dance key, and allow one to make an action sooner, while the key is
still held, and only unregister when the key is released.
The registration must happen in the `on_dance_finished` callback, while
unregistering goes to `on_reset`. The surrounding code makes sure not to
call either multiple times.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
This change adjusts the KEYMAP() function to provide a more visual representation of the key positions on the keyboard. Previously, keymaps have been defined directly using arrays for the Atreus keyboard. While this works, it doesn't utilize the helpful KEYMAP() function at all to allow the user to visually position the key codes for ease of editing. See the Ergodox-EZ KEYMAP() function and layouts for a great example of how this can work.
This change should not break any existing Atreus layouts. At the time of this commit, there are two existing layouts for the Atreus board, and neither use the KEYMAP() function.
This change adjusts the KEYMAP() function to provide a more visual representation of the key positions on the keyboard. Previously, keymaps have been defined directly using arrays for the Atreus keyboard. While this works, it doesn't utilize the helpful KEYMAP() function at all to allow the user to visually position the key codes for ease of editing. See the Ergodox-EZ KEYMAP() function and layouts for a great example of how this can work.
This change should not break any existing Atreus layouts. At the time of this commit, there are two existing layouts for the Atreus board, and neither use the KEYMAP() function.
This updates my ErgoDox EZ layout to v1.3, which has the following
noteworthy changes:
* Added support for logging keys, by pressing `LEAD d`. Also included is
a tool to generate a **heatmap** out of the logs.
* The arrow and navigation keys were rearranged again, and now require
an additional key being held to activate. See the **base layer** for
an image that shows where arrows are.
* The **experimental** layer has been redone, and is now
called **ADORE**, and as such, can be enabled by `LEAD a` now.
* Switching between Dvorak and ADORE is now persisted into EEPROM, and
survives a reboot.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
when using tap dance, we have the `regular` callback that is called on
the last tap. this commit adds an `anyway` callback that is called on
every tap, and a `reset` callback that is called on reset of the tap
dance taps.
Modified the LUFA USB HID Descriptor to change the logical/usage
minimums for System Control from 0x01 (Mouse) to 0x81 (System Power
Down), this fixes OS X recognizing the Planck as having a mouse and
tablet, even with mousekeys off.
The prerequisites at the start of the build process are order-only
so that the trget don't link again. Also added as a dependency to
the compilation to force the messages to be printed at the start
Moves RGB controls out of the macro function and assigns them their own
keycodes:
RGB_TOG (toggle on/off)
RGB_MOD (mode step)
RGB_HUI (increase hue)
RGB_HUD (decrease hue)
RGB_SAI (increase saturation)
RGB_SAD (decrease saturation)
RGB_VAI (increase brightness)
RGB_VAD (decrease brightness)
Allows you to press RSHIFT to cancel the insertion of a "(" when holding down LSHIFT. Alternatively, allows you to press LSHIFT to cancel the insertion of a ")" when holding down RSHIFT. This change enables you to renege from outputting a character should you press a shift key erroneously.
* Add ChibiOS packages to the avr_setup script
* Add git as a dependency
* Rename avr_setup.sh -> install_dependencies.sh
Also fix the Vagrant welcome message to reflect the new directory
structure.
* Modularity and gcc warnings fixes.
* Add ChibiOS support (USB stack + support files).
* Make usb_main more USB_DRIVER #define independent.
* Move chibios to tool.
* Implement jump-to-bootloader.
* Small updates.
* Fix bootloader-jump compiling.
* Move AVR specific sleep_led.c into avr.
* Add basic sleep_led for chibios.
* Update chibios README.
* NKRO fixes.
* Rename some Makefile defines.
* Move STM32 bootloader address config to separate .h file.
* Add ARM Teensies bootloader code.
* Fix chibios/usb_main GET_REPORT handing.
* Add missing #include to keymap.c.
* Make bootmagic.c code portable (_delay_ms -> wait_ms).
* Move declaration of keymap_config.
Should really not declare variables in .h files - since it's included
in different .c files, a proper linker then complains that the same
variable is declared more than once (once for each .c file that the
offending .h is included in).
* Add eeprom support for chibios/kinetis.
* Rename chibios example keyboard.
* Move chibios/cortex selection to local Makefiles.
* Chibios: use WFI in idle. WIP suspend stuff.
* ChibiOS/kinetis: sending remote wakeup.
* ChibiOS/STM32: send remote wakeup.
* Fix report size of boot protocol.
* Fix drop key stroke
Keyboard report should be checked if its transfer finishs successfully.
Otherwise key stroke can be missing when other key event occurs
before the last report transfer is done.
Boot protocol 10ms interval probably causes this problem in case
it receives key events in a row within the period. NKRO protocol
suffers less or nothing due to its interval 1ms.
* Chibios/usb_main: rename a variable for clarity.
* Add correct chibios/bootloader_jump for infinity KB.
* ChibiOS: make reset request more CMSISy.
* Chibios: Add breathing sleep LED on Kinetis MCUs.
* ChibiOS: Update infinity bootloader code to match updated ChibiOS.
* ChibiOS: prettify/document sleep_led code.
* Chibios: Remove the wait in the main loop.
* Add maple mini code.
* Do timeout when writing to CONSOLE EP queue.
Fixes TMK bug #266.
* Chibios: add 'core/protocol' to the makefiles' search path.
* Chibios: Update to new USB API.
* Chibios: add more guards for transmitting (fix a deadlock bug).
* Add update for chibios in README
* Chibios: Fix a HardFault bug (wait after start).
* Chibios: cleanup usb_main code.
* Chibios: Revert common.mk change (fix AVR linking problem).
* core: Fix chibios user compile options
Compile options can be defined in project Makefile such as UDEFS, UADEFS, UINCDIR, ULIBDIR and ULIBS.
* Sysv format for ChibiOS arm-none-eabi-size
Some new patches to ChibiOS puts heap as it's own section. So the
berkeley format is now useless, as the heap will be included in the
BSS report. The sysv format displays the bss size correctly.
* Fix hard-coded path of CHIBIOS
* Add support for new version of ChibiOS and Contrib
The Kinetis support has moved to a separate Contrib repository in
the newest version of Chibios. There has also been some structure
changes. So this adds support for those, while maintaining back-
wards compability.
* Update ChibiOS instructions
* Chibios: implement sleep LED for STM32.
* Chibios: Update the main chibios README.
* Chibios: fix STM32_BOOTLOADER_ADDRESS name.
* Chibios: make the default bootloader_jump redefinable (weak).
* Chibios: disable LTO (link-time optimisation).
With LTO enabled, sometimes things fail for mysterious reasons
(e.g. bootloader jump on WF with LEDs enabled), just because the
linker optimisation is too aggressive.
* Chibios: add default location for chibios-contrib.
* ChibiOS: update mk to match chibios/master.
* ChibiOS: update instructions.md.
* Add chibi_onekey example.
* Add comments to chibi_onekey Makefile.
* Rename some Makefile defines.
* Move STM32 bootloader address config to separate .h file.
* Rename chibios example keyboard.
* Move chibios/cortex selection to local Makefiles.
* Add Teensy LC onekey example.
* Chibios: use WFI in idle. WIP suspend stuff.
* Update chibi/teensy instructions.
* Update chibios/Teensy instructions.
* Add infinity_chibios
* Add keymap_hasu.c
* Infinity_chibios: select correct bootloader_jump.
* Infinity_chibios: improve comments.
* Add generic STM32F103C8T6 example.
* Add maple mini code.
* STM32F103x fixes.
* Add maple mini pinout pic.
* Chibios: updates for 3.0.4 git.
* Chibios: rename example stm32_onekey -> stm32_f072_onekey.
* Chibios: add makefiles for Teensy 3.x examples.
* Chibios: update Teensy 3.x instructions.
* Chibios: Tsy LC is cortex-m0plus.
* Chibios: add more guards for transmitting (fix a deadlock bug).
* Change README for chibios
* Chibios: update examples to current chibios git.
Match the changes in mainline chibios:
- update chconf.h
- update supplied ld scripts structure
- update Teensy instructions (switch to official
chibios and introduce contrib)
* Add ChibiOS and ChibiOS-Contrib submodules
Also fix the makefile path for them.
* Moves chibios keyboards to keyboards folder
* First version of ChibiOS compilation
Only the stm32_f072_onkey keyboard is ported at the moment. It
compiles, but still doesn't link.
* More chibios fixes
It now compiles without warnings and links
* Move the teensy_lc_onekey to the keyboards folder
* Clean up the make file rule structure
* Remove keymap_fn_to_action
* Update more ChibiOS keyboards to QMK
Most of them does not compile at the moment though.
* Use older version of Chibios libraries
The newest ones have problems with compilation
* Remove USB_UNCONFIGURED event
It isn't present in the older version of ChibiOS
* Fix the infinity_chibios compilation
* Fix potentially uninitialized variable
* Add missing include
* Fix the ChibiOS makefile
* Fix some Chibios keyboard compilation
* Revert the rules.mk file back to master version
* Combine the chibios and AVR makefiles
With just the required overrides in the respective platform
specific one.
* Slight makefile restrucuring
Platform specific compiler options
* Move avr specific targets out of the main rules
* Fix ChibiOS objcopy
The ChibiOS objcopy needs different parameters, so the parameters
are moved to the corresponding platform rule file
* Fix the objcopy for real this time
The comands were moved around, so chibios used avr and the ohter
way around.
Also change the objsize output format
* Fix the thumb flags
* Fix the infinity hasu keymap
* Per platform cpp flags
* Add gcc-arm-none-eabi package to travis
* Add arm-none-eabi-newlib to travis
* Fix the name of the libnewlib-arm-none-eabi lib
* Fix the ChibiOS paths
So that they are properly relative, and builds don't generate
extra folders
* Fix the board path of stm32_f103_onekey
* Only consider folders with Makefiles as subproject
* non-working commit
* working
* subprojects implemented for planck
* pass a subproject variable through to c
* consolidates clueboard revisions
* thanks for letting me know about conflicts..
* turn off audio for yang's
* corrects starting paths for subprojects
* messing around with travis
* semicolon
* travis script
* travis script
* script for travis
* correct directory (probably), amend files to commit
* remove origin before adding
* git pull, correct syntax
* git checkout
* git pull origin branch
* where are we?
* where are we?
* merging
* force things to happen
* adds commit message, adds add
* rebase, no commit message
* rebase branch
* idk!
* try just pull
* fetch - merge
* specify repo branch
* checkout
* goddammit
* merge? idk
* pls
* after all
* don't split up keyboards
* syntax
* adds quick for all-keyboards
* trying out new script
* script update
* lowercase
* all keyboards
* stop replacing compiled.hex automatically
* adds if statement
* skip automated build branches
* forces push to automated build branch
* throw an add in there
* upstream?
* adds AUTOGEN
* ignore all .hex files again
* testing out new repo
* global ident
* generate script, keyboard_keymap.hex
* skip generation for now, print pandoc info, submodule update
* try trusty
* and sudo
* try generate
* updates subprojects to keyboards
* no idea
* updates to keyboards
* cleans up clueboard stuff
* setup to use local readme
* updates cluepad, planck experimental
* remove extra led.c [ci skip]
* audio and midi moved over to separate files
* chording, leader, unicode separated
* consolidate each [skip ci]
* correct include
* quantum: Add a tap dance feature (#451)
* quantum: Add a tap dance feature
With this feature one can specify keys that behave differently, based on
the amount of times they have been tapped, and when interrupted, they
get handled before the interrupter.
To make it clear how this is different from `ACTION_FUNCTION_TAP`, lets
explore a certain setup! We want one key to send `Space` on single tap,
but `Enter` on double-tap.
With `ACTION_FUNCTION_TAP`, it is quite a rain-dance to set this up, and
has the problem that when the sequence is interrupted, the interrupting
key will be send first. Thus, `SPC a` will result in `a SPC` being sent,
if they are typed within `TAPPING_TERM`. With the tap dance feature,
that'll come out as `SPC a`, correctly.
The implementation hooks into two parts of the system, to achieve this:
into `process_record_quantum()`, and the matrix scan. We need the latter
to be able to time out a tap sequence even when a key is not being
pressed, so `SPC` alone will time out and register after `TAPPING_TERM`
time.
But lets start with how to use it, first!
First, you will need `TAP_DANCE_ENABLE=yes` in your `Makefile`, because
the feature is disabled by default. This adds a little less than 1k to
the firmware size. Next, you will want to define some tap-dance keys,
which is easiest to do with the `TD()` macro, that - similar to `F()`,
takes a number, which will later be used as an index into the
`tap_dance_actions` array.
This array specifies what actions shall be taken when a tap-dance key is
in action. Currently, there are two possible options:
* `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: Sends the `kc1` keycode when
tapped once, `kc2` otherwise.
* `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in
the user keymap - with the current state of the tap-dance action.
The first option is enough for a lot of cases, that just want dual
roles. For example, `ACTION_TAP_DANCE(KC_SPC, KC_ENT)` will result in
`Space` being sent on single-tap, `Enter` otherwise.
And that's the bulk of it!
Do note, however, that this implementation does have some consequences:
keys do not register until either they reach the tapping ceiling, or
they time out. This means that if you hold the key, nothing happens, no
repeat, no nothing. It is possible to detect held state, and register an
action then too, but that's not implemented yet. Keys also unregister
immediately after being registered, so you can't even hold the second
tap. This is intentional, to be consistent.
And now, on to the explanation of how it works!
The main entry point is `process_tap_dance()`, called from
`process_record_quantum()`, which is run for every keypress, and our
handler gets to run early. This function checks whether the key pressed
is a tap-dance key. If it is not, and a tap-dance was in action, we
handle that first, and enqueue the newly pressed key. If it is a
tap-dance key, then we check if it is the same as the already active
one (if there's one active, that is). If it is not, we fire off the old
one first, then register the new one. If it was the same, we increment
the counter and the timer.
This means that you have `TAPPING_TERM` time to tap the key again, you
do not have to input all the taps within that timeframe. This allows for
longer tap counts, with minimal impact on responsiveness.
Our next stop is `matrix_scan_tap_dance()`. This handles the timeout of
tap-dance keys.
For the sake of flexibility, tap-dance actions can be either a pair of
keycodes, or a user function. The latter allows one to handle higher tap
counts, or do extra things, like blink the LEDs, fiddle with the
backlighting, and so on. This is accomplished by using an union, and
some clever macros.
In the end, lets see a full example!
```c
enum {
CT_SE = 0,
CT_CLN,
CT_EGG
};
/* Have the above three on the keymap, TD(CT_SE), etc... */
void dance_cln (qk_tap_dance_state_t *state) {
if (state->count == 1) {
register_code (KC_RSFT);
register_code (KC_SCLN);
unregister_code (KC_SCLN);
unregister_code (KC_RSFT);
} else {
register_code (KC_SCLN);
unregister_code (KC_SCLN);
reset_tap_dance (state);
}
}
void dance_egg (qk_tap_dance_state_t *state) {
if (state->count >= 100) {
SEND_STRING ("Safety dance!");
reset_tap_dance (state);
}
}
const qk_tap_dance_action_t tap_dance_actions[] = {
[CT_SE] = ACTION_TAP_DANCE_DOUBLE (KC_SPC, KC_ENT)
,[CT_CLN] = ACTION_TAP_DANCE_FN (dance_cln)
,[CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
};
```
This addresses #426.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
* hhkb: Fix the build with the new tap-dance feature
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
* tap_dance: Move process_tap_dance further down
Process the tap dance stuff after midi and audio, because those don't
process keycodes, but row/col positions.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
* tap_dance: Use conditionals instead of dummy functions
To be consistent with how the rest of the quantum features are
implemented, use ifdefs instead of dummy functions.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
* Merge branch 'master' into quantum-keypress-process
# Conflicts:
# Makefile
# keyboards/planck/rev3/config.h
# keyboards/planck/rev4/config.h
* update build script
* non-working commit
* working
* subprojects implemented for planck
* pass a subproject variable through to c
* consolidates clueboard revisions
* thanks for letting me know about conflicts..
* turn off audio for yang's
* corrects starting paths for subprojects
* messing around with travis
* semicolon
* travis script
* travis script
* script for travis
* correct directory (probably), amend files to commit
* remove origin before adding
* git pull, correct syntax
* git checkout
* git pull origin branch
* where are we?
* where are we?
* merging
* force things to happen
* adds commit message, adds add
* rebase, no commit message
* rebase branch
* idk!
* try just pull
* fetch - merge
* specify repo branch
* checkout
* goddammit
* merge? idk
* pls
* after all
* don't split up keyboards
* syntax
* adds quick for all-keyboards
* trying out new script
* script update
* lowercase
* all keyboards
* stop replacing compiled.hex automatically
* adds if statement
* skip automated build branches
* forces push to automated build branch
* throw an add in there
* upstream?
* adds AUTOGEN
* ignore all .hex files again
* testing out new repo
* global ident
* generate script, keyboard_keymap.hex
* skip generation for now, print pandoc info, submodule update
* try trusty
* and sudo
* try generate
* updates subprojects to keyboards
* no idea
* updates to keyboards
* cleans up clueboard stuff
* setup to use local readme
* updates cluepad, planck experimental
* remove extra led.c [ci skip]
* disable power up for now
* config files updates
* makefile updates
* .h file updates, config tuning
* disable audio for yang
* Update setup script 1 for new folder structure
* Improve script 1 output
* Launch elevate if run without admin privileges
* Improve MinGW error message
* Improvements and fixes to second script
* Log elevate output in first script
Noticeable changes since the last pull request:
* The forced NKRO mode can be easily toggled off at compile-time, to
make the firmware compatible with certain operating systems.
* The `:;` key has changed behaviour: to access the `;` symbol, the key
needs to be double-tapped, instead of shifted.
* The `=` and `\` keys were swapped, `=` moved to the home row, on both
the **base** and the **experimental** layers.
* The arrow and navigation keys were redone, they are now more
accessible, but the navigation keys require an extra tap to access.
* The **Emacs** layer is gone, replaced by a simplified
**navigation and media** layer.
* `LEAD v` types the firmware version, and the keymap version.
* On the **experimental** layer, the `L` and `Q`, and the `K` and `G`
keys were swapped.
* The **Steno** layer gained a few more `#` and `*` keys, to make it
easier on my fingers.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
I haven't had a chance to update the Arch base box in a while so using the Ubuntu one is far more likely to succeed for a new user (I did test that box recently as I traded my ErgoDox EZ to a friend and needed to reprogram it for him).
Unfortunately the supported targets, like "quick", "all", "clean",
and so on has to be repeated two extra times, but this is the best
I can do with my makefile skills.
* Added WS2812 support for KC60
* Reorganized WS2812 support into its own keymap
* Fixed relative link in README
* Moved WS2812 mention in README to the bottom
* Fixed titling in WS2812 README
* Reverted KC60 Makefile and default keymap back
* Moved RGB specific config.h to ws2812 keymap folder
* Added my personal keymap
* Updated compiled hex
* Reverted KC60 files to 3f6fac47 before pull request #419
* Added WS2812 support for KC60
* Reorganized WS2812 support into its own keymap
* Fixed relative link in README
* Moved WS2812 mention in README to the bottom
* Fixed titling in WS2812 README
* Reverted KC60 Makefile and default keymap back
* Moved RGB specific config.h to ws2812 keymap folder
* More documentation
* Saving crontab for user on host
* Restructuring in keeping with recent changes to conventions
* Simplify submitting my fave cbbrowne keystroke by using SEND_STRING()
* Local change, not apropos to have in this repo
* Simplify logic; no need to return so much
* Add in a version key
* Add docs
* Split build date into a separate DEFINE
* Ensure there is a value even if not working within a git repo
* Should not include the compiled code in the repo
* compiled.hex files should not be included in the repo; they represent generated compiled code
* Fix spelling in comment
* Remove more generated files
* Add rule to ignore contents of .build directories; their contents are generated
* Revert removals of compiled files
Compared to the previous version, the following noteworthy changes have
been made to the keymap:
* The keyboard starts in NKRO mode, bootmagic and other things are
disabled.
* A STENO layer was added, to be used with Plover.
* An experimental layout was added, something halfway between Dvorak and
Capewell-Dvorak. A work in progress.
* `LEAD y` types \o/.
* Some keys on the BASE layer have been moved around:
- `?` moved to the left pinky, left of `Q`.
- `=` shifted one row down, but `F11` stayed where it was.
- `-` on the left half was replaced by `Tab`.
- `Tab`'s original position is taken by a `Media Next`/`Media Prev`
key.
- `:` now inputs `;` when shifted.
* `ESC` cancels the **HUN** layer too, not just modifiers.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
This adds the keyboard and keymap built, along with the QMK firmware's
git hash (or a timestamp), to OPT_DEFS. That, in turn, allows keymaps to
make use of these information, and do whatever they want with it. For
example, one could print them on `LEADER v` like this:
```c
SEQ_ONE_KEY (KC_V) {
SEND_STRING (QMK_KEYBOARD "/" QMK_KEYMAP " @ " QMK_VERSION);
}
```
This addresses #366.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
* Don't save the ctags file in the repo.
* Initial support for the KC60 board. Only 5x5 working so far.
* Rename because this isn't the same KC60 as others.
* Add in some generic layout.
Pins seem to be in the right order except the 6th column spews
gibberish.
* Don't need this for now.
* Move this to some other folder.
* Trying again to start over.
* Don't need to start over because I figured out why the 'broken' stuff wasn't working.
* Attempt to enable backlighting. It's on on pin B7 like other boards.
* Fix last port changes and fix LED control in keymap.
* Trying some other LED code.
* Bootloader needs to be bigger. Disabling backlight for now.
* Simplify LED code while I try to figure it out.
* Turn back on backlighting.
* Backlighting works now. Just need to get levels or breathing working.
* Trying to allow for turning off the LEDs before I get to brightness levels.
* The missing link: need to run the init_ports function for LEDs to work properly.
* Removing breathing stuff since it bricks the board.
* Clean up default layer.
* Cleanup keymap, KC60 doesn't support a 5th right bottom-row button.
* Add in the keymap I want for now.
* Back to escape by default.
* Move my personal keymap to the new place for keymaps.
* Add the version number for clarity.
* adds support for GH60 Satan keyboard
ANSI 125 layout, capslock and backlight implemented, support for
WS2812LED strip included
* added Phantom and GH60 Satan to travis
* More documentation
* Saving crontab for user on host
* Restructuring in keeping with recent changes to conventions
* Simplify submitting my fave cbbrowne keystroke by using SEND_STRING()
* Local change, not apropos to have in this repo
* Simplify logic; no need to return so much
* .build containment implemented
* no destructive variable setting - builds in either folder
* make from 3 places
* cleans before each build
* make from root with keyboard=keyboard, keymap=keymap
* make from keyboard/keyboard with keymap=keymap
* make from keymaps/keymap
* only implemented on planck
* adds color diag to avr-gcc
* makefiles for all plancks, clean-up
* quick build-all makefile for plancks
* reformatting of make output (colors)
* color toggle, tmk path corrections
* correct if statement for color
* move config.h to main makefile, updates preonic, atomic
* format update, all keyboards targets
* makefile optional for build all target, alps and arrow_pad updated
* alps updated
* make planck default, trying out travis recipe for all-keyboards
* all-keymaps target, different travis recipe
* updates alps64
* updates keyboards to new format
* updates clue* projects
* all projects updated, specialise EZ .hex, let .hex through
* updates travis
* automatically find root, keyboard, keymap
* silent echo, cleaned-up mass make output
* updates all keyboards' .hex files except EZ
* Rename Bantam44.c to bantam44.c
* Rename Bantam44.h to bantam44.h
* nananana
* adds six key keyboard
* does same to ez as rest
* updates send_string example
* brings ergodox_ez up to date
* updates template/new project script
* adds sixkeyboard
* adds readme for sixkeyboard
* adds sixkeyboard to travis
* filenames, gitignore mess
* define clock prescaler stuff manually
* make quick, size test example
* documentation and dfu-no-build
* clean trailing ws in Vagrantfile and util/avr_setup.sh
* replace triple quotes with heredoc.
Ruby doesn't have triple quotes; that's a Python thing. This was just being
parsed as multiple strings concatenated.
* add docker support to Vagrantfile
* make wants to find dfu-programmer in vagrant guest
* Created arrow pad, a QMK based numpad designed for heavy text editing
* Enabled backlighting, numlock indicator, and forced nkro for arrowpad
* WIP Arrowpad 21
* WIP Arrowpad 21
* Combined Arrow Pad 21 and 24
* Combined Arrow Pad 21 and 24
* Removed 21 folder
The documentation for ugfx gEventWait wait is wrong and the
function takes the time in milliseconds, instead of system ticks.
This caused the the thread to sleep way too long. It also caused
somewhat random sleeping behaviour as the MS2ST function overflows
at around 43 seconds sleep.
The event source is also now initialized correctly, so that the
thread actually can be woken up by events.
https://support.apple.com/en-us/HT201236 says that ⌃⌘⏏ will quit all apps and then restart your Mac; ⌃⌘-power will shut things down in an…ungraceful fashion.
I reboot into Windows fairly frequently; I'd rather have the nice behavior at my fingertips, not the rude one.
* Autodetect teensy-loader-cli over teensy_loader_cli.
Some distributions (e.g. Arch Linux, Guix) install teensy_loader_cli
as teensy-loader-cli. Use this one if it is installed.
* Update ergodox_ez/readme.md
- Mention Linux distris providing teensy-loader-cli
- Mention `make teensy ...`
Moved the layer toggles to be in more comfortable locations for my typing. Also expanded the use of the media layer (now called APP) and enhanced the text navigation on the control layer
* Don't save the ctags file in the repo.
* Initial support for the KC60 board. Only 5x5 working so far.
* Rename because this isn't the same KC60 as others.
* Add in some generic layout.
Pins seem to be in the right order except the 6th column spews
gibberish.
* Don't need this for now.
* Move this to some other folder.
* Trying again to start over.
* Don't need to start over because I figured out why the 'broken' stuff wasn't working.
* Attempt to enable backlighting. It's on on pin B7 like other boards.
* Fix last port changes and fix LED control in keymap.
* Trying some other LED code.
* Bootloader needs to be bigger. Disabling backlight for now.
* Simplify LED code while I try to figure it out.
* Turn back on backlighting.
* Backlighting works now. Just need to get levels or breathing working.
* Trying to allow for turning off the LEDs before I get to brightness levels.
* The missing link: need to run the init_ports function for LEDs to work properly.
* Removing breathing stuff since it bricks the board.
* Clean up default layer.
* Cleanup keymap, KC60 doesn't support a 5th right bottom-row button.
This is a squashed up version of the layout I have been working on for
the past month or so. Based on Dvorak, with a lot of unconventional
stuff thrown in for good measures.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
* Updated personal layouts
* tweaked personal
* Nightly - Audio Cleanup
Refactored the LUTs. Abstracted some of the registers out of audio to
use more functional names. Split audio into audio and audio_pwm. WIP
* nightly - collapsed code
* Added check for note playing to LEDs
* Usability tweaks
* TWEAE
* nightly
added extra kcs to keymap common
* turned on Plank audio
* Added backlight breathing to atomic
* reverted accidental merge
* Added music and audio toggles to Quantum.c
* Redid the audio callbacks
* Adjusted default planck layout to use the user tone naming
* tabs to spaces
* Rewrote the ALL recipe to allow for faster parallel make
* tabs to spaces
* Renamed custom event functions to be 'startup_user' and 'shutdown_user'. Also moved the prototypes around.
* Tweaked pvc atomic layout to work with the pvc planck.
* updates midi scale calling
* Unicode
to have unicode input you need to:
- set your OS input method to UNICODE if needed
- enable unicode in your makefile
- copy the action_function from
keyboard/planck/keymaps/unicode/unicode.c to your keymap.c
set the target OS method in your keymap.c: void matrix_init_user() {
set_unicode_mode(UC_OSX); } you can then switch when you want with:
set_unicode_mode(UC_OSX); set_unicode_mode(UC_LNX);
set_unicode_mode(UC_WIN);
put some unicode codes in your keymap like so: UC(0x0061)
I did change the bit mask in quantum/keymap_common.c and .h
I’m afraid we will need uint32 to get a total support for all unicode
tables or relocate the handler as @mbarkhau did.
* rearranges keycode values, hooks-up unicode
* removes extra lalt ref
* adds unicode shortcuts and example
* Updated personal layouts
* tweaked personal
* Nightly - Audio Cleanup
Refactored the LUTs. Abstracted some of the registers out of audio to
use more functional names. Split audio into audio and audio_pwm. WIP
* nightly - collapsed code
* Added check for note playing to LEDs
* Usability tweaks
* TWEAE
* nightly
added extra kcs to keymap common
* turned on Plank audio
* Added backlight breathing to atomic
* reverted accidental merge
* Added music and audio toggles to Quantum.c
* Redid the audio callbacks
* music/audio_on_user
* implements leader key for planck experimental
* allows override of leader timeout
* adds ability to use the leader key in seq
* fixes leader keycode
* adds chording prototype
* fixes keycode detection
* moves music mode to quantum.c
* disables chording by default
* adds music sequencer functionality
* implements audio/music functions in quantum.c
* splits up process_action to allow independent processing of actions
* moves midi stuff to quantum.c
* adds additional scales for midi
* implements leader key for planck experimental
* allows override of leader timeout
* adds ability to use the leader key in seq
* fixes leader keycode
* adds chording prototype
* fixes keycode detection
* moves music mode to quantum.c
* disables chording by default
* adds music sequencer functionality
* implements audio/music functions in quantum.c
* splits up process_action to allow independent processing of actions
* merging?
* [planck] toggle plover output in app when toggling plover layer on keyboard
* [planck] moved plover toggle to separate key
* [planck] renamed toggle button
After using the layout a while I learn that the - and = positions should be
swapped since I keep typing = when I intend to type -.
I also, removed the only macro from the top left on the right hand to put the
power button there and since I never use the arrow keys on the separated groups
of keys, I added 4 macros there to get a feel for it.
Some options I defined on the config.h file don't make much sense to other
keymaps so I revert the global config.h and add those options on the keymap
custom one.
Instead of having a key on the left side for one layer and a key on the right
side for the other layer, I put two dedicated layers on each side to get to the
proper layers.
This keymap was created to have a feel keys on a different place and to have as
fewer layers as possible.
Currently I have only 2 extra layers and only one of them is really required to
have all possible keys available.
Check out the README.md file for more information.
* Updated personal layouts
* tweaked personal
* Nightly - Audio Cleanup
Refactored the LUTs. Abstracted some of the registers out of audio to
use more functional names. Split audio into audio and audio_pwm. WIP
* nightly - collapsed code
* Added check for note playing to LEDs
* Usability tweaks
* TWEAE
* nightly
added extra kcs to keymap common
* turned on Plank audio
* Added backlight breathing to atomic
* reverted accidental merge
* adds backlight pulse to planck
This commit is mostly a cherry-pick from `ahtn` at
https://github.com/tmk/tmk_keyboard/pull/255.
These are the changes:
* Adds ACTION_LAYER_ONESHOT
* Adds ONESHOT_TAP_TOGGLE
* Mentions sticky keys in the docs on oneshot.
* Updated personal layouts
* tweaked personal
* Nightly - Audio Cleanup
Refactored the LUTs. Abstracted some of the registers out of audio to
use more functional names. Split audio into audio and audio_pwm. WIP
* nightly - collapsed code
* Added check for note playing to LEDs
Why:
* I want a custom keymap that suits my needs.
This change addresses the need by:
* Cloned default keymap.
* Customized layout.
* Updated README.
* Add an image created from keyboard layout editor.
- layer modifiers in the thumb clusters, Alt-F1 - Alt-F4 should now be easier to type
- new Alt and Ctrl keys in the bottom row are more easily reachable with thumbs than the little thumb cluster keys, and feel more like traditional keyboards
- thumb backspace wasn't great due to lower precision and repeat rate than index fingers
Running this as a non-administrator appears to work at first, but the
changes wouldn't stick on my Win 8.1 system. It's weird, but this
script needs to run as admin.
- on mod keys, register LGUI, LSFT etc. as normal mods
instead of weak mods:
- they won't be cleared by layer switching
- LSFT(KC_LGUI) will now have the same behavior as LGUI(KC_LSFT)
on mod keys, register LGUI, LSFT etc. as normal mods
instead of weak mods:
- they won't be cleared when pressing another key (#188)
- they won't be cleared by layer switching
- LSFT(KC_LGUI) will now have the same behavior as LGUI(KC_LSFT)
The Raise and Lower keys were transposed in the comment key map for all layers. Assuming _RS and _LW should be mapped to Raise and Lower respectively. Probably is the same in the other custom keymaps that copied from this default.
Having "true" modifiers is more reliable and practical.
- moved APP in place of HOME
- moved HOME in place of LSFT on left thumb
- moved END in place of RSFT on right thumb (Ctrl+End with single hand!)
- removed ALT_T from KC_ESC
- all characters available directly in CSA
- more explicit names for macros that switch accross CSA layers
- use macros to implement the shifts next to the spaces
- implement easy way to define and send unicode characters on Windows
- define 3 characters not available in CSA:
- en dash: –
- em dash: —
- ellipsis: …
- implemented the most useful characters:
- all French characters + €
- common programmer characters
- other keys implemented as KC_NO to avoid mistyping a character
from a lower layer
- AltGr+Shift not supported (yet)
Initial implementation of the BÉPO layout
for use with the Canadian Multilingual Standard layout
(a.k.a. CSA / ACNOR layout) on the OS-side.
- support all bépo characters from the default and shifted layers
No more SFT_T:
- moved ] (bépo W) below Tab
- moved - (bépo =) in place of ] (top right)
- removed SFT_T from ' (bépo M)
- moved \ (bépo Ç) in place of = (bépo %)
- moved = (bépo %) in place of - (bépo =)
Added check for the MinGW directory. Fixed a bug with script exiting out
of a CMD window. Fixed a bug with script dropping user into MinGW
directory. Fixed a bug with RD not deleting temp. Fixed a bug with
PNPUtil.exe not being present in the path.
[This comment](https://www.reddit.com/r/olkb/comments/428umx/rgb_underglow/czaivbc) states that because both audio output and RGB support require the user of timer 3, they can't be enabled at the same time. That makes sense, I can see where audio.c uses timer 3. But this comment in the code states that the incompatibility is with MIDI support, which doesn't make sense based on what I see in the code. Please enlighten me if I'm mistaken.
Fixed compiler warning by including bootloader.h in keymap_common.c.
Changed FORCE_NKRO to only be applied if NKRO_ENABLE is defined.
Added extra documentation to the template config.h
Retro_Refit is an example of using a Teensy to replace a keyboard
controller on an older keyboard. The original 6x15 keyboard had a
non-standard 11x8 matrix.
If one wants to temporarily disable the key cache (for example because
it interferes with a macro), `disable_action_cache` must be set to
`true`. `process_action_nocache` is a simple wrapper doing just that for
a single call.
- new macro_mods bit field for mods applied by macros
- weak_mods now only used for ACT_{L,R}MODS (i.e. LSFT, RSFT, LCTL etc.)
- clear the _weak_ mods on every key *pressed* such that LSFT etc.
can no more interfere with the next key
There were previously no Dvorak specific underscore and plus key codes. For a keyboard like the Planck which has layers directly to shifted versions of special character keys you were unable to produce those characters using the Lower layer.
The M(1) function changes layer temporarily (so that numbers can be used)
and holds LGUI which makes it possible to easily change virtual screens
and swap windows inbetween them.
On most Linux distributions the avr_setup.sh script can be sourced ```. avr_setup.sh``` or under Bash ```source avr_setup.sh```. This will try and detect the appropriate package manager and install the required packages.
By testing I found out that, at least on Linux using the Swedish layout,
two macros present on this file were wrong, for the backslash and pipe
keys. Jack helped me find the correct combination for the backslash and
that led me to the right one for pipe.
Commenting out the line is the only way to disable the console, as the
value of CONSOLE_ENABLE isn't checked. There are only checks for its
existence; setting it to `yes` or `no` doesn't change the compilation.
There's so many control keys in this keymap, one needed to go. So, I changed
the lower-left control key to be a momentary L1, just like the same key on the
right side.
This keymap attempts to match the Kinesis Contoured (aka Advantage) default
layout as closely as possible. See
http://www.kinesis-ergo.com/wp-content/uploads/2013/06/advantage_layout_win.pdf
Apart from the obvious mappings, this keymap also:
* removes the dual-purpose momentary layer/normal keys: Z, /, and Grv;
because the author--coming from a Kinesis keyboard--finds the delays and
accidental modifiers to be more disconcerting than helpful.
* puts Esc in the bottom left since there's no place for it in the top
left to match the Kinesis.
* changes the bottom-right key into an L2 toggle since there's otherwise no
way to get to L2.
* adds PrScr, ScrLk and Pause to the L1 keymap, down the left side, since
they're present on the Kinesis but not available in the default
ergodox_ez keymap.
- removed access to layer 2 from ";" key
- "fn" key toggles both layers 1 & 2
- replaced media and mouse layer by fn layer
- renamed symbol layer to numbers layer
- moved all F-keys together on left hand
- home replaced by KC_TRNS to make backspace available
- prev/next moved left to space to restore ralt
- arrows moved down to have reversed T-shape
- added ctl on bottom right KpEnter, to match layer 0
- removed alt from mute, as it was already no more in layer 0
- keep home/end at the same location
- RAlt as first key on the bottom right row
- left/right arrows moved on the thumb, near the other arrows
- added Alt on App
- added Alt on Mute in Layer 1
- removed ALT from left spaces to avoid issues when pressing too slowly
This moves the keys closer to a traditional layout with some redundancy
around the middle to compensate for fast non-traditional typists like
myself who tend to wander from the home row a fair bit. Navigation keys
are provided in layer 2 (accessed by left thumb button), programming
symbols and classic numeric keypad in layer 1 (accessed by right thumb
button). Permanent layer switching is provided with a smaller thumb
button. Ctrl provided in place of caps lock (because no-one needs
caps/num lock), space, backspace, enter, shift all in traditional
positions with layer 1 providing things like equals, tilde and
apostrophe (an attempt to re-use existing muscle memory).
LEDs are pimped to the point of being silly (fading in/out on layer
switch, rolling on reboot ... because I can). Power and reset keys
provided on left thumb pad in layer 2.
No meh or hyper as I haven't found a burning need for them yet.
The goal of this keymap is to simulate the Atreus layout. Since I've
been using it for quite a while I figured this might help me transition
to Planck.
Adding the makefile options ADB_MOUSE_ENABLE and ADB_MOUSE_ACCMAX.
Might have gone overboard with comments, and tried but failed at not
adding more than necessary outside the converter/adb_usb/ folder.
- Backlight on PB7 controlled by Timer1 Fast PWM (no interrupts).
- Backlight commands connected temporarily to top left keys.
- Backlight init called from matrix.c, since there's no generic keyboard_init() override function.
* can be enabled by defining Makefile macro SERIAL_MOUSE_MICROSOFT_ENABLE or
SERIAL_MOUSE_MOUSESYSTEMS_ENABLE.
* Serial implementation can be chosen via SERIAL_MOUSE_USE_SOFT and
SERIAL_MOUSE_USE_UART macros
* UART configuration still has to be done in config.h: I added working clauses
for both mouse protocols to ps2_usb's config.h
* Both drivers use the interface defined in serial_mouse.h
* They should work with any UART implementation (hardware/software UART)
* The Microsoft driver is currently untested.
The Mousesystems driver is confirmed to work.
This takes the last, reserved bit there, but doesn't necessitate
a revision to the magic number because it doesn't alter byte order.
Add reference to NKRO virtual dip-switch to documentation.
0. Connect ADB keyboard to Teensy by 3 lines(Vcc, GND, Data). By default Data line uses port D0.
This converter uses AVR's internal pull-up, but it seems to be too weak, in particular when you want to use a long or coiled cable.
The external pull-up resistor(1K-10K Ohm) on Data is strongly recommended.
1. Define following macros for ADB connection in config.h if you use other than port D0.
ADB_PORT, ADB_PIN, ADB_DDR, ADB_DATA_BIT
2. make
3. program Teensy
LOCKING CAPSLOCK
----------------
Many of old ADB keyboards have mechanical push-lock switch for Capslock key and this converter supports the locking Capslock key by default. See README in top directory for more detail about this feature.
Also you may want to remove locking pin from the push-lock switch to use capslock as a normal momentary switch.
http://www.youtube.com/watch?v=9wqnt2mGJ2Y
Keymap
------
You can change a keymap by editing code of keymap.c like following.
This is a keymap for AEK, however, also used for other keyboards.
How to define the keymap is probably obvious. You can find key symbols in keycode.h.
If you want to define some keymaps than just one, see hhkb/keymap.c and
macway/keymap.c as examples. Keymap(layer) switching may needs a bit of
This firmware converts the protocol of Apple Macintosh keyboard **M0110**, **M0110A** and **M0120** into USB. Target of this project is USB AVR controller **ATmega32U4**. Using this converter you can revive these retro keyboards with modern computer.
Pics of **M0110 + M0120** and **M0110A**.
- M0110A support was contributed by [skagon@github](https://github.com/skagon).
- M0120 also is supported. keys(+ * / and ,) on M0120 are recognized as cursor keys.
Update
------
- 2013/08: Change port for signals `PF` to `PD`
- 2013/09: Change port again, it uses inversely `PD0` for data and `PD1` for clock line now.
Building Hardware
-----------------
You need **4P4C** cable and **ATMega32U4** board like PJRC [Teensy]. Port of the MCU `PD1` is assigned to `CLOCK` line and `PD0` to `DATA` by default, you can change pin configuration with editing `config.h`.
You may need pull-up registors on signal lines(`CLOCK`, `DATA`) in particular when you have long or coiled cable. **1k-10k Ohm** will be OK for this purpose. In that case the converter may not read signal from keyboard correctly without pull-up resistors.
Building Frimware
-----------------
To compile firmware you need AVR GCC. You can edit *Makefile* and *config.h* to change compile options and pin configuration.
You can use [PJRC HID listen](http://www.pjrc.com/teensy/hid_listen.html) to see debug output. The converter has some functions for debug, press `<Command>+H` simultaneously to get help.
- Command: `Shift+Option+Command`(`Shift+Alt+Gui` or `Shift+Alt+Control`)
# This guide has now been included in the main readme - please reference that one instead.
## Build Environment Setup
### Windows (Vista and later)
1. If you have ever installed WinAVR, uninstall it.
2. Install [MHV AVR Tools](https://infernoembedded.com/sites/default/files/project/MHV_AVR_Tools_20131101.exe). Disable smatch, but **be sure to leave the option to add the tools to the PATH checked**.
3. Install [MinGW](https://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download). During installation, uncheck the option to install a graphical user interface. **DO NOT change the default installation folder.** The scripts depend on the default location.
4. Clone this repository. [This link will download it as a zip file, which you'll need to extract.](https://github.com/qmk/qmk_firmware/archive/master.zip) Open the extracted folder in Windows Explorer.
5. Double-click on the 1-setup-path-win batch script to run it. You'll need to accept a User Account Control prompt. Press the spacebar to dismiss the success message in the command prompt that pops up.
6. Right-click on the 2-setup-environment-win batch script, select "Run as administrator", and accept the User Account Control prompt. This part may take a couple of minutes, and you'll need to approve a driver installation, but once it finishes, your environment is complete!
7. Future build commands should be run from the standard Windows command prompt, which you can find by searching for "command prompt" from the start menu or start screen. Ignore the "MHV AVR Shell".
### Mac
If you're using [homebrew,](http://brew.sh/) you can use the following commands:
brew tap osx-cross/avr
brew install avr-libc
brew install dfu-programmer
This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line.
You can also try these instructions:
1. Install Xcode from the App Store.
2. Install the Command Line Tools from `Xcode->Preferences->Downloads`.
3. Install [DFU-Programmer][dfu-prog].
### Linux
Install AVR GCC, AVR libc, and dfu-progammer with your favorite package manager.
If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the [VAGRANT_GUIDE file](VAGRANT_GUIDE.md).
## Verify Your Installation
1. If you haven't already, obtain this repository ([https://github.com/qmk/qmk_firmware](https://github.com/qmk/qmk_firmware)). You can either download it as a zip file and extract it, or clone it using the command line tool git or the Github Desktop application.
2. Open up a terminal or command prompt and navigate to the `qmk_firmware` folder using the `cd` command. The command prompt will typically open to your home directory. If, for example, you cloned the repository to your Documents folder, then you would type `cd Documents/qmk_firmware`. If you extracted the file from a zip, then it may be named `qmk_firmware-master` instead.
3. To confirm that you're in the correct location, you can display the contents of your current folder using the `dir` command on Windows, or the `ls` command on Linux or Mac. You should see several files, including `readme.md` and a `quantum` folder. From here, you need to navigate to the appropriate folder under `keyboards/`. For example, if you're building for a Planck, run `cd keyboards/planck`.
4. Once you're in the correct keyboard-specific folder, run the `make` command. This should output a lot of information about the build process. More information about the `make` command can be found below.
## Customizing, Building, and Deploying Your Firmware
### The Make command
The `make` command is how you compile the firmware into a .hex file, which can be loaded by a dfu programmer (like dfu-progammer via `make dfu`) or the [Teensy loader](https://www.pjrc.com/teensy/loader.html) (only used with Teensys). You can run `make` from the root (`/`), your keyboard folder (`/keyboards/<keyboard>/`), or your keymap folder (`/keyboards/<keyboard>/keymaps/<keymap>/`) if you have a `Makefile` there (see the example [here](/doc/keymap_makefile_example.mk)).
By default, this will generate a `<keyboard>_<keymap>.hex` file in whichever folder you run `make` from. These files are ignored by git, so don't worry about deleting them when committing/creating pull requests.
* The "root" (`/`) folder is the qmk_firmware folder, in which are `doc`, `keyboard`, `quantum`, etc.
* The "keyboard" folder is any keyboard project's folder, like `/keyboards/planck`.
* The "keymap" folder is any keymap's folder, like `/keyboards/planck/keymaps/default`.
Below is a list of the useful `make` commands in QMK:
*`make` - cleans automatically and builds your keyboard and keymap depending on which folder you're in. This defaults to the "default" layout (unless in a keymap folder), and Planck keyboard in the root folder
*`make keyboard=<keyboard>` - specifies the keyboard (only to be used in root)
*`make keymap=<keymap>` - specifies the keymap (only to be used in root and keyboard folder - not needed when in keymap folder)
*`make quick` - skips the clean step (cannot be used immediately after modifying config.h or Makefiles)
*`make dfu` - (requires dfu-programmer) builds and flashes the keymap to your keyboard once placed in reset/dfu mode (button or press `KC_RESET`). This does not work for Teensy-based keyboards like the ErgoDox EZ.
*`keyboard=` and `keymap=` are compatible with this
*`make all-keyboards` - builds all keymaps for all keyboards and outputs status of each (use in root)
*`make all-keyboards-default` - builds all default keymaps for all keyboards and outputs status of each (use in root)
*`make all-keymaps [keyboard=<keyboard>]` - builds all of the keymaps for whatever keyboard folder you're in, or specified by `<keyboard>`
*`make all-keyboards-quick`, `make all-keyboards-default-quick` and `make all-keymaps-quick [keyboard=<keyboard>]` - like the normal "make-all-*" commands, but they skip the clean steps
Other, less useful functionality:
*`make COLOR=false` - turns off color output
*`make SILENT=true` - turns off output besides errors/warnings
*`make VERBOSE=true` - outputs all of the avr-gcc stuff (not interesting)
### The Makefile
There are 3 different `make` and `Makefile` locations:
The root contains the code used to automatically figure out which keymap or keymaps to compile based on your current directory and commandline arguments. It's considered stable, and shouldn't be modified. The keyboard one will contain the MCU set-up and default settings for your keyboard, and shouldn't be modified unless you are the producer of that keyboard. The keymap Makefile can be modified by users, and is optional. It is included automatically if it exists. You can see an example [here](/doc/keymap_makefile_example.mk) - the last few lines are the most important. The settings you set here will override any defaults set in the keyboard Makefile. **It is required if you want to run `make` in the keymap folder.**
The keyboard `config.h` is included only if the keymap one doesn't exist. The format to use for your custom one [is here](/doc/keymap_config_h_example.h). If you want to override a setting from the parent `config.h` file, you need to do this:
```
#undef MY_SETTING
#define MY_SETTING 4
```c
For a value of `4` for this imaginary setting. So we `undef` it first, then `define` it.
You can then override any settings, rather than having to copy and paste the whole thing.
#Planck Advanced (but not too advanced) `cygwin` Users Guide
If you are a user of the [cygwin environment](https://cygwin.com) in Windows and want the freedom to use the latest tools available, then this is the guide for you. If compiling your own copy of the latest and greatest Gnu C Compiler makes you super happy, then this is the guide for you. If the command line make you smile, then this is the guide for you.
This guide was written step by step as I went through the process on a `Windows 10``x86_64` and a `Windows 7``amd k10` based system. This should be generally applicable to to any `Windows` environment with `cygwin`.
#####Do not skip steps. Do not move past a step until the previous step finishes successfully.
Based on [avr-libc installation guide](http://www.nongnu.org/avr-libc/user-manual/install_tools.html)
##Get the Required Packages
Download the `cygwin` setup ([x86_64](https://cygwin.com/setup-x86_64.exe)) and install the default system plus the following if they are not already selected:
The set of commands below will create a directory (`~/local/avr`) for the sources you compile to be installed on the machine and a directory (`~/src`) for these source files to be stored. The commands then download the sources of the needed packages and unpack them. Note: the expand commands are different depending on if the packages are offered as a `bz2` or `gz` archive
These commands will set up the install directory and the `PATH` variable, which will allow you to access your installed packages. Note: if you close the `cygwin` terminal window, you will need to rerun these commands, they are not permanent.
The following packages are required to be complied and installed in order to compile `gcc`. They are not sufficiently available through the `cygwin` package system, so we have to make them ourselves. They must be complied in this order because each one depends on the previous. Verfiy that for each package, `make check` returns all passing and no fails.
You can build and install a brand new `gcc` or you can use the one supplied by `cygwin`. This will take about 4-5 hours to compile (It is a "native build", so it does the entire build **3 times**. This takes a long while).
##Buliding `binutils`, `gcc`, and `avr-libc` for the AVR system
Now we can make the critical stuff for compiling our firmware: `binutils`, `gcc`, and `avr-libc` for the AVR architecture. These allow us to build and manipulate the firmware for the keyboard.
###Build `binutils` for AVR
If you plan to build and install `avr-gdb` also, use the `gdb` install at the end of this guide as it also builds the `binutils`
For building the `avr-libc`, we have to specify the host build system. In my case it is `x86_64-unknown-cygwin`. You can look for build system type in the `gcc` configure notes for the proper `--build` specification to pass when you configure `avr-libc`.
##Building 'dfu-programmer' for flashing the firmware via USB and installing the drivers
We can either build our own, or use the precomplied binaries. The precompiled binaries don't play well with `cygwin` so it is better to build them ourselves. The procedure for the precompiled binaries is included at the end of this guide.
### Build and Install the `libusb`
The `dfu-programmer` requires `libusb` so that it can interact with the USB system. These repos must be bootstrapped in order to create an appropriate `./configure` and `Makefile` for your system.
Type 'dfu-programmer --help' for a list of commands
'dfu-programmer --targets' to list supported target devices
```
If you are not getting the above result, you will not be able to flash the firmware!
###Install the USB drivers
The drivers are included in the windows binary version of [`dfu-programmer` 0.7.2](http://iweb.dl.sourceforge.net/project/dfu-programmer/dfu-programmer/0.7.2/dfu-programmer-win-0.7.2.zip).
The official drivers are found in [Atmel's `FLIP` installer](http://www.atmel.com/images/Flip%20Installer%20-%203.4.7.112.exe). Download and then install `FLIP`. Upon installation, the drivers will be found in `C:\Program Files (x86)\Atmel\Flip 3.4.7\usb`.
Then, from an **administrator-privileged**`Windows` terminal, run the following command (adjust the path for username, etc. as necessary) and accept the prompt that pops up:
```
C:\> pnputil -i -a C:\cygwin64\home\Kevin\src\dfu-programmer-win-0.7.2\dfu-prog-usb-1.2.2\atmel_usb_dfu.inf
or
C:\> pnputil -i -a "C:\Program Files (x86)\Atmel\Flip 3.4.7\usb\atmel_usb_dfu.inf"
```
This should be the result:
```
Microsoft PnP Utility
Processing inf : atmel_usb_dfu.inf
Successfully installed the driver on a device on the system.
Driver package added successfully.
Published name : oem104.inf
Total attempted: 1
Number successfully imported: 1
```
Alternatively, the `Windows` driver can be installed when prompted by `Windows` when the keyboard is attached. Do not let `Windows` search for a driver; specify the path to search for a driver and point it to the `atmel_usb_dfu.inf` file.
##Building and Flashing the Planck firmware!
If you did everything else right. This part should be a snap! Grab the latest sources from `github`, make the Plank firmware, then flash it.
If you do not get the above, you **did not** build the firmware, and you will have nothing to flash. If you have the fresh clone from `github`, it was probably something gone wrong in this install process, go check and see what didn't work and threw errors or what steps you might have missed.
But if everything went OK, you are ready to flash! Press the reset button on the bottom of the Planck, wait two seconds, then:
```
$ make dfu
```
.
.
.
profit!!!
##extra bits...
###Installing Precompiled `dfu-programmer` Binaries (not recommended for `cygwin`)
To install the `dfu-programmer` from the binaries, we must get if from [the `dfu-programmer` website](https://dfu-programmer.github.io/) ([0.7.2](http://iweb.dl.sourceforge.net/project/dfu-programmer/dfu-programmer/0.7.2/dfu-programmer-win-0.7.2.zip)).
Copy this file into your `cygwin` home\src directory. (For me, it is `C:\cygwin64\home\Kevin\src`), extract the files, move `dfu-programmer.exe` to `~/local/avr/bin`. Most obnoxiously, the `libusb0_x86.dll` and `libusb0.sys` need to be moved from `./dfu-prog-usb-1.2.2/x86/` to a directory in the `Windows``PATH` and the `cygwin``PATH`. This is because the `dfu-programmer` binary is `mingw` based, not `cygwin` based, so the `dlls` do not cooperate. I achieved acceptable pathing by moving the files to `C:\cygwin64\home\Kevin\local\avr\bin` Then, in a `WINDOWS` command prompt running (Adjusting your path for username, etc. as needed):
```
C:\> set PATH=%PATH%;C:\cygwin64\home\Kevin\local\avr\bin
```
Then, rename `libusb0_x86.dll` to `libusb0.dll`.
You can tell that you were successful by trying to execute 'dfu-programmer' from the 'cygwin' prompt:
```
$ which dfu-programmer
/home/Kevin/local/avr/bin/dfu-programmer
$ dfu-programmer
dfu-programmer 0.7.2
https://github.com/dfu-programmer/dfu-programmer
Type 'dfu-programmer --help' for a list of commands
'dfu-programmer --targets' to list supported target devices
```
If you are not getting the above result, you will not be able to flash the firmware!
- Try making sure your `PATH` variables are set correctly for both `Windows` and `cygwin`.
- Make sure the `dll` is named correctly.
- Do not extract it with `cygwin`'s `unzip` as it does not set the executable permission. If you did it anyway, do `chmod +x dfu-programmer.exe`.
- Still have problems? Try building it instead.
##Debugging Tools
These tools are for debugging your firmware, etc. before flashing. Theoretically, it can save your memory from wearing out. However, these tool do not work 100% for the Planck firmware.
### `gdb` for AVR
`gdb` has a simulator for AVR but it does not support all instructions (like WDT), so it immediately crashes when running the Planck firmware (because `lufa.c` disables the WDT in the first few lines of execution). But it can still be useful in debugging example code and test cases, if you know how to use it.
`simulavr` is an AVR simulator. It runs the complied AVR elfs. `simulavr` does not support the `atmega32u4` device... it does `atmega32` but that is not good enough for the firmware (no PORTE and other things), so you cannot run the Planck firmware. I use it to simulate ideas I have for features in separate test projects.
This one is a major pain in the butt because it has a lot of dependencies and it is buggy. I will do my best to explain it but... it was hard to figure out. A few things need to be changed in the 'Makefile' to make it work in `cygwin`.
Edit `src/Makefile.am` now so that `-no-undefined` is included (I did this by removing the SYS_MINGW conditional surrounding `libsim_la_LDFLAGS += -no-undefined` and `libsimulavr_la_LDFLAGS += -no-undefined \ libsimulavr_la_LIBADD += $(TCL_LIB)`. Also, `$(EXEEXT)` is added after `kbdgentables` in two places.
* Wire (strained for wiring to the Teensy, anything for the rows/columns)
* Soldering iron set at 600ºF or 315ºC (if temperature-controlled)
* Resin-cored solder (leaded or lead-free)
* Adequate ventilation/a fan
* Tweezers (optional)
* Wire cutters/snippers
## How the matrix works (why we need diodes)
The microcontroller (in this case, the Teensy 2.0) will be setup up via the firmware to send a logical 1 to the columns, one at a time, and read from the rows, all at once - this process is called matrix scanning. The matrix is a bunch of open switches that, by default, don't allow any current to pass through - the firmware will read this as no keys being pressed. As soon as you press one key down, the logical 1 that was coming from the column the keyswitch is attached to gets passed through the switch and to the corresponding row - check out the following 2x2 example:
Column 0 being scanned Column 1 being scanned
x x
col0 col1 col0 col1
| | | |
row0 ---(key0)---(key1) row0 ---(key0)---(key1)
| | | |
row1 ---(key2)---(key3) row1 ---(key2)---(key3)
The `x` represents that the column/row associated has a value of 1, or is HIGH. Here, we see that no keys are being pressed, so no rows get an `x`. For one keyswitch, keep in mind that one side of the contacts is connected to its row, and the other, its column.
When we press `key0`, `col0` gets connected to `row0`, so the values that the firmware receives for that row is `0b01` (the `0b` here means that this is a bit value, meaning all of the following digits are bits - 0 or 1 - and represent the keys in that column). We'll use this notation to show when a keyswitch has been pressed, to show that the column and row are being connected:
Column 0 being scanned Column 1 being scanned
x x
col0 col1 col0 col1
| | | |
x row0 ---(-+-0)---(key1) row0 ---(-+-0)---(key1)
| | | |
row1 ---(key2)---(key3) row1 ---(key2)---(key3)
We can now see that `row0` has an `x`, so has the value of 1. As a whole, the data the firmware receives when `key0` is pressed is
col0: 0b01
col1: 0b00
│└row0
└row1
A problem arises when you start pressing more than one key at a time. Looking at our matrix again, it should become pretty obvious:
Column 0 being scanned Column 1 being scanned
x x
col0 col1 col0 col1
| | | |
x row0 ---(-+-0)---(-+-1) x row0 ---(-+-0)---(-+-1)
| | | |
x row1 ---(key2)---(-+-3) x row1 ---(key2)---(-+-3)
Remember that this ^ is still connected to row1
The data we get from that is:
col0: 0b11
col1: 0b11
│└row0
└row1
Which isn't accurate, since we only have 3 keys pressed down, not all 4. This behavior is called ghosting, and only happens in odd scenarios like this, but can be much more common on a bigger keyboard. The way we can get around this is by placing a diode after the keyswitch, but before it connects to its row. A diode only allows current to pass through one way, which will protect our other columns/rows from being activated in the previous example. We'll represent a dioded matrix like this;
Column 0 being scanned Column 1 being scanned
x x
col0 col1 col0 col1
│ │ | │
(key0) (key1) (key0) (key1)
! │ ! │ ! | ! │
row0 ─────┴────────┘ │ row0 ─────┴────────┘ │
│ │ | │
(key2) (key3) (key2) (key3)
! ! ! !
row1 ─────┴────────┘ row1 ─────┴────────┘
In practical applications, the black line of the diode will be placed facing the row, and away from the keyswitch - the `!` in this case is the diode, where the gap represents the black line. A good way to remember this is to think of this symbol: `>|`
Now when we press the three keys, invoking what would be a ghosting scenario:
Column 0 being scanned Column 1 being scanned
x x
col0 col1 col0 col1
│ │ │ │
(┌─┤0) (┌─┤1) (┌─┤0) (┌─┤1)
! │ ! │ ! │ ! │
x row0 ─────┴────────┘ │ x row0 ─────┴────────┘ │
│ │ │ │
(key2) (┌─┘3) (key2) (┌─┘3)
! ! ! !
row1 ─────┴────────┘ x row1 ─────┴────────┘
Things act as they should! Which will get us the following data:
col0: 0b01
col1: 0b11
│└row0
└row1
The firmware can then use this correct data to detect what it should do, and eventually, what signals it needs to send to the OS.
## The actual hand-wiring
### Getting things in place
When starting this, you should have all of your stabilisers and keyswitches already installed (and optionally keycaps). If you're using a Cherry-type stabiliser (plate-mounted only, obviously), you'll need to install that before your keyswitches. If you're using Costar ones, you can installed them afterwards.
To make things easier on yourself, make sure all of the keyswitches are oriented the same way (if they can be - not all layouts support this). Despite this, it's important to remember that the contacts on the keyswitches are completely symmetrical. We'll be using the keyswitch's left side contact for wiring the rows, and the right side one for wiring the columns.
Get your soldering iron heated-up and collect the rest of the materials from the part list at the beginning of the guide. Place your keyboard so that the bottoms of the keyswitches are accessible - it may be a good idea to place it on a cloth to protect your keyswitches/keycaps.
Before continuing, plan out where you're going to place your Teensy. If you're working with a board that has a large (6.25u) spacebar, it may be a good idea to place it in-between switches against the plate. Otherwise, you may want to trim some of the leads on the keyswitches where you plan on putting it - this will make it a little harder to solder the wire/diodes, but give you more room to place the Teensy.
### Preparing the diodes
It's a little easier to solder the diodes in place if you bend them at a 90º angle immediately after the black line - this will help to make sure you put them on the right way (direction matters), and in the correct position. The diodes will look like this when bent (with longer leads):
┌─────┬─┐
───┤ │ ├─┐
└─────┴─┘ │
│
We'll be using the long lead at the bent end to connect it to the elbow (bent part) of the next diode, creating the row.
### Soldering the diodes
Starting at the top-left switch, place the diode (with tweezers if you have them) on the switch so that the diode itself is vertically aligned, and the black line is facing toward you. The straight end of the diode should be touching the left contact on the switch, and the bent end should be facing to the right and resting on the switch there, like this:
│o
┌┴┐ o
│ │ O
├─┤
└┬┘
└─────────────
Letting the diode rest, grab your solder, and touch both it and the soldering iron to the left contact at the same time - the rosin in the solder should make it easy for the solder to flow over both the diode and the keyswitch contact. The diode may move a little, and if it does, carefully position it back it place by grabbing the bent end of the diode - the other end will become hot very quickly. If you find that it's moving too much, using needle-nose pliers of some sort may help to keep the diode still when soldering.
The smoke that the rosin releases is harmful, so be careful not to breath it or get it in your eyes/face.
After soldering things in place, it may be helpful to blow on the joint to push the smoke away from your face, and cool the solder quicker. You should see the solder develop a matte (not shiney) surface as it solidifies. Keep in mind that it will still be very hot afterwards, and will take a couple minutes to be cool to touch. Blow on it will accelerate this process.
When the first diode is complete, the next one will need to be soldered to both the keyswitch, and the previous diode at the new elbow. That will look something like this:
│o │o
┌┴┐ o ┌┴┐ o
│ │ O │ │ O
├─┤ ├─┤
└┬┘ └┬┘
└────────────────┴─────────────
After completing a row, use the wire cutters to trim the excess wire from the tops of the diodes, and from the right side on the final switch. This process will need to completed for each row you have.
When all of the diodes are completely soldered, it's a good idea to quickly inspect each one to ensure that your solder joints are solid and sturdy - repairing things after this is possible, but more difficult.
### Soldering the columns
You'll have some options in the next process - it's a good idea to insulate the column wires (since the diodes aren't), but if you're careful enough, you can use exposed wires for the columns - it's not recommended, though. If you're using single-cored wire, stripping the plastic off of the whole wire and feeding it back on is probably the best option, but can be difficult depending on the size and materials. You'll want to leave parts of the wire exposed where you're going to be solder it onto the keyswitch.
If you're using stranded wire, it's probably easiest to just use a lot of small wires to connect each keyswitch along the column. It's possible to use one and melt through the insulation, but this isn't recommended, will produce even more harmful fumes, and can ruin your soldering iron.
Before beginning to solder, it helps to have your wire pre-bent (if using single-cored), or at least have an idea of how you're going to route the column (especially if you're making a staggered board). Where you go in particular doesn't matter too much, as we'll be basing our keymap definitions on how it was wired - just make sure every key in a particular row is in a unique column, and that they're in order from left to right.
If you're not using any insulation, you can try to keep the column wires elevated, and solder them near the tips of the keyswitch contacts - if the wires are sturdy enough, they won't short out to the row wiring an diodes.
### Wiring things to the Teensy
Now that the matrix itself is complete, it's time to connect what you've done to the Teensy. You'll be needing the number of pins equal to your number of columns + your number of rows. There are some pins on the Teensy that are special, like D6 (the LED on the chip), or some of the UART, SPI, I2C, or PWM channels, but only avoid those if you're planning something in addition to a keyboard. If you're unsure about wanting to add something later, you should have enough pins in total to avoid a couple.
The pins you'll absolutely have to avoid are: GND, VCC, AREF, and RST - all the others are usable and accessible in the firmware.
Place the Teensy where you plan to put it - you'll have to cut wires to length in the next step, and you'll want to make sure they reach.
Starting with the first column on the right side, measure out how much wire you'll need to connect it to the first pin on the Teensy - it helps to pick a side that you'll be able to work down, to keep the wires from overlapping too much. It may help to leave a little bit of slack so things aren't too tight. Cut the piece of wire, and solder it to the Teensy, and then the column - you can solder it anywhere along the column, but it may be easiest at the keyswitch. Just be sure the wire doesn't separate from the keyswitch when soldering.
As you move from column to column, it'll be helpful to write the locations of the pins down. We'll use this data to setup the matrix in the future.
When you're done with the columns, start with the rows in the same process, from top to bottom, and write them all down. Again, you can solder anywhere along the row, as long as it's after the diode - soldering before the diode (on the keyswitch side) will cause that row not to work.
As you move along, be sure that the Teensy is staying in place - recutting and soldering the wires is a pain!
### Getting some basic firmware set-up
From here, you should have a working keyboard with the correct firmware. Before we attach the Teensy permanently to the keyboard, let's quickly get some firmware loaded onto the Teensy so we can test each keyswitch.
To start out, download [the firmware](https://github.com/qmk/qmk_firmware/) - we'll be using my (Jack's) fork of TMK called QMK/Quantum. We'll be doing a lot from the Terminal/command prompt, so get that open, along with a decent text editor like [Sublime Text](http://www.sublimetext.com/).
The first thing we're going to do is create a new project using the script in the root directory of the firmware. In your terminal, run this command with `<project_name>` replaced by the name of your project - it'll need to be different from any other project in the `keyboards/` folder:
util/new_project.sh <project_name>
You'll want to navigate to the `keyboards/<project_name>/` folder by typing, like the print-out from the script specifies:
cd keyboards/<project_name>
#### config.h
The first thing you're going to want to modify is the `config.h` file. Find `MATRIX_ROWS` and `MATRIX_COLS` and change their definitions to match the dimensions of your keyboard's matrix.
Farther down are `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`. Change their definitions to match how you wired up your matrix (looking from the top of the keyboard, the rows run top-to-bottom and the columns run left-to-right). Likewise, change the definition of `UNUSED_PINS` to match the pins you did not use (this will save power).
#### \<project_name\>.h
The next file you'll want to look at is `<project_name>.h`. You're going to want to rewrite the `KEYMAP` definition - the format and syntax here is extremely important, so pay attention to how things are setup. The first half of the definition are considered the arguments - this is the format that you'll be following in your keymap later on, so you'll want to have as many k*xy* variables here as you do keys. The second half is the part that the firmware actually looks at, and will contain gaps depending on how you wired your matrix.
We'll dive into how this will work with the following example. Say we have a keyboard like this:
┌───┬───┬───┐
│ │ │ │
├───┴─┬─┴───┤
│ │ │
└─────┴─────┘
This can be described by saying the top row is 3 1u keys, and the bottom row is 2 1.5u keys. The difference between the two rows is important, because the bottom row has an unused column spot (3 v 2). Let's say that this is how we wired the columns:
┌───┬───┬───┐
│ ┋ │ ┋ │ ┋ │
├─┋─┴─┬─┴─┋─┤
│ ┋ │ ┋ │
└─────┴─────┘
The middle column is unused on the bottom row in this example. Our `KEYMAP` definition would look like this:
#define KEYMAP( \
k00, k01, k02, \
k10, k11, \
) \
{ \
{ k00, k01, k02 }, \
{ k10, KC_NO, k11 }, \
}
Notice how the top half is spaced to resemble our physical layout - this helps us understand which keys are associated with which columns. The bottom half uses the keycode `KC_NO` where there is no keyswitch wired in. It's easiest to keep the bottom half aligned in a grid to help us make sense of how the firmware actually sees the wiring.
Let's say that instead, we wired our keyboard like this (a fair thing to do):
┌───┬───┬───┐
│ ┋ │ ┋│ ┋ │
├─┋─┴─┬┋┴───┤
│ ┋ │┋ │
└─────┴─────┘
This would require our `KEYMAP` definition to look like this:
#define KEYMAP( \
k00, k01, k02, \
k10, k11, \
) \
{ \
{ k00, k01, k02 }, \
{ k10, k11, KC_NO }, \
}
Notice how the `k11` and `KC_NO` switched places to represent the wiring, and the unused final column on the bottom row. Sometimes it'll make more sense to put a keyswitch on a particular column, but in the end, it won't matter, as long as all of them are accounted for. You can use this process to write out the `KEYMAP` for your entire keyboard - be sure to remember that your keyboard is actually backwards when looking at the underside of it.
#### keymaps/default.c
This is the actual keymap for your keyboard, and the main place you'll make changes as you perfect your layout. `default.c` is the file that gets pull by default when typing `make`, but you can make other files as well, and specify them by typing `make KEYMAP=<variant>`, which will pull `keymaps/<variant>.c`.
The basis of a keymap is its layers - by default, layer 0 is active. You can activate other layers, the highest of which will be referenced first. Let's start with our base layer.
Using our previous example, let's say we want to create the following layout:
┌───┬───┬───┐
│ A │ 1 │ H │
├───┴─┬─┴───┤
│ TAB │ SPC │
└─────┴─────┘
This can be accomplished by using the following `keymaps` definition:
Note that the layout of the keycodes is similar to the physical layout of our keyboard - this make it much easier to see what's going on. A lot of the keycodes should be fairly obvious, but for a full list of them, check out [tmk_code/doc/keycode.txt](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/doc/keycode.txt) - there are also a lot of aliases to condense your keymap file.
It's also important to use the `KEYMAP` function we defined earlier - this is what allows the firmware to associate our intended readable keymap with the actual wiring.
#### Compiling your firmware
After you've written out your entire keymap, you're ready to get the firmware compiled and onto your Teensy. Before compiling, you'll need to get your [development environment set-up](/doc/BUILD_GUIDE.md) - you can skip the dfu-programmer instructions, but you'll need to download and install the [Teensy Loader](https://www.pjrc.com/teensy/loader.html) to get the firmware on your Teensy.
Once everything is installed, running `make` in the terminal should get you some output, and eventually a `<project_name>.hex` file in that folder. If you're having trouble with this step, see the end of the guide for the trouble-shooting section.
Once you have your `<project_name>.hex` file, open up the Teensy loader application, and click the file icon. From here, navigate to your `QMK/keyboards/<project_name>/` folder, and select the `<project_name>.hex` file. Plug in your keyboard and press the button on the Teensy - you should see the LED on the device turn off once you do. The Teensy Loader app will change a little, and the buttons should be clickable - click the download button (down arrow), and then the reset button (right arrow), and your keyboard should be ready to go!
#### Testing your firmware
Carefully flip your keyboard over, open up a new text document, and try typing - you should get the characters that you put into your keymap. Test each key, and note the ones that aren't working. Here's a quick trouble-shooting guide for non-working keys:
0. Flip the keyboard back over and short the keyswitch's contacts with a piece wire - this will eliminate the possibility of the keyswitch being bad and needing to be replaced.
1. Check the solder points on the keyswitch - these need to be plump and whole. If you touch it with a moderate amount of force and it comes apart, it's not strong enough.
2. Check the solder joints on the diode - if the diode is loose, part of your row may register, while the other may not.
3. Check the solder joints on the columns - if your column wiring is loose, part or all of the column may not work.
4. Check the solder joints on both sides of the wires going to/from the Teensy - the wires need to be fully soldered and connect to both sides.
5. Check the <project_name>.h file for errors and incorrectly placed `KC_NO`s - if you're unsure where they should be, instead duplicate a k*xy* variable.
6. Check to make sure you actually compiled the firmware and flashed the Teensy correctly. Unless you got error messages in the terminal, or a pop-up during flashing, you probably did everything correctly.
If you've done all of these things, keep in mind that sometimes you might have had multiple things affecting the keyswitch, so it doesn't hurt to test the keyswitch by shorting it out at the end.
#### Securing the Teensy, finishing your hardware, getting fancier firmware
Now that you have a working board, it's time to get things in their permanent positions. I've often used liberal amounts of hot glue to secure and insulate things, so if that's your style, start spreading that stuff like butter. Otherwise, double-sided tape is always an elegant solution, and electrical tape is a distant second. Due to the nature of these builds, a lot of this part is up to you and how you planned (or didn't plan) things out.
There are a lot of possibilities inside the firmware - check out the [readme](https://github.com/qmk/qmk_firmware/blob/master/readme.md) for a full feature list, and dive into the different project (Planck, Ergodox EZ, etc) to see how people use all of them. You can always stop by [the OLKB subreddit for help!](http://reddit.com/r/olkb)
1. Install [MHV AVR Tools](https://infernoembedded.com/sites/default/files/project/MHV_AVR_Tools_20131101.exe). Disable smatch, but **be sure to leave the option to add the tools to the PATH checked**.
2. Install [MinGW](https://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download). During installation, uncheck the option to install a graphical user interface. **DO NOT change the default installation folder.** The scripts depend on the default location.
3. Clone this repository. [This link will download it as a zip file, which you'll need to extract.](https://github.com/qmk/qmk_firmware/archive/master.zip) Open the extracted folder in Windows Explorer.
4. Right-click on the 1-setup-path-win batch script, select "Run as administrator", and accept the User Account Control prompt. Press the spacebar to dismiss the success message in the command prompt that pops up.
5. Right-click on the 2-setup-environment-win batch script, select "Run as administrator", and accept the User Account Control prompt. This part may take a couple of minutes, and you'll need to approve a driver installation, but once it finishes, your environment is complete!
### Mac
If you're using homebrew, you can use the following commands:
brew tap osx-cross/avr
brew install avr-libc
brew install dfu-programmer
Otherwise, these instructions will work:
1. Install Xcode from the App Store.
2. Install the Command Line Tools from `Xcode->Preferences->Downloads`.
3. Install [DFU-Programmer][dfu-prog].
### Linux
1. Install AVR GCC with your favorite package manager.
2. Install [DFU-Programmer][dfu-prog].
Note that, since it will be directly accessing USB hardware, the
`dfu-programmer` program needs to be run as root.
## Verify Your Installation
1. Clone the following repository: https://github.com/qmk/qmk_firmware
2. Open a Terminal and `cd` into `qmk_firmware/keyboards/planck`
3. Run `make`. This should output a lot of information about the build process.
## Using the built-in functions
Here is a list of some of the functions available from the command line:
*`make clean`: clean the environment - may be required in-between builds
*`make`: compile the code
*`make KEYMAP=<keymap>`: compile with the extended keymap file `extended_keymaps/extended_keymap_<keymap>.c`
*`make dfu`: build and flash the layout to the PCB
*`make dfu-force`: build and force-flash the layout to the PCB (may be require for first flash)
Generally, the instructions to flash the PCB are as follows:
1. Make changes to the appropriate keymap file
2. Save the file
3.`make clean`
4. Press the reset button on the PCB/press the key with the `RESET` keycode
5.`make <arguments> dfu` - use the necessary `KEYMAP=<keymap>` and/or `COMMON=true` arguments here.
## Troubleshooting
If you see something like this
0 [main] sh 13384 sync_with_child: child 9716(0x178) died before initialization with status code 0xC0000142
440 [main] sh 13384 sync_with_child: *** child state waiting for longjmp
after running 'make' on Windows than you are encountering a very popular issue with WinAVR on Windows 8.1 and 10.
You can easily fix this problem by replacing msys-1.0.dll in WinAVR/utils/bin with [this one](http://www.madwizard.org/download/electronics/msys-1.0-vista64.zip).
Restart your system and everything should work fine!
make (e=2): The system cannot find the file specified.
make: *** [dfu] Error 2
when trying to 'make dfu' on Windows you need to copy the dfu-programmer.exe to qmk_firmware/keyboards/planck.
## Quantum MK Firmware
### Keymap
Unlike the other keymaps, prefixing the keycodes with `KC_` is required. A full list of the keycodes is available [here](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/doc/keycode.txt). For the keycodes available only in the extended keymap, see this [header file](https://github.com/qmk/qmk_firmware/blob/master/quantum/keymap_common.h).
You can use modifiers with keycodes like this:
LCTL(KC_C)
Which will generate Ctrl+c. These are daisy-chainable, meaning you can do things like:
LCTL(LALT(KC_C))
That will generate Ctrl+Alt+c. The entire list of these functions is here:
*`LCTL()`: Left control
*`LSFT()` / `S()`: Left shift
*`LALT()`: Left alt/opt
*`LGUI()`: Left win/cmd
*`RCTL()`: Right control
*`RSFT()`: Right shift
*`RALT()`: Right alt/opt
*`RGUI()`: Right win/cmd
`S(KC_1)`-like entries are useful in writing keymaps for the Planck.
### Other keycodes
A number of other keycodes have been added that you may find useful:
*`CM_<key>`: the Colemak equivalent of a key (in place of `KC_<key>`), when using Colemak in software (`CM_O` generates `KC_SCLN`)
*`RESET`: jump to bootloader for flashing (same as press the reset button)
*`BL_STEP`: step through the backlight brightnesses
*`BL_<0-15>`: set backlight brightness to 0-15
*`BL_DEC`: lower the backlight brightness
*`BL_INC`: raise the backlight brightness
*`BL_TOGG`: toggle the backlight on/off
### Function layers
The extended keymap extends the number of function layers from 32 to the near-infinite value of 256. Rather than using `FN<num>` notation (still available, but limited to `FN0`-`FN31`), you can use the `FUNC(<num>)` notation. `F(<num>)` is a shortcut for this.
The function actions are unchanged, and you can see the full list of them [here](https://github.com/jackhumbert/tmk_keyboard/blob/master/common/action_code.h). They are explained in detail [here](https://github.com/jackhumbert/tmk_keyboard/blob/master/doc/keymap.md#2-action).
### Macros
Macros have been setup in the `keymaps/keymap_default.c` file so that you can use `M(<num>)` to access a macro in the `action_get_macro` section on your keymap. The switch/case structure you see here is required, and is setup for `M(0)` - you'll need to copy and paste the code to look like this (e.g. to support `M(3)`):
switch(id) {
case 0:
return MACRODOWN(TYPE(KC_A), END);
break;
case 1:
return MACRODOWN(TYPE(KC_B), END);
break;
case 2:
return MACRODOWN(TYPE(KC_C), END);
break;
case 3:
return MACRODOWN(TYPE(KC_D), END);
break;
}
return MACRO_NONE;
`MACRODOWN()` is a shortcut for `(record->event.pressed ? MACRO(__VA_ARGS__) : MACRO_NONE)` which tells the macro to execute when the key is pressed. Without this, the macro will be executed on both the down and up stroke.
**GPLv2** or later. Some protocol files are under **Modified BSD License**.
LUFA, PJRC and V-USB stack have their own license respectively.
Third party libraries like LUFA, PJRC and V-USB have their own license respectively.
Build Firmware and Program Controller
-------------------------------------
See [doc/build.md](doc/build.md).
See [build environment setup](/readme.md#build-environment-setup), or the readme in the particular keyboards/* folder.
Change your keymap
------------------
See [doc/keymap.md](doc/keymap.md).
See [doc/keymap.md](tmk_core/doc/keymap.md).
Magic Comannds
Magic Commands
--------------
To see help press `Magic` + `H`.
`Magic` key bind may be`LShift` + `RShift` in many project, but `Power` key on ADB converter. `Magic` keybind can be vary on each project, check `config.h` in project directory.
`Magic` key combination is`LShift` + `RShift` in many project, but `Power` key on ADB converter.
`Magic` keybind can be vary on each project, check `config.h` in project directory.
Following commands can be also executed with `Magic` + key. In console mode `Magic` keybind is not needed.
@@ -118,13 +152,14 @@ Following commands can be also executed with `Magic` + key. In console mode `Mag
Caps: Lock Keyboard(Child Proof)
Paus: jump to bootloader
**TBD**
### Boot Magic Configuration - Virtual DIP Switch
Boot Magic are executed during boot up time. Press Magic key below then pulgin keyboard cable.
Boot Magic Configuration - Virtual DIP Switch
---------------------------------------------
Boot Magic are executed during boot up time. Press Magic key below then plug in keyboard cable.
Note that you must use keys of **Layer 0** as Magic keys. These settings are stored in EEPROM so that retain your configure over power cycles.
To avoid configuring accidentally additive salt key `KC_SPACE` also needs to be pressed along with the following configuration keys. The salt key is configurable in `config.h`. See [common/bootmagic.h](common/bootmagic.h).
To avoid configuring accidentally additive salt key `KC_SPACE` also needs to be pressed along with the following configuration keys. The salt key is configurable in `config.h`. See [tmk_core/common/bootmagic.h](tmk_core/common/bootmagic.h).
#### General
- Skip reading EEPROM to start with default configuration(`ESC`)
@@ -141,12 +176,13 @@ To avoid configuring accidentally additive salt key `KC_SPACE` also needs to be
#### Keymap
- Swap Control and CapsLock(`Left Control`)
- Change CapsLock to Control(`Casp Lock`)
- Change CapsLock to Control(`Caps Lock`)
- Swap LeftAlt and Gui(`Left Alt`)
- Swap RightAlt and Gui(`Right Alt`)
- Disable Gui(`Left Gui`)
- Swap Grave and Escape(`Grave`)
- Swap BackSlash and BackSpace(`Back Slash`)
- Enable NKRO on boot(`N`)
#### Default Layer
- Set Default Layer to 0(`0`)
@@ -158,112 +194,45 @@ To avoid configuring accidentally additive salt key `KC_SPACE` also needs to be
- Set Default Layer to 6(`6`)
- Set Default Layer to 7(`7`)
#### Caution
Unintentional use of this feature will cause user confusion.
TODO: Magic key combination to avoid unintentional press during plug in
**TBD**
Mechanical Locking support
--------------------------
This feature makes it possible for you to use mechanical switch for `CapsLock`, `NumLock`or `ScrollLock`. To enable this feature define these macros in `config.h` and use `KC_LCAP`, `KC_LNUM` or `KC_LSCR` in keymap for locking key instead of normal `KC_CAPS`, `KC_NLCK` or `KC_SLCK`. Resync option tries to keep lock switch state consistent with keyboard LED state.
This feature makes it possible for you to use mechanical locking switch for `CapsLock`, `NumLock`
or `ScrollLock`. To enable this feature define these macros in `config.h` and use `KC_LCAP`, `KC_LN
UM` or `KC_LSCR` in keymap for locking key instead of normal `KC_CAPS`, `KC_NLCK` or `KC_SLCK`. Res
ync option tries to keep switch state consistent with keyboard LED state.
#define LOCKING_SUPPORT_ENABLE
#define LOCKING_RESYNC_ENABLE
Start Your Own Project
-----------------------
**TBD**
### Config.h Options
#### 1. USB vendor/product ID and device description
#define VENDOR_ID 0xFEED
#define PRODUCT_ID 0xBEEF
#define MANUFACTURER t.m.k.
#define PRODUCT Macway mod
#define DESCRIPTION t.m.k. keyboard firmware for Macway mod
This project includes a Vagrantfile that will allow you to build a new firmware for your keyboard very easily without major changes to your primary operating system. This also ensures that when you clone the project and perform a build, you have the exact same environment as anyone else using the Vagrantfile to build. This makes it much easier for people to help you troubleshoot any issues you encounter.
## Requirements
Using the `/Vagrantfile` in this repository requires you have [Vagrant](http://www.vagrantup.com/) as well as [VirtualBox](https://www.virtualbox.org/) (or [VMware Workstation](https://www.vmware.com/products/workstation) and [Vagrant VMware plugin](http://www.vagrantup.com/vmware) but the (paid) VMware plugin requires a licensed copy of VMware Workstation/Fusion).
*COMPATIBILITY NOTICE* Certain versions of Virtualbox 5 appear to have an incompatibility with the Virtualbox extensions installed in the boxes in this Vagrantfile. If you encounter any issues with the /vagrant mount not succeeding, please upgrade your version of Virtualbox to at least 5.0.12. **Alternately, you can try running the following command:**`vagrant plugin install vagrant-vbguest`
Other than having Vagrant and Virtualbox installed and possibly a restart of your computer afterwards, you can simple run a 'vagrant up' anywhere inside the folder where you checked out this project and it will start a Linux virtual machine that contains all the tools required to build this project. There is a post Vagrant startup hint that will get you off on the right foot, otherwise you can also reference the build documentation below.
Build Firmware and Program Controller
-------------------------------------
See [/doc/BUIDE_GUIDE.md](/doc/BUILD_GUIDE.md), or the readme in the particular keyboards/* folder.
Change your keymap
------------------
See [/doc/keymap.md](/doc/keymap.md).
## Flashing the firmware
The "easy" way to flash the firmware is using a tool from your host OS like the Teensy programming app. [ErgoDox EZ](/keyboards/ergodox/readme.md) gives a great example.
If you want to program via the command line you can uncomment the ['modifyvm'] lines in the Vagrantfile to enable the USB passthrough into Linux and then program using the command line tools like dfu-util/dfu-programmer or you can install the Teensy CLI version.
# How keys are registered, and interpreted by computers
In this file, you can will learn the concepts of how keyboards work over USB,
and you'll be able to better understand what you can expect from changing your
firmware directly.
## Schematic view
Whenever you type on 1 particular key, here is the chain of actions taking
place:
``` text
+------+ +-----+ +----------+ +----------+ +----+
| User |-------->| Key |------>| Firmware |----->| USB wire |---->| OS |
+------+ +-----+ +----------+ +----------+ |----+
```
This scheme is a very simple view of what's going on, and more details follow
in the next sections.
## 1. You Press a Key
Whenever you press a key, the firmware of your keyboard can register this event.
It can register when the key is pressed, held and released.
This usually happens with a [periodic scan of key presses with a frequency around 100 hz](https://github.com/benblazak/ergodox-firmware/blob/master/references.md#typical-keyboard-information).
This speed often is limited by the mechanical key response time, the protocol
to transfer those key presses (here USB HID), and by the software it is used in.
## 2. What the Firmware Sends
The [HID specification](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf)
tells what a keyboard can actually send through USB to have a chance to be
properly recognised. This includes a pre-defined list of keycodes which are
simple numbers from `0x00` to `0xE7`. The firmware assigns a keycode to each
key of the keyboard.
The firmware does not send actually letters or characters, but only keycodes.
Thus, by modifying the firmware, you only can modify what keycode is sent over
USB for a given key.
## 3. What the Operating System Does
Once the keycode reaches the operating system, a piece of software has to have
it match an actual character thanks to a keyboard layout. For example, if your
layout is set to QWERTY, a sample of the matching table is as follow:
``` text
| keycode | character |
|---------+-----------|
| 0x04 | a/A |
| 0x05 | b/B |
| 0x06 | c/C |
| ... | ... |
| 0x1C | y/Y |
| 0x1D | z/Z |
| ... | ... |
|---------+-----------|
```
## Back to the firmware
As the layout is generally fixed (unless you create your own), the firmware can
actually call a keycode by its layout name directly to ease things for you.
This is exactly what is done here with `KC_A` actually representing `0x04` in
QWERTY. The full list can be found in `keycode.txt`.
## List of Characters You Can Send
Putting aside shortcuts, having a limited set of keycodes mapped to a limited
layout means that **the list of characters you can assign to a given key only
is the ones present in the layout**.
For example, this means that if you have a QWERTY US layout, and you want to
assign 1 key to produce `€` (euro currency symbol), you are unable to do so,
because the QWERTY US layout does not have such mapping. You could fix that by
using a QWERTY UK layout, or a QWERTY US International.
You may wonder why a keyboard layout containing all of Unicode is not devised
then? The limited number of keycode available through USB simply disallow such
a thing.
## How to (Maybe) Enter Unicode Characters
You can have the firmware send *sequences of keys* to use the [software Unicode
Input
Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input) of
the target operating system, thus effectively entering characters independently
of the layout defined in the OS.
Yet, it does come with multiple disadvantages:
- Tied to a specific OS a a time (need recompilation when changing OS);
- Within a given OS, does not work in all software;
## This guide may be out-dated - use doc/BUILD_GUIDE.md instead
Download and Install
--------------------
### 1. Install Tools
First, you need tools to build firmware and program your controller. I assume you are on Windows here.
1. **Toolchain**Install [WinAVR][winavr]. This is old but works well for this purpose. `WinAVR` is a tool set to build firmware including C compiler(gcc) and make commands. You can use [CrossPack][crosspack] instead if you are on Mac.
1. **Toolchain**On Windows install [MHV AVR Tools][mhv] for AVR GCC compiler and [Cygwin][cygwin](or [MinGW][mingw]) for shell terminal. On Mac you can use [CrossPack][crosspack]. On Linux you can install AVR GCC (and avr-libc) with your favorite package manager or run the avr_setup.sh script in the root of this repository.
2. **Programmer**Install [Atmel FLIP][flip]. `FLIP` is a tool to program(load) firmware into AVR controller via DFU bootloader. AVR USB chips including ATmega32U4 has DFU bootloader by factory default. You can also use [dfu-programmer][dfu-prog] instead if you are on Mac or Linux.
2. **Programmer**On Windows install [Atmel FLIP][flip]. On Mac and Linux install [dfu-programmer][dfu-prog].
3. **Driver**At first time you start DFU bootloader on Chip 'Found New Hardware Wizard' will come up on Windows. If you install device driver properly you can find chip name like 'ATmega32U4' under 'LibUSB-Win32 Devices' tree on 'Device Manager'. If not you shall need to update its driver on 'Device Manager'. You will find the driver in `FLIP` install directory like: C:\Program Files (x86)\Atmel\Flip 3.4.5\usb\. If you use`dfu-programmer`install its driver.
3. **Driver**On Windows you start DFU bootloader on the chip first time you will see 'Found New Hardware Wizard' to install driver. If you install device driver properly you can find chip name like 'ATmega32U4' under 'LibUSB-Win32 Devices' tree on 'Device Manager'. If not you shall need to update its driver on 'Device Manager'. You will find the driver in `FLIP` install directory like: C:\Program Files (x86)\Atmel\Flip 3.4.5\usb\. In case of`dfu-programmer`use its driver.
If you use PJRC Teensy you don't need step 2 and 3 above, just get [Teensy loader][teensy-loader].
### 2. Download source
You can find firmware source at github:
You can find firmware source at github:
- <https://github.com/tmk/tmk_keyboard>
If you are familiar with `Git` tools you are recommended to use it but you can also download zip archive from:
If you are familiar with `Git` tools you are recommended to use it but you can also download zip archive from:
@@ -29,7 +29,7 @@ If you are familiar with `Git` tools you are recommended to use it but you can a
Build firmware
--------------
### 1. Open terminal
Open terminal window to get access to commands. You can use `cmd` in Windows or `Terminal.app` on Mac OSX. In Windows press `Windows` key and `R` then enter `cmd` in 'Run command' dialog showing up.
Open terminal window to get access to commands. Use Cygwin(or MingGW) `shell terminal` in Windows or `Terminal.app` on Mac OSX. In Windows press `Windows` key and `R` then enter `cmd` in 'Run command' dialog showing up.
### 2. Change directory
Move to project directory in the firmware source.
@@ -40,7 +40,7 @@ Move to project directory in the firmware source.
Build firmware using GNU `make` command. You'll see `<project>_<variant>.hex` file in that directory unless something unexpected occurs in build process.
mkae -f Makefile.<variant> clean
make -f Makefile.<variant> clean
make -f Makefile.<variant>
@@ -71,14 +71,14 @@ Or to program with `dfu-programmer` run:
#### FLIP GUI tutorial
1. On menu bar click Device -> Select, then. `ATmega32u4`.
2. On menu bar click Settings -> Communication -> USB, then click 'Open' button on 'USB Port Connection' dialog.
At this point you'll see greyouted widgets on the app get colored and ready.
At this point you'll see grey-outed widgets on the app get colored and ready.
3. On menu bar click File -> Load HEX File, then select your firmware hex file on File Selector dialog.
4. On 'Operations Flow' panel click 'Run' button to load the firmware binary to the chip. Note that you should keep 'Erase', 'Blank Check', 'Program' and 'Verify' check boxes selected.
5. Re-plug USB cord or click 'Start Application' button to restart your controller.
@@ -95,11 +95,14 @@ Or use this command if you have command line version of Teensy Loader installed.
### 4. Program with Other programmer
You may want to use other programmer like `avrdude` with AVRISPmkII, Aruduino or USBasp. In that case you can still use make target `program` for build with configuring `PROGRAM_CMD` in Makefile.
You may want to use other programmer like `avrdude` with AVRISPmkII, Arduino or USBasp. In that case you can still use make target `program` for build with configuring `PROGRAM_CMD` in Makefile.
Optional. Set proper command for your controller, bootloader and programmer. This command can be used with `make program`. Not needed if you use `FLIP`, `dfu-programmer` or `Teesy Loader`.
Optional. Set proper command for your controller, bootloader and programmer. This command can be used with `make program`. Not needed if you use `FLIP`, `dfu-programmer` or `Teensy Loader`.
@@ -68,7 +68,7 @@ On the other hand, you shall change `layer_state` to overlay base layer with som
Note that ***higher layer has higher priority on stack of layers***, namely firmware falls down from top layer to bottom to look up keycode. Once it spots keycode other than **`KC_TRNS`**(transparent) on a layer it stops searching and lower layers aren't referred.
You can place `KC_TRNS` on overlay layer changes just part of layout to fall back on lower or base layer.
Key with `KC_TRANS` doen't has its own keycode and refers to lower valid layers for keycode, instead.
Key with `KC_TRANS` doesn't has its own keycode and refers to lower valid layers for keycode, instead.
See example below.
@@ -155,12 +155,12 @@ You can find other keymap definitions in file `keymap.c` located on project dire
## 1. Keycode
See [`common/keycode.h`](../common/keycode.h) or keycode table below for the detail. Keycode is internal **8bit code** to inidicate action performed on key in keymap. Keycode has `KC_` prefixed symbol respectively. Most of keycodes like `KC_A` have simple action registers key to host on press and unregister on release, while some of other keycodes has some special actions like `Fn` keys, Media contorl keys, System control keys and Mousekeys.
See [`common/keycode.h`](../common/keycode.h) or keycode table below for the detail. Keycode is internal **8bit code** to indicate action performed on key in keymap. Keycode has `KC_` prefixed symbol respectively. Most of keycodes like `KC_A` have simple action registers key to host on press and unregister on release, while some of other keycodes has some special actions like `Fn` keys, Media control keys, System control keys and Mousekeys.
***In `KEYMAP()` macro you should omit prefix part `KC_` of keycode to keep keymap compact.*** For example, just use `A` instead you place `KC_A` in `KEYMAP()`. Some keycodes has 4-letter **short name** in addition to descriptive name, you'll prefer short one in `KEYMAP()`.
### 1.0 Other key
-`KC_NO` for no aciton
-`KC_NO` for no action
-`KC_TRNS` for layer transparency (See above)
### 1.1 Normal key
@@ -192,20 +192,20 @@ There are 8 modifiers which has discrimination between left and right.
-`KC_WSCH`, `KC_WHOM`, `KC_WBAK`, `KC_WFWD`, `KC_WSTP`, `KC_WREF`, `KC_WFAV` for web browser operation
### 1.5 Fn key
`KC_FNnn` are keycodes for `Fn` key which not given any actions at the beginning unlike most of keycodes has its own inborn action. To use these keycodes in `KEYMAP()` you need to assign action you want at first. Action of `Fn` key is defined in `fn_actions[]` and its index of the array is identical with number part of `KC_FNnn`. Thus `KC_FN0` keyocde indicates the action defined in first element of the array. ***32 `Fn` keys can be defined at most.***
`KC_FNnn` are keycodes for `Fn` key which not given any actions at the beginning unlike most of keycodes has its own inborn action. To use these keycodes in `KEYMAP()` you need to assign action you want at first. Action of `Fn` key is defined in `fn_actions[]` and its index of the array is identical with number part of `KC_FNnn`. Thus `KC_FN0` keycode indicates the action defined in first element of the array. ***32 `Fn` keys can be defined at most.***
### 1.6 Keycode Table
See keycode table in [`doc/keycode.txt`](./keycode.txt) for description of keycodes.
In regard to implementation side most of keycodes are identical with [HID usage][HID_usage](pdf) sent to host for real and some virtual keycodes are defined to support special actions.
See [`common/action_code.h`](../common/action_code.h). Action is a **16bit code** and defines function to perform on events of a key like press, release, holding and tapping.
Most of keys just register 8bit scancode to host, but to support other complex features needs 16bit extended action codes internally. However, using 16bit action codes in keymap results in double size in memory compared to using jsut keycodes. To avoid this waste 8bit keycodes are used in `KEYMAP()` instead of action codes.
Most of keys just register 8bit scancode to host, but to support other complex features needs 16bit extended action codes internally. However, using 16bit action codes in keymap results in double size in memory compared to using just keycodes. To avoid this waste 8bit keycodes are used in `KEYMAP()` instead of action codes.
***You can just use keycodes of `Normal key`, `Modifier`, `Mousekey` and `System & Media key` in keymap*** to indicate corresponding actions instead of using action codes. While ***to use other special actions you should use keycode of `Fn` key defined in `fn_actions[]`.***
@@ -230,7 +230,7 @@ You can define these actions on *'A'* key and *'left shift'* modifier with:
#### 2.1.2 Modified key
This action is comprised of strokes of modifiers and a key. `Macro` action is needed if you want more complex key strokes.
Say you want to assign a key to `Shift + 1` to get charactor *'!'* or `Alt + Tab` to switch application windows.
Say you want to assign a key to `Shift + 1` to get character *'!'* or `Alt + Tab` to switch application windows.
ACTION_MODS_KEY(MOD_LSFT, KC_1)
ACTION_MODS_KEY(MOD_LALT, KC_TAB)
@@ -269,10 +269,10 @@ Default Layer is a layer which always is valid and referred to when actions is n
This sets Default Layer to given parameter `layer` and activate it.
ACTION_DEFAULT_LAYER(layer)
ACTION_DEFAULT_LAYER_SET(layer)
#### 2.2.2 Momentary Switch
#### 2.2.2 Momentary
Turns on `layer` momentarily while holding, in other words it activates when key is pressed and deactivate when released.
ACTION_LAYER_MOMENTARY(layer)
@@ -342,7 +342,7 @@ Turns on layer only and clear all layer on release..
ACTION_LAYER_BIT_XOR(part, bits, on)
ACTION_LAYER_BIT_SET(part, bits, on)
These actions works with prameters as following code.
These actions works with parameters as following code.
uint8_t shift = part*4;
uint32_t mask = (bits&0x10) ? ~(0xf<<shift) : 0;
@@ -368,7 +368,7 @@ Default Layer also has bitwise operations, they are executed when key is release
MACRO( I(255), T(H), T(E), T(L), T(L), W(255), T(O), END )
#### 2.3.1 Macro Commands
- **I()** change interavl of stroke.
- **I()** change interval of stroke.
- **D()** press key
- **U()** release key
- **T()** type key(press and release)
@@ -377,8 +377,8 @@ Default Layer also has bitwise operations, they are executed when key is release
#### 2.3.2 Examples
***TODO: sample impl***
See `keyboard/hhkb/keymap.c` for sample.
***TODO: sample implementation***
See `keyboards/hhkb/keymap.c` for sample.
@@ -403,7 +403,7 @@ To define tappable `Function` action in keymap use this.
This C function is called every time key is operated, argument `id` selects action to be performed and `opt` can be used for option. Functon `id` can be 0-255 and `opt` can be 0-15.
This C function is called every time key is operated, argument `id` selects action to be performed and `opt` can be used for option. Function `id` can be 0-255 and `opt` can be 0-15.
`keyrecord_t` is comprised of key event and tap count. `keyevent_t` indicates which and when key is pressed or released. From `tap_count` you can know tap state, 0 means no tap. These information will be used in user function to decide how action of key is performed.
@@ -423,8 +423,8 @@ This C function is called every time key is operated, argument `id` selects acti
uint8_t row;
} key_t;
***TODO: sample impl***
See `keyboard/hhkb/keymap.c` for sample.
***TODO: sample implementation***
See `keyboards/hhkb/keymap.c` for sample.
@@ -444,6 +444,10 @@ Step through backlight levels.
ACTION_BACKLIGHT_STEP()
Turn a specific backlight level on or off.
ACTION_BACKLIGHT_LEVEL(1)
#### 2.5.2 Turn on / off backlight
Turn the backlight on and off without changing level.
@@ -451,6 +455,35 @@ Turn the backlight on and off without changing level.
### 2.6 Swap-Hands Action
The swap-hands action allows support for one-handed keyboards without requiring a separate layer. Set `ONEHAND_ENABLE` in the Makefile and define a `hand_swap_config` entry in your keymap. Now whenever the `ACTION_SWAP_HANDS` command key is pressed the keyboard is mirrored. For instance, to type "Hello, World" on QWERTY you would type `^Ge^s^s^w^c W^wr^sd`
### 2.6.1 Configuration
The configuration table is a simple 2-dimensional array to map from column/row to new column/row. Example `hand_swap_config` for Planck:
Note that the array indices are reversed same as the matrix and the values are of type `keypos_t` which is `{col, row}` and all values are zero-based. In the example above, `hand_swap_config[2][4]` (third row, fifth column) would return {7, 2} (third row, eighth column).
### 2.6.2 Advanced Swap Commands
- **`ACTION_SWAP_HANDS()`** Swaps hands when pressed, returns to normal when released (momentary).
- **`ACTION_SWAP_HANDS_TOGGLE()`** Toggles swap on and off with every keypress.
- **`ACTION_SWAP_HANDS_TAP_TOGGLE()`** Toggles with a tap; momentary when held.
- **`ACTION_SWAP_HANDS_TAP_KEY(key)`** Sends `key` with a tap; momentary swap when held.
- **`ACTION_SWAP_HANDS_ON_OFF()`** Alias for `ACTION_SWAP_HANDS()`
- **`ACTION_SWAP_HANDS_OFF_ON()`** Momentarily turns off swap.
- **`ACTION_SWAP_HANDS_ON()`** Turns on swapping and leaves it on.
- **`ACTION_SWAP_HANDS_OFF()`** Turn off swapping and leaves it off. Good for returning to a known state.
## 3. Layer switching Example
There are some ways to switch layer with 'Layer' actions.
@@ -462,8 +495,8 @@ This action makes 'Layer 1' active(valid) on key press event and inactive on rel
ACTION_LAYER_MOMENTARY(1)
Note that after switching on press the actions on destinaton layer(Layer 1) are perfomed.
***Thus you shall need to place an action to go back on destination layer***, or you will be stuck in destination layer without way to get back. Usually you need to palce same action or 'KC_TRNS` on destination layer to get back.
Note that after switching on press the actions on destination layer(Layer 1) are performed.
***Thus you shall need to place an action to go back on destination layer***, or you will be stuck in destination layer without way to get back. Usually you need to place same action or 'KC_TRNS` on destination layer to get back.
### 3.2 Toggle switching
@@ -480,7 +513,7 @@ These actions switch a layer only while holding a key but register the key on ta
ACTION_LAYER_TAP_KEY(2, KC_SCLN)
With this you can place a layer switching action on normal key like ';' without losing its original key register function. This action allows you to have layer switchig action without necessity of a dedicated key. It means you can have it even on home row of keyboard.
With this you can place a layer switching action on normal key like ';' without losing its original key register function. This action allows you to have layer switching action without necessity of a dedicated key. It means you can have it even on home row of keyboard.
@@ -493,6 +526,13 @@ Number of taps can be configured with `TAPPING_TOGGLE` in `config.h`, `5` by def
### 3.5 Momentary switching with Modifiers
This registers modifier key(s) simultaneously with layer switching.
ACTION_LAYER_MODS(2, MOD_LSFT | MOD_LALT)
## 4. Tapping
Tapping is to press and release a key quickly. Tapping speed is determined with setting of `TAPPING_TERM`, which can be defined in `config.h`, 200ms by default.
@@ -511,20 +551,32 @@ Layer switching with tap key:
### 4.2 Tap Toggle
This is a feature to assign both toggle layer and momentary switch layer action to just same one physical key. It works as mementary layer switch when holding a key but toggle switch with several taps.
This is a feature to assign both toggle layer and momentary switch layer action to just same one physical key. It works as momentary layer switch when holding a key but toggle switch with several taps.
ACTION_LAYER_TAP_TOGGLE(1)
### 4.3 Oneshot Modifier
This runs onetime effectswhich modify only on just one following key. It works as normal modifier key when holding down while oneshot modifier when tapping.
This runs onetime effectswhich modify only on just one following key. It works as normal modifier key when holding down while oneshot modifier when tapping. The behavior of oneshot modifiers is similar to the [sticky keys](https://en.wikipedia.org/wiki/StickyKeys) functionality found in most operating systems.
ACTION_MODS_ONESHOT(MOD_LSFT)
Say you want to type 'The', you have to push and hold Shift key before type 't' then release it before type 'h' and 'e', otherwise you'll get 'THe' or 'the' unintentionally. With Oneshot Modifier you can tap Shift then type 't', 'h' and 'e' normally, you don't need to holding Shift key properly here. This mean you can realease Shift before 't' is pressed down.
Oneshot layer key:
ACTION_LAYER_ONESHOT(MY_LAYER)
Say you want to type 'The', you have to push and hold Shift key before type 't' then release it before type 'h' and 'e', otherwise you'll get 'THe' or 'the' unintentionally. With Oneshot Modifier you can tap Shift then type 't', 'h' and 'e' normally, you don't need to holding Shift key properly here. This mean you can release Shift before 't' is pressed down.
Oneshot effect is cancel unless following key is pressed down within `ONESHOT_TIMEOUT` of `config.h`. No timeout when it is `0` or not defined.
Most implementations of sticky keys allow you to lock a modifier by double tapping the modifier. The layer then remains locked untill the modifier is tapped again. To enable this behaviour for oneshot modifiers set `ONESHOT_TAP_TOGGLE` to the number taps required. The feature is disabled if `ONESHOT_TAP_TOGGLE<2` or not defined.
### 4.4 Tap Toggle Mods
Similar to layer tap toggle, this works as a momentary modifier when holding, but toggles on with several taps. A single tap will 'unstick' the modifier again.
Use `make -f Makefile.pjrc` if you want to use PJRC stack but I find no reason to do so now.
## Keymap
Several version of keymap are available in advance but you are recommended to define your favorite layout yourself. To define your own keymap create file named `keymap_<name>.c` and see keymap document(you can find in top README.md) and existent keymap files.
To build firmware binary hex file with a certain keymap just do `make` with `KEYMAP` option like:
$ make KEYMAP=[poker|poker_set|poker_bit|plain|hasu|spacefn|hhkb|<name>]
### 1 Poker
[keymap_poker.c](keymap_poker.c) emulates original Poker layers
while both [keymap_poker_bit.c](keymap_poker_bit.c) and [keymap_poker_set.c](keymap_poker_set.c) implements same layout in different way and they fix a minor issue of original Poker and enhance arrow keys.
This is my favourite keymap with HHKB Fn, Vi cursor and Mousekey layer. See [keymap_hasu.c](keymap_hasu.c) for detail.
### 4. SpaceFN
This layout proposed by spiceBar uses space bar to change layer with using Dual role key technique. See [keymap_spacefn.c](keymap_spacefn.c) and [SpaceFN discussion](http://geekhack.org/index.php?topic=51069.0).
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
