3 files changed, 117 insertions, 102 deletions
diff --git a/docs/_summary.md b/docs/_summary.md
index 2e874fb1c..44030d812 100644
--- a/docs/_summary.md
+++ b/docs/_summary.md
@@ -105,6 +105,7 @@
    * [Encoders](feature_encoders.md)
    * [Haptic Feedback](feature_haptic_feedback.md)
    * [Joystick](feature_joystick.md)
+    * [LED Indicators](feature_led_indicators.md)
    * [Proton C Conversion](proton_c_conversion.md)
    * [PS/2 Mouse](feature_ps2_mouse.md)
    * [Split Keyboard](feature_split_keyboard.md)
diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md
index bf3a60377..a459042b3 100644
--- a/docs/custom_quantum_functions.md
+++ b/docs/custom_quantum_functions.md
@@ -88,108 +88,6 @@ keyrecord_t record {
 }
 ```
-# LED Control
-QMK provides methods to read 5 of the LEDs defined in the HID spec:
-* Num Lock
-* Caps Lock
-* Scroll Lock
-* Compose
-* Kana
-There are two ways to get the lock LED state:
-* by implementing `bool led_update_kb(led_t led_state)` or `_user(led_t led_state)`; or
-* by calling `led_t host_keyboard_led_state()`
-!> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called.
-Two more deprecated functions exist that provide the LED state as a `uint8_t`:
-* `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)`
-* `uint8_t host_keyboard_leds()`
-## `led_update_user()`
-This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter.
-By convention, return `true` from `led_update_user()` to get the `led_update_kb()` hook to run its code, and
-return `false` when you would prefer not to run the code in `led_update_kb()`.
-Some examples include:
-  - overriding the LEDs to use them for something else like layer indication
-    - return `false` because you do not want the `_kb()` function to run, as it would override your layer behavior.
-  - play a sound when an LED turns on or off.
-    - return `true` because you want the `_kb` function to run, and this is in addition to the default LED behavior.
-?> Because the `led_set_*` functions return `void` instead of `bool`, they do not allow for overriding the keyboard LED control, and thus it's recommended to use `led_update_*` instead.
-### Example `led_update_kb()` Implementation
-```c
-bool led_update_kb(led_t led_state) {
-    bool res = led_update_user(led_state);
-    if(res) {
-        // writePin sets the pin high for 1 and low for 0.
-        // In this example the pins are inverted, setting
-        // it low/0 turns it on, and high/1 turns the LED off.
-        // This behavior depends on whether the LED is between the pin
-        // and VCC or the pin and GND.
-        writePin(B0, !led_state.num_lock);
-        writePin(B1, !led_state.caps_lock);
-        writePin(B2, !led_state.scroll_lock);
-        writePin(B3, !led_state.compose);
-        writePin(B4, !led_state.kana);
-    }
-    return res;
-}
-```
-### Example `led_update_user()` Implementation
-This incomplete example would play a sound if Caps Lock is turned on or off. It returns `true`, because you also want the LEDs to maintain their state.
-```c
-#ifdef AUDIO_ENABLE
-  float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND);
-  float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND);
-#endif
-bool led_update_user(led_t led_state) {
-    #ifdef AUDIO_ENABLE
-    static uint8_t caps_state = 0;
-    if (caps_state != led_state.caps_lock) {
-        led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off);
-        caps_state = led_state.caps_lock;
-    }
-    #endif
-    return true;
-}
-```
-### `led_update_*` Function Documentation
-* Keyboard/Revision: `bool led_update_kb(led_t led_state)`
-* Keymap: `bool led_update_user(led_t led_state)`
-## `host_keyboard_led_state()`
-Call this function to get the last received LED state as a `led_t`. This is useful for reading the LED state outside `led_update_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code).
-## Setting Physical LED State
-Some keyboard implementations provide convenience methods for setting the state of the physical LEDs.
-### Ergodox Boards
-The Ergodox implementations provide `ergodox_right_led_1`/`2`/`3_on`/`off()` to turn individual LEDs on or off, as well as `ergodox_right_led_on`/`off(uint8_t led)` to turn them on or off by their index.
-In addition, it is possible to specify the brightness level of all LEDs with `ergodox_led_all_set(uint8_t n)`; of individual LEDs with `ergodox_right_led_1`/`2`/`3_set(uint8_t n)`; or by index with `ergodox_right_led_set(uint8_t led, uint8_t n)`.
-Ergodox boards also define `LED_BRIGHTNESS_LO` for the lowest brightness and `LED_BRIGHTNESS_HI` for the highest brightness (which is the default).
 # Keyboard Initialization Code
 There are several steps in the keyboard initialization process.  Depending on what you want to do, it will influence which function you should use.
