diff options
Diffstat (limited to 'docs')
27 files changed, 458 insertions, 487 deletions
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_<my_cool_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.<variant>] [KEYMAP=...] clean - $ make [-f Makefile.<variant>] [KEYMAP=...] - $ make [-f Makefile.<variant>] [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 <keyboard>-<keymap>-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. + <!-- FIXME: this formatting needs work ## Audio diff --git a/docs/feature_bluetooth.md b/docs/feature_bluetooth.md index d586278579..79a54208ea 100644 --- a/docs/feature_bluetooth.md +++ b/docs/feature_bluetooth.md @@ -1,6 +1,10 @@ # Bluetooth -<!-- FIXME: Document bluetooth support. --> +## 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. + +<!-- FIXME: Document bluetooth support more completely. --> ## 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 index bf4d5456d1..bf4d5456d1 100644 --- a/docs/leader_key.md +++ b/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<<ISC21) | \ + (0<<ISC20)); \ +} while (0) +#define PS2_INT_ON() do { \ + EIMSK |= (1<<INT2); \ +} while (0) +#define PS2_INT_OFF() do { \ + EIMSK &= ~(1<<INT2); \ +} while (0) +#define PS2_INT_VECT INT2_vect +#endif +``` + +### USART version + +To use USART on the ATMega32u4, you have to use PD5 for clock and PD2 for data. If one of those are unavailable, you need to use interrupt version. + +In rules.mk: + +``` +PS2_MOUSE_ENABLE = yes +PS2_USE_USART = yes +``` + +In your keyboard config.h: + +``` +#ifdef PS2_USE_USART +#define PS2_CLOCK_PORT PORTD +#define PS2_CLOCK_PIN PIND +#define PS2_CLOCK_DDR DDRD +#define PS2_CLOCK_BIT 5 +#define PS2_DATA_PORT PORTD +#define PS2_DATA_PIN PIND +#define PS2_DATA_DDR DDRD +#define PS2_DATA_BIT 2 + +/* synchronous, odd parity, 1-bit stop, 8-bit data, sample at falling edge */ +/* set DDR of CLOCK as input to be slave */ +#define PS2_USART_INIT() do { \ + PS2_CLOCK_DDR &= ~(1<<PS2_CLOCK_BIT); \ + PS2_DATA_DDR &= ~(1<<PS2_DATA_BIT); \ + UCSR1C = ((1 << UMSEL10) | \ + (3 << UPM10) | \ + (0 << USBS1) | \ + (3 << UCSZ10) | \ + (0 << UCPOL1)); \ + UCSR1A = 0; \ + UBRR1H = 0; \ + UBRR1L = 0; \ +} while (0) +#define PS2_USART_RX_INT_ON() do { \ + UCSR1B = ((1 << RXCIE1) | \ + (1 << RXEN1)); \ +} while (0) +#define PS2_USART_RX_POLL_ON() do { \ + UCSR1B = (1 << RXEN1); \ +} while (0) +#define PS2_USART_OFF() do { \ + UCSR1C = 0; \ + UCSR1B &= ~((1 << RXEN1) | \ + (1 << TXEN1)); \ +} while (0) +#define PS2_USART_RX_READY (UCSR1A & (1<<RXC1)) +#define PS2_USART_RX_DATA UDR1 +#define PS2_USART_ERROR (UCSR1A & ((1<<FE1) | (1<<DOR1) | (1<<UPE1))) +#define PS2_USART_RX_VECT USART1_RX_vect +#endif +``` + +### Additional Settings + +#### PS/2 mouse features + +These enable settings supported by the PS/2 mouse protocol: http://www.computer-engineering.org/ps2mouse/ + +``` +/* Use remote mode instead of the default stream mode (see link) */ +#define PS2_MOUSE_USE_REMOTE_MODE + +/* Enable the scrollwheel or scroll gesture on your mouse or touchpad */ +#define PS2_MOUSE_ENABLE_SCROLLING + +/* Some mice will need a scroll mask to be configured. The default is 0xFF. */ +#define PS2_MOUSE_SCROLL_MASK 0x0F + +/* Applies a transformation to the movement before sending to the host (see link) */ +#define PS2_MOUSE_USE_2_1_SCALING + +/* The time to wait after initializing the ps2 host */ +#define PS2_MOUSE_INIT_DELAY 1000 /* Default */ +``` + +You can also call the following functions from ps2_mouse.h + +``` +void ps2_mouse_disable_data_reporting(void); + +void ps2_mouse_enable_data_reporting(void); + +void ps2_mouse_set_remote_mode(void); + +void ps2_mouse_set_stream_mode(void); + +void ps2_mouse_set_scaling_2_1(void); + +void ps2_mouse_set_scaling_1_1(void); + +void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution); + +void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate); +``` + +#### Fine control + +Use the following defines to change the sensitivity and speed of the mouse. +Note: you can also use `ps2_mouse_set_resolution` for the same effect (not supported on most touchpads). + +``` +#define PS2_MOUSE_X_MULTIPLIER 3 +#define PS2_MOUSE_Y_MULTIPLIER 3 +#define PS2_MOUSE_V_MULTIPLIER 1 +``` + +#### Scroll button + +If you're using a trackpoint, you will likely want to be able to use it for scrolling. +Its possible to enable a "scroll button/s" that when pressed will cause the mouse to scroll instead of moving. +To enable the feature, you must set a scroll button mask as follows: + +``` +#define PS2_MOUSE_SCROLL_BTN_MASK (1<<PS2_MOUSE_BUTTON_MIDDLE) /* Default */ +``` + +To disable the scroll button feature: + +``` +#define PS2_MOUSE_SCROLL_BTN_MASK 0 +``` + +The available buttons are: + +``` +#define PS2_MOUSE_BTN_LEFT 0 +#define PS2_MOUSE_BTN_RIGHT 1 +#define PS2_MOUSE_BTN_MIDDLE 2 +``` + +You can also combine buttons in the mask by `|`ing them together. + +Once you've configured your scroll button mask, you must configure the scroll button send interval. +This is the interval before which if the scroll buttons were released they would be sent to the host. +After this interval, they will cause the mouse to scroll and will not be sent. + +``` +#define PS2_MOUSE_SCROLL_BTN_SEND 300 /* Default */ +``` + +To disable sending the scroll buttons: +``` +#define PS2_MOUSE_SCROLL_BTN_SEND 0 +``` + +Fine control over the scrolling is supported with the following defines: + +``` +#define PS2_MOUSE_SCROLL_DIVISOR_H 2 +#define PS2_MOUSE_SCROLL_DIVISOR_V 2 +``` + +#### Debug settings + +To debug the mouse, add `debug_mouse = true` or enable via bootmagic. + +``` +/* To debug the mouse reports */ +#define PS2_MOUSE_DEBUG_HID +#define PS2_MOUSE_DEBUG_RAW +``` diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 8bbe06b971..7f12155cb7 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -2,6 +2,37 @@ <!-- FIXME: Describe how to use RGB Lighting here. --> +## RGB Under Glow Mod + + + +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 + + + +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 ` |