The basics in 2023

Just got an ArduBoyFX at PRGE a couple weeks ago. It’s fun!

It seems like Arduboy FX has a very long and complex history (and even longer considering arduino), but is there a real technical summary of the device and its capabilities? Something suitable for folks coming in new to the platform? As in, haven’t played at all with arduino.

I’m an Android developer, say what you want us JVM nerds, but I’ve done some pc-assembly and C/C++ back in the day. I’m still trying to wrap my head around things though. I’m slowly building up an understanding but it’s usually just lucky searches or random thoughts. And I mean basics so basic y’all probably can’t imagine folks wondering.

Of course now I can’t think of them all, but I’ll put up those I can recall:

eeprom vs flash vs FX flash (good details in this thread – Which are available to programs?

When a program is “I am at 69% RAM used and 80% flash” what are those values referring to? How do you tell if what you’re developing is starting to hit limits?

I’m surprised how tricky adding new software is. It’s probably simple once you get it, but I was sort of hoping for an online image builder, or mass downloads, or something. So while there are nice collections and nice tools like Arduboy Toolset it doesn’t seem like there’s a comprehensive thing to handhold babies like me. An app store, if you will, that lets you customize everything, downloading new bits as needed.

Is the ArduboyFX Loader open source? Can it be changed?

Thanks,

Trin.

Hey, I see that @Pharap is probably going to reply to most if not all of your post here pretty soon, but I wanted to give my thoughts on specifically Arduboy Toolset. I hope it doesn’t sound like excuses, I’m sorry!

I made the toolset as a fun side project, and specifically chose not to make it on the web because web development crushes my soul (I have to do it professionally and I hate it lol). I wasn’t planning on it being “the” toolset for everyone to use, so I didn’t focus on ease of use for newcomers. I’m really sorry if it’s tough to use.

It sounds like you want to be able to browse + add more games. @filmote maintains an excellent website where you actually can mass-download the “full cart” of basically all the games, then you can use Arduboy toolset to flash it to your fx (use the flashcart tab): Cart Builder

Hope that helps! Pharap will probably have lots of answers for you!

3 Likes

My account is going to be 8 years old this year and I wasn’t even here from the very beginning like some were. That’s pretty scary to think about…

Odds are you won’t need to write any assembly unless you’re really struggling for space and/or doing something very advanced or intensive. Modern compilers are very good at optimising, and Arduboy games can take advantage of whole-program optimisation in ways that programs that depend on external dynamically-linked libraries can’t.

Both, or just the one?

Either way, C++ is the only one you need to worry about for Arduboy, and it’s changed quite a bit over the last decade or so, so you’d probably be best off tackling it tabula rasa anyway - forget what they taught you back then and learn what’s good practice now.

(Personally I recommend this website. Though note that not everything they cover is relevant for Arduboy development. E.g. there’s no C++ standard library or exceptions in most Arduino environments.)

You’d be surprised. I still just about remember what it was like to not know the difference between a kilobyte and a megabyte, let alone having never written a line of code.

All three, plus the one you missed out: RAM, but they have different characteristics.

  • RAM (Random Access Memory)
    • 2,560 bytes (2.5 KB)
    • Readable and writable
    • Volatile - contents are erased when the device loses power
    • Used for global variables, some local variables, and the call stack
    • Notably the Arduboy2 library reserves 1,024 bytes (1 KB) for the frame buffer, so actual working memory is potentially lower
  • Flash, or more commonly ‘progmem’ (a portmanteau of ‘program memory’)
    • 32,768 bytes (32 KB)
      • A classic Arduboy has 4,096 bytes (4 KB) reserved for the bootloader, leaving 28,672 bytes (28 KB) for user code
      • An ArduboyFX has 3,072 bytes (3 KB) reserved for the bootloader, leaving 29,696 bytes (29 KB) for user code
    • Read-only for user code, writable in bootloader mode (which is how uploading programs works)
    • Non-volatile - contents remain even when the power is cut
    • The only kind of memory that can store machine code instructions
    • Can be used for read-only (const or constexpr) global variables, but storing a variable in progmem requires that it be explicitly marked with the PROGMEM macro, and reading a variable stored in progmem requires the use of special macros or functions
    • Has a 10,000 write cycle limit, but games are uploaded infrequently enough that this isn’t a concern
  • EEPROM (Electrically Erasable Programmable Memory)
    • 1,024 bytes (1 KB)
    • Readable and writable
    • Non-volatile - contents remain even when the power is cut
    • The first 16 bytes are reserved for user settings like a mute toggle (see Arduboy2 documentation for more info)
    • Used primarily for saving game data
    • Can be used by any game, so games using the same addresses is to be expected
    • It’s best practice to select a semi-random save address to try to minimise clashes and to act as rudimentary wear-levelling
    • Has a 100,000 write cycle limit, so only write to it when you actually need to save the user’s data
  • FX Flash
    • 16,777,216 bytes (16 MB)
    • Readable and writable, with caveats
      • Can only write 1 bits, to write a 0 bit a whole page must be erased
      • Pages are 4,096 bytes (4 KB)
    • Used for storing games that aren’t currently loaded onto the device
    • Can store data that is usable by games
    • Interacted with via the FX library

(I really ought to start bookmarking these explanations so I don’t end up writing the same thing every few months.)

RAM is RAM, the read-write memory occupied by global variables, the call stack, and some local variables. The best way to reduce RAM usage is to either use fewer global variables or smaller global variables.

Putting read-only variables into progmem effectively moves them from RAM to progmem, which is a good way to reduce RAM usage at the expense of progmem usage.

Flash is flash, or ‘progmem’, the read-only memory used by machine code and designated global variables. The best way to reduce progmem usage is to either use fewer progmem-stored global variables, smaller progmem-stored global variables, to use less code, or to generally use more space-efficient techniques.

On an FX, one can move read-only variables onto the FX chip to free up space in progmem, but machine code can only be kept in progmem, so you can’t move things like functions onto the FX chip.

The closest thing to that description is this:

The thing is though, it’s impossible for any single collection to ever be truly complete because people can publish games whenever and wherever they want.

There has been at least one case where someone was publishing games on their personal blog and it went unnoticed for quite a while.

I don’t know what you’re referring to by ‘ArduboyFX Loader’, but the vast majority of games and tools are published under open source licences, so odds are the answer is ‘yes’.

3 Likes

I think the @TrinOKor means the python scripts created by @Mr.Blinky and incorporated into the toolkit by @haloopdy. If so, they are released on a CC0 1.0 Universal licence.

The education lessons in this category are a great way to start. Lessons - Arduboy

If you are a programmer you will smash through the content in no time. But it will cover graphics and sounds.

1 Like

The ‘Arduboy FX loader’ refers to the custom bootloader of the Arduboy FX and it is open source. It is licenced under the MIT licence.

The bootloader is a protected program located at the end of the Atmega32u4 (the MCU) 32K flash memory and is responsible for uploading user programs over USB and selecting and programming user programs from the FX chip (external flash).

The bootloader can only be changed using a special hardware programmer called an ISP programmer. It is normally not required to change/update the bootloader.

When the Arduboy FX powers up you are presented with the ‘FX loader screen’ aka ‘bootloader screen’. This screen is stored on the FX chip and can be customized by the user by editing a flash image with one of the available tools.

History of FX tools:

1 Like

And soon, someone will integrate WebUSB into the cart site for a truly seamless experience?

2 Likes

In addition to the responses already given, it’s helpful to know that the Arduboy is essentially a repackaged Arduino Leonardo with a display, buttons, speaker, RGB LED and rechargeable battery added.

You can therefore use much of the Arduino documentation as a reference, and of course, the Arduino IDE for writing and compiling programs.

Although much of the Arduino libraries and other software will work with an Arduboy, most of what you need for writing Arduboy specific games and other applications is included in the Arduboy2 library (other than some sound, miscellaneous and FX specific extensions, which are available as separate libraries and utilities).

Also, the Arduboy Quick Start Guide is still relevant.

If you want to research the early history of the Arduboy (though after @bateske created the prototype and development kit) you can read through the description, updates and comments of the Arduboy Kickstarter Campaign.

.

2 Likes

As for developping for the Arduboy FX I recommend to use the Legacy Arduino IDE which supports the Arduboy FX plugin and install the Arduboy homemade package.
This package contains not only all the Arduboy libraries but also a custom Arduboy core that adds the ‘UP+DOWN for 2 seconds to return to bootloader’ feature.

As noted the Cart builder + the Toolset should do what you are asking, it’s not all in one place and built into the website but it’s just downloading a couple files and clicking upload.

We’re working on making it easier, but at the core Arduboy is still an open source game development platform.

The tools that are available are there because of the community, the users that support it.

Wow, thanks for all the detailed replies. After work I’ll go through with followup questions on some points y’all made.

But one that grabbed me:

Notably the Arduboy2 library reserves 1,024 bytes (1 KB) for the frame buffer, so actual working memory is potentially lower

So I’m guessing the native display interface is not a framebuffer? How’s that work behind the scenes? I’m sure there’s a doc about this already…

Thanks,

Trin

The display itself has a frame buffer. You don’t need to continually refresh it to display a static image. However, the display’s buffer is write only, so if you want to modify parts of it based on its current content or, as is usual, build the next frame from scratch, a read/write “shadow” copy has to be maintained in CPU RAM.

You (or more commonly library routines you call) manipulate an image of the display in RAM and then write a copy of it to the display once for each frame.

The generalised most common procedure, in english:

  1. Wait until it’s time to display the next frame.
  2. Clear the RAM image of the display buffer.
  3. Manupulate the RAM buffer to render the next frame. This is the big step and the “guts” of your game.
  4. Write the RAM buffer to the display’s internal buffer (where it will continually display that frame until it’s changed).
  5. Repeat from step 1.
2 Likes

Oh by the way, I’m working on updating the home page (arduboy.com) to have better access to all of the information to get started on developing, also building your own Arduboy.

So much more has come out in the last couple years, time for an update! Hoping to get that out by the end of the year.

Finally had time to go through these in detail, thanks so much for your replies… and here’s a too-long response in rough order:

Ah but I loved my asm days… c and c++ I didn’t like as much but I haven’t done much of any of them since college years ago.

The C++ doesn’t look so bad for arduboy though so far.

I’m definitely going to have to look into this more, I love the esoteric ways you can fiddle with graphics on some consoles. Like the 2600 with its 128b of RAM and two scanlines of video to work with.

Ouch. Do folks write some magic bytes to see if it’s their data? Based on the EEPROM map on the cart builder site looks like this could happen a lot.

Is this still the library to use for this? Hm, seems like it has some affordance for easily saving to a unique 4k block, nice. Is this like a virtual filesystem, or how does it keep collisions out?

Is there a reason not to always save to the fx flash? Or a threshold where it’s better to move over there from eeprom?

by this I was asking how did this developer determine how much RAM / flash they used up… estimating by variable size? Looking at final binary?

Arduboy FX cart builder is awesome, thanks for that link!

As folks eventually figured out, yeah, the custom bootloader (which displays that title). Shame it’s not easy to tweak. Now I know why it’s hard to do things like add recents or favorite functionality…

Is there much interesting there that’s not already covered in the various Arduboy libraries?

Is it write-only like you have to send it the whole 1k block? I should look into the sources and see what it’s doing I suppose. Again, mostly for curiosity than optimization as it seems like the hardware is plenty fast for this

Thanks again all.

It is the wild west the best thing you’ve got is checking the map and backing up between swapping games.

In practice though, I think most people end up leaving their favorite game on their Arduboy so it’s not as much of an issue as it seems.

You can save to external memory though so that problem isn’t really an issue any more if you use the arduboyFX library.

Considering the screen is a standard part rather than some custom-made PPU, there’s probably not much you can do with it unless you’re a hardware expert and prepared to dig deep into the datasheet.

It took the best part of 8 years before someone with the right knowledge (@brow1067) came along and figured out it was possible to force the screen to do greyscale.

People have different methods.

The most typical is to just write two predetermined values to the start of the area one intends to use, and hope that those two bytes are enough to detect a clash.

The less common method is to actually run a checksum over the region of EEPROM being used and write the result into memory, thus increasing the ability to detect accidental overwrites and tampering. There was an attempt at the start of the year (by myself) to write a library that would provide a unified checksum facility, but it fell by the wayside, so it hasn’t been incorporated into Arduboy2 as planned.

The fact EEPROM clashes are possible is pretty much common knowledge, so anyone who really cares about their highscores will probably use a tool to back it up (e.g. to a file on a computer).

Though it does depend on which games a person is playing. There’s probably quite a fair chunk you could play without getting any clashes, but naturally there are those games that use great swathes of memory that will inevitably clash with half a dozen others, and with 400+ games the pigeonhole principle pretty much mandates that there will be clashes - it’s inevitable.

Yes.

I’m not sure I’d call it a filesystem as such, but games are given their own ‘slot’:

The original Arduboy didn’t have an FX chip, so if you were planning to make a game that’s compatible with the ‘classic’ Arduboy then you’d avoid using the FX library and stick to just progmem, RAM, and EEPROM.

That aside, bear in mind that flash memory has limitations. You can’t just write to it at random like you can with EEPROM - if a 1 bit needs to be written then an entire 4 KB page must be erased. Hence you have to plan where you’re writing your data to even if you’re writing it to a save area on the FX.

Well, obviously having more than 1008 bytes of save data means you’ve run out of EEPROM space.

The hard limit aside, it’s pretty much arbitrary.

The compiler tells you at the end of every successful compilation, assuming you’re using a standard environment like the Arduino IDE or Arduino plugin for VSCode/VSCodium.

Aside from the amount of space it would take up on the bootloader, you’d pretty much have to alter the storage format to incorporate that kind of information, or at least find a way to encode it in the existinf format.

(Bear in mind this is an environment with very limited resources, not some 32-bit ARM chip with an SD card.)

It depends what you mean by ‘interesting’.

The link @MLXXXp gave has more hardware specs (e.g. it specifies the number of IO pins of each type). The processor’s data sheet has yet further hardware details. For most people that level of detail isn’t really necessary, but really it depends on what sort of things you want to do and how much you want to know.

Yes. You send it an entire screen buffer’s worth of data all at once, in the format the screen expects it in - each byte representing a vertical column of 8 pixels.

Theoretically you could attempt to do something like write a tile engine with composited sprites. You’d gain by doing that is some extra RAM, and you’d likely chew up a lot of CPU cycles doing the compositing.

Another option would be to make a game with a lower resolution that can use a smaller framebuffer, e.g. 64x32. You’d gain some RAM back, but then you’d have even fewer pixels to work with.

A third option would be to have a ‘text mode’, effectively the same as a tile mode but with character tiles and no sprite compositing. That would save quite a chunk of memory and be reasonably fast, but then your game would have to consist entirely of text and/or symbols.

In case anybody’s missed the pattern here: whatever you do, you’ll only make gains in one area by incurring limitations in another.

2 Likes

It’s dangerous to go alone. Take this.
(I previously collated much of the EEPROM info).

1 Like

The (“official” Arduboy and FX SSD1306 based) display has commands to allow writing any number of bytes starting at any given buffer address. It’s just that using a 1K RAM buffer and then writing it to the full 1K display buffer, starting from address 0, is the common and easy way of doing display updates.

(Some of the other OLED displays, such as the SH1106 based ones, that are commonly used for Arduboy clones, can still be addressed and written randomly but a given length that can be written at a time is limited by rows. An Arduoby2 compatible library that supports such displays will take care of this transparently when used with the 1K RAM buffer.)