Table 1-1. The status LEDs
ACT	Green	Lights when the SD card is accessed
PWR	Red	Hooked up to 3.3V power

Chapter 1. Getting Up and Running

A few words come up over and over when people talk about the Raspberry Pi: small, cheap, hackable, education oriented. However, it would be a mistake to describe it as plug and play, even though it is easy enough to plug it into a TV set and get something to appear on the screen. This is not a consumer device, and depending on what you intend to do with your Raspberry Pi, you’ll need to make a number of decisions about peripherals and software when getting up and running.

Of course, the first step is to actually acquire a Raspberry Pi. Chances are you have one by now, but if not, the Raspberry Pi Foundation has arrangements with a few manufacturers from whom you can buy a Pi directly at the well-known $25–$35 price range. The official distributors are:

Premier Farnell/Element 14: A British electronics distributor with many subsidiaries all over the world (such as Newark and MCM in the United States)
RS Components: Another UK-based global electronics distributor (and parent of Allied Electronics in the United States)

The Raspberry Pi’s low price is obviously an important part of the story. Enabling the general public to go directly to a distributor and order small quantities for the same price offered to resellers is an unusual arrangement. A lot of potential resellers were confounded by the original announcements of the price point; it was hard to see how there could be any profit margin. That’s why you’ll see some “downstream” resellers adding a slight markup to the $35 price (usually to $40 or so). Though the general public can still buy direct from the distributors mentioned here for the original price, the retailers and resellers often can fulfill orders faster and provide many well-curated accessories for Raspberry Pi. Here are a few of our favorite resellers:

Adafruit: Based in New York City, Limor Fried (“Ladyada”) and her team have created one of the go-to ecommerce sites for things related to making. They make and sell a lot of neat Raspberry Pi accessories.
Maker Shed: The official store of Make. They make some neat Raspberry Pi kits that can be found in retailers like Barnes & Noble.
Sparkfun: Sparkfun sells lots of electronics prototyping tools and supplies, including a bunch of accessories and kits for Raspberry Pi.
Micro Center: With 25 bricks-and-mortar stores across the United States, Micro Center has positioned itself as one of the premier resellers of Raspberry Pi and tons of accessories. Browsing the aisles at Micro Center is a great way to discover new Raspberry Pi–related products.
Pimoroni: The gang from Pimoroni have been creating and selling fantastic Raspberry Pi products from Sheffield, UK. Fun fact: one of their founders, Paul, is the designer of the Raspberry Pi logo!
The Pi Hut: The Pi Hut is another UK-based Raspberry Pi reseller. It creates many Raspberry Pi kits and also is an official distributor for Raspberry Pi Zero.

Enough microeconomic gossip; let’s start by taking a closer look at the Raspberry Pi board.

A Tour of the Boards

There have been quite a few different versions of the Raspberry Pi board. The first version was the Raspberry Pi 1 Model B, which was followed by a simpler and cheaper Model A. In 2014, the Raspberry Pi Foundation announced a significant revision (and improvement) in the board design: the Raspberry Pi 1 Model B+. The Model B+ set the form-factor for “mainline” Raspberry Pis for the foreseeable future. Since then, the Foundation has also created a device for embedding the Pi in products, called the Compute Module. In 2015, it also released a stripped-down $5 model called Raspberry Pi Zero. And as of February 2016, Raspberry Pi 3 Model B is the latest mainline Raspberry Pi. A few different types of Raspberry Pis are pictured in Figure 1-1.

Note

Over the years, there have been a few different versions of the mainline Raspberry Pi, which is the $35 model with four USB ports that most people tend to use. The versions are called Raspberry Pi 1 Model B+, Raspberry Pi 2 Model B, and Raspberry Pi 3 Model B. Each of these models added performance improvements to the processor. Raspberry Pi 2 added more RAM, and Raspberry Pi 3 added on-board WiFi and Bluetooth.

If you’re following along with the examples in this book, any of these mainline Raspberry Pis will do just fine.

Let’s start with a tour of what you’ll see when you take your Raspberry Pi out of the box.

It’s tempting to think of Raspberry Pi as a microcontroller development board like Arduino or as a laptop replacement. In fact, it is more like the exposed innards of a mobile device with maker-friendly headers for various ports and functions. Figure 1-2 shows the parts of the board.

Here’s a description of each part:

The processor

At the heart of the Raspberry Pi is the same kind of processor you’d find in a cell phone. If you’re using Raspberry Pi 3, this is a 64-bit, quad core 1.2 GHz system on a chip, which is built on the ARM architecture. ARM chips come in a variety of architectures with different cores configured to provide different capabilities at different price points. Raspberry Pi 1 has 512 megabytes of RAM and Raspberry Pi 2 and 3 have one gigabyte of RAM.

Composite video and analog audio out

Analog audio and video outputs are available on a standard 3.5mm 4-pole plug connector. One side of the connecting cable is a four-connector mini jack (which looks like a headphone jack), and the other side is three RCA plugs for stereo audio (red and white) and composite NTSC or PAL video (yellow).

Status LEDs

Two indicator LEDs on the board provide visual feedback (Table 1-1). There are also network activity LEDs on the Ethernet jack itself.

Table 1-1. The status LEDs

ACT

Green

Lights when the SD card is accessed

PWR

Red

Hooked up to 3.3V power

Note

Starting with Raspberry Pi 3, the status LEDs are placed near the MicroUSB power port as shown in Figure 1-2. For previous boards, you’ll find them near the GPIO pins, in place of the WiFi antenna
External USB ports

On the mainline versions of Raspberry Pi, there are four USB 2.0 ports for connecting peripherals like keyboards, mice, thumb drives, and printers. While many USB devices can be powered from these ports, you may want to consider using a powered external hub if you have peripherals that need more power, such as a hard drive.

Ethernet port

This is a standard RJ45 Ethernet port capable of 10 or 100 megabits per second data speeds. Connect this to your router to get online; otherwise you can use WiFi.

HDMI connector

The HDMI port provides digital video and audio output. Fourteen different video resolutions are supported, and the HDMI signal can be converted to DVI (used by many monitors), composite (analog video signal usually carried over a yellow RCA connector), or SCART (a European standard for connecting audiovisual equipment) with external adapters.

Power input

One of the first things you’ll realize is that there is no power switch on the Pi. This MicroUSB connector is used to supply power (this isn’t an additional USB port; it’s only for power). MicroUSB was selected because the connector is cheap and USB power supplies are easy to find.

The microSD card slot

You’ll notice there’s no hard drive on the Pi; everything is stored on a microSD card. Raspberry Pi 1 and 2 are equipped with spring-loaded slots, so you’ll push to put the microSD card in and push again to take it out. With Raspberry Pi 3, they did away with the spring-loaded component in favor of a friction-fit slot. On that model, you’ll push to insert the microSD card and pull to remove it. Of course, you should only do this when the Raspberry Pi is powered down.

Figure 1-3 shows all of the power and input/output (I/O) pins on the Raspberry Pi.

Here’s a description of the pins and headers shown:

General-purpose input/output (GPIO) and other pins

The current Raspberry Pis have a 2 × 20 pin GPIO header. Chapters 6 and 7 show how to use these pins to read buttons and switches and control actuators like LEDs, relays, or motors.
The Camera Serial Interface (CSI) connector

This port allows a camera module to be connected directly to the board (see Figure 1-4).
The Display Serial Interface (DSI) connector

This connector accepts a 15-pin, flat ribbon cable that can be used to communicate with the official Raspberry Pi touch display.

The Proper Peripherals

Now that you know where everything is on the board, you’ll need to know a few things about the proper peripherals to use with the Pi. There are a bunch of prepackaged starter kits that have well-vetted parts lists; there are a few caveats and gotchas when fitting out your Raspberry Pi. There’s an extensive list of supported peripherals on the eLinux.org wiki, but these are the most basic:

A power supply: This is the most important peripheral to get right; you should use a MicroUSB adapter that can provide 5V and at least 1,500mA (1.5A) of current for Raspberry Pi 3 and 1,000 mA (1A) for Raspberry Pi 2 and older. A cell phone charger won’t necessarily cut it, even if it has the correct connector. Many cell phone chargers don’t provide enough current, so check the rating marked on the back. An underpowered Pi may still seem to work but will be flaky and may fail unpredictably. If in doubt, use the official Raspberry Pi power supply, which is available at most places where Raspberry Pis are sold.

