Arduboy FX library

Thought I started a thread for it so we don’t have to ‘polute’ the other threads.

The FX library is part of the Arduboy Homemade package but also available as a stand alone library here:

Creating and uploading FX data to the flash chip is now also much easier.

When using the Arduino IDE:

  • Install the Arduboy FX Arduino plugin With this plugin the FX data can be build and uploaded through the Arduino Tools menu.

For alternative methods:

  • is a Python tool that parses a special format text file and creates a C header file to include with your project and a fxdata .bin file that can be uploaded to the FX flash chip.
  • is a Python tool that uploads the fxdata .bin file.
  • is a Python GUI tool to upload hex files, flashimages and fxdata .bin file.

these 3 tools are part of the Arduboy python utilities you can grab them from there.


The ArduboyFX library is part of the Homemade package when using this package you do not need to install the library manually.

When the Homemade package is not used, the library must be downloaded and copied to the Arduino sketchbook libraries folder.


Cool. Thanks. Regarding the parameter of the following function:

void Cart::seekCommand(uint8_t command, uint24_t address)

Hope it wasn’t already discussed, but how is address comprised? Is it 16bit page number + 8bit page offset?

if page and offset are:

uint16_t page;
uint8_t offset;

then address is:

uint24_t address = (uint24_t)page << 8 | offset;

1 Like

I gave the lib a first try but I have some issues. I added my .hex file and the like to the .csv and build an image. Got this:

List Title                     Curr. Prev. Next  ProgSize DataSize SaveSize
---- ------------------------- ----- ----- ----- -------- -------- --------
0    Bootloader                    0 65535     5
1    Action Games                  5     0    10
1     SanSan                      10     5   107    23552        0        0
2    Arcade Games                107    10   112
2     1943                       112   107   229    28672        0        0
2     Ardu-Whack                 229   112   290    14336        0        0
3    Platformer Games            290   229   295
3     CastleBoy                  295   290   411    28416        0        0
4    Puzzle Games                411   295   416
4     Hangman                    416   411   488    17152        0        0
4     LATE                       488   416   604    28416        0        0
4     Minesweeper                604   488   694    21760        0        0
5    Racing Games                694   604   699
5     Ard-Drivin                 699   694   780    19456        0        0
6    RPG Games                   780   699   785
6     Rick & Morty               785   780   830    10240        0        0
7    Shooter Games               830   785   835
7     Night Raid                 835   830   911    18176        0        0
8    FPS Games                   911   835   916
8     Vault83                    916   911  1146    28416    29184        0
---- ------------------------- ----- ----- ----- -------- -------- --------
                                Page  Page  Page    Bytes    Bytes    Bytes

Image build complete with 9 Title screens, 11 Sketches, 287 Kbyte used.

In my sketch, I did this:


and later:


But it prints 0 all the time. Can you help me out?

Ah nooo… forget it. I just missed to flash my .hex again. I had an old version burned before and just flashed the flashcard binary but did not update the sketch in the progmem…

I get the following warning when compiling my code:

src/cart.h: At global scope:
src/cart.h:56:17: warning: always_inline function might not be inlinable [-Wattributes]
static void disable() __attribute__((always_inline)); // deselects external flash memory and ends the last command

Anyone knows how to fix this. I can probably just remove the attribute but obviously the intention was to always inline it. Does it work for others?

It will be fixed in the next version. You may ignore it for now.!!

I’ve did a quick updated on the public library.


Thanks. The warning is gone now but I got quite some compilation errors. I needed to add

#include <Arduboy2.h>

to cart.h. It was looking for PORTD, PORTD2 and SPDR. Maybe some AVR or SPI include file would match better.

#include <avr/io.h>

1 Like

Hmm strange I ddn’t get any errors. But you’re right I should move the Arduboy2 include from .cpp to .h

I prefere Arduboy2.h there are some macros for to enable /disable oled that use CS_PORT and CS_BIT.

Talking about these macros. I probably should make some inline functions out of them.

