Arduboy2 Library

The Arduboy2 library is maintained in a git repository hosted on GitHub at:

https://github.com/MLXXXp/Arduboy2

The Arduboy2 library is a fork of the Arduboy library, which provides a standard application programming interface (API) to the display, buttons and other hardware of the Arduino based Arduboy miniature game system. The original Arduboy library is no longer being maintained.

The name Arduboy2 doesn't indicate that it's for a new "next generation" of the Arduboy hardware. The name was changed so it can coexist in the Arduino IDE with the current Arduboy library, without conflict. This way, existing sketches can continue to use the Arduboy library and class, without changes, while new sketches can be written (or old ones modified) to use and take advantage of the capabilities of the Arduboy2 class and library.

For notes on the differences between the Arduboy2 library and the original Arduboy library, and for information on migrating a sketch currently using the Arduboy library, see the sections at the end of this document.

Library documentation

Comments in the library header files are formatted for the Doxygen document generation system. The HTML files generated using the configuration file extras/Doxyfile can be found at:

https://MLXXXp.github.io/documents/Arduino/libraries/Arduboy2/Doxygen/html/index.html

A generated PDF file can be found at:

https://MLXXXp.github.io/documents/Arduino/libraries/Arduboy2/Doxygen/pdf/Arduboy2.pdf

Installation

The Arduboy2 library can be installed using the Arduino IDE Library Manager:

In the Arduino IDE select from the menus: Sketch > Include Library > Manage Libraries...
In the Library Manager Filter your search... field enter arduboy2.
Click somewhere within the Arduboy2 entry.
Click on the Install button.

For more library installation information see

Installing Additional Arduino Libraries - Using the Library Manager

Start up features

The begin() function, used to initialize the library, includes features that are intended to be available to all sketches using the library (unless the sketch developer has chosen to disable one or more of them to free up some code space):

The boot logo

At the start of the sketch, the ARDUBOY logo scrolls down from the top of the screen to the center.

The RGB LED lights red then green then blue while the logo is scrolling. (If your Arduboy is one of those that has the RGB LED installed incorrectly, then it will light blue then off then red). For users who do not wish to have the RGB LED flash during the boot logo sequence, a flag can be set in system EEPROM to have it remain off. The included SetSystemEEPROM example sketch can be used to set this flag.

A user settable unit name can be saved in system EEPROM memory. If set, this name will be briefly displayed at the bottom of the boot logo screen, after the logo stops scrolling down. This feature is only available if the Arduboy2 class is used, not the Arduboy2Base class. This is because it requires the text display functions, which are only available in the Arduboy2 class. A flag in system EEPROM controls whether or not the unit name is displayed on the boot logo screen, regardless of whether the unit name itself has been set. The included SetSystemEEPROM example sketch can be used to set both the unit name and this flag.

Once the logo display sequence completes, the sketch continues.

Note:

For developers who wish to quickly begin testing, or impatient users who want to go strait to playing their game, the boot logo sequence can be bypassed by holding the RIGHT button while powering up, and then releasing it. Alternatively, the RIGHT button can be pressed while the logo is scrolling down.
For users who wish to always disable the displaying of the boot logo sequence on boot up, a flag in system EEPROM is available for this. The included SetSystemEEPROM example sketch can be used to set this flag.

"Flashlight" mode

If the UP button is pressed and held when the Arduboy is powered on, it enters flashlight mode. This turns the RGB LED fully on, and all the pixels of the screen are lit, resulting in a bright white light suitable as a small flashlight. (For an incorrect RGB LED, only the screen will light). To exit flashlight mode the Arduboy must be restarted.

Flashlight mode is also sometimes useful to allow uploading of new sketches, in case the sketch currently loaded uses a large amount of RAM which creates a bootloader problem.

Audio mute control

Pressing and holding the B button when powering on will enter System Control mode. The RGB LED will light blue (red for an incorrect LED) to indicate that you are in system control mode. You must continue to hold the B button to remain in this mode. The only system control function currently implemented is audio mute control.

