Preparing plugins for 1.0.0: Looking for documentation reviewers

[jesse]

@bagels

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.

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

@bagels

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.

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:

GitHub - keyboardio/Factory-Firmware-Builds: Built copies of factory firmware...

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

@bagels

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

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.

@bagels

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…

That’s super cool.

@bagels

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.

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:

GitHub - keyboardio/Model01-Firmware at readme-and-env

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

@bagels

Having a tutorial where you show how to remap a single key (like the butterfly or ‘any’ key) would be super helpful.

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

@bagels

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.

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