The Reset Dance: How to fix your Arduboy no matter what

The Reset Dance is a simple and fun routine you can perform to recover any Arduboy that has problems uploading. Perform the dance in order, as some of them to the end are more dangerous and can damage the Arduboy so should be considered only in the method of last result.

  1. Turn on the Arduboy while holding the UP button to enter flashlight mode. While in flashlight mode, attempt to upload.

Games that require flashlight mode: TBD

Flashlight mode will work for your Arduboy if plugging it into USB still gives you a detection chime and attempting an upload resets the device but it will not program. This is a symptom of an application that includes the USB stack but the program is disturbing a memory address in RAM needed for the bootloader to function. Flashlight mode holds the Arduboy in a loop that prevents the game code from running.

  1. Turn on the Arduboy while holding the DOWN button to force bootloader recovery mode. Continue holding the down button to remain in bootloader mode while attempting to upload. The Arduboy will reset several times. – Try this dance move a couple times if it seems like the Arduboy is resetting, it is timing dependent

Games that require down button reset: TBD

Holding the down button is used on games that remove the USB code from the main sketch, and thus do not show up as a serial connection to the PC. The Arduboy cannot be reset by the USB method and so by holding down, the sketch actually just resets the Arduboy to the bootloader repeatedly. This is why the timing is important as most applications have a specific window where it will attempt to upload and this has to match the reset window of the Arduboy.

  1. If the other two dance moves do not work and you are using an application other than Arduino, you should attempt dances moves 1 and 2 again using the Arduino software.

  2. If all else fails, use the reset button and the Arduino software to recover your device. Press upload on the Arduino to initiate the series of attempts from the software, and then quickly but carefully press the reset button on the Arduboy while it is powered on and connected to the PC.

The only circumstance that should require the reset button is a corrupted bootloader, or a very poorly written application that removes the USB code but also does not provide one of the approved methods for recovery. Be careful, the reset button can be damaged by excess force.

If you have authored a game or are otherwise aware of a need to have a special reset procedure and it is not already listed above, please comment below. If you are having a problem using this guide please search the forums first for your specific issue and then make a new post if you cannot find one.

This post will be updated with video soon…

1 Like

Not all sketches include flashlight mode. Developers trying to get more program space will use boot() instead of begin() and leave out a call to the flashlight function.

Some sketches that use boot() will include safe mode (by calling safeMode()), since it uses slightly less program space than flashlight. Safe mode works the same as flashlight except the RGB LED lights red instead of white and the display stays off instead of turning all pixels on.

Some sketches don’t include flashlight or safe mode. If one of these encounters the “magic key” bootloader problem, using the reset button may be the only resort.

(At least some) Linux distributions don’t make a sound when a USB device is plugged in and detected. I don’t know what Macs do.

1 Like

No sound, it just shows up in Finder (hopefully!).

@MLXXXp everything you say is true! The Reset Dance is intended for non technical users to have a catch-all procedure for trying to figure out how to reprogram their Arduboy. It is true some games will not have flashlight mode, others will not have the down button reset, but it’s a good procedure to try anyways. I hope to compile a list of the games that require each method and list them in the first post soon.

1 Like

A list of games 100% requiring flashlight mode won’t be achievable or will be very short.

TL;DR: Any changes made to a sketch, or its dependencies, or build environment could cause the problem to start happening or disappear, and what the sketch is doing when a new upload is attempted could also have an effect. Therefore, it would be a list of sketches where flashlight mode helped at some point but it won’t necessarily still or always be required for one listed. Some versions of sketches in the list will never have a problem and some sketches that infrequently experience the problem won’t be in the list. (This is unlike sketches that have USB removed, which will always require a special procedure.)

More details The problem results in the coincidence of a sketch writing to, during a specific 120ms window, a location in upper RAM that the bootloader has reserved as a "magic key" used to indicate that it needs to go into command mode to allow an upload.

This is a specific location (RAM addresses 0x800 and 0x801) but when the compiler builds a sketch there’s nothing informing it that this location may be used for bootloader purposes, so a running sketch may also end up using it for a global or local variable, stack, heap, or other purpose of its own. It’s a case of one hand not knowing what the other is doing.

More details here.

Whether a given sketch will assign the location, and write to it during the 120ms bootloader window, is somewhat unpredictable. Since the location is high up in RAM, sketches that use a large amount of RAM (again, either global/static or dynamically allocated) are more likely to, but not necessarily, exhibit the problem.

Having the problem occur can depend on what the sketch is doing when a new upload is attempted. I.e. whether it’s writing to the reserved location. Also, if a given sketch is re-compiled after (even minor) changes to: itself, any libraries it uses, the underlying Arduino environment, or the compiler, then the problem could either start happening or cease because RAM location usage has changed.

Example: ArduboyLife

ArduboyLife

When compiled, this sketch reports:

Sketch uses 11100 bytes (38%) of program storage space. Maximum is 28672 bytes.
Global variables use 1257 bytes (49%) of dynamic memory, leaving 1303 bytes for local variables. Maximum is 2560 bytes.

The size of global variable space used is rather small (the screen buffer is 1K of that), so you wouldn’t be inclined to expect the “magic key” problem. However, this sketch “double buffers” the screen data. For each generation, a 1K screen sized array is allocated as a local variable. The main screen buffer is copied to the array then the array contents are used to calculate and write the next generation to the screen buffer. One of those arrays ends up over the “magic key”.

So when running, at least 2K of the available 2.5K of RAM is constantly being written at the rate the game is running at. If that rate is faster than 120ms per generation, the problem is certain to occur. At slower rates it can still happen if the timing coincides.

However, if the game is paused (either an actual pause, or on one of the startup screens, or holding a button so the status is displayed), a normal successful upload can be performed.

A point of interest is that with many other sketches new screens are being generated and written at a set frame rate even when paused or on a status screen, so pausing has no effect.