diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_summary.md | 6 | ||||
| -rw-r--r-- | docs/adding_a_keyboard_to_qmk.md | 35 | ||||
| -rw-r--r-- | docs/isp_flashing_guide.md | 106 | ||||
| -rw-r--r-- | docs/key_functions.md | 4 | ||||
| -rw-r--r-- | docs/memory_write_error,_use_debug_for_more_info.md | 2 | ||||
| -rw-r--r-- | docs/modding_your_keyboard.md | 2 | ||||
| -rw-r--r-- | docs/porting_your_keyboard_to_qmk.md | 6 |
7 files changed, 157 insertions, 4 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 420003996f..c5e29cb520 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -3,6 +3,7 @@ * [Introduction](home.md) * [QMK Overview](qmk_overview.md) * [Build Environment Setup](build_environment_setup.md) +* [Make instructions](make_instructions.md) ### Making a keymap * [Keymap overview](keymap.md) @@ -19,10 +20,13 @@ * [FAQ: Compiling QMK](faq_build.md) ### For hardware makers and modders -* [Modding your keyboard](modding_your_keyboard.md) +* [Adding a keyboard to QMK](adding_a_keyboard_to_qmk.md) * [Porting your keyboard to QMK](porting_your_keyboard_to_qmk.md) +* [Modding your keyboard](modding_your_keyboard.md) * [Adding features to QMK](adding_features_to_qmk.md) +* [ISP flashing guide](isp_flashing_guide.md) ### Other topics * [General FAQ](faq.md) * [Differences from TMK](differences_from_tmk.md) +* [Using Eclipse with QMK](eclipse.md) diff --git a/docs/adding_a_keyboard_to_qmk.md b/docs/adding_a_keyboard_to_qmk.md new file mode 100644 index 0000000000..51c4c44109 --- /dev/null +++ b/docs/adding_a_keyboard_to_qmk.md @@ -0,0 +1,35 @@ +# Adding your keyboard to QMK + +We welcome all keyboard projects into QMK, but ask that you try to stick to a couple guidelines that help us keep things organised and consistent. + +## Naming your directory/project + +All names should be lowercase alphanumeric, and separated by an underscore (`_`), but not begin with one. Dashes (`-`) aren't allow by our build system, and will confuse it with keymaps/subprojects. Your directory and your `.h` and `.c` files should have exactly the same name. Subprojects/revision should follow the same format. + +## `readme.md` + +All projects need to have a `readme.md` file that explains what the keyboard is, who made it, where it is available, and links to move information (template coming). + +## Image/Hardware files + +In an effort to keep the repo size down, we're no longer accepting images of any format in the repo, with few exceptions. Hosting them elsewhere (imgur) and linking them in the readme.md is the preferred method. + +Any sort of hardware file (plate, case, pcb) can't be stored in qmk_firmware, but we have the [qmk.fm repo](https://github.com/qmk/qmk.fm) where such files (as well as in-depth info) can be store, and viewed on [qmk.fm](http://qmk.fm). Downloadable files are stored in `/<keyboard>/` (name follows the same format as above) which are served at `http://qmk.fm/<keyboard>/`, and pages are generated from `/_pages/<keyboard>/` which are served at the same location (.md files are generated into .html files through Jekyll). Check out the `lets_split` directory for an example. + +## Non-production/handwired projects + +We're happy to accept any project that uses QMK, including prototypes and handwired ones, but we have a separate `/keyboards/handwired/` folder for them, so the main `/keyboards/` folder doesn't get overcrowded. If a prototype project becomes a production project at some point in the future, we'd be happy to move it to the main `/keyboards/` folder! + +## Warnings as errors + +When developing your keyboard, keep in mind that all warnings will be treated as errors - these small warnings can build-up and cause larger errors down the road (and keeping them is generally a bad practice). + +## Licenses + +If you're adapting your keyboard's setup from another project, but not using the same code, but sure to update the copyright header at the top of the files to show your name, it this format: + + Copyright 2017 Your Name <your@email.com> + +## Technical details + +If you're looking for more information on making your keyboard work with QMK, [check out this guide](porting_your_keyboard_to_qmk.md)! diff --git a/docs/isp_flashing_guide.md b/docs/isp_flashing_guide.md new file mode 100644 index 0000000000..0819f27480 --- /dev/null +++ b/docs/isp_flashing_guide.md @@ -0,0 +1,106 @@ +# ISP Flashing Guide + +If you're having trouble flashing/erasing your board, and running into cryptic error messages like any of the following: + + libusb: warning [darwin_transfer_status] transfer error: timed out + dfu.c:844: -ETIMEDOUT: Transfer timed out, NAK 0xffffffc4 (-60) + atmel.c:1627: atmel_flash: flash data dfu_download failed. + atmel.c:1629: Expected message length of 1072, got -60. + atmel.c:1434: Error flashing the block: err -2. + ERROR + Memory write error, use debug for more info. + commands.c:360: Error writing memory data. (err -4) + + dfu.c:844: -EPIPE: a) Babble detect or b) Endpoint stalled 0xffffffe0 (-32) + Device is write protected. + dfu.c:252: dfu_clear_status( 0x7fff4fc2ea80 ) + atmel.c:1434: Error flashing the block: err -2. + ERROR + Memory write error, use debug for more info. + commands.c:360: Error writing memory data. (err -4) + +You're likely going to need to ISP flash your board/device to get it working again. Luckily, this process is pretty straight-forward, provided you have any extra programmable keyboard, Arduino, or Teensy 2.0/Teensy 2.0++. There are also dedicated ISP flashers available for this, but most cost >$15, and it's assumed that if you are googling this error, this is the first you've heard about ISP flashing, and don't have one readily available (whereas you might have some other AVR board). __We'll be using a Teensy 2.0 with Windows 10 in this guide__ - if you are comfortable doing this on another system, please consider editing this guide and contributing those instructions! + +## Software needed + +* [The Arduino IDE](https://www.arduino.cc/en/Main/Software) +* [Teensyduino](https://www.pjrc.com/teensy/td_download.html) (if you're using a Teensy) +* [WinAVR](http://www.ladyada.net/learn/avr/setup-win.html) (Windows) + +## Wiring + +This is pretty straight-forward - we'll be connecting like-things to like-things in the following manner: + + Flasher B0 <-> Keyboard RESET + Flasher B1 <-> Keyboard B1 (SCLK) + Flasher B2 <-> Keyboard B2 (MOSI) + Flasher B3 <-> Keyboard B3 (MISO) + Flasher VCC <-> Keyboard VCC + Flasher GND <-> Keyboard GND + +## The ISP firmware + +Make sure your keyboard is unplugged from any device, and plug in your Teensy. + +1. Run Arduino after you have everything installed +2. Select `Tools > Board * > Teensy 2.0` +3. Click `File > Examples > 11.ArduinoISP > ArduinoISP` + +Then scroll down until you see something that looks like this block of code: + + // Configure which pins to use: + + // The standard pin configuration. + #ifndef ARDUINO_HOODLOADER2 + + #define RESET 0 // Use 0 (B0) instead of 10 + #define LED_HB 11 // Use 11 (LED on the Teensy 2.0) + #define LED_ERR 8 // This won't be used unless you have an LED hooked-up to 8 (D3) + #define LED_PMODE 7 // This won't be used unless you have an LED hooked-up to 7 (D2) + +And make the changes in the last four lines. If you're using something besides the Teenys 2.0, you'll want to choose something else that makes sense for `LED_HB`. We define `RESET` as `0`/`B0` because that's what's close - if you want to use another pin for some reason, [you can use the pinouts to choose something else](https://www.pjrc.com/teensy/pinout.html). + +Once you've made your changes, you can click the Upload button (right arrow), which will open up the Teensy flasher app - you'll need to press the reset button on the Teensy the first time, but after that, it's automatic (you shouldn't be flashing this more than once, though). Once flashed, the orange LED on the Teensy will flash on and off, indicating it's ready for some action. + +## The .hex file + +Before flashing your firmware, you're going to need to and do a little preparation. We'll be appending [this bootloader (also a .hex file)](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1_0_0.hex) to the end of our firmware by opening the original .hex file in a text editor, and removing the last line, which should be `:00000001FF` (this is an EOF message). After that's been removed, copy the entire bootloader's contents and paste it at the end of the original file, and save it. + +It's possible to use other bootloaders here in the same way, but __you need a bootloader__, otherwise you'll have to ISP to write new firmware to your keyboard. + +## Flashing your firmware + +Make sure your keyboard is unplugged from any device, and plug in your Teensy. + +Open `cmd` and navigate to your where your modified .hex file is. We'll pretend this file is called `main.hex`, and that your Teensy 2.0 is on the `COM3` port - if you're unsure, you can open your Device Manager, and look for `Ports > USB Serial Device`. Use that COM port here. You can confirm it's the right port with: + + avrdude -c avrisp -P COM3 -p atmega32u4 + +and you should get something like the following output: + + avrdude: AVR device initialized and ready to accept instructions + + Reading | ################################################## | 100% 0.02s + + avrdude: Device signature = 0x1e9587 + + avrdude: safemode: Fuses OK + + avrdude done. Thank you. + +Since our keyboard uses an `atmega32u4` (common), that is the chip we'll specify. This is the full command: + + avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i + +You should see a couple of progress bars, then you should see: + + avrdude: verifying ... + avrdude: 32768 bytes of flash verified + + avrdude: safemode: Fuses OK + + avrdude done. Thank you. + +Which means everything should be ok! Your board may restart automatically, otherwise, unplug your Teensy and plug in your keyboard - you can leave your Teensy wired to your keyboard while testing things, but it's recommended that you desolder it/remove the wiring once you're sure everything works. + +If you have any questions/problems, feel free to [open an issue](https://github.com/qmk/qmk_firmware/issues/new)! diff --git a/docs/key_functions.md b/docs/key_functions.md index c0f06f9c8a..74b80b42f1 100644 --- a/docs/key_functions.md +++ b/docs/key_functions.md @@ -6,6 +6,10 @@ These functions work the same way that their `ACTION_*` functions do - they're j Instead of using `FNx` when defining `ACTION_*` functions, you can use `F(x)` - the benefit here is being able to use more than 32 function actions (up to 4096), if you happen to need them. +### Limits of these aliases + +Currently, the keycodes able to used with these functions are limited to the TMK ones, meaning you can't use keycodes like `KC_TILD`, or anything greater than 0xFF. For a full list of the keycodes able to be used, [see this list](keycode.txt). + ### Switching and toggling layers `MO(layer)` - momentary switch to *layer*. As soon as you let go of the key, the layer is deactivated and you pop back out to the previous layer. When you apply this to a key, that same key must be set as `KC_TRNS` on the destination layer. Otherwise, you won't make it back to the original layer when you release the key (and you'll get a keycode sent). You can only switch to layers *above* your current layer. If you're on layer 0 and you use `MO(1)`, that will switch to layer 1 just fine. But if you include `MO(3)` on layer 5, that won't do anything for you -- because layer 3 is lower than layer 5 on the stack. diff --git a/docs/memory_write_error,_use_debug_for_more_info.md b/docs/memory_write_error,_use_debug_for_more_info.md index adef2601f0..154f3620b9 100644 --- a/docs/memory_write_error,_use_debug_for_more_info.md +++ b/docs/memory_write_error,_use_debug_for_more_info.md @@ -7,7 +7,7 @@ In rare circumstances, your keyboard/device can become unwritable, and `dfu-prog [ X ERROR Memory write error, use debug for more info. -Currently the only way to solve this is to [reprogram the chip via ISP](https://www.reddit.com/r/olkb/comments/4rjzen/flashing_error_on_mac_os_x/d52rj8o/). This requires another device to be hooked up to a couple of exposed pins on the PCB. There is a guide on how to do this [here](https://learn.sparkfun.com/tutorials/installing-an-arduino-bootloader), and [this is where things are on the Planck PCB](http://imgur.com/lvbxbHt). +Currently the only way to solve this is to [reprogram the chip via ISP](https://www.reddit.com/r/olkb/comments/4rjzen/flashing_error_on_mac_os_x/d52rj8o/). This requires another device to be hooked up to a couple of exposed pins on the PCB. __[We now have a guide on ISP flashing](isp_flashing_guide.md)__ and [this is where things are on the Planck PCB](http://imgur.com/lvbxbHt). An example command to flash the board once things are hooked up is: diff --git a/docs/modding_your_keyboard.md b/docs/modding_your_keyboard.md index 2429570f53..44e6e6e72a 100644 --- a/docs/modding_your_keyboard.md +++ b/docs/modding_your_keyboard.md @@ -1,7 +1,7 @@ ## Audio output from a speaker -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 make 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 or B5 port (`#define C6_AUDIO` and `#define B5_AUDIO`), you can hook up a simple speaker and make 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](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/audio.h) and in the other files in the audio directory. It's enabled by default on the Planck [stock keymap](https://github.com/qmk/qmk_firmware/blob/master/keyboards/planck/keymaps/default/keymap.c). Here are the important bits: diff --git a/docs/porting_your_keyboard_to_qmk.md b/docs/porting_your_keyboard_to_qmk.md index 6f291a432d..05787042fd 100644 --- a/docs/porting_your_keyboard_to_qmk.md +++ b/docs/porting_your_keyboard_to_qmk.md @@ -1,3 +1,7 @@ +# Porting your keyboard to QMK + +This page describes the technical details of porting an existing keyboard to QMK. If you're looking to add your keyboard to QMK, please [look through these guidelines](adding_a_keyboard_to_qmk.md)! + If your keyboard is running an Atmega chip (atmega32u4 and others), it's pretty easy to get things setup for compiling your own firmware to flash onto your board. There is a `/util/new_project.sh <keyboard>` script to help get you started - you can simply pass your keyboard's name into the script, and all of the necessary files will be created. The components of each are described below. ## `/keyboards/<keyboard>/config.h` @@ -34,7 +38,7 @@ At the bottom of the file, you'll find lots of features to turn on and off - all ## `/keyboards/<keyboard>/readme.md` -This is where you'll describe your keyboard - please write as much as you can about it! Talking about default functionality/features is useful here. Feel free to link to external pages/sites if necessary. Images can be included here as well. This file will be rendered into a webpage at qmk.fm/keyboards/<keyboard>/. +This is where you'll describe your keyboard - please write as much as you can about it! Talking about default functionality/features is useful here. Feel free to link to external pages/sites if necessary. Images can be included here as well, as long as they're hosted elsewhere (imgur). ## `/keyboards/<keyboard>/<keyboard>.c` |