Download NOOBS_vX_Y_Z.zip (as of this writing, it was NOOBS_v1_3_4.zip but the filename may be different by the time you read this) from http://raspberrypi.org/downloads.

Insert the SD card into your computer. Most SD cards are FAT32 formatted at the factory, so unless you’re using an SD card that you’ve formatted yourself, extracting the NOOBS zip to the SD card is enough. After you unzip the file, make sure that the bootcode.bin file is in the root (top-level) directory of the SD card.

In modern versions of Linux, Windows, and Mac you can just double-click or right-click the NOOBS zip file to extract it. For older versions of Windows, you can install 7zip to let you extract zip files.

Connecting the cables is easy, because each cable will fit only its correct socket. Plug the mouse and the keyboard into the Raspberry Pi’s USB ports. If you’re using an HDMI monitor, connect an HDMI cable between the monitor and Raspberry Pi. If you’re using an NTSC or PAL monitor, use a composite video cable to connect the yellow plug on the Raspberry Pi to the monitor.

Next, connect the micro USB cable to Raspberry to supply power. Plug that cable into either a computer’s USB port or a 5 volt USB charger that provides at least 700 mA.

As soon as you connect power to the Raspberry Pi, it boots. No power switch is needed.

You are greeted with a graphical menu of different operating systems as well as language and keyboard type. Choose “Raspbian [RECOMMENDED]” (Figure 1-2) and select your language and type of keyboard you’ll be using.

Figure 1-2. Choosing an operating system

If you know any Debian, Mint or Ubuntu, you will feel at home with this choice; if you don’t, read on and you’ll still feel at home! Raspbian takes a few minutes to finish installing (Figure 1-3). After the installer completes, it will indicate that it installed the operating system successfully. Press Enter or click OK to reboot.

Figure 1-3. Raspbian installs

The Raspberry Pi configuration utility opens. Use arrow keys and Tab to navigate, and press Enter/Return to select an option, as shown in Figure 1-4.

Figure 1-4. Changing your password

You’ll want to enable the Boot to Desktop option. When you have finished changing settings, use Tab to select Finish and reboot when asked.

After the Raspberry Pi reboots, it will start up in a graphical desktop and will log you in automatically.

If you have chosen not to enable Boot to Desktop, you’ll always start in the command-line interface. Log in as “raspberry” with password “pi” (unless you changed the password). After you log in, type startx to start the X Window System, which is the graphical desktop.

Welcome to Linux! You have now installed Raspbian on Raspberry Pi (Figure 1-5).

Figure 1-5. Welcome to Linux

Here are some solutions to common problems.

If you get any error messages not mentioned here, try typing the exact error message into a Google search. Be sure to use the exact error message shown. If the message appears as the system is booting, take a photo of the screen with your camera or cell phone and transcribe it.

Are you ready to feel the power of the $ prompt?

The command line has stood the test of time, and it might be something you’ll teach your grandchildren. The commands you use all the time, like pwd, ls, or cat, existed long before Linux was invented. (Linux was written by a Finnish student in Helsinki, just five kilometers from the botanical garden where I’m writing this.) Power users on both OS X and Windows dive down into the command line when they need to do something they can’t do with a mouse alone.

Most of the commands you’ll use with Raspberry Pi are the same you’d use on a Mac or Linux computer, and are similar even to the command-line tools on Windows.

As you may know, most of the world’s servers run Linux. Google, Facebook, Amazon, and most supercomputers run Linux. Web servers don’t run a graphical user interface, so that’s why most programmers and system administrators must know how to use the command-line interface (CLI). You can use these commands on a Linux desktop or laptop, too.

The CLI is easy to automate. Whatever commands you can type on the command prompt (also known as the shell), you can also turn into a program. You just put each command into a text file, one command per line (we show you how to do this in the next section). Then you can run that program with dash filename (on Raspberry Pi, the shell is named dash). Whenever you realize you’re typing the same 10 commands over and over, it’s time to turn them into a script.

Even though CLI scripts are so easy to write that they are good for quick-and-dirty one-off scripts, they are also suitable for serious, mission-critical applications. For example, Linux uses scripts for booting and controlling daemons (server applications that run in the background).

After you boot your Raspberry Pi into the graphical user interface, you can start up the command-line interface by double-clicking the LXTerminal icon on your desktop.

The prompt $ means Linux is waiting for your command. Type pwd to print your current working directory (where you are in the file system). Linux answers with a path, such as /home/pi/.

To list the files in the working directory, type ls and press Return or Enter. These are the files you can readily manipulate. Whenever you get an error like No such file or directory, just use pwd to see where you are and ls to see what files are in the working directory.

To edit (or create) a file called foo.txt, use nano foo.txt. Type some text, then press Control-X to save it (when prompted whether to save, type y. When asked for the filename, just press Enter or Return). To edit the file some more, type the command nano foo.txt again.

In Linux, most things are text files. With just the commands listed in the previous section, along with the sudo command, a skillful hacker can change many system settings. All configuration in Linux is stored in text files. System-wide configuration files are in the /etc/ directory and per user configuration is in the user’s home directory, /home/pi/.

Even the Pi’s input and output pins can be manipulated by editing text files under the /sys/ directory. Later in this book, you will learn to connect sensors and LEDs to Raspberry using GPIO pins.

If you connected the Pi to the network with an Ethernet cable before booting, your Raspberry Pi should already be connected to the Internet. Test this by typing ping www.google.com. You’ll see a result every second. Kill the command after a while by typing Control-C. If the network is working well, it should report a packet loss of 0%. You can also download whole web pages with commands like curl botbook.com and wget botbook.com.

Linux is well known for its robust security model. The separation of user privileges is one of its key features. Normal users can make changes only to files that affect their working environment. This means that they can modify files only in their home directory (/home/pi/) and in temporary working directories such as /tmp/.

The super user, or root user, is all-powerful and can change any file on the system. To use root’s privileges, put sudo in front of a command. Putting sudo in front of the command runs that commands under the privileges of the root user.

For example, Raspbian’s package manager makes it very easy to install additional software, but you need to use root’s privileges to install anything. Before you install new software, you need to update the list of what’s available with sudo apt-get update. This requires a network connection because all the software packages are on a file server.

You can install any program from a repository by specifying its package name. To install ipython (an interactive tool for experimenting with the Python language and data visualization), use sudo apt-get -y install ipython. The -y parameter tells the package manager to assume a “yes” answer to any questions it asks. The package manager (apt) does everything for you.

After a moment, you can run the newly installed package by typing ipython. Any python command will work here, but exit() will get you back to the command prompt (“$”), where you can type shell commands.

Installing daemons (also known as servers) is just as easy. Try installing the most popular web server in the planet, Apache, with this command: sudo apt-get -y install apache2. When it finishes, you can pull down your web server’s raw home page with curl localhost. To browse your Apache web server from another computer, determine your IP address with the output of the ifconfig command and type that address into a web browser on another computer connected to your network.

Phew! That was a lot of command line if you are (were) a beginner. To give yourself a well-earned break, power off the Raspberry Pi by typing the command sudo shutdown -P now. Just like you do on your workstation, you must shut down properly so that data gets actually written to disk before you power off. Once it shuts down, you can unplug it from the USB power source. When you’re ready to use it again, plug it back in.

Still wondering what we’re talking about with the sudo sandwich? Try searching the Web for “xkcd sudo sandwich.” You can use the rest of your break to read some of the other comics there.

See Appendix A for a cheat sheet of Linux commands.

$ nano
supercalifragilisticexpialidocious.foo
.bar.txt.botbook.com.pdf.cc

$ ls
supercalifragilisticexpialidocious.foo
.bar.txt.botbook.com.pdf.cc

In this “Hello GPIO World” example, you’ll attach a new LED to Raspberry Pi and blink it.

We start all of our projects with a “Hello World” on any platform, on any language. So whenever you are about to build something more complicated, it’s a good idea to build this “Hello GPIO World” first. This lets you confirm that the hardware and software are functioning at the most basic level. If your “Hello World” example doesn’t work, you need to fix it before trying something more complicated.

Parts needed:

If you don’t have all the parts at hand, see Troubleshooting for suggestions. For wires, a female connector is one that has a receptacle and a male connector is one that has an extending pin. You will often see female abbreviated as F and male abbreviated as M, along with other characteristics of the connector, such as its length. The type of female-to-male jumper wires you need are typically sold as “male to female breadboard jumper wires.”

Figure 1-6. GPIO header

The circuit is simply an LED with a current limiting resistor, connected in series between GPIO pin 27 and ground (Figure 1-7). Connect the short (negative) lead of the LED to the black wire, and the long (positive) lead to the resistor. You should make these connections while the Raspberry Pi is shut down and unplugged.

Figure 1-7. LED hello breadboard

Build the circuit on the breadboard (Figure 1-8). Double-check all connections to avoid breaking your Raspberry Pi. After you’re sure you’ve connected the wires correctly, you can power up your Pi.

To learn about how the Raspberry Pi’s pins are numbered, read on.

Figure 1-8. Hello GPIO!

Each GPIO pin has two numbers: purpose and physical location. To find the correct pin in the GPIO header, you should learn to convert between the two numbering systems.

Locate the GPIO pin header on Raspberry Pi (Figure 1-6). When converting between purpose and physical location numbers, use the numbering diagram (Figure 1-9).

Figure 1-9. GPIO numbering

The left side of the numbering diagram shows the purpose of the pins (GND, GPIO 27). The right side of the numbering diagram shows the physical location (1 to 26).

The physical pin header has a running number, from 1 to 26. There is a tiny white box drawn near pin one, and it is also labeled P1. This physical pin header number tells you where to insert the jumper wire. These physical numbers are also known as board numbers.