There are also a number of battery-pack solutions for taking your Raspberry Pi on the go; the same rules about voltage and current apply there as well.

Note

With the current version of the board, it is possible to power the Pi from a USB hub that feeds power back into one of the two external USB ports. However, there isn’t much protection circuitry, so it may not be the best idea to power it over the external USB ports. This is especially true if you’re going to be doing electronics prototyping where you may accidentally create shorts that may draw a lot of current.

A microSD card

You may also want to consider some of the following add-ons:

A powered USB hub: If you want to add more than four USB devices to a mainline Raspberry Pi, you’ll need a USB hub. A powered USB 2.0 hub is recommended.
Heatsink

The Case

You may find that you want a case for your Raspberry Pi. The stiff cables on all sides make it hard to keep flat, and some of the components like the SD card slot can be mechanically damaged even through normal use.

There are a bunch of premade cases available, but there are also a lot of case designs available to download and fabricate on a laser cutter or 3D printer. In general, avoid tabbed cases where brittle acrylic is used at right angles. The layered acrylic of the Pibow is a colorful option (Figure 1-6).

The Raspberry Pi Foundation also creates an official case, which uses a nice injection-molded design. It has multiple parts that can be removed to allow access to the GPIO pins and other components. (Figure 1-7).

It should probably go without saying, but it’s one of those obvious mistakes you can make sometimes: make sure you don’t put your Raspberry Pi on a conductive surface. Flip over the board and look at the bottom; there are a lot of components there and a lot of solder joints that can be easily shorted. Another reason why it’s important to case your Pi!

Choose Your Distribution

The Raspberry Pi runs Linux for an operating system. Linux is technically just the kernel, but an operating system is much more than that—it’s the total collection of drivers, services, and applications that makes the OS. A variety of flavors or distributions of the Linux OS have evolved over the years. Some of the most common on desktop computers are Ubuntu, Debian, Fedora, and Arch. Each has its own communities of users and is tuned for particular applications.

Because the Pi is based on a mobile device chipset, it has different software requirements than a desktop computer. The Broadcom processor has some proprietary features that require special “binary blob” device drivers and code that won’t be included in any standard Linux distribution. And, while most desktop computers have gigabytes of RAM and hundreds of gigabytes of storage, the Pi is more limited in both regards. Special Linux distributions that target the Pi have been developed.

In this book, we will concentrate on the official Raspbian distribution, which is based on Debian. Note that raspbian.org is a community site, not operated by the Foundation. If you’re looking for the official distribution, visit the Raspberry Pi Foundation’s downloads page. Other specialized distributions are explored in Chapter 3.

Flash the SD Card

Many vendors sell SD cards with the operating system preinstalled; for some people, this may be the best way to get started. Even if it isn’t the latest release, you can easily upgrade once you get the Pi booted up and on the Internet.

The easiest way to get the OS on the microSD card is to use the NOOBS tool. Don’t take offense; no one is questioning your computer acumen. NOOBS stands for New Out Of the Box Software and is a configuration tool that will help install the OS. You’ll need an SD card (at least 8 GB) and reader, then follow these steps: when you boot up the Pi, you’ll see a configuration screen with a number of OS options. Select Raspbian and hit the Install button; that’s all there is to it!

For Advanced Users: Create Your Own Disk Image

The first thing you’ll need to do is download one of the distributions from the Raspberry Pi Foundation’s downloads page or one of the sites in Chapter 3. Note that you can’t just drag the disk image onto the SD card; you’ll need to make a bit-for-bit copy of the image. You’ll need a card writer and a disk image utility; any inexpensive card writer will do. The instructions vary depending on the OS you’re running. Unzip the image file (you should end up with a .img file), then follow the appropriate directions described in Appendix A.

Booting Up

Follow these steps to boot up your Raspberry Pi for the first time:

Push the microSD card into the socket on the bottom of the board. On Raspberry Pi 1 and 2, it’ll click into place. On Raspberry Pi 3, the microSD card won’t click and is held in place with friction.

Plug in a USB keyboard and mouse.

Plug the HDMI output into your TV or monitor. Make sure your monitor is on and set to the correct input.

Last, plug in the power supply. It’s a good habit to make sure everything else is hooked up before connecting the power.

