@ -13,7 +13,7 @@ The OLKB product firmwares are maintained by Jack, the Ergodox EZ by Erez, and t
This is not a tiny project. While this is the main Readme, there are many other files you might want to consult. Here are some points of interest:
This is not a tiny project. While this is the main Readme, there are many other files you might want to consult. Here are some points of interest:
* The Readme for your own keyboard: This is found under `keyboards/<your keyboards's name>/`. So for the ErgoDox EZ, it's [here](keyboard/ergodox_ez/); for the Atomic, it's [here](keyboard/atomic/) and so on.
* The Readme for your own keyboard: This is found under `keyboards/<your keyboards's name>/`. So for the ErgoDox EZ, it's [here](keyboards/ergodox_ez/); for the Atomic, it's [here](keyboards/atomic/) and so on.
* The [build guide](doc/BUILD_GUIDE.md), also mentioned in the next section. This is how you put your development environment together so you can compile the firmware.
* The [build guide](doc/BUILD_GUIDE.md), also mentioned in the next section. This is how you put your development environment together so you can compile the firmware.
* The list of possible keycodes you can use in your keymap is actually spread out in a few different places:
* The list of possible keycodes you can use in your keymap is actually spread out in a few different places:
* [tmk_core/common/keycode.h](tmk_core/common/keycode.h) - the base TMK keycodes. This is the actual source file.
* [tmk_core/common/keycode.h](tmk_core/common/keycode.h) - the base TMK keycodes. This is the actual source file.
@ -23,9 +23,9 @@ This is not a tiny project. While this is the main Readme, there are many other
## Getting started
## Getting started
* [BUILD_GUIDE.md](doc/BUILD_GUIDE.md) contains instructions to set up a build environment, build the firmware, and deploy it to a keyboard. Once your build environment has been set up, all `make` commands to actually build the firmware must be run from a folder in `keyboard/`.
* [BUILD_GUIDE.md](doc/BUILD_GUIDE.md) contains instructions to set up a build environment, build the firmware, and deploy it to a keyboard. Once your build environment has been set up, all `make` commands to actually build the firmware must be run from a folder in `keyboards/`.
* If you're looking to customize a keyboard that currently runs QMK or TMK, find your keyboard's directory under `keyboard/` and run the make commands from there.
* If you're looking to customize a keyboard that currently runs QMK or TMK, find your keyboard's directory under `keyboards/` and run the make commands from there.
* If you're looking to apply this firmware to an entirely new hardware project (a new kind of keyboard), you can create your own Quantum-based project by using `util/new_project.sh <project_name>`, which will create `/keyboard/<project_name>` with all the necessary components for a Quantum project.
* If you're looking to apply this firmware to an entirely new hardware project (a new kind of keyboard), you can create your own Quantum-based project by using `util/new_project.sh <project_name>`, which will create `/keyboards/<project_name>` with all the necessary components for a Quantum project.
### Makefile Options
### Makefile Options
@ -307,7 +307,7 @@ If you have a bunch of macros you want to refer to from your keymap, while keepi
#define EXT_PLV M(13)
#define EXT_PLV M(13)
```
```
As was done on the [Planck default keymap](/keyboard/planck/keymaps/default/keymap.c#L33-L40)
As was done on the [Planck default keymap](/keyboards/planck/keymaps/default/keymap.c#L33-L40)
#### Timer functionality
#### Timer functionality
@ -400,7 +400,7 @@ Enable the backlight from the Makefile.
Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any keyboard that allows access to the C6 port, you can hook up a simple speaker and have it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any keyboard that allows access to the C6 port, you can hook up a simple speaker and have it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
The audio code lives in [quantum/audio/audio.h](/quantum/audio/audio.h) and in the other files in the audio directory. It's enabled by default on the Planck [stock keymap](/keyboard/planck/keymaps/default/keymap.c). Here are the important bits:
The audio code lives in [quantum/audio/audio.h](/quantum/audio/audio.h) and in the other files in the audio directory. It's enabled by default on the Planck [stock keymap](/keyboards/planck/keymaps/default/keymap.c). Here are the important bits:
```
```
#include "audio.h"
#include "audio.h"
@ -475,7 +475,7 @@ AutoHotkey inserts the Text right of `Send, ` when this combination is pressed.
## RGB Under Glow Mod
## RGB Under Glow Mod
Here is a quick demo on Youtube (with NPKC KC60) (https://www.youtube.com/watch?v=VKrpPAHlisY).
Here is a quick demo on Youtube (with NPKC KC60) (https://www.youtube.com/watch?v=VKrpPAHlisY).
@ -501,11 +501,11 @@ You'll need to edit `PORTF`, `DDRF`, and `PF4` on the first three lines to the p
#define ws2812_DDRREG DDRB
#define ws2812_DDRREG DDRB
#define ws2812_pin PB3
#define ws2812_pin PB3
The firmware supports 5 different light effects, and the color (hue, saturation, brightness) can be customized in most effects. To control the underglow, you need to modify your keymap file to assign those functions to some keys/key combinations. For details, please check this keymap. `keyboard/planck/keymaps/yang/keymap.c`
The firmware supports 5 different light effects, and the color (hue, saturation, brightness) can be customized in most effects. To control the underglow, you need to modify your keymap file to assign those functions to some keys/key combinations. For details, please check this keymap. `keyboards/planck/keymaps/yang/keymap.c`
Please note the USB port can only supply a limited amount of power to the keyboard (500mA by standard, however, modern computer and most usb hubs can provide 700+mA.). According to the data of NeoPixel from Adafruit, 30 WS2812 LEDs require a 5V 1A power supply, LEDs used in this mod should not more than 20.
Please note the USB port can only supply a limited amount of power to the keyboard (500mA by standard, however, modern computer and most usb hubs can provide 700+mA.). According to the data of NeoPixel from Adafruit, 30 WS2812 LEDs require a 5V 1A power supply, LEDs used in this mod should not more than 20.
@ -40,20 +40,20 @@ If you have any problems building the firmware, you can try using a tool called
## Verify Your Installation
## Verify Your Installation
1. If you haven't already, obtain this repository ([https://github.com/jackhumbert/qmk_firmware](https://github.com/jackhumbert/qmk_firmware)). You can either download it as a zip file and extract it, or clone it using the command line tool git or the Github Desktop application.
1. If you haven't already, obtain this repository ([https://github.com/jackhumbert/qmk_firmware](https://github.com/jackhumbert/qmk_firmware)). You can either download it as a zip file and extract it, or clone it using the command line tool git or the Github Desktop application.
2. Open up a terminal or command prompt and navigate to the `qmk_firmware` folder using the `cd` command. The command prompt will typically open to your home directory. If, for example, you cloned the repository to your Documents folder, then you would type `cd Documents/qmk_firmware`. If you extracted the file from a zip, then it may be named `qmk_firmware-master` instead.
2. Open up a terminal or command prompt and navigate to the `qmk_firmware` folder using the `cd` command. The command prompt will typically open to your home directory. If, for example, you cloned the repository to your Documents folder, then you would type `cd Documents/qmk_firmware`. If you extracted the file from a zip, then it may be named `qmk_firmware-master` instead.
3. To confirm that you're in the correct location, you can display the contents of your current folder using the `dir` command on Windows, or the `ls` command on Linux or Mac. You should see several files, including `README.md` and a `quantum` folder. From here, you need to navigate to the appropriate folder under `keyboard/`. For example, if you're building for a Planck, run `cd keyboard/planck`.
3. To confirm that you're in the correct location, you can display the contents of your current folder using the `dir` command on Windows, or the `ls` command on Linux or Mac. You should see several files, including `README.md` and a `quantum` folder. From here, you need to navigate to the appropriate folder under `keyboards/`. For example, if you're building for a Planck, run `cd keyboards/planck`.
4. Once you're in the correct keyboard-specific folder, run the `make` command. This should output a lot of information about the build process. More information about the `make` command can be found below.
4. Once you're in the correct keyboard-specific folder, run the `make` command. This should output a lot of information about the build process. More information about the `make` command can be found below.
## Customizing, Building, and Deploying Your Firmware
## Customizing, Building, and Deploying Your Firmware
### The Make command
### The Make command
The `make` command is how you compile the firmware into a .hex file, which can be loaded by a dfu programmer (like dfu-progammer via `make dfu`) or the [Teensy loader](https://www.pjrc.com/teensy/loader.html) (only used with Teensys). You can run `make` from the root (`/`), your keyboard folder (`/keyboard/<keyboard>/`), or your keymap folder (`/keyboard/<keyboard>/keymaps/<keymap>/`) if you have a `Makefile` there (see the example [here](/doc/keymap_makefile_example.mk)).
The `make` command is how you compile the firmware into a .hex file, which can be loaded by a dfu programmer (like dfu-progammer via `make dfu`) or the [Teensy loader](https://www.pjrc.com/teensy/loader.html) (only used with Teensys). You can run `make` from the root (`/`), your keyboard folder (`/keyboards/<keyboard>/`), or your keymap folder (`/keyboards/<keyboard>/keymaps/<keymap>/`) if you have a `Makefile` there (see the example [here](/doc/keymap_makefile_example.mk)).
By default, this will generate a `<keyboard>_<keymap>.hex` file in whichever folder you run `make` from. These files are ignored by git, so don't worry about deleting them when committing/creating pull requests. Your .hex file will also be copied into your keymap folder as `compiled.hex`, which isn't ignored by git - this is included in case first-time users are having trouble compiling, and just want to flash a layout via `make dfu-no-build` or using the Teensy loader.
By default, this will generate a `<keyboard>_<keymap>.hex` file in whichever folder you run `make` from. These files are ignored by git, so don't worry about deleting them when committing/creating pull requests. Your .hex file will also be copied into your keymap folder as `compiled.hex`, which isn't ignored by git - this is included in case first-time users are having trouble compiling, and just want to flash a layout via `make dfu-no-build` or using the Teensy loader.
* The "root" (`/`) folder is the qmk_firmware folder, in which are `doc`, `keyboard`, `quantum`, etc.
* The "root" (`/`) folder is the qmk_firmware folder, in which are `doc`, `keyboard`, `quantum`, etc.
* The "keyboard" folder is any keyboard project's folder, like `/keyboard/planck`.
* The "keyboard" folder is any keyboard project's folder, like `/keyboards/planck`.
* The "keymap" folder is any keymap's folder, like `/keyboard/planck/keymaps/default`.
* The "keymap" folder is any keymap's folder, like `/keyboards/planck/keymaps/default`.
Below is a list of the useful `make` commands in QMK:
Below is a list of the useful `make` commands in QMK:
@ -80,8 +80,8 @@ Other, less useful functionality:
There are 3 different `make` and `Makefile` locations:
There are 3 different `make` and `Makefile` locations:
The root contains the code used to automatically figure out which keymap or keymaps to compile based on your current directory and commandline arguments. It's considered stable, and shouldn't be modified. The keyboard one will contain the MCU set-up and default settings for your keyboard, and shouldn't be modified unless you are the producer of that keyboard. The keymap Makefile can be modified by users, and is optional. It is included automatically if it exists. You can see an example [here](/doc/keymap_makefile_example.mk) - the last few lines are the most important. The settings you set here will override any defaults set in the keyboard Makefile. **It is required if you want to run `make` in the keymap folder.**
The root contains the code used to automatically figure out which keymap or keymaps to compile based on your current directory and commandline arguments. It's considered stable, and shouldn't be modified. The keyboard one will contain the MCU set-up and default settings for your keyboard, and shouldn't be modified unless you are the producer of that keyboard. The keymap Makefile can be modified by users, and is optional. It is included automatically if it exists. You can see an example [here](/doc/keymap_makefile_example.mk) - the last few lines are the most important. The settings you set here will override any defaults set in the keyboard Makefile. **It is required if you want to run `make` in the keymap folder.**
@ -89,8 +89,8 @@ The root contains the code used to automatically figure out which keymap or keym
The keyboard `config.h` is included only if the keymap one doesn't exist. The format to use for your custom one [is here](/doc/keymap_config_h_example.h). If you want to override a setting from the parent `config.h` file, you need to do this:
The keyboard `config.h` is included only if the keymap one doesn't exist. The format to use for your custom one [is here](/doc/keymap_config_h_example.h). If you want to override a setting from the parent `config.h` file, you need to do this:
@ -185,13 +185,13 @@ From here, you should have a working keyboard with the correct firmware. Before
To start out, download [the firmware](https://github.com/jackhumbert/qmk_firmware/) - we'll be using my (Jack's) fork of TMK called QMK/Quantum. We'll be doing a lot from the Terminal/command prompt, so get that open, along with a decent text editor like [Sublime Text](http://www.sublimetext.com/).
To start out, download [the firmware](https://github.com/jackhumbert/qmk_firmware/) - we'll be using my (Jack's) fork of TMK called QMK/Quantum. We'll be doing a lot from the Terminal/command prompt, so get that open, along with a decent text editor like [Sublime Text](http://www.sublimetext.com/).
The first thing we're going to do is create a new project using the script in the root directory of the firmware. In your terminal, run this command with `<project_name>` replaced by the name of your project - it'll need to be different from any other project in the `keyboard/` folder:
The first thing we're going to do is create a new project using the script in the root directory of the firmware. In your terminal, run this command with `<project_name>` replaced by the name of your project - it'll need to be different from any other project in the `keyboards/` folder:
util/new_project.sh <project_name>
util/new_project.sh <project_name>
You'll want to navigate to the `keyboard/<project_name>/` folder by typing, like the print-out from the script specifies:
You'll want to navigate to the `keyboards/<project_name>/` folder by typing, like the print-out from the script specifies:
cd keyboard/<project_name>
cd keyboards/<project_name>
#### config.h
#### config.h
@ -286,7 +286,7 @@ After you've written out your entire keymap, you're ready to get the firmware co
Once everything is installed, running `make` in the terminal should get you some output, and eventually a `<project_name>.hex` file in that folder. If you're having trouble with this step, see the end of the guide for the trouble-shooting section.
Once everything is installed, running `make` in the terminal should get you some output, and eventually a `<project_name>.hex` file in that folder. If you're having trouble with this step, see the end of the guide for the trouble-shooting section.
Once you have your `<project_name>.hex` file, open up the Teensy loader application, and click the file icon. From here, navigate to your `QMK/keyboard/<project_name>/` folder, and select the `<project_name>.hex` file. Plug in your keyboard and press the button on the Teensy - you should see the LED on the device turn off once you do. The Teensy Loader app will change a little, and the buttons should be clickable - click the download button (down arrow), and then the reset button (right arrow), and your keyboard should be ready to go!
Once you have your `<project_name>.hex` file, open up the Teensy loader application, and click the file icon. From here, navigate to your `QMK/keyboards/<project_name>/` folder, and select the `<project_name>.hex` file. Plug in your keyboard and press the button on the Teensy - you should see the LED on the device turn off once you do. The Teensy Loader app will change a little, and the buttons should be clickable - click the download button (down arrow), and then the reset button (right arrow), and your keyboard should be ready to go!
@ -12,7 +12,7 @@ Other than having Vagrant and Virtualbox installed and possibly a restart of you
Build Firmware and Program Controller
Build Firmware and Program Controller
-------------------------------------
-------------------------------------
See [/doc/BUIDE_GUIDE.md](/doc/BUILD_GUIDE.md), or the README in the particular keyboard/* folder.
See [/doc/BUIDE_GUIDE.md](/doc/BUILD_GUIDE.md), or the README in the particular keyboards/* folder.
Change your keymap
Change your keymap
------------------
------------------
@ -20,7 +20,7 @@ See [/doc/keymap.md](/doc/keymap.md).
## Flashing the firmware
## Flashing the firmware
The "easy" way to flash the firmware is using a tool from your host OS like the Teensy programming app. [ErgoDox EZ](/keyboard/ergodox_ez/readme.md) gives a great example.
The "easy" way to flash the firmware is using a tool from your host OS like the Teensy programming app. [ErgoDox EZ](/keyboards/ergodox_ez/readme.md) gives a great example.
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.
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.
@ -7,7 +7,7 @@ For the full Quantum feature list, see [the parent README.md](/README.md).
## Building
## Building
Download or clone the whole firmware and navigate to the keyboard/arrow_pad folder. Once your dev env is setup, you'll be able to type `make` to generate your .hex - you can then use the Teensy Loader to program your .hex file.
Download or clone the whole firmware and navigate to the keyboards/arrow_pad folder. Once your dev env is setup, you'll be able to type `make` to generate your .hex - you can then use the Teensy Loader to program your .hex file.
Depending on which keymap you would like to use, you will have to compile slightly differently.
Depending on which keymap you would like to use, you will have to compile slightly differently.
@ -8,7 +8,7 @@ For the full Quantum feature list, see [the parent README.md](/README.md).
## Building
## Building
Download or clone the whole firmware and navigate to the keyboard/atomic folder. Once your dev env is setup, you'll be able to type `make` to generate your .hex - you can then use `make dfu` to program your PCB once you hit the reset button.
Download or clone the whole firmware and navigate to the keyboards/atomic folder. Once your dev env is setup, you'll be able to type `make` to generate your .hex - you can then use `make dfu` to program your PCB once you hit the reset button.
Depending on which keymap you would like to use, you will have to compile slightly differently.
Depending on which keymap you would like to use, you will have to compile slightly differently.
@ -169,7 +169,7 @@ This requires [some hardware changes](https://www.reddit.com/r/MechanicalKeyboar
## Building
## Building
Download or clone the whole firmware and navigate to the keyboard/planck folder. Once your dev env is setup, you'll be able to type `make` to generate your .hex - you can then use `make dfu` to program your PCB once you hit the reset button.
Download or clone the whole firmware and navigate to the keyboards/planck folder. Once your dev env is setup, you'll be able to type `make` to generate your .hex - you can then use `make dfu` to program your PCB once you hit the reset button.
Depending on which keymap you would like to use, you will have to compile slightly differently.
Depending on which keymap you would like to use, you will have to compile slightly differently.
@ -7,7 +7,7 @@ For the full Quantum feature list, see [the parent README.md](/README.md).
## Building
## Building
Download or clone the whole firmware and navigate to the keyboard/Bantam44 folder. Once your dev env is setup, you'll be able to type `make` to generate your .hex - you can then use the Teensy Loader to program your .hex file.
Download or clone the whole firmware and navigate to the keyboards/Bantam44 folder. Once your dev env is setup, you'll be able to type `make` to generate your .hex - you can then use the Teensy Loader to program your .hex file.
Depending on which keymap you would like to use, you will have to compile slightly differently.
Depending on which keymap you would like to use, you will have to compile slightly differently.
Jack Humbert
9 years ago
committed by
GitHub