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.
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.
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.
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.
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.
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.
@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.
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.)
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.
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.
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.
Thanks for the suggestion, but I don’t think that’s it. The red charging light comes on when I plug it in. Also, when I hit “Upload”, the screen of my Arduboy changes, like it’s trying to do something.
The red charging light will come on if it has power, but if it’s not getting data then it won’t program.
Can you confirm the usb cable you are using can transfer data to other devices like an external hard drive or something like that?
If you plug it in and don’t get the green light to flash once, and don’t hear the usb chime then you aren’t getting a data connection. So, theoretically the screen shouldn’t react to the programming step.
Unfortunately, as you may notice you are using a now outdated guide which uses the old Arduboy library. The Arduboy2 library has the flashlight mode built into it so it can help to try and recover it, so that won’t work in this situation.
The reset button method should always work, but it won’t matter if you aren’t getting any usb connections.
Are you by any chance connecting through a USB hub? If you are sure about the cable, you should connect the cable directly into the PC.
What OS are you using? Are you on PC or Mac?
Let me know, if you try all this and still can’t figure it out then contact me via arduboy.com/contact and I can help you directly from there.
Just to be clear, the original Arduboy library also has flashlight mode included in its begin() function (although it doesn’t protect against the very rare case of an interrupt clobbering the bootloader magic key.)
Update - I was wrong about the screen changing when I hit Upload. Nothing happens. I must have imagined that.
I have tried 5 different cables - but only 1 of those are for sure supposed to allow data - the others are likely only for charging. Unfortunately, I do not have any other devices that use a micro usb, so I cannot test the cables on any other device.
I am not using a USB hub, either. I’m plugging it straight into my PC.
Also, I do know that the game-making guide is out of date. However, it was not out of date back when I used it.
Okay. So…turns out it was the cable all along. Derp.
After trying my 5 cables, I felt certain that it couldn’t possibly be a cable issue. However, I asked a friend if he had a cable I could borrow to try at least one more time - and sure enough, it worked.
I greatly appreciate those of you that took the time to respond.
While I certainly feel silly, this issue led me to discover some new things about how these things work, so it wasn’t all for naught. Thanks again.
Unfortunately a lot of USB cables these days are made without the data lines because USB been misapropriated as a means to charge devices without providing any kind of data transfer, which has lead to a lot of ‘charge only’ cables being produced (because they’re cheaper). In other words, it’s not your fault, it’s the market’s fault.
(I think that technically by not providing data lines these cables don’t actually meet the proper USB standards, but don’t quote me on that, I can’t verify that claim at the moment.)
I’m going to leave this link here in case it’s useful for people with similar issues in the future: