Quick Start Guide

Welcome to your brand-new Arduboy!

This guide will introduce you to the features of the Arduboy and get you started with software you need to upload new games and develop your own software.

There are two versions of the Arduboy:

  1. The “production” Arduboy which was developed as result of a Kickstarter campaign. This is sometimes referred to as the Arduboy 1.0

This guide is applicable to both versions.

Introduction

The tiny square black chip in the bottom right corner of the production Arduboy, or near the center of the DevKit, is called a microcontroller and it is the brains of the device. This tiny 8-bit computer contains all of the instructions, graphics, and sound to produce the game played on the device. We can reprogram the Arduboy, and change the game on it, using a micro-USB cable and some software called Arduino.


Step 1: Download and Install Arduino Software

Click here to go to the Arduino Download Page

Use the links on the Arduino website to download the install file. Run the installer executable and follow the instructions to install the Arduino software onto your computer.

The Arduino IDE is an Integrated Development Environment (IDE). This means that you can create software for Arduino compatible devices within one piece of software. The same program that you use to edit the code will be used for compiling (turning source code into machine language) and uploading to the device.

We are working on some future solutions that will allow you to upload software without Arduino. Stay Tuned!


Step 2: Install the Arduboy Libraries and Board Support

Install the Arduboy, Arduboy2 and other libraries

The Arduboy and Arduboy2 libraries are used by most sketches to access the features and functions of the Arduboy. Also, other Arduino libraries intended for the Arduboy have been written to provide additional features.

Arduboy, Arduboy2 and many other libraries are easy to install using the Arduino IDE’s Library Manager. To add the these libraries to the Arduino IDE, from the Arduino IDE’s menu bar select the Library Manager found under the Sketch menu.

Sketch > Include Library > Manage Libraries...

This will open the Library Manager. Search for Arduboy related libraries by entering arduboy in the Filter your search… field. After selecting the Arduboy, Arduboy2 or other library from the list press Install.

It’s best to install all the Arduboy related libraries, to make them available to sketches that need to use them. Otherwise, you may get errors and be unable to upload a sketch that relies on a particular library having been installed.

Arduboy related libraries include:

More information on installing and managing Arduino Libraries can be found here.

Note for sketch developers: The Arduboy library is no longer being developed. It is recommended that new sketches use the Arduboy2 library.

Install Support for the Arduboy and DevKit (optional)

By installing support for the Arduboy and DevKit in the IDE you will be able to select Arduboy or Arduboy DevKit as the device (board) that you are using.

If you have a production Arduboy, this step is optional. You can just select the built in device Arduino Leonardo, but it’s probably easier to remember Arduboy than Arduino Leonardo.

If you have a DevKit, it is recommended that you install this support. Otherwise, you will have to edit some lines in the Arduboy library which you previously installed, in order to make many of the programs work properly.

Here’s how to add the boards:

  • In the Arduino IDE select File > Preferences. In the Settings tab there will be a field titled Additional Boards Manager URLs:
    Put the following text in this field:
    https://arduboy.github.io/board-support/package_arduboy_index.json

If the field already has had other URL(s) added, you can click on the edit icon at the end of the field to allow you to add the new URL on a separate line.

  • Click on OK to save the preferences.

  • Select Tools > Board: > Boards Manager...

  • In the search field at the top right of the Boards Manager window, enter arduboy.

  • Click on the box containing: Arduboy by Arduboy Team
    and then click on the Install button that appears at the bottom right of the box.

The word INSTALLED should appear in the box.

  • Close the Boards Manager window.

  • There should now be items Arduboy and Arduboy DevKit available for selection in the menu that you get using Tools > Board:


Step 3: Try Opening and Uploading an Example Sketch

In the Arduino IDE, a game or other program is called a sketch. A sketch is opened in the IDE and then uploaded into your Arduboy so you can run it. It’s a good idea to use one of the example sketches included with the Arduboy library as the first sketch that you upload, in order to verify that you have followed the previous steps correctly and everything is working.

The example sketches will have been tested to work with the currently installed Arduboy library, so will eliminate one possible source of problems.

Open an Example Sketch

Select from the IDE menus:
File > Examples > Arduboy2
and click on one of the examples offered.

This should open the chosen sketch in a new IDE window.

Connect your Arduboy and Set the Board Type and Port

Note: In order for a production Arduboy to be seen as a USB device on your computer, to allow uploading a sketch, the power switch must be on. For a DevKit, the power switch should be off.

The first time you plug the Arduboy into your Windows computer after installing the Arduino software you will be notified that a new USB device was detected. The Arduboy will appear to your computer as an Arduino Leonardo.

  • Set the type of Arduboy that you have by selecting from the IDE menus:
    Tools > Board:
    From the offered devices, choose Arduboy (or Arduino Leonardo if you didn’t install the board support in Step 2 above) if you have a production Arduboy.
    If you have a DevKit, choose Arduboy DevKit.

  • Set the port that your Arduboy is connected to by selecting from the IDE menus:
    Tools > Port
    The correct port to choose will likely be identified as an Arduino Leonardo. This is fine. The Arduboy uses the Arduino Leonardo bootloader so is detected as such.

