Creates a userspace for keymaps (#1559)

* create a user space

* adds example

* document, add readme.md

* jackhumbert userspace, ergodox keymap

build_keyboard.mk

@@ -183,6 +183,10 @@ else
     # this state should never be reached
 endif
 
+# User space stuff
+USER_PATH := users/$(KEYMAP)
+-include $(USER_PATH)/rules.mk
+
 # Object files directory
 #     To put object files in current directory, use a dot (.), do NOT make
 #     this an empty or blank macro!
@@ -204,6 +208,7 @@ SRC += $(KEYBOARD_SRC) \
 VPATH += $(KEYMAP_PATH)
 VPATH += $(KEYBOARD_PATHS)
 VPATH += $(COMMON_VPATH)
+VPATH += $(USER_PATH)
 
 include common_features.mk
 include $(TMK_PATH)/protocol.mk

docs/_summary.md

@@ -15,6 +15,7 @@
 * [Features](features.md)
   * [Layouts](feature_layouts.md)
   * [Common Shortcuts](feature_common_shortcuts.md)
+  * [Userspace](feature_userspace.md)
   * [Backlight](feature_backlight.md)
   * [Bootmagic](feature_bootmagic.md)
   * [Dynamic Macros](dynamic_macros.md)

docs/contributing.md

@@ -80,7 +80,7 @@ We have a few different types of changes in QMK, each requiring a different leve
 * Make sure your code change actually compiles.
   * Keymaps: Make sure that `make keyboard:your_new_keymap` does not return an error
   * Keyboards: Make sure that `make keyboard:all` does not return any errors
-  * Core: Make sure that `make allkb` does not return any errors.
+  * Core: Make sure that `make all` does not return any errors.
 * Make sure commit messages are understandable on their own. You should put a short description (no more than 70 characters) on the first line, the second line should be empty, and on the 3rd and later lines you should describe your commit in detail, if required. Example:
 
 ```

docs/dynamic_macros.md

@@ -1,6 +1,6 @@
 # Dynamic macros: record and replay macros in runtime
 
-QMK supports temporarily macros created on the fly. We call these Dynamic Macros. They are defined by the user from the keyboard and are lost when the keyboard is unplugged or otherwise rebooted.
+QMK supports temporary macros created on the fly. We call these Dynamic Macros. They are defined by the user from the keyboard and are lost when the keyboard is unplugged or otherwise rebooted.
 
 You can store one or two macros and they may have a combined total of 128 keypresses. You can increase this size at the cost of RAM.
 
@@ -22,7 +22,7 @@ enum planck_keycodes {
 
 It must be the last element because `dynamic_macros.h` will add some more keycodes after it.
 
-Below it include the `dynamic_macro.h` header:
+Below it, include the `dynamic_macro.h` header:
 
 ```c
 	#include "dynamic_macro.h"`
@@ -58,6 +58,6 @@ For users of the earlier versions of dynamic macros: It is still possible to fin
 	}
 ```
 
-If the LED's start blinking during the recording with each keypress, it means there is no more space for the macro in the macro buffer. To fit the macro in, either make the other macro shorter (they share the same buffer) or increase the buffer size by setting the `DYNAMIC_MACRO_SIZE` preprocessor macro (default value: 128; please read the comments for it in the header).
+If the LEDs start blinking during the recording with each keypress, it means there is no more space for the macro in the macro buffer. To fit the macro in, either make the other macro shorter (they share the same buffer) or increase the buffer size by setting the `DYNAMIC_MACRO_SIZE` preprocessor macro (default value: 128; please read the comments for it in the header).
 
 For the details about the internals of the dynamic macros, please read the comments in the `dynamic_macro.h` header.

docs/faq_build.md

@@ -62,7 +62,7 @@ https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstdd
 https://developer.mbed.org/forum/mbed/topic/5205/
 
 
-## 'clock_prescale_set' and 'clock_div_1' not available
+## `clock_prescale_set` and `clock_div_1` not available
 Your toolchain is too old to support the MCU. For example WinAVR 20100110 doesn't support ATMega32u2.
 
 ```

docs/feature_rgblight.md