Another reason is that the homemade packages Arduboy2 library defines the flash chip select according to the user selected setting as Rx or SDA

That’s probably because of how #includes work.

Whenever there’s an #include, the preprocessor reads the file and dumps its contents into the place where the #include was.

If Arduboy2.h happens to be included before cart.h then there won’t be any problems.
If it hasn’t been included before cart.h then there will be errors because cart.h won’t be able to access the macros/identifiers that it needs.

This applies to every translation unit, and each .cpp file is treated as a separate translation unit.
So if one .cpp file ends up including Arduboy2.h first then it won’t have a problem, but another might include cart.h first and then that .cpp file would have a problem.

This is why it’s good practice to always reference every single .h file that a file explicitly/directly needs, regardless of whether it seems redundant.

It’s also good practice to include the minimal header that will give the feature(s) that you want.
(Which is why a lot of my code uses stddef.h - it’s the minimal file for getting size_t.)

displayOn and displayOff are functions.
Or were you thinking of something else?

I know how includes work

That’s what I ment by strange I moved the #include cart.h up and didn’t get any errors (also after flushing the files) where I expect it

I’m not turning the display on or off. But disable / deselect and enable / select the OLED display as SPI slave device. That’s quite different.

Arduboy2 Library does not have these functions as the OLED display is always selected

I used macros as I couldn’t get the always include work without warnings before

You didn’t mention that before.
That is strange.

Are you using the Arduino IDE to compile?

I know there’s usually at least some cache files in the temp directory and some in appdata.
I don’t know where those files would end up on other OSes.

You just said:

So what did you mean if you didn’t mean turning the display on and off?

The way you said it I thought you meant the Arduboy2 library had “macros for to enable /disable oled”.

Yes I do. I’ll try again later as I like to recreate errors.

Comparing with a light switch. You can turn the light on and off by flipping the lever.
By enabling and disabling I mean inserting or taking the lever out. the light can be on or off. But without the lever you can not control the light.

by disabling the OLED chipselect pin the OLED display will no longer listen to SPI data. By enabling the chipselect pin again it will listen to SPI data again.

Both the flash chip and OLED display share the same SPI bus. So only one device should be selected at a time (unless you know what you are doing :sunglasses: )

Sorry about that. I shall try to be more explicit.

I had to check because I can never remember who’s on Linux, who’s use VSCode, who’s using makefiles to compile et cetera.

(Except for @Botisaurus, I always remember he’s one of the rare people who uses PlatformIO for Arduboy programs.)

Ah, enable/disable the chip select pin.
That makes more sense.

“Explicit is better than implicit” - a golden rule of programming.
(That’s also the excuse people give for swearing at heisenbugs. :P)

1 Like

Here’s something to toy with. drawbitmap supports masked ‘sprites’ @bateske, when I drag and drop an .arduboy file onto a message it doesn’t auto play. So I’ve added the Iframe bit again.

removed iframe code (after being possessed by @bateske)

Press B to toggle show/hide position. Press and hold B to move background instead of chompies. press and hold A for single step movement. Reduced frame rate to 60fps so it runs (hopefully) smoother in ABE.

Actually it totally works and I’ve been possessed by @bateske to have it in my post here:

drawbitmap-test-2.arduboy (20.8 KB)

1 Like

Whatchu talking bout Willis, it for sure works.

1 Like

So this adds the fx functions to sprites now?

The iframes won’t always load predictably in the preview pane, not really sure why.

Good to know :+1: When I drag and dropped the .arduboy file, I just kept seeing the Fm logo (tried a couple of times)

Yep huge bitmaps can be draw as plain bitmaps or masked now. Also want to add a few other modes. like inverse and so. But first I want to add support for irregular pixel heights. so you can have tiles like 10x10 or 20x20 or so. I didn’t get that working yet.

That explains it

@bateske, you should try put the files on Arduboy, rip out the cart and reinsert it. Then you’ll know I’m not cheating :wink: