Preparing plugins for 1.0.0: Looking for documentation reviewers

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

Then build on that by adding one plugin (I’d recommend starting with OneShot, and show both how to do it globally and how to do it for individual modifiers).

Hah! Great minds! I just successfully built a sketch with OneShot to use in the tutorial docs, and went searching for a thread on OneShot because I have some questions. It’s weird typing like this, but not chording any more is going to be much easier on my thumbs. :slight_smile:

2 Likes

After taking a look, SpaceCadet is actually a superset of DualUse now, as far as I can tell. I made SpaceCadet work so you can apply per-key and global timeouts to the functions, and you can actually map any key to any other key (you aren’t limited to the certain modifiers). Of course, it doesn’t have the layer support, at least from an initial glance, but it may still support that. Personally, I’d rather have the main keymap separate, and then define my overrides like you can do in SpaceCadet, but I know others would have the opposite thought.

The two plugins definitely have a lot of overlapping functionality, but I am not sure if they have the same use case. DualUse looks to be a more powerful plugin in concept, with the keymap integration, though SpaceCadet is currently more extensible, but just initialized differently (you can map any defined key to any other defined key, and have separate per-key timeouts). Effectively, they are the same, but you have more control over end behavior with SpaceCadet. If you want to define your mappings and overrides in the keymap, use the DualUse style, and if you want to have an explicit list of overrides, you can use SpaceCadet. As I said, I prefer the explicit nature of mapping one key to another, so I am going to use SpaceCadet. You can definitely implement the SpaceCadet default Shift/Parens with DualUse if you are willing to change the keymap (and assuming you are using DualUse, you are likely changing the keymap), but you can also likely implement anything you wanted to do in DualUse with SpaceCadet (I am unsure about the layer switching, as I don’t use that, but I assume it’d be possible).

Even though they implement similar functionality, I don’t think it hurts to have both options, and I don’t see a reason that they’d need to be combined. Of course, if it is desired that they be combined, I wouldn’t mind implementing the DualUse keymap logic into SpaceCadet (though I sort of like the DualUse name more, so I’d combine and rename). :grin:

2 Likes

Just realised that there was one small, but important difference between DualUse and SpaceCadet: when the secondary action triggers, DualUse did not trigger the first action, while SpaceCadet did. At least, that’s how it worked before @bagels’ changes, which, by the looks of it, changed things, and the primary action is only held when the secondary explicitly says so.

In other words, the subtle difference is no more, yet, both plugins work the way they are supposed to. I do not think merging the functionality is feasible, rebuilding DualUse on top of SpaceCadet seems like a big task for little gain. But if anyone, @bagels or someone else, wants to have a go at it, I’m not going to stand in the way. :slight_smile:

1 Like

Has someone tested the example code for the Leader plugin? I’m getting compilation errors.

In file included from C:\Users\droid\AppData\Local\Arduino15\packages\keyboardio\hardware\avr\1.19.0\libraries\Kaleidoscope-Leader\src/Kaleidoscope-Leader.h:21:0,

                 from C:\localUserProfile\droid\Repositories\kb\Model01-Firmware\Model01-Firmware.ino:74:

C:\Users\droid\AppData\Local\Arduino15\packages\keyboardio\hardware\avr\1.19.0\libraries\Kaleidoscope-Leader\src/Kaleidoscope/Leader.h:29:61: error: too many initializers for 'Key'

 #define LEADER_DICT(...) { __VA_ARGS__, {{Key_NoKey}, NULL} }

                                                             ^

C:\localUserProfile\droid\Repositories\kb\Model01-Firmware\Model01-Firmware.ino:506:3: note: in expansion of macro 'LEADER_DICT'

   LEADER_DICT({LEADER_SEQ(LEAD(0), Key_A), leaderA});

   ^

C:\Users\droid\AppData\Local\Arduino15\packages\keyboardio\hardware\avr\1.19.0\libraries\Kaleidoscope-Leader\src/Kaleidoscope/Leader.h:29:61: error: braces around scalar initializer for type 'kaleidoscope::Leader::action_t {aka void (*)(unsigned char)}'

 #define LEADER_DICT(...) { __VA_ARGS__, {{Key_NoKey}, NULL} }

                                                             ^

C:\localUserProfile\droid\Repositories\kb\Model01-Firmware\Model01-Firmware.ino:506:3: note: in expansion of macro 'LEADER_DICT'

   LEADER_DICT({LEADER_SEQ(LEAD(0), Key_A), leaderA});

   ^

Edit: Also, it was a bit confusing to figure out what that “magic number” in “LEAD(0)” was supposed to mean.
It would be nice if the example code actually referred to the examples used to describe the use case of the plugin (I know, it’s not easy to implement since it’s using the Unicode plugin, which doesn’t work without further configuration).