The E-Reader was a playing card based hardware accessory the the Nintendo Game Boy Advance that reads optically encoded software.
The reason this hardware is of particular interest is the ability to "publish" your own software by simply printing the dot code strips and giving them to other's with the hardware. There is no need for any custom hardware to run new software.
If you want to jump straight into it, an Example Project
has been included. Be sure to set up the bin/ directory as needed
and setup the GBA Development
enviornment first.
This repo has been setup primarily as a linux first development enviornment. However, I have been simultaneously been testing it with WSL Ubuntu and have had no issues. It should be entirely possible to use this setup on either Windows or Linux as a result.
The dev tools usable for the E-Reader can be split into three categories:
The E-Reader has several execution modes, most notably it can run as an NES or as a GBA. If you stick with the GBA mode you can use the standard open source GBA developement toolchain. The main difference is linking in some decicated E-Reader features that are availble. These give you some generic assets to save executable space and reduce the card count.
The recommended toolchain is DevKitPro which supports targeting multiple devices. But we are intersted in the GBA ARM toolchain for this.
The easiest way to test your code is with an emulator, mGBA works very well for this. It supports loading save data as well as directly loading Dot Code data stored in BMP image files. mGBA even supports debugging with a gdb server.
DevKitPro has an annoying and inflexible setup process rather than distributting binaries.
The TL;DR to get it usable for E-Reader GBA Dev is the following:
wget https://apt.devkitpro.org/install-devkitpro-pacman
chmod +x ./install-devkitpro-pacman
sudo ./install-devkitpro-pacman
sudo dkp-pacman -S gba-dev
Each time you start your terminal enviornment for GBA dev you need to load in configuration for the DevKitPro toolchain.
source /etc/profile.d/devkit-env.sh
This sets up environment variables for you to use in your dev processes:
export DEVKITPRO=/opt/devkitpro
export DEVKITARM=${DEVKITPRO}/devkitARM
export PATH=${DEVKITPRO}/tools/bin:$PATH
The $DEVKITARM/bin directory contains the gcc tools for compiling C/C++ code
for the GBA.
Once you have a valid GBA binary you need to convert it to work on the E-Reader. There is a version of the tools available for multiple platforms Downloading and compiling these tools will give you nearly everything you need to create usable E-Reader cards.
With the tools, there are a few steps to this process:
nevpk- VPK Compressionnedcmake- Dot Code binary generationnedcenc- Dot Code Encodingraw2bmp- Dot Code image generation
These steps are best done as part of a build process after compiling with GCC and make sense to include in a MakeFile. They generally each take the output as the input to the next step. There is a variance when your program becomes large enough to split across multiple cards (which I am not able to cover yet.)
There is one alternative step 2 you can do when doing development. Using neflmake will encode the program in a way GBA emulators can load as game save data. The E-Reader can store software on it, and this can "inject" your program into it. You can also use this with the real E-Reader cart to load a program if you have hardware capable of writing GBA cart save data.
Other Dev tools for the GBA can be helpful for importing assets like graphics and sound. Because the GBA is a monolithic ROM based system, assets are embedded in the main executable. This is usually done as arrays of bytes holding the raw data.
A few programs for working with graphics that convert them into compatible formats or directly into C array files.
Sound is 8 bit signed PCM and does not have a fixed sample rate. You don't need
any special software to encode these, export them with Audacity or use ffmpeg
to convert to the s8 codec. To get those into C arrays you still need other
tools though:
- raw2gba - Converts PCM to C arrays
I recommend this article for more information and examples on using sound.