From fe113ebad56e758d635724dc35f2a4e26a6985ee Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Fri, 21 Jul 2017 01:02:32 -0400 Subject: start updating audio docs --- docs/modding_your_keyboard.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/modding_your_keyboard.md') diff --git a/docs/modding_your_keyboard.md b/docs/modding_your_keyboard.md index 44e6e6e72a..30ff4f91af 100644 --- a/docs/modding_your_keyboard.md +++ b/docs/modding_your_keyboard.md @@ -41,7 +41,8 @@ Wherein we bind predefined songs (from [quantum/audio/song_list.h](https://githu So now you have something called `tone_plover` for example. How do you make it play the Plover tune, then? If you look further down the keymap, you'll see this: ``` -PLAY_NOTE_ARRAY(tone_plover, false, 0); // Signature is: Song name, repeat, rest style +PLAY_NOTE_ARRAY(tone_plover, false, LEGATO); // song name, repeat, rest style +PLAY_SONG(tone_plover); // song name (repeat is false, rest is STACCATO) ``` This is inside one of the macros. So when that macro executes, your keyboard plays that particular chime. -- cgit v1.2.3 From f407f3e8deea433ae4bca61f17d8ed8ed208bb27 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Fri, 21 Jul 2017 13:18:36 -0400 Subject: remove unneccesary headers --- docs/modding_your_keyboard.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) (limited to 'docs/modding_your_keyboard.md') diff --git a/docs/modding_your_keyboard.md b/docs/modding_your_keyboard.md index 30ff4f91af..29b0b3b0fb 100644 --- a/docs/modding_your_keyboard.md +++ b/docs/modding_your_keyboard.md @@ -1,12 +1,23 @@ ## 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 or B5 port (`#define C6_AUDIO` and `#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. +Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any 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. -The audio code lives in [quantum/audio/audio.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/audio.h) and in the other files in the audio directory. It's enabled by default on the Planck [stock keymap](https://github.com/qmk/qmk_firmware/blob/master/keyboards/planck/keymaps/default/keymap.c). Here are the important bits: +If you add this to your `rules.mk`: ``` -#include "audio.h" +AUDIO_ENABLE = yes +``` + +there's a couple different sounds that will automatically be enabled without any other configuration: + + +If you want to implement something custom, you can + +``` +#ifdef AUDIO_ENABLE + #include "audio.h" +#endif ``` Then, lower down the file: @@ -41,14 +52,11 @@ Wherein we bind predefined songs (from [quantum/audio/song_list.h](https://githu So now you have something called `tone_plover` for example. How do you make it play the Plover tune, then? If you look further down the keymap, you'll see this: ``` -PLAY_NOTE_ARRAY(tone_plover, false, LEGATO); // song name, repeat, rest style -PLAY_SONG(tone_plover); // song name (repeat is false, rest is STACCATO) +PLAY_SONG(tone_plover); // song name ``` This is inside one of the macros. So when that macro executes, your keyboard plays that particular chime. -"Rest style" in the method signature above (the last parameter) specifies if there's a rest (a moment of silence) between the notes. - ## 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. -- cgit v1.2.3 From 9abbbe70890ee0a0c619411c76a2c7b82b1b49d5 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Fri, 21 Jul 2017 13:30:57 -0400 Subject: update audio documentation --- docs/modding_your_keyboard.md | 59 +++++++++++++++++-------------------------- 1 file changed, 23 insertions(+), 36 deletions(-) (limited to 'docs/modding_your_keyboard.md') diff --git a/docs/modding_your_keyboard.md b/docs/modding_your_keyboard.md index 29b0b3b0fb..ab40bdf93c 100644 --- a/docs/modding_your_keyboard.md +++ b/docs/modding_your_keyboard.md @@ -1,61 +1,48 @@ ## 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 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. +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 this to your `rules.mk`: +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: ``` -AUDIO_ENABLE = yes +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) ``` -there's a couple different sounds that will automatically be enabled without any other configuration: +You can override the default songs by doing something like this in your `config.h`: - -If you want to implement something custom, you can - -``` +```c #ifdef AUDIO_ENABLE - #include "audio.h" + #define STARTUP_SONG SONG(STARTUP_SOUND) #endif ``` -Then, lower down the file: - -``` -float tone_startup[][2] = { - ED_NOTE(_E7 ), - E__NOTE(_CS7), - E__NOTE(_E6 ), - E__NOTE(_A6 ), - M__NOTE(_CS7, 20) -}; -``` - -This is how you write a song. Each of these lines is a note, so we have a little ditty composed of five notes here. +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). -Then, we have this chunk: +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); ``` -float tone_qwerty[][2] = SONG(QWERTY_SOUND); -float tone_dvorak[][2] = SONG(DVORAK_SOUND); -float tone_colemak[][2] = SONG(COLEMAK_SOUND); -float tone_plover[][2] = SONG(PLOVER_SOUND); -float tone_plover_gb[][2] = SONG(PLOVER_GOODBYE_SOUND); -float music_scale[][2] = SONG(MUSIC_SCALE_SOUND); -float goodbye[][2] = SONG(GOODBYE_SOUND); -``` +And then play your song like this: -Wherein we bind predefined songs (from [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h)) into named variables. This is one optimization that helps save on memory: These songs only take up memory when you reference them in your keymap, because they're essentially all preprocessor directives. +```c +PLAY_SONG(my_song); +``` -So now you have something called `tone_plover` for example. How do you make it play the Plover tune, then? If you look further down the keymap, you'll see this: +Alternatively, you can play it in a loop like this: -``` -PLAY_SONG(tone_plover); // song name +```c +PLAY_LOOP(my_song); ``` -This is inside one of the macros. So when that macro executes, your keyboard plays that particular chime. +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 -- cgit v1.2.3 From 6bdf7482b151446c8b4e442de6fadb1395dc4dae Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Sat, 22 Jul 2017 17:12:02 -0400 Subject: update audio/music documentation --- docs/modding_your_keyboard.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs/modding_your_keyboard.md') diff --git a/docs/modding_your_keyboard.md b/docs/modding_your_keyboard.md index ab40bdf93c..5613bf5253 100644 --- a/docs/modding_your_keyboard.md +++ b/docs/modding_your_keyboard.md @@ -12,6 +12,10 @@ 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`: @@ -55,6 +59,11 @@ 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: @@ -64,6 +73,12 @@ In music mode, the following keycodes work differently, and don't pass through: * `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! + ## MIDI functionalty This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile. -- cgit v1.2.3 From cefc09ae7dd88cd6b92412881888404da1abdfcb Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Mon, 24 Jul 2017 12:44:03 -0400 Subject: adds option for alt pitch standards --- docs/modding_your_keyboard.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/modding_your_keyboard.md') diff --git a/docs/modding_your_keyboard.md b/docs/modding_your_keyboard.md index 5613bf5253..a58fbd52b2 100644 --- a/docs/modding_your_keyboard.md +++ b/docs/modding_your_keyboard.md @@ -79,6 +79,10 @@ By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less th 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. -- cgit v1.2.3 From 9d1a08e38ac9937cff4e61abfd0acc26ad5fdf4a Mon Sep 17 00:00:00 2001 From: skullY Date: Sun, 6 Aug 2017 20:57:57 -0700 Subject: Doc updates from going through every file --- docs/modding_your_keyboard.md | 403 ------------------------------------------ 1 file changed, 403 deletions(-) delete mode 100644 docs/modding_your_keyboard.md (limited to 'docs/modding_your_keyboard.md') 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<