If all goes well, you should see a bunch of startup log entries appearing on your screen. At the top, you’ll see a Raspberry Pi logo, or four if you’re using a quad core model (Raspberry Pi 2 or later). If things don’t go well, skip ahead to “Troubleshooting”. These log messages show all of the processes that are launching as you boot up the Pi. You’ll see the network interface be initialized, and you’ll see all of your USB peripherals being recognized and logged. You can see these log messages after you log in by typing dmesg on the command line.

Configuring Your Pi

The very first time you boot up, you’ll be presented with the Raspbian desktop environment. The first thing you’ll want to do is set a few settings with the Raspberry Pi Configuration tool. To open it, click Menu→Preferences→Raspberry Pi Configuration (see Figure 1-8).

Next, in Figure 1-9, we’ll show you which configuration options are essential and which you might want to come back to if you need them.

System → Expand Filesystem: You should always choose this option; this will enlarge the filesystem to let you use the whole microSD card. On the newest versions of Raspbian, this will be done automatically the first time you boot.
System → Change Password: If you’re on a network with others, it’s a good idea to change the default password from “raspberry” to something a little stronger.
System → Boot: This option lets you boot straight to the graphical desktop environment and is set this way by default. If you select CLI, you’ll get the command line when you boot up, and you’ll have to start the graphical interface manually with the command startx.
System → Overscan: The overscan option is set to enabled at first because some monitors may cut off the edges of the desktop. If you have a black border around your desktop, then you can disable overscan to get the desktop to fill your screen.
Interfaces → SSH: This option turns on the Secure Shell (SSH) server, which will allow you to log in to the Raspberry Pi remotely over a network. This is really handy, so you should leave it on.
Performance → GPU Memory: This option allows you to change the allocation of RAM available to the graphics processing unit. The rest of the RAM is left for the CPU to use. It’s best to leave the default split for now. If you decide to experiment with 3D graphics or video decoding, you may want to adjust this value in the future.
Performance → Overclock: With this option, you can run the processor at speeds higher than the default operation. This option is not available for Raspberry Pi 3. For now, it’s best to leave this setting alone.
Localisation → Set Keyboard: The default keyboard settings are for a generic keyboard in a UK-style layout. If you want the keys to do what they’re labeled to do, you’ll definitely want to select a keyboard type and mapping that corresponds to your setup. Luckily, the keyboard list is very robust. Note that your locale settings can affect your keyboard settings as well.
Localisation → Set Locale: If you’re outside the UK, you should change your locale to reflect your language and character encoding preferences. The default setting is for UK English with a standard UTF-8 character encoding (en_GB.UTF-8). Select en_US.UTF-8 if you’re in the US.
Localisation → Set Timezone: You’ll probably want to set this.

When you’re done, select OK and you’ll be prompted to restart so that the settings can take effect.

If you want to access these settings from the command line, you can use the raspi-config tool (see Figure 1-10). Type the following at the command line if you want to try that out:

sudo raspi-config

Getting Online

You’ve got a few different ways to connect to the Internet. If you’ve got easy access to a router, switch, or Ethernet jack connected to a router, just plug in using a standard Ethernet cable. If you have a WiFi USB dongle or you’re using a Raspberry Pi 3, you can connect wirelessly; there’s an icon on the taskbar to set up your wireless connection (see Figure 1-11).

If you’ve got a laptop nearby, or if you’re running the Pi in a headless configuration, you can share the WiFi on your laptop with the Pi (Figure 1-12). It is super simple on the Mac: just enable Internet Sharing In your Sharing settings, then use an Ethernet cable to connect the Pi and your Mac. In Windows, enable “Allow other network users to connect through this computer’s Internet connection” in your Internet Connection Sharing properties. The Pi should automatically get an IP address when connected and be online.

You will probably need a cross-over cable for a Windows-based PC, but you can use any Ethernet cable on Apple hardware, as it will autodetect the type of cable.

Shutting Down

There’s no power button on the Raspberry Pi (although there is a header for a reset switch on newer boards). The proper way to shut down is through the Shutdown command under the taskbar menu within the desktop environment.

You can also shut down from the command line by typing:

pi@raspberrypi ~ $ sudo halt

Be sure to do a clean shutdown (and don’t just pull the plug). In some cases, you can corrupt the SD card if you turn off power without halting the system.

