qmk/qmk_firmware
1
0
Fork 0
mirror of https://github.com/qmk/qmk_firmware.git synced 2026-09-30 05:50:43 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/develop' into xap

Browse Source
This commit is contained in:
Drashna Jael're
2022-09-29 13:30:12 -07:00
parent b0fcd50f22 d44b5b512a
commit 5db8ab38d9
225 changed files with 5934 additions and 1391 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/config_options.md
+11 -1
View File
@@ -2,7 +2,17 @@
QMK is nearly infinitely configurable. Wherever possible we err on the side of allowing users to customize their keyboard, even at the expense of code size. That level of flexibility makes for a daunting configuration experience, however.
There are two main types of configuration files in QMK- `config.h` and `rules.mk`. These files exist at various levels in QMK and all files of the same type are combined to build the final configuration. The levels, from lowest priority to highest priority, are:
There are three main types of configuration files in QMK:
* `config.h`, which contains various preprocessor directives (`#define`, `#ifdef`)
* `rules.mk`, which contains additional variables
* `info.json`, which is utilized for [data-driven configuration](https://docs.qmk.fm/#/data_driven_config)
This page will only discuss the first two types, `config.h` and `rules.mk`.
?> While not all settings have data-driven equivalents yet, keyboard makers are encouraged to utilize the `info.json` file to set the metadata for their boards when possible. See the [`info.json` Format](https://docs.qmk.fm/#/reference_info_json) page for more details.
These files exist at various levels in QMK and all files of the same type are combined to build the final configuration. The levels, from lowest priority to highest priority, are:
* QMK Default
* Keyboard
docs/feature_joystick.md
+27 -54
View File
@@ -70,71 +70,44 @@ When the ADC reads 900 or higher, the returned axis value will be -127, whereas
In this example, the first axis will be read from the `A4` pin while `B0` is set high and `A7` is set low, using `analogReadPin()`, whereas the second axis will not be read.
In order to give a value to the second axis, you can do so in any customizable entry point: as an action, in `process_record_user()` or in `matrix_scan_user()`, or even in `joystick_task()` which is called even when no key has been pressed.
You assign a value by writing to `joystick_status.axes[axis_index]` a signed 8-bit value (ranging from -127 to 127). Then it is necessary to assign the flag `JS_UPDATED` to `joystick_status.status` in order for an updated HID report to be sent.
#### Virtual Axes
The following example writes two axes based on keypad presses, with `KC_P5` as a precision modifier:
To give a value to virtual axes, call `joystick_set_axis(axis, value)`.
The following example adjusts two virtual axes (X and Y) based on keypad presses, with `KC_P5` as a precision modifier:
```c
#ifdef ANALOG_JOYSTICK_ENABLE
static uint8_t precision_val = 70;
static uint8_t axesFlags = 0;
enum axes {
Precision = 1,
Axis1High = 2,
Axis1Low = 4,
Axis2High = 8,
Axis2Low = 16
joystick_config_t joystick_axes[JOYSTICK_AXES_COUNT] = {
[0] = JOYSTICK_AXIS_VIRTUAL, // x
[1] = JOYSTICK_AXIS_VIRTUAL // y
};
#endif
static bool precision = false;
static uint16_t precision_mod = 64;
static uint16_t axis_val = 127;
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch(keycode) {
#ifdef ANALOG_JOYSTICK_ENABLE
// virtual joystick
# if JOYSTICK_AXES_COUNT > 1
int16_t precision_val = axis_val;
if (precision) {
precision_val -= precision_mod;
}
switch (keycode) {
case KC_P8:
if (record->event.pressed) {
axesFlags |= Axis2Low;
} else {
axesFlags &= ~Axis2Low;
}
joystick_status.status |= JS_UPDATED;
break;
joystick_set_axis(1, record->event.pressed ? -precision_val : 0);
return false;
case KC_P2:
if (record->event.pressed) {
axesFlags |= Axis2High;
} else {
axesFlags &= ~Axis2High;
}
joystick_status.status |= JS_UPDATED;
break;
# endif
joystick_set_axis(1, record->event.pressed ? precision_val : 0);
return false;
case KC_P4:
if (record->event.pressed) {
axesFlags |= Axis1Low;
} else {
axesFlags &= ~Axis1Low;
}
joystick_status.status |= JS_UPDATED;
break;
joystick_set_axis(0, record->event.pressed ? -precision_val : 0);
return false;
case KC_P6:
if (record->event.pressed) {
axesFlags |= Axis1High;
} else {
axesFlags &= ~Axis1High;
}
joystick_status.status |= JS_UPDATED;
break;
joystick_set_axis(0, record->event.pressed ? precision_val : 0);
return false;
case KC_P5:
if (record->event.pressed) {
axesFlags |= Precision;
} else {
axesFlags &= ~Precision;
}
joystick_status.status |= JS_UPDATED;
break;
#endif
precision = record->event.pressed;
return false;
}
return true;
}
docs/feature_tap_dance.md
+1 -1
View File
@@ -42,7 +42,7 @@ For more complicated cases, like blink the LEDs, fiddle with the backlighting, a
Well, that's the bulk of it! You should now be able to work through the examples below, and to develop your own Tap Dance functionality. But if you want a deeper understanding of what's going on behind the scenes, then read on for the explanation of how it all works!
Let's go over the three functions mentioned in `ACTION_TAP_DANCE_FN_ADVANCED` in a little more detail. They all receive the same too arguments: a pointer to a structure that holds all dance related state information, and a pointer to a use case specific state variable. The three functions differ in when they are called. The first, `on_each_tap_fn()`, is called every time the tap dance key is *pressed*. Before it is called, the counter is incremented and the timer is reset. The second function, `on_dance_finished_fn()`, is called when the tap dance is interrupted or ends because `TAPPING_TERM` milliseconds have passed since the last tap. When the `finished` field of the dance state structure is set to `true`, the `on_dance_finished_fn()` is skipped. After `on_dance_finished_fn()` was called or would have been called, but no sooner than when the tap dance key is *released*, `on_dance_reset_fn()` is called. It is possible to end a tap dance immediately, skipping `on_dance_finished_fn()`, but not `on_dance_reset_fn`, by calling `reset_tap_dance(state)`.
Let's go over the three functions mentioned in `ACTION_TAP_DANCE_FN_ADVANCED` in a little more detail. They all receive the same two arguments: a pointer to a structure that holds all dance related state information, and a pointer to a use case specific state variable. The three functions differ in when they are called. The first, `on_each_tap_fn()`, is called every time the tap dance key is *pressed*. Before it is called, the counter is incremented and the timer is reset. The second function, `on_dance_finished_fn()`, is called when the tap dance is interrupted or ends because `TAPPING_TERM` milliseconds have passed since the last tap. When the `finished` field of the dance state structure is set to `true`, the `on_dance_finished_fn()` is skipped. After `on_dance_finished_fn()` was called or would have been called, but no sooner than when the tap dance key is *released*, `on_dance_reset_fn()` is called. It is possible to end a tap dance immediately, skipping `on_dance_finished_fn()`, but not `on_dance_reset_fn`, by calling `reset_tap_dance(state)`.
To accomplish this logic, the tap dance mechanics use three entry points. The main entry point is `process_tap_dance()`, called from `process_record_quantum()` *after* `process_record_kb()` and `process_record_user()`. This function is responsible for calling `on_each_tap_fn()` and `on_dance_reset_fn()`. In order to handle interruptions of a tap dance, another entry point, `preprocess_tap_dance()` is run right at the beginning of `process_record_quantum()`. This function checks whether the key pressed is a tap-dance key. If it is not, and a tap-dance was in action, we handle that first, and enqueue the newly pressed key. If it is a tap-dance key, then we check if it is the same as the already active one (if there's one active, that is). If it is not, we fire off the old one first, then register the new one. Finally, `tap_dance_task()` periodically checks whether `TAPPING_TERM` has passed since the last key press and finishes a tap dance if that is the case.
docs/newbs_building_firmware.md
+1 -1
View File
@@ -40,7 +40,7 @@ Open your `keymap.c` file in your text editor. Inside this file you'll find the
This line indicates where the list of Layers begins. Below that you'll find lines containing `LAYOUT`, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a particular layer.
!> When editing your keymap file be careful not to add or remove any commas. If you do you will prevent your firmware from compiling and it may not be easy to figure out where the extra, or missing, comma is.
!> When editing your keymap file be careful not to add or remove any commas. If you do, you will prevent your firmware from compiling and it may not be easy to figure out where the extra, or missing, comma is.
## Customize The Layout To Your Liking
docs/reference_info_json.md
+38 -8
View File
@@ -1,12 +1,12 @@
# `info.json`
This file is used by the [QMK API](https://github.com/qmk/qmk_api). It contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard. You can also set metadata here.
The information contained in `info.json` is combined with the `config.h` and `rules.mk` files, dynamically generating the necessary configuration for your keyboard at compile time. It is also used by the [QMK API](https://github.com/qmk/qmk_api), and contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard.
You can create `info.json` files at every level under `qmk_firmware/keyboards/<name>` to specify this metadata. These files are combined, with more specific files overriding keys in less specific files. This means you do not need to duplicate your metadata information. For example, `qmk_firmware/keyboards/clueboard/info.json` specifies `manufacturer` and `maintainer`, while `qmk_firmware/keyboards/clueboard/66/info.json` specifies more specific information about Clueboard 66%.
You can create `info.json` files at every level under `qmk_firmware/keyboards/<name>`. These files are combined, with more specific files overriding keys in less specific files. This means you do not need to duplicate your metadata information. For example, `qmk_firmware/keyboards/clueboard/info.json` specifies `manufacturer` and `maintainer`, while `qmk_firmware/keyboards/clueboard/66/info.json` specifies more specific information about Clueboard 66%.
## `info.json` Format
The `info.json` file is a JSON formatted dictionary with the following keys available to be set. You do not have to set all of them, merely the keys that apply to your keyboard.
The `info.json` file is a JSON formatted dictionary. The first six keys noted here must be defined in `info.json`, or your keyboard will not be accepted into the QMK repository.
* `keyboard_name`
* A free-form text string describing the keyboard.
@@ -20,6 +20,11 @@ The `info.json` file is a JSON formatted dictionary with the following keys avai
* `maintainer`
* GitHub username of the maintainer, or `qmk` for community maintained boards.
* Example: `skullydazed`
* `usb`
* Configure USB VID, PID, and device version. See the [USB](#USB) section for more detail.
There are many more optional keys, some of which are described below. Others may be found by examining `data/schemas`.
* `debounce`
* The amount of time in milliseconds to wait for debounce to happen.
* Default: `5`
@@ -33,8 +38,6 @@ The `info.json` file is a JSON formatted dictionary with the following keys avai
* Configure the pins corresponding to columns and rows, or direct pins. See the [Matrix Pins](#matrix-pins) section for more detail.
* `rgblight`
* Configure the [RGB Lighting feature](feature_rgblight.md). See the [RGB Lighting](#rgb-lighting) section for more detail.
* `usb`
* Configure USB VID, PID, and other parameters. See the [USB](#USB) section for more detail.
### Layout Format
@@ -45,7 +48,7 @@ Within our `info.json` file the `layouts` portion of the dictionary contains sev
### Key Dictionary Format
Each Key Dictionary in a layout describes the physical properties of a key. If you are familiar with the Raw Code for <https://keyboard-layout-editor.com> you will find many of the concepts the same. We re-use the same key names and layout choices wherever possible, but unlike keyboard-layout-editor each key is stateless, inheriting no properties from the keys that came before it.
Each Key Dictionary in a layout describes the physical properties of a key. If you are familiar with the Raw Data for <https://keyboard-layout-editor.com> you will find many of the concepts the same. We re-use the same key names and layout choices wherever possible, but unlike keyboard-layout-editor each key is stateless, inheriting no properties from the keys that came before it.
All key positions and rotations are specified in relation to the top-left corner of the keyboard, and the top-left corner of each key.
@@ -91,6 +94,8 @@ Direct pins are when you connect one side of the switch to GND and the other sid
When specifying direct pins you need to arrange them in nested arrays. The outer array consists of rows, while the inner array uses text strings to identify the pins used in each row. You can use `null` to indicate an empty spot in the matrix.
Notice that when using direct pins, `diode_direction` is left undefined.
Example:
```json
@@ -113,6 +118,14 @@ Example:
This section controls basic 2-pin LEDs, which typically pass through keyswitches and are soldered into the PCB, or are placed in PCB sockets.
### Backlight
Enable by setting
```json
"features": {
"backlight": true
}
```
* `breathing`
* Enable backlight breathing, if supported
* `breathing_period`
@@ -145,6 +158,13 @@ Used for indicating Num Lock, Caps Lock, and Scroll Lock. May be soldered in-swi
* The pin that controls the `Caps Lock` LED
* `scroll_lock`
* The pin that controls the `Scroll Lock` LED
* `compose`
* The pin that controls the `Compose` LED
* `kana`
* The pin that controls the `Kana` LED
* `on_state`
* The state of the indicator pins when the LED is "on" - `1` for high, `0` for low
* Default: `1`
Example:
@@ -177,8 +197,9 @@ The following items can be set. Not every value is required.
* Set to `true` to enable synchronization functionality between split halves
* `split_count`
* For split keyboards, the number of LEDs on each side
* Example `[ 10 , 10 ]`
* `max_brightness`
* (0-255) What the maxmimum brightness (value) level is
* What the maximum brightness (value) level is (0-255)
* `hue_steps`
* How many steps of adjustment to have for hue
* `saturation_steps`
@@ -197,7 +218,8 @@ Example:
"saturation_steps": 17,
"brightness_steps": 17,
"animations": {
"all": true
"knight": true,
"rainbow_swirl": true
}
}
}
@@ -243,6 +265,14 @@ The device version is a BCD (binary coded decimal) value, in the format `MMmr`,
This section controls the basic [rotary encoder](feature_encoders.md) support.
Enable by setting
```json
"features": {
"encoder": true
}
```
The following items can be set. Not every value is required.
* `pin_a`