Building the firmware

I’ve just started toying around with building the firmware, and I would like to help make the process of building it a bit less painful.
I’m a fairly seasoned developer with lots of experience with C++ development and maintaining build systems, but have never worked with Arduinos and have rather limited experience with embedded systems.

The first question I’ve got to ask: What is going to become the “main firmware”? I know @algernon is working on plugins to the firmware, and @jesse has obviously been developing firmware. But how are these and other peoples efforts going to be combined?

I’ve managed to get the “master” firmware to build on my Arch box, but I had to make extensive changes to the makefile, and also fix a few things in the code that avr-g++ 6.2 (which is what Arch ships) will not accept. So where should these kinds of efforts be directed?

The factory firmware will be keyboardio/KeyboardioFirmware.

By using the Arduino tools (either the IDE, or the CLI tools), and creating a firmware Sketch, that pulls in the bits and pieces you want. Think of the core firmware as a library, one that makes it very easy to build your own firmware. Because essentially, that is what it is. The factory firmware is literally in the examples directory. :slight_smile:

I have my planned layout up on GitHub, that is a fairly complex example of how to pull things together. (It currently does not work, and lots of things will change, but the general idea is likely to remain the same)

Ummm… it is meant to be built with Arduino tools, not “plain” avr-g++. Without the Arduino tools, it will be a huge pain in the backside to build it, and even more so to pull in any plugins.

GitHub issue / PR against either the core firmware library, or Akela, or whatever else you’ll end up touching in the future.

1 Like

Hey @lars,

Thanks so much!

So, @algernon is working on the same “main” firmware that I am. is the canonical firmware for the Model 01.

Pull requests against that repo are the right way to contribute.

The canonical toolchain that the build must work with is the toolchain shipped as part of v1.6.x of the Arduino IDE, but broader compatibility is a win. That toolchain is consistent across Linux, Windows and OS X.

The Makefile is, as you can tell, somewhat of a hack, though other than paths, it’s been known to work on multiple Linux distributions and on OSX. What sorts of changes did you have to make?

(Feel free just to submit GitHub PRs, rather than explaining here, of course)

Well, my aim is really to make it easier to work with the firmware, so making it easy to build on more systems, and making the code more standards compliant. I will also attempt to make Arch User Repository packages wherever relevant (the ArduinoBoards part seem like a prime candidate, not so sure about other things yet).

The changes I had to make to the makefile mainly has to do with paths, since on Arch there is recent versions of the Arduino tools in the repos. I’m going to have to think a bit more about how the makefile can be made more generic.

The other issue I have had is that the KeyboardioHID library uses non-standard C++. There are a bunch of unions which contain “flexible arrays”, e.g. “uint8_t whole8[]”. This is a construct that GCC no longer allows (it is legal in C99, but not in C++, from what I understand). Then again it appears that these whole8/whole16/whole32 members are never actually used. Are they there for a reason, or can I submit a PR which removes them?


In general, standards-compliant is great. I’m a fan of standards-compliant. But embedded stuff is weird, and there are often other considerations that can be more important. (Mostly, related to clock cycle or memory efficiency.)

ArduinoBoards is the Arduino definition for the Model 01’s core. It should include all of our special dependency libraries. (Currently included as submodules in the repo.) has some details on how those work.

Yup. Our paths have been far too hard-coded up to now. Does arch’s arduino-builder use the Arduino GCC version or is it trying to build arduino with a completely different compiler version?

If so, I’m scared and impressed.

My recollection is that that’s something we inherited, rather than something I wrote, though the git history can confirm or deny that. I’m happy for you to submit a PR to kill it, but I’m going to want to check carefully before I merge it.


When I install Arduino dev environment on Arch I get version 6.2.0 of avr-gcc. Don’t really know much more about this. But I’ll be a guinea-pig of using new GCC when the Model01 ships!

