IN THIS CHAPTER

Troubleshooting and fixing common problems

Adjusting the settings on your Raspberry Pi

Fixing audio problems

Mounting external storage devices in the Linux shell

Fixing software installation issues

Troubleshooting your network connection

Connecting using SSH

Many people find that they can just connect up their Raspberry Pi, and everything works fine the first time. Fingers crossed that this will apply to you!

Sometimes people experience problems, however, or want to make more advanced changes to their computer’s settings (also known as configuring it).

In this appendix, we show you how to resolve some common complaints and how to change some of the settings. Hopefully, you won’t need to consult this appendix much, but it might prove valuable if you experience undesirable behavior when you first set up the Pi or if you have an unusual setup.

Whatever you’re doing on the Raspberry Pi (or any computer, come to that), save your work regularly. If it crashes, you’ll be able to pick things up from your last saved version, which will hopefully prevent you from losing too much work.

Troubleshooting the Raspberry Pi

When Sean first started using his Raspberry Pi, he couldn’t connect to the Internet in the desktop environment, although it was working fine in the Linux command line. The problem, it turned out, was an incompatible keyboard. That’s something he never would normally have suspected from the symptom he was seeing. For that reason, we recommend you work your way through this entire 12-point checklist, whatever the problem is and however unlikely it might seem that these steps will fix things. Humor us, and you might be pleasantly surprised!

These steps are listed in a rough order of priority, with the quickest tests and simplest solutions first. You can try any of these solutions at any time, but if you respect this order (more or less), you can minimize any expense and hassle.

1. Be patient.

   With the huge increase in performance over the years, this is less of an issue than it was when the Pi first came out, but it's worth saying nonetheless: When your Raspberry Pi is busy, it can appear to be unresponsive, so you might think it’s crashed. Often, if you wait, it recovers when it finishes its tasks. If it’s not doing anything you particularly care about, you can always just restart the machine, but that loses any data in memory, and it’s not a good idea to reset during operations like software installations (if you can avoid it), because it leaves them half-finished. There is also a risk of corrupting the SD card if you don't shut down properly. Note that the Raspberry Pi has a screensaver built in, so you can recover the Pi from a blank screen by wiggling the mouse (when in the desktop environment) or pressing any key (in the command line). You can use the Shift key so that nothing appears onscreen.

2. Restart your Raspberry Pi.

   Very occasionally, the machine has crashed in a way that we haven’t been able to replicate, so a simple reset can sometimes do the trick. To reset, remove the power, pause a moment, and then reconnect it.

3. Check your connections.

   Switch off your Raspberry Pi and make sure that all its cables are firmly fixed in the right sockets. Start with the source of the problem: For example, if the screen is blank, check the video cable; if the keyboard is unresponsive, check its connection. Chapter 3 is a guide to setting up your Raspberry Pi, including connecting its peripherals and cables.

4. Ensure that your MicroSD or SD card is inserted correctly.

   If your Raspberry Pi’s red PWR light comes on but the green OK light does not flicker or light, the Raspberry Pi is having difficulty using the SD or MicroSD card. In the first instance, check to see that the card is correctly inserted. (See Chapter 3.)

5. Try a new SD or MicroSD card.

   If the red light comes on but the green one still won’t, try a new card. We’ve occasionally had problems with SD cards or MicroSD cards, and with adapters that convert a MicroSD card to fit an SD card slot. You can find a list of SD cards that have been reported as compatible with the Raspberry Pi at http://elinux.org/RPi_SD_cards.

6. Disconnect peripherals.

   Try disconnecting the USB hub, keyboard, and mouse and then restart. Obviously, this won’t help much if the problem you’re experiencing requires input devices for you to replicate it, but it can help to identify any device incompatibilities that might stop the Pi from starting up correctly. If you need to use a keyboard to test whether the problem reoccurs, try connecting it directly to the Raspberry Pi. You could try disconnecting it again after you’ve entered the password or started whatever programs you need to test. If the Pi works fine without anything connected, use the process of elimination (connecting devices one at a time and restarting) to identify which one is causing problems.

7. Try new peripherals.

   If possible, try a new keyboard, mouse, and USB hub, ideally chosen from the list of devices at http://elinux.org/RPi_VerifiedPeripherals that are known to work. Many of the problems people experience are the result of using incompatible devices with the Raspberry Pi, so replacing the keyboard, mouse, and USB hub can resolve a wide range of apparently different problems (including the strange experience Sean had with his Internet connection, mentioned earlier). The previous step can help you to identify which peripherals might be causing problems.

8. Try new cables.

   Especially if you’re having problems with the network connection and audio or visual output, try using new cables to rule out faulty cables as the cause of the problem.

9. Try a new screen.

   If you can’t see anything on the screen but the Raspberry Pi appears to be powering up (the red light comes on and the green light flickers), try connecting to a different monitor or TV. See Chapter 3 for advice on this.

10. Update your software.

    Assuming your Internet connection is working, you can update the operating system and other software on your Raspberry Pi (without overwriting any of your work files) using this Linux command (see Chapter 5):

    sudo apt-get update && sudo apt-get upgrade

11. Try a new power supply.

    We’ve put this near the end of our steps list because it’s probably hardest to do, although dodgy power has been reported to cause a wide range of different problems. If you have a friend with a Raspberry Pi and hers works fine, try using her power supply to see whether it fixes the issues you’re seeing on yours. Alternatively, you might need to buy a new power supply. Note that the Raspberry Pi 3 needs more power than earlier models, so if you've upgraded your Pi but not your power supply, you might experience problems. In the PIXEL desktop, a lightning bolt in the top right of the screen means the Pi is underpowered, and a thermometer means it is over temperature. See Chapter 1 for advice on buying a power supply.

12. Check online for a solution.

    It’s not possible to cover every eventuality here, so if you’re still experiencing difficulties, check the rest of this appendix and then see the troubleshooting guide at http://elinux.org/R-Pi_Troubleshooting, search the forums at www.raspberrypi.org, or search the web with Google or DuckDuckGo (www.duckduckgo.com) for a solution. You’re highly likely to find that someone else has already overcome any difficulties you encounter.

Adjusting the Settings on Your Raspberry Pi

The settings that your Raspberry Pi uses are stored in files on the MicroSD or SD card, and many of them are in a file called config.txt that’s in the /boot directory. You can edit this file directly to change your computer’s settings using a simple text editor called Nano that is preinstalled on your Raspberry Pi.

You might not need to adjust the settings manually. Try using the menus on the PIXEL desktop (see Chapter 3) or running the Raspi-config program, which gives you a menu for changing some of the most frequently used options, including some that are not included in the desktop tool. You can run the program at any time using the following command in the shell:

sudo raspi-config

Raspi-config can help with

• Keyboard configuration: Under Internationalisation Options, you can select your keyboard type. You can also use the Localisation options in the Raspberry Pi Configuration tool, as described in Chapter 3.
• Camera problems: Ensure the camera is enabled in Raspi-config. You can also enable the camera from the Interfaces section of the Raspberry Pi Configuration tool. (See Chapter 3.)
• Audio problems: In Advanced Options, you can force the audio to use the headphone jack or HDMI output.
• Missing space on the card: If you created your card by imaging it, a different process to NOOBS that involves copying a snapshot of the software to the card, you might need to expand the file system to use all the space available. Under Advanced Options, choose Expand Filesystem.

The shell is covered in Chapter 5, but, in brief, it is the way of giving text instructions to your Raspberry Pi. You can open the shell by clicking the Terminal icon at the top of the screen in the desktop environment.

Raspi-config and the Raspberry Pi Configuration tool can make changes for you without your having to edit any configuration files, so it’s more convenient than editing config.txt yourself, and there is less risk of error too. If the option you need isn’t covered on the Raspi-config menu, you need to edit the configuration file manually.

Before you start tampering with the config.txt file, make sure you’ve backed up any important data on your Raspberry Pi. (See “Mounting External Storage Devices” later in this appendix and the section about backing up your data in Chapter 4.) There is a risk that you could, for example, render the screen display unreadable, which would make it difficult to use the Raspberry Pi to access your files.

Using Nano to edit config.txt

To open the config.txt file in the Nano editor, enter the following command in the shell, all in lowercase:

sudo nano /boot/config.txt

The Nano text editor, with config.txt open, looks like Figure A-1.

Use the cursor keys to move around the document. At the bottom of the window is a menu explaining Nano’s controls, where the upward arrow represents the Control key. The shortcuts here are different to what you might be used to, but the main ones you should know about are

