I’ve followed the instructions on the kaleidoscope wiki for windows to update my firmware, and think I know how to remap my keys using the Model 01 firmware file in examples… simple enough.
But as I’m installing/modifying files, how do I know what plugins are currently installed? I’m completely lost here. Can someone please explain the workflow behind changing the keyboard’s firmware and how the Arduino IDE relates to it? Where are all the source files currently being used; are they the “examples” in the IDE? How exactly are plugins installed? Where can I see them? How do I know how much memory they’re using vs. my keyboard’s memory limits?
I know these are a lot of questions, and don’t need/expect them to all get answered, but if someone could shed some light on this process it would really help.
Installed in the firmware, or installed for Arduino, and being available for use?
If you installed through the board manager in the Arduino IDE, then these are the plugins available (Kaleidoscope-*).
Clone the Model01-Firmware repository (or download a zip file). This is the factory firmware. Do any modifications you like, either in the Arduino IDE, or with any other editor you are familiar with. Then, open the Arduino IDE, load the sketch (the .ino file), compile and upload. That’s about it. The Arduino IDE is used for managing the libraries (somewhat), to compile, and to upload the firmware.
As far as I remember, they will be somewhere in Documents\Arduino, and wherever you cloned Model01-Firmware (probably the same location).
No, the examples are just that, examples for the various plugins. They are included with the plugin sources, mind you.
The default set of plugins come with the board manager. When you install Keyboardio support in the Arduino IDE, you also install the default set of plugins.
When you compile with the Arduino IDE, it will have small console-like window at the bottom, which will print how much space (flash & ram) the sketch uses, and what percentage of the available space that is.
Thank you for taking the time to answer my questions. Unfortunately, I’m still a bit lost; maybe an example will show what I mean. For reference, I’m currently on Windows and haven’t found the need to use Git yet, just the IDE.
Let’s say I make all kinds of changes to the firmware files and then flash my keyboard with these changes. So now I have a configuration quite different than the factory default. Then I delete the local copies of all the firmware files I’ve modified, but of course my keyboard’s firmware still has the changes. How can inspect all the changes I’ve made from the factory defaults in my keyboard? I can’t seem to find how to do that in Windows.
If you delete the sources, you can’t. Not easily. The changes you made were compiled from source code to machine code, and flashed onto the keyboard. Think of it like a recipe: from a cookbook, you take a recipe (the factory firmware), you make a few changes to better suit your taste (your modified firmware), then you cook it (compile it), and serve it to friends & family (flash it, kind of).
From the finished dish, most of the time it’s very hard to figure out what you changed, compared to the original. Even if change is obvious (different sauce, for example), the exact details are not obvious from the dish itself. You’ll only know the details if you kept the modified recipe (the modified source code).
Yes, that explanation was great. It helped me install my first package, OneShot, more to follow. Sorry for being so dense, it’s actually really simple now that I get it. So here’s my current understanding of things, at least for Windows, which may help others…
Following the wiki instructions will set you up with the IDE which points to https://raw.githubusercontent.com/keyboardio/boardsmanager/master/package_keyboardio_index.json for its KB packages and main firmware file; they aren’t actually on your local machine. You can make simple keymap changes and package installs to the firmware file by loading it from the ‘Examples’ and then flashing it onto your machine (after testing compilation of course). If you then close the IDE your firmware will of course remain modified but unless you saved a local copy of the Model01-Firmware.ino file your changes will be lost, since they only exist on the keyboard as machine code. This workflow works fine for minor changes, but if you actually want to do package development you will want to use Git to clone the package repo down and make your own changes.
All this leaves me with one worry though. Let’s say I get my firmware file configured just the way I want it and then an update comes along. How can I remain up-to-date while keeping my own modifications? I’m assuming merge conflicts are just something people learn to deal with?
You do not need to merge with the factory firmware to get most of the updates, as a lot of them come from the plugins or the core firmware. So you can opt not to merge, but hand-pick the changes you want from the factory firmware, if there are any.