Flashcart Format: Difference between revisions

From Arduboy Wiki
Jump to navigation Jump to search
(Beginning new documentation for flashcart)
 
m (→‎Slot header: Wrong type for reserved)
 
(2 intermediate revisions by the same user not shown)
Line 10: Line 10:
=== Slot header ===
=== Slot header ===
Each slot in the flashcart starts with the 7 bytes for the ASCII string <code>ARDUBOY</code>. 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.
Each slot in the flashcart starts with the 7 bytes for the ASCII string <code>ARDUBOY</code>. 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:
The header fields are as follows:
Line 37: Line 39:
| 21-22 || short || Size of FX data in pages ('''NOTE:''' not all cart builders set this value!)
| 21-22 || short || Size of FX data in pages ('''NOTE:''' not all cart builders set this value!)
|-
|-
| 23-56 || reserved || Unused data (mostly)
| 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<sup>*</sup>
| 57-255 || strings || Metadata for slot<sup>*</sup>

Latest revision as of 05:45, 23 June 2024

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