New "gotcha" for uploading sketches

I can definitely feel decrepitude creeping up, but here's an experience which I hope might help others and might be useful to beginners across Windows and Linux who suddenly find themselves unable to get a sketch to transfer to their board.

The difference between "Upload" and "Upload using programmer” - skip to “The Bug” to bypass this TL/DR.

For some background, I'll probably catch it for saying this, but this is at least partly down to poor UI design by assuming that everyone knows what everything means what these choices are. While I'm not new to computers (I worked on micros that had less than 1K of DRAM) I am new to Arduino being a bit late to the party. So I’m playing catch-up designing projects I never thought practical this side of a few $100 and are now well within reach.

I've worked across a lot of GUIs over the years, some good, some awful and some worse. One of things that always appealed to me with MacOS long before it was BSD based even, and even when it was still the Lisa, was the cohesive and sensible design. A lot of thought went into everything to make it as human-friendly as possible.

I won’t explain all those choices because they are probably familiar but one of the ones that always stayed with me echoed an experience I had when writing BASIC for other people to enter. As a young programmer I thought using variable names like “r1” and “l1” was a good idea.Most of you are probably cringing at that suggestion, but this was almost half a century ago and things were a lot different then. These were the days when BASIC was still crude, teletypes had fixed width fonts and arrays were marginally slower than fixed variables because of the de-referencing. That’s my excuse anyway.

It never occurred to me this would be a problem, because I knew what it was supposed to be. This is related to a psychological effect called priming. You know the sort of thing that happens when someone says, “Quick, don’t think of an elephant! Now tell me the first animal you think of!” To which the answer, usually, is “An elephant...” much to the bemusement of your victim. A similar effect is created when we’re programming and we suddenly find ourselves stuck looking at the same bug for hours (or days) and its only when we walk away for a day or week that the problem suddenly jumps out and waves! Happens in puzzle games and even action titles too - we become unaware that we’re repeating the same mistake and we fall into a pattern of not being able to see the wood for the trees.Taking a short break allows our brain to unravel itself a little and the cognitive blind spot we’ve developed (actually learned) is forgotten. It takes time for it to sink in that whatever we were doing, albeit on a subconscious level, was slamming the door shut in our face. This even happens to scientists, medical doctors and even professional pilots so we’re all in good company.

Brains are weird.

While developing a project recently, I found myself (on Windows) struggling to get AvrDude to talk to the bootloader. To make things worse, I have several different boards here and (not for the first time) I was getting one of those “An error occurred while uploading the sketch” problems. I flicked between a couple of machines, googled the **** out if it and came to the conclusion that something on the serial line was causing havoc, plus some other vague theories. (Google isn’t always helpful... it tells you what you think you need to know rather than what you might need to know, hence the “University of Google” jibe.)

Various suggestions ranged from: “It’s a bug in avrdude” to “the baud rate is wrong” and so on which brings me to the criticism of the GUI design and some suggestions (for someone to add to the list of “did you try?”) and also for the developers to consider adding to the error reporting. Who among us loves seeing the Windows “Blue Screen of Death” or a Linux kernel panic and thinks, 0x000000c3:0x34ahdee - oh that’s a .... fault. True there are some that are obvious, but honestly, “Something went wrong” is about as much help to someone trying to find a fault as a poke in the eye with a USB connector.

The Bug

This “bug” manifests itself a little like this:

avrdude: usbdev_open(): did not find any USB device "usb” ..

or just:

An error occurred while uploading the sketch

The Cause

And the cause is... (drum roll) sat behind the keyboard. You see rather than pressing the CTRL-U upload accelerator, I found myself pressing CTRL-SHIFT-U which uploads using a programmer.Obvious right?
Well not really - for reasons in the TL/DR section above, once you start making this mistake you can get into a loop where using the second option seems the right thing to do. Why? Because there are other CTRL-SHIFT accelerators for common functions like opening the serial monitor and plotter.
The error is vague too - coming from avrdude which is only doing what we’ve told it to do and even with the extended debug information in the preferences there’s no real clue what went wrong. I’d got locked in a cycle of pressing CTRL-SHIFT-U without realising it.

The Fix

There are two things that can be done to prevent this. Firstly, assuming avrdude leaves an error code when it exits, some helpful suggestions should really spit out of the IDE. Second (and this is more controversial) someone needs to sit down and have a long-hard look at those accelerators and see if they are a source of error or if some of those options need exposing during everyday development.For example, I assume (correct me if wrong) that most of us don’t need the programmer option at all. Using the USBTiny or a parallel programmer is something that comes with more advanced us. So perhaps it should be turned off by default?

I know these discussions are painful to read, but sometimes it does take a fresh pair of eyes to see something that we're blinded to simply because we're so close to something.

I just use the right-hand arrow on the menu and don't have a problem. I think CTRL-T for autoformatting the code is the only accelerator/keyboard shortcut I use. Maybe others have that issue also, I don't recall seeing much discussion of it over the years.

Here's an extra chapter to the story: in the olden days, the Arduino IDE didn't have "Upload Using Programmer". In those times, the Shift + Upload combination was instead used to provide verbose output during upload. So you'll find some ancient tutorials that recommend that when you're having trouble uploading you use the Shift key to get verbose output. So if you follow those instructions while using a modern version of the Arduino IDE, in addition to whatever the original problem you were having while upload, you'll also have the guaranteed failure of using "Upload Using Programmer" instead of "Upload"!

Firstly, assuming avrdude leaves an error code when it exits, some helpful suggestions should really spit out of the IDE.

It will only give exit status 1, no matter what the cause of the error is, in accordance with standard practice.

I remember seeing the Arduino IDE print a suggestion to check the troubleshooting guide when there is an upload failure. I just did a quick test and didn't see it. I don't know whether it only occurs under specific circumstances or if they removed that suggestion because the troubleshooting guide is so outdated.

Second (and this is more controversial)

Yeah. Once you establish something like that, removing it can get people upset.

someone needs to sit down and have a long-hard look at those accelerators and see if they are a source of error

Years ago, when those outdated tutorials were more prevalent, I saw this issue occasionally, but I haven't for a long time. I just did a search to see if I could find an example of such a tutorial to illustrate my opening paragraph and I couldn't even find one, so I don't think the problem of people being mislead by outdated tutorials is so bad any more. As for your problem of adding Shift to the key combo for no apparent reason, I think this issue is exceedingly rare.

So perhaps it should be turned off by default?

I'm always a fan of programs having configurable keyboard shortcuts. However, the focus of the Arduino IDE is to provide as gentle as possible a learning curve for something that's very complex. One of the ways that's accomplished is by avoiding adding unnecessary complexity to the UI. So I would be hesitant to add a keyboard shortcut customization interface to the GUI. However, there is an extablished method to add advanced configuration options without adding complexity to the GUI: by adding support for setting the options by directly editing a configuration file. I would be all for that approach to adding configurable keyboard shortcuts.