From 349f189e83c39dc3387b9358d0d2f372a5bbdf2b Mon Sep 17 00:00:00 2001 From: Fred Sundvik Date: Sun, 10 Jul 2016 21:49:48 +0300 Subject: Move Ergodox readme from ez subfolder to parent --- keyboards/ergodox/readme.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 keyboards/ergodox/readme.md (limited to 'keyboards/ergodox/readme.md') diff --git a/keyboards/ergodox/readme.md b/keyboards/ergodox/readme.md new file mode 100644 index 000000000..67a5fb095 --- /dev/null +++ b/keyboards/ergodox/readme.md @@ -0,0 +1,44 @@ +# Getting started + +There are two main ways you could customize the ErgoDox EZ. + +## The Easy Way: Use an existing firmware file and just flash it + +1. Download and install the [Teensy Loader](https://www.pjrc.com/teensy/loader.html). Some Linux distributions already provide a binary (may be called `teensy-loader-cli`), so you may prefer to use this. +2. Find a firmware file you like. You can find a few if these in the keymaps subdirectory right here. The file you need ends with .hex, and you can look at its .c counterpart (or its PNG image) to see what you'll be getting. You can also use the [Massdrop configurator](https://keyboard-configurator.massdrop.com/ext/ergodox) to create a firmware Hex file you like. +3. Download the firmware file +4. Connect the keyboard, press its Reset button (gently insert a paperclip into the hole in the top-right corner) and flash it using the Teensy loader you installed on step 1 and the firmware you downloaded. + +## More technical: create your own totally custom firmware by editing the source files. + +This requires a little bit of familiarity with coding. + +1. Go to https://github.com/jackhumbert/qmk_firmware and read the readme at the base of this repository, top to bottom. Then come back here :) +2. Clone the repository (download it) +3. Set up a build environment as per [the build guide](/doc/BUILD_GUIDE.md) + - Using a Mac and have homebrew? just run `brew tap osx-cross/avr && brew install avr-libc` +4. Copy `keyboards/ergodox_ez/keymaps/default/keymap.c` into `keymaps/your_name/keymap.c` (for example, `keymaps/german/keymap.c`) +5. Edit this file, changing keycodes to your liking (see "Finding the keycodes you need" below). Try to edit the comments as well, so the "text graphics" represent your layout correctly. See below for more tips on sharing your work. +6. Compile your firmware by running `make keymap=your_name`. For example, `make keymap=german`. This will result in a hex file, which will be called `ergodox_ez_your_name.hex`, e.g. `ergodox_ez_german.hex`. +6. Flash this hex file using the [Teensy loader](https://www.pjrc.com/teensy/loader.html) as described in step 4 in the "Easy Way" above. If you prefer you can automatically flash the hex file after successfull build by running `make teensy keymap=your_name`. +7. Submit your work as a pull request to this repository, so others can also use it. :) See below on specifics. + +Good luck! :) + +## Contributing your keymap + +The ErgoDox EZ firmware is open-source, so it would be wonderful to have your contribution! Within a very short time after launching we already amassed almost 20 user-contributed keymaps, with all sorts of creative improvements and tweaks. This is very valuable for people who aren't comfortable coding, but do want to customize their ErgoDox EZ. To make it easy for these people to use your layout, I recommend submitting your PR in the following format. + +1. All work goes inside your keymap subdirectory (`keymaps/german` in this example). +2. `keymap.c` - this is your actual keymap file; please update the ASCII comments in the file so they correspond with what you did. +3. `readme.md` - a readme file, which GitHub would display by default when people go to your directory. Explain what's different about your keymap, what you tweaked or how it works. No specific format to follow, just communicate what you did. :) +4. Any graphics you wish to add. This is absolutely not a must. If you feel like it, you can use [Keyboard Layout Editor](http://keyboard-layout-editor.com) to make something and grab a screenshot, but it's really not a must. If you do have graphics, your readme can just embed the graphic as a link, just like I did with the default layout. + + +## Finding the keycodes you need + +Let's say you want a certain key in your layout to send a colon; to figure out what keycode to use to make it do that, you're going to need `quantum/keymap_common.h`. + +That file contains a big list of all of the special, fancy keys (like, being able to send % on its own and whatnot). + +If you want to send a plain vanilla key, you can look up its code under `doc/keycode.txt`. That's where all the boring keys hang out. -- cgit v1.2.3 From 44cefcb40a8789d8d7965e645d5cd155b6d16370 Mon Sep 17 00:00:00 2001 From: Fred Sundvik Date: Sun, 10 Jul 2016 22:08:01 +0300 Subject: Refer to the right path in the readme --- keyboards/ergodox/readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'keyboards/ergodox/readme.md') diff --git a/keyboards/ergodox/readme.md b/keyboards/ergodox/readme.md index 67a5fb095..c99c8d82b 100644 --- a/keyboards/ergodox/readme.md +++ b/keyboards/ergodox/readme.md @@ -17,7 +17,7 @@ This requires a little bit of familiarity with coding. 2. Clone the repository (download it) 3. Set up a build environment as per [the build guide](/doc/BUILD_GUIDE.md) - Using a Mac and have homebrew? just run `brew tap osx-cross/avr && brew install avr-libc` -4. Copy `keyboards/ergodox_ez/keymaps/default/keymap.c` into `keymaps/your_name/keymap.c` (for example, `keymaps/german/keymap.c`) +4. Copy `keyboards/ergodox/keymaps/default/keymap.c` into `keymaps/your_name/keymap.c` (for example, `keymaps/german/keymap.c`) 5. Edit this file, changing keycodes to your liking (see "Finding the keycodes you need" below). Try to edit the comments as well, so the "text graphics" represent your layout correctly. See below for more tips on sharing your work. 6. Compile your firmware by running `make keymap=your_name`. For example, `make keymap=german`. This will result in a hex file, which will be called `ergodox_ez_your_name.hex`, e.g. `ergodox_ez_german.hex`. 6. Flash this hex file using the [Teensy loader](https://www.pjrc.com/teensy/loader.html) as described in step 4 in the "Easy Way" above. If you prefer you can automatically flash the hex file after successfull build by running `make teensy keymap=your_name`. -- cgit v1.2.3 From c65da1f2089e53b051cd10a240e14d2335c6d8e6 Mon Sep 17 00:00:00 2001 From: Fred Sundvik Date: Sun, 10 Jul 2016 22:52:26 +0300 Subject: Unify the ErgoDox EZ and Infinity documentation --- keyboards/ergodox/readme.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) (limited to 'keyboards/ergodox/readme.md') diff --git a/keyboards/ergodox/readme.md b/keyboards/ergodox/readme.md index c99c8d82b..8cd553ee1 100644 --- a/keyboards/ergodox/readme.md +++ b/keyboards/ergodox/readme.md @@ -1,17 +1,20 @@ # Getting started -There are two main ways you could customize the ErgoDox EZ. +There are two main ways you could customize the ErgoDox (EZ and Infinity) ## The Easy Way: Use an existing firmware file and just flash it +This does not work for Infinity ErgoDox yet, you need to compile the firmware according to the instructions below + 1. Download and install the [Teensy Loader](https://www.pjrc.com/teensy/loader.html). Some Linux distributions already provide a binary (may be called `teensy-loader-cli`), so you may prefer to use this. -2. Find a firmware file you like. You can find a few if these in the keymaps subdirectory right here. The file you need ends with .hex, and you can look at its .c counterpart (or its PNG image) to see what you'll be getting. You can also use the [Massdrop configurator](https://keyboard-configurator.massdrop.com/ext/ergodox) to create a firmware Hex file you like. +2. Find a firmware file you like. You can find a few of these in the keymaps subdirectory right here. The file you need ends with .hex, and you can look at its .c counterpart (or its PNG image) to see what you'll be getting. You can also use the [Massdrop configurator](https://keyboard-configurator.massdrop.com/ext/ergodox) to create a firmware Hex file you like. 3. Download the firmware file 4. Connect the keyboard, press its Reset button (gently insert a paperclip into the hole in the top-right corner) and flash it using the Teensy loader you installed on step 1 and the firmware you downloaded. -## More technical: create your own totally custom firmware by editing the source files. +## More technical: compile an existing keymap, or create your own totally custom firmware by editing the source files. -This requires a little bit of familiarity with coding. +This requires a little bit of familiarity with coding. +If you are just compiling and existing keymap and don't want to create your own, you can skip step 4, 5 and 8. 1. Go to https://github.com/jackhumbert/qmk_firmware and read the readme at the base of this repository, top to bottom. Then come back here :) 2. Clone the repository (download it) @@ -19,15 +22,17 @@ This requires a little bit of familiarity with coding. - Using a Mac and have homebrew? just run `brew tap osx-cross/avr && brew install avr-libc` 4. Copy `keyboards/ergodox/keymaps/default/keymap.c` into `keymaps/your_name/keymap.c` (for example, `keymaps/german/keymap.c`) 5. Edit this file, changing keycodes to your liking (see "Finding the keycodes you need" below). Try to edit the comments as well, so the "text graphics" represent your layout correctly. See below for more tips on sharing your work. -6. Compile your firmware by running `make keymap=your_name`. For example, `make keymap=german`. This will result in a hex file, which will be called `ergodox_ez_your_name.hex`, e.g. `ergodox_ez_german.hex`. -6. Flash this hex file using the [Teensy loader](https://www.pjrc.com/teensy/loader.html) as described in step 4 in the "Easy Way" above. If you prefer you can automatically flash the hex file after successfull build by running `make teensy keymap=your_name`. -7. Submit your work as a pull request to this repository, so others can also use it. :) See below on specifics. +6. Compile your firmware by running `make keymap=keymap_name`. For example, `make keymap=german`. This will result in a hex file, which will be called `ergodox_ez_keymap_name.hex`, e.g. `ergodox_ez_german.hex`. For **Infinity ErgoDox** you need to add `subproject=infinity` to the make command. +7. **ErgoDox EZ** - Flash this hex file using the [Teensy loader](https://www.pjrc.com/teensy/loader.html) as described in step 4 in the "Easy Way" above. If you prefer you can automatically flash the hex file after successful build by running `make teensy keymap=your_name`. + + **Infinity ErgoDox** - Flash the firmware by running `make dfu-util keymap=your_name` +8. Submit your work as a pull request to this repository, so others can also use it. :) See below on specifics. Good luck! :) ## Contributing your keymap -The ErgoDox EZ firmware is open-source, so it would be wonderful to have your contribution! Within a very short time after launching we already amassed almost 20 user-contributed keymaps, with all sorts of creative improvements and tweaks. This is very valuable for people who aren't comfortable coding, but do want to customize their ErgoDox EZ. To make it easy for these people to use your layout, I recommend submitting your PR in the following format. +The ErgoDox firmware is open-source, so it would be wonderful to have your contribution! Within a very short time after launching we already amassed almost 20 user-contributed keymaps, with all sorts of creative improvements and tweaks. This is very valuable for people who aren't comfortable coding, but do want to customize their ErgoDox. To make it easy for these people to use your layout, I recommend submitting your PR in the following format. 1. All work goes inside your keymap subdirectory (`keymaps/german` in this example). 2. `keymap.c` - this is your actual keymap file; please update the ASCII comments in the file so they correspond with what you did. -- cgit v1.2.3 From 401dd090772936a75667a5d1510ff580d6d568bd Mon Sep 17 00:00:00 2001 From: Fred Sundvik Date: Sun, 10 Jul 2016 22:55:20 +0300 Subject: A couple of more Ergodox readme fixes --- keyboards/ergodox/readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'keyboards/ergodox/readme.md') diff --git a/keyboards/ergodox/readme.md b/keyboards/ergodox/readme.md index 8cd553ee1..983559c76 100644 --- a/keyboards/ergodox/readme.md +++ b/keyboards/ergodox/readme.md @@ -23,9 +23,9 @@ If you are just compiling and existing keymap and don't want to create your own, 4. Copy `keyboards/ergodox/keymaps/default/keymap.c` into `keymaps/your_name/keymap.c` (for example, `keymaps/german/keymap.c`) 5. Edit this file, changing keycodes to your liking (see "Finding the keycodes you need" below). Try to edit the comments as well, so the "text graphics" represent your layout correctly. See below for more tips on sharing your work. 6. Compile your firmware by running `make keymap=keymap_name`. For example, `make keymap=german`. This will result in a hex file, which will be called `ergodox_ez_keymap_name.hex`, e.g. `ergodox_ez_german.hex`. For **Infinity ErgoDox** you need to add `subproject=infinity` to the make command. -7. **ErgoDox EZ** - Flash this hex file using the [Teensy loader](https://www.pjrc.com/teensy/loader.html) as described in step 4 in the "Easy Way" above. If you prefer you can automatically flash the hex file after successful build by running `make teensy keymap=your_name`. +7. **ErgoDox EZ** - Flash this hex file using the [Teensy loader](https://www.pjrc.com/teensy/loader.html) as described in step 4 in the "Easy Way" above. If you prefer you can automatically flash the hex file after successful build by running `make teensy keymap=keymap_name`. - **Infinity ErgoDox** - Flash the firmware by running `make dfu-util keymap=your_name` + **Infinity ErgoDox** - Flash the firmware by running `make dfu-util keymap=keymap_name subproject=infinity` 8. Submit your work as a pull request to this repository, so others can also use it. :) See below on specifics. Good luck! :) -- cgit v1.2.3 From 6e8a5aca9d7a955a6037a6db8a6e9068354db894 Mon Sep 17 00:00:00 2001 From: Fred Sundvik Date: Sun, 10 Jul 2016 23:07:00 +0300 Subject: Fix typo in the readme. --- keyboards/ergodox/readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'keyboards/ergodox/readme.md') diff --git a/keyboards/ergodox/readme.md b/keyboards/ergodox/readme.md index 983559c76..9afa47410 100644 --- a/keyboards/ergodox/readme.md +++ b/keyboards/ergodox/readme.md @@ -14,7 +14,7 @@ This does not work for Infinity ErgoDox yet, you need to compile the firmware ac ## More technical: compile an existing keymap, or create your own totally custom firmware by editing the source files. This requires a little bit of familiarity with coding. -If you are just compiling and existing keymap and don't want to create your own, you can skip step 4, 5 and 8. +If you are just compiling an existing keymap and don't want to create your own, you can skip step 4, 5 and 8. 1. Go to https://github.com/jackhumbert/qmk_firmware and read the readme at the base of this repository, top to bottom. Then come back here :) 2. Clone the repository (download it) -- cgit v1.2.3 From 56aa51664e69af93ca3c1f59c760853a24548145 Mon Sep 17 00:00:00 2001 From: Erez Zukerman Date: Mon, 1 Aug 2016 21:15:01 -0400 Subject: Updates ErgoDox readme --- keyboards/ergodox/readme.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) (limited to 'keyboards/ergodox/readme.md') diff --git a/keyboards/ergodox/readme.md b/keyboards/ergodox/readme.md index 9afa47410..f81d7cd8d 100644 --- a/keyboards/ergodox/readme.md +++ b/keyboards/ergodox/readme.md @@ -2,24 +2,21 @@ There are two main ways you could customize the ErgoDox (EZ and Infinity) -## The Easy Way: Use an existing firmware file and just flash it - -This does not work for Infinity ErgoDox yet, you need to compile the firmware according to the instructions below +## The Easy Way: Use an existing firmware file and just flash it (ErgoDox EZ only) 1. Download and install the [Teensy Loader](https://www.pjrc.com/teensy/loader.html). Some Linux distributions already provide a binary (may be called `teensy-loader-cli`), so you may prefer to use this. -2. Find a firmware file you like. You can find a few of these in the keymaps subdirectory right here. The file you need ends with .hex, and you can look at its .c counterpart (or its PNG image) to see what you'll be getting. You can also use the [Massdrop configurator](https://keyboard-configurator.massdrop.com/ext/ergodox) to create a firmware Hex file you like. +2. Find a firmware file you like. There are [dozens of community-contributed keymaps](http://qmk.fm/keyboards/ergodox/) you can browse and download. You can also use the [Massdrop configurator](https://keyboard-configurator.massdrop.com/ext/ergodox) to create a firmware Hex file you like. 3. Download the firmware file 4. Connect the keyboard, press its Reset button (gently insert a paperclip into the hole in the top-right corner) and flash it using the Teensy loader you installed on step 1 and the firmware you downloaded. ## More technical: compile an existing keymap, or create your own totally custom firmware by editing the source files. -This requires a little bit of familiarity with coding. +This requires a little bit of familiarity with coding. If you are just compiling an existing keymap and don't want to create your own, you can skip step 4, 5 and 8. 1. Go to https://github.com/jackhumbert/qmk_firmware and read the readme at the base of this repository, top to bottom. Then come back here :) 2. Clone the repository (download it) -3. Set up a build environment as per [the build guide](/doc/BUILD_GUIDE.md) - - Using a Mac and have homebrew? just run `brew tap osx-cross/avr && brew install avr-libc` +3. Set up a build environment as per the readme. 4. Copy `keyboards/ergodox/keymaps/default/keymap.c` into `keymaps/your_name/keymap.c` (for example, `keymaps/german/keymap.c`) 5. Edit this file, changing keycodes to your liking (see "Finding the keycodes you need" below). Try to edit the comments as well, so the "text graphics" represent your layout correctly. See below for more tips on sharing your work. 6. Compile your firmware by running `make keymap=keymap_name`. For example, `make keymap=german`. This will result in a hex file, which will be called `ergodox_ez_keymap_name.hex`, e.g. `ergodox_ez_german.hex`. For **Infinity ErgoDox** you need to add `subproject=infinity` to the make command. @@ -32,12 +29,12 @@ Good luck! :) ## Contributing your keymap -The ErgoDox firmware is open-source, so it would be wonderful to have your contribution! Within a very short time after launching we already amassed almost 20 user-contributed keymaps, with all sorts of creative improvements and tweaks. This is very valuable for people who aren't comfortable coding, but do want to customize their ErgoDox. To make it easy for these people to use your layout, I recommend submitting your PR in the following format. +The QMK firmware is open-source, so it would be wonderful to have your contribution! Within a very short time after launching we already amassed dozens of user-contributed keymaps, with all sorts of creative improvements and tweaks. This is very valuable for people who aren't comfortable coding, but do want to customize their ErgoDox. To make it easy for these people to use your layout, I recommend submitting your PR in the following format. 1. All work goes inside your keymap subdirectory (`keymaps/german` in this example). 2. `keymap.c` - this is your actual keymap file; please update the ASCII comments in the file so they correspond with what you did. 3. `readme.md` - a readme file, which GitHub would display by default when people go to your directory. Explain what's different about your keymap, what you tweaked or how it works. No specific format to follow, just communicate what you did. :) -4. Any graphics you wish to add. This is absolutely not a must. If you feel like it, you can use [Keyboard Layout Editor](http://keyboard-layout-editor.com) to make something and grab a screenshot, but it's really not a must. If you do have graphics, your readme can just embed the graphic as a link, just like I did with the default layout. +4. Any graphics you wish to add. This is absolutely not a must. If you feel like it, you can use [Keyboard Layout Editor](http://keyboard-layout-editor.com) to make something and grab a screenshot, but it's really not a must. If you do have graphics, your readme can just embed the graphic as a link, just like I did with the default layout. ## Finding the keycodes you need -- cgit v1.2.3