You have your spangly new Arduino board, you've installed the software, and you plug it in. Nothing happens. Diagnosing problems may be a little tricky for the beginner, so what hoops should you go through to try and work out where the problem is and why you can't get your board working?
Note: this is an FAQ. Do not use it to ask about your specific problem. Comments will be deleted. Either ask a new question detailing all the steps you have taken, or, better, discuss your problem in chat.
Getting Arduino and Arduino-like boards working properly under Linux can be a troublesome task if you are not familiar with how Linux works.
So I am going to introduce you to some of the basic tools you will need to work out why your board isn’t working as you’d like it to work.
The majority of problems a new user is faced with boil down to one simple thing: permissions. A normal user doesn’t, by default, have permission to talk to much in the way of hardware. That include serial ports and USB serial emulation ports (FTDI, etc). Fortunately granting permission to your user to access the serial ports is a simple matter, and one that you should always do by default to make life much simpler for you. This is done through a Linux permission facility called groups. A group is a name given to a collection of users, files, devices etc., that go together. Permissions can be granted on files to the group that it belongs to, and users that are in that group can access those files. On Linux most devices are just files.
The serial ports are all in the default group dialout, but your normal user isn’t. So you need to add your user to that group. Only root has the permission to do that, so use sudo to execute the commands as root. If you don’t have access to root through sudo or some other means then you will have to seek the assistance of an administrator who does have permission.
First add your user (you’re called fred, right?) to the dialout group:
$ sudo usermod -a -G dialout fred
The “-a” is of vital importance. That says “Add the user to these groups”. Without it you have “Set the user’s groups to be this list”. If you omit the “-a” by accident you will remove your user from any other groups before setting them to be in the dialout group. That means you will never be able to run sudo again. So be sure not to miss that one out, eh?
Now that has only changed the configuration files (/etc/groups in this case) and the change hasn’t actually had any effect yet. The groups are only set when you log in to the computer, so you will either need to log out and back in again or (a more definite solution, especially if you have auto-login turned on) reboot the computer.
Now you should be in the dialout group:
(before)
$ id
uid=1000(fred) gid=1000(fred) groups=1000(fred),4(adm),24(cdrom),27(sudo),30(dip),46(plugdev),113(lpadmin),128(sambashare)
(after)
$ id
uid=1000(fred) gid=1000(fred) groups=1000(fred),4(adm),20(dialout),24(cdrom),27(sudo),30(dip),46(plugdev),113(lpadmin),128(sambashare)
Now try it, see if that has got you working.
Next step, if that doesn’t fix your problems, is to see if the computer knows about the Arduino. First look to see if there is a device file for the Arduino and if it has the right permissions:
$ ls -l /dev/ttyACM* /dev/ttyUSB*
ls: cannot access '/dev/ttyUSB*': No such file or directory
crw-rw---- 1 root dialout 166, 0 Aug 24 11:05 /dev/ttyACM0
Don’t worry about the “cannot access…” message unless you get two of them. There are two sets of device names that the Arduino could be under depending on which type it is. Genuine UNO and similar boards (the ones with the ATMega16U2 chip as the USB interface) are /dev/ttyACM*. Clones using the CH340G, and FT232 based boards appear as /dev/ttyUSB*. We just asked for both there, so it complained when it couldn’t find any entries for one of the types. Which is fair enough. If you get:
$ ls -l /dev/ttyACM* /dev/ttyUSB*
ls: cannot access '/dev/ttyACM*': No such file or directory
ls: cannot access '/dev/ttyUSB*': No such file or directory
however, then worry. That can’t find anything at all. The computer doesn’t know the Arduino exists.
One thing to check is the permissions on the files that have been listed above. You see the word “dialout” in the list? That’s the group that the device belongs to, and it should match the group you added yourself to earlier. There are times when it may say “tty” instead. This is because some other program has grabbed the device and is using it to allow remote access to the computer through that serial port. For that you need to make sure that there are no agetty processes using that port. How you do that is very much down to your version of Linux. Modern Debian based systems (such as Debian Jessie and Ubuntu) use systemd to manage it. You can examine what is running on your system using
$ systemctl status
That returns a tree of all the services that your system is running. Look through that list to see if there are any “serial-getty” services running. If there are you should remove them:
$ sudo systemctl stop serial-getty@ttyACM0
$ sudo systemctl disable serial-getty@ttyACM0
While you’re there look through the list for another troublesome member: ModemManager. This is a program used to dial out to the internet through old-fashioned modems (you know, the kind that go beep beep beep squark squeek squark ) or USB DSL modems (that no one uses any more, we’re all wireless now. Remember the old green “frog” modem from way back when…?). That has a habit of grabbing a serial port as soon as it appears and trying to configure a modem attached to it. While that’s happening nothing else can access the serial port. It’s especially a problem with boards like the Arduino Leonardno or chipKIT Lenny which create a new serial port when they enter programming mode. So unless you really need the functionality that ModemManager provides you should just remove it:
$ sudo apt-get remove modemmanager
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following packages will be REMOVED
modemmanager
0 to upgrade, 0 to newly install, 1 to remove and 138 not to upgrade.
After this operation, 2,826 kB disk space will be freed.
Do you want to continue? [Y/n] y
(Reading database ... 180827 files and directories currently installed.)
Removing modemmanager (1.4.12-1ubuntu1) ...
Created symlink from /run/systemd/system/ModemManager.service to /dev/null.
Removed symlink /run/systemd/system/ModemManager.service.
Processing triggers for man-db (2.7.5-1) ...
Processing triggers for hicolor-icon-theme (0.15-0ubuntu1) ...
Processing triggers for dbus (1.10.6-1ubuntu3) ...
Another useful tool is lsusb. This lists the USB devices that are connected to your computer. You should find your Arduino listed there. This is especially useful for boards that don’t present a serial port for programming, but we’ll cover those in more depth a little later on.
$ lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 002: ID 80ee:0021 VirtualBox USB Tablet
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Nothing much on this computer. Well, actually I am using a virtual machine for this, as you can see by the VirtualBox USB Tablet entry. But let’s connect my Arduino UNO:
$ lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 004: ID 2341:0001 Arduino SA Uno (CDC ACM)
Bus 002 Device 002: ID 80ee:0021 VirtualBox USB Tablet
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
So we know that the operating system has identified it. You can find out lots more information about it if you so desire, with:
$ lsusb -v -d 2341:0001
That gives you all the device descriptors for the device. Tells you all you could ever want to know about the information the board sends to the computer when it is connected.
Another useful tool is dmesg. This is the system message log viewer and can be used to find out exactly what is going on with your computer. It has a useful “keep running” mode specified by the flag -w. I like to run dmesg and then press return a few times to create a breakpoint in the listing, then plug in the board I am diagnosing to see just what the messages are that pertain to that board:
$ dmesg -w
[ 0.000000] Initializing cgroup subsys cpuset
[ 0.000000] Initializing cgroup subsys cpu
[ 0.000000] Initializing cgroup subsys cpuacct
[ 0.000000] Linux version 4.4.0-24-generic (buildd@lgw01-12) (gcc version 5.3
... lots of stuff spools past ...
[ 19.425870] NFS: Registering the id_resolver key type
[ 19.425883] Key type id_resolver registered
[ 19.425885] Key type id_legacy registered
<press return a few times>
<connect Arduino>
[ 131.232511] usb 2-2: new full-speed USB device number 3 using ohci-pci
[ 131.519307] usb 2-2: New USB device found, idVendor=2341, idProduct=0001
[ 131.519312] usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=220
[ 131.519315] usb 2-2: Product: Arduino Uno
[ 131.519317] usb 2-2: Manufacturer: Arduino (www.arduino.cc)
[ 131.519319] usb 2-2: SerialNumber: 64934333235351B002E0
[ 131.605485] cdc_acm 2-2:1.0: ttyACM0: USB ACM device
[ 131.613792] usbcore: registered new interface driver cdc_acm
[ 131.613796] cdc_acm: USB Abstract Control Model driver for USB modems and ISDN adapters
Press CTRL+C to terminate the listing.
If nothing appears when you connect the Arduino then there is something fatally wrong. My money is either on a faulty cable (some cheap cables on eBay only have power wires and no data wires) or the Arduino itself is completely dead.
More likely though you get error messages. I can’t replicate them right now (I don’t have a faulty Arduino) but they usually pertain to things like “device not accepting address” and “Error -71”. This is usually caused by bad USB communication. It may, again, be a faulty cable, or it may be that the USB interface chip is not working right. Maybe the crystal has drifted and it’s not running at precisely the right frequency. Maybe it’s a cheap CH340 chip that has failed. Maybe the firmware on the ATMega16U2 has become corrupted.
If all that checks out fine so far and you still can’t upload a sketch there may be something even more fundamentally wrong with your Ardunio board. Maybe it’s time to look to see if there is actually any communication happening. I find the program minicom invaluable, although you could use the ghastly Serial Monitor in the Arduino IDE.
First you need to disable the main chip on your Arduino. You can do this simply by connecting the RESET pin to GND with a piece of wire. Or you can hold the RESET button down, but that means you’re then typing one-handed. That stops the main chip from interfering in any way with the serial communications while you’re testing it. It can also prevent any damage to the chip while testing.
The second step is to connect the TX and RX pins together (pins 0 and 1 usually) with another piece of wire. You are now in what is known as a loopback mode. Any serial data you send to the board should be sent straight back to where it came from. So now fire up minicom and try it out (you will need to install it first of course with sudo apt-get install minicom).
$ minicom -D /dev/ttyACM0 -b 115200
Of course replace the /dev/ttyACM0 with the real device name for your board. The -b 115200 is the baud rate, though that is pretty much irrelevant since we’re not actively communicating with an external device.
Now you should be able to type some gibberish and get some gibberish back. If you do then communication is working fine, and the problem most likely lies within the target MCU – maybe the bootloader has become corrupted and needs re-flashing, or the chip has died.
CTRL+A, X gets you back out of minicom again.
If you didn’t get your gibberish back, or you got back different gibberish than you sent, then there is definitely something up with the serial communications. The main culprit is, again, the USB interface chip.
All this, of course, has been focusing on the traditional Arduino style interface with a USB serial port of some form. Not all boards give you that though. Some, such as the Launchpad boards, use a hardware programmer on the board, and that doesn’t always give a serial port – certainly the programming isn’t done through the serial port. To gain access to those (again by default you don’t have permission to access the low-level devices) you have to get deeper into the operating system.
For these you need to make modifications to the configuration of a system called udev. This is a management system for the devices on your computer and is used to control what happens to them when they are plugged in. One of the things you can do is set the permissions on that device so people can actually access it.
The system is configured by a set of rules in “rules files”. These are stored in /etc/udev/rules.d and there should already be a few in there for other purposes. You will need to, as root, create a new file to put your rules in.
$ sudo nano /etc/udev/rules.d/50-boards.rules
The most important thing to know is the VID and PID (Vendor ID and Product ID) of your board. You can get that from lsusb as above (it’s the vvvv:pppp bit – v = VID, p = PID). You can then feed that into a simple rule, such as:
ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="0033", MODE="0660", GROUP="plugdev"
There we are matching a vendor (04d8 = Microchip) and product (0033 = PICkit2) and assigning it to the group plugdev (make sure you are in that group – default users should be already) and allowing the group members read and write access to it (MODE="0660"). Save that file and restart udev for the changes to take effect (or reboot your computer if you like):
$ sudo /etc/init.d/udev restart
Now plug the device in and you should have permission to access it.
Ok, the first thing you need to do is identify the kind of board you have. I don't mean is it an Uno, a Mega, or one of Intel's brief forays into the Arduino world - I mean what kind of USB interface the board has.
Boards can be loosely grouped into two categories - CDC/ACM and Custom USB Profile.
Current versions of the official Arduino Uno and Mega are both CDC/ACM devices (CDC/ACM, by the way, stands for Communication Device Class / Abstract Control Model). This means that between the main microcontroller (ATMega328P, ATMega2560, etc) there is another microcontroller - usually an ATMega16U2. This takes the serial data from the main microcontroller and sends it to the PC over USB using the USB CDC/ACM protocol.
You can identify these boards by the chip that is nearest the USB connector.
That small black chip with the Atmel logo on it is the USB interface chip.
Boards of this style have the USB drivers included in the Arduino IDE. If you have installed the IDE properly the drivers should have been installed for you automatically. Also Windows 10 (finally) contains "class compliant" drivers for CDC/ACM, so no drivers actually need to be installed for these boards anyway (installing the Arduino ones doesn't hurt, though, and helps it to show the right board name in the device manager).
The other category of board, "Custom USB Profile", use different chips. And there's lots of different chips it can be using.
Early Arduinos and some other makes of board (such as chipKIT boards from Digilent) use the Future Technologies RT232R chip. This sometimes looks at first glance like the Atmel chip above, but is very very different. You have to check the number on it to be sure. Other times a different package is used and it's obvious it's different.
Then there are the cheap clone boards you get on eBay and Amazon. These, more often than not, use yet another chip - the CH340G. This is a fraction of the cost than the FT232R or ATMega16U2 chips, which is why cheap boards tend to use them. They're also less reliable and harder to get working in some operating systems (most notably OS X).
For these kind of chips you need to install the right driver for the specific chip you have. For the FT232R chips that's not too hard - Future Tech have the drivers on their website.
The CH340G driver is harder to find from a reliable source.(someone with more knowledge please fill this in)
Ok, so your board is a CDC/ACM based one, or you are sure you have installed the right drivers. The next thing to check is if the board is even being seen by the operating system.
When you plug it in for the first time it should pop up a bubble saying it found new hardware:
Or something similar to that. It should also make a noise.
If neither of those happen then it's likely the computer isn't seeing the device at all. This sounds more like a hardware problem than a Windows problem.
The first thing to try is to plug the Arduino into a different port. Even better is, if you have access to one, plug the Arduino into an entirely different computer. What you are trying to diagnose here is if the problem is related to the Arduino/USB cable or to the computer/USB port.
If it works in a different computer but not your computer then there is something wrong with your USB ports. It may be that you are using a computer that is locked down (such as in a school or an office) where the "group policy" has been configured to not allow any USB devices to be used (chiefly to prevent people bringing in memory sticks with viruses on them). If this is the case you will have to consult with the powers that be in your organisation to get your device authorised. If not, then you may have more luck plugging your Arduino into a powered USB hub instead of directly into your computer (it may be that the computer can't provide enough current for the Arduino to run properly).
If it's failing equally as badly on another computer / port then you should start looking at the USB cable and the Arduino.
It is quite common for small battery powered devices that are charged through USB to be shipped with cheap cables. These are cables that only have the +5V and GND wires in them - no D+ and D- wires. For obvious reasons these can't be used with an Arduino: with no data wires how can the computer see it? However it's generally impossible to tell these cables apart from a full USB cable.
If you happen to be using one of these cables without knowing it you'll get a power light on the Arduino and not much else. So you need to swap the USB cable for another one - preferably one you know works properly. If it suddenly springs into life then you know you have a bad cable. Throw the old one away - it's almost useless - or stick a label on it saying "power only" so you know what it is.
Another thing to mention in passing: I have known some of the early Arduino boards to have lower quality USB connectors on them (Uno R2). These sometimes have trouble connecting properly with some cables (not all), so maybe a better quality cable may fix the problem, or tweaking the contacts within the USB connector with a needle may help.
Right - the other direction to go in is if it does identify that you plugged a board in, but can't install the drivers. Maybe it's saying the device failed, or it can't find the drivers.
Step one is to go into the device manager and look for an "Unknown Device":
That is most likely the Arduino. You should be able to inspect all the data for it to find the USB Vendor ID (VID) and Product ID (PID). If those are showing up as corrupted, not available, or FFFF, then your Arduino has a serious problem and Windows cannot work out what it is. In this case it may be that the USB interface chip has failed (there have been unsubstantiated rumours that shorting 5V to GND on an Uno R3 can kill the ATMega16U2 chip). There's not much you can do when that has happened.
If you can find reasonable data in the device manager, as in the image below, then it's going to be a case of trying to fix (or find the correct) driver, since you may not have the right one installed. Also note that some other board manufacturers use the same VID and PID as the Arduino and having their drivers installed could cause the Arduino to not function properly - you should uninstall their drivers first, or manually set the Arduino to use the proper Arduino driver.
MAC OS X
Getting an Arduino to work with OS X can be as simple as "plug and play" to almost impossible. It depends on which version of OS X you are using, and more importantly, what "kind" of Arduino you have. "Kind" means, is your Arduino a genuine Arduino, a "counterfeit" claiming to be the real thing or a cheap "knock off" using the CH340 USB interface.
Your first step is to identify exactly what you've got. If you have a CH340 chip on your Arduino like the one on this cheap "knock off" of an Arduino UNO, then you'll need to install a driver so that OS X can communicate with it.
Download a CH340 driver for the exact version number of OS X you are using and install it as per the manufacturer's instructions. If you download a driver for the latest version of OS X and install it on an older version of OS X, it may install just fine. When you plug in your Arduino device, OS X reads the .kext file and sees it's for a newer version of the OS so it doesn't load it, and never will (unless you upgrade to that exact version someday).
Here is a picture of a "counterfeit" Arduino UNO. It uses the ATMEL MEGA 16U2 chip as a USB interface which is "suppose to work" with OS X's existing drivers. If you have one of these and it's "not working", don't bother installing the FTDI drivers because that won't solve your problem.
Unfortunately, what works on one version of OS X doesn't always work on another version. Solutions are usually specific to OS X versions, but there are some common troubleshooting steps to follow once you know what Arduino USB Interface you have and you've installed the correct driver (if required).
Verify that OS X is recognizing your device.
You should see something like this:
If you plugged in your Arduino and is not listed somewhere on the USB Device Tree, I can guarantee it will not show up in the Arduino IDE Serial Port Menu. It won't show up in the /dev list using terminal either. Please keep in mind that System Profiler does not refresh automatically. If you un-plug your Arduino and plug it back in again, you have to MANUALLY re-fresh System Profiler to see the current data
If you still can't get your Arduino working, try swapping the USB cable or using a different computer / OS to see if it works.