Backlight abstraction and other changes (#439)

* redoes matrix pins, abstracts backlight code for B5,6,7

* slimming down keyboard stuff, backlight breathing implemented

* don't call backlight init when no pin

* cleans up user/kb/quantum calls, keyboard files

* fix pvc atomic

* replaces CHANNEL with correct var in breathing

* removes .hexs, updates readmes, updates template

* cleans-up clueboards, readmes to lowercase

* updates readme

9 files changed, 75 insertions, 116 deletions

diff --git a/quantum/template/Makefile b/quantum/template/Makefile
index 87e4c2d2bb..3f6d133c9b 100644
--- a/quantum/template/Makefile
+++ b/quantum/template/Makefile
@@ -53,20 +53,20 @@ OPT_DEFS += -DBOOTLOADER_SIZE=512
 # Build Options
 #   change yes to no to disable
 #
-BOOTMAGIC_ENABLE = no      # Virtual DIP switch configuration(+1000)
-MOUSEKEY_ENABLE = yes       # Mouse keys(+4700)
-EXTRAKEY_ENABLE = yes       # Audio control and System control(+450)
-CONSOLE_ENABLE = yes        # Console for debug(+400)
-COMMAND_ENABLE = yes        # Commands for debug and configuration
+BOOTMAGIC_ENABLE ?= no      # Virtual DIP switch configuration(+1000)
+MOUSEKEY_ENABLE ?= yes       # Mouse keys(+4700)
+EXTRAKEY_ENABLE ?= yes       # Audio control and System control(+450)
+CONSOLE_ENABLE ?= yes        # Console for debug(+400)
+COMMAND_ENABLE ?= yes        # Commands for debug and configuration
 # Do not enable SLEEP_LED_ENABLE. it uses the same timer as BACKLIGHT_ENABLE
-SLEEP_LED_ENABLE = no       # Breathing sleep LED during USB suspend
+SLEEP_LED_ENABLE ?= no       # Breathing sleep LED during USB suspend
 # if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
-NKRO_ENABLE = no            # USB Nkey Rollover
-BACKLIGHT_ENABLE = no       # Enable keyboard backlight functionality on B7 by default
-MIDI_ENABLE = no            # MIDI controls
-UNICODE_ENABLE = no         # Unicode
-BLUETOOTH_ENABLE = no       # Enable Bluetooth with the Adafruit EZ-Key HID
-AUDIO_ENABLE = no           # Audio output on port C6
+NKRO_ENABLE ?= no            # USB Nkey Rollover
+BACKLIGHT_ENABLE ?= no       # Enable keyboard backlight functionality on B7 by default
+MIDI_ENABLE ?= no            # MIDI controls
+UNICODE_ENABLE ?= no         # Unicode
+BLUETOOTH_ENABLE ?= no       # Enable Bluetooth with the Adafruit EZ-Key HID
+AUDIO_ENABLE ?= no           # Audio output on port C6
 
 ifndef QUANTUM_DIR
 	include ../../Makefile
diff --git a/quantum/template/config.h b/quantum/template/config.h
index cad3e3260a..b02f0c7ebc 100644
--- a/quantum/template/config.h
+++ b/quantum/template/config.h
@@ -48,6 +48,11 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 /* COL2ROW or ROW2COL */
 #define DIODE_DIRECTION COL2ROW
+ 
+// #define BACKLIGHT_PIN B7
+// #define BACKLIGHT_BREATHING
+// #define BACKLIGHT_LEVELS 3
+
 
 /* Debounce reduces chatter (unintended double-presses) - set 0 if debouncing is not needed */
 #define DEBOUNCING_DELAY 5
@@ -56,7 +61,6 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 //#define MATRIX_HAS_GHOST
 
 /* number of backlight levels */
-#define BACKLIGHT_LEVELS 3
 
 /* Mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap */
 #define LOCKING_SUPPORT_ENABLE
diff --git a/quantum/template/keymaps/default/Makefile b/quantum/template/keymaps/default/Makefile
new file mode 100644
index 0000000000..f4671a9d11
--- /dev/null
+++ b/quantum/template/keymaps/default/Makefile
@@ -0,0 +1,21 @@
+# Build Options
+#   change to "no" to disable the options, or define them in the Makefile in 
+#   the appropriate keymap folder that will get included automatically
+#
+BOOTMAGIC_ENABLE = no       # Virtual DIP switch configuration(+1000)
+MOUSEKEY_ENABLE = yes       # Mouse keys(+4700)
+EXTRAKEY_ENABLE = yes       # Audio control and System control(+450)
+CONSOLE_ENABLE = no         # Console for debug(+400)
+COMMAND_ENABLE = yes        # Commands for debug and configuration
+NKRO_ENABLE = yes           # Nkey Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
+BACKLIGHT_ENABLE = no       # Enable keyboard backlight functionality
+MIDI_ENABLE = no            # MIDI controls
+AUDIO_ENABLE = no           # Audio output on port C6
+UNICODE_ENABLE = no         # Unicode
+BLUETOOTH_ENABLE = no       # Enable Bluetooth with the Adafruit EZ-Key HID
+RGBLIGHT_ENABLE = no        # Enable WS2812 RGB underlight.  Do not enable this with audio at the same time.
+SLEEP_LED_ENABLE = no       # Breathing sleep LED during USB suspend
+
+ifndef QUANTUM_DIR
+	include ../../../../Makefile
+endif
\ No newline at end of file
diff --git a/quantum/template/keymaps/default/config.h b/quantum/template/keymaps/default/config.h
new file mode 100644
index 0000000000..df06a26206
--- /dev/null
+++ b/quantum/template/keymaps/default/config.h
@@ -0,0 +1,8 @@
+#ifndef CONFIG_USER_H
+#define CONFIG_USER_H
+
+#include "../../config.h"
+
+// place overrides here
+
+#endif
\ No newline at end of file
diff --git a/quantum/template/keymaps/default/keymap.c b/quantum/template/keymaps/default/keymap.c
index 4121fd860c..e28a4723e9 100644
--- a/quantum/template/keymaps/default/keymap.c
+++ b/quantum/template/keymaps/default/keymap.c
@@ -1,6 +1,3 @@
-// This is the canonical layout file for the Quantum project. If you want to add another keyboard,
-// this is the style you want to emulate.
-
 #include "%KEYBOARD%.h"
 
 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
@@ -28,3 +25,20 @@ const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt)
       }
     return MACRO_NONE;
 };