diff --git a/docs/feature_led_indicators.md b/docs/feature_led_indicators.md
new file mode 100644
index 000000000..10e095ab1
--- /dev/null
+++ b/docs/feature_led_indicators.md
@@ -0,0 +1,116 @@
+# LED Indicators
+QMK provides methods to read 5 of the LEDs defined in the HID spec:
+* Num Lock
+* Caps Lock
+* Scroll Lock
+* Compose
+* Kana
+There are three ways to get the lock LED state:
+* by specifying configuration options within `config.h`
+* by implementing `bool led_update_kb(led_t led_state)` or `_user(led_t led_state)`; or
+* by calling `led_t host_keyboard_led_state()`
+!> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called.
+Two more deprecated functions exist that provide the LED state as a `uint8_t`:
+* `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)`
+* `uint8_t host_keyboard_leds()`
+## Configuration Options
+To configure the indicators, `#define` these in your `config.h`:
+|Define               |Default      |Description                                |
+|---------------------|-------------|-------------------------------------------|
+|`LED_NUM_LOCK_PIN`   |*Not defined*|The pin that controls the `Num Lock` LED   |
+|`LED_CAPS_LOCK_PIN`  |*Not defined*|The pin that controls the `Caps Lock` LED  |
+|`LED_SCROLL_LOCK_PIN`|*Not defined*|The pin that controls the `Scroll Lock` LED|
+|`LED_COMPOSE_PIN`    |*Not defined*|The pin that controls the `Compose` LED    |
+|`LED_KANA_PIN`       |*Not defined*|The pin that controls the `Kana` LED       |
+|`LED_PIN_ON_STATE`   |`1`          |The state of the indicator pins when the LED is "on" - `1` for high, `0` for low|
+Unless you are designing your own keyboard, you generally should not need to change the above config options.
+## `led_update_*()`
+When the configuration options do not provide enough flexibility, the API hooks provided allow custom control of the LED behavior. These functions will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter.
+By convention, return `true` from `led_update_user()` to get the `led_update_kb()` hook to run its code, and
+return `false` when you would prefer not to run the code in `led_update_kb()`.
+Some examples include:
+  - overriding the LEDs to use them for something else like layer indication
+    - return `false` because you do not want the `_kb()` function to run, as it would override your layer behavior.
+  - play a sound when an LED turns on or off.
+    - return `true` because you want the `_kb` function to run, and this is in addition to the default LED behavior.
+?> Because the `led_set_*` functions return `void` instead of `bool`, they do not allow for overriding the keyboard LED control, and thus it's recommended to use `led_update_*` instead.
+### Example `led_update_kb()` Implementation
+```c
+bool led_update_kb(led_t led_state) {
+    bool res = led_update_user(led_state);
+    if(res) {
+        // writePin sets the pin high for 1 and low for 0.
+        // In this example the pins are inverted, setting
+        // it low/0 turns it on, and high/1 turns the LED off.
+        // This behavior depends on whether the LED is between the pin
+        // and VCC or the pin and GND.
+        writePin(B0, !led_state.num_lock);
+        writePin(B1, !led_state.caps_lock);
+        writePin(B2, !led_state.scroll_lock);
+        writePin(B3, !led_state.compose);
+        writePin(B4, !led_state.kana);
+    }
+    return res;
+}
+```
+### Example `led_update_user()` Implementation
+This incomplete example would play a sound if Caps Lock is turned on or off. It returns `true`, because you also want the LEDs to maintain their state.
+```c
+#ifdef AUDIO_ENABLE
+  float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND);
+  float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND);
+#endif
+bool led_update_user(led_t led_state) {
+    #ifdef AUDIO_ENABLE
+    static uint8_t caps_state = 0;
+    if (caps_state != led_state.caps_lock) {
+        led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off);
+        caps_state = led_state.caps_lock;
+    }
+    #endif
+    return true;
+}
+```
+### `led_update_*` Function Documentation
+* Keyboard/Revision: `bool led_update_kb(led_t led_state)`
+* Keymap: `bool led_update_user(led_t led_state)`
+## `host_keyboard_led_state()`
+Call this function to get the last received LED state as a `led_t`. This is useful for reading the LED state outside `led_update_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code).
+## Setting Physical LED State
+Some keyboard implementations provide convenience methods for setting the state of the physical LEDs.
+### Ergodox Boards
+The Ergodox implementations provide `ergodox_right_led_1`/`2`/`3_on`/`off()` to turn individual LEDs on or off, as well as `ergodox_right_led_on`/`off(uint8_t led)` to turn them on or off by their index.
+In addition, it is possible to specify the brightness level of all LEDs with `ergodox_led_all_set(uint8_t n)`; of individual LEDs with `ergodox_right_led_1`/`2`/`3_set(uint8_t n)`; or by index with `ergodox_right_led_set(uint8_t led, uint8_t n)`.
+Ergodox boards also define `LED_BRIGHTNESS_LO` for the lowest brightness and `LED_BRIGHTNESS_HI` for the highest brightness (which is the default).

diff --git a/docs/_summary.md b/docs/_summary.md index 2e874fb1c..44030d812 100644 --- a/docs/_summary.md +++ b/docs/_summary.md
@@ -105,6 +105,7 @@
105	* [Encoders](feature_encoders.md)	105	* [Encoders](feature_encoders.md)
106	* [Haptic Feedback](feature_haptic_feedback.md)	106	* [Haptic Feedback](feature_haptic_feedback.md)
107	* [Joystick](feature_joystick.md)	107	* [Joystick](feature_joystick.md)
		108	* [LED Indicators](feature_led_indicators.md)
108	* [Proton C Conversion](proton_c_conversion.md)	109	* [Proton C Conversion](proton_c_conversion.md)
109	* [PS/2 Mouse](feature_ps2_mouse.md)	110	* [PS/2 Mouse](feature_ps2_mouse.md)
110	* [Split Keyboard](feature_split_keyboard.md)	111	* [Split Keyboard](feature_split_keyboard.md)


diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index bf3a60377..a459042b3 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md
@@ -88,108 +88,6 @@ keyrecord_t record {
88	}	88	}
89	```	89	```
90		90
91	# LED Control
92
93	QMK provides methods to read 5 of the LEDs defined in the HID spec:
94
95	* Num Lock
96	* Caps Lock
97	* Scroll Lock
98	* Compose
99	* Kana
100
101	There are two ways to get the lock LED state:
102
103	* by implementing `bool led_update_kb(led_t led_state)` or `_user(led_t led_state)`; or
104	* by calling `led_t host_keyboard_led_state()`
105
106	!> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called.
107
108	Two more deprecated functions exist that provide the LED state as a `uint8_t`:
109
110	* `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)`
111	* `uint8_t host_keyboard_leds()`
112
113	## `led_update_user()`
114
115	This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter.
116
117	By convention, return `true` from `led_update_user()` to get the `led_update_kb()` hook to run its code, and
118	return `false` when you would prefer not to run the code in `led_update_kb()`.
119
120	Some examples include:
121
122	- overriding the LEDs to use them for something else like layer indication
123	- return `false` because you do not want the `_kb()` function to run, as it would override your layer behavior.
124	- play a sound when an LED turns on or off.
125	- return `true` because you want the `_kb` function to run, and this is in addition to the default LED behavior.
126
127	?> Because the `led_set_` functions return `void` instead of `bool`, they do not allow for overriding the keyboard LED control, and thus it's recommended to use `led_update_` instead.
128
129	### Example `led_update_kb()` Implementation
130
131	```c
132	bool led_update_kb(led_t led_state) {
133	bool res = led_update_user(led_state);
134	if(res) {
135	// writePin sets the pin high for 1 and low for 0.
136	// In this example the pins are inverted, setting
137	// it low/0 turns it on, and high/1 turns the LED off.
138	// This behavior depends on whether the LED is between the pin
139	// and VCC or the pin and GND.
140	writePin(B0, !led_state.num_lock);
141	writePin(B1, !led_state.caps_lock);
142	writePin(B2, !led_state.scroll_lock);
143	writePin(B3, !led_state.compose);
144	writePin(B4, !led_state.kana);
145	}
146	return res;
147	}
148	```
149
150	### Example `led_update_user()` Implementation
151
152	This incomplete example would play a sound if Caps Lock is turned on or off. It returns `true`, because you also want the LEDs to maintain their state.
153
154	```c
155	#ifdef AUDIO_ENABLE
156	float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND);
157	float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND);
158	#endif
159
160	bool led_update_user(led_t led_state) {
161	#ifdef AUDIO_ENABLE
162	static uint8_t caps_state = 0;
163	if (caps_state != led_state.caps_lock) {
164	led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off);
165	caps_state = led_state.caps_lock;
166	}
167	#endif
168	return true;
169	}
170	```
171
172	### `led_update_*` Function Documentation
173
174	* Keyboard/Revision: `bool led_update_kb(led_t led_state)`
175	* Keymap: `bool led_update_user(led_t led_state)`
176
177	## `host_keyboard_led_state()`
178
179	Call this function to get the last received LED state as a `led_t`. This is useful for reading the LED state outside `led_update_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code).
180
181	## Setting Physical LED State
182
183	Some keyboard implementations provide convenience methods for setting the state of the physical LEDs.
184
185	### Ergodox Boards
186
187	The Ergodox implementations provide `ergodox_right_led_1`/`2`/`3_on`/`off()` to turn individual LEDs on or off, as well as `ergodox_right_led_on`/`off(uint8_t led)` to turn them on or off by their index.
188
189	In addition, it is possible to specify the brightness level of all LEDs with `ergodox_led_all_set(uint8_t n)`; of individual LEDs with `ergodox_right_led_1`/`2`/`3_set(uint8_t n)`; or by index with `ergodox_right_led_set(uint8_t led, uint8_t n)`.
190
191	Ergodox boards also define `LED_BRIGHTNESS_LO` for the lowest brightness and `LED_BRIGHTNESS_HI` for the highest brightness (which is the default).
192
193	# Keyboard Initialization Code	91	# Keyboard Initialization Code
194		92
195	There are several steps in the keyboard initialization process. Depending on what you want to do, it will influence which function you should use.	93	There are several steps in the keyboard initialization process. Depending on what you want to do, it will influence which function you should use.


