From 9d1a08e38ac9937cff4e61abfd0acc26ad5fdf4a Mon Sep 17 00:00:00 2001 From: skullY Date: Sun, 6 Aug 2017 20:57:57 -0700 Subject: [PATCH] Doc updates from going through every file --- docs/README.md | 2 +- docs/_summary.md | 8 +- docs/adding_features_to_qmk.md | 4 +- docs/documentation_best_practices.md | 20 + docs/faq_build.md | 21 +- docs/faq_debug.md | 39 ++ docs/faq_general.md | 4 +- docs/faq_keymap.md | 4 +- docs/feature_audio.md | 86 ++++ docs/feature_bluetooth.md | 6 +- docs/feature_common_shortcuts.md | 2 +- docs/{leader_key.md => feature_leader_key.md} | 0 docs/feature_ps2_mouse.md | 238 +++++++++++ docs/feature_rgblight.md | 31 ++ docs/features.md | 2 +- docs/getting_started_build_tools.md | 2 +- docs/getting_started_make_guide.md | 6 +- docs/hand_wire.md | 6 +- ...eyboards_work.md => how_keyboards_work.md} | 0 docs/keycodes.md | 42 +- docs/{basic_keycodes.md => keycodes_basic.md} | 0 docs/keymap.md | 7 +- docs/macros.md | 2 +- docs/modding_your_keyboard.md | 403 ------------------ docs/porting_your_keyboard_to_qmk.md | 4 +- docs/quantum_keycodes.md | 4 +- docs/understanding_qmk.md | 2 +- 27 files changed, 458 insertions(+), 487 deletions(-) rename docs/{leader_key.md => feature_leader_key.md} (100%) create mode 100644 docs/feature_ps2_mouse.md rename docs/{basic_how_keyboards_work.md => how_keyboards_work.md} (100%) rename docs/{basic_keycodes.md => keycodes_basic.md} (100%) delete mode 100644 docs/modding_your_keyboard.md diff --git a/docs/README.md b/docs/README.md index 06597a2b69..09317d6520 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,4 +22,4 @@ This would build the `rev4` revision of the `planck` with the `default` keymap. ## How to customize {#how-to-customize} -QMK has lots of [features](features/README.md) to explore, and a good deal of [reference documentation](reference/README.md) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md). +QMK has lots of [features](features.md) to explore, and a good deal of [reference documentation](http://docs.qmk.fm) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md). diff --git a/docs/_summary.md b/docs/_summary.md index 071ce56310..c73b8a0edf 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -17,9 +17,10 @@ * [Bootmagic](feature_bootmagic.md) * [Dynamic Macros](dynamic_macros.md) * [Key Lock](key_lock.md) - * [Leader Key](leader_key.md) + * [Leader Key](feature_leader_key.md) * [Macros](macros.md) * [Mouse keys](mouse_keys.md) + * [PS2 Mouse](feature_ps2_mouse.md) * [Space Cadet](space_cadet_shift.md) * [Tap Dance](tap_dance.md) * [Thermal Printer](feature_thermal_printer.md) @@ -30,7 +31,7 @@ * [Glossary](glossary.md) * [Keymap overview](keymap.md) * [Keycodes](keycodes.md) - * [Basic](basic_keycodes.md) + * [Basic](keycodes_basic.md) * [Quantum](quantum_keycodes.md) * [Backlight](feature_backlight.md#backlight-keycodes) * [Bluetooth](feature_bluetooth.md#bluetooth-keycodes) @@ -40,6 +41,7 @@ * [Mod Tap](feature_common_shortcuts.md#mod-tap) * [One Shot Keys](feature_common_shortcuts.md#one-shot-keys) * [Shifted Keys](feature_common_shortcuts.md#shifted-keycodes) + * [Stenography](stenography.md#keycode-reference) * [RGB Light](feature_rgblight.md#rgblight-keycodes) * [Thermal Printer](feature_thermal_printer.md#thermal-printer-keycodes) * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md) @@ -57,7 +59,7 @@ * [Porting your keyboard to QMK](porting_your_keyboard_to_qmk.md) * For a Deeper Understanding - * [How Keyboards Work](basic_how_keyboards_work.md) + * [How Keyboards Work](how_keyboards_work.md) * [Understanding QMK](understanding_qmk.md) * Other Topics diff --git a/docs/adding_features_to_qmk.md b/docs/adding_features_to_qmk.md index fb036496c7..e031ddbb7b 100644 --- a/docs/adding_features_to_qmk.md +++ b/docs/adding_features_to_qmk.md @@ -11,6 +11,6 @@ Once you have implemented your new feature you will generally submit a [pull req * **Disabled by default** - memory is a pretty limited on most chips QMK supports, and it's important that current keymaps aren't broken, so please allow your feature to be turned **on**, rather than being turned off. If you think it should be on by default, or reduces the size of the code, please talk with us about it. * **Compile locally before submitting** - hopefully this one is obvious, but things need to compile! Our Travis system will catch any issues, but it's generally faster for you to compile a few keyboards locally instead of waiting for the results to come back. -* **Consider subprojects and different chip-bases** - there are several keyboards that have subprojects that have allow for slightly different configurations, and even different chip-bases. Try to make a feature supported in ARM and AVR, or automatically disabled in one that doesn't work. +* **Consider subprojects and different chip-bases** - there are several keyboards that have subprojects that allow for slightly different configurations, and even different chip-bases. Try to make a feature supported in ARM and AVR, or automatically disabled on platforms it doesn't work on. * **Explain your feature** - Document it in `docs/`, either as a new file or as part of an existing file. If you don't document it other people won't be able to benefit from your hard work. -* **Don't refactor code** - to maintain a clear vision of how things are laid out in QMK, we try to plan out refactors in-depth, and have a collaborator make the changes. If you have an idea for refactoring, or suggestions, [open an issue](https://github.com/qmk/qmk_firmware/issues). +* **Don't refactor code** - to maintain a clear vision of how things are laid out in QMK, we try to plan out refactors in-depth, and have a collaborator make the changes. If you have an idea for refactoring, or suggestions, [open an issue](https://github.com/qmk/qmk_firmware/issues), we'd love to talk about how QMK can be improved. diff --git a/docs/documentation_best_practices.md b/docs/documentation_best_practices.md index f30793181c..059b25bcd3 100644 --- a/docs/documentation_best_practices.md +++ b/docs/documentation_best_practices.md @@ -75,3 +75,23 @@ You can add some colors. What about a warning message? What about an error message? **[error [ERROR] This is not the error you are looking for] ``` + +# Documenting Features + +If you create a new feature for QMK, create a documentation page for it. It doesn't have to be very long, a few sentances describing your feature and a table listing any relevant keycodes is enough. Here is a basic template: + +```markdown +# My Cool Feature + +This page describes my cool feature. You can use my cool feature to make coffee and order cream and sugar to be delivered via drone. + +## My Cool Feature Keycodes + +|Long Name|Short Name|Description| +|---------|----------|-----------| +|KC_COFFEE||Make Coffee| +|KC_CREAM||Order Cream| +|KC_SUGAR||Order Sugar| +``` + +Place your documentation into `docs/feature_.md`, and add that file to the appropriate place in `docs/_summary.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page. diff --git a/docs/faq_build.md b/docs/faq_build.md index ebe8caccd1..353e805948 100644 --- a/docs/faq_build.md +++ b/docs/faq_build.md @@ -1,17 +1,9 @@ # Frequently Asked Build Questions -This page covers questions about building QMK. If you have not yet you should read the [Build Guide](https://github.com/qmk/qmk_firmware/blob/master/docs/build_guide.md). - -In short, - - $ make [-f Makefile.] [KEYMAP=...] clean - $ make [-f Makefile.] [KEYMAP=...] - $ make [-f Makefile.] [KEYMAP=...] dfu - +This page covers questions about building QMK. If you have not yet you should read the [Build Environment Setup](build_environment_setup.md) and [Make Instructions](make_instructions.md) guides. ## Can't program on Linux -You will need proper permission to operate a device. For Linux users see udev rules below. -Easy way is to use `sudo` command, if you are not familiar with this command check its manual with `man sudo` or this page on line. +You will need proper permission to operate a device. For Linux users see udev rules below. Easy way is to use `sudo` command, if you are not familiar with this command check its manual with `man sudo` or this page on line. In short when your controller is ATMega32u4, @@ -21,16 +13,16 @@ In short when your controller is ATMega32u4, or just - $ sudo make dfu + $ sudo make --dfu -But to run `make` with root privilege is not good idea. Use former method as possible. +But to run `make` with root privilege is not good idea. Use former method if possible. ## WINAVR is obsolete It is no longer recommended and may cause some problem. -See [Issue #99](https://github.com/tmk/tmk_keyboard/issues/99). +See [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99). ## USB VID and PID -You can use any ID you want with editing `config.h`. Using any presumably unused ID will be no problem in fact except for very least chance of collision with other product. +You can use any ID you want with editing `config.h`. Using any presumably unused ID will be no problem in fact except for very low chance of collision with other product. Most boards in QMK use `0xFEED` as the vendor ID. You should look through other keyboards to make sure you pick a unique Product ID. @@ -41,7 +33,6 @@ You can buy a really unique VID:PID here. I don't think you need this for person - http://www.obdev.at/products/vusb/license.html - http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1 - ## Linux udev rules On Linux you need proper privilege to access device file of MCU, you'll have to use `sudo` when flashing firmware. You can circumvent this with placing these files in `/etc/udev/rules.d/`. diff --git a/docs/faq_debug.md b/docs/faq_debug.md index 9e76ac4094..3f7cfe7477 100644 --- a/docs/faq_debug.md +++ b/docs/faq_debug.md @@ -48,6 +48,45 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" *** # Miscellaneous +## Safety Considerations + +You probably don't want to "brick" your keyboard, making it impossible +to rewrite firmware onto it. Here are some of the parameters to show +what things are (and likely aren't) too risky. + +- If your keyboard map does not include RESET, then, to get into DFU + mode, you will need to press the reset button on the PCB, which + requires unscrewing the bottom. +- Messing with tmk_core / common files might make the keyboard + inoperable +- Too large a .hex file is trouble; `make dfu` will erase the block, + test the size (oops, wrong order!), which errors out, failing to + flash the keyboard, leaving it in DFU mode. + - To this end, note that the maximum .hex file size on Planck is + 7000h (28672 decimal) + +``` +Linking: .build/planck_rev4_cbbrowne.elf [OK] +Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK] + +Size after: + text data bss dec hex filename + 0 22396 0 22396 577c planck_rev4_cbbrowne.hex +``` + + - The above file is of size 22396/577ch, which is less than + 28672/7000h + - As long as you have a suitable alternative .hex file around, you + can retry, loading that one + - Some of the options you might specify in your keyboard's Makefile + consume extra memory; watch out for BOOTMAGIC_ENABLE, + MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE +- DFU tools do /not/ allow you to write into the bootloader (unless + you throw in extra fruitsalad of options), so there is little risk + there. +- EEPROM has around a 100000 write cycle. You shouldn't rewrite the + firmware repeatedly and continually; that'll burn the EEPROM + eventually. ## NKRO Doesn't work First you have to compile frimware with this build option `NKRO_ENABLE` in **Makefile**. diff --git a/docs/faq_general.md b/docs/faq_general.md index efa564743c..fcc40e0a1f 100644 --- a/docs/faq_general.md +++ b/docs/faq_general.md @@ -12,9 +12,9 @@ TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert's](https://github.com/jackhumbert) fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK. -From a technical standpoint QMK builds upon TMK by adding several new features. Most notably QMK has expanded the number of available keycodes and uses these to implement advanced features like `S()`, `LCTL()`, and `MO()`. You can see a complete list of these keycodes in [Quantum Keycodes](quantum_keycodes.html). +From a technical standpoint QMK builds upon TMK by adding several new features. Most notably QMK has expanded the number of available keycodes and uses these to implement advanced features like `S()`, `LCTL()`, and `MO()`. You can see a complete list of these keycodes in [Keycodes](keycodes.md). -From a project and community management standpoint TMK maintains all the officially supported keyboards by himself, with a bit of community support. Separate community maintained forks exist or can be created for other keyboards. Only a few keymaps are provided by default, so users typically don't share keymaps with each other. QMK encourages sharing of both keyboards and keymaps through a centrally managed repository, accepting all pull requests that follows the quality standards. These are mostly community maintained, but the QMK team also helps when necessary. +From a project and community management standpoint TMK maintains all the officially supported keyboards by himself, with a bit of community support. Separate community maintained forks exist or can be created for other keyboards. Only a few keymaps are provided by default, so users typically don't share keymaps with each other. QMK encourages sharing of both keyboards and keymaps through a centrally managed repository, accepting all pull requests that follow the quality standards. These are mostly community maintained, but the QMK team also helps when necessary. Both approaches have their merits and their drawbacks, and code flows freely between TMK and QMK when it makes sense. diff --git a/docs/faq_keymap.md b/docs/faq_keymap.md index 9f54f2213f..eb49a36996 100644 --- a/docs/faq_keymap.md +++ b/docs/faq_keymap.md @@ -1,9 +1,9 @@ # Keymap FAQ -This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.html) first. +This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.md) first. ## What Keycodes Can I Use? -See [Basic Keycodes](keycodes.html) and [Quantum Keycodes](quantum_keycodes.html) for most of the keys you can define. +See [Keycodes](keycodes.md) for an index of keycodes available to you. These link to more extensive documentation when available. Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h). diff --git a/docs/feature_audio.md b/docs/feature_audio.md index 6b476880d1..c142ff69c2 100644 --- a/docs/feature_audio.md +++ b/docs/feature_audio.md @@ -1,5 +1,91 @@ # Audio +Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to the C6 or B5 port (`#define C6_AUDIO` and/or `#define B5_AUDIO`), 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. + +If you add `AUDIO_ENABLE = yes` to your `rules.mk`, there's a couple different sounds that will automatically be enabled without any other configuration: + +``` +STARTUP_SONG // plays when the keyboard starts up (audio.c) +GOODBYE_SONG // plays when you press the RESET key (quantum.c) +AG_NORM_SONG // plays when you press AG_NORM (quantum.c) +AG_SWAP_SONG // plays when you press AG_SWAP (quantum.c) +MUSIC_ON_SONG // plays when music mode is activated (process_music.c) +MUSIC_OFF_SONG // plays when music mode is deactivated (process_music.c) +CHROMATIC_SONG // plays when the chromatic music mode is selected (process_music.c) +GUITAR_SONG // plays when the guitar music mode is selected (process_music.c) +VIOLIN_SONG // plays when the violin music mode is selected (process_music.c) +MAJOR_SONG // plays when the major music mode is selected (process_music.c) +``` + +You can override the default songs by doing something like this in your `config.h`: + +```c +#ifdef AUDIO_ENABLE + #define STARTUP_SONG SONG(STARTUP_SOUND) +#endif +``` + +A full list of sounds can be found in [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) - feel free to add your own to this list! All available notes can be seen in [quantum/audio/musical_notes.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/musical_notes.h). + +To play a custom sound at a particular time, you can define a song like this (near the top of the file): + +```c +float my_song[][2] = SONG(QWERTY_SOUND); +``` + +And then play your song like this: + +```c +PLAY_SONG(my_song); +``` + +Alternatively, you can play it in a loop like this: + +```c +PLAY_LOOP(my_song); +``` + +It's advised that you wrap all audio features in `#ifdef AUDIO_ENABLE` / `#endif` to avoid causing problems when audio isn't built into the keyboard. + +## Music mode + +The music mode maps your columns to a chromatic scale, and your rows to octaves. This works best with ortholinear keyboards, but can be made to work with others. All keycodes less than `0xFF` get blocked, so you won't type while playing notes - if you have special keys/mods, those will still work. A work-around for this is to jump to a different layer with KC_NOs before (or after) enabling music mode. + +Recording is experimental due to some memory issues - if you experience some weird behavior, unplugging/replugging your keyboard will fix things. + +Keycodes available: + +* `MU_ON` - Turn music mode on +* `MU_OFF` - Turn music mode off +* `MU_TOG` - Toggle music mode +* `MU_MOD` - Cycle through the music modes: + * `CHROMATIC_MODE` - Chromatic scale, row changes the octave + * `GUITAR_MODE` - Chromatic scale, but the row changes the string (+5 st) + * `VIOLIN_MODE` - Chromatic scale, but the row changes the string (+7 st) + * `MAJOR_MODE` - Major scale + +In music mode, the following keycodes work differently, and don't pass through: + +* `LCTL` - start a recording +* `LALT` - stop recording/stop playing +* `LGUI` - play recording +* `KC_UP` - speed-up playback +* `KC_DOWN` - slow-down playback + +By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less than `0xFF` are turned into notes, and don't output anything. You can change this by defining this in your `config.h` like this: + + #define MUSIC_MASK keycode != KC_NO + +Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard! + +The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`: + + #define PITCH_STANDARD_A 432.0f + +## 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 + +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. + + ## Bluetooth Keycodes diff --git a/docs/feature_common_shortcuts.md b/docs/feature_common_shortcuts.md index e911420261..a3dde8b670 100644 --- a/docs/feature_common_shortcuts.md +++ b/docs/feature_common_shortcuts.md @@ -13,7 +13,7 @@ This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping i ### Limits of these aliases -Currently, the keycodes able to used with these functions are limited to the [Basic Keycodes](keycodes.html), meaning you can't use keycodes like `KC_TILD`, or anything greater than 0xFF. For a full list of the keycodes able to be used see [Keycodes](keycodes.html). +Currently, the keycodes able to used with these functions are limited to the [Basic Keycodes](keycodes_basic.html), meaning you can't use keycodes like `KC_TILD`, or anything greater than 0xFF. For a full list of the keycodes able to be used see [Basic Keycodes](keycodes_basic.html). ## Switching and toggling layers diff --git a/docs/leader_key.md b/docs/feature_leader_key.md similarity index 100% rename from docs/leader_key.md rename to docs/feature_leader_key.md diff --git a/docs/feature_ps2_mouse.md b/docs/feature_ps2_mouse.md new file mode 100644 index 0000000000..8629b28cff --- /dev/null +++ b/docs/feature_ps2_mouse.md @@ -0,0 +1,238 @@ +## PS/2 Mouse Support + +Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device. + +To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest from a Thinkpad keyboard), identify the function of each pin of the module, and make the necessary circuitry between controller and Trackpoint module. For more information, please refer to [Trackpoint Hardware](https://deskthority.net/wiki/TrackPoint_Hardware) page on Deskthority Wiki. + +There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended). + +### Busywait version + +Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible. + +In rules.mk: + +``` +PS2_MOUSE_ENABLE = yes +PS2_USE_BUSYWAIT = yes +``` + +In your keyboard config.h: + +``` +#ifdef PS2_USE_BUSYWAIT +# define PS2_CLOCK_PORT PORTD +# define PS2_CLOCK_PIN PIND +# define PS2_CLOCK_DDR DDRD +# define PS2_CLOCK_BIT 1 +# define PS2_DATA_PORT PORTD +# define PS2_DATA_PIN PIND +# define PS2_DATA_DDR DDRD +# define PS2_DATA_BIT 2 +#endif +``` + +### Interrupt version + +The following example uses D2 for clock and D5 for data. You can use any INT or PCINT pin for clock, and any pin for data. + +In rules.mk: + +``` +PS2_MOUSE_ENABLE = yes +PS2_USE_INT = yes +``` + +In your keyboard config.h: + +``` +#ifdef PS2_USE_INT +#define PS2_CLOCK_PORT PORTD +#define PS2_CLOCK_PIN PIND +#define PS2_CLOCK_DDR DDRD +#define PS2_CLOCK_BIT 2 +#define PS2_DATA_PORT PORTD +#define PS2_DATA_PIN PIND +#define PS2_DATA_DDR DDRD +#define PS2_DATA_BIT 5 + +#define PS2_INT_INIT() do { \ + EICRA |= ((1< +## RGB Under Glow Mod + +![Planck with RGB Underglow](https://raw.githubusercontent.com/qmk/qmk_firmware/master/keyboards/planck/keymaps/yang/planck-with-rgb-underglow.jpg) + +Here is a quick demo on Youtube (with NPKC KC60) (https://www.youtube.com/watch?v=VKrpPAHlisY). + +For this mod, you need an unused pin wiring to DI of WS2812 strip. After wiring the VCC, GND, and DI, you can enable the underglow in your Makefile. + + RGBLIGHT_ENABLE = yes + +In order to use the underglow animation functions, you need to have `#define RGBLIGHT_ANIMATIONS` in your `config.h`. + +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_ANIMATIONS // 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 `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](https://raw.githubusercontent.com/qmk/qmk_firmware/master/keyboards/planck/keymaps/yang/WS2812-wiring.jpg) + +Please note the USB port can only supply a limited amount of power to the keyboard (500mA by standard, however, modern computer and most usb hubs can provide 700+mA.). According to the data of NeoPixel from Adafruit, 30 WS2812 LEDs require a 5V 1A power supply, LEDs used in this mod should not more than 20. + ## RGB Lighting Keycodes This controls the RGB Lighting functionality. Most keyboards use WS2812 (and compatible) LEDs for underlight or case lighting. diff --git a/docs/features.md b/docs/features.md index 0de6622938..c5965f4c0e 100644 --- a/docs/features.md +++ b/docs/features.md @@ -7,7 +7,7 @@ Steve Losh [described](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) ## The Leader key: A new kind of modifier -Most modifiers have to be held or toggled. But what if you had a key that indicated the start of a sequence? You could press that key and then rapidly press 1-3 more keys to trigger a macro, or enter a special layer, or anything else you might want to do. To learn more about it check out the [Leader Key](leader_key.md) page. +Most modifiers have to be held or toggled. But what if you had a key that indicated the start of a sequence? You could press that key and then rapidly press 1-3 more keys to trigger a macro, or enter a special layer, or anything else you might want to do. To learn more about it check out the [Leader Key](feature_leader_key.md) page. ## Tap Dance: A single key can do 3, 5, or 100 different things diff --git a/docs/getting_started_build_tools.md b/docs/getting_started_build_tools.md index 49ffdaf69f..e46b7f2e53 100644 --- a/docs/getting_started_build_tools.md +++ b/docs/getting_started_build_tools.md @@ -86,7 +86,7 @@ The Toolchain setup is done through the Windows Subsystem for Linux, and the pro * The WSL Git is **not** compatible with the Windows Git, so use the Windows Git Bash or a windows Git GUI for all Git operations * You can edit files either inside WSL or normally using Windows, but note that if you edit makefiles or shell scripts, make sure you are using an editor that saves the files with Unix line endings. Otherwise the compilation might not work. -## Windows (Vista and later) +## Windows (Vista and later) (Deprecated) These are the old instructions for Windows Vista and later. We recommend you use [MSYS2 as outlined above](#windows-with-msys2-recommended). diff --git a/docs/getting_started_make_guide.md b/docs/getting_started_make_guide.md index 299c5785b2..fac801082f 100644 --- a/docs/getting_started_make_guide.md +++ b/docs/getting_started_make_guide.md @@ -21,7 +21,7 @@ As mentioned above, there are some shortcuts, when you are in a: * `keyboard` folder, the command will automatically fill the `` part. So you only need to type `--` * `subproject` folder, it will fill in both `` and `` * `keymap` folder, then `` and `` will be filled in. If you need to specify the `` use the following syntax `-` - * Note in order to support this shortcut, the keymap needs its own Makefile (see the example [here](https://github.com/qmk/qmk_firmware/blob/master/doc/keymap_makefile_example.mk)) + * Note in order to support this shortcut, the keymap needs its own Makefile * `keymap` folder of a `subproject`, then everything except the `` will be filled in The `` means the following @@ -142,7 +142,7 @@ This allows you to interface with a Bluefruit EZ-key to send keycodes wirelessly `AUDIO_ENABLE` -This allows you output audio on the C6 pin (needs abstracting). See the [audio section](#audio-output-from-a-speaker) for more information. +This allows you output audio on the C6 pin (needs abstracting). See the [audio page](feature_audio.md) for more information. `FAUXCLICKY_ENABLE` @@ -150,7 +150,7 @@ Uses buzzer to emulate clicky switches. A cheap imitation of the Cherry blue swi `VARIABLE_TRACE` -Use this to debug changes to variable values, see the [tracing variables](#tracing-variables) section for more information. +Use this to debug changes to variable values, see the [tracing variables](unit_testing.md#tracing-variables) section of the Unit Testing page for more information. `API_SYSEX_ENABLE` diff --git a/docs/hand_wire.md b/docs/hand_wire.md index 9f63095426..263cd59948 100644 --- a/docs/hand_wire.md +++ b/docs/hand_wire.md @@ -298,13 +298,13 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { }; ``` -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. +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 [Keycodes](keycodes.md) - 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](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. +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](getting_started_build_tools.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 `.hex` file in that folder. If you're having trouble with this step, see the end of the guide for the trouble-shooting section. @@ -328,4 +328,4 @@ If you've done all of these things, keep in mind that sometimes you might have h 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) +There are a lot of possibilities inside the firmware - explore [docs.qmk.fm](http://docs.qmk.fm) for a full feature list, and dive into the different project (Planck, Clueboard, 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) diff --git a/docs/basic_how_keyboards_work.md b/docs/how_keyboards_work.md similarity index 100% rename from docs/basic_how_keyboards_work.md rename to docs/how_keyboards_work.md diff --git a/docs/keycodes.md b/docs/keycodes.md index b9e1f42f77..c601ad4ced 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -66,8 +66,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |`KC_X`|||| |`KC_Y`|||| |`KC_Z`|||| -|Long Name|Short Name|Description| -|---------|----------|-----------| |`KC_ENTER`|`KC_ENT`|`Return (ENTER)`| |`KC_ESCAPE`|`KC_ESC`|`ESCAPE`| |`KC_BSPACE`|`KC_BSPC`|`DELETE (Backspace)`| @@ -90,8 +88,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |`KC_DOT`||`.` and `>`| |`KC_SLASH`|`KC_SLSH`|`/` and `?`| |`KC_CAPSLOCK`|`KC_CAPS`|Caps Lock| -|Long Name|Short Name|Description| -|---------|----------|-----------| |`KC_LCTRL`|`KC_LCTL`|LeftControl| |`KC_LSHIFT`|`KC_LSFT`|LeftShift| |`KC_LALT`||LeftAlt| @@ -105,8 +101,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |`KC_LOCKING_SCROLL`|`KC_LSCR`|Locking Scroll Lock| |`KC_INT4`|`KC_HENK`|JIS Henken| |`KC_INT5`|`KC_MHEN`|JIS Muhenken| -|Long Name|Short Name|Description| -|---------|----------|-----------| |`KC_PSCREEN`|`KC_PSCR`|PrintScreen| |`KC_SCROLLLOCK`|`KC_SLCK`|Scroll Lock| |`KC_PAUSE`|`KC_PAUS`|Pause| @@ -157,8 +151,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |`KC_WWW_STOP`|`KC_WSTP`|| |`KC_WWW_REFRESH`|`KC_WREF`|| |`KC_WWW_FAVORITES`|`KC_WFAV`|| -|Long Name|Short Name|Description| -|---------|----------|-----------| |`KC_STOP`||Stop| |`KC__MUTE`||Mute| |`KC__VOLUP`||Volume Up| @@ -173,8 +165,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |`KC_MEDIA_STOP`|`KC_MSTP`|| |`KC_MEDIA_PLAY_PAUSE`|`KC_MPLY`|| |`KC_MEDIA_SELECT`|`KC_MSEL`|| -|Long Name|Short Name|Description| -|---------|----------|-----------| |`KC_NUMLOCK`|`KC_NLCK`|Keypad Num Lock and Clear| |`KC_KP_SLASH`|`KC_PSLS`|Keypad /| |`KC_KP_ASTERISK`|`KC_PAST`|Keypad *| @@ -195,12 +185,8 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |`KC_KP_EQUAL`|`KC_PEQL`|Keypad =| |`KC_KP_COMMA`|`KC_PCMM`|Keypad Comma| |`KC_KP_EQUAL_AS400`||Keypad Equal Sign| -|Long Name|Short Name|Description| -|---------|----------|-----------| |`KC_NO`||Ignore this key. (NOOP) | |`KC_TRNS`||Make this key transparent to find the key on a lower layer.| -|Long Name|Short Name|Description| -|---------|----------|-----------| |[`KC_MS_UP`](mouse_keys.md)|`KC_MS_U`|Mouse Cursor Up| |[`KC_MS_DOWN`](mouse_keys.md)|`KC_MS_D`|Mouse Cursor Down| |[`KC_MS_LEFT`](mouse_keys.md)|`KC_MS_L`|Mouse Cursor Left| @@ -217,19 +203,15 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |[`KC_MS_ACCEL0`](mouse_keys.md)|`KC_ACL0`|Mouse Acceleration 0| |[`KC_MS_ACCEL1`](mouse_keys.md)|`KC_ACL1`|Mouse Acceleration 1| |[`KC_MS_ACCEL2`](mouse_keys.md)|`KC_ACL2`|Mouse Acceleration 2| -|Long Name|Short Name|Description| -|---------|----------|-----------| |[`RESET`](quantum_keycodes.md#qmk-keycodes)||Put the keyboard into DFU mode for flashing| |[`DEBUG`](quantum_keycodes.md#qmk-keycodes)||Toggles debug mode| |[`KC_GESC`](quantum_keycodes.md#qmk-keycodes)|`GRAVE_ESC`|Acts as escape when pressed normally but when pressed with Shift or GUI will send a `~`| |[`KC_LSPO`](quantum_keycodes.md#qmk-keycodes)||Left shift when held, open paranthesis when tapped| |[`KC_RSPC`](quantum_keycodes.md#qmk-keycodes)||Right shift when held, close paranthesis when tapped| -|[`KC_LEAD`](quantum_keycodes.md#qmk-keycodes)||The [leader key](leader_key.md)| +|[`KC_LEAD`](feature_leader_key.md)||The leader key| |[`FUNC(n)`](quantum_keycodes.md#qmk-keycodes)|`F(n)`|Call `fn_action(n)`| |[`M(n)`](quantum_keycodes.md#qmk-keycodes)||to call macro n| |[`MACROTAP(n)`](quantum_keycodes.md#qmk-keycodes)||to macro-tap n idk FIXME`| -|Long Name|Short Name|Description| -|---------|----------|-----------| |[`MAGIC_SWAP_CONTROL_CAPSLOCK`](feature_bootmagic.md)||Swap Capslock and Left Control| |[`MAGIC_CAPSLOCK_TO_CONTROL`](feature_bootmagic.md)||Treat Capslock like a Control Key| |[`MAGIC_SWAP_LALT_LGUI`](feature_bootmagic.md)||Swap the left Alt and GUI keys| @@ -249,8 +231,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |[`MAGIC_UNHOST_NKRO`](feature_bootmagic.md)||Force NKRO off| |[`MAGIC_UNSWAP_ALT_GUI`/`AG_NORM`](feature_bootmagic.md)||Disable the Alt/GUI switching| |[`MAGIC_TOGGLE_NKRO`](feature_bootmagic.md)||Turn NKRO on or off| -|Long Name|Short Name|Description| -|---------|----------|-----------| |[`BL_x`](feature_backlight.md)||Set a specific backlight level between 0-9| |[`BL_ON`](feature_backlight.md)||An alias for `BL_9`| |[`BL_OFF`](feature_backlight.md)||An alias for `BL_0`| @@ -258,8 +238,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |[`BL_INC`](feature_backlight.md)||Turn the backlight level up by 1| |[`BL_TOGG`](feature_backlight.md)||Toggle the backlight on or off| |[`BL_STEP`](feature_backlight.md)||Step through backlight levels, wrapping around to 0 when you reach the top.| -|Long Name|Short Name|Description| -|---------|----------|-----------| |[`RGB_TOG`](feature_rgblight.md)||toggle on/off| |[`RGB_MOD`](feature_rgblight.md)||cycle through modes| |[`RGB_HUI`](feature_rgblight.md)||hue increase| @@ -268,17 +246,11 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |[`RGB_SAD`](feature_rgblight.md)||saturation decrease| |[`RGB_VAI`](feature_rgblight.md)||value increase| |[`RGB_VAD`](feature_rgblight.md)||value decrease| -|Long Name|Short Name|Description| -|---------|----------|-----------| |[`PRINT_ON`](feature_thermal_printer.md)||Start printing everything the user types| |[`PRINT_OFF`](feature_thermal_printer.md)||Stop printing everything the user types| -|Long Name|Short Name|Description| -|---------|----------|-----------| |[`OUT_AUTO`](feature_bluetooth.md)||auto mode| |[`OUT_USB`](feature_bluetooth.md)||usb only| |[`OUT_BT`](feature_bluetooth.md)||bluetooth (when `BLUETOOTH_ENABLE`)| -|Long Name|Short Name|Description| -|---------|----------|-----------| |[`KC_HYPR`](quantum_keycodes.md#modifiers)||Hold down LCTL + LSFT + LALT + LGUI`| |[`KC_MEH`](quantum_keycodes.md#modifiers)||Hold down LCTL + LSFT + LALT`| |[`LCTL(kc)`](quantum_keycodes.md#modifiers)||`LCTL` + `kc`| @@ -295,8 +267,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |[`ALTG(kc)`](quantum_keycodes.md#modifiers)||`RCTL` + `RALT` + `kc`| |[`SCMD(kc)`](quantum_keycodes.md#modifiers)|[`SWIN(kc)`](quantum_keycodes.md#modifiers)|`LGUI` + `LSFT` + `kc`| |[`LCA(kc)`](quantum_keycodes.md#modifiers)||`LCTL` + `LALT` + `kc`| -|Long Name|Short Name|Description| -|---------|----------|-----------| |[`CTL_T(kc)`](quantum_keycodes.md#mod-tap-keys)|[`LCTL_T(kc)`](quantum_keycodes.md#mod-tap-keys)|`LCTL` when held, `kc` when tapped| |[`RCTL_T(kc)`](quantum_keycodes.md#mod-tap-keys)||[`RCTL` when held, `kc` when tapped| |[`SFT_T(kc)`](quantum_keycodes.md#mod-tap-keys)|[`LSFT_T(kc)`](quantum_keycodes.md#mod-tap-keys)|`LSFT` when held, `kc` when tapped| @@ -312,8 +282,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |[`ALL_T(kc)`](quantum_keycodes.md#mod-tap-keys)||`LCTL` + `LSFT` + `LALT` + `LGUI` when held, `kc` when tapped [more info](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)| |[`SCMD_T(kc)`](quantum_keycodes.md#mod-tap-keys)|[`SWIN_T(kc)`](quantum_keycodes.md#mod-tap-keys)|`LGUI` + `LSFT` when held, `kc` when tapped| |[`LCA_T(kc)`](quantum_keycodes.md#mod-tap-keys)||`LCTL` + `LALT` when held, `kc` when tapped| -|Short Name|Long Name|Description| -|----------|---------|-----------| |[`KC_TILD`](keycodes_us_ansi_shifted.md)|`KC_TILDE`|tilde `~`| |[`KC_EXLM`](keycodes_us_ansi_shifted.md)|`KC_EXCLAIM`|exclamation mark `!`| |[`KC_AT`](keycodes_us_ansi_shifted.md)||at sign `@`| @@ -335,17 +303,13 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |[`KC_PIPE`](keycodes_us_ansi_shifted.md)||pipe `\|`| |[`KC_QUES`](keycodes_us_ansi_shifted.md)|`KC_QUESTION`|question mark `?`| |[`KC_DQT`/`KC_DQUO`](keycodes_us_ansi_shifted.md)|`KC_DOUBLE_QUOTE`|double quote `"`| -|Long Name|Short Name|Description| -|---------|----------|-----------| -|[`LT(layer, kc)`](feature_common_shortcuts.md#switching-and-toggling-layers)||turn on layer (0-15) when held, kc ([basic keycodes](basic_keycodes.md)) when tapped| +|[`LT(layer, kc)`](feature_common_shortcuts.md#switching-and-toggling-layers)||turn on layer (0-15) when held, kc ([basic keycodes](keycodes_basic.md)) when tapped| |[`TO(layer)`](feature_common_shortcuts.md#switching-and-toggling-layers)||turn on layer when depressed| |[`MO(layer)`](feature_common_shortcuts.md#switching-and-toggling-layers)||momentarily turn on layer when depressed (requires `KC_TRNS` on destination layer)| |[`DF(layer)`](feature_common_shortcuts.md#switching-and-toggling-layers)||sets the base (default) layer| |[`TG(layer)`](feature_common_shortcuts.md#switching-and-toggling-layers)||toggle layer on/off| -|[`TT(layer)](feature_common_shortcuts.md#switching-and-toggling-layers)`||tap toggle? idk FIXME`| +|[`TT(layer)`](feature_common_shortcuts.md#switching-and-toggling-layers)||tap toggle? idk FIXME`| |[`OSM(mod)`](quantum_keycodes.md#one-shot-keys)||hold mod for one keypress| |[`OSL(layer)`](quantum_keycodes.md#one-shot-keys)||switch to layer for one keypress| -|Long Name|Short Name|Description| -|---------|----------|-----------| |[`UNICODE(n)`](unicode.md)|[`UC(n)`](unicode.md)|if `UNICODE_ENABLE`, this will send characters up to `0x7FFF`| |[`X(n)`](unicode.md)||if `UNICODEMAP_ENABLE`, also sends unicode via a different method| diff --git a/docs/basic_keycodes.md b/docs/keycodes_basic.md similarity index 100% rename from docs/basic_keycodes.md rename to docs/keycodes_basic.md diff --git a/docs/keymap.md b/docs/keymap.md index 53b17f4019..170fdaed7d 100644 --- a/docs/keymap.md +++ b/docs/keymap.md @@ -215,8 +215,7 @@ To actually handle the keypress event we define an `action_function()`. This fun This should have given you a basic overview for creating your own keymap. For more details see the following resources: -* https://github.com/qmk/qmk_firmware/wiki/Keycodes -* https://github.com/qmk/qmk_firmware/wiki/FAQ-Keymap -* https://github.com/qmk/qmk_firmware/wiki/Keymap-examples +* [Keycodes](keycodes.md) +* [Keymap FAQ](faq_keymap.md) -We are actively working to improve these docs. If you have suggestions for how they could be made better please [file an issue](https://github.com/qmk/qmk_firmware/issues/new)! \ No newline at end of file +We are actively working to improve these docs. If you have suggestions for how they could be made better please [file an issue](https://github.com/qmk/qmk_firmware/issues/new)! diff --git a/docs/macros.md b/docs/macros.md index 6b128541b8..c7a9b2e7a6 100644 --- a/docs/macros.md +++ b/docs/macros.md @@ -24,7 +24,7 @@ const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { }; ``` -This defines two macros which will be run when the key they are assigned to is pressed. If you'd like them to run when the release is released instead you can change the if statement: +This defines two macros which will be run when the key they are assigned to is pressed. If instead you'd like them to run when the key is released you can change the if statement: ```c if (!record->event.pressed) { diff --git a/docs/modding_your_keyboard.md b/docs/modding_your_keyboard.md deleted file mode 100644 index a58fbd52b2..0000000000 --- a/docs/modding_your_keyboard.md +++ /dev/null @@ -1,403 +0,0 @@ - -## Audio output from a speaker - -Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to the C6 or B5 port (`#define C6_AUDIO` and/or `#define B5_AUDIO`), 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. - -If you add `AUDIO_ENABLE = yes` to your `rules.mk`, there's a couple different sounds that will automatically be enabled without any other configuration: - -``` -STARTUP_SONG // plays when the keyboard starts up (audio.c) -GOODBYE_SONG // plays when you press the RESET key (quantum.c) -AG_NORM_SONG // plays when you press AG_NORM (quantum.c) -AG_SWAP_SONG // plays when you press AG_SWAP (quantum.c) -MUSIC_ON_SONG // plays when music mode is activated (process_music.c) -MUSIC_OFF_SONG // plays when music mode is deactivated (process_music.c) -CHROMATIC_SONG // plays when the chromatic music mode is selected (process_music.c) -GUITAR_SONG // plays when the guitar music mode is selected (process_music.c) -VIOLIN_SONG // plays when the violin music mode is selected (process_music.c) -MAJOR_SONG // plays when the major music mode is selected (process_music.c) -``` - -You can override the default songs by doing something like this in your `config.h`: - -```c -#ifdef AUDIO_ENABLE - #define STARTUP_SONG SONG(STARTUP_SOUND) -#endif -``` - -A full list of sounds can be found in [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) - feel free to add your own to this list! All available notes can be seen in [quantum/audio/musical_notes.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/musical_notes.h). - -To play a custom sound at a particular time, you can define a song like this (near the top of the file): - -```c -float my_song[][2] = SONG(QWERTY_SOUND); -``` - -And then play your song like this: - -```c -PLAY_SONG(my_song); -``` - -Alternatively, you can play it in a loop like this: - -```c -PLAY_LOOP(my_song); -``` - -It's advised that you wrap all audio features in `#ifdef AUDIO_ENABLE` / `#endif` to avoid causing problems when audio isn't built into the keyboard. - -## Music mode - -The music mode maps your columns to a chromatic scale, and your rows to octaves. This works best with ortholinear keyboards, but can be made to work with others. All keycodes less than `0xFF` get blocked, so you won't type while playing notes - if you have special keys/mods, those will still work. A work-around for this is to jump to a different layer with KC_NOs before (or after) enabling music mode. - -Recording is experimental due to some memory issues - if you experience some weird behavior, unplugging/replugging your keyboard will fix things. - -Keycodes available: - -* `MU_ON` - Turn music mode on -* `MU_OFF` - Turn music mode off -* `MU_TOG` - Toggle music mode -* `MU_MOD` - Cycle through the music modes: - * `CHROMATIC_MODE` - Chromatic scale, row changes the octave - * `GUITAR_MODE` - Chromatic scale, but the row changes the string (+5 st) - * `VIOLIN_MODE` - Chromatic scale, but the row changes the string (+7 st) - * `MAJOR_MODE` - Major scale - -In music mode, the following keycodes work differently, and don't pass through: - -* `LCTL` - start a recording -* `LALT` - stop recording/stop playing -* `LGUI` - play recording -* `KC_UP` - speed-up playback -* `KC_DOWN` - slow-down playback - -By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less than `0xFF` are turned into notes, and don't output anything. You can change this by defining this in your `config.h` like this: - - #define MUSIC_MASK keycode != KC_NO - -Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard! - -The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`: - - #define PITCH_STANDARD_A 432.0f - -## 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 - -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. - -## RGB Under Glow Mod - -![Planck with RGB Underglow](https://raw.githubusercontent.com/qmk/qmk_firmware/master/keyboards/planck/keymaps/yang/planck-with-rgb-underglow.jpg) - -Here is a quick demo on Youtube (with NPKC KC60) (https://www.youtube.com/watch?v=VKrpPAHlisY). - -For this mod, you need an unused pin wiring to DI of WS2812 strip. After wiring the VCC, GND, and DI, you can enable the underglow in your Makefile. - - RGBLIGHT_ENABLE = yes - -In order to use the underglow animation functions, you need to have `#define RGBLIGHT_ANIMATIONS` in your `config.h`. - -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_ANIMATIONS // 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 `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](https://raw.githubusercontent.com/qmk/qmk_firmware/master/keyboards/planck/keymaps/yang/WS2812-wiring.jpg) - -Please note the USB port can only supply a limited amount of power to the keyboard (500mA by standard, however, modern computer and most usb hubs can provide 700+mA.). According to the data of NeoPixel from Adafruit, 30 WS2812 LEDs require a 5V 1A power supply, LEDs used in this mod should not more than 20. - -## PS/2 Mouse Support - -Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device. - -To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest from a Thinkpad keyboard), identify the function of each pin of the module, and make the necessary circuitry between controller and Trackpoint module. For more information, please refer to [Trackpoint Hardware](https://deskthority.net/wiki/TrackPoint_Hardware) page on Deskthority Wiki. - -There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended). - -### Busywait version - -Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible. - -In rules.mk: - -``` -PS2_MOUSE_ENABLE = yes -PS2_USE_BUSYWAIT = yes -``` - -In your keyboard config.h: - -``` -#ifdef PS2_USE_BUSYWAIT -# define PS2_CLOCK_PORT PORTD -# define PS2_CLOCK_PIN PIND -# define PS2_CLOCK_DDR DDRD -# define PS2_CLOCK_BIT 1 -# define PS2_DATA_PORT PORTD -# define PS2_DATA_PIN PIND -# define PS2_DATA_DDR DDRD -# define PS2_DATA_BIT 2 -#endif -``` - -### Interrupt version - -The following example uses D2 for clock and D5 for data. You can use any INT or PCINT pin for clock, and any pin for data. - -In rules.mk: - -``` -PS2_MOUSE_ENABLE = yes -PS2_USE_INT = yes -``` - -In your keyboard config.h: - -``` -#ifdef PS2_USE_INT -#define PS2_CLOCK_PORT PORTD -#define PS2_CLOCK_PIN PIND -#define PS2_CLOCK_DDR DDRD -#define PS2_CLOCK_BIT 2 -#define PS2_DATA_PORT PORTD -#define PS2_DATA_PIN PIND -#define PS2_DATA_DDR DDRD -#define PS2_DATA_BIT 5 - -#define PS2_INT_INIT() do { \ - EICRA |= ((1</readme.md` @@ -42,7 +42,7 @@ This is where you'll describe your keyboard - please write as much as you can ab ## `/keyboards//.c` -This is where all of the custom logic for your keyboard goes - you may not need to put anything in this file, since a lot of things are configured automatically. All of the `*_kb()` functions are defined here. If you modify them, remember to keep the calls to `*_user()`, or things in the keymaps might not work. You can read more about the functions [here](#custom-quantum-functions-for-keyboards-and-keymaps) +This is where all of the custom logic for your keyboard goes - you may not need to put anything in this file, since a lot of things are configured automatically. All of the `*_kb()` functions are defined here. If you modify them, remember to keep the calls to `*_user()`, or things in the keymaps might not work. You can read more about the functions [here](custom_quantum_functions.md). ## `/keyboards//.h` diff --git a/docs/quantum_keycodes.md b/docs/quantum_keycodes.md index 2e17ae4b7b..a5160bf94a 100644 --- a/docs/quantum_keycodes.md +++ b/docs/quantum_keycodes.md @@ -15,8 +15,8 @@ On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are |`KC_GESC`/`GRAVE_ESC`|Acts as escape when pressed normally but when pressed with Shift or GUI will send a ```| |`KC_LSPO`|Left shift when held, open paranthesis when tapped| |`KC_RSPC`|Right shift when held, close paranthesis when tapped| -|`KC_LEAD`|The [leader key](leader_key.md)| +|`KC_LEAD`|The [leader key](feature_leader_key.md)| |`KC_LOCK`|The [lock key](key_lock.md)| -|`FUNC(n)`/`F(n)`|Call `fn_action(n)`| +|`FUNC(n)`/`F(n)`|Call `fn_action(n)` (deprecated)| |`M(n)`|to call macro n| |`MACROTAP(n)`|to macro-tap n idk FIXME| diff --git a/docs/understanding_qmk.md b/docs/understanding_qmk.md index 28927f0eff..2ac4f30365 100644 --- a/docs/understanding_qmk.md +++ b/docs/understanding_qmk.md @@ -3,7 +3,7 @@ This document attempts to explain how the QMK firmware works from a very high level. It assumes you understand basic programming concepts but does not (except where needed to demonstrate) assume familiarity with C. It assumes that you have a basic understanding of the following documents: * [QMK Overview](qmk_overview.md) -* [How Keyboards Work](basic_how_keyboards_work.md) +* [How Keyboards Work](how_keyboards_work.md) * [FAQ](faq.md) ## Startup