I found a strange problem with my Model 100.
Sometimes (hard to say, roughly in 10 % of the cases) after starting up the computer, the keyboard swallows some keystrokes, others are repeated endlessly until I press another (or the same) key.
For demonstration I “recorded” some keystrokes. In each line I entered all characters from a-z and then from A-Z (and stopped if some key started repeating endlessly).
But you need to help me a bit here. There are several things I don’t understand yet about Kaleidoscope.
Since I use some features not available in Chrysalis, I am building my own firmware by modifying a Model100.ino file.
Is this .ino file considered being part of the firmware? That means, should I pull some changes of the “default” .ino file from time to time into my local copy I use for building the firmware? How is this .ino file related to the actual firmware?
I am using the Arduino IDE for building my firmware. I do this, because it was the only description I found for doing so. But I totally don’t understand what I am doing here.
I opened the example Model100 (sketch?) with it. That is the one I modified. But was this only the .ino file? What about the actual firmware? Where is this coming from? I found the ~/.arduino15/packages/keyboardio/hardware/gd32/1.99.7/libraries/Kaleidoscope directory (with lots of seemingly related sibling directories). I assume this is the firmware the Arduino IDE uses. How is this different from the firmware I can get from GitHub - keyboardio/Kaleidoscope: Firmware for the Keyboardio Model 01 and other keyboards with AVR or ARM MCUs.? If a new release is created in github, will this release automatically end up in this directory? Can I influence this somehow? For example if for some reason I do not want to jump to the newest version of the firmware and would like to stick to an older one.
You write about version 0.91.0. That is the version I see in Chrysalis when looking for a firmware update. But the Kaleidoscope on github (and the above mentioned arduino directory) have a current version number of 1.99.7. Why this different version numbers? How are they related?
When I am building mv own firmware and install it (via Chrysalis) it ends up having a version number of 0.0.0. That means I have no indicator what actual firmware version I am using. What do I have to do to get the actual version number (preferably with a custom suffix indicating my changes to the .ino file).
How can I build my firmware without using the Arduino IDE?
Sorry for these mostly stupid questions, but I am totally new to these firmware things and struggle to understand it fully.
Not stupid questions. The 0.0.0 version has always seemed odd to me too. Sure a custom sketch is not exactly the same as the versioned firmware, but it is based on a version.
Does the Arduino IDE automatically pull new versions? I’m not sure, but if you look at Tools | Board: "Keyboardio Model 100" | Board Manager and choose Updatable under Type you will be able to do it manually if there’s a new version. I don’t think the updates happen as quickly as with Chrysalis.
Edit: Looking at the Chrysalis repo just now it seems that things have changed recently. Before the Chrysalis version was updated first, but now it seems that the Kaleidoscope code is the canonical version, which I suppose means 1.99.7 is the latest.
Yes. The firmware is a combination of the sketch (the .ino file), and all of its dependencies: Kaleidoscope, the Arduino core used, KeyboardioHID, and any other library or third-party plugin you may pull in.
That depends whether you want those changes or not. It’s perfectly fine to not have anything in common with the default firmware. (Mine for example, has no relation; there are common plugins, but that’s about it.)
0.91.0 is the version of Chrysalis-Firmware-Bundle. The version is unrelated to Kaleidoscope. We version them independently so that they can be released and managed separately: we usually release the firmware bundle more often than Kaleidoscope. The firmware bundle also depends on the Arduino core (ArduinoCore-GD32-Keyboardio in case of the Model100).
So, as I wrote above, the relation is that Chrysalis-Firmware-Bundle is at the top, that’s what we build the firmware from. It depends on Kaleidoscope (the main firmware library, think of it as a framework of sorts), which in turn depends on KeyboardioHID (the HID implementation we use), and the appropriate Arduino Core (the aforementioned ArduinoCore-GD32-Keyboard for the Model100, and Kaleidoscope-Bundle-Keyboardio for previous, AVR-based keyboards).
The tooling for the official builds - as of 0.91.0 - pulls in a specific git commit for Kaleidoscope, and the latest git head for the Arduino Core, along with whatever version of KeyboardioHID the core itself pulls in.
Yes, it’s a bit complicated.
The version is set via the FirmwareVersion plugin. If you define KALEIDOSCOPE_FIRMWARE_VERSION to a string before including the plugin’s header in your sketch, then you can set a custom version.
If you derive your sketch from the official firmware, and intend to follow it, then I guess it makes sense to set that version to something like 0.91.0-hupfdule.1, and bump it whenever you feel like it. If you’re using CLI tools to build the firmware, you may be able to set things up so that the version becomes a git sha or something.
If you want to see a standalone sketch, here you can find mine. I build it using command line tools. make setup will set things up, and make compiles it. There are many ways to set things up, however.
On Linux - and likely macOS -, the easiest is probably to start with the Chrysalis-Firmware-Bundle repository. make setup will do the necessary steps to install stuff, make update will update dependencies, and make will compile all firmware. make Keyboardio/Model100 will only compile firmware for the Model100. It does require arduino-cli to be available, but does everything else apart from that.
No, the firmware bundle is still versioned independently. We just rearranged things so that rather than having two copies of the firmware (one in the bundle, one in Kaleidoscope to serve as an example in the Arduino IDE), we only have one: the one in Kaleidoscope. This rearrangement does not affect how things are versioned, it’s merely to eliminate the problem of the two copies growing out of sync.
Totally forgot in the wall of text above, but the actual fix for the problem is in the Arduino Core and Kaleidoscope. So both should be updated. It’s been a while I used the Arduino IDE, I have no idea what to put where in there to use the latest, git head versions of the core & Kaleidoscope.
We really need to sit down and document these processes, the repos in play, and how to update them via the Arduino IDE or otherwise.
The release process for the Arduino board support package for the Model 100 is separate from the one for either Kaleidoscope or Chrysalis-Firmware-Bundle, and sometimes lags. This means that if you use the Arduino IDE, you might get an out-of-date GD32 core or Kaleidoscope library compared to the firmware that’s delivered in Chrysalis. Though typically, the “release” Arduino BSP is a release version of Kaleidoscope.
This is admittedly not a great experience, especially because EEPROM layout changes can result in scrambled keymaps. We’d like to improve that in the future. This might involve making sure that BSP releases are synchronized to Chrysalis-Firmware-Bundle releases.
At the moment, the best way to get the most up-to-date firmware for custom sketches is to use the command line build process. Start with a checked-out copy of the Kaleidoscope repository, and base your sketch on the sketch in the latest Chrysalis-Firmware-Bundle. You need to make sure that the BSP in Kaleidoscope is up-to-date, by running make update (if you had run make setup long enough in the past).