Creating a keyboard remapping tutorial

Programming
21

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. :stuck_out_tongue:

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. :slight_smile:

-jennifer

5 Likes
22

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)

I’m happy to hear it and incredibly chagrined that ‘arthritic thumbs’ wasn’t something we’d thought hard about before now.

<3

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.

That is an incredibly fair assessment.

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.

A good suggestion. And one I’ve just pushed a poorly-worded initial fix for:

-jesse

1 Like
23

Eeek! let me see what I can do to have at least something. :slight_smile: 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.

2 Likes
24

#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 :wink:

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.

3 Likes
25

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. :wink:

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.

4 Likes
26

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.

1 Like
27

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)

1 Like
28

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.

3 Likes
29

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.

2 Likes
30

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. :slight_smile:

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!

4 Likes
31

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 and I can cut you push access :slight_smile:

1 Like
32

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.

2 Likes
33

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.

34

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.

2 Likes
35

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.

36

If you sacrifice a shift, perhaps I can interest you in a nice set of OneShot modifiers? :smiley:

1 Like
37

@Jennigma Try Sublime Text 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.)

38

@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.

1 Like
39

@algernon I’m NOT LOOKING at all the wonderful tricks on your blog until I have usable basic docs out in the world. :stuck_out_tongue:

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.

4 Likes
40

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?