The board type and port that is currently selected can be seen on the status bar at the bottom of the IDE window. Always check that they are correct before uploading a sketch to your Arduboy.

Upload the sketch

To upload the opened sketch to your Arduboy, select from the IDE menus:
Sketch > Upload
or just click on the Upload button near the top left of the IDE.

If all goes well, the sketch will compile without errors and then be uploaded to your Arduboy. After the upload completes, the sketch will run immediately. Hurray! :thumbsup:

Just a note: If at any time you wish to check if the opened sketch will compile properly but not have it uploaded to your Arduboy (even if the Arduboy isn’t connected), you can click on the Verify button or select from the IDE menus:
Sketch > Verify/Compile

Another note: Once you become familiar with using the Arduino IDE, you may wish to use keyboard shortcuts to perform many operations, instead of using menu selections or mouse clicks. If a shortcut is available, it will be shown at the right of the menu item for the operation that it will perform.


Step 4: Install more Games and other Sketches and Start to Play!

Click Here to Visit the Games Category

Adding games and other sketches to the IDE isn’t very difficult, once you get the hang of it.

         :arrow_down:
:arrow_right: Use the detailed guide on how to install sketches, which can be viewed by clicking here. :arrow_left:
         :arrow_up:

Installed sketches that aren’t library examples can be opened by selecting from the IDE menus:
File > Sketchbook
You can also open any installed sketch by clicking on the Open button near the top left of the IDE.

We are currently working on a web interface for a more simple one-click upload. The goal is for users to navigate to arduboy.com and be able to immediately play new games. An offline hex uploader is also in development.

Browse around in the community for games other users have posted! The best thing about the Arduboy community is the ability to communicate directly with the developers! Join in on the fun!


Start Up Features and Customization

Start Up

Most sketches use the Arduboy2 library. If used in the standard way, this library will perform or make available features when a sketch first starts. (Some or all of these may not be available if the developer has chosen not to include them or a different main library is used.)

  • Boot logo: The ARDUBOY logo scrolls down from the top of the screen to the center and the RGB LED flashes red - green - blue. If you’ve given your Arduboy a custom name (see below), it will be shown at the bottom of the screen after the logo stops moving (for most sketches).

    If you want to quickly start the game, you can abort the logo sequence by pressing the RIGHT button. You can also configure your Arduboy so that the LED doesn’t flash, the custom name doesn’t appear, or even bypass the logo sequence altogether. (See below.)

  • Flashlight mode: If you hold the UP button while powering up, the RGB LED and screen will light up white. This can be used as a flashlight/torch. This mode is also useful to allow uploading a new sketch when a problem with the Arduino bootloader occurs.

  • Audio mute control: Sound can be muted or re-enabled by pressing and holding the B button while powering up, then while still holding B, pressing UP to enable or DOWN to disable sound. The setting is non-volatile and will remain in effect, even over power cycles, until changed using this feature or within a sketch.

More details on the above can be found in the Start Up Features section of the Arduboy2 Library documentation.

Naming Your Arduboy and Setting the Boot Logo Behavior

As mentioned in the Boot logo section above, there’s a place in non-volatile storage (system EEPROM) that can hold an up to 6 character “Unit Name”, which is displayed at the end of the logo sequence. This name can also be accessed by sketches if they wish to use it for some purpose. Also mentioned in the Boot logo section is the ability to set aspects of how the boot logo sequence behaves (also saved in EEPROM). All of this can be configured using the SetSystemEEPROM example sketch included in the Arduboy2 Library. You can load this sketch from the Arduino IDE using:
File > Examples > Arduboy2 > SetSystemEEPROM


Having problems?

If at some point your Arduboy appears to be dead, or you’re having trouble uploading a new sketch to it, don’t panic :anguished:. You may just have to use flashlight mode or follow a reset procedure.

Click here for instructions on using flashlight mode
Click here for production Arduboy reset instructions
Click here for DevKit reset instructions

If you run into problems at this stage there are guides elsewhere on the community site that can help out.


And there you have it! You’re ready! If you are just learning about Arduino for the first time this link is probably as good a place as any to get started. Get curious! Start Google searching and watching other peoples tutorials! Participate in this forum! Before long you will be posting content of your own! Start to Play! :checkered_flag:

Discuss this topic

If you would like to talk about this Guide, you can do so in your own topic OR go to this one:

5 Likes

April 11, 2017

Added Arduboy-TinyFont to the list of Arduboy related libraries.

3 Likes

April 23, 2017

Emphasize that all Arduboy related libraries should be installed.

May 9, 2017

Added a Having problems? heading for the section at the end of Step 4.

Added a link to the guides category.

June 10, 2018

Added @Pharap’s FixedPointsArduino library to the list of Arduboy related libraries in Step 2.

3 Likes

September 29, 2020

Added a section describing the operation of the Arduboy2 library’s “start up” features (logo, flashlight, audio control), and how to set the Unit Name.

Removed the section about Team A.R.G.

Changed a few outdated links.

1 Like

March 14, 2021

Fixed broken link to ATMlib caused by Team A.R.G. deleting their GitHub repository.

The link now points to the archived copy in the Team ARG Museum GitHub repository.