Flashcart Format
The Flashcart is a binary blob stored on the external flash memory of Fx-modded Arduboys, Arduboy FX and Arduboy Mini. It stores games and saves organized into categories.
General format
(This section needs work; probably a visual representation of the cart)
The flashcart is a contiguous binary blob storing images, categories, sketches, data, and save data. It is separated into chunks called "slots", where each slot has a 256-byte header. Everything is a slot: both categories and programs. Each slot header is followed by a 1024-byte image which is shown on the Arduboy as you browse the flashcart, then all the data for that slot (sketch, data, save).
The flashcart ends when there are no more slots.
Slot header
Each slot in the flashcart starts with the 7 bytes for the ASCII string ARDUBOY. You know you have reached an invalid slot while scanning the flashcart when you reach a slot that does not start with those 7 bytes. The rest of the header are numbers and text explaining where items in the slot are and human-readable information about the program.
Note: all values on Arduboy are little endian
The header fields are as follows:
| Byte Index | Type | Description |
|---|---|---|
| 0-6 | preamble | The bytes ARDUBOY
|
| 7 | byte | Category number (mostly unused but required) |
| 8-9 | short | Previous slot page (0xFFFF if first slot) (page = 256 bytes) |
| 10-11 | short | Next slot page (0xFFFF if last slot) |
| 12-13 | short | Total slot size in pages |
| 14 | byte | Size of sketch in flash memory pages (128 bytes) |
| 15-16 | short | Starting page of sketch (technically redundant but required) |
| 17-18 | short | Starting page of FX data (0xFFFF if no FX data in slot) |
| 19-20 | short | Starting page of FX save (0xFFFF if no FX save in slot) |
| 21-22 | short | Size of FX data in pages (NOTE: not all cart builders set this value!) |
| 23-24 | short | Unused data (mostly) |
| 25-56 | sha256 | Raw bytes for SHA256 of program + data (after FX page align) |
| 57-255 | strings | Metadata for slot* |
Slot metadata
The final 199 bytes are used for 4 string fields, as follows:
- Title - Name of the program
- Version - Arbitrary text indicating the version of the program (no required format)
- Developer - Name of the developer or group for the program
- Description - A description of the program
Each field is separated by the null terminator, and the final field is truncated if it overflows. If the final field fills up the entire rest of the data, no null terminator is added.
The fields are not used on the Arduboy itself (they are not displayed anywhere), however they are extremely useful for cart editors, so they should always be included. Furthermore, certain cart editors depend on the version being in some recognizable form of Semver format, such as 0.1 or 1.0-r etc. Some cart editors use a combination of Title and Developer as a unique ID for the slot when figuring out if a program is new or an update.
Program slots use and expect all four fields, even if they're empty. Thus, at an absolute minimum, you should write "\0\0\0\0" to the metadata if you are not providing any information
Category slots only expect two fields: Title and Description. The version and developer fields are not stored. As a result, the minimum metadata for categories should be "\0\0".
Working with the flashcart
There are several programs which let you modify or create flashcarts:
- Cart Builder - This online repository of games will construct a custom cart for any given device
- Arduboy Toolset - This desktop app lets you modify flashcarts directly
- Ardugotools - This cli program gives you both low-level access to the flashcart and the ability to modify the flashcart with lua scripting
- Arduboy-Python-Utilitiles - The original python scripts made by the creator of the FX chip