From 6bd4df7a90e6137653c22b5dffa95870566eb4fd Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Sun, 11 Jun 2017 14:28:30 -0400 Subject: define limits to functions --- docs/key_functions.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/key_functions.md b/docs/key_functions.md index c0f06f9c8..74b80b42f 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. -- cgit v1.2.3 From 4217cb5bbcc7df356a084c992b7bd3239fc66390 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Sun, 18 Jun 2017 13:26:20 -0400 Subject: Update key_functions.md --- docs/key_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/key_functions.md b/docs/key_functions.md index 74b80b42f..0c5148e89 100644 --- a/docs/key_functions.md +++ b/docs/key_functions.md @@ -8,7 +8,7 @@ Instead of using `FNx` when defining `ACTION_*` functions, you can use `F(x)` - ### 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). +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.md). ### Switching and toggling layers -- cgit v1.2.3 From 621ae42a6cb9f96b8c02a0094b36daf125c4e6ca Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Sun, 18 Jun 2017 13:28:34 -0400 Subject: revert edit --- docs/key_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/key_functions.md b/docs/key_functions.md index 0c5148e89..74b80b42f 100644 --- a/docs/key_functions.md +++ b/docs/key_functions.md @@ -8,7 +8,7 @@ Instead of using `FNx` when defining `ACTION_*` functions, you can use `F(x)` - ### 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.md). +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 -- cgit v1.2.3 From f32c68ee6584fa55ea8c5ebb6399cd535234b6e4 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Thu, 22 Jun 2017 13:21:43 -0400 Subject: Update porting_your_keyboard_to_qmk.md --- docs/porting_your_keyboard_to_qmk.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/porting_your_keyboard_to_qmk.md b/docs/porting_your_keyboard_to_qmk.md index 6f291a432..05787042f 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 ` 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//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//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//. +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//.c` -- cgit v1.2.3 From 7b3c9cc8de763b7ce05415805f8f4715b2e8c136 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Thu, 22 Jun 2017 13:22:21 -0400 Subject: Create adding_a_keyboard_to_qmk.md --- docs/adding_a_keyboard_to_qmk.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/adding_a_keyboard_to_qmk.md (limited to 'docs') diff --git a/docs/adding_a_keyboard_to_qmk.md b/docs/adding_a_keyboard_to_qmk.md new file mode 100644 index 000000000..51c4c4410 --- /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 `//` (name follows the same format as above) which are served at `http://qmk.fm//`, and pages are generated from `/_pages//` 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 + +## 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)! -- cgit v1.2.3 From 2b98ec67f3c2e0e408275ea6b2c90be2dbeada23 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Thu, 22 Jun 2017 13:23:08 -0400 Subject: Update _summary.md --- docs/_summary.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 420003996..23128cafe 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -19,8 +19,9 @@ * [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) ### Other topics -- cgit v1.2.3 From b4f2f44a6f4e80ab358e439ec3c4695fccdba189 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Fri, 23 Jun 2017 21:29:04 -0400 Subject: Create isp_flashing_guide.md --- docs/isp_flashing_guide.md | 106 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 docs/isp_flashing_guide.md (limited to 'docs') diff --git a/docs/isp_flashing_guide.md b/docs/isp_flashing_guide.md new file mode 100644 index 000000000..02b34497e --- /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.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)! -- cgit v1.2.3 From 918aea5b473ebc1dee99c8ac967b8167e8b852b6 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Fri, 23 Jun 2017 21:29:35 -0400 Subject: Update _summary.md --- docs/_summary.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 23128cafe..88ed75117 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -23,6 +23,7 @@ * [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) -- cgit v1.2.3 From c208a6d4e504d736fe52bab536f9732e7e50c436 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Fri, 23 Jun 2017 23:09:14 -0400 Subject: update docs for isp --- docs/isp_flashing_guide.md | 2 +- docs/memory_write_error,_use_debug_for_more_info.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/isp_flashing_guide.md b/docs/isp_flashing_guide.md index 02b34497e..0819f2748 100644 --- a/docs/isp_flashing_guide.md +++ b/docs/isp_flashing_guide.md @@ -64,7 +64,7 @@ Once you've made your changes, you can click the Upload button (right arrow), wh ## 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.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. +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. 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 adef2601f..154f3620b 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: -- cgit v1.2.3 From 901a92a2fd2b15601832e532e5400c565f16bbaf Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Sat, 24 Jun 2017 13:11:25 -0400 Subject: Update _summary.md --- docs/_summary.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 88ed75117..8e0a6f51c 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) -- cgit v1.2.3 From 4ba9438c3f71e6ea3433be4f9e1a28d36471d247 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Tue, 27 Jun 2017 13:07:50 -0400 Subject: Add eclipse to the _summary --- docs/_summary.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 8e0a6f51c..c5e29cb52 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -29,3 +29,4 @@ ### Other topics * [General FAQ](faq.md) * [Differences from TMK](differences_from_tmk.md) +* [Using Eclipse with QMK](eclipse.md) -- cgit v1.2.3 From ea7590c8940bc85f8a83bd42b1e01bc1431c104b Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Tue, 27 Jun 2017 14:35:08 -0400 Subject: add new arguements, docs --- docs/modding_your_keyboard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/modding_your_keyboard.md b/docs/modding_your_keyboard.md index 2429570f5..44e6e6e72 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: -- cgit v1.2.3