When things don't seem to be working as expected, it's time to troubleshoot. These are some of the common tools and commands that come in very handy for this process. You can also post in the Adafruit Forums and we'll try and help as well.
If your Pi is not booting at all, this sticky in the Raspberry Pi forums is a good place to start.
Boot Error Code via LED blink
(Pi 4 and Pi 400, but possibly others!)
From https://www.raspberrypi.com/documentation/computers/configuration.html#led-warning-flash-codes
If a Pi fails to boot for some reason, or has to shut down, in many cases an LED will be flashed a specific number of times to indicate what happened. The LED will blink for a number of long flashes (0 or more), then short flashes, to indicate the exact status. In most cases, the pattern will repeat after a 2 second gap.
Knowing specifics of your operating system and hardware are very useful for troubleshooting. Here are some commands to use to get this information.
To figure out what version of Linux you are running, use:
uname -a
To get hardware details, use the following, cat is used to dump the contents of a file::
cat /proc/cpuinfo
The model info can also be found here:
cat /sys/firmware/devicetree/base/model ; echo
An echo was added to the above since the file apparently does not end on a new line. This just makes the output look cleaner.
There are actually numerous system log files (look in /var/log), but the basic kernel one, accessed with the command dmesg, is the first place to look. There can be a lot of output from running this command. Too much to fit on one screen. One option is to send the output to a file:
dmesg > dmesg.txt
And then you can view that file in a text editor, or upload it to the forums so support there can take a look.
Another option is to "pipe" the output to something like more, which will allow you to paginate through the listing:
dmesg | more
Another useful way is to filter for specific text using grep (the -i ignores case):
dmesg | grep -i some_text
Hmmm. My network cable is not plugged in. Guess that's why eth0 is not ready.
And yet another way - this may be the most useful - is to only show the most recent output by using tail. This is good for when you are trying to do SomeThing and it's not working as expected. Try running the command before doing SomeThing:
dmesg | tail -10
and then do SomeThing and run the command again. This way you can see the operating system kernel messages associated with what happened when you did SomeThing. The -10 limits it to the last 10 lines.
For example, how do I know my Raspberry Pi is even seeing my USB Thermal Printer when I plug it in? Well, run the command before plugging in the printer:
Nothing exciting, just boot messages about Bluetooth. What we are really interested in is what happens after plugging the printer in:
Cool. It saw a new USB device being attached, recognized it as pl2303 and attached it to ttyUSB0. That is all as expected. But if you got the same thing as the first output again - then nothing happened and something is wrong. Or maybe there would be messages that are flagged more as *error*, etc.
Note:
- The numbers relate to time when message was logged. You can generally ignore them for basic checks like this.
- You can change
-10to some other value to increase/decrease the number of lines shown.
Is my I2C device there?
A lot of breakout boards use I2C to communicate with the Raspberry Pi. Each I2C devices has a unique address. A quick way to check that the Raspberry Pi can see the connected device is to scan for the addresses of everything attached. To do that, use:
i2cdetect -y 1
The numbers that show up are the addresses, in hex. For the example above, something with the address 0x48 is seen. To find out what address your device should have, check the product page, or The List:
Raspberry Pi's have gotten more power hungry over the years, with the current high end models recommending a whopping 2.5 amps! The actual current consumption will vary depending on what the Raspberry Pi is doing, but you need to accommodate the worst case scenario. Maintaining a good voltage of 5V is also important. Some power supplies will drop in voltage as current draw goes up - even if they claim they are rated for that current.
It actually can be difficult to know. At a minimum, look for the label on the supply and check its voltage and current rating.
The power supply above has an output of 5.25 volts and is rated for 2 amps.
If you're using a (earlier) Pi 4, use the Official Pi Power Supply
Original manufactured Pi 4's had a mistake on the USB connector which causes proper "USB Power Delivery (PD)" supplies to get confused and not power the Pi 4. You can tell which version you have by checking this guide.
If you have an older Pi, try using the official Pi Power supply or USB Micro B to USB C adapter attached to a standard micro USB power supply
Make sure USB cable is good.
Another important factor for power is the USB cable being used to deliver it to the Raspberry Pi. Cheap charge only cables may have conductors that can only carry a couple 100 milliamps. Even if you have a good power supply, these cables will fail to adequately deliver it to the Raspberry Pi.
This is even more difficult to check. Ideally, the cable itself will have a printed label that will indicate the gauge of the wires used.
The units will probably be AWG (American Wire Gauge). For the cable above, the wires are 28 AWG. For Raspberry Pi usage, that's probably about as thin as you want to go.
If you can't find a label on your USB cable, the only other option is to try other cables.
Use an updated operating system image.
The Raspberry Pi Foundation typically roles out a new release of their operating system with each new Raspberry Pi model. These updated releases are needed to be able to boot the latest models. So make sure you are running latest software with latest hardware.
You should get your operating system images from here:
If you are just starting out, it's best to steer clear of the Third Party images and use the main Raspbian distribution. Installation onto and SD card has become very easy:
Use a text editor, not a word processor, for configuration files
If you are doing setup and configuration by directly editing text files, as shown in this guide, then use a simple text editor, like Notepad, and not a full featured word processor, like Pages, Word, etc. A "text editor" edits text and nothing else, whereas a "word processor" allows for all kinds of formatting, like making text bold, inserting images, etc. A word processor can add additional content to the file which can make it appear unreadable when the operating system tries to access it.
