aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJames Young <18669334+noroadsleft@users.noreply.github.com>2020-03-15 20:29:11 -0700
committerGitHub <noreply@github.com>2020-03-15 20:29:11 -0700
commitb272c035ba7fa8555a88c922b3e94c3f3817c4ff (patch)
treea5c9a1f6e4a1d9c02b72a12e33b2f9e69b5bf85b
parent5f1f370463d818a5283a17001ad832073efc45a4 (diff)
downloadqmk_firmware-b272c035ba7fa8555a88c922b3e94c3f3817c4ff.tar.gz
qmk_firmware-b272c035ba7fa8555a88c922b3e94c3f3817c4ff.zip
[Docs] Random Fixes (#8340)
* fix CLI section links in the Summary * fix heading in Pointing Device doc * fix headings in PS/2 Mouse Support doc * add explicit section ids to I2C Master Driver doc * reformat GPIO Controls table Much like the I2C Master Driver doc, I found this a bit less than ideal to read. (The table was actually wider than the space available for it.) Reformatted so each GPIO function is an H3 heading, followed by a paragraph and a table of each architecture's old-style function. * migrate changes from I2C Master Driver doc to Japanese translation * add explicit anchors to I2C Master Driver docs * fix code block language markers The language markers are case-sensitive; using the wrong case means the syntax highlighting doesn't work. Good: ```c Bad: ```C * restore Japanese I2C Master Driver doc to current master Can't update the internal tracking references accurately until the changes to the English doc are committed to master. * add explicit anchors to edited files * change ChibiOS/ARM to ARM/ChibiOS Because ARM/ATSAM is also a thing that exists. * fix code block language markers again Used the wrong markers in a few spots. Also these are apparently always supposed to be lowercase. * add section anchors to cli.md * restore table formatting on GPIO Control doc * remove changes to _summary.md
-rw-r--r--docs/cli.md12
-rw-r--r--docs/feature_pointing_device.md6
-rw-r--r--docs/feature_ps2_mouse.md59
-rw-r--r--docs/feature_rgb_matrix.md56
-rw-r--r--docs/feature_stenography.md28
-rw-r--r--docs/i2c_driver.md24
-rw-r--r--docs/internals_gpio_control.md26
7 files changed, 106 insertions, 105 deletions
diff --git a/docs/cli.md b/docs/cli.md
index 165f2a372..760fe1cdb 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,14 +1,14 @@
1# QMK CLI 1# QMK CLI :id=qmk-cli
2 2
3## Overview 3## Overview :id=overview
4 4
5The QMK CLI makes building and working with QMK keyboards easier. We have provided a number of commands to simplify and streamline tasks such as obtaining and compiling the QMK firmware, creating keymaps, and more. 5The QMK CLI makes building and working with QMK keyboards easier. We have provided a number of commands to simplify and streamline tasks such as obtaining and compiling the QMK firmware, creating keymaps, and more.
6 6
7### Requirements 7### Requirements :id=requirements
8 8
9The CLI requires Python 3.5 or greater. We try to keep the number of requirements small but you will also need to install the packages listed in [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt). These are installed automatically when you install the QMK CLI. 9The CLI requires Python 3.5 or greater. We try to keep the number of requirements small but you will also need to install the packages listed in [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt). These are installed automatically when you install the QMK CLI.
10 10
11### Install Using Homebrew (macOS, some Linux) 11### Install Using Homebrew (macOS, some Linux) :id=install-using-homebrew
12 12
13If you have installed [Homebrew](https://brew.sh) you can tap and install QMK: 13If you have installed [Homebrew](https://brew.sh) you can tap and install QMK:
14 14
@@ -19,7 +19,7 @@ export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
19qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment 19qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment
20``` 20```
21 21
22### Install Using easy_install or pip 22### Install Using easy_install or pip :id=install-using-easy_install-or-pip
23 23
24If your system is not listed above you can install QMK manually. First ensure that you have python 3.5 (or later) installed and have installed pip. Then install QMK with this command: 24If your system is not listed above you can install QMK manually. First ensure that you have python 3.5 (or later) installed and have installed pip. Then install QMK with this command:
25 25
@@ -29,7 +29,7 @@ export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
29qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment 29qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment
30``` 30```
31 31
32### Packaging For Other Operating Systems 32### Packaging For Other Operating Systems :id=packaging-for-other-operating-systems
33 33
34We are looking for people to create and maintain a `qmk` package for more operating systems. If you would like to create a package for your OS please follow these guidelines: 34We are looking for people to create and maintain a `qmk` package for more operating systems. If you would like to create a package for your OS please follow these guidelines:
35 35
diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md
index 8ad428939..b90c341d5 100644
--- a/docs/feature_pointing_device.md
+++ b/docs/feature_pointing_device.md
@@ -1,10 +1,10 @@
1## Pointing Device 1# Pointing Device :id=pointing-device
2 2
3Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around. There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and lightweight. You can implement custom keys to control functionality, or you can gather information from other peripherals and insert it directly here - let QMK handle the processing for you. 3Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around. There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and lightweight. You can implement custom keys to control functionality, or you can gather information from other peripherals and insert it directly here - let QMK handle the processing for you.
4 4
5To enable Pointing Device, uncomment the following line in your rules.mk: 5To enable Pointing Device, uncomment the following line in your rules.mk:
6 6
7``` 7```makefile
8POINTING_DEVICE_ENABLE = yes 8POINTING_DEVICE_ENABLE = yes
9``` 9```
10 10
@@ -25,7 +25,7 @@ When the mouse report is sent, the x, y, v, and h values are set to 0 (this is d
25 25
26In the following example, a custom key is used to click the mouse and scroll 127 units vertically and horizontally, then undo all of that when released - because that's a totally useful function. Listen, this is an example: 26In the following example, a custom key is used to click the mouse and scroll 127 units vertically and horizontally, then undo all of that when released - because that's a totally useful function. Listen, this is an example:
27 27
28``` 28```c
29case MS_SPECIAL: 29case MS_SPECIAL:
30 report_mouse_t currentReport = pointing_device_get_report(); 30 report_mouse_t currentReport = pointing_device_get_report();
31 if (record->event.pressed) 31 if (record->event.pressed)
diff --git a/docs/feature_ps2_mouse.md b/docs/feature_ps2_mouse.md
index d13896799..ce072fbe9 100644
--- a/docs/feature_ps2_mouse.md
+++ b/docs/feature_ps2_mouse.md
@@ -1,4 +1,4 @@
1## PS/2 Mouse Support 1# PS/2 Mouse Support :id=ps2-mouse-support
2 2
3Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device. 3Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device.
4 4
@@ -6,7 +6,7 @@ To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest fr
6 6
7There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended). 7There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended).
8 8
9### The Cirtuitry between Trackpoint and Controller 9## The Circuitry between Trackpoint and Controller :id=the-circuitry-between-trackpoint-and-controller
10 10
11To get the things working, a 4.7K drag is needed between the two lines DATA and CLK and the line 5+. 11To get the things working, a 4.7K drag is needed between the two lines DATA and CLK and the line 5+.
12 12
@@ -24,20 +24,20 @@ MODULE 5+ --------+--+--------- PWR CONTROLLER
24``` 24```
25 25
26 26
27### Busywait Version 27## Busywait Version :id=busywait-version
28 28
29Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible. 29Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible.
30 30
31In rules.mk: 31In rules.mk:
32 32
33``` 33```makefile
34PS2_MOUSE_ENABLE = yes 34PS2_MOUSE_ENABLE = yes
35PS2_USE_BUSYWAIT = yes 35PS2_USE_BUSYWAIT = yes
36``` 36```
37 37
38In your keyboard config.h: 38In your keyboard config.h:
39 39
40``` 40```c
41#ifdef PS2_USE_BUSYWAIT 41#ifdef PS2_USE_BUSYWAIT
42# define PS2_CLOCK_PORT PORTD 42# define PS2_CLOCK_PORT PORTD
43# define PS2_CLOCK_PIN PIND 43# define PS2_CLOCK_PIN PIND
@@ -50,20 +50,20 @@ In your keyboard config.h:
50#endif 50#endif
51``` 51```
52 52
53### Interrupt Version 53## Interrupt Version :id=interrupt-version
54 54
55The 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. 55The 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.
56 56
57In rules.mk: 57In rules.mk:
58 58
59``` 59```makefile
60PS2_MOUSE_ENABLE = yes 60PS2_MOUSE_ENABLE = yes
61PS2_USE_INT = yes 61PS2_USE_INT = yes
62``` 62```
63 63
64In your keyboard config.h: 64In your keyboard config.h:
65 65
66``` 66```c
67#ifdef PS2_USE_INT 67#ifdef PS2_USE_INT
68#define PS2_CLOCK_PORT PORTD 68#define PS2_CLOCK_PORT PORTD
69#define PS2_CLOCK_PIN PIND 69#define PS2_CLOCK_PIN PIND
@@ -88,20 +88,20 @@ In your keyboard config.h:
88#endif 88#endif
89``` 89```
90 90
91### USART Version 91## USART Version :id=usart-version
92 92
93To 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. 93To 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.
94 94
95In rules.mk: 95In rules.mk:
96 96
97``` 97```makefile
98PS2_MOUSE_ENABLE = yes 98PS2_MOUSE_ENABLE = yes
99PS2_USE_USART = yes 99PS2_USE_USART = yes
100``` 100```
101 101
102In your keyboard config.h: 102In your keyboard config.h:
103 103
104``` 104```c
105#ifdef PS2_USE_USART 105#ifdef PS2_USE_USART
106#define PS2_CLOCK_PORT PORTD 106#define PS2_CLOCK_PORT PORTD
107#define PS2_CLOCK_PIN PIND 107#define PS2_CLOCK_PIN PIND
@@ -145,13 +145,13 @@ In your keyboard config.h:
145#endif 145#endif
146``` 146```
147 147
148### Additional Settings 148## Additional Settings :id=additional-settings
149 149
150#### PS/2 Mouse Features 150### PS/2 Mouse Features :id=ps2-mouse-features
151 151
152These enable settings supported by the PS/2 mouse protocol. 152These enable settings supported by the PS/2 mouse protocol.
153 153
154``` 154```c
155/* Use remote mode instead of the default stream mode (see link) */ 155/* Use remote mode instead of the default stream mode (see link) */
156#define PS2_MOUSE_USE_REMOTE_MODE 156#define PS2_MOUSE_USE_REMOTE_MODE
157 157
@@ -170,7 +170,7 @@ These enable settings supported by the PS/2 mouse protocol.
170 170
171You can also call the following functions from ps2_mouse.h 171You can also call the following functions from ps2_mouse.h
172 172
173``` 173```c
174void ps2_mouse_disable_data_reporting(void); 174void ps2_mouse_disable_data_reporting(void);
175 175
176void ps2_mouse_enable_data_reporting(void); 176void ps2_mouse_enable_data_reporting(void);
@@ -188,36 +188,36 @@ void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution);
188void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate); 188void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate);
189``` 189```
190 190
191#### Fine Control 191### Fine Control :id=fine-control
192 192
193Use the following defines to change the sensitivity and speed of the mouse. 193Use the following defines to change the sensitivity and speed of the mouse.
194Note: you can also use `ps2_mouse_set_resolution` for the same effect (not supported on most touchpads). 194Note: you can also use `ps2_mouse_set_resolution` for the same effect (not supported on most touchpads).
195 195
196``` 196```c
197#define PS2_MOUSE_X_MULTIPLIER 3 197#define PS2_MOUSE_X_MULTIPLIER 3
198#define PS2_MOUSE_Y_MULTIPLIER 3 198#define PS2_MOUSE_Y_MULTIPLIER 3
199#define PS2_MOUSE_V_MULTIPLIER 1 199#define PS2_MOUSE_V_MULTIPLIER 1
200``` 200```
201 201
202#### Scroll Button 202### Scroll Button :id=scroll-button
203 203
204If you're using a trackpoint, you will likely want to be able to use it for scrolling. 204If you're using a trackpoint, you will likely want to be able to use it for scrolling.
205It's possible to enable a "scroll button/s" that when pressed will cause the mouse to scroll instead of moving. 205It's possible to enable a "scroll button/s" that when pressed will cause the mouse to scroll instead of moving.
206To enable the feature, you must set a scroll button mask as follows: 206To enable the feature, you must set a scroll button mask as follows:
207 207
208``` 208```c
209#define PS2_MOUSE_SCROLL_BTN_MASK (1<<PS2_MOUSE_BUTTON_MIDDLE) /* Default */ 209#define PS2_MOUSE_SCROLL_BTN_MASK (1<<PS2_MOUSE_BUTTON_MIDDLE) /* Default */
210``` 210```
211 211
212To disable the scroll button feature: 212To disable the scroll button feature:
213 213
214``` 214```c
215#define PS2_MOUSE_SCROLL_BTN_MASK 0 215#define PS2_MOUSE_SCROLL_BTN_MASK 0
216``` 216```
217 217
218The available buttons are: 218The available buttons are:
219 219
220``` 220```c
221#define PS2_MOUSE_BTN_LEFT 0 221#define PS2_MOUSE_BTN_LEFT 0
222#define PS2_MOUSE_BTN_RIGHT 1 222#define PS2_MOUSE_BTN_RIGHT 1
223#define PS2_MOUSE_BTN_MIDDLE 2 223#define PS2_MOUSE_BTN_MIDDLE 2
@@ -229,27 +229,28 @@ Once you've configured your scroll button mask, you must configure the scroll bu
229This is the interval before which if the scroll buttons were released they would be sent to the host. 229This is the interval before which if the scroll buttons were released they would be sent to the host.
230After this interval, they will cause the mouse to scroll and will not be sent. 230After this interval, they will cause the mouse to scroll and will not be sent.
231 231
232``` 232```c
233#define PS2_MOUSE_SCROLL_BTN_SEND 300 /* Default */ 233#define PS2_MOUSE_SCROLL_BTN_SEND 300 /* Default */
234``` 234```
235 235
236To disable sending the scroll buttons: 236To disable sending the scroll buttons:
237``` 237
238```c
238#define PS2_MOUSE_SCROLL_BTN_SEND 0 239#define PS2_MOUSE_SCROLL_BTN_SEND 0
239``` 240```
240 241
241Fine control over the scrolling is supported with the following defines: 242Fine control over the scrolling is supported with the following defines:
242 243
243``` 244```c
244#define PS2_MOUSE_SCROLL_DIVISOR_H 2 245#define PS2_MOUSE_SCROLL_DIVISOR_H 2
245#define PS2_MOUSE_SCROLL_DIVISOR_V 2 246#define PS2_MOUSE_SCROLL_DIVISOR_V 2
246``` 247```
247 248
248#### Invert Mouse and Scroll Axes 249### Invert Mouse and Scroll Axes :id=invert-mouse-and-scroll-axes
249 250
250To invert the X and Y axes you can put: 251To invert the X and Y axes you can put:
251 252
252``` 253```c
253#define PS2_MOUSE_INVERT_X 254#define PS2_MOUSE_INVERT_X
254#define PS2_MOUSE_INVERT_Y 255#define PS2_MOUSE_INVERT_Y
255``` 256```
@@ -258,18 +259,18 @@ into config.h.
258 259
259To reverse the scroll axes you can put: 260To reverse the scroll axes you can put:
260 261
261``` 262```c
262#define PS2_MOUSE_INVERT_H 263#define PS2_MOUSE_INVERT_H
263#define PS2_MOUSE_INVERT_V 264#define PS2_MOUSE_INVERT_V
264``` 265```
265 266
266into config.h. 267into config.h.
267 268
268#### Debug Settings 269### Debug Settings :id=debug-settings
269 270
270To debug the mouse, add `debug_mouse = true` or enable via bootmagic. 271To debug the mouse, add `debug_mouse = true` or enable via bootmagic.
271 272
272``` 273```c
273/* To debug the mouse reports */ 274/* To debug the mouse reports */
274#define PS2_MOUSE_DEBUG_HID 275#define PS2_MOUSE_DEBUG_HID
275#define PS2_MOUSE_DEBUG_RAW 276#define PS2_MOUSE_DEBUG_RAW
diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md
index 23082ef2a..7bc219347 100644
--- a/docs/feature_rgb_matrix.md
+++ b/docs/feature_rgb_matrix.md
@@ -1,22 +1,22 @@
1# RGB Matrix Lighting 1# RGB Matrix Lighting :id=rgb-matrix-lighting
2 2
3This feature allows you to use RGB LED matrices driven by external drivers. It hooks into the RGBLIGHT system so you can use the same keycodes as RGBLIGHT to control it. 3This feature allows you to use RGB LED matrices driven by external drivers. It hooks into the RGBLIGHT system so you can use the same keycodes as RGBLIGHT to control it.
4 4
5If you want to use single color LED's you should use the [LED Matrix Subsystem](feature_led_matrix.md) instead. 5If you want to use single color LED's you should use the [LED Matrix Subsystem](feature_led_matrix.md) instead.
6 6
7## Driver configuration 7## Driver configuration :id=driver-configuration
8--- 8---
9### IS31FL3731 9### IS31FL3731 :id=is31fl3731
10 10
11There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`: 11There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
12 12
13```C 13```makefile
14RGB_MATRIX_ENABLE = IS31FL3731 14RGB_MATRIX_ENABLE = IS31FL3731
15``` 15```
16 16
17Configure the hardware via your `config.h`: 17Configure the hardware via your `config.h`:
18 18
19```C 19```c
20// This is a 7-bit address, that gets left-shifted and bit 0 20// This is a 7-bit address, that gets left-shifted and bit 0
21// set to 0 for write, 1 for read (as per I2C protocol) 21// set to 0 for write, 1 for read (as per I2C protocol)
22// The address will vary depending on your wiring: 22// The address will vary depending on your wiring:
@@ -39,7 +39,7 @@ Currently only 2 drivers are supported, but it would be trivial to support all 4
39 39
40Define these arrays listing all the LEDs in your `<keyboard>.c`: 40Define these arrays listing all the LEDs in your `<keyboard>.c`:
41 41
42```C 42```c
43const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { 43const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
44/* Refer to IS31 manual for these locations 44/* Refer to IS31 manual for these locations
45 * driver 45 * driver
@@ -55,19 +55,19 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
55Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0` or `1` right now). 55Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0` or `1` right now).
56 56
57--- 57---
58### IS31FL3733/IS31FL3737 58### IS31FL3733/IS31FL3737 :id=is31fl3733is31fl3737
59 59
60!> For the IS31FL3737, replace all instances of `IS31FL3733` below with `IS31FL3737`. 60!> For the IS31FL3737, replace all instances of `IS31FL3733` below with `IS31FL3737`.
61 61
62There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`: 62There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`:
63 63
64```C 64```makefile
65RGB_MATRIX_ENABLE = IS31FL3733 65RGB_MATRIX_ENABLE = IS31FL3733
66``` 66```
67 67
68Configure the hardware via your `config.h`: 68Configure the hardware via your `config.h`:
69 69
70```C 70```c
71// This is a 7-bit address, that gets left-shifted and bit 0 71// This is a 7-bit address, that gets left-shifted and bit 0
72// set to 0 for write, 1 for read (as per I2C protocol) 72// set to 0 for write, 1 for read (as per I2C protocol)
73// The address will vary depending on your wiring: 73// The address will vary depending on your wiring:
@@ -90,7 +90,7 @@ Currently only a single drivers is supported, but it would be trivial to support
90 90
91Define these arrays listing all the LEDs in your `<keyboard>.c`: 91Define these arrays listing all the LEDs in your `<keyboard>.c`:
92 92
93```C 93```c
94const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { 94const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
95/* Refer to IS31 manual for these locations 95/* Refer to IS31 manual for these locations
96 * driver 96 * driver
@@ -107,17 +107,17 @@ Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](
107 107
108--- 108---
109 109
110### WS2812 110### WS2812 :id=ws2812
111 111
112There is basic support for addressable RGB matrix lighting with a WS2811/WS2812{a,b,c} addressable LED strand. To enable it, add this to your `rules.mk`: 112There is basic support for addressable RGB matrix lighting with a WS2811/WS2812{a,b,c} addressable LED strand. To enable it, add this to your `rules.mk`:
113 113
114```C 114```makefile
115RGB_MATRIX_ENABLE = WS2812 115RGB_MATRIX_ENABLE = WS2812
116``` 116```
117 117
118Configure the hardware via your `config.h`: 118Configure the hardware via your `config.h`:
119 119
120```C 120```c
121// The pin connected to the data pin of the LEDs 121// The pin connected to the data pin of the LEDs
122#define RGB_DI_PIN D7 122#define RGB_DI_PIN D7
123// The number of LEDs connected 123// The number of LEDs connected
@@ -128,7 +128,7 @@ Configure the hardware via your `config.h`:
128 128
129From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example: 129From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example:
130 130
131```C 131```c
132const led_config_t g_led_config = { { 132const led_config_t g_led_config = { {
133 // Key Matrix to LED Index 133 // Key Matrix to LED Index
134 { 5, NO_LED, NO_LED, 0 }, 134 { 5, NO_LED, NO_LED, 0 },
@@ -146,7 +146,7 @@ const led_config_t g_led_config = { {
146 146
147The first part, `// Key Matrix to LED Index`, tells the system what key this LED represents by using the key's electrical matrix row & col. The second part, `// LED Index to Physical Position` represents the LED's physical `{ x, y }` position on the keyboard. The default expected range of values for `{ x, y }` is the inclusive range `{ 0..224, 0..64 }`. This default expected range is due to effects that calculate the center of the keyboard for their animations. The easiest way to calculate these positions is imagine your keyboard is a grid, and the top left of the keyboard represents `{ x, y }` coordinate `{ 0, 0 }` and the bottom right of your keyboard represents `{ 224, 64 }`. Using this as a basis, you can use the following formula to calculate the physical position: 147The first part, `// Key Matrix to LED Index`, tells the system what key this LED represents by using the key's electrical matrix row & col. The second part, `// LED Index to Physical Position` represents the LED's physical `{ x, y }` position on the keyboard. The default expected range of values for `{ x, y }` is the inclusive range `{ 0..224, 0..64 }`. This default expected range is due to effects that calculate the center of the keyboard for their animations. The easiest way to calculate these positions is imagine your keyboard is a grid, and the top left of the keyboard represents `{ x, y }` coordinate `{ 0, 0 }` and the bottom right of your keyboard represents `{ 224, 64 }`. Using this as a basis, you can use the following formula to calculate the physical position:
148 148
149```C 149```c
150x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION 150x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION
151y = 64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION 151y = 64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION
152``` 152```
@@ -157,7 +157,7 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{
157 157
158`// LED Index to Flag` is a bitmask, whether or not a certain LEDs is of a certain type. It is recommended that LEDs are set to only 1 type. 158`// LED Index to Flag` is a bitmask, whether or not a certain LEDs is of a certain type. It is recommended that LEDs are set to only 1 type.
159 159
160## Flags 160## Flags :id=flags
161 161
162|Define |Description | 162|Define |Description |
163|------------------------------------|-------------------------------------------| 163|------------------------------------|-------------------------------------------|
@@ -169,7 +169,7 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{
169|`#define LED_FLAG_UNDERGLOW 0x02` |If the LED is for underglow. | 169|`#define LED_FLAG_UNDERGLOW 0x02` |If the LED is for underglow. |
170|`#define LED_FLAG_KEYLIGHT 0x04` |If the LED is for key backlight. | 170|`#define LED_FLAG_KEYLIGHT 0x04` |If the LED is for key backlight. |
171 171
172## Keycodes 172## Keycodes :id=keycodes
173 173
174All RGB keycodes are currently shared with the RGBLIGHT system: 174All RGB keycodes are currently shared with the RGBLIGHT system:
175 175
@@ -189,11 +189,11 @@ All RGB keycodes are currently shared with the RGBLIGHT system:
189 189
190* `RGB_MODE_*` keycodes will generally work, but are not currently mapped to the correct effects for the RGB Matrix system 190* `RGB_MODE_*` keycodes will generally work, but are not currently mapped to the correct effects for the RGB Matrix system
191 191
192## RGB Matrix Effects 192## RGB Matrix Effects :id=rgb-matrix-effects
193 193
194All effects have been configured to support current configuration values (Hue, Saturation, Value, & Speed) unless otherwise noted below. These are the effects that are currently available: 194All effects have been configured to support current configuration values (Hue, Saturation, Value, & Speed) unless otherwise noted below. These are the effects that are currently available:
195 195
196```C 196```c
197enum rgb_matrix_effects { 197enum rgb_matrix_effects {
198 RGB_MATRIX_NONE = 0, 198 RGB_MATRIX_NONE = 0,
199 RGB_MATRIX_SOLID_COLOR = 1, // Static single hue, no speed support 199 RGB_MATRIX_SOLID_COLOR = 1, // Static single hue, no speed support
@@ -285,7 +285,7 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con
285|`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Disables `RGB_MATRIX_SOLID_MULTISPLASH` | 285|`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Disables `RGB_MATRIX_SOLID_MULTISPLASH` |
286 286
287 287
288## Custom RGB Matrix Effects 288## Custom RGB Matrix Effects :id=custom-rgb-matrix-effects
289 289
290By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rules.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files. 290By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rules.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files.
291 291
@@ -294,7 +294,7 @@ To declare new effects, create a new `rgb_matrix_user/kb.inc` that looks somethi
294`rgb_matrix_user.inc` should go in the root of the keymap directory. 294`rgb_matrix_user.inc` should go in the root of the keymap directory.
295`rgb_matrix_kb.inc` should go in the root of the keyboard directory. 295`rgb_matrix_kb.inc` should go in the root of the keyboard directory.
296 296
297```C 297```c
298// !!! DO NOT ADD #pragma once !!! // 298// !!! DO NOT ADD #pragma once !!! //
299 299
300// Step 1. 300// Step 1.
@@ -341,7 +341,7 @@ static bool my_cool_effect2(effect_params_t* params) {
341For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix_animation/` 341For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix_animation/`
342 342
343 343
344## Colors 344## Colors :id=colors
345 345
346These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions. 346These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.
347 347
@@ -369,9 +369,9 @@ These are shorthands to popular colors. The `RGB` ones can be passed to the `set
369These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list! 369These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list!
370 370
371 371
372## Additional `config.h` Options 372## Additional `config.h` Options :id=additional-configh-options
373 373
374```C 374```c
375#define RGB_MATRIX_KEYPRESSES // reacts to keypresses 375#define RGB_MATRIX_KEYPRESSES // reacts to keypresses
376#define RGB_MATRIX_KEYRELEASES // reacts to keyreleases (instead of keypresses) 376#define RGB_MATRIX_KEYRELEASES // reacts to keyreleases (instead of keypresses)
377#define RGB_DISABLE_AFTER_TIMEOUT 0 // number of ticks to wait until disabling effects 377#define RGB_DISABLE_AFTER_TIMEOUT 0 // number of ticks to wait until disabling effects
@@ -386,21 +386,21 @@ These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blo
386#define RGB_MATRIX_STARTUP_SPD 127 // Sets the default animation speed, if none has been set 386#define RGB_MATRIX_STARTUP_SPD 127 // Sets the default animation speed, if none has been set
387``` 387```
388 388
389## EEPROM storage 389## EEPROM storage :id=eeprom-storage
390 390
391The EEPROM for it is currently shared with the RGBLIGHT system (it's generally assumed only one RGB would be used at a time), but could be configured to use its own 32bit address with: 391The EEPROM for it is currently shared with the RGBLIGHT system (it's generally assumed only one RGB would be used at a time), but could be configured to use its own 32bit address with:
392 392
393```C 393```c
394#define EECONFIG_RGB_MATRIX (uint32_t *)28 394#define EECONFIG_RGB_MATRIX (uint32_t *)28
395``` 395```
396 396
397Where `28` is an unused index from `eeconfig.h`. 397Where `28` is an unused index from `eeconfig.h`.
398 398
399## Suspended state 399## Suspended state :id=suspended-state
400 400
401To use the suspend feature, add this to your `<keyboard>.c`: 401To use the suspend feature, add this to your `<keyboard>.c`:
402 402
403```C 403```c
404void suspend_power_down_kb(void) 404void suspend_power_down_kb(void)
405{ 405{
406 rgb_matrix_set_suspend_state(true); 406 rgb_matrix_set_suspend_state(true);
diff --git a/docs/feature_stenography.md b/docs/feature_stenography.md
index 4d7374a03..099993f85 100644
--- a/docs/feature_stenography.md
+++ b/docs/feature_stenography.md
@@ -1,16 +1,16 @@
1# Stenography in QMK 1# Stenography in QMK :id=stenography-in-qmk
2 2
3[Stenography](https://en.wikipedia.org/wiki/Stenotype) is a method of writing most often used by court reports, closed-captioning, and real-time transcription for the deaf. In stenography words are chorded syllable by syllable with a mixture of spelling, phonetic, and shortcut (briefs) strokes. Professional stenographers can reach 200-300 WPM without any of the strain usually found in standard typing and with far fewer errors (>99.9% accuracy). 3[Stenography](https://en.wikipedia.org/wiki/Stenotype) is a method of writing most often used by court reports, closed-captioning, and real-time transcription for the deaf. In stenography words are chorded syllable by syllable with a mixture of spelling, phonetic, and shortcut (briefs) strokes. Professional stenographers can reach 200-300 WPM without any of the strain usually found in standard typing and with far fewer errors (>99.9% accuracy).
4 4
5The [Open Steno Project](http://www.openstenoproject.org/) has built an open-source program called Plover that provides real-time translation of steno strokes into words and commands. It has an established dictionary and supports 5The [Open Steno Project](http://www.openstenoproject.org/) has built an open-source program called Plover that provides real-time translation of steno strokes into words and commands. It has an established dictionary and supports
6 6
7## Plover with QWERTY Keyboard 7## Plover with QWERTY Keyboard :id=plover-with-qwerty-keyboard
8 8
9Plover can work with any standard QWERTY keyboard, although it is more efficient if the keyboard supports NKRO (n-key rollover) to allow Plover to see all the pressed keys at once. An example keymap for Plover can be found in `planck/keymaps/default`. Switching to the `PLOVER` layer adjusts the position of the keyboard to support the number bar. 9Plover can work with any standard QWERTY keyboard, although it is more efficient if the keyboard supports NKRO (n-key rollover) to allow Plover to see all the pressed keys at once. An example keymap for Plover can be found in `planck/keymaps/default`. Switching to the `PLOVER` layer adjusts the position of the keyboard to support the number bar.
10 10
11To use Plover with QMK just enable NKRO and optionally adjust your layout if you have anything other than a standard layout. You may also want to purchase some steno-friendly keycaps to make it easier to hit multiple keys. 11To use Plover with QMK just enable NKRO and optionally adjust your layout if you have anything other than a standard layout. You may also want to purchase some steno-friendly keycaps to make it easier to hit multiple keys.
12 12
13## Plover with Steno Protocol 13## Plover with Steno Protocol :id=plover-with-steno-protocol
14 14
15Plover also understands the language of several steno machines. QMK can speak a couple of these languages, TX Bolt and GeminiPR. An example layout can be found in `planck/keymaps/steno`. 15Plover also understands the language of several steno machines. QMK can speak a couple of these languages, TX Bolt and GeminiPR. An example layout can be found in `planck/keymaps/steno`.
16 16
@@ -20,26 +20,26 @@ In this mode Plover expects to speak with a steno machine over a serial port so
20 20
21> Note: Due to hardware limitations you may not be able to run both a virtual serial port and mouse emulation at the same time. 21> Note: Due to hardware limitations you may not be able to run both a virtual serial port and mouse emulation at the same time.
22 22
23### TX Bolt 23### TX Bolt :id=tx-bolt
24 24
25TX Bolt communicates the status of 24 keys over a very simple protocol in variable-sized (1-5 byte) packets. 25TX Bolt communicates the status of 24 keys over a very simple protocol in variable-sized (1-5 byte) packets.
26 26
27### GeminiPR 27### GeminiPR :id=geminipr
28 28
29GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything that is necessary for standard stenography, GeminiPR opens up many more options, including supporting non-English theories. 29GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything that is necessary for standard stenography, GeminiPR opens up many more options, including supporting non-English theories.
30 30
31## Configuring QMK for Steno 31## Configuring QMK for Steno :id=configuring-qmk-for-steno
32 32
33Firstly, enable steno in your keymap's Makefile. You may also need disable mousekeys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them. 33Firstly, enable steno in your keymap's Makefile. You may also need disable mousekeys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them.
34 34
35```Makefile 35```makefile
36STENO_ENABLE = yes 36STENO_ENABLE = yes
37MOUSEKEY_ENABLE = no 37MOUSEKEY_ENABLE = no
38``` 38```
39 39
40In your keymap create a new layer for Plover. You will need to include `keymap_steno.h`. See `planck/keymaps/steno/keymap.c` for an example. Remember to create a key to switch to the layer as well as a key for exiting the layer. If you would like to switch modes on the fly you can use the keycodes `QK_STENO_BOLT` and `QK_STENO_GEMINI`. If you only want to use one of the protocols you may set it up in your initialization function: 40In your keymap create a new layer for Plover. You will need to include `keymap_steno.h`. See `planck/keymaps/steno/keymap.c` for an example. Remember to create a key to switch to the layer as well as a key for exiting the layer. If you would like to switch modes on the fly you can use the keycodes `QK_STENO_BOLT` and `QK_STENO_GEMINI`. If you only want to use one of the protocols you may set it up in your initialization function:
41 41
42```C 42```c
43void matrix_init_user() { 43void matrix_init_user() {
44 steno_set_mode(STENO_MODE_GEMINI); // or STENO_MODE_BOLT 44 steno_set_mode(STENO_MODE_GEMINI); // or STENO_MODE_BOLT
45} 45}
@@ -49,37 +49,37 @@ Once you have your keyboard flashed launch Plover. Click the 'Configure...' butt
49 49
50On the display tab click 'Open stroke display'. With Plover disabled you should be able to hit keys on your keyboard and see them show up in the stroke display window. Use this to make sure you have set up your keymap correctly. You are now ready to steno! 50On the display tab click 'Open stroke display'. With Plover disabled you should be able to hit keys on your keyboard and see them show up in the stroke display window. Use this to make sure you have set up your keymap correctly. You are now ready to steno!
51 51
52## Learning Stenography 52## Learning Stenography :id=learning-stenography
53 53
54* [Learn Plover!](https://sites.google.com/site/learnplover/) 54* [Learn Plover!](https://sites.google.com/site/learnplover/)
55* [QWERTY Steno](http://qwertysteno.com/Home/) 55* [QWERTY Steno](http://qwertysteno.com/Home/)
56* [Steno Jig](https://joshuagrams.github.io/steno-jig/) 56* [Steno Jig](https://joshuagrams.github.io/steno-jig/)
57* More resources at the Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki 57* More resources at the Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki
58 58
59## Interfacing with the code 59## Interfacing with the code :id=interfacing-with-the-code
60 60
61The steno code has three interceptible hooks. If you define these functions, they will be called at certain points in processing; if they return true, processing continues, otherwise it's assumed you handled things. 61The steno code has three interceptible hooks. If you define these functions, they will be called at certain points in processing; if they return true, processing continues, otherwise it's assumed you handled things.
62 62
63```C 63```c
64bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[6]); 64bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[6]);
65``` 65```
66 66
67This function is called when a chord is about to be sent. Mode will be one of `STENO_MODE_BOLT` or `STENO_MODE_GEMINI`. This represents the actual chord that would be sent via whichever protocol. You can modify the chord provided to alter what gets sent. Remember to return true if you want the regular sending process to happen. 67This function is called when a chord is about to be sent. Mode will be one of `STENO_MODE_BOLT` or `STENO_MODE_GEMINI`. This represents the actual chord that would be sent via whichever protocol. You can modify the chord provided to alter what gets sent. Remember to return true if you want the regular sending process to happen.
68 68
69```C 69```c
70bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; } 70bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; }
71``` 71```
72 72
73This function is called when a keypress has come in, before it is processed. The keycode should be one of `QK_STENO_BOLT`, `QK_STENO_GEMINI`, or one of the `STN_*` key values. 73This function is called when a keypress has come in, before it is processed. The keycode should be one of `QK_STENO_BOLT`, `QK_STENO_GEMINI`, or one of the `STN_*` key values.
74 74
75```C 75```c
76bool postprocess_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed); 76bool postprocess_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed);
77``` 77```
78 78
79This function is called after a key has been processed, but before any decision about whether or not to send a chord. If `IS_PRESSED(record->event)` is false, and `pressed` is 0 or 1, the chord will be sent shortly, but has not yet been sent. This is where to put hooks for things like, say, live displays of steno chords or keys. 79This function is called after a key has been processed, but before any decision about whether or not to send a chord. If `IS_PRESSED(record->event)` is false, and `pressed` is 0 or 1, the chord will be sent shortly, but has not yet been sent. This is where to put hooks for things like, say, live displays of steno chords or keys.
80 80
81 81
82## Keycode Reference 82## Keycode Reference :id=keycode-reference
83 83
84As defined in `keymap_steno.h`. 84As defined in `keymap_steno.h`.
85 85
diff --git a/docs/i2c_driver.md b/docs/i2c_driver.md
index c9f53ef0d..d28a20fa1 100644
--- a/docs/i2c_driver.md
+++ b/docs/i2c_driver.md
@@ -1,8 +1,8 @@
1# I2C Master Driver 1# I2C Master Driver :id=i2c-master-driver
2 2
3The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs. 3The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs.
4 4
5## An important note on I2C Addresses 5## An important note on I2C Addresses :id=note-on-i2c-addresses
6 6
7All of the addresses expected by this driver should be pushed to the upper 7 bits of the address byte. Setting 7All of the addresses expected by this driver should be pushed to the upper 7 bits of the address byte. Setting
8the lower bit (indicating read/write) will be done by the respective functions. Almost all I2C addresses listed 8the lower bit (indicating read/write) will be done by the respective functions. Almost all I2C addresses listed
@@ -15,7 +15,7 @@ You can either do this on each call to the functions below, or once in your defi
15 15
16See https://www.robot-electronics.co.uk/i2c-tutorial for more information about I2C addressing and other technical details. 16See https://www.robot-electronics.co.uk/i2c-tutorial for more information about I2C addressing and other technical details.
17 17
18## Available functions 18## Available functions :id=available-functions
19 19
20|Function |Description | 20|Function |Description |
21|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 21|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -27,7 +27,7 @@ See https://www.robot-electronics.co.uk/i2c-tutorial for more information about
27|`i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` |Same as the `i2c_receive` function but `regaddr` sets from where in the slave the data will be read. | 27|`i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` |Same as the `i2c_receive` function but `regaddr` sets from where in the slave the data will be read. |
28|`i2c_status_t i2c_stop(void);` |Ends an I2C transaction. | 28|`i2c_status_t i2c_stop(void);` |Ends an I2C transaction. |
29 29
30### Function Return 30### Function Return :id=function-return
31 31
32All the above functions, except `void i2c_init(void);` return the following truth table: 32All the above functions, except `void i2c_init(void);` return the following truth table:
33 33
@@ -38,9 +38,9 @@ All the above functions, except `void i2c_init(void);` return the following trut
38|`I2C_STATUS_TIMEOUT`|-2 |Operation timed out. | 38|`I2C_STATUS_TIMEOUT`|-2 |Operation timed out. |
39 39
40 40
41## AVR 41## AVR :id=avr
42 42
43### Configuration 43### Configuration :id=avr-configuration
44 44
45The following defines can be used to configure the I2C master driver. 45The following defines can be used to configure the I2C master driver.
46 46
@@ -50,12 +50,12 @@ The following defines can be used to configure the I2C master driver.
50 50
51AVRs usually have set GPIO which turn into I2C pins, therefore no further configuration is required. 51AVRs usually have set GPIO which turn into I2C pins, therefore no further configuration is required.
52 52
53## ARM 53## ARM :id=arm
54 54
55For ARM the Chibios I2C HAL driver is under the hood. 55For ARM the Chibios I2C HAL driver is under the hood.
56This section assumes an STM32 MCU. 56This section assumes an STM32 MCU.
57 57
58### Configuration 58### Configuration :id=arm-configuration
59 59
60The configuration for ARM MCUs can be quite complex as often there are multiple I2C drivers which can be assigned to a variety of ports. 60The configuration for ARM MCUs can be quite complex as often there are multiple I2C drivers which can be assigned to a variety of ports.
61 61
@@ -90,7 +90,7 @@ The ChibiOS I2C driver configuration depends on STM32 MCU:
90 STM32F1xx, STM32F2xx, STM32F4xx, STM32L0xx and STM32L1xx use I2Cv1; 90 STM32F1xx, STM32F2xx, STM32F4xx, STM32L0xx and STM32L1xx use I2Cv1;
91 STM32F0xx, STM32F3xx, STM32F7xx and STM32L4xx use I2Cv2; 91 STM32F0xx, STM32F3xx, STM32F7xx and STM32L4xx use I2Cv2;
92 92
93#### I2Cv1 93#### I2Cv1 :id=i2cv1
94STM32 MCUs allow for different clock and duty parameters when configuring I2Cv1. These can be modified using the following parameters, using <https://www.playembedded.org/blog/stm32-i2c-chibios/#I2Cv1_configuration_structure> as a reference: 94STM32 MCUs allow for different clock and duty parameters when configuring I2Cv1. These can be modified using the following parameters, using <https://www.playembedded.org/blog/stm32-i2c-chibios/#I2Cv1_configuration_structure> as a reference:
95 95
96| Variable | Default | 96| Variable | Default |
@@ -99,7 +99,7 @@ STM32 MCUs allow for different clock and duty parameters when configuring I2Cv1.
99| `I2C1_CLOCK_SPEED` | `100000` | 99| `I2C1_CLOCK_SPEED` | `100000` |
100| `I2C1_DUTY_CYCLE` | `STD_DUTY_CYCLE` | 100| `I2C1_DUTY_CYCLE` | `STD_DUTY_CYCLE` |
101 101
102#### I2Cv2 102#### I2Cv2 :id=i2cv2
103STM32 MCUs allow for different timing parameters when configuring I2Cv2. These can be modified using the following parameters, using <https://www.st.com/en/embedded-software/stsw-stm32126.html> as a reference: 103STM32 MCUs allow for different timing parameters when configuring I2Cv2. These can be modified using the following parameters, using <https://www.st.com/en/embedded-software/stsw-stm32126.html> as a reference:
104 104
105| Variable | Default | 105| Variable | Default |
@@ -117,10 +117,10 @@ STM32 MCUs allow for different "alternate function" modes when configuring GPIO
117| `I2C1_SCL_PAL_MODE` | `4` | 117| `I2C1_SCL_PAL_MODE` | `4` |
118| `I2C1_SDA_PAL_MODE` | `4` | 118| `I2C1_SDA_PAL_MODE` | `4` |
119 119
120#### Other 120#### Other :id=other
121You can also overload the `void i2c_init(void)` function, which has a weak attribute. If you do this the configuration variables above will not be used. Please consult the datasheet of your MCU for the available GPIO configurations. The following is an example initialization function: 121You can also overload the `void i2c_init(void)` function, which has a weak attribute. If you do this the configuration variables above will not be used. Please consult the datasheet of your MCU for the available GPIO configurations. The following is an example initialization function:
122 122
123```C 123```c
124void i2c_init(void) 124void i2c_init(void)
125{ 125{
126 setPinInput(B6); // Try releasing special pins for a short time 126 setPinInput(B6); // Try releasing special pins for a short time
diff --git a/docs/internals_gpio_control.md b/docs/internals_gpio_control.md
index 8b8351382..74ac09035 100644
--- a/docs/internals_gpio_control.md
+++ b/docs/internals_gpio_control.md
@@ -1,22 +1,22 @@
1# GPIO Control 1# GPIO Control :id=gpio-control
2 2
3QMK has a GPIO control abstraction layer which is microcontroller agnostic. This is done to allow easy access to pin control across different platforms. 3QMK has a GPIO control abstraction layer which is microcontroller agnostic. This is done to allow easy access to pin control across different platforms.
4 4
5## Functions 5## Functions :id=functions
6 6
7The following functions can provide basic control of GPIOs and are found in `quantum/quantum.h`. 7The following functions can provide basic control of GPIOs and are found in `quantum/quantum.h`.
8 8
9|Function |Description | Old AVR Examples | Old ChibiOS/ARM Examples | 9|Function |Description | Old AVR Examples | Old ChibiOS/ARM Examples |
10|----------------------|------------------------------------------------------------------|------------------------------------------------|-------------------------------------------------| 10|------------------------|--------------------------------------------------|-------------------------------------------------|-------------------------------------------------|
11|`setPinInput(pin)` |Set pin as input with high impedance (High-Z) | `DDRB &= ~(1<<2)` | `palSetLineMode(pin, PAL_MODE_INPUT)` | 11| `setPinInput(pin)` | Set pin as input with high impedance (High-Z) | `DDRB &= ~(1<<2)` | `palSetLineMode(pin, PAL_MODE_INPUT)` |
12|`setPinInputHigh(pin)`|Set pin as input with builtin pull-up resistor | `DDRB &= ~(1<<2); PORTB \|= (1<<2)` | `palSetLineMode(pin, PAL_MODE_INPUT_PULLUP)` | 12| `setPinInputHigh(pin)` | Set pin as input with builtin pull-up resistor | `DDRB &= ~(1<<2); PORTB \|= (1<<2)` | `palSetLineMode(pin, PAL_MODE_INPUT_PULLUP)` |
13|`setPinInputLow(pin)` |Set pin as input with builtin pull-down resistor | N/A (Not supported on AVR) | `palSetLineMode(pin, PAL_MODE_INPUT_PULLDOWN)` | 13| `setPinInputLow(pin)` | Set pin as input with builtin pull-down resistor | N/A (Not supported on AVR) | `palSetLineMode(pin, PAL_MODE_INPUT_PULLDOWN)` |
14|`setPinOutput(pin)` |Set pin as output | `DDRB \|= (1<<2)` | `palSetLineMode(pin, PAL_MODE_OUTPUT_PUSHPULL)` | 14| `setPinOutput(pin)` | Set pin as output | `DDRB \|= (1<<2)` | `palSetLineMode(pin, PAL_MODE_OUTPUT_PUSHPULL)` |
15|`writePinHigh(pin)` |Set pin level as high, assuming it is an output | `PORTB \|= (1<<2)` | `palSetLine(pin)` | 15| `writePinHigh(pin)` | Set pin level as high, assuming it is an output | `PORTB \|= (1<<2)` | `palSetLine(pin)` |
16|`writePinLow(pin)` |Set pin level as low, assuming it is an output | `PORTB &= ~(1<<2)` | `palClearLine(pin)` | 16| `writePinLow(pin)` | Set pin level as low, assuming it is an output | `PORTB &= ~(1<<2)` | `palClearLine(pin)` |
17|`writePin(pin, level)`|Set pin level, assuming it is an output | `(level) ? PORTB \|= (1<<2) : PORTB &= ~(1<<2)` | `(level) ? palSetLine(pin) : palClearLine(pin)` | 17| `writePin(pin, level)` | Set pin level, assuming it is an output | `(level) ? PORTB \|= (1<<2) : PORTB &= ~(1<<2)` | `(level) ? palSetLine(pin) : palClearLine(pin)` |
18|`readPin(pin)` |Returns the level of the pin | `_SFR_IO8(pin >> 4) & _BV(pin & 0xF)` | `palReadLine(pin)` | 18| `readPin(pin)` | Returns the level of the pin | `_SFR_IO8(pin >> 4) & _BV(pin & 0xF)` | `palReadLine(pin)` |
19 19
20## Advanced Settings 20## Advanced Settings :id=advanced-settings
21 21
22Each microcontroller can have multiple advanced settings regarding its GPIO. This abstraction layer does not limit the use of architecture-specific functions. Advanced users should consult the datasheet of their desired device and include any needed libraries. For AVR, the standard avr/io.h library is used; for STM32, the ChibiOS [PAL library](http://chibios.sourceforge.net/docs3/hal/group___p_a_l.html) is used. 22Each microcontroller can have multiple advanced settings regarding its GPIO. This abstraction layer does not limit the use of architecture-specific functions. Advanced users should consult the datasheet of their desired device and include any needed libraries. For AVR, the standard avr/io.h library is used; for STM32, the ChibiOS [PAL library](http://chibios.sourceforge.net/docs3/hal/group___p_a_l.html) is used.