Preparing plugins for 1.0.0: Looking for documentation reviewers

I’m also willing to review documentation, but I don’t know anything about Arduino, so would need it to be step-by-step, starting from the very beginning.

I’d much rather have straightforward step-by-step instructions, and skip the stories, myself. For example:

  1. Type the following command to install Arduino: …
  2. Type the following commands to clone/create the necessary git repositories: …
  3. Edit file X to remap some keys as follows: …
  4. Flash the firmware with this command: …

How long would it take to write that up (but with actual details) so that someone with a Model 01 could get started gradually building up their own configuration? It ought to make debugging issues people report simpler, too, if they’re not just left to their own devices in figuring out how to make a sketch, but have a recommended pattern to follow.

I think it would be nice if both existed, they serve different audiences.

If I wrote it, and had to skip the stories, It would take ~forever. I’m not good at writing things I wouldn’t read myself. But! The good news is, that the steps will be easy to extract from the stories, so after a story is written, I can lift the steps out, and turn it into a step-by-step, story-less guide.

So the two can be done in parallel: I first write the story, because I find that much more fun (and if something is fun, I do it considerably faster), and then either me, or someone else can lift out the steps to another, more to-the-point kind of guide.

So, yep, fully agreed, having a step-by-step guide would be awesome too, and having written this response made me realize I can do both at the same time.

1 Like

In that case, would someone who already understands how to do it other than @algernon care to help out the people who don’t? Even without all the details, some instructions would be better than the nothing that we have right now.

If nobody has done it yet by the time I next have some free time for this (the last week of August, probably), I’ll make some guesses and write it up myself, then people who actually have hardware and genuine knowledge of how it works can make corrections.

It’s poorly organized and not without errors, but there is basic setup and customization doc.

https://github.com/keyboardio/Model01-Firmware/blob/master/README.md (https://github.com/keyboardio/Model01-Firmware/blob/readme-and-env/README.md is an updated version already a WIP)

And indeed, more in Remapping keys? - #23 by algernon

That’s the kind of step-by-step guide I’m getting at, but it only gets the user as far as (re)flashing the keyboard with the default firmware. It doesn’t provide any guidance or even hints about how to make one’s own customized firmware.

  • Should one make a copy of Model01-Firmware? Make a new repository from scratch?
  • What files should be modified to make changes? And how?
  • The plugin docs (such as they are) refer to a thing called a “Sketch” – what is that?

These questions (and more) need to be answered clearly with step-by-step instructions, or many people are likely to just give up.

2 Likes

I don’t think anyone is disagreeing that we need such tutorial documentation. As I said earlier, I know the existing customization documentation is deficient. That’s why our promise to everyone who got a PVT keyboard is that I will personally do whatever layout customization they need if it’s not easy for them. I…very much do not want to have to make the same deal for the thousands of folks who have preordered keyboards.

Er, to clarify, I will make that same deal for the thousands of folks who have preordered keyboards, which means that the documentation and tooling has to get better.

I’ve added the specific questions you have to the ticket I created earlier today for such a tutorial We need a tutorial explaining basic keymap customization · Issue #164 · keyboardio/Kaleidoscope · GitHub

If there are other questions you’d like to see answered in an intro customization tutorial, please do add them there.

1 Like

Got it. I’m sure I can come up with more, but I’ll be mostly offline until a few days after the eclipse. Then I expect to have time to devote to helping substantially with documentation.

Awesome. Have a great time.

So, I fumbled through the documentation and had a fun time discovering what I needed to do to get a (mostly-same) build as the official firmware. I’d be happy to try to spend some time writing it up or expanding on the existing documentation and listing where I pulled things from.

I also discovered some bugs in that process (such as the keymap I had being different than the original PVT firmware, and the fact that the rainbow wave led plugin didn’t have the correct default LED intensity set so it looked dull). Though I am a professional software developer, I develop in either C or Java, usually, and so the step into C++ was a little bit more confusing for me than it might otherwise have been. Despite that, I was able to fix the rainbow wave default brightness, extend the plugin to support different backlight levels (I got rid of all of the solid colors and have 4 different intensities of the rainbow wave right now, haha!), and make it so the wave effect is a bit faster (which was another thing I extended and made user-changeable). I also was able to extend @algernon’s SpaceCadetShift plugin to take a variable list of mappings and timeouts, so you can enable the SpaceCadet effect on any key, with per-key different timeouts. Useful to have square brackets and curly braces to go along with those parentheses. But I digress…

