_/qmk_firmware
1
0
Fork 0
Code Releases Activity

Rework the newbs guide around the qmk cli

Browse source
This commit is contained in:
skullY 2020-02-20 15:50:50 -08:00 committed by skullydazed
parent 1b7fa46f8e
commit a701c15d87
17 changed files with 143 additions and 354 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
docs/README.md
View file

@ -9,7 +9,7 @@
## What is QMK Firmware?
QMK (*Quantum Mechanical Keyboard*) is an open source community centered around developing computer input devices. Early on the community was keyboard focused, but has now grown to include mice and MIDI devices as well. The community maintains [QMK Firmware](https://github.com/qmk/qmk_firmware), [QMK Configurator](https://config.qmk.fm), [QMK Toolbox](https://github.com/qmk/qmk_toolbox), [qmk.fm](https://qmk.fm), and this documentation.
QMK (*Quantum Mechanical Keyboard*) is an open source community centered around developing computer input devices. The community encompasses all sorts of input devices, such as keyboards, mice, and MIDI devices. A core group of collaborators maintains [QMK Firmware](https://github.com/qmk/qmk_firmware), [QMK Configurator](https://config.qmk.fm), [QMK Toolbox](https://github.com/qmk/qmk_toolbox), [qmk.fm](https://qmk.fm), and this documentation with the help of community members like you.
## Get Started
@ -18,9 +18,24 @@ Totally new to QMK? There are two ways to get started:
* Basic: [QMK Configurator](https://config.qmk.fm)
* Just select your keyboard from the dropdown and program your keyboard.
* We have an [introductory video](https://www.youtube.com/watch?v=-imgglzDMdY) you can watch.
* There is also an overview [document you can read](newbs_building_firmware_configurator.md).
* Advanced: [Use The Source](newbs.md)
* More powerful, but harder to use
## Make It Yours
QMK has lots of [features](features.md) to explore, and a good deal of reference documentation to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).
## Need help?
Check out the [support page](getting_started_getting_help.md) to see how you can get help using QMK.
## Give Back
There are a lot of ways you can contribute to the QMK Community. The easiest way to get started is to use it and spread the word to your friends.
* Help people out on our forums and chat rooms:
* [/r/olkb](https://www.reddit.com/r/olkb/)
* [Discord Server](https://discord.gg/Uq7gcHh)
* Contribute to our documentation by clicking "Edit This Page" at the bottom
* [Translate our documentation into your language](translating.md)

5
docs/_summary.md
View file

@ -20,7 +20,7 @@
* [Driver Installation with Zadig](driver_installation_zadig.md)
* Using QMK
* [Support](support.md)
* [Support](getting_started_getting_help.md)
* Guides
* [ARM Debugging Guide](arm_debugging.md)
* [Best Git Practices](newbs_git_best_practices.md)
@ -37,7 +37,8 @@
* [Vagrant Guide](getting_started_vagrant.md)
* QMK Features
* [Keycodes](keycodes.md)
* Keycodes
* [Full List](keycodes.md)
* [Basic Keycodes](keycodes_basic.md)
* [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
* [Quantum Keycodes](quantum_keycodes.md)

2
docs/de/_summary.md
View file

@ -108,7 +108,7 @@
* Andere Themen
* [Eclipse mit QMK](de/other_eclipse.md)
* [VSCode mit QMK](de/other_vscode.md)
* [Support](de/support.md)
* [Support](de/getting_started_getting_help.md)
* [Übersetzungen](de/translating.md)
* QMK Internals (In Progress)

2
docs/es/_summary.md
View file

@ -108,7 +108,7 @@
* Otros temas
* [Usando Eclipse con QMK](es/other_eclipse.md)
* [Usando VSCode con QMK](es/other_vscode.md)
* [Soporte](es/support.md)
* [Soporte](es/getting_started_getting_help.md)
* [Cómo añadir traducciones](es/translating.md)
* QMK Internals (En progreso)

38
docs/faq_general.md
View file

@ -4,6 +4,44 @@
[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).
## I don't know where to start!
If this is the case, then you should start with our [Newbs Guide](newbs.md). There is a lot of great info there, and that should cover everything you need to get started.
If that's an issue, hop onto the [QMK Configurator](https://config.qmk.fm), as that will handle a majority of what you need there.
## How can I flash the firmware I built?
First, head to the [Compiling/Flashing FAQ Page](faq_build.md). There is a good deal of info there, and you'll find a bunch of solutions to common issues there.
## What if I have an issue that isn't covered here?
Okay, that's fine. Then please check the [open issues in our GitHub](https://github.com/qmk/qmk_firmware/issues) to see if somebody is experiencing the same thing (make sure it's not just similar, but actually the same).
If you can't find anything, then please open a [new issue](https://github.com/qmk/qmk_firmware/issues/new)!
## What if I found a bug?
Then please open an [issue](https://github.com/qmk/qmk_firmware/issues/new), and if you know how to fix it, open up a Pull Request on GitHub with the fix.
## But `git` and `GitHub` are intimidating!
Don't worry, we have some pretty nice [Guidelines](newbs_git_best_practices.md) on how to start using `git` and GitHub to make things easier to develop.
Additionally, you can find additional `git` and GitHub related links [here](newbs_learn_more_resources.md).
## I have a Keyboard that I want to add support for
Awesome! Open up a Pull Request for it. We'll review the code, and merge it!
### What if I want to do brand it with `QMK`?
That's amazing! We would love to assist you with that!
In fact, we have a [whole page](https://qmk.fm/powered/) dedicated to adding QMK Branding to your page and keyboard. This covers pretty much everything you need (knowledge and images) to officially support QMK.
If you have any questions about this, open an issue or head to [Discord](https://discord.gg/Uq7gcHh).
## 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](https://github.com/jackhumbert)'s 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.

2
docs/fr-fr/_summary.md
View file

@ -112,7 +112,7 @@
* Autres sujets
* [Utiliser Eclipse avec QMK](fr-fr/other_eclipse.md)
* [Utiliser VSCode avec QMK](fr-fr/other_vscode.md)
* [Support](fr-fr/support.md)
* [Support](fr-fr/getting_started_getting_help.md)
* [Comment ajouter des traductions](fr-fr/translating.md)
* À l’intérieur de QMK (En cours de documentation)

4
docs/getting_started_getting_help.md
View file

@ -2,9 +2,11 @@
There are a lot of resources for getting help with QMK.
Please read our [Code of Conduct](https://qmk.fm/coc/) before participating in any of our community spaces.
## Realtime Chat
You can find QMK developers and users on our main [Discord server](https://discord.gg/Uq7gcHh). There are specific channels in the server for chatting about the firmware, Toolbox, hardware, and configurator.
If you need help with something, the best place to get quick support is going to be on our [Discord Server](https://discord.gg/Uq7gcHh). There is usually somebody online, and there are a bunch of very helpful people there.
## OLKB Subreddit

2
docs/he-il/_summary.md
View file

@ -124,7 +124,7 @@
* נושאים נוספים
* [שימוש ב - Eclipse עם QMK](he-il/other_eclipse.md)
* [שימוש ב - VSCode עם QMK](he-il/other_vscode.md)
* [תמיכה](he-il/support.md)
* [תמיכה](he-il/getting_started_getting_help.md)
* [כיצד להוסיף תרגום](he-il/translating.md)
* QMK מבפנים (בתהליך)

2
docs/ja/_summary.md
View file

@ -117,7 +117,7 @@
* 他の話題
* [Eclipse で QMK を使用](ja/other_eclipse.md)
* [VSCode で QMK を使用](ja/other_vscode.md)
* [サポート](ja/support.md)
* [サポート](ja/getting_started_getting_help.md)
* [翻訳を追加する方法](ja/translating.md)
* QMK の内部詳細(作成中)

21
docs/newbs.md
View file

@ -2,19 +2,22 @@
QMK is a powerful Open Source firmware for your mechanical keyboard. You can use QMK to customize your keyboard in ways both simple and powerful. People of all skill levels, from complete newbie to master programmer, have successfully used QMK to customize their keyboard. This guide will help you do the same, no matter your skill level.
Not sure if your keyboard can run QMK? If it's a mechanical keyboard you built yourself chances are good it can. We support a [large number of hobbyist boards](http://qmk.fm/keyboards/), so even if your current keyboard can't run QMK you shouldn't have trouble finding one to suit your needs.
Not sure if your keyboard can run QMK? If it's a mechanical keyboard you built yourself chances are good it can. We support a [large number of hobbyist boards](http://qmk.fm/keyboards/). If your current keyboard can't run QMK there are a lot of choices out there for boards that do.
## Is This Guide For Me?
This guide is suitable for everyone who wants to build a keyboard firmware using the source code. If you are already a programmer you will find the process very familiar and easier to follow. If the thought of programming intimidates you please [take a look at our online GUI](newbs_building_firmware_configurator.md) instead.
## Overview
There are 7 main sections to this guide:
There are 6 main sections to this guide:
* [Getting Started](newbs_getting_started.md)
* [Building Your First Firmware using the command line](newbs_building_firmware.md)
* [Building Your First Firmware using the online GUI](newbs_building_firmware_configurator.md)
* [Flashing Firmware](newbs_flashing.md)
* [Testing and Debugging](newbs_testing_debugging.md)
* [Best Git Practices](newbs_git_best_practices.md)
* [Learn More with these Resources](newbs_learn_more_resources.md)
1. [Getting Started](newbs_getting_started.md)
2. [Building Your First Firmware](newbs_building_firmware.md)
3. [Flashing Firmware](newbs_flashing.md)
4. [Testing and Debugging](newbs_testing_debugging.md)
5. [Best Git Practices](newbs_git_best_practices.md)
6. [Learn More with these Resources](newbs_learn_more_resources.md)
This guide is focused on helping someone who has never compiled software before. It makes choices and recommendations based on that viewpoint. There are alternative methods for many of these procedures, and we support most of those alternatives. If you have any doubt about how to accomplish a task you can [ask us for guidance](getting_started_getting_help.md).

46
docs/newbs_building_firmware.md
View file

@ -2,47 +2,29 @@
Now that you have setup your build environment you are ready to start building custom firmware. For this section of the guide we will bounce between 3 programs- your file manager, your text editor, and your terminal window. Keep all 3 open until you are done and happy with your keyboard firmware.
If you have closed and reopened your terminal window since following the first part of the guide, don't forget to `cd qmk_firmware` so that your terminal is in the correct directory.
## Create a New Keymap
## Navigate To Your Keymaps Folder
To create your own keymap you'll want to create a copy of the `default` keymap. If you configured your build environment in the last step you can do that easily with the QMK CLI:
Start by navigating to the `keymaps` folder for your keyboard.
qmk new-keymap
If you are on macOS or Windows there are commands you can use to easily open the keymaps folder.
If you did not configure your environment, or you have multiple keyboards, you can specify a keyboard name:
### macOS:
qmk new-keymap -kb <keyboard_name>
``` open keyboards/<keyboard_folder>/keymaps ```
Look at the output from that command, you should see something like this:
### Windows:
Ψ <github_username> keymap directory created in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/<github_username>
``` start .\\keyboards\\<keyboard_folder>\\keymaps ```
## Create a Copy Of The `default` Keymap
Once you have the `keymaps` folder open you will want to create a copy of the `default` folder. We highly recommend you name your folder the same as your GitHub username, but you can use any name you want as long as it contains only lower case letters, numbers, and the underscore character.
To automate the process, you also have the option to run the `new_keymap.sh` script.
Navigate to the `qmk_firmware/util` directory and type the following:
```
./new_keymap.sh <keyboard path> <username>
```
For example, for a user named John, trying to make a new keymap for the 1up60hse, they would type in
```
./new_keymap.sh 1upkeyboards/1up60hse john
```
This is the location of your new `keymap.c` file.
## Open `keymap.c` In Your Favorite Text Editor
Open up your `keymap.c`. Inside this file you'll find the structure that controls how your keyboard behaves. At the top of `keymap.c` there may be some defines and enums that make the keymap easier to read. Farther down you'll find a line that looks like this:
Open your `keymap.c` file in your text editor. Inside this file you'll find the structure that controls how your keyboard behaves. At the top of `keymap.c` there may be some defines and enums that make the keymap easier to read. Farther down you'll find a line that looks like this:
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
This line indicates the start of the list of Layers. Below that you'll find lines containing either `LAYOUT` or `KEYMAP`, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a particular layer.
This line indicates where the list of Layers begins. Below that you'll find lines containing `LAYOUT`, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a particular layer.
!> When editing your keymap file be careful not to add or remove any commas. If you do you will prevent your firmware from compiling and it may not be easy to figure out where the extra, or missing, comma is.
@ -58,13 +40,13 @@ How to complete this step is entirely up to you. Make the one change that's been
## Build Your Firmware
When your changes to the keymap are complete you will need to build the firmware. To do so go back to your terminal window and run the build command:
When your changes to the keymap are complete you will need to build the firmware. To do so go back to your terminal window and run the compile command:
make <my_keyboard>:<my_keymap>
qmk compile
For example, if your keymap is named "xyverz" and you're building a keymap for a rev5 planck, you'll use this command:
If you did not configure your environment, or you have multiple keyboards, you can specify a keyboard and/or keymap:
make planck/rev5:xyverz
qmk compile -kb <keyboard> -km <keymap>
While this compiles you will have a lot of output going to the screen informing you of what files are being compiled. It should end with output that looks similar to this:

275
docs/newbs_flashing.md
View file

@ -86,13 +86,13 @@ Click the `Flash` button in QMK Toolbox. You will see output similar to the foll
## Flash your Keyboard from the Command Line
This has been made pretty simple compared to what it used to be. When you are ready to compile and flash your firmware, open up your terminal window and run the build command:
This has been made pretty simple compared to what it used to be. When you are ready to compile and flash your firmware, open up your terminal window and run the flash command:
make <my_keyboard>:<my_keymap>:flash
qmk flash
For example, if your keymap is named "xyverz" and you're building a keymap for a rev5 planck, you'll use this command:
If you have not configured your keyboard/keymap name, or you have multiple keyboards, you can specify the keyboard and keymap:
make planck/rev5:xyverz:flash
qmk flash -kb <my_keyboard> -km <my_keymap>
This will check the keyboard's configuration, and then attempt to flash it based on the specified bootloader. This means that you don't need to know which bootloader that your keyboard uses. Just run the command, and let the command do the heavy lifting.
@ -106,273 +106,20 @@ There are five main bootloaders that are used. Pro Micro and clones use Caterina
You can find more information about the bootloaders in the [Flashing Instructions and Bootloader Information](flashing.md) page.
If you know what bootloader that you're using, then when compiling the firmware, you can actually add some extra text to the `make` command to automate the flashing process.
If you know what bootloader that you're using you can specify that in your flash command:
### DFU
qmk flash -bl <bootloader>
For the DFU bootloader, when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
Run this command to get a list of valid bootloaders:
make <my_keyboard>:<my_keymap>:dfu
qmk flash --bootloaders
For example, if your keymap is named "xyverz" and you're building a keymap for a rev5 planck, you'll use this command:
### More information
make planck/rev5:xyverz:dfu
Once it finishes compiling, it should output the following:
```
Linking: .build/planck_rev5_xyverz.elf [OK]
Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK]
Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK]
Checking file size of planck_rev5_xyverz.hex
* File size is fine - 18574/28672
```
After it gets to this point, the build script will look for the DFU bootloader every 5 seconds. It will repeat the following until the device is found or you cancel it.
dfu-programmer: no device present.
Error: Bootloader not found. Trying again in 5s.
Once it does this, you'll want to reset the controller. It should then show output similar to this:
```
*** Attempting to flash, please don't remove device
>>> dfu-programmer atmega32u4 erase --force
Erasing flash... Success
Checking memory from 0x0 to 0x6FFF... Empty.
>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
Checking memory from 0x0 to 0x55FF... Empty.
0% 100% Programming 0x5600 bytes...
[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
0% 100% Reading 0x7000 bytes...
[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
Validating... Success
0x5600 bytes written into 0x7000 bytes memory (76.79%).
>>> dfu-programmer atmega32u4 reset
```
?> If you have any issues with this - such as `dfu-programmer: no device present` - please see the [Frequently Asked Build Questions](faq_build.md).
#### DFU commands
There are a number of DFU commands that you can use to flash firmware to a DFU device:
* `:dfu` - This is the normal option and waits until a DFU device is available, and then flashes the firmware. This will check every 5 seconds, to see if a DFU device has appeared.
* `:dfu-ee` - This flashes an `eep` file instead of the normal hex. This is uncommon.
* `:dfu-split-left` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Left Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
* `:dfu-split-right` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Right Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
### Caterina
For Arduino boards and their clones (such as the SparkFun ProMicro), when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
make <my_keyboard>:<my_keymap>:avrdude
For example, if your keymap is named "xyverz" and you're building a keymap for a rev2 Lets Split, you'll use this command:
make lets_split/rev2:xyverz:avrdude
Once the firmware finishes compiling, it will output something like this:
```
Linking: .build/lets_split_rev2_xyverz.elf [OK]
Creating load file for flashing: .build/lets_split_rev2_xyverz.hex [OK]
Checking file size of lets_split_rev2_xyverz.hex [OK]
* File size is fine - 27938/28672
Detecting USB port, reset your controller now..............
```
At this point, reset the board and then the script will detect the bootloader and then flash the board. The output should look something like this:
```
Detected controller on USB port at /dev/ttyS15
Connecting to programmer: .
Found programmer: Id = "CATERIN"; type = S
Software Version = 1.0; No Hardware Version given.
Programmer supports auto addr increment.
Programmer supports buffered memory access with buffersize=128 bytes.
Programmer supports the following devices:
Device code: 0x44
avrdude.exe: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.00s
avrdude.exe: Device signature = 0x1e9587 (probably m32u4)
avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed
To disable this feature, specify the -D option.
avrdude.exe: erasing chip
avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex"
avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
avrdude.exe: writing flash (27938 bytes):
Writing | ################################################## | 100% 2.40s
avrdude.exe: 27938 bytes of flash written
avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex:
avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex:
avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes
avrdude.exe: reading on-chip flash data:
Reading | ################################################## | 100% 0.43s
avrdude.exe: verifying ...
avrdude.exe: 27938 bytes of flash verified
avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
avrdude.exe done. Thank you.
```
If you have any issues with this, you may need to this:
sudo make <my_keyboard>:<my_keymap>:avrdude
#### Caterina commands
There are a number of DFU commands that you can use to flash firmware to a DFU device:
* `:avrdude` - This is the normal option which waits until a Caterina device is available (by detecting a new COM port), and then flashes the firmware.
* `:avrdude-loop` - This runs the same command as `:avrdude`, but after each device is flashed, it will attempt to flash again. This is useful for bulk flashing. _This requires you to manually escape the loop by hitting Control+C._
* `:avrdude-split-left` - This flashes the normal firmware, just like the default option (`:avrdude`). However, this also flashes the "Left Side" EEPROM file for split keyboards. _This is ideal for Pro Micro based split keyboards._
* `:avrdude-split-right` - This flashes the normal firmware, just like the default option (`:avrdude`). However, this also flashes the "Right Side" EEPROM file for split keyboards. _This is ideal for Pro Micro based split keyboards._
### HalfKay
For the PJRC devices (Teensy's), when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
make <my_keyboard>:<my_keymap>:teensy
For example, if your keymap is named "xyverz" and you're building a keymap for an Ergodox or Ergodox EZ, you'll use this command:
make ergodox_ez:xyverz:teensy
Once the firmware finishes compiling, it will output something like this:
```
Linking: .build/ergodox_ez_xyverz.elf [OK]
Creating load file for flashing: .build/ergodox_ez_xyverz.hex [OK]
Checking file size of ergodox_ez_xyverz.hex [OK]
* File size is fine - 25584/32256
Teensy Loader, Command Line, Version 2.1
Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage
Waiting for Teensy device...
(hint: press the reset button)
```
At this point, reset your board. Once you've done that, you'll see output like this:
```
Found HalfKay Bootloader
Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage
Programming............................................................................................................................................................................
...................................................
Booting
```
### STM32 (ARM)
For a majority of ARM boards (including the Proton C, Planck Rev 6, and Preonic Rev 3), when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
make <my_keyboard>:<my_keymap>:dfu-util
For example, if your keymap is named "xyverz" and you're building a keymap for the Planck Revision 6 keyboard, you'll use this command and then reboot the keyboard to the bootloader (before it finishes compiling):
make planck/rev6:xyverz:dfu-util
Once the firmware finishes compiling, it will output something like this:
```
Linking: .build/planck_rev6_xyverz.elf [OK]
Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK]
Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK]
Size after:
text data bss dec hex filename
0 41820 0 41820 a35c .build/planck_rev6_xyverz.hex
Copying planck_rev6_xyverz.bin to qmk_firmware folder [OK]
dfu-util 0.9
Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
Invalid DFU suffix signature
A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 011a
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuERROR, status = 10
dfuERROR, clearing status
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 011a
Device returned transfer size 2048
DfuSe interface name: "Internal Flash "
Downloading to address = 0x08000000, size = 41824
Download [=========================] 100% 41824 bytes
Download done.
File downloaded successfully
Transitioning to dfuMANIFEST state
```
#### STM32 Commands
There are a number of DFU commands that you can use to flash firmware to a STM32 device:
* `:dfu-util` - The default command for flashing to STM32 devices, and will wait until an STM32 bootloader is present. .
* `:dfu-util-split-left` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Left Side" EEPROM setting for split keyboards.
* `:dfu-util-split-right` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Right Side" EEPROM setting for split keyboards.
* `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util.
### BootloadHID
For Bootmapper Client(BMC)/bootloadHID/ATmega32A based boards, when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
make <my_keyboard>:<my_keymap>:bootloaderHID
For example, if your keymap is named "xyverz" and you're building a keymap for a jj40, you'll use this command:
make jj40:xyverz:bootloaderHID
Once the firmware finishes compiling, it will output something like this:
```
Linking: .build/jj40_default.elf [OK]
Creating load file for flashing: .build/jj40_default.hex [OK]
Copying jj40_default.hex to qmk_firmware folder [OK]
Checking file size of jj40_default.hex [OK]
* The firmware size is fine - 21920/28672 (6752 bytes free)
```
After it gets to this point, the build script will look for the DFU bootloader every 5 seconds. It will repeat the following until the device is found or you cancel it.
```
Error opening HIDBoot device: The specified device was not found
Trying again in 5s.
```
Once it does this, you'll want to reset the controller. It should then show output similar to this:
```
Page size = 128 (0x80)
Device size = 32768 (0x8000); 30720 bytes remaining
Uploading 22016 (0x5600) bytes starting at 0 (0x0)
0x05580 ... 0x05600
```
See the Flashing documentation for more information on esoteric flashing situations.
## Test It Out!
Congrats! Your custom firmware has been programmed to your keyboard!
Give it a try and make sure everything works the way you want it to. We've written [Testing and Debugging](newbs_testing_debugging.md) to round out this Newbie Guide, so head over there to learn about how to troubleshoot your custom functionality.
Give it a try and make sure everything works the way you want it to. We've written [Testing and Debugging](newbs_testing_debugging.md) to round out this Newbie Guide, so head over there to learn about validating your firmware and how to troubleshoot your custom functionality.

61
docs/newbs_getting_started.md
View file

@ -1,6 +1,6 @@
# Getting Started
Your computer keyboard has a processor inside of it, not unlike the one inside your computer. This processor runs software that is responsible for detecting button presses and sending reports about the state of the keyboard when buttons are pressed or released. QMK fills the role of that software, detecting button presses and passing that information on to the host computer. When you build your custom keymap, you are creating the equivalent of an executable program for your keyboard.
Your computer keyboard has a processor inside of it, similar to the one inside your computer. This processor runs software that is responsible for detecting button presses and informing the computer when keys are pressed. QMK fills the role of that software, detecting button presses and passing that information on to the host computer. When you build your custom keymap, you are creating an executable program for your keyboard.
QMK tries to put a lot of power into your hands by making easy things easy, and hard things possible. You don't have to know how to program to create powerful keymaps — you only have to follow a few simple syntax rules.
@ -8,8 +8,7 @@ QMK tries to put a lot of power into your hands by making easy things easy, and
Before you can build keymaps, you need to install some software and set up your build environment. This only has to be done once no matter how many keyboards you plan to compile firmware for.
If you would prefer a more graphical user interface approach, please consider using the online [QMK Configurator](https://config.qmk.fm). Please refer to [Building Your First Firmware using the online GUI](newbs_building_firmware_configurator.md).
If you would prefer a more graphical user interface approach, please consider using the online [QMK Configurator](newbs_building_firmware_configurator.md).
## Download Software
@ -40,52 +39,50 @@ We've tried to make QMK as easy to set up as possible. You only have to prepare
### Windows
You will need to install MSYS2 and Git.
You will need to install MSYS2, Git, and the QMK CLI.
* Follow the installation instructions on the [MSYS2 homepage](http://www.msys2.org).
* Close any open MSYS2 terminals and open a new MSYS2 MinGW 64-bit terminal.
* Install Git by running this command: `pacman -S git`.
After opening a new MSYS2 MinGW 64-bit terminal run these commands:
pacman -S git python3-pip
python3 -m pip install qmk
qmk setup
### macOS
You will need to install Homebrew. Follow the instructions on the [Homebrew homepage](https://brew.sh).
After Homebrew is installed, continue with _Set Up QMK_. In that step you will run a script that will install other packages.
After Homebrew is installed run these commands:
brew tap qmk/qmk
brew install qmk
qmk setup
### Linux
You will need to install Git. It's very likely that you already have it, but if not, one of the following commands should install it:
You will need to install Git and Python. It's very likely that you already have both, but if not, one of the following commands should install them:
* Debian / Ubuntu / Devuan: `apt-get install git`
* Fedora / Red Hat / CentOS: `yum install git`
* Arch: `pacman -S git`
* Debian / Ubuntu / Devuan: `apt-get install git python3 && python3 -m pip install qmk`
* Fedora / Red Hat / CentOS: `yum install git python3 && python3 -m pip install qmk`
* Arch: `pacman -S qmk`
?> Docker is also an option on all platforms. [Click here for details.](getting_started_build_tools.md#docker)
After installing QMK you can set it up with this command:
## Set Up QMK
qmk setup
Once you have set up your Linux/Unix environment, you are ready to download QMK. We will do this by using Git to "clone" the QMK repository. Open a Terminal or MSYS2 MinGW window and leave it open for the remainder of this guide. Inside that window run these two commands:
```shell
git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
cd qmk_firmware
```
?> If you already know [how to use GitHub](getting_started_github.md), we recommend that you create and clone your own fork instead. If you don't know what that means, you can safely ignore this message.
QMK comes with a script to help you set up the rest of what you'll need. You should run it now by typing in this command:
util/qmk_install.sh
?> 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.
## Test Your Build Environment
Now that your QMK build environment is set up, you can build a firmware for your keyboard. Start by trying to build the keyboard's default keymap. You should be able to do that with a command in this format:
make <keyboard>:default
qmk compile -kb <keyboard> -km default
For example, to build a firmware for a Clueboard 66% you would use:
make clueboard/66/rev3:default
qmk compile -kb clueboard/66/rev3 -km default
When it is done you should have a lot of output that ends similar to this:
@ -97,6 +94,18 @@ Checking file size of clueboard_66_rev3_default.hex
* The firmware size is fine - 26356/28672 (2316 bytes free)
```
## Configure Your Build Environment
You can configure your build environment to set the defaults and make working with QMK less tedious. Let's do that now!
Most people new to QMK only have 1 keyboard. You can set this keyboard as your default with the `qmk config` command. For example, to set your default keyboard to `clueboard/66/rev4`:
qmk config user.keyboard=clueboard/66/rev4
You can also set your default keymap name. Most people use their github username here, and we recommend that you do too.
qmk config user.keymap=<github_username>
# Creating Your Keymap
You are now ready to create your own personal keymap! Move on to [Building Your First Firmware](newbs_building_firmware.md) for that.

10
docs/newbs_testing_debugging.md
View file

@ -4,15 +4,7 @@ Once you've flashed your keyboard with a custom firmware you're ready to test it
## Testing
Testing your keyboard is usually pretty straightforward. Press every single key and make sure it sends the keys you expect. There are even programs that will help you make sure that no key is missed.
Note: These programs are not provided by or endorsed by QMK.
* [QMK Configurator](https://config.qmk.fm/#/test/) (Web Based)
* [Switch Hitter](https://web.archive.org/web/20190413233743/https://elitekeyboards.com/switchhitter.php) (Windows Only)
* [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (Mac Only)
* [Keyboard Tester](http://www.keyboardtester.com) (Web Based)
* [Keyboard Checker](http://keyboardchecker.com) (Web Based)
Testing your keyboard is usually pretty straightforward. Press every single key and make sure it sends the keys you expect. You can use [QMK Configurator](https://config.qmk.fm/#/test/)'s test mode to check your keyboard, even if it doesn't run QMK.
## Debugging

2
docs/pt-br/_summary.md
View file

@ -108,7 +108,7 @@
* Other Topics
* [Using Eclipse with QMK](pt-br/other_eclipse.md)
* [Using VSCode with QMK](pt-br/other_vscode.md)
* [Support](pt-br/support.md)
* [Support](pt-br/getting_started_getting_help.md)
* [How to add translations](pt-br/translating.md)
* QMK Internals (In Progress)

2
docs/ru-ru/_summary.md
View file

@ -110,7 +110,7 @@
* Other Topics
* [Using Eclipse with QMK](ru-ru/other_eclipse.md)
* [Using VSCode with QMK](ru-ru/other_vscode.md)
* [Support](ru-ru/support.md)
* [Support](ru-ru/getting_started_getting_help.md)
* [Translating the QMK Docs](ru-ru/translating.md)
* QMK Internals (In Progress)

2
docs/zh-cn/_summary.md
View file

@ -117,7 +117,7 @@
* 其他话题
* [使用Eclipse开发QMK](zh-cn/other_eclipse.md)
* [使用VSCode开发QMK](zh-cn/other_vscode.md)
* [支持](zh-cn/support.md)
* [支持](zh-cn/getting_started_getting_help.md)
* [翻译QMK文档](zh-cn/translating.md)
* QMK 内构 (正在编写)