There is also another, purpose-based numbering. The code you’ll be writing uses GPIO numbers, such as GPIO 27, which corresponds to physical pin 13 (which is the pin you connected to the resistor with a wire). Circuit diagrams are likely to refer to ground (GND), +5 V, and +3.3 V, and Figure 1-9 will help you find them. Some pins can have multiple purposes. For example, GPIO 10 can be used for the SPI bus. These purpose-based numbers are also known as BCM numbers.

To help you get started, the two pins used here are listed in Table 1-1. For future projects, learn to find these numbers in the numbering diagram (Figure 1-9).

Let’s see how to use the command-line interface to control the GPIO pins we just connected. First you’ll try it out as root, then advance to using it without needing to invoke sudo privileges each time.

Text files control everything in Linux. The kernel GPIO driver (a piece of software that controls how Linux talks to GPIO pins) makes the GPIO pins available to you through the virtual /sys/ file system. To control GPIO, you simply edit or otherwise make changes to these text files.

You don’t need a graphical user interface at this point, so we can do everything from the LXTerminal command-line interface. Double-click its icon to launch it.

To turn on the pin, you first export it, configure it for “out” mode, and write the number “1” to it. All this is done by editing text files.

Earlier, you saw how to modify the contents of a file with the nano text editor. Here’s how you can modify files without needing the editor.

First, let’s look at how to display text. You can print text to the terminal using this command (don’t type the $; it indicates the shell prompt):

$ echo "Hello BotBook"

Any text you display this way can also be redirected to overwrite a file (be careful using this, and don’t overwrite anything important):

$ echo "Hello BotBook" > foo.txt

If the file foo.txt, did not exist, it will be created. If it existed, it was overwritten without warning. You can use the > (redirection) operator to send the output of almost any command to a text file. You can see what’s inside that file with the cat command:

$ cat foo.txt

Hello BotBook

Couldn’t you just use nano foo.txt? Yes, of course you could. But it requires more typing, and it’s not as easy to automate.

We’ll use sudo the first time through lighting an LED. Does it feel wrong to use root for non-administrative tasks? If not, it should; if you mistype a command with sudo, you can potentially render your operating system unusable and will need to reinstall it.

Don’t worry, you’ll use sudo just to initially try it. Later, you’ll fix Linux’s file permissions and interact with the files that control GPIOs as a normal user.

Type sudo -i to get a root shell. Use root shell only as long as required by this task, and type exit when you’re done. You’ll notice that your prompt changes to a hash mark, #. Be careful what you type as root, as mistakes can break your operating system.

After you start the root shell, export GPIO pin 27 to be able to manipulate it (remember, just type the text to the right of the # shell prompt):

# echo "27">/sys/class/gpio/export

This creates the new virtual file you’ll use to blink the LED. Next, set pin 27 to out mode, so that you can turn it on and off.

# echo "out" > /sys/class/gpio/gpio27/direction

Now turn on the pin:

# echo "1" > /sys/class/gpio/gpio27/value

Your LED should light up now. Once you have enjoyed the light for a while, turn it off:

# echo "0" > /sys/class/gpio/gpio27/value

Did your LED light up? Hello, GPIO world!

Once you are done with playing root, remember to type exit. Your prompt should return to the dollar sign symbol $, indicating that you are working with the shell as a normal user.

If you had trouble setting things up, check out the following:

Figure 1-10. LED polarity

As always, start with a “Hello World” to test your environment. Using a text editor, create the file:

$ nano hello.py

The file needs only one line:

print "Hello world!"

Save the file (in nano, you save with Control-X, then type y and press Enter/Return).

Now run your program:

$ python hello.py

Hello world!

$ python led_hello.py

Blinking LED on GPIO 27 once...

# led_hello.py - light a LED using Raspberry Pi GPIO
# (c) BotBook.com - Karvinen, Karvinen, Valtokari

import time     # 
import os

def writeFile(filename, contents):      # 
        with open(filename, 'w') as f:  # 
                f.write(contents)

# main

print "Blinking LED on GPIO 27 once..."         # 

if not os.path.isfile("/sys/class/gpio/gpio27/direction"):      # 
        writeFile("/sys/class/gpio/export", "27")       # 

time.sleep(0.1)
writeFile("/sys/class/gpio/gpio27/direction", "out")    # 

writeFile("/sys/class/gpio/gpio27/value", "1")  # 
time.sleep(2)   # seconds       # 
writeFile("/sys/class/gpio/gpio27/value", "0") # 

You have now set up your own $35 Linux environment. And you can even wire it directly to hardware. This means you have combined the power of Linux and electronics.

The system administration techniques you have been practicing are leading you in the right direction. It’s always good to use minimum (non-root) privileges whenever possible.

To keep playing with your Raspberry Pi, you can now move ahead to the sensor projects in this book. The individual sensor examples teach you how to use digital input, analog input, industry standard protocols, and to measure pulse length with an interrupt.

You can apply your new system administration and GPIO skills with all the sensors in this book. Raspberry Pi usually shines with sensors that use more advanced protocols. This advantage is clear with I2C sensors such as Wii Nunchuk, MPU 6050 accelerometer-gyro, and the GY65 atmospheric pressure sensor.

Welcome to embedded Linux!