A motivation for changing this is that at some stage a new Arduino package with update GCC will ship, and then you will get bitten by this regardless. Having me “on the frontlines” will let you get a heads up whenever something is not “future-proof”. :slight_smile:

1 Like

Interesting. I’ll install Arch in a VM, and give it a go. Would be nice to be able to compile with new tools too, before the keyboard ships.

If you’re not a seasoned arch user I can recommend Antergos, which is arch, but easier to install.

Oh, and I also uploaded an AUR package yesterday. “arduino-keyboardio-boards-git”, which will install the Arduino-Boards repo on your installation. Although, currently it installs my fork of said package, which removes the flexible array construct from the code.

PR for my fork is here:, and I put a comment in there about another way of solving the flexible array problem.

1 Like

Installed Arch, and started to tinker with build stuff. So far, I managed to compile all of Akela using the flexible array fix by @lars. Still have to tinker a bit with the build system to make it work with both a locally installed Arduino, and with a system-wide install like Arch’s.

One of the major problems is that Arch installs the arduino hardware bits as hardware/archlinux-arduino, while the Model01 specs depend on arduino. The easiest fix there that I found was to symlink that dir to arduino, but I’ll see if there are better, less hacky options.

Apart from this, the changes to the Makefiles were reasonably small, but I need to clean them up quite a bit.

Yeah, in my AUR package I actually patched the board.txt file to say archlinux-arduino instead of arduino… I can’t quite understand why Arch would call their directory archlinux-arduino, tbh.

As for the Makefiles, I was going to look into that next… I might give using CMake a whirl, since I kinda like it better than pure Makefiles.

CMake would be an overkill here, I think. I’m down to about 3 lines changed right now, and a couple of arguments on the command-line, and things work on both Arch, and the “traditional” Arduino install. Though, CMake would make some things easier, but I don’t think it adds enough convenience to justify the additional requirement to install it too. For us, seasoned Linux users, that’s no big deal. But for someone on Windows, with very little programming knowledge, the less tools needed, the better. On the other hand, the Arduino IDE is still there…

Most likely to make it clear that it is not stock Arduino, to avoid Arch users filing weird issues against projects that work with whatever Arduino ships with. (There may be licensing/trademark issues at hand too, I have not looked into that.)

Took a few more lines to make it reasonable, pull request here. Works for me on both Arch, and using the standalone Arduino install, but further testing, especially by someone familiar with Arch (hi @lars!), would be more than welcome!

The patch is not pretty, mind you.

1 Like

Both pull requests now merged. Eventually, we’ll do better for making building with the makefile easier

Great, the AUR package (for the Arduino-Boards repo) now builds with the official repo, instead of my fork.

Two questions, that are hopefully correctly related to this topic.

  1. Will there be an easy (read idiot friendly, hopefully GUI) way to build the firmware with extra plugins and update the keyboard?
  2. Will there be an easy way to update the layout?

There already is: the Arduino IDE. The plugins are not the easiest to install (read: you have to run a script on Linux/MacOS, no easy solution for Windows yet), but I’ll be writing up some guides soon, with screenshots and the like. And once keyboards start reaching eager hands, the documentation speed will dramatically increase, because I’ll have feedback from users who aren’t me =) (At least, as far as plugin docs go, that is).

We are working on a way to do that, without having to compile anything. I’m not sure if it will be ready by the time the keyboard ships, but it is definitely coming.

wrt Windows (10), might (ubuntu’s) bash shell support provide an easyish solution?

Possibly. But a batch file would likely do the job, too. I just need someone willing to write one =)

All it needs to do is copy (& overwrite, if it exists) the directories from the lib/ directory of the Akela plugin collection to a libraries directory under the default Arduino Sketch path. Same for the hardware directory. That’s about it. Doing this makes the plugins and the KeyboardioFirmware easily available for the Arduino IDE.

I think I’d be cool curating Akela plugins and other plugins into the core arduino-boards. That’d dramatically cut down the hassle.

1 Like