Problem

You want to connect your Raspberry Pi to the Internet using a wired network connection.

Solution

First, if you have a Raspberry Pi model A, A+, or Zero, there is no RJ45 connector for Ethernet. In this case, your best option for Internet access is to use a wireless USB adaptor (see Recipe 2.5).

If you have a Raspberry Pi model B, plug an Ethernet patch cable into its RJ45 socket and then connect the other end to a spare socket on the back of your home router. Figure 2-1 shows an original Raspberry Pi 1 where the Network LEDs are next to the audio socket. On a Raspberry Pi 2, the LEDs are built into the Ethernet socket itself.

Figure 2-1. Connecting Raspberry Pi to a home hub

The network LEDs on your Raspberry Pi should immediately start to flicker as the Raspberry Pi connects to your network.

Discussion

Raspbian is preconfigured to connect to any network using Dynamic Host Configuration Protocol (DHCP). It will automatically be assigned an IP address as long as DHCP is enabled on your network.

If the network LEDs on your Raspberry Pi do not light up when you plug it into the home router, check that you have not used the Uplink RJ45 socket on the hub or try a different cable.

If the LEDs blink but you cannot connect to the Internet on your Raspberry Pi using a browser, check that DHCP is enabled on your network management console. Look for an option like that shown in Figure 2-2.

Figure 2-2. Enabling DHCP on your home hub

See Also

To connect to a wireless network, see Recipe 2.5.

Problem

You want to know the IP address of your Raspberry Pi so that you can communicate with it, whether connecting to it as a web server, exchanging files, or controlling it remotely with SSH (Recipe 2.7) or VNC (Recipe 2.8).

An IP address is a four-part number uniquely identifying a computer’s network interface within a network. Each part is separated by a dot.

Solution

To find the IP address of your Raspberry Pi, you need to issue this command in a Terminal window:

$ hostname -I
192.168.1.16

This is the local IP address of your Raspberry Pi on your home network.

Discussion

A Raspberry Pi can have more than one IP address (i.e., one for each network connection). So if you have both a wired connection and a wireless connection to your Pi, it would have two IP addresses. Normally, however, you would only connect it by one method or the other, not both. To see all the network connections, use the ifconfig command:

$ sudo ifconfig

eth0      Link encap:Ethernet  HWaddr b8:27:eb:d5:f4:8f
          inet addr:192.168.1.16  Bcast:192.168.255.255  Mask:255.255.0.0
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:1114 errors:0 dropped:1 overruns:0 frame:0
          TX packets:1173 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:76957 (75.1 KiB)  TX bytes:479753 (468.5 KiB)

lo        Link encap:Local Loopback
          inet addr:127.0.0.1  Mask:255.0.0.0
          UP LOOPBACK RUNNING  MTU:16436  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)

wlan0     Link encap:Ethernet  HWaddr 00:0f:53:a0:04:57
          inet addr:192.168.1.13  Bcast:192.168.255.255  Mask:255.255.0.0
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:38 errors:0 dropped:0 overruns:0 frame:0
          TX packets:28 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:6661 (6.5 KiB)  TX bytes:6377 (6.2 KiB)

Looking at the results of running this ifconfig, you can see that the Pi in question is connected by both a wired connection (eth0) with an IP address of 192.168.1.16, and a wireless one (wlan0) with an IP address of 192.168.1.13. The lo network interface is a virtual interface that allows the computer to communicate with itself. 

Another way to find your IP address is to connect to the management console of your home hub and find the LAN page and then the IP table. There should be a device listed called raspberrypi with its IP address next to it.

See Also

Wikipedia has everything you want to know about IP addresses.

Problem

You want to set the IP address of your Raspberry Pi so that it does not change.

Solution

To set the IP address of your Raspberry Pi, whether using a wired or wireless network, you need to edit the configuration file /etc/network/interfaces.

If you view your /etc/network/interfaces file using the following command:

$ more /etc/network/interfaces

it should look something like this:

auto lo

iface lo inet loopback
iface eth0 inet dhcp

allow-hotplug wlan0
iface wlan0 inet manual
wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
iface default inet dhcp

This is telling you that Raspbian is aware of three network interfaces on your Raspberry Pi, each starting with the word iface.

lo

Loopback. You can ignore this.

eth0

A network connection using the Ethernet socket.

wlan0

A network interface using a USB WiFi adapter or the built-in WiFi hardware of the Raspberry Pi 3.

Your Raspberry Pi will have a different IP address for each network connection. In this example, you will just make the IP address for the Ethernet interface static. If you want to do the same for the WiFi interface, just edit that entry in the interfaces file instead.

To edit this file, type the following command:

$ sudo nano /etc/network/interfaces

First, decide on an IP address to use. You need to pick one that is both unused by any other machine on the network and within the allowed range of IP addresses for your home hub. In this case, I will use 192.168.1.116.

Modify the contents of the file, changing the word dhcp to static and adding the following lines:

    address 192.168.1.116
    netmask 255.255.255.0
    gateway 192.168.1.1

With the file changed as shown here, the static IP address of 192.168.1.116 has been assigned to the eth0 interface.

auto lo

iface lo inet loopback
iface eth0 inet static
    address 192.168.1.116
    netmask 255.255.255.0
    gateway 192.168.1.1

allow-hotplug wlan0
iface wlan0 inet manual
wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
iface default inet dhcp

For most networks, the netmask setting should be set to 255.255.255.0 and the gateway should be the IP address of your home router itself. This will be the same as the IP address you use to connect to the admin console of your router.

After you edit and save the file, run the following commands to clear out all the existing DHCP leases, and restart your Pi so that the changes will take effect.