• Ctrl+W: Search for a word or phrase. This option (short for Where Is?) enables you to jump straight to the configuration option you want to edit.
• Ctrl+V: Next page.
• Ctrl+Y: Previous page.
• Ctrl+K: Cut the current row of text.
• Ctrl+U: Uncut text, which means paste the text you previously cut at the cursor’s location.
• Ctrl+G: Get help, which provides more detailed instructions.
• Ctrl+O: Write out, or save, the current file.
• Ctrl+X: Exit Nano and return to the shell.

The first thing you’ll notice about config.txt is that the # (hash mark) symbol is used at the start of most lines. This symbol has a special meaning to the computer, which is “ignore the rest of this line.” You might wonder why anyone would enter information into a computer that he wants it to ignore, but this concept is often used (not often enough, some would say) to help the human users of a particular program or file. Any line with a # symbol at the start of it isn’t actually doing anything, but it’s there to guide you as you edit config.txt. Lines like this are called comments. (They are also used in Python, as you see in Chapter 11.)

The first two lines in config.txt say

# uncomment if you get no picture on HDMI for a ↩
default "safe" mode
#hdmi_safe=1

The first line is obviously intended for you to read, but the second line shows the settings you need to use to turn the HDMI Safe mode on. This takes the form that all settings in config.txt do — namely:

setting_name=value

Each setting needs a line of its own. If you wanted to turn the HDMI Safe mode on, you would remove the comment symbol (the hash mark) before the second line, or “uncomment” that line, so that the first two lines now read

# uncomment if you get no picture on HDMI for a ↩
default "safe" mode
hdmi_safe=1

Don’t remove the # symbol from the line of instructions. It remains a comment that’s intelligible only to human readers. You should remove the # symbol only from lines you want the computer to do something with.

Just taking out that single hash mark makes all the difference! Save the file (Ctrl+O) and reboot the computer, and Safe mode is activated. You can reboot the Raspberry Pi with the following command:

sudo reboot

If you need to disable a setting, you can just put a # symbol in front of it again to turn its line into a comment that the computer will ignore.

You can add your own comments too. It’s a good idea to add a line starting with a # symbol to remind yourself what you changed and when, in case you need to change the settings back later.

Fixing Audio Problems

In the desktop environment, you can use the Speaker icon in the top right to adjust the volume of sound and mute or unmute it. In the command line, you can call up a utility to adjust the sound using this instruction:

sudo alsamixer

Use the cursor keys or the mouse scroll wheel to adjust the volume level.

The sound output device is automatically detected. Note that if you're using HDMI to connect to a screen, the audio might be directed there by default, even if the monitor does not have speakers. You can use the audio options in Raspi-config (found under Advanced Options) to direct the audio to the headphone jack or the HDMI cable. In LibreELEC (see Chapter 8), you can click the cogwheel at the top of the menu to go into Settings, choose System Settings, and click Audio to find the option to change the output device.

Mounting External Storage Devices

When you plug in an external storage device such as a USB key or flash drive, the desktop environment recognizes it automatically and opens it in File Manager for you. Not so when using the shell. You need to mount the device yourself, which means you need to connect the device to a folder in the directory tree where you want to browse its contents.

If your only goal is to back up your data to an external storage device, it’s probably easier to use File Manager or the SD Card Copier application in the desktop environment. (See Chapter 4.)

To use external storage in the shell, you first need to create a directory that will be the mount point for the USB key, which means when you look in that directory, you are actually looking at the contents of the external storage device. You can reuse this directory, but the first time you mount a device, you need to create the directory. You can create this directory anywhere (including inside your home directory), but it’s conventional to mount temporary devices in the /mnt directory:

sudo mkdir /mnt/usbdrive

Next, you need to investigate the device you’re connecting. To do that, connect your storage device and then enter this command:

sudo fdisk -l

The last character of this command is a letter l (lowercase L), and not a number 1. The output should look something like this:

Disk /dev/mmcblk0: 4025 MB, 4025483264 bytes
4 heads, 16 sectors/track, 122848 cylinders, total 7862272 sectors
Units = sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disk identifier: 0x000714e9

Device Boot Start End Blocks Id System
/dev/mmcblk0p1 8192 122879 57344 c W95 FAT32 (LBA)
/dev/mmcblk0p2 122880 7862271 3869696 83 Linux
Disk /dev/sda: 16.0 GB, 16037969920 bytes
32 heads, 63 sectors/track, 15537 cylinders, total 31324160 sectors
Units = sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disk identifier: 0x1707001e

Device Boot Start End Blocks Id System
/dev/sda1 * 63 31322591 15661264+ c W95 FAT32 (LBA)

This lists the different storage devices that are connected to the Pi. In the preceding example, you can see the first disk (Disk /dev/mmcblk0) is 4025 MB, which is a 4GB SD card, and the second one (Disk /dev/sda) is 16GB, which is a USB key we’ve connected. The important information we need from this is the device name and the partition number, which is shown at the bottom of the output and is sda1.

To mount the drive for the user pi (uid=pi) and the group pi (gid=pi), we then use

sudo mount -o uid=pi,gid=pi /dev/sda1 /mnt/usbdrive

To view the contents of the USB key, you can then use

ls /mnt/usbdrive

To back up your home directory to the USB key, use

cp -R ~/* /mnt/usbdrive

Fixing Software Installation Issues

The apt package manager should enable you to cleanly install and remove software. If software isn’t working, try removing it and then reinstalling it as described in Chapter 5.

Packages often require other packages (called dependencies) to work. The package manager looks after these dependencies for you, but in the event they get broken, you can fix dependencies using

sudo apt-get -f install

Troubleshooting Your Network Connection

In the desktop environment, you can easily test whether your network is working by using the web browser. In the Linux shell, you can test whether it’s working with the ping command:

ping -c 5 www.google.com

This makes five attempts to connect with Google and reports on its success. You should see that five packets were transmitted and five were received if the network is working perfectly. If this fails, try substituting another website address to rule out the possibility that the problem is on Google’s end. Firewalls can sometimes interfere with the ping command, but this is rare. If the command works, it’s a guarantee that the Pi is connected to the Internet.

You can query the network devices on your Raspberry Pi using ifconfig. This shows you the information for eth0 (your Ethernet connection), wlan0 (your Wi-Fi connection, if available), and the local loopback, which is how the Raspberry Pi refers to itself and which you can safely ignore. If there is an inet addr entry (this is not the same as the inet6 addr entry) for eth0 or wlan0, it means your Raspberry Pi has connected to the router and been assigned an IP address successfully.

The Ethernet connection should be automatically activated, but in the event it isn’t, you can manually activate it like this:

sudo ifup eth0

You can deactivate the Ethernet connection using

sudo ifdown eth0

Your Raspberry Pi should automatically connect to home routers using Dynamic Host Configuration Protocol (DHCP), but these tips can help you to identify where the problem lies if you experience difficulties.

If you experience network problems, try a new cable to rule out problems with the physical connection, and make sure your power supply is strong enough for the Raspberry Pi. (See Chapter 1 for more on power supplies.)

See Chapter 3 for advice on configuring your Wi-Fi connection.

Connecting Using SSH

If your Raspberry Pi has a network connection, you should be able to access it with another computer on the same network using Secure Shell (also known as SSH), which is a way to make a secure connection between computers. This can be helpful if you have set up your Pi to use it headerless (without a screen). Here's how to set it up:

1. Change your password.

   To prevent unauthorized access to your Raspberry Pi after a remote connection is enabled, start by changing your password. You can use the Raspberry Pi Configuration tool (see Chapter 3), or see Chapter 5 for instructions on changing the password in the command line.

2. Enable SSH on your Pi.

   Use the Raspberry Pi Configuration tool (see Chapter 3) to enable SSH on the Interfaces tab. Alternatively, use this instruction to create an empty file in the boot directory called ssh and then reboot your Pi:

   sudo touch /boot/ssh

3. Get your Pi's IP address.

   Use ifconfig in the command line to get your Raspberry Pi's IP address (shown as inet addr).

4. Connect from your other device.

   On a Windows PC, for example, you'll need to download an SSH client such as Putty. In Putty, you input the IP address of your Raspberry Pi and click the Open button. You can then use the command line on the Raspberry Pi to manage and fix files, viewing it through your PC screen and using your PC keyboard. Clients are also available for the iPhone/iPad and Android. The Mac doesn't need any additional software, but works through the terminal window. You can find fuller instructions for using SSH on your other machine at www.raspberrypi.org/documentation/remote-access/ssh.

You can only use SSH to access the Raspberry Pi command line, not the desktop.