@@ -49,8 +49,10 @@ If you have `#define RGBLIGHT_ANIMATIONS` in your `config.h` you will have a num
 | Option | Default Value | Description |
 |--------|---------------|-------------|
 | `RGBLIGHT_ANIMATIONS` | | `#define` this to enable animation modes. |
-| `RGBLIGHT_EFFECT_SNAKE_LENGTH` | 4 | The number of LEDs to light up for the "snake" mode. |
-| `RGBLIGHT_EFFECT_KNIGHT_LENGTH` | 3 | The number of LEDs to light up for the "knight" mode. |
+| `RGBLIGHT_EFFECT_BREATHE_CENTER` | 1.85 | Used to calculate the curve for the breathing animation. Valid values 1.0-2.7. |
+| `RGBLIGHT_EFFECT_BREATHE_MAX` | 255 | The maximum brightness for the breathing mode. Valid values 1-255. |
+| `RGBLIGHT_EFFECT_SNAKE_LENGTH` | 4 | The number of LEDs to light up for the "snake" animation. |
+| `RGBLIGHT_EFFECT_KNIGHT_LENGTH` | 3 | The number of LEDs to light up for the "knight" animation. |
 | `RGBLIGHT_EFFECT_KNIGHT_OFFSET` | 0 | Start the knight animation this many LEDs from the start of the strip. |
 | `RGBLIGHT_EFFECT_KNIGHT_LED_NUM` | RGBLED_NUM | The number of LEDs to have the "knight" animation travel. |
 | `RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL` | 1000 | How long to wait between light changes for the "christmas" animation. Specified in ms. |

docs/feature_userspace.md

@@ -0,0 +1,33 @@
+# Userspace: sharing code between keymaps
+
+If you use more than one keyboard with a similar keymap, you might see the benefit in being able to share code between them. Create your own folder in `users/` named the same as your keymap (ideally your github username, `<name>`) with the following structure:
+
+* `/users/<name>/` (added to the path automatically)
+  * `readme.md`
+  * `rules.mk` (included automatically)
+  * `<name>.h` (optional)
+  * `<name>.c` (optional)
+
+`<name>.c` will need to be added to the SRC in `rules.mk` like this:
+
+    SRC += <name>.c
+
+Additional files may be added in the same way - it's recommended you have one named `<name>`.c/.h though.
+
+All this only happens when you build a keymap named `<name>`, like this:
+
+    make planck:<name>
+
+For example, 
+
+    make planck:jack
+
+Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`.
+
+## Readme
+
+Please include authorship (your name, github username, email), and optionally [a license that's GPL compatible](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses).
+
+## Example
+
+For a brief example, checkout `/users/_example/` until we have more reasonable and useful examples.

docs/tap_dance.md

@@ -63,20 +63,23 @@ qk_tap_dance_action_t tap_dance_actions[] = {
 TD(TD_ESC_CAPS)
 ```
 
-## Complex Example
+## Complex Examples
 
-Here's a more complex example involving custom actions:
+This section details several complex tap dance examples.
+All the enums used in the examples are declared like this:
 
 ```c
+// Enums defined for all examples:
 enum {
  CT_SE = 0,
  CT_CLN,
  CT_EGG,
  CT_FLSH,
+ X_TAP_DANCE
 };
-
-/* Have the above three on the keymap, TD(CT_SE), etc... */
-
+```
+### Example 1: Send `:` on single tap, `;` on double tap
+```c
 void dance_cln_finished (qk_tap_dance_state_t *state, void *user_data) {
   if (state->count == 1) {
     register_code (KC_RSFT);
@@ -95,6 +98,13 @@ void dance_cln_reset (qk_tap_dance_state_t *state, void *user_data) {
   }
 }
 
+//All tap dance functions would go here. Only showing this one.
+qk_tap_dance_action_t tap_dance_actions[] = {
+ [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
+};
+```
+### Example 2: Send "Safety Dance!" after 100 taps
+```c
 void dance_egg (qk_tap_dance_state_t *state, void *user_data) {
   if (state->count >= 100) {
     SEND_STRING ("Safety dance!");
@@ -102,6 +112,14 @@ void dance_egg (qk_tap_dance_state_t *state, void *user_data) {
   }
 }
 
+qk_tap_dance_action_t tap_dance_actions[] = {
+ [CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
+};
+```
+
+### Example 3: Turn LED lights on then off, one at a time
+
+```c
 // on each tap, light up one led, from right to left
 // on the forth tap, turn them off from right to left
 void dance_flsh_each(qk_tap_dance_state_t *state, void *user_data) {
@@ -141,6 +159,7 @@ void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) {
   ergodox_right_led_3_off();
 }
 
+//All tap dances now put together. Example 3 is "CT_FLASH"
 qk_tap_dance_action_t tap_dance_actions[] = {
   [CT_SE]  = ACTION_TAP_DANCE_DOUBLE (KC_SPC, KC_ENT)
  ,[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
@@ -148,3 +167,69 @@ qk_tap_dance_action_t tap_dance_actions[] = {
  ,[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED (dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
 };
 ```
