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:

Table describing the format of the Arduboy FX flashcart header

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