+
+
+void matrix_init_user(void) {
+
+}
+
+void matrix_scan_user(void) {
+
+}
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  return true;
+}
+
+void led_set_user(uint8_t usb_led) {
+
+}
\ No newline at end of file
diff --git a/quantum/template/keymaps/default/readme.md b/quantum/template/keymaps/default/readme.md
new file mode 100644
index 0000000000..21aa663d55
--- /dev/null
+++ b/quantum/template/keymaps/default/readme.md
@@ -0,0 +1 @@
+# The default keymap for %KEYBOARD%
\ No newline at end of file
diff --git a/quantum/template/README.md b/quantum/template/readme.md
index d6b0ac936c..b2fb4dd98d 100644
--- a/quantum/template/README.md
+++ b/quantum/template/readme.md
@@ -3,7 +3,7 @@
 
 ## Quantum MK Firmware
 
-For the full Quantum feature list, see [the parent README.md](/doc/README.md).
+For the full Quantum feature list, see [the parent readme.md](/doc/readme.md).
 
 ## Building
 
@@ -12,13 +12,17 @@ Download or clone the whole firmware and navigate to the keyboards/%KEYBOARD% fo
 Depending on which keymap you would like to use, you will have to compile slightly differently.
 
 ### Default
+
 To build with the default keymap, simply run `make`.
 
 ### Other Keymaps
-Several version of keymap are available in advance but you are recommended to define your favorite layout yourself. To define your own keymap create file named `<name>.c` in the keymaps folder, and see keymap document (you can find in top README.md) and existent keymap files.
 
-To build the firmware binary hex file with a keymap just do `make` with `KEYMAP` option like:
+Several version of keymap are available in advance but you are recommended to define your favorite layout yourself. To define your own keymap create a folder with the name of your keymap in the keymaps folder, and see keymap documentation (you can find in top readme.md) and existant keymap files.
+
+To build the firmware binary hex file with a keymap just do `make` with `keymap` option like:
+
 ```
-$ make KEYMAP=[default|jack|<name>]
+$ make keymap=[default|jack|<name>]
 ```
-Keymaps follow the format **__\<name\>.c__** and are stored in the `keymaps` folder.
\ No newline at end of file
+
+Keymaps follow the format **__keymap.c__** and are stored in folders in the `keymaps` folder, eg `keymaps/my_keymap/`
\ No newline at end of file
diff --git a/quantum/template/template.c b/quantum/template/template.c
index 649072eb2e..dcc4b0a221 100644
--- a/quantum/template/template.c
+++ b/quantum/template/template.c
@@ -1,26 +1,5 @@
 #include "%KEYBOARD%.h"
 