$ sudo rm /var/lib/dhcp/*
$ sudo reboot

Discussion

Internal IP addresses are typically something like 192.168.1.116, where just the last number is changed for each of the different computers. Another common format for internal IP addresses is 10.0.0.16.

See Also

Wikipedia has everything you want to know about IP addresses.

Problem

You want to change the network name of your Raspberry Pi so that it’s not just called “raspberrypi.”

Solution

Changing the name of your Pi is pretty straightforward. There are just two files that need to be changed.

First, edit the file /etc/hostname. You can do this by opening a Terminal window and typing the command:

$ sudo nano /etc/hostname

Replace “raspberrypi” with a name of your choice. This should remain one word, without any punctuation or unusual characters (including the _ character.)

Second, open the file /etc/hosts in an editor using the command:

$ sudo nano /etc/hosts

The file will look something like this:

127.0.0.1       localhost
::1             localhost ip6-localhost ip6-loopback
fe00::0         ip6-localnet
ff00::0         ip6-mcastprefix
ff02::1         ip6-allnodes
ff02::2         ip6-allrouters

127.0.1.1       raspberrypi

Change the text at the end that uses the old name (“raspberrypi”) to the new name.

Restart the Pi, and you should find that the name has changed when you view it on the network from another computer.

Discussion

Changing the name of your Pi can be very useful, especially if you have more than one Pi connected to your network.

See Also

See also Recipe 2.3 to change the IP address of your Raspberry Pi.

Problem

You want to connect your Raspberry Pi to the Internet using a USB wireless adapter.

Solution

If you have the latest version of Raspbian, then setting up WiFi is really easy. Just plug in a USB WiFi adapter and then click on the Network icon at the top right of your screen (Figure 2-3). You will then be presented with a list of WiFi networks. Select your network and you will be prompted to enter your Pre Shared Key (password). Enter your password, and after a while, the Network Icon will switch to show the standard WiFi symbol and you will be connected.

Figure 2-3. Connecting to a WiFi network

If you have an older distribution of Raspbian, you will have to use the WiFi Config utility with a shortcut on the desktop. If you are not using a recent distribution, then you should update to one anyway (see Recipe 1.4).

If you have a Raspberry Pi 3, then the the board already has WiFi hardware built-in. If you have an older Raspberry Pi, plug a compatible USB wireless adapter (most are compatable) into one of the USB sockets on your Raspberry Pi, and launch the WiFi Config utility (Figure 2-4). You will find the WiFi Configuration tool under the Preferences section of the Raspberry start menu. Then click the Scan button to search for access points. Double-click on the access point (for your home hub) that you want to join and then enter the password in the PSK field.

Finally, click Connect to join the network.

Figure 2-4. WiFi Config—scanning for networks

Discussion

USB WiFi adapters can use quite a lot of power, so if you find your Pi rebooting unexpectedly or not booting properly, then you may need to use a larger power supply for it. Look for a supply that is 1.5A or more.

If you’re using a keyboard and mouse as well, you may find you’ve run out of USB sockets. In that case, a USB hub is the answer. Choosing a hub with its own power supply will also help with the power problem.

If you are using your Raspberry Pi as a media center (see Recipe 4.1), then there will be a settings page to allow you to connect the media center to your network using WiFi.

You can also set up a wireless connection by using just the command line. To do so, first edit the file /etc/network/interfaces by using the command:

$ sudo nano /etc/network/interfaces

Then find the section of the file relating to the wlan0 interface and change it to be:

allow-hotplug wlan0
iface wlan0 inet dhcp
wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf

The first line specifies that the WiFi connection should automatically start when a USB WiFi dongle is inserted. The second specifies that the Raspberry Pi should allocate the IP address using DHCP. If you want to use a static IP address, replace the word dhcp with static and add in the extra lines described in Recipe 2.3 to allocate a static IP address.

The final line specifies the location of a supplicant file. This is the file that actually contains the SSID (network name) and PSK (password) for your wireless network. So, next you will edit this file using the command:

$ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

Modify the file, setting the values of ssid and pskfoobar for your wireless network.

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
network={
        ssid="My-Network-Name"
        psk="My-password"
        proto=RSN
        key_mgmt=WPA-PSK
        pairwise=TKIP
        auth_alg=OPEN
}

For the changes to the file to take effect, reboot your Raspberry Pi.

See Also

For wired connections, see also Recipe 2.1. For a list of WiFi adapters that are compatible with the Raspberry Pi, go to http://elinux.org/RPi_VerifiedPeripherals.

For more information on setting up a wired network, see Recipe 2.1.

Problem

No network connection is available, but you still want to be able to remotely control your Raspberry Pi from another computer.

Solution

Use a console cable to connect to a Raspberry Pi. 

Console cables are great for a Pi that is going to be used headless—that is, without keyboard, mouse, or monitor. The console cable shown in Figure 2-5 is available from Adafruit.

Figure 2-5. A console cable

Connect the lead as follows:

1. Connect the red (5V) lead to the 5V pin one pin to the left of the edge of the GPIO header.

2. Connect the black (GND) lead to GND on the next pin to the left on the Raspberry Pi.

3. Connect the white lead (RX) to Raspberry Pi GPIO 14 (TXD) to the left of the black lead.

4. Connect the green lead (RX) to 15 (RXD) to the left of the white lead on the Raspberry Pi.

If you use a different lead, the wire colors may well be different, so always check the documentation for the lead else or you may damage your Raspberry Pi.

Note that the USB lead also provides 5V on the red wire, with enough power for the Pi on its own but not with a lot of devices attached.

If you are a Windows or Mac OS X user, you will need to install drivers for the USB lead, which are available for Windows and for Mac OS X. Linux users usually don’t need to install any drivers for these leads.

To connect to the Pi from Mac OS X, you will need to run the Terminal and enter the command:

$ sudo cu -l /dev/cu.NoZAP-PL2303-00001004 -s 115200

The exact device name will be different, but if you press Tab after cu.P, it will autocomplete. After connecting, press Enter, and the Raspberry Pi login prompt should appear (Figure 2-6). The default username and password are pi and raspberry, respectively.

Figure 2-6. Logging in with the console cable

If you are trying to connect to your Raspberry Pi from a Windows computer, you need to download the terminal software called Putty.

When you run Putty, change the “Connection type” to Serial and set the speed to 115200. You also need to set the “Serial line” to be the COM port in use by the cable. This may be COM7, but if that does not work, check into using the Windows Device manager.

When you click Open and press Enter, the Terminal session should start with a login prompt.

Discussion

The console cable can be a very convenient way of using your Pi if you are traveling light, as it provides both power and a way to control the Pi remotely.

The console lead has a chip in the USB end that provides a USB-to-serial interface. This sometimes (depending on your operating system) requires the installation of drivers on your PC. The lead used here is one supplied by Adafruit (product code 954). You should be able to use any USB-to-serial converter as long as it has the necessary drivers for your PC.

Plugging the sockets of the lead into the right places is made easier if you carefully glue the four sockets together in the right order so that they fit over the GPIO header in a block.

Finding the right position on the GPIO header is made easier if you use a GPIO template like the Raspberry Leaf (see Recipe 9.1). 

See Also

You can find out more about using the serial console at this Adafruit tutorial. Adafruit also sells console cables.

Problem

You want to connect to a remote Pi from another computer by using Secure Shell (SSH).

Solution

Before you can connect to your Raspberry Pi using SSH, you must enable SSH. On newer versions of Raspbian, you can use the Raspberry Pi Configuration tool (Figure 2-7) that you will find on the main menu under Preferences. Just check the box for SSH and click OK. You will be prompted to restart.

If you have an older version of Raspbian, use the raspi_config application. Start this at any time by entering the following command in Terminal:

$ sudo raspi-config

Scroll down to the SSH option and enable it.

Figure 2-7. Enabling SSH using the Pi Configuration tool

If you are using Mac OS X or have Linux installed on the computer from which you want to connect your Pi, then all you need to do to connect is open a Terminal window and enter the command:

$ ssh 192.168.1.16 -l pi

where the IP address (192.168.1.16) is the IP address of your Pi (see Recipe 2.2). You will be prompted for your password and then logged in to the Pi (Figure 2-8).

Figure 2-8. Logging in with SSH

To connect from a Windows computer, you will need to use Putty (Recipe 2.6) to start an SSH session.

Discussion

SSH is a very common way of connecting to remote computers; any commands that you could issue on the Pi itself, you can use from the secure shell. It is also, as the name suggests, secure because the communication is encrypted.

Perhaps the only drawback is that it is a command-line rather than graphical environment. If you need access to the full Raspberry Pi desktop environment remotely, then you need to use VNC (Recipe 2.8) or RDP (Recipe 2.9).

See Also

See also this Adafruit tutorial.

Problem

You want access to the full Raspbian graphical desktop of your Pi from a PC (Windows or Linux) or from Mac OS X, using VNC.

Solution

Install a Virtual Network Connection (VNC) server.

Open a Terminal session (or SSH session) on the Pi and run the following commands:

$ sudo apt-get update
$ sudo apt-get install tightvncserver

Having installed the VNC server, run it using the command:

$ vncserver :1

The first time you run this, you will be prompted to create a new password so that anyone connecting remotely has to enter the password before being granted access to the Pi.

To connect to the Pi from a remote computer, you need to install a VNC client. RealVNC is a popular choice and connects well with tightvnc and is available for Windows, Linux, and Mac OS X.

When you run the client program on Mac OS X or a PC, you will be asked to enter the IP address of the VNC server you want to connect to (the IP address of your Pi). Enter “:1” after the IP address to indicate that you wish to connect to display number 1.

You will then be prompted for the password. Remember, this is the password you set previously after installing tightvncserver and is not necessarily the same as your normal Raspberry Pi password.

Figure 2-9. Logging in with VNC

Discussion

Although you can do most things with SSH, sometimes it is useful to have access to the graphical environment of the Pi.

If you want the VNC server to automatically start whenever you restart your Raspberry Pi, follow these steps:

$ cd /home/pi
$ cd .config
$ mkdir autostart
$ cd autostart
$ nano tightvnc.desktop

Paste the following into the editor window:

[Desktop Entry]
Type=Application
Name=TightVNC
Exec=vncserver :1
StartupNotify=false

As long as your Raspberry Pi is set to automatically log in and boot into the windowing environment, the VNC server will automatically start when you reboot.

See Also

See also this Adafruit tutorial.

See also Recipe 2.9.

Problem

You want access to the full Raspbian graphical desktop of your Pi from a PC or Mac OS X using RDP.

Solution

Install the XRDP software on your Raspberry Pi by entering the following commands:

$ sudo apt-get update
$ sudo apt-get install xrdp

Once the software is installed, it will automatically start the xrdp service, which means the service will automatically start when the Raspberry Pi is rebooted.

If you have Windows 7 or later, then it already includes an RPD client for connecting to your Raspberry Pi. You will find it on your Start menu under All Programs/Accessories/Remote Desktop Connection. For older versions of Windows, you can download the client from: ModMyPi.

Mac OS X users can download the Microsoft RDP client for OS X from Microsoft’s website.

A client for Linux machines is available from http://www.rdesktop.org/.

When you start your RDP client, you will be prompted for the computer you want to connect to. Enter the IP address of your Raspberry Pi. You will then be prompted for the username and password (Figure 2-10), which are the same as your usual Raspberry Pi login—that is, a username of pi and a password of raspberry unless you have changed it.

Figure 2-10. Logging in with RDP

Discussion

RDP does the same job as VNC but works more efficiently and therefore refreshes the contents of the screen more smoothly. The only downside is that for Mac OS X users, it does not integrate with the Share Screen feature of OS X.

See Also

See also Recipe 2.8.

Problem

You want your Raspberry Pi to appear on the list of computers in the Mac OS X Finder so that you can connect to it and browse the filesystem using Finder.

Solution

The Mac OS X operating system includes built-in support for file viewing in Finder over the network (Figure 2-11). However, you must make some configuration changes on your Raspberry Pi for OS X to pick these up.

Figure 2-11. Raspberry Pi in the Mac OS X Finder

You will need to know the IP address of your Raspberry Pi (Recipe 2.2).

Now, on the Raspberry Pi, install netatalk by using the command:

$ sudo apt-get install netatalk

Then, back on your Mac, in the Finder menu, select Go→Connect to Server and enter afp://192.168.1.16 as the server address (but use the IP address for your Raspberry Pi instead of the one shown here). Then click Connect. You will be prompted to log in. I had to reboot my Raspberry Pi before I got the login prompt.

Log in using the name pi and your password, which will be raspberry by default. The Finder should then show you the contents of your home directory on the Raspberry Pi.

There are a few more configuration changes to make on the Raspberry Pi.

$ sudo apt-get install avahi-daemon
$ sudo update-rc.d avahi-daemon defaults

Next, type the command:

$ sudo nano /etc/avahi/services/afpd.service

Paste the following code into the file:

<?xml version="1.0" standalone='no'?><!--*-nxml-*-->
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
   <name replace-wildcards="yes">%h</name>
   <service>
      <type>_afpovertcp._tcp</type>
      <port>548</port>
   </service>
</service-group>

To set the daemon running, type the command:

$ sudo /etc/init.d/avahi-daemon restart

Switch back to your Mac, and you should now see your Raspberry Pi in the Finder.

Discussion

Being able to move files easily between your Mac and your Raspberry Pi is very useful. It means that you can use files on your Pi without having to hook up a separate keyboard, mouse, and monitor.

You can also open files on the Raspberry Pi as if they were on your Mac. This has the advantage that you can edit them with TextMate or your favorite OS X text editor.

If you’re using Windows or Linux, you can also share files by configuring your Raspberry Pi to work as Network Attached Storage (NAS); see Recipe 2.12.

See Also

The instructions here were adapted from this tutorial, which credits Matt Richardson and Shawn Wallace’s book Getting Started with Raspberry Pi (O’Reilly) as the original source.

Problem

You set up VNC, but would like to share the screen on your Raspberry Pi as if it were another Mac OS X device on your network.

Solution

First, follow Recipe 2.8 to install VNC. You will also need to complete Recipe 2.10.

Then enter the command:

$ sudo nano /etc/avahi/services/rfb.service

and paste the following into the editor:

<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
  <name replace-wildcards="yes">%h</name>
  <service>
    <type>_rfb._tcp</type>
    <port>5901</port>
  </service>
</service-group>

Now enter the command:

$ sudo /etc/init.d/avahi-daemon restart

You should now be able to see the Share Screen option shown in Figure 2-12. When prompted for a password, use the password you set up for VNC, not your general Raspberry Pi password.

Figure 2-12. Raspberry Pi screen sharing with the Mac OS X Finder

Discussion

This recipe just adds a little convenience to the process of sharing the screen of your Raspberry Pi.

If you have more than one Raspberry Pi on your network, you need to give them different names so that you can identify them on the network (Recipe 2.4).

If you are a Windows or Linux user, you can still connect to a Raspberry Pi using VNC (Recipe 2.8).

See Also

The instructions here were adapted from this tutorial, which credits Matt Richardson and Shawn Wallace’s book Getting Started with Raspberry Pi (O’Reilly) as the original source.

Problem

You want to use your Raspberry Pi as Network Attached Storage (NAS) by accessing a large USB drive attached to your Raspberry Pi from computers on your network.

Solution

The solution to this problem is to install and configure Samba. To do this, issue the commands:

$ sudo apt-get install samba
$ sudo apt-get install samba-common-bin

Now, attach the USB hard drive to the Raspberry Pi. It will automatically mount in your /media folder. To check that it’s there, use the command:

$ cd /media
$ ls

The drive should be listed with whatever name you gave it when you formatted it. It will automatically mount itself whenever the Raspberry Pi reboots.

You now need to configure Samba so the drive can be shared on the network. To do this, you first need to add a Samba user (pi). Enter the following command and type in a password:

$ sudo smbpasswd -a pi
New SMB password:
Retype new SMB password:
Added user pi.

You now need to make some changes to the file /etc/samba/smb.conf, so enter the command:

$ sudo nano /etc/samba/smb.conf

The first line you’re looking for is near the top of the file:

workgroup = WORKGROUP

You only need to change this if you plan to connect from a Windows machine. This should be the name of your Windows workgroup. For Windows XP, the default is MSHOME; for newer versions of Windows, it is HOME. (But check on your Windows network.)

The next change to be made is further down the file in the Authentication section. Find the line:

# security = user

Remove the # from the front to turn security on.

Finally, scroll right to the end of the file and add the following lines:

[USB]
path = /media/NAS
comment = NAS Drive
valid users = pi
writeable = yes
browseable = yes
create mask = 0777
public = yes

Save the file and then restart Samba by entering the command:

$ sudo /etc/init.d/samba restart

If all is well, your USB drive should now be shared on your network.

Discussion

To connect to the drive on a Mac OS X, just select Go→Connect to Server from the Finder menu. Then enter smb://raspberrypi/USB in the Server Address field. You will see a login dialog box, where you need to change the username to pi (Figure 2-13).

Figure 2-13. Connecting to NAS with the Mac OS X Finder

If you are connecting to the NAS from a Windows machine, the exact procedure will vary depending on your version of Windows. However, the basic principle is that at some point you will need to enter the network address, which should be \\raspberrypi\USB (Figure 2-14).

Figure 2-14. Connecting to NAS from Windows

You will then be prompted for the username and password before you can use the NAS disk (Figure 2-15).

Figure 2-15. Browsing NAS on Windows

If you are a Linux user, this command should mount the NAS drive for you:

$ sudo mkdir /pishare
$ sudo smbmount -o username=pi,password=raspberry //192.168.1.16/USB /pishare

See Also

You may wish to change your Raspberry Pi’s network name to something inappropriate like piNAS (see Recipe 2.4).

Problem

You want to print to a network printer using your Raspberry Pi.

Solution

Use Common Unix Printing System (CUPS).

Start by entering the following command into a Terminal to install CUPS. This may take some time.

$ sudo apt-get install cups

Give yourself admin privileges for CUPS by entering the following command:

$ sudo usermod -a -G lpadmin pi

CUPS is configured via a web interface. Neither the Midori or Dillo web browsers work very well with the CUPS administration pages, but Iceweasel works just fine. You can install the Iceweasel browser by entering the following command:

$ sudo apt-get install iceweasel

Start Iceweasel from the Internet group of your Start menu and navigate to the address http://localhost:631.

Go to the Administration tab and choose the Add Printer option. This will display a list of printers that are on the network or connected directly to the Raspberry Pi’s USB port (Figure 2-16).

Figure 2-16. Discovering printers with CUPS

Follow the series of dialog boxes to set up the printer.

Discussion

When you’re finished, you can test out the printer by firing up AbiWord (see Recipe 4.2). Type some text, and when you’re ready to print it, you should see your newly added printer available for printing (Figure 2-17).

Figure 2-17. Printing from AbiWord

See Also

See also the official CUPS website.

Problem

You want to move files around using a graphical interface like you can on a Mac OS X or PC.

Solution

Use the File Manager.

You can find this program on your Start menu in the Accessories group (Figure 3-1).

Using the File Manager, you can drag a file or directory from one directory to another or use the Edit menu to copy a file from one location and paste it to a second. This operates in much the same way as the Windows File Manager or Mac OS X Finder. 

Figure 3-1. The File Manager

Discussion

The lefthand side of the File Manager shows the volumes that are mounted, so if you connect a USB flash drive or external USB drive, it will appear here.

The central area displays the files in the current folder, which you can navigate using the buttons in the toolbar or by typing a location in the file path area at the top.

Right-click a file to reveal options that can be used on that file (Figure 3-2).

Figure 3-2. The File Manager options

See Also

See also Recipe 3.4.

Problem

When using a Raspberry Pi, you need to issue text commands in a Terminal.

Solution

Select the LX Terminal icon (looks like a black computer monitor) at the top of the Raspberry Pi Desktop, or select the Terminal menu option on the Start menu in the Accessories group (Figure 3-3). 

Figure 3-3. Opening LX Terminal

Discussion

When the LX Terminal starts, it is set to your home directory (/home/pi).

You can open as many Terminal sessions as you want. It is often useful to have a couple of sessions open in different directories so that you don’t have to constantly switch directories using cd (Recipe 3.3).

See Also

In the next section (Recipe 3.3), you will look at navigating the directory structure using the Terminal.

Problem

You need to know how to change directory and move about the fileystem using the Terminal.

Solution

The main command used for navigating the filesystem is cd (change directory). After cd, you have to specify the directory that you want to change to. This can either be a relative path to a directory inside your current directory, or an absolute path to somewhere else on the filesystem.

To see what the current directory is, you can use the command pwd (print working directory).

Discussion

Try out a few examples. Open a Terminal session, and you should see a prompt like this:

pi@raspberrypi ~ $

The prompt that you will see after each command (pi@raspberrypi ~ $) is a reminder of your username (pi) and your computer name (raspberrypi). The ~ character is shorthand for your home directory (/home/pi). So, at any point, you can change your current directory to your home directory as follows:

$ cd ~

You can confirm that the command did indeed set the directory to the home directory by using the pwd command:

$ pwd
/home/pi

If you want to move up one level in the directory structure, you can use the special value .. (two dots) after the cd command, as shown here:

$ cd ..
$ pwd
/home

As you may have deduced by now, the path to a particular file or directory is made up of words separated by a /. So the very root of the whole filesystem is /, and to access the home directory within / you would refer to /home/. Then, to find the pi directory within that, you would use /home/pi/. The final / can be omitted from a path.

Paths can also be absolute (starting with a / and specifying the full path from the root), or they can be relative to the current working directory, in which case they must not start with a /.

You will have full read and write access to the files in your home directory, but once you move into the places where system files and applications are kept, your access to some files will be restricted to read only. You can override this (Recipe 3.11), but some care is required.

Check out the root of the directory structure by entering the following commands:

$ cd /
$ ls
bin   dev  home  lost+found  mnt  proc  run   selinux  sys  usr
boot  etc  lib   media       opt  root  sbin  srv      tmp  var

The ls command (list) shows us all the files and directories underneath / the root directory. You will see that there is a home directory listed, which is the directory you have just come from.

Now change into one of those directories by using the command:

$ cd etc
$ ls
adduser.conf                   hosts.deny      polkit-1
alternatives                   hp              profile
apm                            iceweasel       profile.d
apparmor.d                     idmapd.conf     protocols
apt                            ifplugd         pulse
asound.conf                    init            python

You will notice a couple of things. First, there are a lot of files and folders listed, more than can fit on the screen at once. Use the scroll bar on the side of the Terminal window to move up and down.

Second, you will see that the files and folders have some color-coding. Files are displayed in white, whereas directories are blue.

Unless you particularly like typing, the Tab key offers a convenient shortcut. If you start typing the name of a file, pressing the Tab key allows the autocomplete feature to attempt to complete the filename. For example, if you’re going to change directory to network, type the command cd netw and then press the Tab key. Because netw is enough to uniquely identify the file or directory, pressing the Tab key will autocomplete it.

If what you have typed is not enough to uniquely identify the file or directory name, then pressing the Tab key another time will display a list of possible options that match what you have typed so far. So, if you had stopped at net and pressed the Tab key, you would see the following:

$ cd net
netatalk/ network/

You can provide an extra argument after ls to narrow down the things you want to list. Change directory to /etc and then run the following:

$ ls f*
fake-hwclock.data  fb.modes  fstab  fuse.conf

fonts:
conf.avail  conf.d  fonts.conf  fonts.dtd

foomatic:
defaultspooler  direct  filter.conf

fstab.d:
pi@raspberrypi /etc $

The * character is called a wildcard. In specifying f* after ls, we are saying that we want to list everything that starts with an f.

Helpfully, the results first list all the files within /etc that start with f, and then the contents of all the directories in that folder starting with f.

A common use of wildcards is to list all files with a certain extension (e.g., ls *.docx).

A convention in Linux (and many other operating systems) is to prefix files that should be hidden from the user by starting their name with a period. Any so-named files or folders will not appear when you type ls unless you also supply ls with the option -a. For example:

$ cd ~
$ ls -a
.                                  Desktop               .pulse
..                                 .dillo                .pulse-cookie
Adafruit-Raspberry-Pi-Python-Code  .dmrc                 python_games
.advance                           .emulationstation     sales_log
.AppleDB                           .fltk                 servo.py
.AppleDesktop                      .fontconfig           .stella
.AppleDouble                       .gstreamer-0.10       stepper.py.save
Asteroids.zip                      .gvfs                 switches.txt.save
atari_roms                         indiecity             Temporary Items
.bash_history                      .local                thermometer.py
.bash_logout                       motor.py              .thumbnails
.bashrc                            .mozilla              .vnc
.cache                             mydocument.doc        .Xauthority
.config                            Network Trash Folder  .xsession-errors
.dbus                              .profile              .xsession-errors.old

As you can see, most of the files and folders in your home directory are hidden.

See Also

See also Recipe 3.13.

Problem

You want to copy a file using a Terminal session.

Solution

Use the cp command to copy files and directories.

Discussion

You can, of course, copy files by using the File Manager and its copy and paste menu options (Recipe 3.1).

The simplest example of copying in a Terminal session is to make a copy of a file within your working directory. The cp command is followed first by the file to copy, and then by the name to be given to the new file.

For example, the following example creates a file called myfile.txt and then makes a copy of it with the name myfile2.txt. You can find out more about the trick of creating a file using the > command in Recipe 3.8.

$ echo "hello" > myfile.txt
$ ls
myfile.txt
$ cp myfile.txt myfile2.txt
$ ls
myfile.txt    myfile2.txt

Although in this example, both file paths are local to the current working directory, the file paths can be to anywhere in the filesystem where you have write access. The following example copies the original file to an area /tmp, which is a location for temporary files. Do not put anything important in that folder.

$ cp myfile.txt /tmp

Note that in this case, the name to be given to the new file is not specified, just the directory where it is to go. This will create a copy of myfile.txt in /tmp with the same name of myfile.tmp.

Sometimes, rather than copying just one file, you may want to copy a whole directory full of files and possibly other directories. To copy such a directory, you need to use the -r option (for recursive). This will copy the directory and all its contents.

$ cp -r mydirectory mydirectory2

Whenever you are copying files or folders, if you do not have permission, the result of the command will tell you that. You will need to either change the permissions of the folder into which you are copying (Recipe 3.13) or copy the files with superuser privileges (Recipe 3.11).

See Also

See also Recipes 3.5 and 3.10.

Problem

You need to rename a file by using a Terminal session.

Solution

Use the mv command to rename files and directories.

Discussion

The mv (move) command is used in a similar way to the cp command, except that the file or folder being moved is simply renamed rather than a duplicate being made.

For example, to simply rename a file from my_file.txt to my_file.rtf, you use the command:

$ mv my_file.txt my_file.rtf

Changing a directory name is just as straightforward, and you don’t need the recursive -r option you used when copying because changing a directory’s name implicitly means that everything within it is contained in a renamed directory.

See Also

See also Recipes 3.4 and 3.10.

Problem

You want to run an editor from the command line to change a config file.

Solution

Use the editor nano included with most Raspberry Pi distributions.

Discussion

To use nano, simply type the command nano followed by the name or path to the file that you want to edit. If the file does not exist, it will be created when you save it from the editor. However, this will only happen if you have write permissions in the directory where you are trying to write the file.

From your home directory, type the command nano my_file.txt to edit or create the file nano my_file.txt. Figure 3-4 shows nano in action.

Figure 3-4. Editing a file with nano

You cannot use the mouse to position the cursor; use the arrow keys instead.

The area at the bottom of the screen lists a number of commands that you access by holding down the Ctrl key and pressing the letter indicated. Most of these are not that useful. The ones that you are likely to use most of the time are:

Ctrl-X

Exit. You will be prompted to save the file before nano exits.

Ctrl-V

Next page. Think of it as an arrow pointing downward. This allows you to move through a large file one screen at a time.

Ctrl-Y

Previous page.

Ctrl-W

Where is. This allows you to search for a piece of text.

There are also some fairly crude cut-and-paste type options there, but in practice, it’s easier to use the normal clipboard from the menu that you access with a right-click.

Figure 3-5. Using the clipboard in nano

Using this clipboard also allows you to copy and paste text between other windows such as your browser.

When you’re ready to save your changes to the file and exit nano, use the command Ctrl-X. Type Y to confirm that you want to save the file. nano then displays the filename as the default name to save the file under. Press Enter to save and exit.

If you want to abandon changes you have made, enter N in place of Y.

See Also

Editors are very much a matter of personal taste. Many other editors that are available for Linux will work just fine on Raspberry Pi. The vim (vi improved) editor has many fans in the Linux world. This is also included in the popular Raspberry Pi distributions. It is not, however, an easy editor for the beginner. You can run it in the same way as nano, but using the command vi instead of nano. There are more details on using vim at http://newbiedoc.sourceforge.net/text_editing/vim.html.en.

Problem

You want to view the contents of a small file without editing it.

Solution

Use the cat or more commands to view the file.

For example:

$ more myfile.txt
This file contains
some text

Discussion

The cat command displays the whole contents of the file, even if it is longer than will fit on the screen.

The more command just displays one screen of text at a time. Press the space bar to display the next screen.

See Also

You can also use cat to concatenate (join together) a number of files (Recipe 3.30).

Another popular command related to more is less. less is like more except it allows you to move backward in the file as well as forward.

Problem

You want to create a one-line file without having to use an editor.

Solution

Use the > and echo commands to redirect what you type on the command line to a file.

For example:

$ echo "file contents here" > test.txt
$ more test.txt
file contents here

Discussion

This can be useful for quickly creating a file.

See Also

To use the more command to view files without using an editor, see Recipe 3.7.

To use > to capture other kinds of system output, see Recipe 3.29.

Problem

You want to create a new directory by using the Terminal.

Solution

The mkdir command will create a new directory.

Discussion

To create a directory, use the mkdir command. Try out the following example:

$ cd ~
$ mkdir my_directory
$ cd my_directory
$ ls

You need to have write permission in the directory within which you are trying to create the new directory.

See Also

For general information on using the Terminal to navigate the filesystem, see Recipe 3.3.

Problem

You want to delete a file or directory using the Terminal.

Solution

The rm (remove) command will delete a file or directory and its contents. It should be used with extreme caution.

Discussion

Deleting a single file is simple and safe. The following example will delete the file my_file.txt from the home directory:

$ cd ~
$ rm my_file.txt
$ ls

You need to have write permission in the directory within which you are trying to carry out the deletion.

You can also use the * wildcard when deleting files. This example will delete all the files starting with my_file. in the current directory:

$ rm my_file.*

You could also delete all the files in the directory by typing:

$ rm *

If you want to recursively delete a directory and all its contents, including any directories that it contains, you can use the -r option:

$ rm -r mydir

See Also

See also Recipe 3.3.

If you are concerned about accidentally deleting files or folders, you can force the rm command to confirm by setting up a command alias (Recipe 3.34).

Problem

Some commands don’t work because you have insufficient privileges. You need to issue commands with superuser privileges.

Solution

The sudo (substitute user do) command allows you to perform actions with superuser privileges. Just prefix the command with sudo.

Discussion

Most tasks that you want to perform on the command line can usually be performed without superuser privileges. The most common exceptions to this are when you’re installing new software and editing configuration files.

For example, if you try to use the command apt-get update, you will receive a number of permission denied messages:

$ apt-get update
E: Could not open lock file /var/lib/apt/lists/lock - open (13: Permission denied)
E: Unable to lock directory /var/lib/apt/lists/
E: Could not open lock file /var/lib/dpkg/lock - open (13: Permission denied)
E: Unable to lock the administration directory (/var/lib/dpkg/), are you root?

The message at the end—are you root?—gives the game away. If you issue the same command prefixed with sudo, the command will work just fine:

$ sudo apt-get update
Get:1 http://mirrordirector.raspbian.org wheezy InRelease [12.5 kB]
Hit http://archive.raspberrypi.org wheezy InRelease
Get:2 http://mirrordirector.raspbian.org wheezy/main Sources [6,241 kB]
Hit http://archive.raspberrypi.org wheezy/main armhf Packages
Ign http://archive.raspberrypi.org wheezy/main Translation-en_GB
Ign http://archive.raspberrypi.org wheezy/main Translation-en
40% [2 Sources 2,504 kB/6,241 kB 40%]

If you have a whole load of commands to run as superuser and don’t want to have to prefix each command with sudo, you can use the following command:

$ sudo sh
# 

Note how the prompt changes from $ to #. All subsequent commands will be run as superuser. When you want to revert to being a regular user, enter the command:

# exit
$

See Also

To understand more about file permissions, see Recipe 3.12.

To install software using apt-get, see Recipe 3.16.

Problem

You have seen the strange characters that accompany a filename when it is listed. You would like to know what they all mean.

Solution

To see the permissions and ownership information relating to files and directories, use the ls command with the option -l.

Discussion

Run the command ls -l, and you will see a result like this:

$ ls -l
total 16
-rw-r--r-- 1 pi pi    5 Apr 23 15:23 file1.txt
-rw-r--r-- 1 pi pi    5 Apr 23 15:23 file2.txt
-rw-r--r-- 1 pi pi    5 Apr 23 15:23 file3.txt
drwxr-xr-x 2 pi pi 4096 Apr 23 15:23 mydir

Figure 3-6 shows the different sections of the listing information. The first section contains the permissions. In the second column, the number 1 (labeled “Files”) indicates how many files are involved. This field only makes sense if the listing entry is for a directory; if it is a file, it will mostly be just 1. The next two entries (both pi) are the owner and group of the file. The size entry (the fifth column) indicates the size of the file in bytes. The modified date will change every time the file is edited or changed and the final entry is the actual name of the file or directory.

Figure 3-6. File permissions

The permissions string is split into four sections (Type, Owner, Group, and Other). The first section is the type of the file. If this is a directory, it will be the character d; if it is just a file, the entry will be just a -.

The next section of three characters specifies the owner permissions for that file. Each character is a flag that is either on or off. So if the owner has read permissions, there will be a r in the first character position. If he has write permissions, there will be a w in the second slot. The third position, which is - in this example, can be x if the file is executable (a program or script) for the owner.

The third section has the same three flags but for any users in the group. Users can be organized into groups. So, in this case, the file has a user pi and a group ownership of pi. If there were any other users in the group pi, they would have the permissions specified here.

The final section specifies the permissions for any other users who are neither pi nor in the group pi.

Since most people will only ever use the Raspberry Pi as the user pi, the permissions of most interest are in the first section.

See Also

To change file permissions, see Recipe 3.13.

Problem

You need to change the permissions on a file.

Solution

The command chmod is used to modify file permissions.

Discussion

Common reasons why you might want to change file permissions include needing to edit a file that is marked as read-only and giving a file execute permissions so that it can run as a program or script.

The chmod command allows you to add or remove permissions for a file. There are two syntaxes for doing this; one requires the use of octal (base 8) and the other is text-based. You will use the easier-to-understand text method.

The first parameter to chmod is the change to make, and the second is the file or folder to which it should apply. This change parameter takes the form of the permission scope (+, -, = for add, remove, and set, respectively) and then the permission type.

For example, the following code will add execute (x) rights to the file for the owner of the file file2.txt.

$ chmod u+x file2.txt

If we now list the directory, we can see that the x permission has been added.

$ ls -l
total 16
-rw-r--r-- 1 pi pi    5 Apr 23 15:23 file1.txt
-rwxr--r-- 1 pi pi    5 Apr 24 08:08 file2.txt
-rw-r--r-- 1 pi pi    5 Apr 23 15:23 file3.txt
drwxr-xr-x 2 pi pi 4096 Apr 23 15:23 mydir

If we wanted to add execute permission for the group or other users, then we could use g and o, respectively. The letter a will add the permission to everyone.

See Also

For background on file permissions, see Recipe 3.12.

See Recipe 3.14 for changing file ownership.

Problem

You need to change the ownership of a file.

Solution

The command chown (change owner) is used to modify the ownership of a file or directory.

Discussion

As we discovered in Recipe 3.12, any file or directory has both an owner and a group associated with it. Since most users of the Raspberry Pi will just have the single user of pi, we don’t really need to worry about groups.

Occasionally, you will find files on your system that have been installed with a different user than pi. If this is the case, you can change the ownership of the file by using the chown command.

To just change the owner of a file, use chown followed by the new owner and group, separated by a colon, and then the name of the file.

You will probably find that you need superuser privileges to change ownership, in which case, prefix the command with sudo (Recipe 3.11).

$ sudo chown root:root file2.txt
$ ls -l
total 16
-rw-r--r-- 1 pi   pi      5 Apr 23 15:23 file1.txt
-rwxr--r-- 1 root root    5 Apr 24 08:08 file2.txt
-rw-r--r-- 1 pi   pi      5 Apr 23 15:23 file3.txt
drwxr-xr-x 2 pi   pi   4096 Apr 23 15:23 mydir

See Also

For background on file permissions, see Recipe 3.12.

Also see Recipe 3.13 for changing file permissions.

Problem

You want to capture an image of the Raspberry Pi’s screen and save it to a file.

Solution

Install and use the delightfully named scrot screen capture software.

Discussion

To install scrot, run the following command from Terminal:

$ sudo apt-get install scrot

The simplest way to trigger a screen capture is to just enter the command scrot. This will immediately take an image of the primary display and save it in a file named something like 2013-04-25-080116_1024x768_scrot.png within the current directory.

Sometimes you want a screenshot to show a menu being opened or something that generally disappears when the window in which you are interested loses focus. For such situations, you can specify a delay before the capture takes place using the -d option.

$ scrot -d 5

The delay is specified in seconds.

If you capture the whole screen, you can crop it later with image editing software, such as Gimp (Recipe 4.11). However, it is more convenient to just capture an area of the screen in the first place, which you can do using the -s option.

To use this option, type this command and then drag out the area of screen that you want to capture with the mouse.

$ scrot -s

The filename will include the dimensions in pixels of the image captured.

See Also

The scrot command has a number of other options to control things like using multiple screens and changing the format of the saved file. You can find out more about scrot from its manpage by entering the following command.

$ man scrot

For more information on installing with apt-get, see Recipe 3.16.

Problem

You want to install software using the command line.

Solution

The most frequently used tool for installing software from a Terminal session is apt-get.

The basic format of the command, which you must run as a superuser, is:

$ sudo apt-get install <name of software>

For example, to install the AbiWord word processing software, you would enter the command:

$ sudo apt-get install abiword

Discussion

The apt-get package manager uses a list of available software. This list is included with the Raspberry Pi operating system distribution that you use but is likely to be out-of-date. So if the software that you try to install is reported by apt-get as not found, run the following command to update the list:

$ sudo apt-get update

The list and the software packages for installation are all on the Internet, so none of this will work unless your Raspberry Pi has an Internet connection.

sudo rm /var/lib/dpkg/status
sudo touch /var/lib/dpkg/status

The installation process can often take a while because the files have to be downloaded and installed. Some installations will also add shortcuts to your desktop, or the program groups on your Start menu.

You can search for software to install using the command apt-get search followed by a search string such as abiword. This will then display a list of matching packages that you could install.

See Also

See Recipe 3.17 for removing programs that you no longer need so that you can free up space.

See also Recipe 3.20 for downloading source code from GitHub.

Problem

Having installed a whole load of programs using apt-get, you now find that you want to remove some of them.

Solution

The apt-get utility has an option (remove) that will remove a package, but it will only remove packages that have been installed with apt-get install.

For example, if you wanted to remove AbiWord, you would use the command:

$ sudo apt-get remove abiword

Discussion

Removing a package like this does not always delete everything, as packages often also have prerequisite packages that are installed as well. To remove these, you can use the autoremove option, as shown here:

$ sudo apt-get autoremove abiword
$ sudo apt-get clean

The apt-get clean option will do some further tidying up of unused package installation files.

See Also

See Recipe 3.16 for installing packages using apt-get.

Problem

You want to download a file from the Internet without using a web browser.

Solution

Use the wget command to fetch a file from the Internet.

For example:

$ wget http://www.icrobotics.co.uk/wiki/images/c/c3/Pifm.tar.gz
--2013-06-07 07:35:01--  http://www.icrobotics.co.uk/wiki/images/c/c3/Pifm.tar.gz
Resolving www.icrobotics.co.uk (www.icrobotics.co.uk)... 155.198.3.147
Connecting to www.icrobotics.co.uk (www.icrobotics.co.uk)|155.198.3.147|
:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 5521400 (5.3M) [application/x-gzip]
Saving to: `Pifm.tar.gz'

100%[==================================================>] 5,521,400    601K/s

2013-06-07 07:35:11 (601 KB/s) - `Pifm.tar.gz' saved [5521400/5521400]

If your URL contains any special characters, it is a good idea to enclose it in double quotes. This example URL is from Recipe 4.10.

Discussion

You will find instructions for installing software that rely on using wget to fetch files. It is often more convenient to do this from the command line rather than use a browser, find the file, download it, and then copy it to the place you need it.

The wget command takes the URL to download as its argument and downloads it into the current directory. It’s typically used to download an archive file of some type but will also download any web page.

See Also

For more information on installing with apt-get, see Recipe 3.16.

For information on selecting and using a browser, see Recipe 4.3.

Problem

Sometimes Python libraries and other software are supplied via a Git repository URL. You need to be able to fetch them onto your Raspberry Pi.

Solution

To use code in Git repositories, you need to use the git clone command to fetch the files.

Discussion

For example, the following command will fetch all the source code examples from this book:

$ git clone https://github.com/simonmonk/raspberrypi_cookbook_ed2.git

See Also

Learn more about Git and the Git hosting service GitHub.

See also Recipe 3.16.

Problem

You want to arrange for a script or program to start automatically every time the Raspberry Pi reboots.

Solution

Debian Linux, upon which most Raspberry Pi distributions are based, uses a dependency-based mechanism for automating the running of commands at startup. This is a little tricky to use and involves creating a configuration file for the script or program that you want to run in a folder called init.d.

Discussion

The following example shows you how to run a Python script in your home directory. The script could do anything, but in this case, the script runs a simple Python web server, which is described further in Recipe 7.17.

The steps involved in this are:

1. Create an init script.

2. Make the init script executable.

3. Tell the system about the new init script.

First, create the init script. This needs to be created in the folder /etc/init.d/. The script can be called anything, but in this example, you will call it my_server.

Create the new file by using nano with the following command:

$ sudo nano /etc/init.d/my_server

Paste the following code into the editor window and save the file:

### BEGIN INIT INFO
# Provides: my_server
# Required-Start: $remote_fs $syslog $network
# Required-Stop: $remote_fs $syslog $network
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Simple Web Server
# Description: Simple Web Server
### END INIT INFO

#! /bin/sh
# /etc/init.d/my_server

export HOME
case "$1" in
  start)
    echo "Starting My Server"
    sudo /usr/bin/python /home/pi/myserver.py  2>&1 &
  ;;
stop)
  echo "Stopping My Server"
  PID=`ps auxwww | grep myserver.py | head -1 | awk '{print $2}'`
  kill -9 $PID
  ;;
*)
  echo "Usage: /etc/init.d/my_server {start|stop}"
  exit 1
;;
esac
exit 0

This is quite a lot of work to automate the running of a script, but most of it is boiler-plate code. To run a different script, just work your way through the script, changing the descriptions and the name of the Python file you want to run.

The next step is to make this file executable for the owner, which you do using this command:

$ sudo chmod +x /etc/init.d/my_server

Now that the program is set up as a service, you can test that everything is OK before you set it to autostart as part of the boot sequence, using the following command:

$ /etc/init.d/my_server start
Starting My Server
Bottle v0.11.4 server starting up (using WSGIRefServer())...
Listening on http://192.168.1.16:80/
Hit Ctrl-C to quit.

Finally, if that runs OK, use the following command to make the system aware of the new service that you have defined:

$ sudo update-rc.d my_server defaults

See Also

For a simpler approach to making a program run automatically, see Recipe 3.21.

For more information on changing file and folder permissions, see Recipe 3.12.

Problem

You want to run a script once a day or at regular intervals.

Solution

Use the Linux crontab command.

To do this, the Raspberry Pi needs to know the time and date, and therefore needs a network connection or a real-time clock. See Recipe 12.13.

Discussion

The command crontab allows you to schedule events to take place at regular intervals. This can be daily or hourly, and you can even define complicated patterns so different things happen on different days of the week. This is useful for backup tasks that you might want to run in the middle of the night.

You can edit the scheduled events by using the following command:

$ crontab -e

If the script or program that you want to run needs to be run by a superuser, then prefix all the crontab commands with sudo (Recipe 3.11).

The comment line indicates the format of a crontab line. The digits are, in order, minute, hour, day of month, month, day of week, and then the command that you want to run.

The first line that starts with a # is just a comment line to remind you of the format for a crontab line.

If there is a * in the digit position, that means every; if there is a number there instead, the script will only be run at that minute/hour/day of the month.

So, to run the script every day at 1 a.m., you would add the line shown in Figure 3-7.

Figure 3-7. Editing crontab

Using only a single digit, you can specify ranges to run the script just on weekdays; for example:

0 1 * * 1-5 /home/pi/myscript.sh

If your script needs to be run from a particular directory, you can use a semicolon (;) to separate multiple commands as shown here:

0 1 * * * cd /home/pi; python mypythoncode.py

See Also

You can see the full documentation for crontab by entering this command:

$ man crontab

Problem

You want to find a file that you know is on the system somewhere.

Solution

Use the Linux find command.

Discussion

Starting with a directory specified in the command, the find command will search, and if it finds the file, display its location. For example:

$ find /home/pi -name gemgem.py
/home/pi/python_games/gemgem.py

You can start the search higher up the tree, even at the root of the whole filesystem (/). This will make the search take a lot longer, and will also produce error messages. You can redirect these error messages by adding 2>/dev/null to the end of the line.

To search for the file throughout the entire filesystem, use the following command:

$ find / -name gemgem.py 2>/dev/null
/home/pi/python_games/gemgem.py

You can also use wildcards with find as follows:

$ find /home/pi -name match*
/home/pi/python_games/match4.wav
/home/pi/python_games/match2.wav
/home/pi/python_games/match1.wav
/home/pi/python_games/match3.wav
/home/pi/python_games/match0.wav
/home/pi/python_games/match5.wav

See Also

The find command has a number of other advanced features for searching. To see the full manpage documentation for find, use this command:

$ man find

Problem

You want to be able to repeat commands on the command line without having to type them again.

Solution

Use the up and down arrow keys to select previous commands from the command history, and the history command with grep to find older commands.

Discussion

You can access the previous command you ran by pressing the up arrow key. Pressing it again will take you to the command before that, and so on. If you overshoot the command you wanted, the down arrow key will take you back in the other direction.

If you want to cancel without running the selected command, use Ctrl-C.

Over time, your command history will grow too large to find a command that you used ages ago. To find a command from way back, you can use the history command.

$ history
    1  sudo nano /etc/init.d/my_server
    2  sudo chmod +x /etc/init.d/my_server
    3  /etc/init.d/my_server start
    4  cp /media/4954-5EF7/sales_log/server.py myserver.py
    5  /etc/init.d/my_server start
    6  sudo apt-get update
    7  sudo apt-get install bottle
    8  sudo apt-get install python-bottle

This lists all your command history and is likely to have far too many entries for you to find the one you want. To remedy this, you can pipe the history command into the grep command, which will just display results matching a search string. So, for example, to find all the apt-get (Recipe 3.16) commands that you’ve issued, you can use the line:

$ history | grep apt-get
    6  sudo apt-get update
    7  sudo apt-get install bottle
    8  sudo apt-get install python-bottle
   55  history | grep apt-get

Each history item has a number next to it, so if you find the line you were looking for, you can run it using ! followed by the history number, as shown here:

$ !6
sudo apt-get update
Hit http://mirrordirector.raspbian.org wheezy InRelease
Hit http://mirrordirector.raspbian.org wheezy/main armhf Packages
Hit http://mirrordirector.raspbian.org wheezy/contrib armhf Packages
.....

See Also

To find files rather than commands, see Recipe 3.24.

Problem

The Raspberry Pi can run a bit slow sometimes, so you want to see what’s hogging the processor.

Solution

Use the Task Manager utility, which you’ll find on the Start menu in the System Tools program group (Figure 3-8).

Figure 3-8. The Task Manager

The Task Manager allows you to see at a glance how much CPU and memory are being used. You can also right-click on a process and select the option to kill it from the pop-up menu.

The graphs at the top of the window display the total CPU usage and memory. The processes are listed below that, and you can see the CPU share each is taking.

Discussion

If you prefer to do this type of thing from the command line, use the Linux top command to display very similar data about processor and memory and which processes are using the most resources (Figure 3-9). You can then use the kill command to kill a process. You will need to do this as superuser.

In this case, you can see that the top process is a Python program that uses 97% of CPU. The first column shows its process ID (2447). To kill this process, enter this command:

$ kill 2447

It is quite possible to kill some vital operating system process this way, but if you do, powering off your Pi and turning it back on again will restore things to normal.

Figure 3-9. Using the top command to see resource usage

Sometimes, you may have a process running that is not immediately visible when you use top. If this is the case, you can search all the processes running by using the ps command and piping (Recipe 3.31) the results to the grep command, which will search the results and highlight items of interest.

For example, to find the process ID for our CPU-hogging Python process, we could run the following command:

$ ps -ef | grep "python"
pi        2447  2397 99 07:01 pts/0    00:00:02 python speed.py
pi        2456  2397  0 07:01 pts/0    00:00:00 grep --color=auto python

In this case, the process ID for the Python program speed.py is 2447. The second entry in the list is the process for the ps command itself.

A variation on the kill command is the killall command. Use this with caution, as it kills all processes that match its argument. So, for example, the following command will kill all Python programs running on the Raspberry Pi:

$ sudo killall python

See Also

See also the manpages for top, ps, grep, kill, and killall. You can view these by typing man followed by the name of the command, as shown here:

$ man top

Problem

You have downloaded a compressed file and want to uncompress it.

Solution

Depending on the file type, you will need to use the tar or gunzip commands.

Discussion

If the file that you want to uncompress just has the extension .gz, you can unzip it using the command:

$ gunzip myfile.gz

You also often find files (called tarballs) that contain a directory that has been archived with the Linux tar utility and then compressed with gzip into a file with a name like myfile.tar.gz.

You can extract the original files and folders out of a tarball by using the tar command:

$ tar -xzf myfile.tar.gz

See Also

You can find out more about tar from the manpages, which you can access by using the command man tar.

Problem

You’ve plugged in a USB device and want to make sure Linux recognizes it.

Solution

Use the lsusb command. This will list all the devices attached to the USB ports on your Raspberry Pi:

$ lsusb
Bus 001 Device 002: ID 0424:9512 Standard Microsystems Corp.
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 0424:ec00 Standard Microsystems Corp.
Bus 001 Device 004: ID 15d9:0a41 Trust International B.V. MI-2540D [Optical mouse]

Discussion

This command will tell you whether a device is connected or not, but it will not guarantee that it is working correctly. There may be drivers to install or configuration changes to make for the hardware.

See Also

For an example of using lsusb when attaching an external webcam, see Recipe 4.5.

Problem

You want to quickly create a file with some text, or record a directory listing into a file.

Solution

Use the > command to redirect output that would otherwise appear on the command line.

For example, to copy a directory listing into a file called myfiles.txt, do the following:

$ ls > myfiles.txt
$ more myfiles.txt
Desktop
indiecity
master.zip
mcpi

Discussion

You can use the > command on any Linux command that produces output, even if you are running, say, a Python program.

You can also use the opposite (<) command to redirect user input, although this is not nearly as useful as >.

See Also

To use cat to join together a number of files, see Recipe 3.30.

Problem

You have a number of text files and you want to join them into one big file.

Solution

Use the cat command to concatenate a number of files into one output file.

For example:

$ cat file1.txt file2.txt file3.txt > full_file.txt

Discussion

Joining files is the real purpose of the cat command. You can supply as many filenames as you like, and they will all be written to the file you direct to. If you do not redirect the output, then it will just appear in your Terminal window. If they are big files, this might take some time!

See Also

See also Recipe 3.7, where cat is used to display the contents of a file.

Problem

You want to use the output of one Linux command as the input to another command.

Solution

Use the pipe command, which is the bar symbol (|) on your keyboard, to pipe the output of one command to another. For example:

$ ls -l *.py | grep Jun
-rw-r--r-- 1 pi pi 226 Jun  7 06:49 speed.py

This example will find all the files with the extension py that also have Jun in their directory listing, indicating that they were last modified in June.

Discussion

At first sight, this looks rather like output redirection using > (Recipe 3.29). The difference is that +>_ will not work where the target is another program. It will only work for redirecting to a file.

You can chain together as many programs as you like, as shown here, although this isn’t something you will do often:

$ command1 | command2 | command3

See Also

See Recipe 3.26 for an example of using grep to find a process, and Recipe 3.25 to search your command history, using a pipe and grep.

Problem

You want to run a command, but you don’t want the output filling up your screen.

Solution

Redirect the output to /dev/null using >.

For example:

$ ls > /dev/null

Discussion

This example illustrates the syntax but is otherwise pretty useless. A more common use is where you’re running a program and the developer has left a lot of trace messages in her code, which you don’t really want to see. The following example hides superfluous output from the find command (see Recipe 3.34).

$ find / -name gemgem.py 2>/dev/null
/home/pi/python_games/gemgem.py

See Also

For more information about redirecting standard output, see Recipe 3.29.

Problem

You want to run a program but also work on some other task.

Solution

Run the program or command in the background using the & command.

For example:

$ python speed.py &
[1] 2528
$ ls

Rather than wait until the program has finished running, the command line displays the process ID (the second number) and immediately allows you to continue with whatever other commands you want to run. You can then use this process ID to kill the background process (Recipe 3.26).

To bring the background process back to the foreground, use the fg command:

$ fg
python speed.py

This will report the command or program that is running and then wait for it to finish.

Discussion

Output from the background process will still appear in the Terminal.

An alternative to putting processes in the background is to just open more than one Terminal window.

See Also

For information on managing processes, see Recipe 3.26.

Problem

You want to create aliases to commands that you use frequently.

Solution

Edit the file ~/.bashrc using nano (Recipe 3.6), and then move to the end of the file and add as many lines as you want, like this:

alias l='ls -a'

This creates an alias called l that, when entered, will be interpreted as the command ls -a.

Save and exit the file using Ctrl-X and Ctrl-Y, and then to update the Terminal with the new alias, type the following command:

$ source .bashrc

Discussion

Many Linux users set up an alias for rm like the following, so that it confirms deletions.

$ alias rm='rm -i'

This is not a bad idea, as long as you do not forget when you use someone else’s system that doesn’t have this alias set up!

See Also

For more information about rm, see Recipe 3.10.

Problem

You want to manually set the date and time on your Raspberry Pi, because it does not have an Internet connection.

Solution

Use the Linux date command.

The date and time format is MMDDHHMMYYYY, where MM is the month number, DD is the day of the month, HH and MM are the hours and minutes, respectively, and YYYY is the year.

For example:

$ sudo date 010203042013
Wed Jan  2 03:04:00 UTC 2013

Discussion

If the Raspberry Pi is connected to the Internet, then as it boots up it will automatically set its own time using an Internet time server.

You can also use date to display the UTC time by just entering date on its own:

$ date
Wed Jan  2 03:08:14 UTC 2013

See Also

If you want your Raspberry Pi to maintain the correct time even when there is no network, then you can use a real-time clock (RTC) module (Recipe 12.13).

Problem

You want to know how much free space there is on the SD card.

Solution

Use the Linux df command:

$ df -h
Filesystem      Size  Used Avail Use% Mounted on
rootfs          3.6G  1.7G  1.9G  48% /
/dev/root       3.6G  1.7G  1.9G  48% /
devtmpfs        180M     0  180M   0% /dev
tmpfs            38M  236K   38M   1% /run
tmpfs           5.0M     0  5.0M   0% /run/lock
tmpfs            75M     0   75M   0% /run/shm
/dev/mmcblk0p1   56M   19M   38M  34% /boot

Discussion

Looking at the first line of the results, you can see that there is 3.6 GB of storage on the SD card, of which 1.7 GB is used.

When you run out of disk space, you are likely to get unexpected bad behavior, such as error messages saying that a file could not be written.

See Also

You can find the manpage for df using man df.

Problem

You want to convert your Raspberry Pi into a super-duper media center.

Solution

To use your Raspberry Pi as a media center, you should definitely go for the superior performance of the Raspberry Pi 3 or 2 Model B, as video playing is very processor-intensive. 

You can set up your Raspberry Pi as a media center during the NOOBS installation process (Recipe 1.5). Instead of selecting Raspbian as the distribution to install, select either OpenELEC_Pi1 if you have a Raspberry Pi 1 or OpenELEC_Pi2 if you have a Raspberry Pi 2.

OpenELEC is a distribution that optimizes your Raspberry Pi as a media center. It incudes the Kodi media center software, which is based on the XBMC open source project that was originally developed to convert Xbox game consoles into media centers. The code has since been ported to many platforms including the Raspberry Pi (Figure 4-1).

Figure 4-1. Raspberry Pi as a media center

Raspberry Pi is perfectly capable of playing full HD video as well as streamed music, MP3 files, and Internet radio.

Discussion

Kodi is a powerful piece of software with many features. Perhaps the simplest way to check that it is working is to put some music and/or video files onto a USB flash drive or external USB hard disk and connect it to the Raspberry Pi. You should be able to play them from Kodi.

Since the Raspberry Pi is likely to be sitting near your TV, you may find that your TV has a USB port that can provide enough current to run the Raspberry Pi. If this is the case, you won’t need a separate power supply.

A wireless keyboard and mouse are a good idea because if you buy them as a pair, they will use a single USB port for the dongle, which avoids the need for wires trailing all over the place. You can also buy mini-keyboards with built-in trackpads that are useful in this situation.

A wired network connection is generally higher performance and better than a WiFi connection, but it is not always convenient to have the Pi near an Ethernet socket. If this is the case, then you can set up XBMC to use a WiFi dongle for a network connection.

Setting up Kodi is very intuitive, and you can find full instructions on using the software at http://kodi.wiki/.

See Also

You can add an IR remote to Raspberry Pi to control XBMC.

Problem

You need to open word processor and spreadsheet documents on a Raspberry Pi.

Solution

Raspberry Pi is, after all, a Linux computer, so there are several office applications that you can install to use spreadsheets and word processor documents.

Programs for the Raspberry Pi are downloaded from the Internet, so you’ll need an Internet connection.

Before you install any new software, it is a good idea to open a Terminal and run the following command:

$ sudo apt-get update

To install the AbiWord word processor, run this command:

$ sudo apt-get install abiword

You will be asked to confirm the installation by typing Y; after a minute or so, installation will be complete. If you look on your Start menu, you will see a new section called Office, where you will find AbiWord (Figure 4-2).

AbiWord will open .doc, .docx, and other common word processing document formats.

If you need to use a spreadsheet, Gnumeric is a good choice. Install it by using the command:

$ sudo apt-get install gnumeric

Figure 4-2. AbiWord on Raspberry Pi

Discussion

If you find that the office applications run a bit too slowly, try overclocking your Raspberry Pi (Recipe 1.10) to speed things up. A Raspberry Pi 3 or 2 will also run office applications much better than an older Raspberry Pi.

See Also

There are efforts in progress to port other office software to the Raspberry Pi, such as Libre Office (a fork of Open Office). Check the Internet for the latest news on office software ports.

See Recipe 3.16 for information on using apt-get.

Problem

You want to use a browser other than Midori.

Solution

You can use a number of browsers on the Raspberry Pi. The Pi is not a powerful computer, and modern browsers and web pages can put quite a load on it. This means that when you use a browser on a Raspberry Pi, there is always a trade-off between features and performance.

Chromium (Figure 4-3), as the name suggests, will be familiar to users of Google Chrome. It is full-featured but noticeably slow when you try to scroll up and down a busy web page. You can install Chromium by using the following command, which will put a new link in the Internet section of your Start menu:

$ sudo apt-get install chromium-browser

Figure 4-3. The Chromium browser

Another popular alternative to Midori is Iceweasel (Figure 4-4). This browser is based on Firefox and will perform faster than Chromium because it uses the mobile version of websites (when available), which will normally be much simpler HTML. You can download and install Iceweasel by using this command:

$ sudo apt-get install iceweasel

Figure 4-4. The Iceweasel browser

Discussion

Since browsers require a certain amount of power for many websites, you really need a Raspberry Pi 3 or 2 to avoid a frustratingly slow experience. 

See Also

For more information on installing with apt-get, see Recipe 3.16.

Problem

You want to install software and games using the Pi Store.

Solution

The Pi Store (Figure 4-5) is the Raspberry Pi equivalent of Apple’s App Store or Google’s Play Store; it is a place from which you can download, install, and run all sorts of applications, both free and for sale.

You will find a shortcut on your Start menu for the Pi Store application in the Internet section.

Figure 4-5. The Pi Store

The first time you try to download an app, you will be asked to register. After you register, the app will download and appear in the My Library tab. To run the app, just double-click it.

Discussion

This is a convenient way to browse for interesting programs to use on your Raspberry Pi. More and more apps are finding their way into the store.

See Also

See the official Pi Store website.

Problem

You want to set up a Raspberry Pi as a webcam server.

Solution

Download the motion software. This will allow you to set up a Raspberry Pi with a USB webcam connected to it so you can connect to a web page and view the webcam.

To install the software, enter the following command in a Terminal window:

$ sudo apt-get install motion

Plug in your USB webcam and type lsusb to see if the webcam is connected:

$ lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 0424:9512 Standard Microsystems Corp.
Bus 001 Device 003: ID 0424:ec00 Standard Microsystems Corp.
Bus 001 Device 004: ID 3538:0059 Power Quotient International Co., Ltd
Bus 001 Device 006: ID eb1a:299f eMPIA Technology, Inc.

If you can’t see an entry that obviously looks like a webcam, try disconnecting it, run the command again, and see if one of the entries vanishes from the list. In this case, the final entry in the list is for the webcam.

There are now a few configuration changes that you need to make. First, edit the file /etc/motion/motion.conf using the command:

$ sudo nano /etc/motion/motion.conf

This is quite a big configuration file. Right near the top of the file, you will find the line daemon off; change this to daemon on.

The other change is much further down the file. You need to change webcam_localhost = on to webcam_localhost = off.

There is one other file that you need to change. Enter the command:

$ sudo nano /etc/default/motion

Change start_motion_daemon=no to start_motion_daemon=yes.

To get the web service running, issue the command:

$ sudo service motion start

You should now be able to open your web browser and view the webcam. To do this, you will need to know the IP address of your Raspberry Pi (Recipe 2.2).

From another computer on the same network, open a browser and go to the URL http://192.168.1.16:8081/. You will need to change the URL to match the IP address of your Raspberry Pi, but keep the :8081 port number on the end of the URL.

If all goes well, you should see something like Figure 4-6.

Figure 4-6. A Raspberry Pi webcam

Discussion

The motion software is actually really powerful; there are many other settings you can tweak to change how your webcam works.

By default, the webcam will be viewable only from within your network. If you want your webcam to be visible to the whole Internet, you need to set up port forwarding on your home hub. This will require you to log in to the admin console for the hub, look for the port forwarding option, and enable it for port 8081 for the IP address of the Raspberry Pi.

You will then be able to view the webcam by using the external IP address allocated by your ISP. This is usually shown on the front page of your admin console. But beware: unless you pay your ISP for a static IP address, this IP address is likely to change every time you restart your home hub modem.

Services such as No-ip can also be used to provide dynamic DNS, so that you can register a domain name that automatically follows changes to your IP address.

See Also

There is thorough documentation on the motion website.

You can find a list of webcams compatible with the Raspberry Pi at http://elinux.org/RPi_USB_Webcams.

The Raspberry Pi has a plug-in camera module (Recipe 1.14). At the time of writing, this is not compatible with motion, but it may be by the time you read this.

To use a webcam for computer vision projects, see Chapter 8.

See Recipe 3.16 for information on using apt-get.

Problem

You want to use a games emulator on a Raspberry Pi to make a vintage game console.

Solution

There are a number of emulators around for game consoles from the 1980s. One of the most popular is Stella, an emulator for the Atari 2600 (Figure 4-7).

Figure 4-7. Asteroids on the Stella Atari 2600 emulator

To install Stella, simply enter the following command in a Terminal window:

$ sudo apt-get install stella

Once it’s installed, you will find a new program in Games on your Start menu. Do not run it yet—you need to obtain the ROM image for a game.

If you are outside of the US and own the actual game, you are entitled to take a copy of the ROM image for backup purposes in many, but not all, countries. You can also find ROM images for some games that have been released without any license restrictions.

Now that you have the ROM image for the game you wish to play, create a folder called roms and place the ROM image in that folder. Then start Stella.

Click the image file to start a game. By default, the cursor keys are mapped to the joystick controls and the space bar is fire. You can change a number of settings for the emulator—for example, you almost certainly want to go to Video Settings and set it to fullscreen mode.

You can also use Input Settings and the Emul Events tab to map controller buttons to your keyboard.

Discussion

The emulator uses a surprisingly large amount of the Raspberry Pi’s meager resources, so you may find that you need to use a Raspberry Pi 3 or 2.

If you search the Internet, you will find that many people have taken this basic setup and added a retro USB controller, like the widely available and quite low-cost Nintendo Retrolink USB Super SNES Classic Controller, and built the Pi and a monitor into a big arcade-style housing.

See Also

There are a number of other console emulators available—at various stages of maturity, and thus reliability—on the Raspberry Pi. One to consider is Mame, which emulates a number of different game platforms.

For more information on installing with apt-get, see Recipe 3.16.

Problem

You want to run the popular game Minecraft on your Raspberry Pi.

Solution

Mojang, the original developers of Minecraft, have ported it to the Raspberry Pi and Minecraft Pi is pre-installed on the latest Raspbian distribution.

Figure 4-8. Minecraft on Raspberry Pi

Discussion

To get Minecraft to fit on the Raspberry Pi, the developers made some shortcuts in the graphics code. This means that you can only play the game directly on the Raspberry Pi with the keyboard, mouse, and monitor connected directly to it. It will not work over a remote VNC connection.

The Pi edition of Minecraft is based on the mobile version of Minecraft and lacks some features, most notably Redstone.

See Also

Find out more about the Raspberry Pi port of Minecraft.

You can also run a full version of the Minecraft Server on a Raspberry Pi (Recipe 4.8), although a Raspberry Pi 3 or 2 will perform a lot better (see Recipe 1.1).

Minecraft Pi also includes a Python programming interface, and in Recipe 7.20, you will learn how to send commands to Python over an SSH connection to do automated building.

Problem

You want to host a low-cost low-energy Minecraft server for you and your friends to play on.

Solution

The first step is to install the Java runtime environment by using these commands:

$ sudo apt-get update
$ sudo apt-get install openjdk-7-jdk

Then create a directory to contain the server code and fetch the spigot Minecraft server using the commands:

$ mkdir mcserver
$ cd mcserver
$ wget http://getspigot.org/spigot18/spigot_server.jar

Start the server using the command:

$ java -Xms512M -Xmx800M -jar spigot_server.jar nogui

The server will soon give you the following error message:

[15:51:26 WARN]: Failed to load eula.txt
[15:51:26 INFO]: You need to agree to the EULA in order to run 
the server. Go to eula.txt for more info.
[15:51:26 INFO]: Stopping server

This is telling you that you need to accept the terms of the license agreement by editing the file called eula.txt that the server has just created for you. So, open eula.txt using nano using the command:

$ nano eula.txt

Change the line that says eula=false to eula=true and save the file, then run, and then start the server again. This time it will take several minutes to create a world and start up the server. Don’t worry, the next time you run it, it will be a lot quicker.

Eventually, the server will start and you can test it by connecting to it from another computer running Minecraft on your network.

Start Minecraft and click on Multiplayer and then Direct Connect. Enter the IP address of your Raspberry Pi (Figure 4-9) and then click Connect.

Figure 4-9. Connecting to the Minecraft server

Once you are connected, you and anyone else on your network can join the server and start playing (Figure 4-10).

Figure 4-10. Playing on a Raspberry Pi Minecraft server

You will probably want to give yourself operator status in the game by typing the command:

> op YourName

where YourName is your nickname in the game.

Discussion

A Raspberry Pi 2 with its four processor cores and 1 GB of memory will run a pretty decent Minecraft server. The parameters -Xms512M and -Xmx800M set the minimum and maximum amounts of memory that Java should use for the server.

The LXTerminal or SSH window will let you know when anyone connects to the server, and you can also issue various server admin commands from here. Type help for a list of commands.

When you want to stop the server, enter the command stop.

[17:41:10 INFO]: UUID of player SimonMonk is 4e3e1a27-4e7e-4bfb-b331-a30af5bd49ec
[17:41:11 INFO]: SimonMonk[/192.168.1.5:58831] logged in with entity id
382 at ([world]257.23244892748414, 67.0, 185.3728463324922)
>stop
[17:41:20 INFO]: Stopping the server
[17:41:20 INFO]: Stopping server
[17:41:20 INFO]: Saving players
[17:41:20 INFO]: SimonMonk lost connection: Server closed
[17:41:20 INFO]: SimonMonk left the game.
[17:41:21 INFO]: Saving worlds
[17:41:21 INFO]: Saving chunks for level 'world'/Overworld
[17:41:24 INFO]: Saving chunks for level 'world_nether'/Nether
[17:41:24 INFO]: Saving chunks for level 'world_the_end'/The End
>pi@Pi2headless ~/mcserver $ 

To allow your friends from the wider Internet to play on your server, you will need to use your router’s admin console to set up port forwarding.

See Also

You do not need to be directly connected to the Raspberry Pi to start a Minecraft server; it will work just fine if started from SSH (Recipe 2.7).

For information on running your own Minecraft server, check out http://uk.ign.com/wikis/minecraft/Admin_and_Server_Commands.

See also the Minecraft Pi edition (Recipe 4.7).

Problem

You want to run the Quake derivative Open Arena on your Raspberry Pi.

Solution

Download and run Open Arena (Figure 4-11) from the Pi Store.

Figure 4-11. Open Arena on Raspberry Pi

Discussion

Not surprisingly, you will find Open Arena in the Games section of the Pi Store. Since the game is quite violent and bloody, it comes under a plain wrapper.

See Also

Find out more about Open Arena.

For more information on using the Pi Store, see Recipe 4.4.

Problem

You want to convert your Raspberry Pi into a high-powered FM transmitter that will send a radio signal to a normal FM radio receiver (Figure 4-12).

Solution

The clever folks at Imperial College, London, have created some C code and a Python wrapper that allow you to do just this. The download even includes the theme from Star Wars to play as a sample.

All you need is a short length of wire attached to GPIO pin 4. A female-to-male header lead will work just fine for this. In fact, it should work with the radio right next to your Pi without any kind of antenna—such is the strength of the transmission.

Figure 4-12. Raspberry Pi as an FM transmitter

The first step is to install the pifm library using the following commands:

$ mkdir pifm
$ cd pifm
$ wget http://www.icrobotics.co.uk/wiki/images/c/c3/Pifm.tar.gz
$ tar -xzf Pifm.tar.gz

Next, find yourself an FM radio receiver and tune it to 103.0 MHz. If this frequency is already occupied by some other transmission, pick another frequency and make note of it.

Now run the following command (changing the final parameter from 103.0 if you had to change frequency):

sudo ./pifm sound.wav 103.0

If all is well, you should hear the stirring tones of the Star Wars theme.

Discussion

You need to know that this project may not be legal in your country. The power output is higher than that of FM transmitters used with MP3 players.

You can play other .wav files, but they must be 16-bit 44.1kHz.

The code also includes a Python library that you can use within your own Python programs. So, you could write a user interface to allow the selection and playing of tunes.

The following fragment of code illustrates the use of the Python interface:

pi@raspberrypi ~/pifm $ sudo python
Python 2.7.3 (default, Jan 13 2013, 11:20:46)
[GCC 4.6.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import PiFm
>>> PiFm.play_sound("sound.wav")

Were you to put a Raspberry Pi in your vehicle, this would be a great way of outputting sound through the vehicle’s audio system—especially if you use the features of the latest version of pifm, which allow you to stream music to the FM transmitter from various sources.

See Also

This description is based on the original post from Imperial College London. This also includes clever tricks for piping music from various sources to pifm including from a USN microphone, which opens up all sorts of opportunities.

Problem

You want to edit an image.

Solution

Download and run the GNU image manipulation program (GIMP; see Figure 4-13).

Figure 4-13. GIMP on the Raspberry Pi

To install GIMP, open a Terminal session and type the following command:

$ sudo apt-get install gimp

Once GIMP is installed, you’ll find a new entry in your Start menu under the Graphics heading called GNU Image Manipulation Program.

Discussion

Despite being very hungry for memory and processor power, GIMP is quite usable on a Raspberry Pi model B.

See Also

Find out more from the GIMP website.

GIMP has a lot of features and is a very sophisticated image editing program, so it does take a little learning. You’ll find an online manual for the software at the GIMP website, under the Documentation tab.

For more information on installing with apt-get, see Recipe 3.16.

Problem

You want to be able to play Internet radio on your Raspberry Pi.

Solution

Install the VLC media player by running the following command:

sudo apt-get install vlc

Once it’s installed, you can find VLC in the Sound & Video section of your Start menu.

Run the program and select the Open Network Stream option on the Media menu. This will open a dialog box (see Figure 4-14) where you can enter the URL of the Internet radio station that you wish to play.

You will need to plug headphones or amplified speakers into the audio socket on the Raspberry Pi.

Discussion

VLC can also be run from the command line:

$ vlc http://www.a-1radio.com/listen.pls -I dummy

VLC will probably produce a series of error messages, but then play the audio just fine.

Figure 4-14. VLC on Raspberry Pi

See Also

This recipe borrows heavily from this tutorial, where Jan Holst takes things a step further and adds radio-style controls to the project.

For UK readers, you can find a list of the BBC radio stream URLs online.

Problem

You need to use Python but are unsure about which version to use.

Solution

Use both. Use Python 3 until you face a problem that is best solved by reverting to version 2.

Discussion

Although the latest version of Python is Python 3 and has been for years, you will find that a lot of people stick to Python 2. In fact, in the Raspbian distribution, both versions are supplied and version 2 is just called Python, whereas version 3 is called Python 3. You even run Python 3 by using the command python3. The examples in this book are written for Python 3 unless otherwise stated. Most will run on both Python 2 and Python 3 without modification.

This reluctance on the part of the Python community to ditch the old Python 2 is largely because Python 3 introduced some changes that broke compatibility with version 2. This means that some of the huge body of third-party libraries that have been developed for Python 2 won’t work under Python 3.

My strategy is to write in Python 3 wherever possible, and revert to Python 2 when I have to because of compatibility problems.

See Also

For a good summary of the Python 2 versus Python 3 debate, see the Python wiki.

Problem

You are not sure what to use to write your Python programs.

Solution

The common Raspberry Pi distributions come with the IDLE Python development tool in both the Python 2 and Python 3 versions. If you are using Raspbian, you will find shortcuts to both versions of IDLE labeled Python 2 and Python 3 in the Programming section of your Start menu (Figure 5-1).

Figure 5-1. Starting Python with IDLE

Discussion

IDLE and IDLE 3 appear to be identical; the only difference is the version of Python that they use, so open IDLE 3 (Figure 5-2).

Figure 5-2. IDLE Python console

The window that opens is labeled Python Shell. This is an interactive area where you can type Python and see the results immediately. So try typing the following into the shell next to the >>> prompt:

>>> 2 + 2
4
>>>

Python has evaluated the expression 2 + 2 and given us the answer of 4.

The Python Shell is fine for trying things out, but if you want to write programs, then you need to use an editor. To open a new file to edit using IDLE, select New Window from the File menu (Figure 5-3).

You can now enter your program into the editor window. Just to try things, paste the following text into the editor, save the file as count.py, and then select Run Module from the Run menu. You can see the results of the program running in the Python console:

for i in range(1, 10):
    print(i)

Figure 5-3. IDLE editor

Python is unusual for a programming language in that indentation is a fundamental part of the language. Whereas many C-based languages use { and } to delimit a block of code, Python uses the indentation level. So in the preceding example, Python knows that print is to be invoked repeatedly as part of the for loop because it is indented out four spaces.

The convention used in this book is to use four spaces for a level of indentation.

Notice how IDLE uses color-coding to highlight the structure of the program.

See Also

Many of the recipes in this chapter use IDLE to edit Python examples.

As well as using IDLE to edit and run Python files, you can also edit files in nano (Recipe 3.6) and then run them from a Terminal session (Recipe 5.4).

Problem

You want to enter Python commands without writing a whole program.

Solution

Use the Python console, either within IDLE (Recipe 5.2) or in a Terminal session.

Discussion

To start a Python 2 console in a Terminal window, just type the command python; for a Python 3 console, enter the command python3.

The >>> prompt indicates that you can type Python commands. If you need to type multiline commands, then the console will automatically provide a continuation line indicated by three dots. You still need to indent any such lines, by four spaces, as shown in the following session:

>>> for i in range(1, 10):
...   print(i)
...
1
2
3
4
5
6
7
8
9
>>>

You will need to press Enter twice after your last command for the console to recognize the end of the indented block and run the code.

The Python console also provides a command history so that you can move back and forth through your previous commands using the up and down keys.

See Also

If you have more than a couple of lines that you want to type in, then chances are you would be better off using IDLE (Recipe 5.2) to edit and run a file.

Problem

Running programs from within IDLE is fine, but sometimes you want to run a Python program from a Terminal window.

Solution

Use the python or python3 command in a Terminal, followed by the filename containing the program you want to run.

Discussion

To run a Python 2 program from the command line, use a command like this:

$ python myprogram.py

If you want to run the program using Python 3, then change the command python to python3. The Python program that you wish to run should be in a file with the extension .py.

You can run most Python programs as a normal user; however, there are some, especially those that use the GPIO port, that you need to run as superuser. If this is the case for your program, prefix the command with sudo:

$ sudo python myprogram.py

In the earlier examples, you have to include python in the command to run the program, but you can also add a line to the start of a Python program so that Linux knows it is a Python program. This special line is called a shebang (a contraction of hash-bang) and the following single-line example program has it as its first line.

#!/usr/bin/python
print("I'm a program, I can run all by myself")

Before you can run this directly from the command line, you have to give the file write permissions by using the command below (see Recipe 3.13).

$ chmod +x test.py

The parameter +x means add execute permission.

Now you will be able to run the Python program test.py by using the single command:

$ ./test.py
I'm a program, I can run all by myself
$ 

The ./ at the start of the line is needed for the command line to find the file.

See Also

Recipe 3.23 allows you to run a Python program as a timed event.

To automatically run a program at startup, see Recipe 3.22.

Problem

You want to give a value a name.

Solution

Assign a value to a name using =.

Discussion

In Python, you don’t have to declare the type of a variable, you can just assign it a value, as shown in the following examples:

a = 123
b = 12.34
c = "Hello"
d = 'Hello'
e = True

You can define character-string constants using either single or double quotes. The logical constants in Python are True and False, and are case-sensitive.

By convention, variable names begin with a lowercase letter and if the variable name consists of more than one word, the words are joined together with an underscore character. It is always a good idea to give your variables descriptive names.

Some examples of valid variable names are x, total, and number_of_chars.

See Also

Variables can also be assigned a value that is a list (Recipe 6.1) or dictionary (Recipe 6.12).

For more information on arithmetic with variables, see Recipe 5.8.

Problem

You want to see the value of a variable.

Solution

Use the print command. You can try the following example in the Python console (Recipe 5.3):

>>> x = 10
>>> print(x)
10
>>>

Discussion

In Python 2, you can use the print command without brackets. However, this is not true in Python 3, so for compatibility with both versions of Python, use brackets around the value you are printing.

See Also

To read user input, see Recipe 5.7.

Problem

You want to prompt the user to enter a value.

Solution

Use the input (Python 3) or raw_input (Python 2) command. You can try the following example in the Python 3 console (Recipe 5.3):

>>> x = input("Enter Value:")
Enter Value:23
>>> print(x)
23
>>>

Discussion

In Python 2, raw_input must be substituted for input in the preceding example.

Python 2 also has an input function, but this validates the input and attempts to convert it into a Python value of the appropriate type, whereas raw_input does the same thing as input in Python 3 and just returns a string.

See Also

Find more information on Python 2 input.

Problem

You want to do arithmetic in Python.

Solution

Use the +, -, *, and / operators.

Discussion

The most common operators for arithmetic are +, -, *, and /, which are, respectively, add, subtract, multiply, and divide.

You can also group parts of the expression together with parentheses, as shown in the following example, which, given a temperature in degrees Celsius, converts it to degrees Fahrenheit:

>>> tempC = input("Enter temp in C: ")
Enter temp in C: 20
>>> tempF = (int(tempC) * 9) / 5 + 32
>>> print(tempF)
68.0
>>>

Other arithmetic operators include % (modulo remainder) and ** (raise to the power of). For example, to raise 2 to the power of 8, you would write the following:

>>> 2 ** 8
256

See Also

See Recipe 5.7 on using the input command, and Recipe 5.12 on converting the string value from input to a number.

The Math library has many useful math functions that you can use.

Problem

You want to create a string variable.

Solution

Use the assignment operator and a string constant to create a new string. You can use either double or single quotation marks around the string, but they must match.

For example:

>>> s = "abc def"
>>> print(s)
abc def
>>>

Discussion

If you need to include double or single quotes inside a string, then pick the type of quotes that you don’t want to use inside the string as the beginning and end markers of the string. For example:

>>> s = "Isn't it warm?"
>>> print(s)
Isn't it warm?
>>>

Sometimes you’ll need to include special characters such as tab or newline inside your string. This requires the use of what are called escape characters. To include a tab, use \t, and for a newline, use \n. For example:

>>> s = "name\tage\nMatt\t14"
>>> print(s)
name	age
Matt	14
>>>

See Also

For a full list of escape characters, see the Python Reference Manual.

Problem

You want to join a number of strings together.

Solution

Use the + (concatenate) operator.

For example:

>>> s1 = "abc"
>>> s2 = "def"
>>> s = s1 + s2
>>> print(s)
abcdef
>>>

Discussion

In many languages, you can have a chain of values to concatenate, some of which are strings and some of which are other types such as numbers; numbers will automatically be converted into strings during the concatenation. This is not the case in Python, and if you try the following command, you will get an error:

>>> "abc" + 23
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: Can't convert 'int' object to str implicitly

You need to convert each component that you want to concatenate to a string before concatenating, as shown in this example:

>>> "abc" + str(23)
'abc23'
>>>

See Also

See Recipe 5.11 for more information about converting numbers to strings using the str function.

Problem

You want to convert a number into a string.

Solution

Use the str Python function. For example:

>>> str(123)
'123'
>>>

Discussion

A common reason for wanting to convert a number into a string is so you can then concatenate it with another string (Recipe 5.10).

See Also

For the reverse operation of turning a string into a number, see Recipe 5.12.

Problem

You want to convert a string into a number.

Solution

Use the int or float Python function.

For example, to convert -123 into a number, you could use:

>>> int("-123")
-123
>>>

This will work on both positive and negative whole numbers.

To convert a floating-point number, use float instead of int:

>>> float("00123.45")
123.45
>>>

Discussion

Both int and float will handle leading zeros correctly and are tolerant of any spaces or other whitespace characters around the number.

You can also use int to convert a string representing a number in a number base other than the default of 10 by supplying the number base as the second argument. The following example converts the string representation of binary 1001 into a number:

>>> int("1001", 2)
9
>>>

This second example converts the hexadecimal number AFF0 to an integer:

>>> int("AFF0", 16)
45040
>>>

See Also

For the reverse operation of turning a number into a string, see Recipe 5.11.

Problem

You need to know how many characters there are in a string.

Solution

Use the len Python function.

Discussion

For example, to find the length of the string abcdef, you would use:

>>> len("abcdef")
6
>>>

See Also

The len command also works on lists (Recipe 6.3).

Problem

You need to find the position of one string within another.

Solution

Use the find Python function.

For example, to find the starting position of the string def within the string abcdefghi, you would use:

>>> s = "abcdefghi"
>>> s.find("def")
3
>>>

Note that the character positions start at 0, so a position of 3 means the fourth character in the string.

Discussion

If the string you’re looking for doesn’t exist in the string being searched, then find returns the value -1.

See Also

The replace function is used to find and then replace all occurrences of a string (Recipe 5.16).

Problem

You want to cut out a section of a string between certain character positions.

Solution

Use the Python [:] notation.

For example, to cut out a section from the second character to the fifth character of the string abcdefghi, you would use:

>>> s = "abcdefghi"
>>> s[1:5]
'bcde'
>>>

Note that the character positions start at 0, so a position of 1 means the second character in the string, and 5 means the sixth, but the character range is exclusive at the high end so the letter f is not included in this example.

Discussion

The [:] notation is actually quite powerful. You can omit either argument, in which case, the start or end of the string is assumed as appropriate. For example:

>>> s[:5]
'abcde'
>>>

and

>>> s = "abcdefghi"
>>> s[3:]
'defghi'
>>>

You can also use negative indices to count back from the end of the string. This can be useful in situations such as when you want to find the three-letter extension of a file, as in the following example:

>>> "myfile.txt"[-3:]
'txt'

See Also

Recipe 5.10 describes joining strings together rather than splitting them.

Recipe 6.10 uses the same syntax but with lists rather than strings.

Problem

You want to replace all occurrences of a string within another string.

Solution

Use the replace function.

For example, to replace all occurrences of X with times, you would use:

>>> s = "It was the best of X. It was the worst of X"
>>> s.replace("X", "times")
'It was the best of times. It was the worst of times'
>>>

Discussion

The string being searched for must match exactly; that is, the search is case-sensitive and will include spaces.

See Also

See Recipe 5.14 for searching a string without performing a replacement.

Problem

You want to convert all the characters in a string to upper- or lowercase letters.

Solution

Use the upper or lower function as appropriate.

For example, to convert aBcDe to uppercase, you would use:

>>> "aBcDe".upper()
'ABCDE'
>>>

To convert it to lowercase, you would use:

>>> "aBcDe".lower()
'abcde'
>>>

Discussion

Like most functions that manipulate a string in some way, upper and lower do not actually modify the string but rather return a modified copy of the string.

For example, the following code returns a copy of the string s, but note how the original string is unchanged.

>>> s = "aBcDe"
>>> s.upper()
'ABCDE'
>>> s
'aBcDe'
>>>

If you want to change the value of s to be all uppercase, then you need to do the following:

>>> s = "aBcDe"
>>> s = s.upper()
>>> s
'ABCDE'
>>>

See Also

See Recipe 5.16 for replacing text within strings.

Problem

You want to run some Python commands only when some condition is true.

Solution

Use the Python if command.

The following example will print the message x is big only if x has a value greater than 100:

>>> x = 101
>>> if x > 100:
...     print("x is big")
...
x is big

Discussion

After the if keyword, there is a condition. This condition often, but not always, compares two values and gives an answer that is either True or False. If it is True, then the subsequent indented lines will all be executed.

It is quite common to want to do one thing if a condition is True and something different if the answer is False. In this case, the else command is used with if, as shown in this example:

x = 101
if x > 100:
    print("x is big")
else:
    print("x is small")

print("This will always print")

You can also chain together a long series of elif conditions. If any one of the conditions succeeds, then that block of code is executed and none of the other conditions are tried. For example:

x = 90
if x > 100:
    print("x is big")
elif x < 10:
    print("x is small")
else:
    print("x is medium")

This example will print x is medium.

See Also

See Recipe 5.19 for more information on different types of comparisons you can make.

Problem

You want to compare values.

Solution

Use one of the comparison operators: <, >, <=, >=, ==, or !=.

Discussion

You used the < (less than) and > (greater than) operators in Recipe 5.18. Here’s the full set of comparison operators:

Some people prefer to use the <> operator in place of !=. Both work the same.

You can test these commands using the Python console (Recipe 5.3), as shown in the following exchange:

>>> 1 != 2
True
>>> 1 != 1
False
>>> 10 >= 10
True
>>> 10 >= 11
False
>>> 10 == 10
True
>>>

A common mistake is to use = (set a value) instead of == (double equals) in comparisons. This can be difficult to spot because if one half of the comparison is a variable, it is perfectly legal syntax and will run, but it will not produce the result you were expecting.

As well as comparing numbers, you can also compare strings by using these comparison operators, as shown here:

>>> 'aa' < 'ab'
True
>>> 'aaa' < 'aa'
False

The strings are compared lexicographically—that is, in the order that you would find them in a dictionary.

This is not quite correct because, for each letter, the uppercase version of the letter is considered less than the lowercase equivalent. Each letter has a value that is its ASCII code.

See Also

See also Recipes 5.18 and 5.20.

Problem

You need to specify a complex condition in an if statement.

Solution

Use one of the logical operators: and, or, and not.

Discussion

As an example, you may want to check whether a variable x has a value between 10 and 20. For that, you would use the and operator:

>>> x = 17
>>> if x >= 10 and x <= 20:
...     print('x is in the middle')
...
x is in the middle

You can combine as many and and or statements as you need and also use brackets to group them if the expressions become complicated.

See Also

See Recipes 5.18 and 5.19.

Problem

You need to repeat some program code an exact number of times.

Solution

Use the Python for command and iterate over a range.

For example, to repeat a command 10 times, use the following example:

>>> for i in range(1, 11):
...     print(i)
...
1
2
3
4
5
6
7
8
9
10
>>>

Discussion

The second parameter in the range command is exclusive; that is, to count up to 10, you must specify a value of 11.

See Also

If the condition for stopping the loop is more complicated than simply repeating a number of times, see Recipe 5.22.

If you are trying to repeat commands for each element of a list or dictionary, see Recipes 6.7 or 6.15, respectively.

Problem

You need to repeat some program code until something changes.

Solution

Use the Python while statement. The while statement repeats its nested commands until its condition becomes false. The following example will stay in the loop until the user enters X for exit:

>>> answer = ''
>>> while answer != 'X':
...     answer = input('Enter command:')
...
Enter command:A
Enter command:B
Enter command:X
>>>

Discussion

Note that the preceding example uses the input command as it works in Python 3. To run the example in Python 2, substitute the command raw_input for input.

See Also

If you just want to repeat some commands a number of times, see Recipe 5.21.

If you are trying to repeat commands for each element of a list or dictionary, then see Recipes 6.7 or 6.15, respectively.

Problem

You are in a loop and need to exit the loop if some condition occurs.

Solution

Use the Python break statement to exit either a while or for loop.

The following example behaves in exactly the same way as the example code in Recipe 5.22:

>>> while True:
...     answer = input('Enter command:')
...     if answer == 'X':
...             break
...
Enter command:A
Enter command:B
Enter command:X
>>>

Discussion

Note that this example uses the input command as it works in Python 3. To run the example in Python 2, substitute the command raw_input for input.

This example behaves in exactly the same way as the example of Recipe 5.22. However, in this case, the condition for the while loop is just True, so the loop will never end unless we use break to exit the loop when the user enters X.

See Also

You can also leave a while loop by using its condition; see Recipe 5.18.

Problem

You want to avoid repeating the same code over and over in a program.

Solution

Create a function that groups together lines of code, allowing it to be called from multiple places.

Creating and then calling a function in Python is illustrated in the following example:

def count_to_10():
    for i in range(1, 11):
        print(i)

count_to_10()

In this example, we have defined a function using the def command that will print out the numbers between 1 and 10 whenever it is called:

count_to_10()

Discussion

The conventions for naming functions are the same as for variables in Recipe 5.5; that is, they should start with a lowercase letter, and if the name consists of more than one word, the words should be separated by underscores.

The example function is a little inflexible because it can only count to 10. If we wanted to make it more flexible—so it could count up to any number—then we can include the maximum number as a parameter to the function, as this example illustrates:

def count_to_n(n):
    for i in range(1, n + 1):
        print(i)

count_to_n(5)

The parameter name n is included inside the parentheses and then used inside the range command, but not before 1 is added to it.

Using a parameter for the number you want to count up to means that if you usually count to 10 but sometimes count to a different number, you will always have to specify the number. You can, however, specify a default value for a parameter, and hence have the best of both worlds, as shown in this example:

def count_to_n(n=10):
    for i in range(1, n + 1):
        print(i)

count_to_n()

This will now count to 10 unless a different number is specified when you call the function.

If your function needs more than one parameter, perhaps to count between two numbers, then the parameters are separated by commas:

def count(from_num=1, to_num=10):
    for i in range(from_num, to_num + 1):
		print(i)

count()
count(5)
count(5, 10)

All these examples are functions that do not return any value; they just do something. If you need a function to return a value, you need to use the return command.

The following function takes a string as an argument and adds the word please to the end of the string.

def make_polite(sentence):
    return sentence + " please"

print(make_polite("Pass the cheese"))

When a function returns a value, you can assign the result to a variable, or as in this example, print out the result.

See Also

To return more than one value from a function, see Recipe 7.3.

Problem

You want to use a variable to hold a series of values rather than just one value.

Solution

Use a list. In Python, a list is a collection of values stored in order so that you can access them by position.

You create a list using [ and ] to contain its initial contents:

>>> a = [34, 'Fred', 12, False, 72.3]
>>>

Unlike the more rigid arrays in languages like C, you don’t need to specify the size of a list in Python when you declare it. You can also change the number of elements in the list any time you like.

Discussion

As this example illustrates, the items in a list do not have to be all of the same type, although they often are.

If you want to create an empty list that you can add items to later, you can write:

>>> a = []
>>>

See Also

All the recipes between Recipes 6.1 and 6.11 involve the use of lists.

Problem

You want to find individual elements of a list or change them.

Solution

Use the [] notation to access elements of a list by their position in the list. For example:

>>> a = [34, 'Fred', 12, False, 72.3]
>>> a[1]
'Fred'

Discussion

The list positions (indices) start at 0 for the first element.

As well as using the [] notation to read values out of a list, you can also use it to change values at a certain position. For example:

>>> a = [34, 'Fred', 12, False, 72.3]
>>> a[1] = 777
>>> a
[34, 777, 12, False, 72.3]

If you try to change (or, for that matter, read) an element of a list using an index that is too large, you will get an “Index out of range” error:

>>> a[50] = 777
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IndexError: list assignment index out of range
>>>

See Also

All the recipes between Recipes 6.1 and 6.11 involve the use of lists.

Problem

You need to know how many elements there are in a list.

Solution

Use the len Python function. For example:

>>> a = [34, 'Fred', 12, False, 72.3]
>>> len(a)
5

Discussion

The len command also works on strings (Recipe 5.13).

See Also

All the recipes between Recipes 6.1 and 6.11 involve the use of lists.

Problem

You need to add an item to a list.

Solution

Use the append, insert, or extend Python functions.

To add a single item to the end of a list, use append:

>>> a = [34, 'Fred', 12, False, 72.3]
>>> a.append("new")
>>> a
[34, 'Fred', 12, False, 72.3, 'new']

Discussion

Sometimes you don’t want to add the new elements to the end of a list, but rather you want to insert them at a certain position in the list. For this, use the insert command. The first argument is the index where the item should be inserted, and the second argument is the item to be inserted:

>>> a.insert(2, "new2")
>>> a
[34, 'Fred', 'new2', 12, False, 72.3]

Note how all the elements after the newly inserted element are shuffled up one position.

Both append and insert add only one element to a list. The extend function adds all the elements of one list to the end of another:

>>> a = [34, 'Fred', 12, False, 72.3]
>>> b = [74, 75]
>>> a.extend(b)
>>> a
[34, 'Fred', 12, False, 72.3, 74, 75]

See Also

All the recipes between Recipes 6.1 and 6.11 involve the use of lists.

Problem

You need to remove an item from a list.

Solution

Use the pop Python function.

The command pop with no parameters removes the last element of a list:

>>> a = [34, 'Fred', 12, False, 72.3]
>>> a.pop()
72.3
>>> a
[34, 'Fred', 12, False]

Discussion

Notice that pop returns the value removed from the list.

To remove an item in a position rather than the last element, use pop with a parameter of the position from which the item will be removed:

>>> a = [34, 'Fred', 12, False, 72.3]
>>> a.pop(0)
34

If you use an index position that is beyond the end of the list, you will get an “Index out of range” exception.

See Also

All the recipes between Recipes 6.1 and 6.11 involve the use of lists.

Problem

You need to convert a string of words separated by some character into an array of strings, with each string in the array being one of the words.

Solution

Use the split Python string function.

The command split with no parameters separates the words out of a string into individual elements of an array:

>>> "abc def ghi".split()
['abc', 'def', 'ghi']

If you supply split with a parameter, then it will split the string, using the parameter as a separator. For example:

>>> "abc--de--ghi".split('--')
['abc', 'de', 'ghi']

Discussion

This command can be very useful when you are, say, importing data from a file. The split command can optionally take an argument that is the string to use as a delimiter when you are splitting the string. So, if you were to use commas as a separator, you could split the string as follows:

>>> "abc,def,ghi".split(',')
['abc', 'def', 'ghi']

See Also

All the recipes between Recipes 6.1 and 6.11 involve the use of lists.

Problem

You need to apply some lines of code to each item in a list in turn.

Solution

Use the for Python language command:

>>> a = [34, 'Fred', 12, False, 72.3]
>>> for x in a:
...     print(x)
...
34
Fred
12
False
72.3
>>>

Discussion

The for keyword is immediately followed by a variable name (in this case, x). This is called the loop variable and will be set to each of the elements of the list specified after in.

The indented lines that follow will be executed one time for each element in the list. Each time around the loop, x will be given the value of the element in the list at that position. You can then use x to print out the value, as shown in the previous example.

See Also

All the recipes between Recipes 6.1 and 6.11 involve the use of lists.

Problem

You need to run some lines of code for each item in a list in turn, but you also need to know the index position of each item.

Solution

Use the for Python language command along with the enumerate command.

>>> a = [34, 'Fred', 12, False, 72.3]
>>> for (i, x) in enumerate(a):
...     print(i, x)
...
(0, 34)
(1, 'Fred')
(2, 12)
(3, False)
(4, 72.3)
>>>

Discussion

It’s quite common to need to know the position of something in the list while enumerating each of the values. An alternative method is to simply count with an index variable and then access the value by using the [] syntax:

>>> a = [34, 'Fred', 12, False, 72.3]
>>> for i in range(len(a)):
...     print(i, a[i])
...
(0, 34)
(1, 'Fred')
(2, 12)
(3, False)
(4, 72.3)
>>>

See Also

All the recipes between Recipes 6.1 and 6.11 involve the use of lists.

See Recipe 6.7 to iterate over a list without needing to know each item’s index position.

Problem

You need to sort the elements of a list.

Solution

Use the sort Python language command:

>>> a = ["it", "was", "the", "best", "of", "times"]
>>> a.sort()
>>> a
['best', 'it', 'of', 'the', 'times', 'was']

Discussion

When you sort a list, you’ll actually be modifying it rather than returning a sorted copy of the original list. This means that if you also need the original list, you need to use the copy command in the standard library to make a copy of the original list before sorting it:

>>> import copy
>>> a = ["it", "was", "the", "best", "of", "times"]
>>> b = copy.copy(a)
>>> b.sort()
>>> a
['it', 'was', 'the', 'best', 'of', 'times']
>>> b
['best', 'it', 'of', 'the', 'times', 'was']
>>>

See Also

All the recipes between Recipes 6.1 and 6.11 involve the use of lists.

Problem

You need to make a sublist of a list, using a range of the original list’s elements.

Solution

Use the [:] Python language construction. The following example returns a list containing the elements of the original list from index position 1 to index position 2 (the number after the : is exclusive):

>>> l = ["a", "b", "c", "d"]
>>> l[1:3]
['b', 'c']

Note that the character positions start at 0, so a position of 1 means the second character in the string, and 5 means the sixth, but the character range is exclusive at the high end, so the letter d is not included in this example.

Discussion

The [:] notation is actually quite powerful. You can omit either argument, in which case the start or end of the list is assumed as appropriate. For example:

>>> l = ["a", "b", "c", "d"]
>>> l[:3]
['a', 'b', 'c']
>>> l[3:]
['d']
>>>

You can also use negative indices to count back from the end of the list. The following example returns the last two elements in the list:

>>> l[-2:]
['c', 'd']

Incidentally, l[:-2] returns ['a', 'b'] in the preceding example.

See Also

All the recipes between Recipes 6.1 and 6.11 involve the use of lists.

See Recipe 5.15 where the same syntax is used for strings.

Problem

You need to apply a function to each element of a list and collect the results.

Solution

Use the Python language feature called comprehensions.

The following example converts each string element of the list to uppercase and returns a new list that is the same length as the old one, but with all the strings in uppercase:

>>> l = ["abc", "def", "ghi", "ijk"]
>>> [x.upper() for x in l]
['ABC', 'DEF', 'GHI', 'IJK']

Although it can get confusing, there is no reason why you can’t combine these kinds of statements, nesting one comprehension inside another.

Discussion

This is a very concise way of doing comprehensions. The whole expression has to be enclosed in brackets ([]). The first element of the comprehension is the code to be evaluated for each element of the list. The rest of the comprehension looks rather like a normal list iteration command (Recipe 6.7). The loop variable follows the for keyword, and the list to be used follows the in keyword.

See Also

All the recipes between Recipes 6.1 and 6.11 involve the use of lists.

Problem

You need to create a lookup table where you associate values with keys.

Solution

Use a Python dictionary.

Arrays are great when you need to access a list of items in order or you always know the index of the element that you want to use. Dictionaries are an alternative to lists for storing collections of data, but they are organized very differently.

Figure 6-1 shows how a dictionary is organized.

Figure 6-1. A Python dictionary

A dictionary stores key/value pairs in such a way that you can use the key to retrieve that value very efficiently and without having to search the whole dictionary.

To create a dictionary, you use the {} notation:

>>> phone_numbers = {'Simon':'01234 567899', 'Jane':'01234 666666'}

Discussion

In this example, the keys of the dictionary are strings, but they do not have to be; they could be numbers or in fact any data type, although strings are most commonly used.

The values can also be of any data type, including other dictionaries or lists. The following example creates one dictionary (a) and then uses it as a value in a second dictionary (b):

>>> a = {'key1':'value1', 'key2':2}
>>> a
{'key2': 2, 'key1': 'value1'}
>>> b = {'b_key1':a}
>>> b
{'b_key1': {'key2': 2, 'key1': 'value1'}}

When you display the contents of a dictionary, you will notice that the order of the items in the dictionary may not match the order in which they were specified when the dictionary was created and initialized with some contents:

>>> phone_numbers = {'Simon':'01234 567899', 'Jane':'01234 666666'}
>>> phone_numbers
{'Jane': '01234 666666', 'Simon': '01234 567899'}

Unlike lists, dictionaries have no concept of keeping items in order. Because of the way they are represented internally, the order of a dictionary’s contents will be—for all intents and purposes—random.

The reason the order appears to be random is that the underlying data structure is a hash table. Hash tables use a hashing function to decide where to store the value; the hashing function calculates a numeric equivalent to any object.

You can find out more about hash tables at Wikipedia.

See Also

All the recipes between Recipes 6.12 and 6.15 involve the use of dictionaries.

Problem

You need to find and change entries in a dictionary.

Solution

Use the Python [] notation. Use the key of the entry to which you need access inside the brackets:

>>> phone_numbers = {'Simon':'01234 567899', 'Jane':'01234 666666'}
>>> phone_numbers['Simon']
'01234 567899'
>>> phone_numbers['Jane']
'01234 666666'

Discussion

The lookup process is in one direction only, from key to value.

If you use a key that is not present in the dictionary, you will get a key error. For example:

{'b_key1': {'key2': 2, 'key1': 'value1'}}
>>> phone_numbers = {'Simon':'01234 567899', 'Jane':'01234 666666'}
>>> phone_numbers['Phil']
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError: 'Phil'
>>>

As well as using the [] notation to read values from a dictionary, you can also use it to add new values or overwrite existing ones.

The following example adds a new entry to the dictionary with a key of Pete and a value of 01234 777555:

>>> phone_numbers['Pete'] = '01234 777555'
>>> phone_numbers['Pete']
'01234 777555'

If the key is not in use in the dictionary, a new entry is automatically added. If the key is already present, then whatever value was there before will be overwritten by the new value.

This is in contrast to trying to read a value from the dictionary, where an unknown key will cause an error.

See Also

All the recipes between Recipes 6.12 and 6.15 involve the use of dictionaries.

For information on handling errors, see Recipe 7.10.

Problem

You need to remove an item from a dictionary.

Solution

Use the pop command, specifying the key for the item that you want to remove:

>>> phone_numbers = {'Simon':'01234 567899', 'Jane':'01234 666666'}
>>> phone_numbers.pop('Jane')
'01234 666666'
>>> phone_numbers
{'Simon': '01234 567899'}

See Also

All the recipes between Recipes 6.12 and 6.15 involve the use of dictionaries.

Problem

You need to do something to each of the items in the dictionary in turn.

Solution

Use the for command to iterate over the keys of the dictionary:

>>> phone_numbers = {'Simon':'01234 567899', 'Jane':'01234 666666'}
>>> for name in phone_numbers:
...     print(name)
...
Jane
Simon

Discussion

There are a couple of other techniques that you can use to iterate over a dictionary. The following form can be useful if you need access to the values as well as the keys:

>>> phone_numbers = {'Simon':'01234 567899', 'Jane':'01234 666666'}
>>> for name, num in phone_numbers.items():
...     print(name + " " + num)
...
Jane 01234 666666
Simon 01234 567899

See Also

All the recipes between Recipes 6.12 and 6.15 involve the use of dictionaries.

See the for command used elsewhere in Recipes 5.21, 6.7, and 6.11.

Problem

You want to format numbers to a certain number of decimal places.

Solution

Apply a format string to the number. For example:

>>> x = 1.2345678
>>> "x={:.2f}".format(x)
'x=1.23'
>>>

Discussion

The formatting string can contain a mixture of regular text and markers delimited by { and }. The parameters to the format function (there can be as many as you like) will be substituted in place of the marker, according to the format specifier.

In the preceding example, the format specifier is :.2f, which means that the number will be specified with two digits after the decimal place and is a float f.

If you wanted the number to be formatted so that the total length of the number is always seven digits (or padding spaces), then you would add another number before the decimal place like this:

>>> "x={:7.2f}".format(x)
'x=   1.23'
>>>

In this case, since the number is only three digits long, there are four spaces of padding before the 1. If you wanted the padding to take the form of leading zeros, you would use:

>>> "x={:07.2f}".format(x)
'x=0001.23'
>>> 

A more complicated example might be to display the temperature in both degrees Celsius and degrees Fahrenheit, as shown here:

>>> c = 20.5
>>> "Temperature {:5.2f} deg C, {:5.2f} deg F.".format(c, c * 9 / 5 + 32)
'Temperature 20.50 deg C, 68.90 deg F.'
>>>

See Also

Formatting in Python involves a whole formatting language.

Problem

You want to convert a date into a string and format it in a certain way. 

Solution

Apply format string to the date object.

For example:

>>> from datetime import datetime
>>> d = datetime.now()
>>> "{:%Y-%m-%d %H:%M:%S}".format(d)
'2015-12-09 16:00:45'
>>>

Discussion

The Python formatting language includes some special symbols for formatting date. %Y, %m, and %d correspond to year, month, and day numbers, respectively.

Other symbols useful for formatting the date are %B, which supplies the full name of the month and %Y, which gives the year in four digit format, as shown here:

>>> "{:%d %B %Y}".format(d)
'09 December 2015'

See Also

See Recipe 7.1  for formatting of numbers.

Formatting in Python actually involves a whole formatting language. You will find full details of this at http://strftime.org/.

Problem

You need to write a function that returns more than one value.

Solution

Return a Python tuple and use the multiple variable assignment syntax. A tuple is a Python data structure that’s a little like a list, except that tuples are enclosed in parentheses rather than brackets. They are also of fixed size.

For example, you could have a function that converts a temperature in Kelvin into both Fahrenheit and Celsius. You can arrange for this function to return the temperature in both these units by separating the multiple return values by commas:

>>> def calculate_temperatures(kelvin):
...     celsius = kelvin - 273
...     fahrenheit = celsius * 9 / 5 + 32
...     return celsius, fahrenheit
...
>>> c, f = calculate_temperatures(340)
>>>
>>> print(c)
67
>>> print(f)
152.6

When you call the function, you just provide the same number of variables before the = and each of the return values will be assigned to the variables in the same position.

Discussion

Sometimes when you just have one or two values to return, this is the right way to return multiple values. However, if the data is complex, you might find that the solution is neater if you use Python’s object-oriented features and define a class that contains the data. That way, you can return an instance of the class rather than a tuple.

See Also

See Recipe 7.4 for information on defining classes.

Problem

You need to group together related data and functionality into a class.

Solution

Define a class and provide it with the member variables you need.

The following example defines a class to represent an address book entry:

class Person:
    '''This class represents a person object'''

    def __init__(self, name, tel):
        self.name = name
        self.tel = tel

The first line inside the class definition uses the triple quotes to denote a documentation string. This should explain the purpose of the class. Although entirely optional, adding a documentation string to a class allows others to see what the class does. This is particularly useful if the class is made available for others to use.

Doc strings are not like normal comments because, although they are not active lines of code, they do get associated with the class, so, at any time, you can read the doc string for a class by using the following command:

Person.__doc__

Inside the class definition is the constructor method, which will be called automatically whenever you create a new instance of the class. A class is like a template, so in defining a class called Person, we do not create any actual Person objects until later:

def __init__(self, name, tel):
    self.name = name
    self.tel = tel

The constructor method must be named as shown with double underscores on either side of the word init.

Discussion

One way in which Python differs from most object-oriented languages is that you have to include the special variable self as a parameter to all the methods that you define within the class. This is a reference to, in this case, the newly created instance. The variable self is the same concept as the special variable this that you find in Java and some other languages.

The code in this method transfers parameters that were supplied to it into member variables. The member variables do not need to be declared in advance, but do need to be prefixed by self..

So the following line:

self.name = name

creates a variable called name that’s accessible to every member of the class Person and initializes it with the value passed into the call to create an instance, which looks like this:

p = Person("Simon", "1234567")

We can then check that our new Person object, p, has a name of "Simon" by typing the following:

>>> p.name
Simon

In a complex program, it is good practice to put each class in its own file with a filename that matches the class name. This also makes it easy to convert the class into a module (see Recipe 7.11).

See Also

See Recipe 7.5  for information on defining methods.

Problem

You need to add a method to a class.

Solution

The following example shows how you can include a method within a class definition:

class Person:
    '''This class represents a person object'''

    def __init__(self, first_name, surname, tel):
        self.first_name = first_name
        self.surname = surname
        self.tel = tel

    def full_name(self):
        return self.first_name + " " + self.surname

The full_name method concatenates the first name and surname attributes of the person, with a space in between.

Discussion

You can think of methods as just functions that are tied to a specific class and may or may not use member variables of that class in their processing. So, as with a function, you can write whatever code you like in a method and also have one method call another.

If one method calls another within the same class, the call to the method has to be prefixed with self.

See Also

See Recipe 7.4  for information on defining a class.

Problem

You need a specialized version of an existing class.

Solution

Use inheritance to create a subclass of an existing class and add new member variables and methods.

By default, all new classes that you create are subclasses of object. You can change this by specifying the class you want to use as a superclass in parentheses after the class name in a class definition. The following example defines a class (Employee) as a subclass of Person and adds a new member variable (salary) and an extra method (give_raise):

class Employee(Person):

    def __init__(self, first_name, surname, tel, salary):
        super().__init__(first_name, surname, tel)
        self.salary = salary

    def give_raise(self, amount):
        self.salary = self.salary + amount

Note that the preceding example is for Python 3. For Python 2, you can’t use super the same way. Instead, you must write:

class Employee(Person):

    def __init__(self, first_name, surname, tel, salary):
        Person.__init__(self, first_name, surname, tel)
        self.salary = salary

    def give_raise(self, amount):
        self.salary = self.salary + amount

Discussion

In both of these examples, the initializer method for the subclass first uses the initializer method of the parent class (superclass) and then adds the member variable. This has the advantage that you do not need to repeat the initialization code in the new subclass.

See Also

See Recipe 7.4  for information on defining a class.

The Python inheritance mechanism is actually very powerful and supports multiple inheritance, where a subclass inherits from more than one superclass. For more on multiple inheritance, see the official documentation for Python.

Problem

You need to write something to a file.

Solution

Use the open, write, and close functions to open a file, write some data, and then close the file, respectively:

>>> f = open('test.txt', 'w')
>>> f.write('This file is not empty')
>>> f.close()

Discussion

Once you have opened the file, you can make as many writes to it as you like before you close the file. Note that it is important to use close because although each write should update the file immediately, it may be buffered in memory and data could be lost. It could also leave the file locked so that other programs can’t open it.

The open method takes two parameters. The first is the path to the file to be written. This can be relative to the current working directory, or if it starts with a /, an absolute path.

The second parameter is the mode in which the file should be opened. To overwrite an existing file or create the file with the name specified if it doesn’t exist, just use w. Table 7-1 shows the full list of file mode characters. You can combine these using +. So to open a file in read and binary mode, you would use:

>>> f = open('test.txt', 'r+b')

Binary mode allows you to read or write binary streams of data, such as images, rather than text.

See Also

To read the contents of a file, see Recipe 7.8. For more information on handling exceptions, see Recipe 7.10.

Problem

You need to read the contents of a file into a string variable.

Solution

To read a file’s contents, you need to use the file methods open, read, and close. The following example reads the entire contents of the file into the variable s:

f = open('test.txt')
s = f.read()
f.close()

Discussion

You can also read text files one line at a time using the method readline.

The preceding example will throw an exception if the file does not exist or is not readable for some other reason. You can handle this by enclosing the code in a try/except construction like this:

try:
    f = open('test.txt')
    s = f.read()
    f.close()
except IOError:
    print("Cannot open the file")

See Also

To write things to a file and for a list of file open modes, see Recipe 7.7.

For more information on handling exceptions, see Recipe 7.10.

Problem

You want to save the entire contents of a data structure to a file so that it can be read the next time the program is run.

Solution

Use the Python pickling feature to dump the data structure to file in a format that can be automatically read back into memory as an equivalent data structure later on.

The following example saves a complex list structure to file:

>>> import pickle
>>> mylist = ['some text', 123, [4, 5, True]]
>>> f = open('mylist.pickle', 'w')
>>> pickle.dump(mylist, f)
>>> f.close()

To unpickle the contents of the file into a new list, use the following:

>>> f = open('mylist.pickle')
>>> other_array = pickle.load(f)
>>> f.close()
>>> other_array
['some text', 123, [4, 5, True]]

Discussion

Pickling will work on pretty much any data structure you can throw at it. It does not need to be a list.

The file is saved in a text format that is sort of human-readable, but you will not normally need to look at or edit the text file.

See Also

To write things to a file and for a list of file open modes, see Recipe 7.7.

Problem

If something goes wrong while a program is running, you want to catch the error or exception and display a more user-friendly error message.

Solution

Use Python’s try/except construct.

The following example, taken from Recipe 7.8, catches any problems in opening a file:

try:
    f = open('test.txt')
    s = f.read()
    f.close()
except IOError:
    print("Cannot open the file") 

Because you wrapped the potentially error-prone commands to open the file in a try/except construction, any error that occurs will be captured before it displays any error message allowing you to handle it in your own way. In this case, that means displaying the friendly message "Cannot open the file".

Discussion

A common situation where runtime exceptions can occur, in addition to during file access, is when you are accessing a list and the index you are using is outside the bounds of the list. For example, this happens if you try to access the fifth (index 4) element of a three-element list:

>>> list = [1, 2, 3]
>>> list[4]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IndexError: list index out of range

Errors and exceptions are arranged in a hierarchy, and you can be as specific or general as you like when catching the exceptions.

Exception is pretty near the top of that tree and will catch almost any exception. You can also have separate except sections for catching different types of exception and handling, each in a different way. If you do not specify any exception class, all exceptions will be caught.

Python also allows you to have else and finally clauses in your error handling:

list = [1, 2, 3]
try:
    list[8]
except:
    print("out of range")
else:
    print("in range")
finally:
    print("always do this")

The else clause will be run if there is no exception, and the finally clause will be run whether there is an exception or not.

Whenever an exception occurs, you can get more information about it by using the exception object, which is available only if you use the as keyword, as shown in the following example:

>>> list = [1, 2, 3]
>>> try:
...     list[8]
... except Exception as e:
...     print("out of range")
...     print(e)
...
out of range
list index out of range
>>>

This allows you to handle the error in your own way, but also keep hold of the original error message.

See Also

Python documentation for Python exception class hierarchy.

Problem

You want to use a Python module in your program.

Solution

Use the import command: