diff options
Diffstat (limited to 'docs')
40 files changed, 584 insertions, 140 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 4a6e6996e..d47b252c0 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -121,6 +121,7 @@ * [Drivers](hardware_drivers.md) * [ADC Driver](adc_driver.md) * [I2C Driver](i2c_driver.md) + * [SPI Driver](spi_driver.md) * [WS2812 Driver](ws2812_driver.md) * [EEPROM Driver](eeprom_driver.md) * [GPIO Controls](internals_gpio_control.md) @@ -135,6 +136,10 @@ * [Development Environment](api_development_environment.md) * [Architecture Overview](api_development_overview.md) + * Hardware Platform Development + * Arm/ChibiOS + * [Early initialization](platformdev_chibios_earlyinit.md) + * QMK Reference * [Contributing to QMK](contributing.md) * [Translating the QMK Docs](translating.md) diff --git a/docs/cli.md b/docs/cli.md index 760fe1cdb..01641bd8b 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -6,7 +6,7 @@ The QMK CLI makes building and working with QMK keyboards easier. We have provid ### Requirements :id=requirements -The 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. +QMK requires Python 3.6 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) :id=install-using-homebrew @@ -21,7 +21,7 @@ qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build ### Install Using easy_install or pip :id=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.5 (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.6 (or later) installed and have installed pip. Then install QMK with this command: ``` pip3 install qmk diff --git a/docs/cli_commands.md b/docs/cli_commands.md index eb5362bd2..eff5321bd 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -1,38 +1,6 @@ # QMK CLI Commands -# CLI Commands - -## `qmk cformat` - -This command formats C code using clang-format. - -Run it with no arguments to format all core code that has been changed. Default checks `origin/master` with `git diff`, branch can be changed using `-b <branch_name>` - -Run it with `-a` to format all core code, or pass filenames on the command line to run it on specific files. - -**Usage for specified files**: - -``` -qmk cformat [file1] [file2] [...] [fileN] -``` - -**Usage for all core files**: - -``` -qmk cformat -a -``` - -**Usage for only changed files against origin/master**: - -``` -qmk cformat -``` - -**Usage for only changed files against branch_name**: - -``` -qmk cformat -b branch_name -``` +# User Commands ## `qmk compile` @@ -136,16 +104,6 @@ This command lets you configure the behavior of QMK. For the full `qmk config` d qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] ``` -## `qmk docs` - -This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936. - -**Usage**: - -``` -qmk docs [-p PORT] -``` - ## `qmk doctor` This command examines your environment and alerts you to potential build or flash problems. It can fix many of them if you want it to. @@ -180,56 +138,102 @@ Creates a keymap.c from a QMK Configurator export. qmk json2c [-o OUTPUT] filename ``` -## `qmk kle2json` +## `qmk list-keyboards` -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. +This command lists all the keyboards currently defined in `qmk_firmware` **Usage**: ``` -qmk kle2json [-f] <filename> +qmk list-keyboards ``` -**Examples**: +## `qmk list-keymaps` + +This command lists all the keymaps for a specified keyboard (and revision). + +**Usage**: ``` -$ qmk kle2json kle.txt -☒ File info.json already exists, use -f or --force to overwrite. +qmk list-keymaps -kb planck/ez ``` +## `qmk new-keymap` + +This command creates a new keymap based on a keyboard's existing default keymap. + +**Usage**: + ``` -$ qmk kle2json -f kle.txt -f -Ψ Wrote out to info.json +qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] ``` -## `qmk list-keyboards` +--- -This command lists all the keyboards currently defined in `qmk_firmware` +# Developer Commands -**Usage**: +## `qmk cformat` + +This command formats C code using clang-format. + +Run it with no arguments to format all core code that has been changed. Default checks `origin/master` with `git diff`, branch can be changed using `-b <branch_name>` + +Run it with `-a` to format all core code, or pass filenames on the command line to run it on specific files. + +**Usage for specified files**: ``` -qmk list-keyboards +qmk cformat [file1] [file2] [...] [fileN] ``` -## `qmk list-keymaps` +**Usage for all core files**: -This command lists all the keymaps for a specified keyboard (and revision). +``` +qmk cformat -a +``` + +**Usage for only changed files against origin/master**: + +``` +qmk cformat +``` + +**Usage for only changed files against branch_name**: + +``` +qmk cformat -b branch_name +``` + +## `qmk docs` + +This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936. **Usage**: ``` -qmk list-keymaps -kb planck/ez +qmk docs [-p PORT] ``` -## `qmk new-keymap` +## `qmk kle2json` -This command creates a new keymap based on a keyboard's existing default keymap. +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 new-keymap [-kb KEYBOARD] [-km KEYMAP] +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 pyformat` @@ -251,3 +255,4 @@ This command runs the python test suite. If you make changes to python code you ``` qmk pytest ``` + diff --git a/docs/cli_development.md b/docs/cli_development.md index cc8c59d06..af86686c0 100644 --- a/docs/cli_development.md +++ b/docs/cli_development.md @@ -6,6 +6,18 @@ This document has useful information for developers wishing to write new `qmk` s The QMK CLI operates using the subcommand pattern made famous by git. The main `qmk` script is simply there to setup the environment and pick the correct entrypoint to run. Each subcommand is a self-contained module with an entrypoint (decorated by `@cli.subcommand()`) that performs some action and returns a shell returncode, or None. +## Developer mode: + +If you intend to maintain keyboards and/or contribute to QMK, you can enable the CLI's "Developer" mode: + +`qmk config user.developer=True` + +This will allow you to see all available subcommands. +**Note:** You will have to install additional requirements: +```bash +python3 -m pip install -r requirements-dev.txt +``` + # Subcommands [MILC](https://github.com/clueboard/milc) is the CLI framework `qmk` uses to handle argument parsing, configuration, logging, and many other features. It lets you focus on writing your tool without wasting your time writing glue code. @@ -32,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.5/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.6/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 @@ -44,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.5/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.6/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.5/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.6/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 1aefc044e..47dff7f8e 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.5 for compatability with all supported platforms. +* We target Python 3.6 for compatability 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.5/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.6/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/config_options.md b/docs/config_options.md index 661cfccce..16fea83a3 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -115,9 +115,9 @@ If you define these options you will disable the associated feature, which can s * `#define NO_ACTION_ONESHOT` * disable one-shot modifiers * `#define NO_ACTION_MACRO` - * disable old style macro handling: MACRO() & action_get_macro + * disable old-style macro handling using `MACRO()`, `action_get_macro()` _(deprecated)_ * `#define NO_ACTION_FUNCTION` - * disable calling of action_function() from the fn_actions array (deprecated) + * disable old-style function handling using `fn_actions`, `action_function()` _(deprecated)_ ## Features That Can Be Enabled @@ -317,10 +317,10 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i * `LAYOUTS` * A list of [layouts](feature_layouts.md) this keyboard supports. * `LINK_TIME_OPTIMIZATION_ENABLE` - * Enables Link Time Optimization (`LTO`) when compiling the keyboard. This makes the process take longer, but can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable). However, this will automatically disable the old Macros and Functions features automatically, as these break when `LTO` is enabled. - It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION` + * Enables Link Time Optimization (LTO) when compiling the keyboard. This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable). +However, this will automatically disable the legacy TMK Macros and Functions features, as these break when LTO is enabled. It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`. (Note: This does not affect QMK [Macros](feature_macros.md) and [Layers](feature_layers.md).) * `LTO_ENABLE` - * It has the same meaning as LINK_TIME_OPTIMIZATION_ENABLE. You can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`. + * Has the same meaning as `LINK_TIME_OPTIMIZATION_ENABLE`. You can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`. ## AVR MCU Options * `MCU = atmega32u4` diff --git a/docs/de/_summary.md b/docs/de/_summary.md index a894420a2..19c75ecd3 100644 --- a/docs/de/_summary.md +++ b/docs/de/_summary.md @@ -98,6 +98,7 @@ * [ISP Flashing Guide](de/isp_flashing_guide.md) * [ARM Debugging Guide](de/arm_debugging.md) * [I2C Driver](de/i2c_driver.md) + * [SPI Driver](de/spi_driver.md) * [GPIO Controls](de/internals_gpio_control.md) * [Proton C Conversion](de/proton_c_conversion.md) diff --git a/docs/es/_summary.md b/docs/es/_summary.md index 7dffea7d2..b58d825f7 100644 --- a/docs/es/_summary.md +++ b/docs/es/_summary.md @@ -98,6 +98,7 @@ * [Guía de flasheado de ISP](es/isp_flashing_guide.md) * [Guía de depuración de ARM](es/arm_debugging.md) * [Driver I2C](es/i2c_driver.md) + * [Driver SPI](es/spi_driver.md) * [Controles GPIO](es/internals_gpio_control.md) * [Conversión Proton C](es/proton_c_conversion.md) diff --git a/docs/faq_debug.md b/docs/faq_debug.md index 6c66defbd..08c84fe4f 100644 --- a/docs/faq_debug.md +++ b/docs/faq_debug.md @@ -160,10 +160,3 @@ As of now root of its cause is not clear but some build options seem to be relat https://github.com/tmk/tmk_keyboard/issues/266 https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778 - - - -## FLIP Doesn't Work -### `AtLibUsbDfu.dll` Not Found -Remove current driver and reinstall one FLIP provides from DeviceManager. -http://imgur.com/a/bnwzy diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index b2abe5dae..b8664074a 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -6,11 +6,11 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown |----------|-------------------------------|----------------------------------------------------| |`LCTL(kc)`|`C(kc)` |Hold Left Control and press `kc` | |`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` | -|`LALT(kc)`|`A(kc)` |Hold Left Alt and press `kc` | +|`LALT(kc)`|`A(kc)`, `LOPT(kc)` |Hold Left Alt and press `kc` | |`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc` | |`RCTL(kc)`| |Hold Right Control and press `kc` | |`RSFT(kc)`| |Hold Right Shift and press `kc` | -|`RALT(kc)`|`ALGR(kc)` |Hold Right Alt and press `kc` | +|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)` |Hold Right Alt and press `kc` | |`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)` |Hold Right GUI and press `kc` | |`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)` |Hold Left Shift and GUI and press `kc` | |`LCA(kc)` | |Hold Left Control and Alt and press `kc` | @@ -18,7 +18,7 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown |`MEH(kc)` | |Hold Left Control, Shift and Alt and press `kc` | |`HYPR(kc)`| |Hold Left Control, Shift, Alt and GUI and press `kc`| -You can also chain them, for example `LCTL(LALT(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress. +You can also chain them, for example `LCTL(LALT(KC_DEL))` or `C(A(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress. # Legacy Content :id=legacy-content diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md index b5e5b61bb..65b4ea1e5 100644 --- a/docs/feature_debounce_type.md +++ b/docs/feature_debounce_type.md @@ -38,5 +38,6 @@ For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computati appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use. * eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key * sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occured, all input changes are pushed. +* sym_pk - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occured on that key, the key status change is pushed. diff --git a/docs/feature_macros.md b/docs/feature_macros.md index 1bd2d74e7..1c7705a51 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -161,11 +161,11 @@ There's also a couple of mod shortcuts you can use: * `SS_LCTL(string)` * `SS_LSFT(string)` -* `SS_LALT(string)` +* `SS_LALT(string)` or `SS_LOPT(string)` * `SS_LGUI(string)`, `SS_LCMD(string)` or `SS_LWIN(string)` * `SS_RCTL(string)` * `SS_RSFT(string)` -* `SS_RALT(string)` or `SS_ALGR(string)` +* `SS_RALT(string)`, `SS_ROPT(string)` or `SS_ALGR(string)` * `SS_RGUI(string)`, `SS_RCMD(string)` or `SS_RWIN(string)` These press the respective modifier, send the supplied string and then release the modifier. diff --git a/docs/feature_ps2_mouse.md b/docs/feature_ps2_mouse.md index ce072fbe9..c1bd8bff5 100644 --- a/docs/feature_ps2_mouse.md +++ b/docs/feature_ps2_mouse.md @@ -266,6 +266,25 @@ To reverse the scroll axes you can put: into config.h. +### Rotate Mouse Axes :id=rotate-mouse-axes + +Transform the output of the device with a clockwise rotation of 90, 180, or 270 +degrees. + +When compensating for device orientation, rotate the output the same amount in +the opposite direction. E.g. if the normal device orientation is considered to +be North-facing, compensate as follows: + +```c +#define PS2_MOUSE_ROTATE 270 /* Compensate for East-facing device orientation. */ +``` +```c +#define PS2_MOUSE_ROTATE 180 /* Compensate for South-facing device orientation. */ +``` +```c +#define PS2_MOUSE_ROTATE 90 /* Compensate for West-facing device orientation. */ +``` + ### Debug Settings :id=debug-settings To debug the mouse, add `debug_mouse = true` or enable via bootmagic. diff --git a/docs/flashing.md b/docs/flashing.md index ab003308d..1f71c253c 100644 --- a/docs/flashing.md +++ b/docs/flashing.md @@ -26,7 +26,6 @@ Compatible flashers: * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI) * [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` in QMK (recommended command line) -* [Atmel's Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (not recommended) Flashing sequence: diff --git a/docs/fr-fr/_summary.md b/docs/fr-fr/_summary.md index bb14d2f0a..25a593b2e 100644 --- a/docs/fr-fr/_summary.md +++ b/docs/fr-fr/_summary.md @@ -101,7 +101,8 @@ * [Guide des claviers soudés à la main](fr-fr/hand_wire.md) * [Guide de flash de l’ISP](fr-fr/isp_flashing_guide.md) * [Guide du débogage ARM](fr-fr/arm_debugging.md) - * [Drivers i2c](fr-fr/i2c_driver.md) + * [Drivers I2C](fr-fr/i2c_driver.md) + * [Drivers SPI](fr-fr/spi_driver.md) * [Contrôles des GPIO](fr-fr/internals_gpio_control.md) * [Conversion en Proton C](fr-fr/proton_c_conversion.md) diff --git a/docs/fr-fr/faq_debug.md b/docs/fr-fr/faq_debug.md index 754c79921..9c12f2917 100644 --- a/docs/fr-fr/faq_debug.md +++ b/docs/fr-fr/faq_debug.md @@ -155,11 +155,3 @@ Pour le moment, l'origine du problème n'est pas comprise, mais certaines option https://github.com/tmk/tmk_keyboard/issues/266 https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778 - -## FLIP ne marche pas - -### `AtLibUsbDfu.dll` Not Found - -Supprimez le pilote actuel et réinstallez celui donné par FLIP dans le gestionnaire de périphériques. - -http://imgur.com/a/bnwzy diff --git a/docs/fr-fr/flashing.md b/docs/fr-fr/flashing.md index c380614a5..74eae4977 100644 --- a/docs/fr-fr/flashing.md +++ b/docs/fr-fr/flashing.md @@ -26,7 +26,6 @@ Méthodes de flash compatibles : * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (interface graphique recommandé) * [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` avec QMK (outil en ligne de commande recommandé) -* [Atmel's Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (non recommandé) Ordre des actions : diff --git a/docs/getting_started_vagrant.md b/docs/getting_started_vagrant.md index da26682d7..7a4541cfc 100644 --- a/docs/getting_started_vagrant.md +++ b/docs/getting_started_vagrant.md @@ -20,7 +20,6 @@ The "easy" way to flash the firmware is using a tool from your host OS: * [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (recommended) * [Teensy Loader](https://www.pjrc.com/teensy/loader.html) -* [Atmel FLIP](http://www.atmel.com/tools/flip.aspx) If you want to program via the command line you can uncomment the ['modifyvm'] lines in the Vagrantfile to enable the USB passthrough into Linux and then program using the command line tools like dfu-util/dfu-programmer or you can install the Teensy CLI version. diff --git a/docs/he-il/_summary.md b/docs/he-il/_summary.md index 21059f997..bdacd0d1f 100644 --- a/docs/he-il/_summary.md +++ b/docs/he-il/_summary.md @@ -114,6 +114,7 @@ * [מדריך לצריבת ISP](he-il/isp_flashing_guide.md) * [מדריך לדיבאגינג ARM](he-il/arm_debugging.md) * [מנהל התקן I2C](he-il/i2c_driver.md) + * [מנהל התקן SPI](he-il/spi_driver.md) * [בקרת GPIO](he-il/internals_gpio_control.md) * [המרת Proton C](he-il/proton_c_conversion.md) diff --git a/docs/ja/_summary.md b/docs/ja/_summary.md index 10279471a..e6423c6c2 100644 --- a/docs/ja/_summary.md +++ b/docs/ja/_summary.md @@ -121,6 +121,7 @@ * [ドライバ](ja/hardware_drivers.md) * [ADC ドライバ](ja/adc_driver.md) * [I2C ドライバ](ja/i2c_driver.md) + * [SPI ドライバ](ja/spi_driver.md) * [WS2812 ドライバ](ja/ws2812_driver.md) * [EEPROM ドライバ](ja/eeprom_driver.md) * [GPIO コントロール](ja/internals_gpio_control.md) diff --git a/docs/ja/faq_debug.md b/docs/ja/faq_debug.md index 8e42aebbb..856e9473a 100644 --- a/docs/ja/faq_debug.md +++ b/docs/ja/faq_debug.md @@ -152,10 +152,3 @@ https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034 https://github.com/tmk/tmk_keyboard/issues/266 https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778 - - - -## FLIP が動作しない -### `AtLibUsbDfu.dll` が見つかりません -デバイスマネージャから現在のドライバを削除し、FLIP が提供するものを再インストールします。 -http://imgur.com/a/bnwzy diff --git a/docs/ja/feature_advanced_keycodes.md b/docs/ja/feature_advanced_keycodes.md index d208d7f92..c6e21feb9 100644 --- a/docs/ja/feature_advanced_keycodes.md +++ b/docs/ja/feature_advanced_keycodes.md @@ -54,11 +54,11 @@ QMK を使い始めたばかりの場合は、全てを単純にしたいでし |----------|-------------------------------|----------------------------------------------------| | `LCTL(kc)` | `C(kc)` | 左 Control を押しながら `kc` を押します。 | | `LSFT(kc)` | `S(kc)` | 左 Shift を押しながら `kc` を押します。 | -| `LALT(kc)` | `A(kc)` | 左 Alt を押しながら `kc`を押します。 | +| `LALT(kc)` | `A(kc)`, `LOPT(kc)` | 左 Alt を押しながら `kc`を押します。 | | `LGUI(kc)` | `G(kc)`, `LCMD(kc)`, `LWIN(kc)` | 左 GUI を押しながら `kc` を押します。 | | `RCTL(kc)` | | 右 Control を押しながら `kc` を押します。 | | `RSFT(kc)` | | 右 Shift を押しながら `kc` を押します。 | -| `RALT(kc)` | `ALGR(kc)` | 右 Alt を押しながら `kc` を押します。 | +| `RALT(kc)` | `ROPT(kc)`, `ALGR(kc)` | 右 Alt を押しながら `kc` を押します。 | | `RGUI(kc)` | `RCMD(kc)`, `LWIN(kc)` | 右 GUI を押しながら `kc` を押します。 | | `SGUI(kc)` | `SCMD(kc)`, `SWIN(kc)` | 左 Shift と左 GUI を押しながら `kc` を押します。 | | `LCA(kc)` | | 左 Control と左 Alt を押しながら `kc` を押します。 | diff --git a/docs/ja/feature_combo.md b/docs/ja/feature_combo.md new file mode 100644 index 000000000..4fbd6847d --- /dev/null +++ b/docs/ja/feature_combo.md @@ -0,0 +1,108 @@ +# コンボ + +<!--- + original document: 0.8.94:docs/feature_combo.md + git diff 0.8.94 HEAD -- docs/feature_combo.md | cat +--> + +コンボ機能は、同時押し方式でのカスタムアクション追加機能です。同時に複数のキーを押して、異なる効果を生み出すことができます。例えば、タッピング時間内で `A` と `S` を押すと、代わりに `ESC` が押されます。もっと複雑なタスクを実行させることもできます。 + +この機能を有効にするには、`rules.mk` に `COMBO_ENABLE = yes` を追加する必要があります。 + +さらに、使用するコンボの数を `config.h` の中で、`#define COMBO_COUNT 1` (1を使用するコンボの数で置き換えます)と書いて、指定する必要があります。 +<!-- At this time, this is necessary --> + +また、デフォルトでは、コンボのタッピング時間は `TAPPING_TERM` と同じ値に設定されます (ほとんどのキーボードではデフォルトで 200)。ただし、`config.h` で定義することにより異なる値を指定することができます。例えば: `#define COMBO_TERM 300` はコンボのためのタイムアウト時間を 300ms に設定します。 + +次に、`keymap.c` ファイルに、`COMBO_END` で終了するキーのシーケンス、およびキーの組み合わせを列挙する構造体、その結果のアクションを定義する必要があります。 + +```c +const uint16_t PROGMEM test_combo[] = {KC_A, KC_B, COMBO_END}; +combo_t key_combos[COMBO_COUNT] = {COMBO(test_combo, KC_ESC)}; +``` + +これは、A と B のキーを押した場合に、"Escape" を送信します。 + +!> このメソッドは[基本的なキーコード](ja/keycodes_basic.md)のみをサポートします。詳細な制御については例を見てください。 + +## 例 + +リストを追加したい場合は、以下のようなものを使います: + +```c +enum combos { + AB_ESC, + JK_TAB +}; + +const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END}; +const uint16_t PROGMEM jk_combo[] = {KC_J, KC_K, COMBO_END}; + +combo_t key_combos[COMBO_COUNT] = { + [AB_ESC] = COMBO(ab_combo, KC_ESC), + [JK_TAB] = COMBO(jk_combo, KC_TAB) +}; +``` + +より複雑な実装として、カスタム処理を追加するために `process_combo_event` 関数を使うことができます。 + +```c +enum combo_events { + ZC_COPY, + XV_PASTE +}; + +const uint16_t PROGMEM copy_combo[] = {KC_Z, KC_C, COMBO_END}; +const uint16_t PROGMEM paste_combo[] = {KC_X, KC_V, COMBO_END}; + +combo_t key_combos[COMBO_COUNT] = { + [ZC_COPY] = COMBO_ACTION(copy_combo), + [XV_PASTE] = COMBO_ACTION(paste_combo), +}; + +void process_combo_event(uint8_t combo_index, bool pressed) { + switch(combo_index) { + case ZC_COPY: + if (pressed) { + tap_code16(LCTL(KC_C)); + } + break; + case XV_PASTE: + if (pressed) { + tap_code16(LCTL(KC_V)); + } + break; + } +} +``` + +これは、Z と C を押すと Ctrl+C を送信し、X と V を押すと Ctrl+V を送信します。これを変更して、レイヤーの変更、サウンドの再生、設定の変更などを行うこともできます。 + +## 追加の設定 + +長いコンボあるいはさらに長いコンボを使っている場合、構造体があなたのしていることに対応するのに十分な大きさで無いかもしれないため、問題が発生するかもしれません。 + +この場合、`config.h` ファイルに `#define EXTRA_LONG_COMBOS` または `#define EXTRA_EXTRA_LONG_COMBOS` のどちらかを追加することができます。 + +`COMBO_ALLOW_ACTION_KEYS` を定義することでアクションキーを有効にすることもできます。 + +## キーコード + +その場でコンボ機能を有効、無効および切り替えすることができます。ゲームなどで、一時的にそれらを無効にする必要がある場合に便利です。 + +| キーコード | 説明 | +|----------|---------------------------------| +| `CMB_ON` | コンボ機能をオンにします | +| `CMB_OFF` | コンボ機能をオフにします | +| `CMB_TOG` | コンボ機能のオンとオフを切り替えます | + +## ユーザコールバック + +キーコードに加えて、状態を設定または状態をチェックするために使うことができる幾つかの関数があります: + +| 関数 | 説明 | +|-----------|--------------------------------------------------------------------| +| `combo_enable()` | コンボ機能を有効にします | +| `combo_disable()` | コンボ機能を無効にし、コンボバッファをクリアします | +| `combo_toggle()` | コンボ機能の状態を切り替えます | +| `is_combo_enabled()` | コンボ機能の状態(true か false)を返します | diff --git a/docs/ja/feature_dip_switch.md b/docs/ja/feature_dip_switch.md new file mode 100644 index 000000000..1403485ca --- /dev/null +++ b/docs/ja/feature_dip_switch.md @@ -0,0 +1,95 @@ +# DIP スイッチ + +<!--- + original document: 0.8.94:docs/feature_dip_switch.md + git diff 0.8.94 HEAD -- docs/feature_dip_switch.md | cat +--> + +DIP スイッチは、以下を `rules.mk` に追加することでサポートされます: + + DIP_SWITCH_ENABLE = yes + +さらに、以下を `config.h` に追加します: + +```c +#define DIP_SWITCH_PINS { B14, A15, A10, B9 } +``` + +## コールバック + +コールバック関数を `<keyboard>.c` に記述することができます: + +```c +void dip_switch_update_kb(uint8_t index, bool active) { + dip_switch_update_user(index, active); +} +``` + + +あるいは `keymap.c` に記述することもできます: + +```c +void dip_switch_update_user(uint8_t index, bool active) { + switch (index) { + case 0: + if(active) { audio_on(); } else { audio_off(); } + break; + case 1: + if(active) { clicky_on(); } else { clicky_off(); } + break; + case 2: + if(active) { music_on(); } else { music_off(); } + break; + case 3: + if (active) { + #ifdef AUDIO_ENABLE + PLAY_SONG(plover_song); + #endif + layer_on(_PLOVER); + } else { + #ifdef AUDIO_ENABLE + PLAY_SONG(plover_gb_song); + #endif + layer_off(_PLOVER); + } + break; + } +} +``` + +更に、より複雑な処理ができるビットマスク関数をサポートします。 + + +```c +void dip_switch_update_mask_kb(uint32_t state) { + dip_switch_update_mask_user(state); +} +``` + + +あるいは `keymap.c` に記述することもできます: + +```c +void dip_switch_update_mask_user(uint32_t state) { + if (state & (1UL<<0) && state & (1UL<<1)) { + layer_on(_ADJUST); // C on esc + } else { + layer_off(_ADJUST); + } + if (state & (1UL<<0)) { + layer_on(_TEST_A); // A on ESC + } else { + layer_off(_TEST_A); + } + if (state & (1UL<<1)) { + layer_on(_TEST_B); // B on esc + } else { + layer_off(_TEST_B); + } +} +``` + + +## ハードウェア + +DIP スイッチの片側は MCU のピンへ直接配線し、もう一方の側はグラウンドに配線する必要があります。機能的に同じであるため、どちら側がどちらに接続されているかは問題にはならないはずです。 diff --git a/docs/ja/flashing.md b/docs/ja/flashing.md index 62baa907d..713d4fdf9 100644 --- a/docs/ja/flashing.md +++ b/docs/ja/flashing.md @@ -31,7 +31,6 @@ BOOTLOADER = atmel-dfu * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI) * QMK の [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` (推奨のコマンドライン) -* [Atmel の Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (非推奨) 書き込み手順: diff --git a/docs/ja/getting_started_vagrant.md b/docs/ja/getting_started_vagrant.md index 0bc5c4b79..66fb89510 100644 --- a/docs/ja/getting_started_vagrant.md +++ b/docs/ja/getting_started_vagrant.md @@ -25,7 +25,6 @@ Vagrant 以外に、適切なプロバイダがインストールされ、その * [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (推奨) * [Teensy ローダー](https://www.pjrc.com/teensy/loader.html) -* [Atmel FLIP](http://www.atmel.com/tools/flip.aspx) コマンドラインでプログラムしたい場合は、Vagranfile の ['modifyvm'] 行のコメントを解除して Linux への USB パススルーを有効にし、dfu-util/dfu-programmer のようなコマンドラインツールを使ってプログラムすることができます。あるいは Teensy CLI バージョンをインストールすることができます。 diff --git a/docs/keycodes.md b/docs/keycodes.md index 1a388f106..18fd81118 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -175,11 +175,11 @@ See also: [Basic Keycodes](keycodes_basic.md) |`KC_EXSEL` | |ExSel | |`KC_LCTRL` |`KC_LCTL` |Left Control | |`KC_LSHIFT` |`KC_LSFT` |Left Shift | -|`KC_LALT` | |Left Alt | +|`KC_LALT` |`KC_LOPT` |Left Alt (Option) | |`KC_LGUI` |`KC_LCMD`, `KC_LWIN` |Left GUI (Windows/Command/Meta key) | |`KC_RCTRL` |`KC_RCTL` |Right Control | |`KC_RSHIFT` |`KC_RSFT` |Right Shift | -|`KC_RALT` |`KC_ALGR` |Right Alt (AltGr) | +|`KC_RALT` |`KC_ROPT`, `KC_ALGR` |Right Alt (Option/AltGr) | |`KC_RGUI` |`KC_RCMD`, `KC_RWIN` |Right GUI (Windows/Command/Meta key) | |`KC_SYSTEM_POWER` |`KC_PWR` |System Power Down | |`KC_SYSTEM_SLEEP` |`KC_SLEP` |System Sleep | @@ -378,11 +378,11 @@ See also: [Modifier Keys](feature_advanced_keycodes.md#modifier-keys) |----------|-------------------------------|----------------------------------------------------| |`LCTL(kc)`|`C(kc)` |Hold Left Control and press `kc` | |`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` | -|`LALT(kc)`|`A(kc)` |Hold Left Alt and press `kc` | +|`LALT(kc)`|`A(kc)`, `LOPT(kc)` |Hold Left Alt and press `kc` | |`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc` | |`RCTL(kc)`| |Hold Right Control and press `kc` | |`RSFT(kc)`| |Hold Right Shift and press `kc` | -|`RALT(kc)`|`ALGR(kc)` |Hold Right Alt and press `kc` | +|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)` |Hold Right Alt and press `kc` | |`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)` |Hold Right GUI and press `kc` | |`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)` |Hold Left Shift and GUI and press `kc` | |`LCA(kc)` | |Hold Left Control and Alt and press `kc` | @@ -401,11 +401,11 @@ See also: [Mod-Tap](mod_tap.md) |`MT(mod, kc)`| |`mod` when held, `kc` when tapped | |`LCTL_T(kc)` |`CTL_T(kc)` |Left Control when held, `kc` when tapped | |`LSFT_T(kc)` |`SFT_T(kc)` |Left Shift when held, `kc` when tapped | -|`LALT_T(kc)` |`ALT_T(kc)` |Left Alt when held, `kc` when tapped | +|`LALT_T(kc)` |`LOPT_T(kc)`, `ALT_T(kc)`, `OPT_T(kc)` |Left Alt when held, `kc` when tapped | |`LGUI_T(kc)` |`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped | |`RCTL_T(kc)` | |Right Control when held, `kc` when tapped | |`RSFT_T(kc)` | |Right Shift when held, `kc` when tapped | -|`RALT_T(kc)` |`ALGR_T(kc)` |Right Alt when held, `kc` when tapped | +|`RALT_T(kc)` |`ROPT_T(kc)`, `ALGR_T(kc)` |Right Alt when held, `kc` when tapped | |`RGUI_T(kc)` |`RCMD_T(kc)`, `RWIN_T(kc)` |Right GUI when held, `kc` when tapped | |`SGUI_T(kc)` |`SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped | |`LCA_T(kc)` | |Left Control and Alt when held, `kc` when tapped | diff --git a/docs/keycodes_basic.md b/docs/keycodes_basic.md index 75d58c1f1..09efc8c9c 100644 --- a/docs/keycodes_basic.md +++ b/docs/keycodes_basic.md @@ -112,11 +112,11 @@ The basic set of keycodes are based on the [HID Keyboard/Keypad Usage Page (0x07 |-----------|--------------------|------------------------------------| |`KC_LCTRL` |`KC_LCTL` |Left Control | |`KC_LSHIFT`|`KC_LSFT` |Left Shift | -|`KC_LALT` | |Left Alt | +|`KC_LALT` |`KC_LOPT` |Left Alt (Option) | |`KC_LGUI` |`KC_LCMD`, `KC_LWIN`|Left GUI (Windows/Command/Meta key) | |`KC_RCTRL` |`KC_RCTL` |Right Control | |`KC_RSHIFT`|`KC_RSFT` |Right Shift | -|`KC_RALT` |`KC_ALGR` |Right Alt (AltGr) | +|`KC_RALT` |`KC_ROPT`, `KC_ALGR`|Right Alt (Option/AltGr) | |`KC_RGUI` |`KC_RCMD`, `KC_RWIN`|Right GUI (Windows/Command/Meta key)| ## International diff --git a/docs/mod_tap.md b/docs/mod_tap.md index 2b86701ca..ced0beba9 100644 --- a/docs/mod_tap.md +++ b/docs/mod_tap.md @@ -31,11 +31,11 @@ For convenience, QMK includes some Mod-Tap shortcuts to make common combinations |------------|-----------------------------------------------------------------|-------------------------------------------------------| |`LCTL_T(kc)`|`CTL_T(kc)` |Left Control when held, `kc` when tapped | |`LSFT_T(kc)`|`SFT_T(kc)` |Left Shift when held, `kc` when tapped | -|`LALT_T(kc)`|`ALT_T(kc)` |Left Alt when held, `kc` when tapped | +|`LALT_T(kc)`|`LOPT_T(kc)`, `ALT_T(kc)`, `OPT_T(kc)` |Left Alt when held, `kc` when tapped | |`LGUI_T(kc)`|`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped | |`RCTL_T(kc)`| |Right Control when held, `kc` when tapped | |`RSFT_T(kc)`| |Right Shift when held, `kc` when tapped | -|`RALT_T(kc)`|`ALGR_T(kc)` |Right Alt when held, `kc` when tapped | +|`RALT_T(kc)`|`ROPT_T(kc)`, `ALGR_T(kc)` |Right Alt when held, `kc` when tapped | |`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)` |Right GUI when held, `kc` when tapped | |`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped | |`LCA_T(kc)` | |Left Control and Alt when held, `kc` when tapped | diff --git a/docs/newbs_getting_started.md b/docs/newbs_getting_started.md index 8ffbb9117..c8916b0e2 100644 --- a/docs/newbs_getting_started.md +++ b/docs/newbs_getting_started.md @@ -78,7 +78,7 @@ After installing QMK you can set it up with this command: In most situations you will want to answer Yes to all of the prompts. -?> If you already know [how to use GitHub](getting_started_github.md), we recommend that you create your own fork and use `qmk setup <github_username>` to clone your personal fork. If you don't know what that means you can safely ignore this message. +?> If you already know [how to use GitHub](getting_started_github.md), we recommend that you create your own fork and use `qmk setup <github_username>/qmk_firmware` to clone your personal fork. If you don't know what that means you can safely ignore this message. ## 4. Test Your Build Environment diff --git a/docs/platformdev_chibios_earlyinit.md b/docs/platformdev_chibios_earlyinit.md new file mode 100644 index 000000000..699c22377 --- /dev/null +++ b/docs/platformdev_chibios_earlyinit.md @@ -0,0 +1,53 @@ +# Arm/ChibiOS Early Initialization :id=chibios-early-init + +This page describes a part of QMK that is a somewhat advanced concept, and is only relevant to keyboard designers. + +QMK uses ChibiOS as the underlying layer to support a multitude of Arm-based devices. Each ChibiOS-supported keyboard has a low-level board definition which is responsible for initializing hardware peripherals such as the clocks, and GPIOs. + +Older QMK revisions required duplication of these board definitions inside your keyboard's directory in order to override such early initialization points; this is now abstracted into the following APIs, and allows usage of the board definitions supplied with ChibiOS itself. Check `<qmk_firmware>/lib/chibios/os/hal/boards` for the list of official definitions. If your keyboard needs extra initialization at a very early stage, consider providing keyboard-level overrides of the following APIs: + +## `early_hardware_init_pre()` :id=early-hardware-init-pre + +The function `early_hardware_init_pre` is the earliest possible code that can be executed by a keyboard firmware. This is intended as a replacement for the ChibiOS board definition's `__early_init` function, and is the equivalent of executing at the start of the function. + +This is executed before RAM gets cleared, and before clocks or GPIOs are configured; any delays or preparation using GPIOs is not likely to work at this point. After executing this function, RAM on the MCU may be zero'ed. Assigning values to variables during execution of this function may be overwritten. + +As such, if you wish to override this API consider limiting use to writing to low-level registers. The default implementation of this function can be configured to jump to bootloader if a `RESET` key was pressed, by ensuring `#define EARLY_INIT_PERFORM_BOOTLOADER_JUMP TRUE` is in the keyboard's `config.h` file. + +To implement your own version of this function, in your keyboard's source files: + +```c +void early_hardware_init_pre(void) { + // do things with registers +} +``` + +## `early_hardware_init_post()` :id=early-hardware-init-post + +The function `early_hardware_init_post` is the next earliest possible code that can be executed by a keyboard firmware. This is executed after RAM has been cleared, and clocks and GPIOs are configured. This is intended as a replacement for the ChibiOS board definition's `__early_init` function, and is the equivalent of executing at the end of the function. + +Much like `early_hardware_init_pre`, ChibiOS has not yet been initialized either, so the same restrictions on delays and timing apply. + +If you wish to override this API, consider limiting functionality to register writes, variable initialization, and GPIO toggling. The default implementation of this function is to do nothing. + +To implement your own version of this function, in your keyboard's source files: + +```c +void early_hardware_init_post(void) { + // toggle GPIO pins and write to variables +} +``` + +## `board_init()` :id=board-init + +The function `board_init` is executed directly after the ChibiOS initialization routines have completed. At this stage, all normal low-level functionality should be available for use (including timers and delays), with the restriction that USB is not yet connected. This is intended as a replacement for the ChibiOS board definition's `boardInit` function. + +The default implementation of this function is to do nothing. + +To implement your own version of this function, in your keyboard's source files: + +```c +void board_init(void) { + // initialize anything that requires ChibiOS +} +```
\ No newline at end of file diff --git a/docs/proton_c_conversion.md b/docs/proton_c_conversion.md index dc0a3f484..98f1508a9 100644 --- a/docs/proton_c_conversion.md +++ b/docs/proton_c_conversion.md @@ -1,5 +1,9 @@ # Converting a board to use the Proton C +Since the Proton C is a drop-in replacement for a Pro Micro we've made it easy to use. This page documents a handy automated process for converting keyboards, as well as documenting the manual process if you'd like to make use of Proton C features that aren't available on Pro Micros. + +## Automatic Conversion + If a board currently supported in QMK uses a Pro Micro (or compatible board) and you want to use the Proton C, you can generate the firmware by appending `CONVERT_TO_PROTON_C=yes` (or `CTPC=yes`) to your make argument, like this: make 40percentclub/mf68:default CTPC=yes @@ -8,13 +12,15 @@ You can add the same argument to your keymap's `rules.mk`, which will accomplish This exposes the `CONVERT_TO_PROTON_C` flag that you can use in your code with `#ifdef`s, like this: - #ifdef CONVERT_TO_PROTON_C - // Proton C code - #else - // Pro Micro code - #endif +```c +#ifdef CONVERT_TO_PROTON_C + // Proton C code +#else + // Pro Micro code +#endif +``` -Before being able to compile, you may get some errors about `PORTB/DDRB`, etc not being defined, so you'll need to convert the keyboard's code to use the [GPIO Controls](internals_gpio_control.md) that will work for both ARM and AVR. This shouldn't affect the AVR builds at all. +If you get errors about `PORTB/DDRB`, etc not being defined, so you'll need to convert the keyboard's code to use the [GPIO Controls](internals_gpio_control.md) that will work for both ARM and AVR. This shouldn't affect the AVR builds at all. The Proton C only has one on-board LED (C13), and by default, the TXLED (D5) is mapped to it. If you want the RXLED (B0) mapped to it instead, add this like to your `config.h`: @@ -31,3 +37,54 @@ These are defaults based on what has been implemented for ARM boards. | [Backlight](feature_backlight.md) | Forces [task driven PWM](feature_backlight.md#software-pwm-driver) until ARM can provide automatic configuration | | USB Host (e.g. USB-USB converter) | Not supported (USB host code is AVR specific and is not currently supported on ARM) | | [Split keyboards](feature_split_keyboard.md) | Not supported yet | + +## Manual Conversion + +To use the Proton C natively, without having to specify `CTPC=yes`, you need to change the `MCU` line in `rules.mk`: + +``` +MCU = STM32F303 +``` + +Remove these variables if they exist: + +* `BOOTLOADER` +* `EXTRA_FLAGS` + +Finally convert all pin assignments in `config.h` to the stm32 equivalents. + +| Pro Micro Left | Proton C Left | | Proton C Right | Pro Micro Right | +|-----------|----------|-|----------|-----------| +| `D3` | `A9` | | 5v | RAW (5v) | +| `D2` | `A10` | | GND | GND | +| GND | GND | | FLASH | RESET | +| GND | GND | | 3.3v | VCC <sup>1</sup> | +| `D1` | `B7` | | `A2` | `F4` | +| `D0` | `B6` | | `A1` | `F5` | +| `D4` | `B5` | | `A0` | `F6` | +| `C6` | `B4` | | `B8` | `F7` | +| `D7` | `B3` | | `B13` | `B1` | +| `E6` | `B2` | | `B14` | `B3` | +| `B4` | `B1` | | `B15` | `B2` | +| `B5` | `B0` | | `B9` | `B6` | +| `B0` (RX LED) | `C13` <sup>2</sup> | | `C13` <sup>2</sup> | `D5` (TX LED) | + +You can also make use of several new pins on the extended portion of the Proton C: + +| Left | | Right | +|------|-|-------| +| `A4`<sup>3</sup> | | `B10` | +| `A5`<sup>4</sup> | | `B11` | +| `A6` | | `B12` | +| `A7` | | `A14`<sup>5</sup> (SWCLK) | +| `A8` | | `A13`<sup>5</sup> (SWDIO) | +| `A15` | | RESET<sup>6</sup> | + +Notes: + +1. On a Pro Micro VCC can be 3.3v or 5v. +2. A Proton C only has one onboard LED, not two like a Pro Micro. The Pro Micro has an RX LED on `D5` and a TX LED on `B0`. +3. `A4` is shared with the speaker. +4. `A5` is shared with the speaker. +5. `A13` and `A14` are used for hardware debugging (SWD). You can also use them for GPIO, but should use them last. +6. Short RESET to 3.3v (pull high) to reboot the MCU. This does not enter bootloader mode like a Pro Micro, it only resets the MCU. diff --git a/docs/pt-br/_summary.md b/docs/pt-br/_summary.md index 9c29c5a3a..78b3b2021 100644 --- a/docs/pt-br/_summary.md +++ b/docs/pt-br/_summary.md @@ -98,6 +98,7 @@ * [ISP Flashing Guide](pt-br/isp_flashing_guide.md) * [ARM Debugging Guide](pt-br/arm_debugging.md) * [I2C Driver](pt-br/i2c_driver.md) + * [SPI Driver](pt-br/spi_driver.md) * [GPIO Controls](pt-br/internals_gpio_control.md) * [Proton C Conversion](pt-br/proton_c_conversion.md) diff --git a/docs/ref_functions.md b/docs/ref_functions.md index 708b0be28..57f701d79 100644 --- a/docs/ref_functions.md +++ b/docs/ref_functions.md @@ -8,7 +8,7 @@ There are actually separate functions that you can use there, depending on what ### `update_tri_layer(x, y, z)` -The first is the `update_tri_layer(x, y, z)` function. This function check to see if layers `x` and `y` are both on. If they are both on, then it runs on layer `z`. Otherwise, if both `x` and `y` are not both on (either only one is, or neither is), then it runs off layer `z`. +The first is the `update_tri_layer(x, y, z)` function. This function check to see if layers `x` and `y` are both on. If they are both on, then it turns on layer `z`. Otherwise, if both `x` and `y` are not both on (either only one is, or neither is), then it turns off layer `z`. This function is useful if you want to create specific keys that have this functionality, but other layer keycodes won't do this. @@ -43,7 +43,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { ``` ### `update_tri_layer_state(state, x, y, z)` -The other function is `update_tri_layer_state(state, x, y, z)`. This function is meant to be called from they [`layer_state_set_*` functions](custom_quantum_functions.md#layer-change-code). This means that any time that you use a keycode to change the layer, this will be checked. So you could use `LT(layer, kc)` to change the layer and it will trigger the same layer check. +The other function is `update_tri_layer_state(state, x, y, z)`. This function is meant to be called from the [`layer_state_set_*` functions](custom_quantum_functions.md#layer-change-code). This means that any time that you use a keycode to change the layer, this will be checked. So you could use `LT(layer, kc)` to change the layer and it will trigger the same layer check. The caveat to this method is that you cannot access the `z` layer without having `x` and `y` layers on, since if you try to activate just layer `z`, it will run this code and turn off layer `z` before you could use it. diff --git a/docs/reference_glossary.md b/docs/reference_glossary.md index 08a22050c..4cdba024e 100644 --- a/docs/reference_glossary.md +++ b/docs/reference_glossary.md @@ -46,9 +46,6 @@ An IDE that is popular with many C developers. ## Firmware The software that controls your MCU. -## FLIP -Software provided by Atmel for flashing AVR devices. We generally recommend [QMK Flasher](https://github.com/qmk/qmk_flasher) instead, but for some advanced use cases FLIP is required. - ## git Versioning software used at the command line diff --git a/docs/ru-ru/_summary.md b/docs/ru-ru/_summary.md index caa7cdd56..f893be3cf 100644 --- a/docs/ru-ru/_summary.md +++ b/docs/ru-ru/_summary.md @@ -99,6 +99,7 @@ * [ISP Flashing Guide](ru-ru/isp_flashing_guide.md) * [ARM Debugging Guide](ru-ru/arm_debugging.md) * [I2C Driver](ru-ru/i2c_driver.md) + * [SPI Driver](ru-ru/spi_driver.md) * [WS2812 Driver](ru-ru/ws2812_driver.md) * [GPIO Controls](ru-ru/internals_gpio_control.md) * [Proton C Conversion](ru-ru/proton_c_conversion.md) diff --git a/docs/spi_driver.md b/docs/spi_driver.md new file mode 100644 index 000000000..e2b5b140b --- /dev/null +++ b/docs/spi_driver.md @@ -0,0 +1,121 @@ +# SPI Master Driver + +The SPI Master drivers used in QMK have a set of common functions to allow portability between MCUs. + +## AVR Configuration + +No special setup is required - just connect the `SS`, `SCK`, `MOSI` and `MISO` pins of your SPI devices to the matching pins on the MCU: + +|MCU |`SS`|`SCK`|`MOSI`|`MISO`| +|---------------|----|-----|------|------| +|ATMega16/32U2/4|`B0`|`B1` |`B2` |`B3` | +|AT90USB64/128 |`B0`|`B1` |`B2` |`B3` | +|ATmega32A |`B4`|`B7` |`B5` |`B6` | +|ATmega328P |`B2`|`B5` |`B3` |`B4` | + +You may use more than one slave select pin, not just the `SS` pin. This is useful when you have multiple devices connected and need to communicate with them individually. +`SPI_SS_PIN` can be passed to `spi_start()` to refer to `SS`. + +## ChibiOS/ARM Configuration + +ARM support for this driver is not ready yet. Check back later! + +## Functions + +### `void spi_init(void)` + +Initialize the SPI driver. This function must be called only once, before any of the below functions can be called. + +--- + +### `bool spi_start(pin_t slavePin, bool lsbFirst, uint8_t mode, uint16_t divisor)` + +Start an SPI transaction. + +#### Arguments + + - `pin_t slavePin` + The QMK pin to assert as the slave select pin, eg. `B4`. + - `bool lsbFirst` + Determines the endianness of the transmission. If `true`, the least significant bit of each byte is sent first. + - `uint8_t mode` + The SPI mode to use: + + |Mode|Clock Polarity |Clock Phase | + |----|--------------------|-----------------------| + |`0` |Leading edge rising |Sample on leading edge | + |`1` |Leading edge rising |Sample on trailing edge| + |`2` |Leading edge falling|Sample on leading edge | + |`3` |Leading edge falling|Sample on trailing edge| + + - `uint16_t divisor` + The SPI clock divisor, will be rounded up to the nearest power of two. This number can be calculated by dividing the MCU's clock speed by the desired SPI clock speed. For example, an MCU running at 8 MHz wanting to talk to an SPI device at 4 MHz would set the divisor to `2`. + +#### Return Value + +`false` if the supplied parameters are invalid or the SPI peripheral is already in use, or `true`. + +--- + +### `spi_status_t spi_write(uint8_t data)` + +Write a byte to the selected SPI device. + +#### Arguments + + - `uint8_t data` + The byte to write. + +#### Return Value + +`SPI_STATUS_TIMEOUT` if the timeout period elapses, or `SPI_STATUS_SUCCESS`. + +--- + +### `spi_status_t spi_read(void)` + +Read a byte from the selected SPI device. + +#### Return Value + +`SPI_STATUS_TIMEOUT` if the timeout period elapses, or the byte read from the device. + +--- + +### `spi_status_t spi_transmit(const uint8_t *data, uint16_t length)` + +Send multiple bytes to the selected SPI device. + +#### Arguments + + - `const uint8_t *data` + A pointer to the data to write from. + - `uint16_t length` + The number of bytes to write. Take care not to overrun the length of `data`. + +#### Return Value + +`SPI_STATUS_TIMEOUT` if the timeout period elapses, `SPI_STATUS_SUCCESS` on success, or `SPI_STATUS_ERROR` otherwise. + +--- + +### `spi_status_t spi_receive(uint8_t *data, uint16_t length)` + +Receive multiple bytes from the selected SPI device. + +#### Arguments + + - `uint8_t *data` + A pointer to the buffer to read into. + - `uint16_t length` + The number of bytes to read. Take care not to overrun the length of `data`. + +#### Return Value + +`SPI_STATUS_TIMEOUT` if the internal transmission timeout period elapses, `SPI_STATUS_SUCCESS` on success, or `SPI_STATUS_ERROR` otherwise. + +--- + +### `void spi_stop(void)` + +End the current SPI transaction. This will deassert the slave select pin and reset the endianness, mode and divisor configured by `spi_start()`. diff --git a/docs/zh-cn/_summary.md b/docs/zh-cn/_summary.md index 12bd07a21..201b83894 100644 --- a/docs/zh-cn/_summary.md +++ b/docs/zh-cn/_summary.md @@ -104,6 +104,7 @@ * [ARM调试指南](zh-cn/arm_debugging.md) * [ADC设备](zh-cn/adc_driver.md) * [I2C设备](zh-cn/i2c_driver.md) + * [SPI设备](zh-cn/spi_driver.md) * [WS2812设备](zh-cn/ws2812_driver.md) * [EEPROM设备](zh-cn/eeprom_driver.md) * [GPIO控制](zh-cn/internals_gpio_control.md) diff --git a/docs/zh-cn/faq_debug.md b/docs/zh-cn/faq_debug.md index 7eff7f265..71b575ea0 100644 --- a/docs/zh-cn/faq_debug.md +++ b/docs/zh-cn/faq_debug.md @@ -139,10 +139,3 @@ https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034 https://github.com/tmk/tmk_keyboard/issues/266 https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778 - - - -## FLIP 不工作 -### `AtLibUsbDfu.dll` 未找到 -从设备管理器中删除当前驱动程序并在设备管理器重新安装一个FLIP提供的程序。 -http://imgur.com/a/bnwzy diff --git a/docs/zh-cn/reference_glossary.md b/docs/zh-cn/reference_glossary.md index 7b9adcc2a..0e0521221 100644 --- a/docs/zh-cn/reference_glossary.md +++ b/docs/zh-cn/reference_glossary.md @@ -46,9 +46,6 @@ Français (法国)标准键盘布局。用键盘的前六个字母命名。 ## Firmware(固件) 用来控制单片机的软件。 -## FLIP -爱特梅尔(Atmel)提供的AVR器件刷写软件。我们一般推荐 [QMK刷写工具](https://github.com/qmk/qmk_flasher)，但是对于一些高级用例，需要FLIP。 - ## git 命令行版本控制软件 |