-__attribute__ ((weak))
-void matrix_init_user(void) {
-	// leave this function blank - it can be defined in a keymap file
-};
-
-__attribute__ ((weak))
-void matrix_scan_user(void) {
-	// leave this function blank - it can be defined in a keymap file
-}
-
-__attribute__ ((weak))
-bool process_action_user(keyrecord_t *record) {
-	// leave this function blank - it can be defined in a keymap file
-    return true;
-}
-
-__attribute__ ((weak))
-void led_set_user(uint8_t usb_led) {
-	// leave this function blank - it can be defined in a keymap file
-}
-
 void matrix_init_kb(void) {
 	// put your keyboard start-up code here
 	// runs once when the firmware starts up
@@ -35,7 +14,7 @@ void matrix_scan_kb(void) {
 	matrix_scan_user();
 }
 
-bool process_action_kb(keyrecord_t *record) {
+bool process_record_kb(uint16_t keycode, keyrecord_t *record) {
 	// put your per-action keyboard code here
 	// runs for every action, just before processing by the firmware
 
@@ -47,64 +26,3 @@ void led_set_kb(uint8_t usb_led) {
 
 	led_set_user(usb_led);
 }
-
-#ifdef BACKLIGHT_ENABLE
-#define CHANNEL OCR1C
-
-void backlight_init_ports()
-{
-
-    // Setup PB7 as output and output low.
-    DDRB |= (1<<7);
-    PORTB &= ~(1<<7);
-    
-    // Use full 16-bit resolution. 
-    ICR1 = 0xFFFF;
-
-    // I could write a wall of text here to explain... but TL;DW
-    // Go read the ATmega32u4 datasheet.
-    // And this: http://blog.saikoled.com/post/43165849837/secret-konami-cheat-code-to-high-resolution-pwm-on
-    
-    // Pin PB7 = OCR1C (Timer 1, Channel C)
-    // Compare Output Mode = Clear on compare match, Channel C = COM1C1=1 COM1C0=0
-    // (i.e. start high, go low when counter matches.)
-    // WGM Mode 14 (Fast PWM) = WGM13=1 WGM12=1 WGM11=1 WGM10=0
-    // Clock Select = clk/1 (no prescaling) = CS12=0 CS11=0 CS10=1
-    
-    TCCR1A = _BV(COM1C1) | _BV(WGM11); // = 0b00001010;
-    TCCR1B = _BV(WGM13) | _BV(WGM12) | _BV(CS10); // = 0b00011001;
-
-    backlight_init();
-}
-
-void backlight_set(uint8_t level)
-{
-    if ( level == 0 )
-    {
-        // Turn off PWM control on PB7, revert to output low.
-        TCCR1A &= ~(_BV(COM1C1));
-        CHANNEL = 0x0;
-        // Prevent backlight blink on lowest level
-        PORTB &= ~(_BV(PORTB7));
-    }
-    else if ( level == BACKLIGHT_LEVELS )
-    {
-        // Prevent backlight blink on lowest level
-        PORTB &= ~(_BV(PORTB7));
-        // Turn on PWM control of PB7
-        TCCR1A |= _BV(COM1C1);
-        // Set the brightness
-        CHANNEL = 0xFFFF;
-    }
-    else        
-    {
-        // Prevent backlight blink on lowest level
-        PORTB &= ~(_BV(PORTB7));
-        // Turn on PWM control of PB7
-        TCCR1A |= _BV(COM1C1);
-        // Set the brightness
-        CHANNEL = 0xFFFF >> ((BACKLIGHT_LEVELS - level) * ((BACKLIGHT_LEVELS + 1) / 2));
-    }
-}
-
-#endif
\ No newline at end of file
diff --git a/quantum/template/template.h b/quantum/template/template.h
index b8e7a0456b..cd78a54e3e 100644
--- a/quantum/template/template.h
+++ b/quantum/template/template.h
@@ -1,13 +1,7 @@
 #ifndef %KEYBOARD_UPPERCASE%_H
 #define %KEYBOARD_UPPERCASE%_H
 
-#include "matrix.h"
-#include "keymap.h"
-#ifdef BACKLIGHT_ENABLE
-	#include "backlight.h"
-#endif
-#include <avr/io.h>
-#include <stddef.h>
+#include "quantum.h"
 
 // This a shortcut to help you visually see your layout.
 // The following is an example using the Planck MIT layout
@@ -22,9 +16,4 @@
     { k10, KC_NO, k11 }, \
 }
 
-void matrix_init_user(void);
-void matrix_scan_user(void);
-bool process_action_user(keyrecord_t *record);
-void led_set_user(uint8_t usb_led);
-
 #endif