Arduboy2 Library

The library provides two sprite classes:

• Sprites: Optimized for execution speed.
• SpritesB: Optimized for small code size.

If execution speed is not a critical factor for your sketch, using SpritesB can help reduce the overall memory footprint.

Sprites sprites;  // Optimized for speed
SpritesB sprites; // Optimized for code size

The Arduboy2 library reserves the beginning of the EEPROM for system information (e.g., audio mute state, Unit Name, and Unit ID).

Warning: Do not use the reserved area for your own data. To ensure you are using safe memory, use the defined constant EEPROM_STORAGE_SPACE_START as the starting address for your sketch's EEPROM operations.

The Arduboy2 library uses system EEPROM to manage boot-up behavior and personalization. You can use the included SetSystemEEPROM example sketch to manage the following:

• Disable Boot Logo: Set a flag to prevent the logo sequence from playing on boot.
• Set Unit Name: Save a custom name that appears briefly at the bottom of the boot logo. Note: This requires using the Arduboy2 class (not Arduboy2Base) because it relies on text display functions.
• Toggle Unit Name Display: Set a flag to control whether the saved unit name is shown during the logo sequence, regardless of whether a name is set.

To ensure correct conversion, follow these requirements for your input PNG:

1. Dimensions: The image height must be a multiple of 8 pixels (e.g., 8, 16, 24, 32...). Width can be any size.
2. Color Logic: Cabi uses RGBA values to determine pixel state:
   • Image Output (Drawn vs Non-drawn):
     • Pixels with Alpha <= 127 are always non-drawn (0).
     • Pixels with Alpha > 127 and Red > 127 are drawn (1).
     • All other combinations result in non-drawn (0).
   • Mask Output (Transparency):
     • Only the Alpha channel is used.
     • Alpha > 127 results in a mask value of 1.
     • Alpha <= 127 results in a mask value of 0.

Recommendation: For best results, use fully white pixels for drawn areas, fully black for non-drawn areas, and fully transparent pixels for masked areas.

Cabi is a command-line tool written in C that converts PNG images into RLE-encoded C/C++ arrays for use with the Arduboy2 drawCompressed() function. Since pre-built binaries are not provided, you must compile it using an ANSI C99 compatible compiler like gcc or clang.

To build the program from the cabi directory, run:

gcc cabi.c lodepng/lodepng.c -o cabi
# or for Windows
gcc cabi.c lodepng/lodepng.c -o CABI.EXE

To play music in the background while your main sketch code runs in the foreground, you must install the ArduboyPlayTune library.

1. Install the library: Download it from https://github.com/Arduboy/ArduboyPlayTune.
2. Define a score: Store your musical composition in a PROGMEM byte array.
3. Play the score: Call playScore(score) within your sketch loop to begin playback.

// Define the composition in PROGMEM
byte PROGMEM score[] = { /* ... musical data ... */ };

void loop() {
  // Start playing the score in the background
  playScore(score);
  
  // Your 'real' sketch code runs here in the foreground
}

The begin() function triggers a boot logo sequence where the ARDUBOY logo scrolls down the screen and the RGB LED flashes. To skip this sequence for faster testing or gameplay:

• Method 1: Hold the RIGHT button while powering up the device, then release it.
• Method 2: Press the RIGHT button while the logo is currently scrolling down the screen.

To use the Arduboy2 library, include the header file, instantiate an Arduboy2 object, and call begin() within your setup() function. If you need sprite functionality, you must also instantiate a Sprites object.

To load built-in examples in the Arduino IDE, navigate to: File > Examples > Arduboy2.

#include <Arduboy2.h>

Arduboy2 arduboy;
Sprites sprites;

void setup()
{
  arduboy.begin();
  // more setup code follows, if required
}

The begin() function includes several startup features (like the boot logo and system button checks). To save memory, you can call boot() instead, which only initializes the hardware.

If you use boot(), you must manually call other features if needed. Crucially, you should always include either flashlight() or safeMode() to ensure you can still upload new sketches if the bootloader becomes inaccessible.

void setup()
{
  // Initializes hardware but skips extra boot features
  arduboy.boot();

  // Manually add back necessary features
  arduboy.display();
  arduboy.flashlight(); // Safeguard for uploading
  arduboy.audio.begin();
  arduboy.waitNoButtons();

  // Additional setup code...
}