diff --git a/docs/feature_led_indicators.md b/docs/feature_led_indicators.md new file mode 100644 index 000000000..10e095ab1 --- /dev/null +++ b/docs/feature_led_indicators.md
@@ -0,0 +1,116 @@
		1	# LED Indicators
		2
		3	QMK provides methods to read 5 of the LEDs defined in the HID spec:
		4
		5	* Num Lock
		6	* Caps Lock
		7	* Scroll Lock
		8	* Compose
		9	* Kana
		10
		11	There are three ways to get the lock LED state:
		12	* by specifying configuration options within `config.h`
		13	* by implementing `bool led_update_kb(led_t led_state)` or `_user(led_t led_state)`; or
		14	* by calling `led_t host_keyboard_led_state()`
		15
		16	!> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called.
		17
		18	Two more deprecated functions exist that provide the LED state as a `uint8_t`:
		19
		20	* `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)`
		21	* `uint8_t host_keyboard_leds()`
		22
		23	## Configuration Options
		24
		25	To configure the indicators, `#define` these in your `config.h`:
		26
		27	\|Define \|Default \|Description \|
		28	\|---------------------\|-------------\|-------------------------------------------\|
		29	\|`LED_NUM_LOCK_PIN` \|Not defined\|The pin that controls the `Num Lock` LED \|
		30	\|`LED_CAPS_LOCK_PIN` \|Not defined\|The pin that controls the `Caps Lock` LED \|
		31	\|`LED_SCROLL_LOCK_PIN`\|Not defined\|The pin that controls the `Scroll Lock` LED\|
		32	\|`LED_COMPOSE_PIN` \|Not defined\|The pin that controls the `Compose` LED \|
		33	\|`LED_KANA_PIN` \|Not defined\|The pin that controls the `Kana` LED \|
		34	\|`LED_PIN_ON_STATE` \|`1` \|The state of the indicator pins when the LED is "on" - `1` for high, `0` for low\|
		35
		36	Unless you are designing your own keyboard, you generally should not need to change the above config options.
		37
		38	## `led_update_*()`
		39
		40	When the configuration options do not provide enough flexibility, the API hooks provided allow custom control of the LED behavior. These functions will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter.
		41
		42	By convention, return `true` from `led_update_user()` to get the `led_update_kb()` hook to run its code, and
		43	return `false` when you would prefer not to run the code in `led_update_kb()`.
		44
		45	Some examples include:
		46
		47	- overriding the LEDs to use them for something else like layer indication
		48	- return `false` because you do not want the `_kb()` function to run, as it would override your layer behavior.
		49	- play a sound when an LED turns on or off.
		50	- return `true` because you want the `_kb` function to run, and this is in addition to the default LED behavior.
		51
		52	?> Because the `led_set_` functions return `void` instead of `bool`, they do not allow for overriding the keyboard LED control, and thus it's recommended to use `led_update_` instead.
		53
		54	### Example `led_update_kb()` Implementation
		55
		56	```c
		57	bool led_update_kb(led_t led_state) {
		58	bool res = led_update_user(led_state);
		59	if(res) {
		60	// writePin sets the pin high for 1 and low for 0.
		61	// In this example the pins are inverted, setting
		62	// it low/0 turns it on, and high/1 turns the LED off.
		63	// This behavior depends on whether the LED is between the pin
		64	// and VCC or the pin and GND.
		65	writePin(B0, !led_state.num_lock);
		66	writePin(B1, !led_state.caps_lock);
		67	writePin(B2, !led_state.scroll_lock);
		68	writePin(B3, !led_state.compose);
		69	writePin(B4, !led_state.kana);
		70	}
		71	return res;
		72	}
		73	```
		74
		75	### Example `led_update_user()` Implementation
		76
		77	This incomplete example would play a sound if Caps Lock is turned on or off. It returns `true`, because you also want the LEDs to maintain their state.
		78
		79	```c
		80	#ifdef AUDIO_ENABLE
		81	float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND);
		82	float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND);
		83	#endif
		84
		85	bool led_update_user(led_t led_state) {
		86	#ifdef AUDIO_ENABLE
		87	static uint8_t caps_state = 0;
		88	if (caps_state != led_state.caps_lock) {
		89	led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off);
		90	caps_state = led_state.caps_lock;
		91	}
		92	#endif
		93	return true;
		94	}
		95	```
		96
		97	### `led_update_*` Function Documentation
		98
		99	* Keyboard/Revision: `bool led_update_kb(led_t led_state)`
		100	* Keymap: `bool led_update_user(led_t led_state)`
		101
		102	## `host_keyboard_led_state()`
		103
		104	Call this function to get the last received LED state as a `led_t`. This is useful for reading the LED state outside `led_update_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code).
		105
		106	## Setting Physical LED State
		107
		108	Some keyboard implementations provide convenience methods for setting the state of the physical LEDs.
		109
		110	### Ergodox Boards
		111
		112	The Ergodox implementations provide `ergodox_right_led_1`/`2`/`3_on`/`off()` to turn individual LEDs on or off, as well as `ergodox_right_led_on`/`off(uint8_t led)` to turn them on or off by their index.
		113
		114	In addition, it is possible to specify the brightness level of all LEDs with `ergodox_led_all_set(uint8_t n)`; of individual LEDs with `ergodox_right_led_1`/`2`/`3_set(uint8_t n)`; or by index with `ergodox_right_led_set(uint8_t led, uint8_t n)`.
		115
		116	Ergodox boards also define `LED_BRIGHTNESS_LO` for the lowest brightness and `LED_BRIGHTNESS_HI` for the highest brightness (which is the default).