keyboard/qmk-keychron-q3-colemak-dh
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Flesh out the newbs guide

Browse Source
This commit is contained in:
skullY 2018-03-06 15:22:47 -08:00
parent 08e48eb6f5
commit 6a4e08938e
2 changed files with 50 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
docs/newbs_building_firmware.md
View File

@ -9,7 +9,7 @@ If you have closed and reopened your terminal window since following the first p
Start by navigating to the `keymaps` folder for your keyboard.
{% hint style='info' %}
If you are on macOS or Windows there are commands you can use to easily open the `keymaps` folder.
If you are on macOS or Windows there are commands you can use to easily open the keymaps folder.
macOS:
@ -22,17 +22,17 @@ Windows:
## 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.
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.
## Open `keymap.c` In Your Favorite Text Editor
Inside the `keymap.c` file you'll find the structure that controls how your keyboard behaves. At the top 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 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:
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 that particular layer.
{% hint style='warning' %}
{% hint style='warn' %}
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.
{% endhint %}
@ -47,3 +47,27 @@ How to complete this step is entirely up to you. Make the one change that's been
{% hint style='info' %}
While you get a feel for how keymaps work, keep each change small. Bigger changes make it harder to debug any problems that arise.
{% endhint %}
## 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:
make <my_keyboard>:<my_keymap>
For example, if your keymap is named "xyverz" and you're building a keymap for a rev5 planck, you'll use this command:
make planck/rev5:xyverz
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:
```
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 [OK]
* File size is fine - 18392/28672
```
## Flash Your Firmware
Move on to [Flashing Firmware](newbs_flashing.md) to learn how to write your new firmware to your keyboard.

30
docs/newbs_getting_started.md
View File

@ -6,9 +6,19 @@ QMK tries to put a lot of power into your hands by making easy things easy, and
# Getting Started
Before you can build keymaps you need to setup your build environment. This only has to be done one time no matter how many keyboards you want to compile firmware for.
Before you can build keymaps you need to install some software and setup your build environment. This only has to be done one time no matter how many keyboards you want to compile firmware for.
## Download QMK Toolbox
## Download Software
### Text Editor
You'll need a program that can edit and save **plain text** files. If you are on Windows you can make due with Notepad, and on Linux you can use Gedit, both of which are simple but functional text editors. On macOS you can not use TextEdit.app, it will not save plain text files. You will need to install another program such as Sublime Text.
{% hint style='info' %}
Not sure which text editor to use? Laurence Bradford wrote [a great introduction](https://learntocodewith.me/programming/basics/text-editors/) to the subject.
{% endhint %}
### QMK Toolbox
QMK Toolbox is a Windows and macOS program that allows you to both program and debug your custom keyboard. You will want to install it so that you can easily flash your keyboard and receive the debugging messages that your keyboard will print.
@ -43,8 +53,8 @@ You will need to install git. It's extremely likely you already have it, but if
Once you have setup 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 Console window and leave it open for the remainder of this guide. Inside that window run these two commands:
* `git clone https://github.com/qmk/qmk_firmware.git`
* `cd qmk_firmware`
git clone https://github.com/qmk/qmk_firmware.git
cd qmk_firmware
{% hint style='info' %}
If you already know [how to use GitHub](getting_started_github.md) we recommend you create and clone your own fork instead. If you don't know what that means you can safely ignore this message.
@ -52,19 +62,19 @@ If you already know [how to use GitHub](getting_started_github.md) we recommend
## Setup QMK
QMK comes with a script to help you setup the rest of what you'll need. You should run it now:
QMK comes with a script to help you setup the rest of what you'll need. You should run it now by typing in this command:
* `./util/qmk_install.sh`
./util/qmk_install.sh
## Test Your Build Environment
Now that your QMK build environment is setup you can build a firmware for your keyboard. Start by trying to build the default layout for your keyboard. You should be able to do that with a command in this format:
* `make <keyboard>:default`
make <keyboard>:default
For example, to build a firmware for a Clueboard 66% use:
* `make clueboard/66:default`
make clueboard/66/rev3:default
When it is done you should have a lot of output that ends similar to this:
@ -75,3 +85,7 @@ Copying clueboard_66_rev2_default.hex to qmk_firmware folder
Checking file size of clueboard_66_rev2_default.hex [OK]
* File size is fine - 25174/28672
```
## Creating Your Layout
Now you are ready to create your own personal layout. Move on to [Building Your First Firmware](newbs_building_firmware.md) for that.