Pressing the UP button (while still holding B) will set a flag in system EEPROM indicating audio enabled. The RGB LED will flash green once (off for an incorrect LED) to indicate this action.

Pressing the DOWN button (while still holding B) will set the flag to audio disabled (muted). The RGB LED will flash red once (blue for an incorrect LED) to indicate this action.

Releasing the B button will exit system control mode and the sketch will continue.

Note that the audio control feature only sets a flag in EEPROM. Whatever code actually produces the sound must use the audio.enabled() function to check and honor the mute state. Audio libraries written with the Arduboy system in mind, such as the available ArduboyPlaytune and ArduboyTones, should do this. However, be aware that for some sketches, which don't use the Arduboy2 or other compliant library and generate sounds in their own way, this method of muting sound may not work.

Using the library in a sketch

As with most libraries, to use Arduboy2 in your sketch you must include its header file at the start:

#include <Arduboy2.h>

You must then create an Arduboy2 class object:

Arduboy2 arduboy;

Naming the object arduboy has become somewhat of a standard, but you can use a different name if you wish.

To initialize the library, you must call its begin() function. This is usually done at the start of the sketch's setup() function:

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

The rest of the Arduboy2 functions will now be available for use.

If you wish to use the Sprites class functions you must create a Sprites object:

Sprites sprites;

Sample sketches have been included with the library as examples of how to use it. To load an example, for examination and uploading to the Arduboy, using the Arduino IDE menus select:

File > Examples > Arduboy2

More information on writing sketches for the Arduboy can be found in the Arduboy Community Forum.

Using EEPROM in a sketch <- THIS IS IMPORTANT!

The Arduboy2 library reserves an area at the start of EEPROM for storing system information, such as the current audio mute state and the Unit Name and Unit ID. A sketch MUST NOT use this reserved area for its own purposes. A sketch may use any EEPROM past this reserved area. The first EEPROM address available for sketch use is given as the defined value EEPROM_STORAGE_SPACE_START

Audio control functions

The library includes an Arduboy2Audio class. This class provides functions to enable and disable (mute) sound and also save the current mute state so that it remains in effect over power cycles and after loading a different sketch. It doesn't contain anything to actually produce sound.

The Arduboy2Base class, and thus the Arduboy2 class, creates an Arduboy2Audio class object named audio, so a sketch doesn't need to create its own Arduboy2Audio object.

Example:

#include <Arduboy2.h>

Arduboy2 arduboy;

// Arduboy2Audio functions can be called as follows:
  arduboy.audio.on();
  arduboy.audio.off();

Simple tone generation

The BeepPin1 and BeepPin2 classes are available to generate simple square wave tones using speaker pin 1 and speaker pin 2 respectively. These classes are documented in file Arduboy2Beep.h. Also, BeepDemo is included as one of the example sketches, which demonstrates basic use.

NOTE: These functions will not work with a DevKit Arduboy because the speaker pins used cannot be directly controlled by a timer/counter. "Dummy" functions are provided so a sketch will compile and work properly but no sound will be produced.

Ways to make more code space available to sketches

Sound effects and music

If all you want is to play single tones, using the built in BeepPin1 or BeepPin2 classes will be very efficient.

If you want to be able to play sequences of tones or background music, using the ArduboyTones library will be more code efficient than using ArduboyPlaytune or most other sound libraries compatible with the Arduboy. ArduboyTones even produces less code than the Arduino built in tone() function. You'll have to decide on the appropriate library or functions you use to generate sound, based on the features required and how much memory you want it to use.

Remove the text functions

If your sketch doesn't use any of the functions for displaying text, such as setCursor() and print(), you can remove them. You could do this if your sketch generates whatever text it requires by some other means. Removing the text functions frees up code by not including the font table and some code that is always pu

Arduboy2

Install / Use

README