Arduboy Toolset

Arduboy Toolset attempts to be an all-in-one, cross-platform aggregation of tools for working with Arduboy. Mr.Blinky’s Arduboy-Python-Utilities was used as the base for this code. It also has a cart builder so you can add + edit games on your Arduboy, and a basic .arduboy package creator/editor. It is a standalone application that does not require additional installation.


  • Load the flashcart off your Arduboy FX and edit games/categories or add new ones.
  • Save or flash the edited flashcart directly back to your Arduboy FX
  • Upload and backup program sketches
  • Upload and backup flashcart images
  • Backup, restore, and delete EEPROM
  • Create .arduboy packages
  • Convert images to code or FX data
  • Flash development FX data at the same time as your sketch for testing

Thank you to:

  • @Mr.Blinky for all his help with the cart formatting and for writing the original code. I couldn’t have done it without you
  • @filmote for all their input on the toolset (and for creating + updating the cart builder website, which I utilize)
  • @Pharap for always being willing to help and their strong determination to do things right
  • @Ard_Flamingo for fixing the MacOS build with their wisdom
  • @brow1067 for their help on some technical aspects + arduboy packages
  • @acedent and @ZennDev1337 for their suggestions and support
  • @Blixten for the various important bug reports

Notes on Arduboy Library

If you ever wanted to make your own Arduboy tools (in Python), this toolset can make it much easier. The arduboy folder contains a python module with structured, organized functions and classes to help with nearly every aspect of working with Arduboy, from finding devices to flashing sketches and fx data. It also has utilities for decompiling and recompiling the flashcart, converting images back and forth between Arduboy format, parsing .arduboy files, and creating automatic title cards (text only). It has a few dependencies (pyserial, PILlow, demjson3, intelhex, slugify) but is completely separate from any GUI code, making it an ideal drop-in library for Arduboy projects. There’s tons of comments and I plan on finishing up the type annotations soon (I think they’re mostly done)

How to use the cart builder (general): Arduboy Toolset - #27 by haloopdy
How to add a game: Arduboy Toolset - #147 by haloopdy
Updated v4 schema + package editor: Arduboy Toolset - #161 by haloopdy

Latest release: github - arduboy_toolset/release

(Releases for Windows, MacOS, and Linux (IDK the minimum kernel!). The .dmg release for MacOS yells at you about signing or updating but if you try again by ctrl-clicking and opening from there, it should work)


uhh i kinda like the idea of one complete Toolset. Well done

Definitely something i will use in the future. :hearts:


Thank you very much!

I don’t think I’ll ever implement a custom compiler, so you’ll still need to use Arduino tools to compile and such. And I probably won’t mess with burning fuses, so no flashing custom bootloaders either. But I do want to add other things I hope are useful! There’s still neat things I haven’t reimplemented from Mr.Blinky’s utilities, and I still want a way to quickly manage flash carts locally.

i never used the Arduino Toolset at all to compile ^^
i write my games in Rust :crab:
If you struggle with certain implementations from Mr.Blinky’s utilities i’m maybe able to help you ^^

just ask :smiling_face:

Oh hang on, is that possible? I’ve been hoping to be able to write some games in rust, have you made a post somewhere detailing how to do that? Are you just using unsafe blocks to call out to the arduboy libraries and then like… idk, is one of the rust targets relevant for atmega? If there isn’t a post yet on programming for Arduboy with rust you should make one!!

i will later on but i can share it here for the first time ^^
i finished today but i don’t have all the functions from the Arduboy2 library

for questions you can reach out to me via discord: zenndev


WOwowow! That is amazing! I’ve been hoping for something like this ever since I found out about Arduboy!

maybe i will post tomorrow about that ^^
yes most of the hardware calls are just in save blocks wrapped unsafe calls but i try to port most of the logic to rust

i bought the arduboy, used the arduino ide twice, and decided, nope i need to do it in rust ^^

i wrote a little post about it ^^

1 Like


With lots of help from @Mr.Blinky, I’m very close to finishing the first version of a rudimentary cart modifier. You’ll be able to directly load the cart off the arduboy right into the editor, make changes, add/remove/reorder games, then flash the cart right back. In the future, I plan on calculating minimum flash requirements so reading + writing will be a lot faster, especially if you are only adding games to the end.

The toolset also now has a very robust “arduboy” module with tons of organized functions and classes that can perform nearly all operations from the GUI + CLI, so if you wanted to make your own tools, it’ll be a lot easier! As long as you want to use python…

It doesn’t look like much, I’m not one for fancy UIs, but here’s how it’s looking so far. It reads, decompiles the flash, you can make all the modifications + add games + categories, and recompile + flash already. I just want to make things easier to use before I release:


If I saw it right, games like Dark & Under II have a bin file and a hex file. Will you add support for this type of game?
I would love to see an easy solution to upload larger games.

Oh yeah it’s already supported! See the three buttons and three numbers? First is program, then data, then save. And I’m currently working on a way for it to pull all that from the .arduboy file, I just have to see how many different formats people have and support the major ones.

