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?
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?
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!
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
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
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’.
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.
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).
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.
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.
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:
Wait until it’s time to display the next frame.
Clear the RAM image of the display buffer.
Manupulate the RAM buffer to render the next frame. This is the big step and the “guts” of your game.
Write the RAM buffer to the display’s internal buffer (where it will continually display that frame until it’s changed).
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
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.
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.
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.)