+
+### Example 4: 'Quad Function Tap-Dance'
+
+By @DanielGGordon
+
+Allow one key to have 4 (or more) functions, depending on number of presses, and if the key is held or tapped.
+Below is a specific example:
+*  Tap = Send `x`
+*  Hold = Send `Control`
+*  Double Tap = Send `Escape`
+*  Double Tap and Hold = Send `Alt`
+
+The following example can be easily expanded to more than 4 quite easily:
+```c
+//**************** Definitions needed for quad function to work *********************//
+//Enums used to clearly convey the state of the tap dance
+enum {
+  SINGLE_TAP = 1,
+  SINGLE_HOLD = 2,
+  DOUBLE_TAP = 3,
+  DOUBLE_HOLD = 4
+  // Add more enums here if you want for triple, quadruple, etc. 
+};
+
+typedef struct {
+  bool is_press_action;
+  int state;
+} tap;
+
+int cur_dance (qk_tap_dance_state_t *state) {
+  if ((state->count == 1) && (!state->pressed)) return SINGLE_TAP;
+  else if ((state->count == 1) && (state->pressed)) return SINGLE_HOLD;
+  else if ((state->count == 2) && (!state->pressed)) return DOUBLE_TAP;
+  else if ((state->count == 2) && (state->pressed)) return DOUBLE_HOLD;
+  else return 5; //magic number. At some point this method will expand to work for more presses
+}
+//**************** Definitions needed for quad function to work *********************//
+
+//instanalize an instance of 'tap' for the 'x' tap dance.
+static tap xtap_state = { 
+  .is_press_action = true,
+  .state = 0
+};
+
+void x_finished (qk_tap_dance_state_t *state, void *user_data) {
+  xtap_state.state = cur_dance(state);
+  switch (xtap_state.state) {
+    case SINGLE_TAP: register_code(KC_X); break;
+    case SINGLE_HOLD: register_code(KC_LCTRL); break;
+    case DOUBLE_TAP: register_code(KC_ESC); break;
+    case DOUBLE_HOLD: register_code(KC_LALT);
+  }
+}
+
+void x_reset (qk_tap_dance_state_t *state, void *user_data) {
+  switch (xtap_state.state) {
+    case SINGLE_TAP: unregister_code(KC_X); break;
+    case SINGLE_HOLD: unregister_code(KC_LCTRL); break;
+    case DOUBLE_TAP: unregister_code(KC_ESC); break;
+    case DOUBLE_HOLD: unregister_code(KC_LALT);
+  }
+  xtap_state.state = 0;
+}
+```
+And then simply add this to your list of tap dance functions:
+`[X_TAP_DANCE] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, x_finished, x_reset)`

keyboards/clueboard/17/17.c

@@ -1,4 +1,4 @@
-#include "clueboard_17.h"
+#include "17.h"
 
 int pwm_level;
 

keyboards/clueboard/17/keymaps/default/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_17.h"
+#include "17.h"
 
 #include "backlight.h"
 

keyboards/clueboard/17/readme.md

@@ -1,15 +1,16 @@
-# Cluepad
+# Clueboard 17% (Formerly Cluepad)
 
