Flashcart Format - Revision history

Haloopdy: /* Slot header */ Wrong type for reserved

2024-06-23T05:45:08Z

Slot header: Wrong type for reserved

← Older revision		Revision as of 05:45, 23 June 2024
Line 39:		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-24 \|\| ~~reserved~~ \|\| Unused data (mostly)		\| 23-24 \|\| short \|\| Unused data (mostly)
	\|-		\|-
	\| 25-56 \|\| sha256 \|\| Raw bytes for SHA256 of program + data ('''after''' FX page align)		\| 25-56 \|\| sha256 \|\| Raw bytes for SHA256 of program + data ('''after''' FX page align)

Haloopdy: /* Slot header */ Forgot the sha256

2024-06-23T05:44:36Z

Slot header: Forgot the sha256

← Older revision		Revision as of 05:44, 23 June 2024
Line 39:		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 \|\| reserved \|\| 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>

Haloopdy: /* Slot header */ note about little endian

2024-06-22T22:30:35Z

Slot header: note about little endian

← Older revision		Revision as of 22:30, 22 June 2024
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:

Haloopdy: Beginning new documentation for flashcart

2024-06-22T22:27:48Z

Beginning new documentation for flashcart

New page

The [[Flashcart]] is a binary blob stored on the external flash memory of [[Arduboy (Original)|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 <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.

The header fields are as follows:
{| class="wikitable" style="margin:auto"
|+ Table describing the format of the Arduboy FX flashcart header
|-
! Byte Index !! Type !! Description
|-
| 0-6 || preamble || The bytes <code>ARDUBOY</code>
|-
| 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-56 || reserved || Unused data (mostly)
|-
| 57-255 || strings || Metadata for slot<sup>*</sup>
|}

==== 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 [https://semver.org/ 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 <code>"\0\0\0\0"</code> 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 <code>"\0\0"</code>.

== 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