Box file format

Notice

This section is in development and the BOX format will be introduced in the future. This page just presents what WILL be implemented and is currently under modification.

Goal

The BOX file format aims at a simple binary distribution means for bitbox games. They are a means to provide everything for a game : binaries for several formats, an icon for selecting it, a common description, high scores, et caetera.

They are usable directly by the bootloader from SD card and several scripts can be used to flash the bitbox models with it.

Usage

Box files can be used in several ways.

Main Bitbox

Main use case : Using Bitbox Bootloader

• Put all you box files in the microSD
• use them from the bitbox Bootloader to flash the game to the chip.

Using a SWD adaptor + texane st-link (under linux)

(in the future : create a small app + a .desktop file ?) Plug your SWD connectxor to the bixbox, type this (replacing mygame.box and mygame.bin with the game you want to flash)

tar -xvf mygame.box /tmp/mygame.bin && st-flash /tmp/mygame.bin 0x804000

Bitbox Micro

Using DFU mode under linux

Put the bitbox micro in bootloader mode (ie set up the Boot0 jumper & plug it to a PC using usb )

tar -xvf mygame.box /tmp/mygame-micro.bin && dfu-util -D /tmp/mygame-micro.bin --dfuse-address 0x8000000 -a 0

Using DFU mode under windows

Extract the mygame-micro.bin from the .box file (by renaming it to .tar) Use dfuse stm graphical utility Alternatively, install dfu-util for windows (dfu-util-static.exe)

Using an SWD connector

Same as with Bitbox, but use the mygame-micro.bin of course.

Running SDL emulators on the PC

manually : just extract the binary (win32.exe under windows, ... ) for your system manually next to the tar file and run it.

Utility

An eventual utility might also be used to run games emulators, or flash a bitbox

Box files format

Box files are in fact very standard tar files with a few standards for file names. Just rename them from .box to .tar and you can view, modify or create them as is.

• Under Linux or MacOS, you can use the commandline tar utility to create, view or modify them. Many other utilities exist to modify such files, such as file-roller under gnome.

example :

$ tar -tvf mygame.box 
-rwxrwxrwx 0/0            1106 2016-03-11 14:40 mygame.bin
-rwxrwxrwx 0/0            2052 2016-03-17 17:29 mygame.bmp
-rwxrwxrwx 0/0           10247 2016-03-10 15:39 mygame.txt
-rwxrwxrwx 0/0               4 2016-03-11 10:38 mygame_micro.bin

• Under windows, 7-zip is a good general purpose compressor which can create them. Select a bunch of files, create archive and select "tar" (non compressed)

If you want to create new .box files, just follow these rules for a game named mygame.box (which is a mygame.tar in fact):

• No directories, all files must be in the root of the archive
• mygame.bmp : is a 16-color 64x64 bitmap file, uncompressed
• mygame.txt : is a description of the game
• mygame.bin : is the bitbox binary file
• mygame_micro.bin : is the bitbox-micro binary file
• win32/64, lin32/64, emulators and extra other files can be included here.