-![Cluepad](https://static1.squarespace.com/static/55c13bdee4b099be5dcb82eb/5842fbdce3df28eae5ec557e/5844fb2cb8a79bbdfd63bad1/1498501250178/IMGP3931.jpg?format=750w)
+![Clueboard 17%](https://static1.squarespace.com/static/55c13bdee4b099be5dcb82eb/5842fbdce3df28eae5ec557e/5844fb2cb8a79bbdfd63bad1/1498501250178/IMGP3931.jpg?format=750w)
 
 A basic 17 key numpad PCB.
 
 * Keyboard Maintainer: [Zach White](https://github.com/skullydazed)
-* Hardware Supported: Cluepad PCB 1.0
+* Hardware Supported:
+  * Cluepad PCB 1.0
 * Hardware Availability: [clueboard.co](https://clueboard.co/)
 
 Make example for this keyboard (after setting up your build environment):
 
-    make clueboard_17:default
+    make clueboard/17:default
 
 See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.

keyboards/clueboard/60/60.c

@@ -13,7 +13,7 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-#include "clueboard_60.h"
+#include "60.h"
 
 void matrix_init_kb(void) {
 

keyboards/clueboard/60/keymaps/default/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_60.h"
+#include "60.h"
 
 #define _______ KC_TRNS
 

keyboards/clueboard/60/keymaps/default_aek/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_60.h"
+#include "60.h"
 
 #define _______ KC_TRNS
 

keyboards/clueboard/60/readme.md

@@ -9,6 +9,6 @@ A fully customizable 60% keyboard.
 
 Make example for this keyboard (after setting up your build environment):
 
-    make clueboard_60:default:dfu-util
+    make clueboard/60:default
 
 See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.

keyboards/clueboard/66/66.c

@@ -0,0 +1 @@
+#include "66.h"

keyboards/clueboard/66/config.h

@@ -15,8 +15,8 @@ You should have received a copy of the GNU General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-#ifndef CONFIG_H
-#define CONFIG_H
+#ifndef CLUEBOARD_66_CONFIG_H
+#define CLUEBOARD_66_CONFIG_H
 
 #include "config_common.h"
 

keyboards/clueboard/66/keymaps/bloodlvst/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Helpful defines
 #define _______ KC_TRNS

keyboards/clueboard/66/keymaps/caps_fn/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Helpful defines
 #define _______ KC_TRNS

keyboards/clueboard/66/keymaps/colemak/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Helpful defines
 #define _______ KC_TRNS

keyboards/clueboard/66/keymaps/default/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Helpful defines
 #define _______ KC_TRNS

keyboards/clueboard/66/keymaps/jokrik/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Helpful defines
 #define _______ KC_TRNS

keyboards/clueboard/66/keymaps/mac_optimized/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Helpful defines
 #define _______ KC_TRNS

keyboards/clueboard/66/keymaps/magicmonty/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Helpful defines
 #define _______ KC_TRNS

keyboards/clueboard/66/keymaps/maximised/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Helpful defines
 #define _______ KC_TRNS

keyboards/clueboard/66/keymaps/mouse_keys/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Helpful defines
 #define _______ KC_TRNS

keyboards/clueboard/66/keymaps/serubin/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Helpful defines
 #define _______ KC_TRNS

keyboards/clueboard/66/keymaps/shift_fn/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Helpful defines
 #define _______ KC_TRNS

keyboards/clueboard/66/keymaps/skully/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Helpful defines
 #define _______ KC_TRNS

keyboards/clueboard/66/keymaps/smt/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Each layer gets a name for readability, which is then used in the keymap matrix below.
 // The underscores don't mean anything - you can have a layer called STUFF or any other name.

keyboards/clueboard/66/keymaps/tetris/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 #include "tetris_text.h"
 
 // Helpful defines

keyboards/clueboard/66/keymaps/unix_optimized/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Helpful defines
 #define _______ KC_TRNS

keyboards/clueboard/66/keymaps/win_optimized/keymap.c

@@ -1,4 +1,4 @@
-#include "clueboard_66.h"
+#include "66.h"
 
 // Helpful defines
 #define _______ KC_TRNS

keyboards/clueboard/66/keymaps/xyverz/keymap.c

@@ -1,7 +1,7 @@
 // Xyverz' keymap.
 // It's based on the default keymap, but Dvorak!
 
-#include "clueboard_66.h"
+#include "66.h"
 
 // Used for SHIFT_ESC
 #define MODS_CTRL_MASK  (MOD_BIT(KC_LSHIFT)|MOD_BIT(KC_RSHIFT))

keyboards/clueboard/66/readme.md

@@ -13,6 +13,6 @@ A fully customizable 66% keyboard.
 
 Make example for this keyboard (after setting up your build environment):
 
-    make clueboard/rev3:default
+    make clueboard/66:default
 
 See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.

keyboards/clueboard/66/rev1/config.h

@@ -1,5 +1,5 @@
-#ifndef REV2_CONFIG_H
-#define REV2_CONFIG_H
+#ifndef CLUEBOARD_66_REV1_CONFIG_H
+#define CLUEBOARD_66_REV1_CONFIG_H
 
 #include "config_common.h"
 
@@ -33,4 +33,4 @@
 #define RGBLIGHT_VAL_STEP 17
 
 
-#endif
+#endif

keyboards/clueboard/66/rev1/rev1.h

@@ -1,7 +1,7 @@
 #ifndef REV1_H
 #define REV1_H
 
-#include "../clueboard_66.h"
+#include "../66.h"
 
 /* Clueboard matrix layout
  * ,-----------------------------------------------------------.  ,---.

keyboards/clueboard/66/rev2/config.h

@@ -1,5 +1,5 @@
-#ifndef REV2_CONFIG_H
-#define REV2_CONFIG_H
+#ifndef CLUEBOARD_66_REV2_CONFIG_H
+#define CLUEBOARD_66_REV2_CONFIG_H
 
 #include "config_common.h"
 
@@ -36,6 +36,8 @@
 #define RGBLIGHT_VAL_STEP 17
 
 #define RGBLIGHT_ANIMATIONS
+#define RGBLIGHT_EFFECT_BREATHE_CENTER 1
+#define RGBLIGHT_EFFECT_BREATHE_MAX 200
 #define RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL 666*2
 #define RGBLIGHT_EFFECT_CHRISTMAS_STEP 1
 #define RGBLIGHT_EFFECT_KNIGHT_LENGTH 3   // How many LEDs wide to light up

keyboards/clueboard/66/rev2/rev2.h

@@ -1,7 +1,7 @@
 #ifndef REV2_H
 #define REV2_H
 
-#include "clueboard_66.h"
+#include "66.h"
 
 /* Clueboard matrix layout
  * ,-----------------------------------------------------------.  ,---.

keyboards/clueboard/66/rev3/config.h

@@ -1,5 +1,5 @@
-#ifndef REV3_CONFIG_H
-#define REV3_CONFIG_H
+#ifndef CLUEBOARD_66_REV3_CONFIG_H
+#define CLUEBOARD_66_REV3_CONFIG_H
 
 #include "config_common.h"
 
@@ -36,6 +36,8 @@
 #define RGBLIGHT_VAL_STEP 17
 
 #define RGBLIGHT_ANIMATIONS
+#define RGBLIGHT_EFFECT_BREATHE_CENTER 1
+#define RGBLIGHT_EFFECT_BREATHE_MAX 200
 #define RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL 666*2
 #define RGBLIGHT_EFFECT_CHRISTMAS_STEP 1
 #define RGBLIGHT_EFFECT_KNIGHT_LENGTH 3   // How many LEDs wide to light up

keyboards/clueboard/66/rev3/rev3.h

@@ -1,7 +1,7 @@
 #ifndef REV3_H
 #define REV3_H
 
-#include "clueboard_66.h"
+#include "66.h"
 
 /* Clueboard matrix layout
  * ,-----------------------------------------------------------.  ,---.

keyboards/clueboard/66/rules.mk

@@ -1,3 +1,4 @@
+DEFAULT_FOLDER = clueboard/66/rev2
 MCU = atmega32u4
 F_CPU = 16000000
 ARCH = AVR8
@@ -19,5 +20,3 @@ RGBLIGHT_ENABLE = yes  # Enable keyboard underlight functionality
 MIDI_ENABLE = no 		# MIDI controls
 UNICODE_ENABLE = no 		# Unicode
 BLUETOOTH_ENABLE = no # Enable Bluetooth with the Adafruit EZ-Key HID
-
-DEFAULT_FOLDER = clueboard_66/rev2

keyboards/clueboard/card/card.c

@@ -1,4 +1,4 @@
-#include "cluecard.h"
+#include "card.h"
 #define BL_RED OCR1B
 #define BL_GREEN OCR1A
 #define BL_BLUE OCR1C