Running Headless

If you want to work on the Raspberry Pi without plugging in a monitor, keyboard, and mouse, there are some ways to set it up to run headless. If all you require is to get into the command line, you can simply hook the Raspberry Pi up to the network and use an SSH client to connect to it (username: pi, password: raspberry). The SSH utility on Mac or Linux will do; use PuTTY on Windows (or Linux). The SSH server on the Raspberry Pi is enabled by default (run the Raspberry Pi configuration utility again if for some reason it doesn’t launch at startup).

Another way to connect to the Pi over a network connection is to run a Virtual Network Computing (VNC) server on the Pi and connect to it using a VNC client. The benefit of this is that you can run a complete working graphical desktop environment in a window on your laptop or desktop. This is a great solution for a portable development environment. See the Raspberry Pi Hub for extensive instructions on how to install TightVNC, a lightweight VNC server.

A third way of logging in to the Pi without a keyboard or monitor is via some pins on the GPIO header. You can use a special cable from FTDI that allows you to connect to that serial port via USB. The FTDI cable has three wires that connect to ground (pin 6), TX (pin 8), and RX (pin 10) on the header. Alternatively, you could use the BUB I from Modern Device, which is a breakout board for the FTDI chip with a prototyping area that allows you to reroute the signals.

Troubleshooting

If things aren’t working the way you think they should, there are a few common mistakes and missed steps. Be sure to check all of the following suggestions:

Is the microSD card in the slot, and is it making a good connection? Are you using the correct type of microSD card?
Was the disk image written correctly to the card? Try copying it again with another card reader.
Check the integrity of your original disk image. You can do this by running a Secure Hash Algorithm (SHA) checksum utility on the disk image and comparing the result to the 40-character hash published on the download page.
Is the Pi restarting or having intermittent problems? Check your power supply; an underpowered board may seem to work but act flaky.
Do you get a kernel panic on startup? A kernel panic is the equivalent of Windows’ Blue Screen of Death; it’s most often caused by a problem with a device on the USB hub. Try unplugging USB devices and restarting.

If that all fails, head over to the Raspberry Pi Hub’s troubleshooting page for solutions to all sorts of problems people have had.

Going Further

The Raspberry Pi Hub: Hosted by elinux.org, this is a massive wiki of information on the Pi’s hardware and configuration.
List of Verified Peripherals: The definitive list of peripherals known to work with the Raspberry Pi.

Note

Figure 1-4. The Raspberry Pi camera module connects directly to the CSI connector. See Chapter 9 for a full discussion of cameras and the Pi.

Figure 1-5. The Sense HAT add-on board includes an LED matrix, a suite of sensors, and a joystick input. It was designed for the Raspberry Pis that were sent to the International Space Station.

Figure 1-6. The colorful Pibow case from Pimoroni

Figure 1-7. With the official Raspberry Pi case, you can remove the top and sides to access the different parts of the board.

Figure 1-12. A handy trick is to share your laptop’s WiFi connection with the Pi. You can also run the Pi headless (see “Running Headless”), which is convenient if you’re using your Raspberry Pi on the run.

Chapter 1. Getting Up and Running

A Tour of the Boards

Note

Figure 1-1. There are many versions of the Pi, and here are a few (clockwise from top left): Raspberry Pi 3 Model B, Raspberry Pi 1 Model A+, Raspberry Pi Compute Module, and Raspberry Pi Zero. As of February 2016, Raspberry Pi 3 Model B is the latest mainline Raspberry Pi.

Figure 1-2. A map of the hardware interface of the Raspberry Pi

Figure 1-3. The pins and headers on the Raspberry Pi

The Proper Peripherals

Note

The Case

Choose Your Distribution

Flash the SD Card

For Advanced Users: Create Your Own Disk Image

Booting Up

Configuring Your Pi

Figure 1-8. How to launch the Raspberry Pi Configuration tool

Figure 1-9. The Raspberry Pi Configuration tool allows you to change many of the important settings on your Raspberry Pi.

Figure 1-10. The raspi-config tool when run from the command line

Getting Online

Figure 1-11. Click on the network icon on the right side of the taskbar to select a WiFi network to connect to.

Shutting Down

Running Headless

Troubleshooting

Going Further