diff options
Diffstat (limited to 'docs')
86 files changed, 4195 insertions, 1246 deletions
diff --git a/docs/README.md b/docs/README.md index 22ab243cd2..9f9ca166bd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,7 +15,7 @@ QMK (*Quantum Mechanical Keyboard*) is an open source community that maintains Q If you plan on contributing a keymap, keyboard, or features to QMK, the easiest thing to do is [fork the repo through Github](https://github.com/qmk/qmk_firmware#fork-destination-box), and clone your repo locally to make your changes, push them, then open a [Pull Request](https://github.com/qmk/qmk_firmware/pulls) from your fork. -Otherwise, you can either download it directly ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), or clone it via git (`git@github.com:qmk/qmk_firmware.git`), or https (`https://github.com/qmk/qmk_firmware.git`). +Otherwise, you can clone it directly with `git clone https://github.com/qmk/qmk_firmware`. Do not download the zip or tar files; a git repository is required to download the submodules in order to compile. ## How to Compile diff --git a/docs/_langs.md b/docs/_langs.md index 7a7f127a97..f7b375fb94 100644 --- a/docs/_langs.md +++ b/docs/_langs.md @@ -4,4 +4,6 @@ - [:es: Español](/es/) - [:fr: Français](/fr-fr/) - [:he: עברית](/he-il/) + - [:brazil: Português](/pt-br/) - [:ru: Русский](/ru-ru/) + - [:jp: 日本語](/ja/) diff --git a/docs/_summary.md b/docs/_summary.md index dc6e88f958..f6b03867fc 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -3,7 +3,10 @@ * [Building Your First Firmware](newbs_building_firmware.md) * [Flashing Firmware](newbs_flashing.md) * [Testing and Debugging](newbs_testing_debugging.md) - * [Git Best Practices](newbs_best_practices.md) + * [Best Git Practices](newbs_git_best_practices.md) + * [Using Your Fork's Master](newbs_git_using_your_master_branch.md) + * [Resolving Merge Conflicts](newbs_git_resolving_merge_conflicts.md) + * [Resynchronizing a Branch](newbs_git_resynchronize_a_branch.md) * [Learning Resources](newbs_learn_more_resources.md) * [QMK Basics](README.md) @@ -33,6 +36,7 @@ * [Keymap Overview](keymap.md) * [Hardware](hardware.md) + * [Compatible Microcontrollers](compatible_microcontrollers.md) * [AVR Processors](hardware_avr.md) * [Drivers](hardware_drivers.md) @@ -97,6 +101,7 @@ * [Hand Wiring Guide](hand_wire.md) * [ISP Flashing Guide](isp_flashing_guide.md) * [ARM Debugging Guide](arm_debugging.md) + * [ADC Driver](adc_driver.md) * [I2C Driver](i2c_driver.md) * [WS2812 Driver](ws2812_driver.md) * [GPIO Controls](internals_gpio_control.md) @@ -110,7 +115,7 @@ * [Using Eclipse with QMK](other_eclipse.md) * [Using VSCode with QMK](other_vscode.md) * [Support](support.md) - * [How to add translations](translating.md) + * [Translating the QMK Docs](translating.md) * QMK Internals (In Progress) * [Defines](internals_defines.md) diff --git a/docs/adc_driver.md b/docs/adc_driver.md new file mode 100644 index 0000000000..26e148addd --- /dev/null +++ b/docs/adc_driver.md @@ -0,0 +1,50 @@ +# ADC Driver + +QMK can leverage the Analog-to-Digital Converter (ADC) on supported MCUs to measure voltages on certain pins. This can be useful for implementing things such as battery level indicators for Bluetooth keyboards, or volume controls using a potentiometer, as opposed to a [rotary encoder](feature_encoders.md). + +This driver is currently AVR-only. The values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V). + +## Usage + +To use this driver, add the following to your `rules.mk`: + +```make +SRC += analog.c +``` + +Then place this include at the top of your code: + +```c +#include "analog.h" +``` + +## Channels + +|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328P| +|-------|-------------|-------------|---------|----------| +|0 |`F0` |`F0` |`A0` |`C0` | +|1 |`F1` |`F1` |`A1` |`C1` | +|2 |`F2` | |`A2` |`C2` | +|3 |`F3` | |`A3` |`C3` | +|4 |`F4` |`F4` |`A4` |`C4` | +|5 |`F5` |`F5` |`A5` |`C5` | +|6 |`F6` |`F6` |`A6` |* | +|7 |`F7` |`F7` |`A7` |* | +|8 | |`D4` | | | +|9 | |`D6` | | | +|10 | |`D7` | | | +|11 | |`B4` | | | +|12 | |`B5` | | | +|13 | |`B6` | | | + +<sup>\* The ATmega328P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these.</sup> + +## Functions + +|Function |Description | +|----------------------------|-------------------------------------------------------------------------------------------------------------------| +|`analogReference(mode)` |Sets the analog voltage reference source. Must be one of `ADC_REF_EXTERNAL`, `ADC_REF_POWER` or `ADC_REF_INTERNAL`.| +|`analogRead(pin)` |Reads the value from the specified Arduino pin, eg. `4` for ADC6 on the ATmega32U4. | +|`analogReadPin(pin)` |Reads the value from the specified QMK pin, eg. `F6` for ADC6 on the ATmega32U4. | +|`pinToMux(pin)` |Translates a given QMK pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)". | +|`adc_read(mux)` |Reads the value from the ADC according to the specified mux. See your MCU's datasheet for more information. | diff --git a/docs/cli.md b/docs/cli.md index e655b0ee89..1c09527221 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -95,6 +95,30 @@ qmk compile <configuratorExport.json> qmk compile -kb <keyboard_name> -km <keymap_name> ``` +## `qmk flash` + +This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default. +To specify a different bootloader, use `-bl <bootloader>`. Visit <https://docs.qmk.fm/#/flashing> +for more details of the available bootloaders. + +**Usage for Configurator Exports**: + +``` +qmk flash <configuratorExport.json> -bl <bootloader> +``` + +**Usage for Keymaps**: + +``` +qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader> +``` + +**Listing the Bootloaders** + +``` +qmk flash -b +``` + ## `qmk config` This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration.md). @@ -135,6 +159,28 @@ Creates a keymap.c from a QMK Configurator export. qmk json-keymap [-o OUTPUT] filename ``` +## `qmk kle2json` + +This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite. + +**Usage**: + +``` +qmk kle2json [-f] <filename> +``` + +**Examples**: + +``` +$ qmk kle2json kle.txt +☒ File info.json already exists, use -f or --force to overwrite. +``` + +``` +$ qmk kle2json -f kle.txt -f +Ψ Wrote out to info.json +``` + ## `qmk list-keyboards` This command lists all the keyboards currently defined in `qmk_firmware` diff --git a/docs/cli_development.md b/docs/cli_development.md index f5c7ad139a..cc8c59d067 100644 --- a/docs/cli_development.md +++ b/docs/cli_development.md @@ -173,3 +173,35 @@ You will only be able to access these arguments using `cli.args`. For example: ``` cli.log.info('Reading from %s and writing to %s', cli.args.filename, cli.args.output) ``` + +# Testing, and Linting, and Formatting (oh my!) + +We use nose2, flake8, and yapf to test, lint, and format code. You can use the `pytest` and `pyformat` subcommands to run these tests: + +### Testing and Linting + + qmk pytest + +### Formatting + + qmk pyformat + +## Formatting Details + +We use [yapf](https://github.com/google/yapf) to automatically format code. Our configuration is in the `[yapf]` section of `setup.cfg`. + +?> Tip- Many editors can use yapf as a plugin to automatically format code as you type. + +## Testing Details + +Our tests can be found in `lib/python/qmk/tests/`. You will find both unit and integration tests in this directory. We hope you will write both unit and integration tests for your code, but if you do not please favor integration tests. + +If your PR does not include a comprehensive set of tests please add comments like this to your code so that other people know where they can help: + + # TODO(unassigned/<yourGithubUsername>): Write <unit|integration> tests + +We use [nose2](https://nose2.readthedocs.io/en/latest/getting_started.html) to run our tests. You can refer to the nose2 documentation for more details on what you can do in your test functions. + +## Linting Details + +We use flake8 to lint our code. Your code should pass flake8 before you open a PR. This will be checked when you run `qmk pytest` and by CI when you submit a PR. diff --git a/docs/coding_conventions_c.md b/docs/coding_conventions_c.md index 08994bfbb7..16e28b2884 100644 --- a/docs/coding_conventions_c.md +++ b/docs/coding_conventions_c.md @@ -14,7 +14,7 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely * Think of them as a story describing the feature * Use them liberally to explain why particular decisions were made. * Do not write obvious comments - * If you not sure if a comment is obvious, go ahead and include it. + * If you're not sure if a comment is obvious, go ahead and include it. * In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns. * We use `#pragma once` at the start of header files rather than old-style include guards (`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`) * We accept both forms of preprocessor if's: `#ifdef DEFINED` and `#if defined(DEFINED)` diff --git a/docs/coding_conventions_python.md b/docs/coding_conventions_python.md index 694aa38cfc..9dd95e4b73 100644 --- a/docs/coding_conventions_python.md +++ b/docs/coding_conventions_python.md @@ -8,7 +8,7 @@ Most of our style follows PEP8 with some local modifications to make things less * Think of them as a story describing the feature * Use them liberally to explain why particular decisions were made. * Do not write obvious comments - * If you not sure if a comment is obvious, go ahead and include it. + * If you're not sure if a comment is obvious, go ahead and include it. * We require useful docstrings for all functions. * In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns. * Some of our practices conflict with the wider python community to make our codebase more approachable to non-pythonistas. diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 6e3f8372c9..85dd440d37 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -1,25 +1,36 @@ -# Atmel AVR +# Compatible Microcontrollers -QMK should run on any Atmel AVR processor with enough Flash. It has been tested on the following: +QMK runs on any USB-capable AVR or ARM microcontroller with enough flash space - generally 32kB or more, though it will *just* squeeze into 16kB with most features disabled. -* ATmega32U4 ([PJRC Teensy 2.0](http://www.pjrc.com/teensy/)) -* AT90USB1286 ([PJRC Teensy++ 2.0](http://www.pjrc.com/teensy/)) -* AT90USB1287 ([Atmel USBKEY](http://www.atmel.com/tools/AT90USBKEY.aspx)) -* ATmega168P with using [V-USB](http://www.obdev.at/products/vusb/index.html) -* ATmega328P with using [V-USB](http://www.obdev.at/products/vusb/index.html) -* ATmega32U2 -* AT90USB1286, 646, 647 should work -* AT90USB162 testing... +## Atmel AVR -NOTE: To enable full features of firmware you'll need 32KB flash size. +The following use [LUFA](https://www.fourwalledcubicle.com/LUFA.php) as the USB stack: -Please add any tested microcontrollers to this list. +* [ATmega16U2](https://www.microchip.com/wwwproducts/en/ATmega16U2) / [ATmega32U2](https://www.microchip.com/wwwproducts/en/ATmega32U2) +* [ATmega16U4](https://www.microchip.com/wwwproducts/en/ATmega16U4) / [ATmega32U4](https://www.microchip.com/wwwproducts/en/ATmega32U4) +* [AT90USB64](https://www.microchip.com/wwwproducts/en/AT90USB646) / [AT90USB128](https://www.microchip.com/wwwproducts/en/AT90USB1286) -# ARM +Certain MCUs which do not have native USB will use [V-USB](https://www.obdev.at/products/vusb/index.html) inst |