gitbot/qmk_firmware
0
0
Fork 0
mirror of https://github.com/qmk/qmk_firmware.git synced 2024-11-22 03:19:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1554 from qmk/docs

Browse Source 
Updates some remaining doc stuff
This commit is contained in:
Jack Humbert 2017-08-06 22:29:59 -04:00 committed by GitHub
commit 9e79bb1491
4 changed files with 241 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
book.json
View File

@ -3,12 +3,9 @@
"summary": "_summary.md"
},
"plugins" : [
"anchors",
"edit-link",
"forkmegithub",
"git-author",
"hints",
"numbered-headings",
"page-toc",
"terminal",
"toolbar"
@ -25,6 +22,11 @@
"page-toc": {
"selector": ".markdown-section h1, .markdown-section h2"
},
"terminal": {
"copyButtons": true,
"fade": false,
"style": "flat"
},
"toolbar": {
"buttons": [
{

38
docs/documentation_best_practices.md
View File

@ -22,6 +22,14 @@ Your page should generally have multiple "H1" headings. Only H1 and H2 headings
You can have styled hint blocks drawn around text to draw attention to it.
```
{% hint style='info' %}
This uses `hint style='info'`
{% endhint %}
```
### Examples:
{% hint style='info' %}
This uses `hint style='info'`
{% endhint %}
@ -37,3 +45,33 @@ This uses `hint style='danger'`
{% hint style='working' %}
This uses `hint style='working'`
{% endhint %}
# Styled Terminal Blocks
You can present styled terminal blocks by including special tokens inside your text block.
```
\`\`\`
**[terminal]
**[prompt foo@joe]**[path ~]**[delimiter $ ]**[command ./myscript]
Normal output line. Nothing special here...
But...
You can add some colors. What about a warning message?
**[warning [WARNING] The color depends on the theme. Could look normal too]
What about an error message?
**[error [ERROR] This is not the error you are looking for]
\`\`\`
```
### Example
```
**[terminal]
**[prompt foo@joe]**[path ~]**[delimiter $ ]**[command ./myscript]
Normal output line. Nothing special here...
But...
You can add some colors. What about a warning message?
**[warning [WARNING] The color depends on the theme. Could look normal too]
What about an error message?
**[error [ERROR] This is not the error you are looking for]
```

110
docs/faq.md
View File

@ -1,10 +1,16 @@
# Frequently Asked Questions
## What is QMK?
## General
### What is QMK?
[QMK](https://github.com/qmk), short for Quantum Mechanical Keyboard, is a group of people building tools for custom keyboards. We started with the [QMK firmware](https://github.com/qmk/qmk_firmware), a heavily modified fork of [TMK](https://github.com/tmk/tmk_keyboard).
## What Differences Are There Between QMK and TMK?
### Why the name Quantum?
<!-- FIXME -->
### What Differences Are There Between QMK and TMK?
TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert's](https://github.com/jackhumbert) fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK.
@ -14,8 +20,22 @@ From a project and community management standpoint TMK maintains all the officia
Both approaches have their merits and their drawbacks, and code flows freely between TMK and QMK when it makes sense.
# Debug Console
## hid_listen can't recognize device
# Building
## Windows
### I'm on Windows Vista, 7, or 8, how do I setup my build environment?
Follow the build instructions to [install MHV AVR Tools](https://docs.qmk.fm/build_environment_setup.html#windows-vista-and-later).
### I'm on Windows 10 without the Creators Update. Do I have to install it?
No, but if you don't install the creators update you will not be able to build and flash with a single command. You will be able to build but to flash you will have to use a separate program, such as [QMK Flasher](https://github.com/qmk/qmk_flasher).
# Troubleshooting
## Debug Console
### hid_listen can't recognize device
When debug console of your device is not ready you will see like this:
```
@ -34,7 +54,7 @@ If you can't get this 'Listening:' message try building with `CONSOLE_ENABLE=yes
You may need privilege to access the device on OS like Linux.
- try `sudo hid_listen`
## Can't get message on console
### Can't get message on console
Check:
- *hid_listen* finds your device. See above.
- Enable debug with pressing **Magic**+d. See [Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands).
@ -42,7 +62,7 @@ Check:
- try using 'print' function instead of debug print. See **common/print.h**.
- disconnect other devices with console function. See [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97).
## Linux or UNIX like system requires Super User privilege
### Linux or UNIX like system requires Super User privilege
Just use 'sudo' to execute *hid_listen* with privilege.
```
$ sudo hid_listen
@ -56,10 +76,9 @@ File: /etc/udev/rules.d/52-tmk-keyboard.rules(in case of Ubuntu)
SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
```
***
## Software Issues
# Miscellaneous
## NKRO Doesn't work
### NKRO Doesn't work
First you have to compile frimware with this build option `NKRO_ENABLE` in **Makefile**.
Try `Magic` **N** command(`LShift+RShift+N` by default) when **NKRO** still doesn't work. You can use this command to toggle between **NKRO** and **6KRO** mode temporarily. In some situations **NKRO** doesn't work you need to switch to **6KRO** mode, in particular when you are in BIOS.
@ -68,15 +87,7 @@ If your firmeare built with `BOOTMAGIC_ENABLE` you need to turn its switch on by
https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
## TrackPoint needs reset circuit(PS/2 mouse support)
Without reset circuit you will have inconsistent reuslt due to improper initialize of the hardware. See circuit schematic of TPM754.
- http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
- http://www.mikrocontroller.net/attachment/52583/tpm754.pdf
## Can't read column of matrix beyond 16
### Can't read column of matrix beyond 16
Use `1UL<<16` instead of `1<<16` in `read_cols()` in [matrix.h] when your columns goes beyond 16.
In C `1` means one of [int] type which is [16bit] in case of AVR so you can't shift left more than 15. You will get unexpected zero when you say `1<<16`. You have to use [unsigned long] type with `1UL`.
@ -84,16 +95,16 @@ In C `1` means one of [int] type which is [16bit] in case of AVR so you can't sh
http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
## Bootloader jump doesn't work
### Bootloader jump doesn't work
Properly configure bootloader size in **Makefile**. With wrong section size bootloader won't probably start with **Magic command** and **Boot Magic**.
```
# Size of Bootloaders in bytes:
# Atmel DFU loader(ATmega32U4) 4096
# Atmel DFU loader(AT90USB128) 8192
# LUFA bootloader(ATmega32U4) 4096
# Arduino Caterina(ATmega32U4) 4096
# USBaspLoader(ATmega***) 2048
# Teensy halfKay(ATmega32U4) 512
# Atmel DFU loader(ATmega32U4) 4096
# Atmel DFU loader(AT90USB128) 8192
# LUFA bootloader(ATmega32U4) 4096
# Arduino Caterina(ATmega32U4) 4096
# USBaspLoader(ATmega***) 2048
# Teensy halfKay(ATmega32U4) 512
# Teensy++ halfKay(AT90USB128) 2048
OPT_DEFS += -DBOOTLOADER_SIZE=4096
```
@ -107,14 +118,14 @@ byte Atmel/LUFA(ATMega32u4) byte Atmel(AT90SUB1286)
| | | |
| | | |
| Application | | Application |
| | | |
| | | |
= = = =
| | 32KB-4KB | | 128KB-8KB
0x6000 +---------------+ 0x1E000 +---------------+
| Bootloader | 4KB | Bootloader | 8KB
0x7FFF +---------------+ 0x1FFFF +---------------+
byte Teensy(ATMega32u4) byte Teensy++(AT90SUB1286)
0x0000 +---------------+ 0x00000 +---------------+
| | | |
@ -132,20 +143,28 @@ And see this discussion for further reference.
https://github.com/tmk/tmk_keyboard/issues/179
## Special Extra key doesn't work(System, Audio control keys)
### Special Extra key doesn't work(System, Audio control keys)
You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK.
```
EXTRAKEY_ENABLE = yes # Audio control and System control
```
## Wakeup from sleep doesn't work
### Wakeup from sleep doesn't work
In Windows check `Allow this device to wake the computer` setting in Power **Management property** tab of **Device Manager**. Also check BIOS setting.
Pressing any key during sleep should wake host.
## Using Arduino?
## Hardware Issues
### TrackPoint needs reset circuit(PS/2 mouse support)
Without reset circuit you will have inconsistent reuslt due to improper initialize of the hardware. See circuit schematic of TPM754.
- http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
- http://www.mikrocontroller.net/attachment/52583/tpm754.pdf
### Using Arduino?
**Note that Arduino pin naming is different from actual chip.** For example, Arduino pin `D0` is not `PD0`. Check circuit with its schematics yourself.
@ -154,8 +173,7 @@ Pressing any key during sleep should wake host.
Arduino leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem.
## Using PF4-7 pins of USB AVR?
### Using PF4-7 pins of USB AVR?
You need to set JTD bit of MCUCR yourself to use PF4-7 as GPIO. Those pins are configured to serve JTAG function by default. MCUs like ATMega*U* or AT90USB* are affeteced with this.
If you are using Teensy this isn't needed. Teensy is shipped with JTAGEN fuse bit unprogrammed to disable the function.
@ -171,12 +189,7 @@ https://github.com/tmk/tmk_keyboard/blob/master/keyboard/hbkb/matrix.c#L67
And read **26.5.1 MCU Control Register – MCUCR** of ATMega32U4 datasheet.
## Adding LED indicators of Lock keys
You need your own LED indicators for CapsLock, ScrollLock and NumLock? See this post.
http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560
## Program Arduino Micro/Leonardo
### Program Arduino Micro/Leonardo
Push reset button and then run command like this within 8 seconds.
```
@ -188,27 +201,16 @@ Device name will vary depending on your system.
http://arduino.cc/en/Main/ArduinoBoardMicro
https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867
## USB 3 compatibility
I heard some people have a problem with USB 3 port, try USB 2 port.
## Mac compatibility
### OS X 10.11 and Hub
https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
## Problem on BIOS(UEFI)/Resume(Sleep&Wake)/Power cycles
### Problem on BIOS(UEFI)/Resume(Sleep&Wake)/Power cycles
Some people reported their keyboard stops working on BIOS and/or after resume(power cycles).
As of now root of its cause is not clear but some build options seem to be related. In Makefile try to disable those options like `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` and/or others.
As of now root of its cause is not clear but some build options seem to be related. In Makefile try to disable those options like `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` and/or others.
https://github.com/tmk/tmk_keyboard/issues/266
https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
## Flashing Problems
### Can't use dfu-programmer or QMK Flasher to flash on Windows
## FLIP doesn't work
### AtLibUsbDfu.dll not found
Remove current driver and reinstall one FLIP provides from DeviceManager.
http://imgur.com/a/bnwzy
Windows requires a driver to support the keyboard in DFU mode. You can use [QMK Driver Installer](https://github.com/qmk/qmk_driver_installer/releases) to install the necessary drivers.

143
docs/glossary.md
View File

@ -1,29 +1,170 @@
# Glossary of QMK terms
## ARM
A line of 32-bit MCU's produced by a number of companies, such as Atmel, Cypress, Kinetis, NXP, ST, and TI.
## AVR
A line of 8-bit MCU's produced by [Atmel](http://atmel.com). AVR was the original platform that TMK supported.
## AZERTY
The standard Français (French) keyboard layout. Named for the first 6 keys on the keyboard.
## Backlight
A generic term for lighting on a keyboard. The backlight is typically, but not always, an array of LED's that shine through keycaps and/or switches.
## Bluetooth
A short range peer to peer wireless protocol. Most common wireless protocol for a keyboard.
## Bootloader
A special program that is written to a protected area of your MCU that allows the MCU to upgrade its own firmware, typically over USB.
## Bootmagic
A feature that allows for various keyboard behavior changes to happen on the fly, such as swapping or disabling common keys.
## C
A low-level programming language suitable for system code. Most QMK code is written in C.
## Colemak
An alternative keyboard layout that is gaining in popularity.
## Compile
The process of turning human readable code into machine code your MCU can run.
## Dvorak
An alternative keyboard layout developed by Dr. August Dvorak in the 1930's. A shortened form of the Dvorak Simplified Keyboard.
## Dynamic Macro
A macro which has been recorded on the keyboard and which will be lost when the keyboard is unplugged or the computer rebooted.
* [Dynamic Macro Documentation](dynamic_macros.html)
## Eclipse
An IDE that is popular with many C developers.
* [Eclipse Setup Instructions](eclipse.html)
## 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 commandline
## GitHub
The website that hosts most of the QMK project. It provides integration with git, issue tracking, and other features that help us run QMK.
## ISP
In-system programming, a method of programming an AVR chip using external hardware and the JTAG pins.
## hid_listen
An interface for receiving debugging messages from your keyboard. You can view these messages using [QMK Flasher](https://github.com/qmk/qmk_flasher) or [PJRC's hid_listen](https://www.pjrc.com/teensy/hid_listen.html)
## Keycode
A 2-byte number that represents a particular key. `0x00`-`0xFF` are used for [Basic Keycodes](keycodes.html) while `0x100`-`0xFFFF` are used for [Quantum Keycodes](quantum_keycodes.html).
## Key Down
An event that happens when a key is pressed down, but is completed before a key is released.
## Key Up
An event that happens when a key is released.
## Keymap
An array of keycodes mapped to a physical keyboard layout, which are processed on key presses and releases
## Layer
An abstraction used to allow a key to serve multiple purposes. The highest active layer takes precedence.
## Leader Key
A feature that allows you to tap the leader key followed by a sequence of 1, 2, or 3 keys to activate key presses or other quantum features.
* [Leader Key Documentation](leader_key.html)
## LED
Light Emitting Diode, the most common device used for indicators on a keyboard.
## Make
Software package that is used to compile all the source files. You run `make` with various options to compile your keyboard firmware.
## Matrix
A wiring pattern of columns and rows (and usually diodes) that enables the MCU to detect keypresses with a fewer number of pins
A wiring pattern of columns and rows that enables the MCU to detect keypresses with a fewer number of pins. The matrix often incorporates diodes to allow for NKRO.
## Macro
A feature that lets you send muiltple keypress events (hid reports) after having pressed only a single key.
* [Macro Documentation](macros.html)
## MCU
Microcontrol Unit, the processor that powers your keyboard.
## Modifier
A key that is held down while typing another key to modify the action of that key. Examples include Ctrl, Alt, and Shift.
## Mousekeys
A feature that lets you control your mouse cursor and click from your keyboard.
* [Mousekeys Documentation](mouse_keys.html)
## N-Key Rollover (NKRO)
A term that applies to keyboards that are capable of reporting any number of key-presses at once.
## Oneshot Modifier
A modifier that acts as if it is held down until another key is released, so you can press the mod and then press the key, rather than holding the mod while pressing the key.
## ProMicro
A low cost AVR development board. Clones of this device are often found on ebay very inexpensively (under $5) but people often struggle with flashing their pro micros.
## Pull Request
A request to submit code to QMK. We encourage all users to submit Pull Requests for their personal keymaps.
## QWERTY
The standard English keyboard layout, and often a shortcut for other language's standard layouts. Named for the first 6 letters on the keyboard.
## QWERTZ
The standard Deutsche (German) keyboard layout. Named for the first 6 letters on the keyboard.
## Rollover
The term for pressing a key while a key is already held down. Variants include 2KRO, 6KRO, and NKRO.
## Scancode
A 1 byte number that is sent as part of a HID report over USB that represents a single key. These numbers are documented in the [HID Usage Tables](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) published by the [USB-IF](http://www.usb.org/).
## Space Cadet Shift
A special set of shift keys which allow you to type various types of braces by tapping the left or right shift one or more times.
* [Space Cadet Shift Documentation](space_cadet_shift.html)
## Tap
Pressing and releasing a key. In some situations you will need to distinguish between a key down and a key up event, and Tap always refers to both at once.
## Tap Dance
A feature that lets you assign muiltple keycodes to the same key based on how many times you press it.
* [Tap Dance Documentation](tap_dance.html)
## Teensy
A low-cost AVR development board that is commonly used for hand-wired builds. A teensy is often chosen despite costing a few dollors more due to its halfkay bootloader, which makes flashing very simple.
## Underlight
A generic term for LEDs that light the underside of the board. These LED's typically shine away from the bottom of the PCB and towards the surface the keyboard rests on.
## Unicode
In the larger computer world Unicode is a set of encoding schemes for representing characters in any language. As it relates to QMK it means using various OS schemes to send unicode codepoints instead of scancodes.
* [Unicode Documentation](unicode.html)
## Unit Testing
A framework for running automated tests against QMK. Unit testing helps us be confident that our changes do not break anything.
* [Unit Testing Documentation](unit_testing.html)
## USB
Universal Serial Bus, the most common wired interface for a keyboard.
## USB Host (or simply Host)
The USB Host is your computer, or whatever device your keyboard is plugged into.
# Couldn't find the term you're looking for?
[Open an issue](https://github.com/qmk/qmk_firmware/issues) with your question and the term in question could be added here. Better still, open a pull request with the definition. :)