diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/cli.md | 4 | ||||
-rw-r--r-- | docs/cli_development.md | 6 | ||||
-rw-r--r-- | docs/coding_conventions_python.md | 4 | ||||
-rw-r--r-- | docs/faq_debug.md | 11 | ||||
-rw-r--r-- | docs/features/split_keyboard.md | 2 | ||||
-rw-r--r-- | docs/license_violations.md | 6 | ||||
-rw-r--r-- | docs/unit_testing.md | 28 |
7 files changed, 53 insertions, 8 deletions
diff --git a/docs/cli.md b/docs/cli.md index 7d4c10cedd..36983d5e00 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -6,7 +6,7 @@ The QMK CLI (command line interface) makes building and working with QMK keyboar ### Requirements {#requirements} -QMK requires Python 3.7 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. +QMK requires Python 3.9 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. ### Install Using Homebrew (macOS, some Linux) {#install-using-homebrew} @@ -20,7 +20,7 @@ qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build ### Install Using pip {#install-using-easy_install-or-pip} -If your system is not listed above you can install QMK manually. First ensure that you have Python 3.7 (or later) installed and have installed pip. Then install QMK with this command: +If your system is not listed above you can install QMK manually. First ensure that you have Python 3.9 (or later) installed and have installed pip. Then install QMK with this command: ``` python3 -m pip install qmk diff --git a/docs/cli_development.md b/docs/cli_development.md index 2e74220d4b..74ac53d327 100644 --- a/docs/cli_development.md +++ b/docs/cli_development.md @@ -44,7 +44,7 @@ def hello(cli): First we import the `cli` object from `milc`. This is how we interact with the user and control the script's behavior. We use `@cli.argument()` to define a command line flag, `--name`. This also creates a configuration variable named `hello.name` (and the corresponding `user.name`) which the user can set so they don't have to specify the argument. The `cli.subcommand()` decorator designates this function as a subcommand. The name of the subcommand will be taken from the name of the function. -Once inside our function we find a typical "Hello, World!" program. We use `cli.log` to access the underlying [Logger Object](https://docs.python.org/3.7/library/logging.html#logger-objects), whose behavior is user controllable. We also access the value for name supplied by the user as `cli.config.hello.name`. The value for `cli.config.hello.name` will be determined by looking at the `--name` argument supplied by the user, if not provided it will use the value in the `qmk.ini` config file, and if neither of those is provided it will fall back to the default supplied in the `cli.argument()` decorator. +Once inside our function we find a typical "Hello, World!" program. We use `cli.log` to access the underlying [Logger Object](https://docs.python.org/3.9/library/logging.html#logger-objects), whose behavior is user controllable. We also access the value for name supplied by the user as `cli.config.hello.name`. The value for `cli.config.hello.name` will be determined by looking at the `--name` argument supplied by the user, if not provided it will use the value in the `qmk.ini` config file, and if neither of those is provided it will fall back to the default supplied in the `cli.argument()` decorator. # User Interaction @@ -56,13 +56,13 @@ There are two main methods for outputting text in a subcommand- `cli.log` and `c You can use special tokens to colorize your text, to make it easier to understand the output of your program. See [Colorizing Text](#colorizing-text) below. -Both of these methods support built-in string formatting using python's [printf style string format operations](https://docs.python.org/3.7/library/stdtypes.html#old-string-formatting). You can use tokens such as `%s` and `%d` within your text strings then pass the values as arguments. See our Hello, World program above for an example. +Both of these methods support built-in string formatting using python's [printf style string format operations](https://docs.python.org/3.9/library/stdtypes.html#old-string-formatting). You can use tokens such as `%s` and `%d` within your text strings then pass the values as arguments. See our Hello, World program above for an example. You should never use the format operator (`%`) directly, always pass values as arguments. ### Logging (`cli.log`) -The `cli.log` object gives you access to a [Logger Object](https://docs.python.org/3.7/library/logging.html#logger-objects). We have configured our log output to show the user a nice emoji for each log level (or the log level name if their terminal does not support unicode.) This way the user can tell at a glance which messages are most important when something goes wrong. +The `cli.log` object gives you access to a [Logger Object](https://docs.python.org/3.9/library/logging.html#logger-objects). We have configured our log output to show the user a nice emoji for each log level (or the log level name if their terminal does not support unicode.) This way the user can tell at a glance which messages are most important when something goes wrong. The default log level is `INFO`. If the user runs `qmk -v <subcommand>` the default log level will be set to `DEBUG`. diff --git a/docs/coding_conventions_python.md b/docs/coding_conventions_python.md index 502ee9102e..b25466bf82 100644 --- a/docs/coding_conventions_python.md +++ b/docs/coding_conventions_python.md @@ -2,7 +2,7 @@ Most of our style follows PEP8 with some local modifications to make things less nit-picky. -* We target Python 3.7 for compatibility with all supported platforms. +* We target Python 3.9 for compatibility with all supported platforms. * We indent using four (4) spaces (soft tabs) * We encourage liberal use of comments * Think of them as a story describing the feature @@ -317,7 +317,7 @@ At the time of this writing our tests are not very comprehensive. Looking at the ## Integration Tests -Integration tests can be found in `lib/python/qmk/tests/test_cli_commands.py`. This is where CLI commands are actually run and their overall behavior is verified. We use [`subprocess`](https://docs.python.org/3.7/library/subprocess.html#module-subprocess) to launch each CLI command and a combination of checking output and returncode to determine if the right thing happened. +Integration tests can be found in `lib/python/qmk/tests/test_cli_commands.py`. This is where CLI commands are actually run and their overall behavior is verified. We use [`subprocess`](https://docs.python.org/3.9/library/subprocess.html#module-subprocess) to launch each CLI command and a combination of checking output and returncode to determine if the right thing happened. ## Unit Tests diff --git a/docs/faq_debug.md b/docs/faq_debug.md index 35a4160e27..269049afb8 100644 --- a/docs/faq_debug.md +++ b/docs/faq_debug.md @@ -77,6 +77,17 @@ KL: kc: 172, col: 2, row: 0, pressed: 1, time: 16303, int: 0, count: 0 KL: kc: 172, col: 2, row: 0, pressed: 0, time: 16411, int: 0, count: 0 ``` +### Which keycode is this keypress? + +Keycodes are logged in the example above as numerical codes, which may be difficult to interpret. For more readable logging, add `KEYCODE_STRING_ENABLE = yes` in your `rules.mk` and use `get_keycode_string(kc)`. For example: + +```c +uprintf("kc: %s\n", get_keycode_string(keycode)); +``` + +This logs the keycode as a human-readable string like "`LT(2,KC_D)`" rather than a numerical code like "`0x4207`." See the [Keycode String](unit_testing#keycode-string) section of the Unit Testing page for more information. + + ### How long did it take to scan for a keypress? When testing performance issues, it can be useful to know the frequency at which the switch matrix is being scanned. To enable logging for this scenario, add the following code to your keymaps `config.h` diff --git a/docs/features/split_keyboard.md b/docs/features/split_keyboard.md index 49582c3946..fbf5d3d3e2 100644 --- a/docs/features/split_keyboard.md +++ b/docs/features/split_keyboard.md @@ -444,7 +444,7 @@ This setting implies that `RGBLIGHT_SPLIT` is enabled, and will forcibly enable #define SPLIT_USB_DETECT ``` -Enabling this option changes the startup behavior to listen for an active USB communication to delegate which part is master and which is slave. With this option enabled and theres's USB communication, then that half assumes it is the master, otherwise it assumes it is the slave. +Enabling this option changes the startup behavior to listen for an active USB communication to delegate which part is master and which is slave. With this option enabled and active USB communication, then that half assumes it is the master, otherwise it assumes it is the slave. Without this option, the master is the half that can detect voltage on the physical USB connection (VBUS detection). diff --git a/docs/license_violations.md b/docs/license_violations.md index 81a6ba517f..cf7850effc 100644 --- a/docs/license_violations.md +++ b/docs/license_violations.md @@ -19,9 +19,13 @@ If you own a board from one of the following vendors already, consider asking th | Vendor | Reason | |------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Ajazz | Selling tri-mode boards based on QMK without sources. | +| Alpaca / Apos | Selling wireless boards with "open" source code, but linking against closed-source wireless libraries. Crippled source code already unknowingly merged to QMK. | +| Attack Shark | Selling tri-mode boards based on QMK without sources. (Clones of Ajazz?) | | BBB Keyboard | Selling tri-mode boards based on QMK without sources, attempted upstreaming crippled firmware without wireless. | | Chosfox | Selling L75 wired/wireless boards based on QMK without sources, just `via.json` provided. Raised on discord over multiple weeks without response. | | CIDOO | Selling wired boards based on QMK without sources, just `via.json` provided. | +| ColorReco | Selling tri-mode boards based on QMK without sources. | | Darmoshark | Selling wired boards based on QMK without sources, just `via.json` provided. | | Epomaker | Lots of historical keyboards with `via.json` but no corresponding sources. Wireless code for a small handful provided, pending core cleanup for QMK upstreaming. Most other boards have source nowhere to be seen. | | Ergokbd (IFKB) | At least their crkbd clone ships with QMK+Vial, seemingly refuses to disclose sources despite multiple customers requesting them. | @@ -36,6 +40,7 @@ If you own a board from one of the following vendors already, consider asking th | pressplayid | Selling wired and tri-mode boards based on QMK without sources, just `via.json` provided | | qwertykeys | Selling wired and tri-mode boards based on QMK without sources, just `via.json` provided. | | Redragon | Selling tri-mode boards based on QMK without sources, attempted upstreaming crippled firmware without wireless. | +| Riccks | Selling tri-mode boards based on QMK without sources. | | Royal Kludge | PRs for fake boards in order to attain VIA compatibility identified. Lots of other keyboards with `via.json` but no corresponding sources, attempted upstreaming crippled firmware without wireless. Wireless code for some provided, pending core cleanup for QMK upstreaming. PRs including different manufacturer names as well. | | Shenzhen Hangsheng | PR submissions with crippled firmware, debating with maintainers about wireless despite marketing material clearly stating tri-mode. | | Tacworks | Selling tri-mode boards based on QMK, crippled firmware already merged into QMK without wireless without QMK team realising. | @@ -45,6 +50,7 @@ If you own a board from one of the following vendors already, consider asking th | Womier | Selling tri-mode boards based on QMK without sources, attempted upstreaming crippled firmware without wireless. | | Wuque Studio | Selling wired and tri-mode boards based on QMK without sources, just `via.json` provided. | | XVX | Ambiguity on PRs -- marketing says wireless, PR author said wired-only. Seemingly intentionally deceptive. | +| Yunzii | Selling tri-mode boards based on QMK without sources, just `via.json` provided. | | Zuoya | Selling tri-mode boards based on QMK without sources, just `via.json` provided. | ::: danger Violations diff --git a/docs/unit_testing.md b/docs/unit_testing.md index 3e4c914bf1..aec4ec8334 100644 --- a/docs/unit_testing.md +++ b/docs/unit_testing.md @@ -58,6 +58,34 @@ It's not yet possible to do a full integration test, where you would compile the In that model you would emulate the input, and expect a certain output from the emulated keyboard. +# Keycode String {#keycode-string} + +It's much nicer to read keycodes as names like "`LT(2,KC_D)`" than numerical codes like "`0x4207`." To convert keycodes to human-readable strings, add `KEYCODE_STRING_ENABLE = yes` to the `rules.mk` file, then use the `get_keycode_string(kc)` function to convert a given 16-bit keycode to a string. + +```c +const char *key_name = get_keycode_string(keycode); +dprintf("kc: %s\n", key_name); +``` + +The stringified keycode may then be logged to console output with `dprintf()` or elsewhere. + +::: warning +Use the result of `get_keycode_string()` immediately. Subsequent invocations reuse the same static buffer and overwrite the previous contents. +::: + +Many common QMK keycodes are recognized by `get_keycode_string()`, but not all. These include some common basic keycodes, layer switch keycodes, mod-taps, one-shot keycodes, tap dance keycodes, and Unicode keycodes. As a fallback, an unrecognized keycode is written as a hex number. + +Optionally, `KEYCODE_STRING_NAMES_USER` may be defined to add names for additional keycodes. For example, supposing keymap.c defines `MYMACRO1` and `MYMACRO2` as custom keycodes, the following adds their names: + +```c +KEYCODE_STRING_NAMES_USER( + KEYCODE_STRING_NAME(MYMACRO1), + KEYCODE_STRING_NAME(MYMACRO2), +); +``` + +Similarly, `KEYCODE_STRING_NAMES_KB` may be defined to add names at the keyboard level. + # Tracing Variables {#tracing-variables} Sometimes you might wonder why a variable gets changed and where, and this can be quite tricky to track down without having a debugger. It's of course possible to manually add print statements to track it, but you can also enable the variable trace feature. This works for both variables that are changed by the code, and when the variable is changed by some memory corruption. |