* [Preonic](/keyboards/preonic/)
* [Atomic](/keyboards/atomic/)
* [ErgoDox EZ](/keyboards/ergodox_ez/)
-* [Clueboard rev.1](/keyboards/clueboard1/)
-* [Clueboard rev.2](/keyboards/clueboard2/)
+* [Clueboard](/keyboards/clueboard/)
* [Cluepad](/keyboards/cluepad/)
The project also includes community support for [lots of other keyboards](/keyboards/).
4. Clone this repository. [This link will download it as a zip file, which you'll need to extract.](https://github.com/jackhumbert/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".
+7. Future build commands should be run from the MHV AVR Shell, which sets up an environment compatible with colorful build output. The standard Command Prompt will also work, but add `COLOR=false` to the end of all make commands when using it.
### Mac
If you're using [homebrew,](http://brew.sh/) you can use the following commands:
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 flashing your keymap
+# Customizing your keymap
In every keymap folder, the following files are recommended:
You can then override any settings, rather than having to copy and paste the whole thing.
-## Editing your keymap
+## Going beyond the keycodes
Aside from the [basic keycodes](doc/keycode.txt), your keymap can include shortcuts to common operations.
#define LSPO_KEY KC_9
#define RSPC_KEY KC_0
+You can also choose between different rollover behaviors of the shift keys by defining:
+
+ #define DISABLE_SPACE_CADET_ROLLOVER
+
+in your `config.h`. Disabling rollover allows you to use the opposite shift key to cancel the space cadet state in the event of an erroneous press instead of emitting a pair of parentheses when the keys are released.
+
The only other thing you're going to want to do is create a `Makefile` in your keymap directory and set the following:
```
As you can see, you have three function. you can use - `SEQ_ONE_KEY` for single-key sequences (Leader followed by just one key), and `SEQ_TWO_KEYS` and `SEQ_THREE_KEYS` for longer sequences. Each of these accepts one or more keycodes as arguments. This is an important point: You can use keycodes from **any layer on your keyboard**. That layer would need to be active for the leader macro to fire, obviously.
+### Tap Dance: A single key can do 3, 5, or 100 different things
+
+Hit the semicolon key once, send a semicolon. Hit it twice, rapidly -- send a colon. Hit it three times, and your keyboard's LEDs do a wild dance. That's just one example of what Tap Dance can do. It's one of the nicest community-contributed features in the firmware, conceived and created by [algernon](https://github.com/algernon) in [#451](https://github.com/jackhumbert/qmk_firmware/pull/451). Here's how Algernon describes the 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, let's 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)
+};
+```
+
### Temporarily setting the default layer
`DF(layer)` - sets default layer to *layer*. The default layer is the one at the "bottom" of the layer stack - the ultimate fallback layer. This currently does not persist over power loss. When you plug the keyboard back in, layer 0 will always be the default. It is theoretically possible to work around that, but that's not what `DF` does.
Enable the backlight from the Makefile.
-# Custom Quantum functions for keyboards and keymaps
+# Custom Quantum functions
All of these functions are available in the `*_kb()` or `*_user()` variety. `kb` ones should only be used in the `<keyboard>/<keyboard>.c` file, and `user` ones should only be used in the `keymap.c`. The keyboard ones call the user ones - it's necessary to keep these calls to allow the keymap functions to work correctly.
and can be tested against the `usb_led` with a conditional like `if (usb_led & (1<<USB_LED_CAPS_LOCK))` - if this is true, you can turn your LED one, otherwise turn it off.
+# Modding your keyboard
-# Audio output from a speaker
+## Audio output from a speaker
Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any keyboard that allows access to the C6 port, you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
"Rest style" in the method signature above (the last parameter) specifies if there's a rest (a moment of silence) between the notes.
-# MIDI functionalty
+## MIDI functionalty
This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile.
-# Bluetooth functionality
+## Bluetooth functionality
This requires [some hardware changes](https://www.reddit.com/r/MechanicalKeyboards/comments/3psx0q/the_planck_keyboard_with_bluetooth_guide_and/?ref=search_posts), but can be enabled via the Makefile. The firmware will still output characters via USB, so be aware of this when charging via a computer. It would make sense to have a switch on the Bluefruit to turn it off at will.
-# International Characters on Windows
+## International Characters on Windows
[AutoHotkey](https://autohotkey.com) allows Windows users to create custom hotkeys among others.
The hotkeys above are for the combination CtrlAltGui and CtrlAltGuiShift plus the letter a.
AutoHotkey inserts the Text right of `Send, ` when this combination is pressed.
-# RGB Under Glow Mod
+## RGB Under Glow Mod
RGBLIGHT_ENABLE = yes
-Please note that the underglow is not compatible with audio output. So you cannot enable both of them at the same time.
+In order to use the underglow timer functions, you need to have `#define RGBLIGHT_TIMER` in your `config.h`, and have audio disabled (`AUDIO_ENABLE = no` in your Makefile).
-Please add the following options into your config.h, and set them up according your hardware configuration. These settings are for the F4 by default:
-
- #define ws2812_PORTREG PORTF
- #define ws2812_DDRREG DDRF
- #define ws2812_pin PF4
+Please add the following options into your config.h, and set them up according your hardware configuration. These settings are for the `F4` pin by default:
+
+ #define RGB_DI_PIN F4 // The pin your RGB strip is wired to
+ #define RGBLIGHT_TIMER // Require for fancier stuff (not compatible with audio)
#define RGBLED_NUM 14 // Number of LEDs
#define RGBLIGHT_HUE_STEP 10
#define RGBLIGHT_SAT_STEP 17
#define RGBLIGHT_VAL_STEP 17
-You'll need to edit `PORTF`, `DDRF`, and `PF4` on the first three lines to the port/pin you have your LED(s) wired to, eg for B3 change things to:
-
- #define ws2812_PORTREG PORTB
- #define ws2812_DDRREG DDRB
- #define ws2812_pin PB3
+You'll need to edit `RGB_DI_PIN` to the pin you have your `DI` on your RGB strip wired to.
The firmware supports 5 different light effects, and the color (hue, saturation, brightness) can be customized in most effects. To control the underglow, you need to modify your keymap file to assign those functions to some keys/key combinations. For details, please check this keymap. `keyboards/planck/keymaps/yang/keymap.c`
-## WS2812 Wiring
+### WS2812 Wiring
projects / qmk_firmware.git / blobdiff