# Creating a keyboard remapping tutorial **URL:** \ **Category:** Programming\ **Created:** [September 28, 2017, 6:56pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343 "2017-09-28T18:56:23Z")\ **Posts on this page:** 20\ **Page:** 2
**Author:** ![Jennigma](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jennigma/32/353_2.png) [@Jennigma](https://community.keyboard.io/u/Jennigma)\ **Post date:** [October 2, 2017, 1:12am UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/21 "2017-10-02T01:12:46Z")
I tried remapping Key\_Keymap1\_Momentary in all three layers without making other changes to my system, and it’s working just fine. So I had indeed tried to re-map a magic key. 😛 This is also so much more comfortable for me! I have arthritic thumbs, so it was a lot to ask to have them managing to do so much. I may end up re-mapping all of the thumb keys. So nice to be able to customize! ok, I’ll start working on newbie docs for keymapping and enabling/disabling LED patterns. I’m also curious about some of the ideas I’ve seen on @algernon’s blog, and on creating some macros, but I’m going to wait to dive into that. It’s nice to be ending the weekend with a sense of accomplishment! When are the production boards shipping? I’ll try to have the docs done with time to spare so they can be QA’d before the next wave of newbies hits. My takeaway from this is that it’s not at all difficult to make simple changes once the underlying structure and lingo is clarified, but it’s a pretty substantial hill to climb without more documentation. Is there a reason the Model01-Firmware.ino file is uncommented? I think a few comments would go a long way towards clarifying the major regions of the config for newbs with more or less my level of competence. I would also recommend ending Model01-Firmware/README.md with a next steps section pointing at the .ino as the likely next place a newb is going to want to go. Chances are good that anyone who downloads and installs the firmware has modification in mind. 🙂 -jennifer ---
**Author:** ![jesse](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jesse/32/361_2.png) [@jesse](https://community.keyboard.io/u/jesse)\ **Post date:** [October 2, 2017, 7:04pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/22 "2017-10-02T19:04:03Z")
> [@Preparing plugins for 1.0.0: Looking for documentation reviewers](https://community.keyboard.io/t/preparing-plugins-for-1-0-0-looking-for-documentation-reviewers/263/56): > > I tried remapping Key\_Keymap1\_Momentary in all three layers without making other changes to my system, and it’s working just fine. So I had indeed tried to re-map a magic key. 😛 Ok! That’s something indeed. And It’s something that could be clearer. Looking at the code, I think that we should be able to simplify the keymaps a little bit: - On the Numpad keymap, I don’t see why we need to explicitly make the fn key Key\_Keymap1\_Momentary instead of a ‘`___`’ fallthrough. - On the GENERIC\_FN2 keymap, we should change the map such that the thumb keys are all ‘`___`’ fallthroughs, with the exception of the two keys that are _different_ on that layer. (Backspace becomes Delete and Space becomes Enter) > [@Preparing plugins for 1.0.0: Looking for documentation reviewers](https://community.keyboard.io/t/preparing-plugins-for-1-0-0-looking-for-documentation-reviewers/263/56): > > This is also so much more comfortable for me! I have arthritic thumbs, so it was a lot to ask to have them managing to do so much. I may end up re-mapping all of the thumb keys. So nice to be able to customize! I’m happy to hear it and incredibly chagrined that ‘arthritic thumbs’ wasn’t something we’d thought hard about before now. > [@Preparing plugins for 1.0.0: Looking for documentation reviewers](https://community.keyboard.io/t/preparing-plugins-for-1-0-0-looking-for-documentation-reviewers/263/56): > > ok, I’ll start working on newbie docs for keymapping and enabling/disabling LED patterns. I’m also curious about some of the ideas I’ve seen on @algernon’s blog, and on creating some macros, but I’m going to wait to dive into that. It’s nice to be ending the weekend with a sense of accomplishment! \<3 > [@Preparing plugins for 1.0.0: Looking for documentation reviewers](https://community.keyboard.io/t/preparing-plugins-for-1-0-0-looking-for-documentation-reviewers/263/56): > > When are the production boards shipping? I’ll try to have the docs done with time to spare so they can be QA’d before the next wave of newbies hits. They should start going out on Friday or Monday. (Right now, they’re in the air from Seoul to SFO, if the tracking data is to believed. > [@Preparing plugins for 1.0.0: Looking for documentation reviewers](https://community.keyboard.io/t/preparing-plugins-for-1-0-0-looking-for-documentation-reviewers/263/56): > > My takeaway from this is that it’s not at all difficult to make simple changes once the underlying structure and lingo is clarified, but it’s a pretty substantial hill to climb without more documentation. That is an incredibly fair assessment. > [@Preparing plugins for 1.0.0: Looking for documentation reviewers](https://community.keyboard.io/t/preparing-plugins-for-1-0-0-looking-for-documentation-reviewers/263/56): > > Is there a reason the Model01-Firmware.ino file is uncommented? I think a few comments would go a long way towards clarifying the major regions of the config for newbs with more or less my level of competence. There are a few reasons. All of them are bad reasons that can be reduced to ‘procrastination’. I’m going to take fixing that as _my_ next task. > [@Preparing plugins for 1.0.0: Looking for documentation reviewers](https://community.keyboard.io/t/preparing-plugins-for-1-0-0-looking-for-documentation-reviewers/263/56): > > I would also recommend ending Model01-Firmware/README.md with a next steps section pointing at the .ino as the likely next place a newb is going to want to go. Chances are good that anyone who downloads and installs the firmware has modification in mind. 🙂 A good suggestion. And one I’ve just pushed a poorly-worded initial fix for: > -jesse ---
**Author:** ![Jennigma](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jennigma/32/353_2.png) [@Jennigma](https://community.keyboard.io/u/Jennigma)\ **Post date:** [October 2, 2017, 7:20pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/23 "2017-10-02T19:20:15Z")
> [@Preparing plugins for 1.0.0: Looking for documentation reviewers](https://community.keyboard.io/t/preparing-plugins-for-1-0-0-looking-for-documentation-reviewers/263/57): > > They should start going out on Friday or Monday. (Right now, they’re in the air from Seoul to SFO, if the tracking data is to believed. Eeek! let me see what I can do to have at least something. 🙂 Adding to the readme and code comments may be the best initial goal. In the medium term I create docs as one of the many professional hats I wear and can easily turn out a nice pdf with screenshots, if you would like that. ---
**Author:** ![jesse](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jesse/32/361_2.png) [@jesse](https://community.keyboard.io/u/jesse)\ **Post date:** [October 2, 2017, 7:44pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/24 "2017-10-02T19:44:34Z")
> [@Preparing plugins for 1.0.0: Looking for documentation reviewers](https://community.keyboard.io/t/preparing-plugins-for-1-0-0-looking-for-documentation-reviewers/263/58): > > Eeek! let me see what I can do to have at least something. 🙂 Adding to the readme and code comments may be the best initial goal. In the medium term I create docs as one of the many professional hats I wear and can easily turn out a nice pdf with screenshots, if you would like that. _ **#1 most important thing - You are doing this out of the goodness in your heart. My tardiness on getting docs in place is not your emergency 😉** _ I agree that a better commented default sketch feels like the next priority and I’m settling in with some loud music and a cup of coffee to work on that now. Documentation in any format you care to generate on any schedule that works for you will be a wonderful addition. For long-term maintainability, we’ve mostly been standardizing on markdown for writing what documentation we have. It’s not the most expressive thing on the planet, but it’s something we can use to generate HTML and PDF output, among other things. If your preference is just to generate PDFs directly, that’s 100% cool, though I may end up asking for permission to extract the content to something editable later. We’ve been starting to look at using doxygen to generate API docs. In _theory_ it should work ok for tutorials as well. That said, if you have recommendations of toolsets you’ve found useful, I’m all ears. ---
**Author:** ![Jennigma](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jennigma/32/353_2.png) [@Jennigma](https://community.keyboard.io/u/Jennigma)\ **Post date:** [October 2, 2017, 8:10pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/25 "2017-10-02T20:10:51Z")
Yup! I like using my skills in service of projects I want to support. And I like imagining that my struggles will help people in the production run have a better experience. Helps me feel like I earned my PVT unit. 😉 I can work in markdown. Very familiar with it. I don’t have recommendations for code documentation tools, though one of my good friends who should be getting a Model 1 soon writes API docs for Google, and also likes working on open source projects. I’ll ask her and see if she has thoughts. I was already going to ask her to review my docs when she gets her unit. ---
**Author:** ![jesse](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jesse/32/361_2.png) [@jesse](https://community.keyboard.io/u/jesse)\ **Post date:** [October 3, 2017, 6:17am UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/26 "2017-10-03T06:17:06Z")
I’ve just pushed an update of the sketch: > It refactors some stuff and adds a bunch of very poorly written documentation. It’s…not up to what I’d consider my usual standard, but I’m a little short of sleep. Hopefully, it’s at least something that can be used as the basis of something we can improve in the future. ---
**Author:** ![jesse](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jesse/32/361_2.png) [@jesse](https://community.keyboard.io/u/jesse)\ **Post date:** [October 3, 2017, 7:06am UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/27 "2017-10-03T07:06:39Z")
Just as a note, you’ll also need to ‘make update-submodules’ inside the hardware directory with today’s update. (That’s now described in the README, too) ---
**Author:** ![Jennigma](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jennigma/32/353_2.png) [@Jennigma](https://community.keyboard.io/u/Jennigma)\ **Post date:** [October 3, 2017, 3:38pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/28 "2017-10-03T15:38:21Z")
I’ve archived my original installation and am uninstalling all of the subcomponents so I can begin working through documenting the process. Since you’ve working on the readme and commenting, I’m going to work on the more discursive Markdown version. ---
**Author:** ![james.nvc](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/james.nvc/32/54_2.png) [@james.nvc](https://community.keyboard.io/u/james.nvc)\ **Post date:** [October 3, 2017, 5:31pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/29 "2017-10-03T17:31:19Z")
I did a pass on @algernon’s docs for the Kaleidoscope things a while ago; when I (fingers crossed) get my hands on a keyboard, I would like very much to contribute to this as well! I’ve been working on making my own mapping but obviously haven’t been able to actually test that it works yet. ---
**Author:** ![Jennigma](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jennigma/32/353_2.png) [@Jennigma](https://community.keyboard.io/u/Jennigma)\ **Post date:** [October 3, 2017, 9:46pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/30 "2017-10-03T21:46:39Z")
Anyone feel like giving me a quick primer on using git to set up a repository for the Markdown docs, and to submit suggestions on the code comments and readme? I’ve only ever taken things from git, not contributed, so my skillset is limited. I’m assuming folks who know what git and brew are, already have a favorite editor, and are comfortable with the command line will be happy with the readme and code comments, so I’m writing docs for a clever novice audience. My current plan is to introduce them to Atom for repository management and firmware editing, to limit the number of new tools they need to learn. I haven’t started writing that part of things yet and would love opinions and suggestions if there are better tools out there. Atom is new to me as well; I am comfortable with emacs and the command line, and used git and brew to setup my system as the readme suggests. I’m using Atom as a Markdown editor now, to familiarize myself with it. What I’m working on first is a conceptual introduction to how the keyboardio and operating system interact, and how the firmware is structured at a high level. (Think: keymaps, modules, etc.) I would love any commentary and insight from folks who know more about keyboards than me. For instance I just wrote a couple paragraphs about keycodes and keymaps, as well as a couple more explaining why the shifted function of a given keycode can’t (easily) be changed in keyboardio firmware. I don’t want to overwhelm novices with esoteric details, but I would like to highlight pitfalls they are likely to encounter, and to introduce the basic concepts. The idea is to help novices turn concepts over in their minds so they get familiar with them before they try to make changes. I expect most people will skip the intro and dive straight into the nuts and bolts of getting things working, then revisit it if they get snarled up. Only the cautious and timid will read this section on their first pass through, and I want to help those folks find their confidence. 🙂 If there are good discussions in the forums about the structure of the keyboardio firmware, tips and ideas about configuring it, or outside resources that do similar things, please let me know! ---
**Author:** ![jesse](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jesse/32/361_2.png) [@jesse](https://community.keyboard.io/u/jesse)\ **Post date:** [October 3, 2017, 10:11pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/31 "2017-10-03T22:11:01Z")
If you’re cool with using existing infrastructure, you shouldn’t need to create a new repository. Every git project has its own ‘wiki’ which is essentially, just a git repo full of Markdown docs. The one question is whether things belong in the Model01-Firmware repo or the Kaleidoscope repo. The way we think about it, Kaleidoscope can run on multiple keyboards, though the Model 01 is the first hardware it ships on. We’re fine with Model01-specific content in the Kaleidoscope repo, though hope to make most of the content more generally useful as more keyboards ship with Kaleidoscope. If you’re game, the wiki’s github URL is [https://github.com/keyboardio/Kaleidoscope.wiki.git](https://github.com/keyboardio/Kaleidoscope.wiki.git) and I can cut you push access 🙂 ---
**Author:** ![merlin](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/merlin/32/3416_2.png) [@merlin](https://community.keyboard.io/u/merlin)\ **Post date:** [October 4, 2017, 1:55am UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/32 "2017-10-04T01:55:47Z")
> [@Jennigma](#): > > This is also so much more comfortable for me! I have arthritic thumbs, so it was a lot to ask to have them managing to do so much. I may end up re-mapping all of the thumb keys. So nice to be able to customize! You might be interested in trying one of my experimental ideas and using @algernon’s `DualUse` module to put modifier keys under your fingers, possibly even on the home row of each hand. I can’t tell you how well that works, since I don’t have the hardware yet, but it sounds like you may have a much better reason to do that than I do. ---
**Author:** ![Jennigma](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jennigma/32/353_2.png) [@Jennigma](https://community.keyboard.io/u/Jennigma)\ **Post date:** [October 4, 2017, 6:01am UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/33 "2017-10-04T06:01:32Z")
cmd/shift on the left and shift/alt on the right are comfortable, but it hurts to pinch my thumb in towards my palm, so to hit ctrl/bksp or space/ctrl I have to move my hands from the home keys. So I may sacrifice a shift key to become a control, or make fn-shift be control. ---
**Author:** ![Jennigma](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jennigma/32/353_2.png) [@Jennigma](https://community.keyboard.io/u/Jennigma)\ **Post date:** [October 5, 2017, 1:29pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/34 "2017-10-05T13:29:06Z")
I take back any nice thing I ever said about Atom. I just spent half an hour cleaning its fingerprints off my system because it wouldn’t uninstall cleanly. Ick. ---
**Author:** ![Jennigma](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jennigma/32/353_2.png) [@Jennigma](https://community.keyboard.io/u/Jennigma)\ **Post date:** [October 5, 2017, 1:43pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/35 "2017-10-05T13:43:16Z")
Atom can DIAF. I just had to reset my LauchServices because it had claimed ownership of every possibly relevant file type. Ick. For shame, GitHub. For shame. ---
**Author:** ![algernon](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/algernon/32/4404_2.png) [@algernon](https://community.keyboard.io/u/algernon)\ **Post date:** [October 5, 2017, 1:59pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/36 "2017-10-05T13:59:31Z")
> [@Jennigma](#): > > So I may sacrifice a shift key to become a control, or make fn-shift be control. If you sacrifice a shift, perhaps I can interest you in a nice set of [OneShot](https://github.com/keyboardio/Kaleidoscope-OneShot) modifiers? 😃 ---
**Author:** ![Benji](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/benji/32/355_2.png) [@Benji](https://community.keyboard.io/u/Benji)\ **Post date:** [October 5, 2017, 2:01pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/37 "2017-10-05T14:01:17Z")
@Jennigma Try [Sublime Text](https://www.sublimetext.com) instead of Atom. Sublime’s track record is far longer than Atom, and it’s one of the top programming text editors. (Programmer friends: let’s not get into a war about editors here; I’m just trying to get @Jennigma pointed towards a toolset that won’t get in her way.) ---
**Author:** ![Jennigma](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jennigma/32/353_2.png) [@Jennigma](https://community.keyboard.io/u/Jennigma)\ **Post date:** [October 5, 2017, 2:16pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/38 "2017-10-05T14:16:21Z")
@Benji I’m an old hack and emacs has been my editor since… 1987? I think? Thereabouts, anyway. Though I’ll freely admit I’m quite rusty; I haven’t used the command line on a daily basis this century. I was auditioning Atom as a toolset for novices to use in the docs I’m creating, because it has support for git and for Arduino, got good reviews on a couple sites, and looked friendly. I was gaining familiarity with it by using it to edit the markdown files I’m working on. ---
**Author:** ![Jennigma](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jennigma/32/353_2.png) [@Jennigma](https://community.keyboard.io/u/Jennigma)\ **Post date:** [October 5, 2017, 2:23pm UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/39 "2017-10-05T14:23:32Z")
@algernon I’m NOT LOOKING at all the wonderful tricks on your blog until I have usable basic docs out in the world. 😛 Believe me I’ve read your blog and dreamed up all sorts of ideas. There will be more advanced docs as I work my way through them. Starting to play with that is my lollipop for when I have something released and teched by at least a couple folks. I’m guessing that’s at least a couple weeks out, because I expect there will be a flood of new user questions hitting any day now when the 1002 keyboards start showing up on doorsteps, and we’ll all be swamped for a bit. ---
**Author:** ![Jennigma](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jennigma/32/353_2.png) [@Jennigma](https://community.keyboard.io/u/Jennigma)\ **Post date:** [October 6, 2017, 2:18am UTC](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/40 "2017-10-06T02:18:02Z")
A few questions: 1. Am I telling lies if I say in the tutorial that it’s ok to map the PROG key in any way that’s desired? 2. Do we want to include the Dvorak and Colemark keymaps in the docs with instructions so people can easily cut/paste and search/replace QWERTY? Or do we want to have them pre-defined but inactive in the Model 01 sketch? [Previous page](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343.md?page=1) [Next page](https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343.md?page=3)