Preparing plugins for 1.0.0: Looking for documentation reviewers

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

I might try to get CLion setup. I’d be happy to share configs with that, if I get it fully working. JetBrains actually has free licenses for OpenSource project contributors – https://www.jetbrains.com/buy/opensource/ The only thing I don’t know about is if this would fall under “commercially supported”, but since kaleidescope is able to be used by other companies, too, it might get by it.

I know astyle can be used that way – I really need to look into implementing post-pull and pre-commit hooks to format the code in the way I want it to be. If I get those working, I’ll contribute those notes to the community, as well.

Thanks so much!
We also need to get pre-commit hooks in place to run our style and smoke tests.

1 Like

Emacs (Spacemacs, in particular) for everything. =)

1 Like

Got it! I’ve added a couple notes to the README.

1 Like

ADMIN: I moved posts about creating a keyboard remapping tutorial to a new topic. You can find it here: Creating a keyboard remapping tutorial

1 Like

Does it make sense to have separate SpaceCadet & DualUse plugins? Especially now that SpaceCadet has been extended, they seem to have overlapping functionality.

SpaceCadet is nice because the user can just add the plugin & not need to change the keymap, but perhaps the plugin should just be a wrapper of calls to DualUse?

There used to be subtle differences between the two, but perhaps there isn’t that much of a difference by now. Will have to check at some point.

1 Like

I can also take a look at the DualUse and SpaceCadet plugins. Maybe see if I can reconcile them, as I was the one who extended SpaceCadet.

2 Likes