One of my main goals for this thing was to be able to easily manage FX games and not lose your FX save data (which I guess almost nothing uses right now, but I figure it might start happening!). If you use the cart builder website, it won’t have any idea about your FX saves, and so they get overwritten if you build a new cart with new games. This one won’t do that, since it modifies it directly, preserving all the data.

1 Like

I’m really excited about it.

1 Like

Will it work on my Mac ? That was a joke

Nice work. I wonder if you used a treeview, you could represent the cart / categories / game hierarchy and allow users to drag and drop within the tree to reorder.


It should! It’s still just python, and I do want to make a standalone release for Mac (without dependencies)… I just don’t have one! If someone wants to make a release for me, I’ve simplified the process to hopefully just a few commands. But that can come later. I might just rent a virtual Mac from one of those VM thingies eventually.

Ah I hope you don’t mind, I specifically chose not to use a tree view to better represent how it is stored on the flashcart (and to make literally everything easier). When I eventually add the mode where only edits are written, I want it to be obvious WHY your random edit in the middle of the cart caused nearly a full rewrite even though you only updated one game. Also, what you get out of a treeview (reorderable categories + easier navigation) is so greatly overshadowed by the added complexity of a treeview (even for the end user) that I figured… well it’ll be one of those things I’ll add if I absolutely have to lol. I’m going to have controls to move categories around; I figure it’ll be such an infrequent use case that having it be hidden away in the menu or otherwise be slightly clunky won’t be too much of an issue. We’ll see though, I don’t like saying I “won’t do things” when I don’t know the shortcomings in people’s workflows.

If you’re worried about being able to find games in a giant list, there’s a search feature (and it’s mapped to Ctrl-F for sanity). And there’s a quick “repeat search” feature so you can quickly jump through all the instances of like “miner” or whatever.

1 Like

Looks great!
If you are strongly opposed to the tree view… perhaps consider each Category label as a new tab/ page, so that the User can move horizontally, as well as vertically through the list. This behaviour matches on device experience and the Cart site; most importantly it makes navigation faster with a 2nd dimension.

I don’t think most Users actually care how it works (a linear sequence of data)… just that it works conveniently… :wink:

1 Like

Feature Request:

My biggest issue with the FX, is I can never remember/ find what category a game is under! :eyes:
Would love every Cart to have a special ‘Search’ app. It should be dynamically generated for the Cart contents. It should have a compact list view per category, to quickly browse / page through. It should also support a smart alphabetic ‘find’, where a few characters may be entered to reveal the location of a named game. Bonus points if the game can then be launched… but I suspect that might be a firmware requirement (@Mr.Blinky)?

That would work as well!

Thank you!

Show excuses

I’ll have to see how it goes, with how the tool is meant to work. Hopefully it’ll make more sense when it gets used; I know having a more obvious layout is better for initial ease of use, I just worry that more complicated UIs will get in the way of what people actually normally do. I know it “feels” better to have a fancy layout, but consider… how often do people ACTUALLY move games between categories, or move categories around. I assume that if the existing cart format really doesn’t do it for you, you’ll create a new one. And if you want to reorder categories to put some of your favorites up front, I figure you’ll do that once, not every time you add a game lol. I know I’m spending a lot of time defending my decision to stick with a linear view, which means it’s probably a bad idea, I just… have opinions on UIs lol.

I feel strongly that the most common use case will be adding games or updating existing ones, both of which this particular layout supports very well with search features to find particular games, and the ability to insert games anywhere in the list. But again I’m not opposed to alternate layouts, I just… they usually get in the way for me lol. If this becomes more of a community tool than a personal tool I will definitely be easy to sway by the majority lol.

Agh, all the feedback so far has been “needs a treeview”, that probably means I should seriously consider it. Let me get other things done first, I’ll definitely add it to the list of possible enhancements. Sorry for making lots of excuses lol

And I should admit that it’s a flaw of mine too: I always focus on what I think are the most functional features first before spending time on fancy UI stuff. This often means the stuff I make never ends up having general convenience features that take a significant time to implement since there’s always something easier that’s worth more to me. If you do end up liking the tool, please keep pushing me if you want certain features! I’m OK with that!

Ah I’m not even sure how I’d do that. Maybe a precompiled app that reads from FX data, and I make the app store the dynamic FX data and the static program? I’ll have to consider how to do it and how useful it’d be; like you implied, unless it can launch it, IDK how useful it’ll be to just find it. But that’s a cool idea!

Edit: OK I make absolutely no guarantees on this working even a little bit, I have tons more testing to do. But since I was asked about it, you could try it out here: GitHub - randomouscrap98/arduboy_toolset at v0.2. Please be careful, I make frequent commits to the repo and they may sometimes be broken. You can run the file directly, I honestly don’t know if it launches properly from the main menu (still part of my testing stuff for later). Again, I don’t take responsibility for any lost data! It’s missing a lot of features I know people will ask for too, like reading all the data out of arduboy files and not crashing when there’s no image (I’m going to auto-generate one based on the title eventually) and a bunch of other stuff.