I am more than happy to help review and even write documentation, as necessary. I think a very big part of that revolves around having the exact, full Arduino sketch that ships by default available to clone, and having links and descriptions describing exactly how to do that process. Having a tutorial where you show how to remap a single key (like the butterfly or ‘any’ key) would be super helpful. It’d also be helpful to show exactly how to choose which LED pattern you want by default and show how and where to put that setting, or possible show how to disable LED effects that you don’t care about. I’m happy to help write that sort of documentation.

5 Likes

I’d be very interested in having that in the plugin, if you don’t mind sending a pull request =)

2 Likes

That’d be hugely useful. Home · keyboardio/Kaleidoscope Wiki · GitHub is probably the right place to post stuff like that.

It sounds like you were working from the head of the repo, rather than the tags for the PVT build. While I 100% agree that it would have been confusing for you, it’s also likely to have gotten you a less buggy firmware in the deal.

Official builds of the firmware get checked into this repo:

The PVT build was:

https://github.com/keyboardio/Model01-Firmware-Builds/tree/master/v1.01-PVT-BUILD

The automatically generated documentation of what was built and how it was built is here:

https://github.com/keyboardio/Model01-Firmware-Builds/blob/master/v1.01-PVT-BUILD/BUILD_DETAILS.txt

The tool that makes these builds is here:

https://github.com/keyboardio/Model01-Flashing/tree/master/firmware-builder

Just as a note, the default intensities are tuned to not draw more than 500 MA over USB. Doing otherwise, while pretty and almost always ok, is a spec violation and could cause some computers to forcibly disconnect the keyboard.

That said, I’d love a pull request to make the plugin more configurable and a writeup of how to make this change is another item that I think would go over really well.

That’s super cool.

Yes. As a PVT customer, you’re definitely getting the most painful possible experience. I’ve spent some time working on improving the basic install instructions here:

Once at least one person tells me it’s not full of lies, I’ll merge it to master.

Yes. We need a tutorial explaining basic keymap customization · Issue #164 · keyboardio/Kaleidoscope · GitHub is the open issue to track this :slight_smile:

I’d love that. And I’m happy to tech review any doc you or anyone else contributes. Thank you!

2 Likes

Alright, once I get some time I’ll take a stab at building out some documentation. I know I signed up for a painful process with the PVT program – fortunately this is the kind of stuff I love! And you’re right, I pulled everything from the head, not from the PVT tag. That’s likely my own fault and (gasp) getting used to git (I use svn and hg more often, as I use svn at work and hg for personal projects),

1 Like

In general, I think we want to encourage folks who want the latest working code to pull from master.

It’s useful to be able to rebuild the shipping firmware, but I don’t think it’s likely to be the right starting point for most folks.

(I do expect to keep the keymaps for the default firmware more stable. The PVT version had a couple of outright mistakes :/)

1 Like

No worries, I am definitely planning on sharing it back once I get it into a cleaned-up, documented state following the code standards guide. It was very much a hack-and-slash attempt that needs some cleaning up before I’d be happy with others seeing it. I’ll send a pull request once that’s done and I am more confident that it’s in a usable-to-others state. :grin:

3 Likes

As a note on the coding standard: We cribbed from Google and have been trying to adapt the standard to something that would make sense for us. If there are bits that seem…wrong, please shout.

2 Likes

25 posts were split to a new topic: Creating a keyboard remapping tutorial

Absolutely personal preference, but I really dislike 2-space indents. 4-space is where it’s at for me! It’s just a lot easier to see indentation levels. For now, I’ll astyle the source so it’s readable for me and then astyle it back before I commit. :slight_smile:

As another aside, what is everybody using for development? I have been using a combo of vim and sublime text, but I’d really like to get CLion setup and working with all of the libraries (as I use IntelliJ IDEA for most of my professional work).

1 Like

Using astyle like that is not wrong.

There’s a reason we have a house astyle invocation and automated tests for it.

I’d love to hear more about that. I’m using vim and make, though I hear good things about VS Code

1 Like