Appendix B

Raspberry Pi Camera Module Quick Reference

THE RASPBERRY PI Camera Module comes with software designed to capture still images and videos, each of which has a variety of options that can control the final output. Options for raspistill, raspiyuv and raspivid are included in this appendix. For more information, see Chapter 16, “The Raspberry Pi Camera Module”.

Shared Options

The following options, listed in alphabetical order, are shared between raspistill, raspiyuv and raspivid. For application-specific options, see the individual raspistill, raspiyuv and raspivid entries later in this appendix.

• -? or --help (Help)—Displays all options and their uses.
• -awb or --awb (Automatic White Balance)—Sets the colour temperature of the captured image or video according to one of a series of preset configurations. If your image or video appears blue or orange, try adjusting this option first. Possible values for this option are off, auto, sun, cloud, shade, tungsten, fluorescent, incandescent, flash, horizon.
• -br or --brightness (Brightness)—Adjusts the brightness of the captured image or video. Possible values for this option are whole numbers ranging from 0 (minimum brightness) to 100 (maximum brightness).
• -cfx or --colfx (Colour Effects)—Allows the user to adjust the YUV colour space for fine-grained control of the final image. Values should be given as U:V, where U controls the chrominance and V the luminance. A value of 128:128 will result in a greyscale image.
• -co or --contrast (Contrast)—Adjusts the contrast of the captured image or video. Possible values for this option are whole numbers ranging from −100 (minimum contrast) to 100 (maximum contrast).
• -d or --demo (Demonstration Mode)—The -d option runs either raspistill or raspivid in demonstration mode, which displays a preview that cycles through various camera options. In this mode, no image is captured—even if you specify an output file using the --output option.
• -ev or --ev (Exposure Value)—Allows the camera to increase or decrease its exposure value, brightening or darkening the captured image or video. Unlike the brightness and contrast settings, this affects the actual capturing of the image or video. Possible values are −10 to 10, with 0 being the default.
• -ex or --exposure (Exposure Mode)—Sets the camera’s automatic exposure setting, which controls how long the camera spends capturing an individual image or frame and is largely a factor of available light or the speed of the subject: fast-moving objects need a short exposure time in order to remain in focus, while low-light shooting demands a long exposure time. Possible values for this option are: auto, night, nightpreview, backlight, spotlight, sports, snow, beach, verylong, fixedfps, antishake, fireworks.
• -f or --fullscreen (Fullscreen Preview)—Makes the preview image fill the screen, overriding any other preview option you may have set.
• -h or --height (Height)—Specifies the height, or vertical resolution, of the captured image or video. This should be set to the desired height in pixels; for example, a Full HD capture would require a height value of 1080. The minimum value is 64; the maximum depends on whether video or still images are being captured.
• -hf or --hflip (Horizontal Flip)—Flips the captured image or video along its horizontal axis, as though it has been viewed in a mirror.
• -ifx or --imxfx (Image Effects)—Enables one of a number of preconfigured special effects on the image or video. Possible values for this option are none, negative, solarise, sketch, denoise, emboss, oilpaint, hatch, gpen, pastel, watercolour, film, blur, saturation, colourswap, washedout, posterise, colourpoint, colourbalance, cartoon. These settings can be seen in action using the Demonstration Mode option.
• -ISO or --ISO (ISO Sensitivity)—Sets the camera’s sensitivity to light. A lower ISO value provides a clearer image, but requires longer exposures; a higher ISO value can shoot at very low exposure times to capture fast-moving or badly lit subjects, but creates a “noisier” image.
• -mm or --metering (Metering Mode)—Sets the light metering mode for image or video capture, which controls the automatic exposure, white balance and ISO sensitivity options. Possible values for this option are average, spot, backlit, matrix.
• -n or --nopreview (No Preview)—Does not display a preview window while capturing.
• -o or --output (Output File)—Sets the name of the file to be saved. The value for this option can be either a filename, in which case the file will be created in the current directory, or an absolute path. If you are using raspistill or raspivid along with another application that expects image or video data through standard input, you can divert the data through standard output using a hyphen (-) character as the filename.
• -op or --opacity (Preview Opacity)—Controls how transparent the preview window appears. Possible values are any whole number from 0 to 255, where 0 is completely transparent and thus invisible and 255 is completely visible. Using a value around 128 allows you to see the live preview, but also read the text behind the preview.
• -p or --preview (Preview Window Control)—Sets the size of the preview window and where it appears. The value should be given as X,Y,W,H where X and Y are the pixel coordinates where the window’s top-left corner should be drawn, and W and H the width and height of the preview window in pixels.
• -rot or --rotation (Rotate Capture)—Rotates the captured image or video through any arbitrary angle. Values for this option should be given as a whole number of clockwise degrees, where 0 is no rotation and 359 the maximum possible rotation. Values given will be rounded down to the nearest 90 degrees, giving actual rotations of 0, 90, 180 and 270 degrees.
• -sa or --saturation (Saturation)—Adjusts the colour saturation of the captured image or video. Possible values for this option are whole numbers ranging from −100 (minimum saturation) to 100 (maximum saturation).
• -sh or --sharpness (Sharpness)—Adjusts the sharpness of the captured image or video. Possible values for this option are whole numbers ranging from −100 (minimum sharpness) to 100 (maximum sharpness).
• -t or --timeout (Capture Timeout)—Controls the timeout, in milliseconds, that the preview window will appear. While shared between the tools, the action of the --timeout option is different: in raspistill, the --timeout option will set the time until the picture is captured; in raspivid, the option will set the time for which video will be recorded. A value of 0 in raspistill will display the preview indefinitely and never capture an image; a value of 0 in raspivid continues to record indefinitely. If not specified, the timeout defaults to 5 seconds (i.e., 5000 milliseconds).
• -v or --verbose (Verbose Messaging)—Verbose mode tells the capture application to output as much detail as possible about what it is doing to the console or terminal. This is generally used only for debugging errors in the software, as it allows the user to see at what point the capture fails.
• -vf or --vflip (Vertical Flip)—Flips the image through the vertical axis. Most commonly used when the camera cannot be positioned the correct way up, with the connecting ribbon cable exiting from the bottom. If the camera is at an angle other than upside down, try using the rotation option to control the final captured image.
• -vs or --vstab (Video Stabilisation)—Attempts to correct for the camera’s sensor shaking. Commonly used when the Raspberry Pi or its Camera Module is held in the hand or attached to a robot, vehicle or other moving platform.
• -w or --width (Width)—Specifies the width, or horizontal resolution, of the captured image or video. This should be set to the desired width in pixels; for example, a Full HD capture would require a width value of 1920. The minimum value is 64; the maximum depends on whether a still image or a video is being captured.

Raspistill Options

Designed to capture still images, raspistill has some specific options that do not apply to raspivid. Those options are listed here:

• -e or --encoding (Encoding Format)—Sets the format of the output image. This does not affect the file extension of the output file, which must be changed manually using the --output option. Possible values for this option are jpg, bmp, gif, png.
• -q or --quality (JPEG Quality)—Sets the compression level of the saved JPEG, and has no effect when using any other encoding format. The lower the value, the smaller the final image file; a value of 100 will provide the best possible quality, while a value of 0 will provide the smallest file size. A value of 90 is a good trade-off between size and quality.
• -r or --raw (Save Bayer Data)—Saves the output of the camera’s Bayer colour filter as metadata in the JPEG image and has no effect when using any other encoding format. This extra data, the output of the camera’s sensor without interpolation, can be used in image editing applications to reconstruct a higher quality or more detailed image, but is not normally required.
• -th or -–thumb (Thumbnail Settings)—Sets the size and quality of the thumbnail saved with JPEG images and has no effect when used with any other encoding format. The value should be given as X:Y:Q, where X is the width, Y the height and Q the JPEG quality from 0 to 100 of the thumbnail, or give the value none to turn off thumbnails.
• -tl or --timelapse (Timelapse Mode)—Puts raspistill into timelapse mode, where images will be captured at a set interval. Most useful when using raspistill with a script or third-party application by setting the Output file to the standard output with a hyphen (-) character; when used with a filename in the --output option, the file will be overwritten every time a new image is captured. The value for this option should be the delay between captures in milliseconds.
• -x or --exif (EXIF Tag)—Allows custom Exchangable Image File Format (EXIF) tags to be written to a JPEG image and has no effect when used with any other encoding formats. Tags should be formatted as ‘key=value’ with one possible example being setting the name of the photographer using -x 'Author=Gareth Halfacree'. Or give the setting –x none to turn off EXIF tags.

Raspivid Options

Designed to capture moving images, raspivid has some specific options that do not apply to raspistill. Those options are listed here:

• -b or --bitrate (Encoding Bitrate)—Sets the bitrate of the captured video, in bits per second (BPS). The higher the bitrate, the higher the quality of the finished video—but the larger the file size. Unless you have a specific requirement from your video, this should typically be left at the default setting.
• -e or --penc (Encoding Preview)—Uses the preview window to show video frames after they have been passed through the encoder, rather than before. Provides an accurate preview of the final video and is most commonly used when tweaking the Encoding Bitrate.
• -fps or –-framerate (Video Framerate)—Sets the framerate of the captured video, in frames per second. Higher figures give smoother motion, while lower figures take up less disk space. Recording at a rate above 30 frames per second, which can be turned into slow-motion video with a video editing application, will likely work only at lower resolutions (set with the --width and --height options).
• -g or --intra (Intra Refresh Period)—Sets how often a key frame, also known as an intra-coded picture or I frame, should be captured. A key frame is an entire image, rather than the changes recorded since the last image. More frequent key frames can result in higher quality video when recording rapidly changing scenes, but will result in larger file sizes.

Raspiyuv Options

Raspiyuv is an application designed to capture one of two specific formats of colour image—YUV or RGB. Most users will be better off using raspistill, which outputs into image formats ready for use; those who plan to edit their images further after capture, however, may find raspiyuv a useful tool.

Most raspiyuv options are the same as those found on raspistill, with the following exception:

• -rgb or --rgb (Capture RGB)—Sets raspiyuv to capture red, green, blue (RGB) pixel data rather than the chrominance and luminance normally used.

Appendix C

HDMI Display Modes

YOU CAN USE the values in Table C-1 and Table C-2 with the hdmi_mode option in config.txt to alter the HDMI video output format. For more information, see Chapter 7, “Advanced Raspberry Pi Configuration”.

Table C-1 HDMI Group 1 (CEA)

Table C-2 HDMI Group 2 (DMT)

Chapter 1

Meet the Raspberry Pi

YOUR RASPBERRY PI board is a miniature marvel, packing considerable computing power into a footprint no larger than a credit card. It’s capable of some amazing feats, but you need to know a few things before you plunge head-first into the bramble patch.

A Trip Around the Board

The Raspberry Pi is currently available as two different models, known as the Model A and the Model B. While there are differences, with the Model A sacrificing some functionality in order to reduce its cost and power requirements, both share plenty of similarities that you find out about in this chapter. Figure 1-1 shows a Raspberry Pi Model B Revision 2, the most common board type. Its layout is shared between the original Model B Revision 1 and the cheaper Model A; the latest Model B+ uses an altered layout discussed later in this chapter.

In the rough centre of all Raspberry Pi boards is a square semiconductor, more commonly known as an integrated circuit or chip. This is the Broadcom BCM2835 system-on-chip (SoC) module, which provides the Pi with its general-purpose processing, graphics rendering and input/output capabilities. Stacked on top of that chip is another semiconductor, which provides the Pi with memory for temporary storage of data while it’s running programs. This type of memory is known as random access memory (RAM), because the computer can read from or write to any part of the memory at any time. RAM is volatile, meaning that anything stored in the memory is lost when the Pi loses power or is switched off.

Above and below the SoC are the Pi’s video outputs. The silver (bottom) connector is a High Definition Multimedia Interface (HDMI) port, the same type of connector found on media players and many satellite and cable set-top boxes. When connected to a modern TV or monitor, the HDMI port provides high-resolution video and digital audio. The yellow (top) connector is a composite video port, which is designed for connection to older TVs that don’t have an HDMI socket. The video quality is lower than is available via HDMI, and there’s no audio; instead, audio is provided as an analogue signal on the 3.5mm audio jack to the right of the composite video socket.

The pins to the top-left of the Pi compose the general-purpose input-output (GPIO) header, which can be used to connect the Pi to other hardware. The most common use for this port is to connect an add-on board. A selection of these boards is described in Chapter 17, “Add-On Boards”. The GPIO port is extremely powerful, but it’s fragile. When handling the Pi, always avoid touching these pins and never connect anything to them while the Pi is switched on.

The plastic and metal connector below the GPIO port is the Display Serial Interface (DSI) port, which is used to connect digitally driven flat-panel display systems. These are rarely used except by professional embedded developers because the HDMI port is more flexible. A second plastic and metal connector, found to the right of the HDMI port, is the Camera Serial Interface (CSI) port, which provides a high-speed connection to the Raspberry Pi Camera Module or other Pi-compatible CSI-connected camera system. For more details on the CSI port, see Chapter 16, “The Raspberry Pi Camera Module”.

At the very bottom-left of the board is the Pi’s power socket. This is a micro-USB socket, the same type found on most modern smartphones and tablets. Connecting a micro-USB cable to a suitable power adapter, detailed in Chapter 2, “Getting Started with the Raspberry Pi”, switches the Raspberry Pi on. Unlike a desktop or laptop computer, the Pi doesn’t have a power switch and will start immediately when power is connected.

On the underside of the Raspberry Pi board on the left-hand side is an SD card slot. A Secure Digital (SD) memory card provides storage for the operating system, programs, data and other files, and is non-volatile. Unlike the volatile RAM, it will retain its information even when power is lost. In Chapter 2, you’ll learn how to prepare an SD card for use with the Pi, including installing an operating system in a process known as flashing.

The right-hand edge of the Pi will have different connectors depending on which model of Raspberry Pi you have, the Model A or the Model B. Above these is a series of Light Emitting Diodes (LEDs), the left-most two of which—marked ACT and PWR and providing SD card activity notification and power notification, respectively—are present on all boards.

Model A

The least expensive Raspberry Pi, the Model A shown in Figure 1-2, is designed to be affordable yet flexible. As well as costing less than the Model B, the Model A draws less power and is a good choice for projects that use solar, wind or battery power. Although the Model A’s BCM2835 SoC is just as powerful as the one found on the Model B, it comes with half the memory, at 256MB. This is an important consideration when deciding which model to buy, because it can make more complex applications run slowly—in particular, those applications that turn the Pi into a server, as described in Chapter 10, “The Pi as a Web Server”.

The Model A has only a single port on its right-hand edge, a Universal Serial Bus (USB) port. This is the same type of port found on desktop and laptop computers, and allows the Pi to be connected to almost any USB-compatible peripheral. Most commonly, the USB port is used to connect a keyboard for interacting with the Pi. If you also want to use a mouse at the same time, you’ll need to buy a USB hub to add more ports to the Model A, or alternatively, a keyboard with built-in mouse functionality.

Model B

The Raspberry Pi Model B shown in Figure 1-3 is more expensive than the Model A, but it comes with considerable advantages. Internally, it includes twice the memory, at 512MB, while externally there are additional ports not available on the lower-cost model. For many users, the Model B is a worthwhile investment. Only those with particular requirements of low weight, space or power draw should consider the Model A for general-purpose use.

The Model B has either two or four USB ports on the right-hand edge of the board, primarily to provide connectivity for a keyboard and mouse along with other USB peripherals. Additionally, the Model B includes an Ethernet port for connecting the Pi to a wired network, which allows the Pi to access the Internet and allows other devices on the network to access the Pi—providing, that is, that they know the username and password or that the Pi has been set up as a server, as described in Chapter 10.

Model B+

The Raspberry Pi Model B+, shown in Figure 1-4, is the latest version of the board developed by the Raspberry Pi Foundation. It was created to address issues with the existing Model B Revision 2 design and has a dramatically different layout than any of the previously released Raspberry Pi models.

The Raspberry Pi Model B+ includes the same BCM2835 processor and 512MB memory as its predecessor, the Model B Revision 2, but on a newly designed circuit board with four—rather than two—mounting holes. The biggest changes are the elongated GPIO connector, with 40 pins to the other models’ 26 pins; four USB ports instead of two; a shifted power connector and 3.5mm jack; and the removal of the composite video connector on the top of the board. The Model B+ also uses a micro-SD card, in place of the full-size SD card of other models, and the power and activity lights have been moved to the top-left.

The Model B+ is a good choice if you are interested in getting the most out of the Pi. Its extended GPIO header, described in Chapter 15, “The GPIO Port”, offers additional pins for more complex electronics projects; its extra USB ports mean a keyboard and mouse can be connected while still leaving two ports free for other devices; and its power circuitry has been revised to dramatically reduce power draw and improve reliability when used with cheaper power supplies.

A History of Model B PCB Revisions

Although the latest model of Raspberry Pi Model B+ currently has 512MB of memory and four USB ports, this wasn’t always the case. As well as the Model B+, there are two variants of standard Model B; if you bought a second-hand Rasbperry Pi Model B or purchased one some time ago, you may have the earliest Revision 1 model.

Revision 1

The original Raspberry Pi Model B, the Revision 1 board, has only 256MB of RAM. It also has a slightly different GPIO header. That is, while the number and locations of the pins look identical to those of later revisions, it assigns certain features to different pins. (See Chapter 15 for more on this topic.) This is the most important difference. All other Raspberry Pi revisions and models share the same GPIO layout, so if you have an original Model B Revision 1, you may need to adjust instructions and programs before you can use them successfully.

Revision 2

Introduced shortly before the launch of the Model A, the Raspberry Pi Revision 2 includes double the memory of the original at 512MB. It also introduces the new, standardised GPIO header shared with the Model A. An extra header, which is also present on Model A boards, marked P5 or P6 and located just below the GPIO header, is a sure sign that a Model B is a newer model.

Model B+

Previously known as the Revision 3, the Model B+ is a dramatic redesign and is immediately recognisable, thanks to its longer 40-pin GPIO header and four USB ports. It features the same processor and memory as the Revision 2 but moves some ports to different locations on the board. It also does away with the yellow composite video connector; if still required, this signal can be found on the 3.5mm jack—along with the usual stereo audio signal—using a special adapter cable.

A Bit of Background

Before heading into Chapter 2, it’s a good idea to familiarise yourself with some background details of the Pi and its creation. While the Pi is usable as a general-purpose computer, capable of performing the same tasks as any desktop, laptop or server—albeit more slowly—it is designed as a single-board computer aimed at hobbyists and educational use, and as such differs from a “normal” computer in a couple of important ways.

ARM versus x86

The processor at the heart of the Raspberry Pi system is the Broadcom BCM2835 SoC multimedia processor. This means that the vast majority of the system’s components, including its central and graphics processing units along with the audio and communications hardware, are built onto that single component hidden beneath the memory chip at the centre of the board.

It’s not just this SoC design that makes the BCM2835 different from the processor found in your desktop or laptop, however. It also uses a different instruction set architecture (ISA), known as ARM.

Developed by Acorn Computers back in the late 1980s, the ARM architecture is a relatively uncommon sight in the desktop world. Where it excels, however, is in mobile devices. The phone in your pocket almost certainly has at least one ARM-based processing core hidden inside. Its combination of a simple reduced instruction set computing (RISC) architecture and low power draw make it the perfect choice over desktop chips with high power demands and complex instruction set computing (CISC) architectures.

The ARM-based BCM2835 is the secret to the Raspberry Pi’s capacity to operate on just the 5V 1A power supply provided via the onboard micro-USB port. It’s also the reason why you won’t find any metal heat sinks on the device—the chip’s low power draw directly translates into very little wasted heat, even during complicated processing tasks.

It does mean, however, that the Raspberry Pi isn’t compatible with traditional PC software. The majority of software for desktops and laptops are built with the x86 instruction set architecture in mind, as found in processors from the likes of AMD, Intel and VIA. As a result, it won’t run on the ARM-based Raspberry Pi.

The BCM2835 uses a generation of ARM’s processor design known as ARM11, which in turn is designed around a version of the instruction set architecture known as ARMv6. This is worth remembering: ARMv6 is a lightweight and powerful architecture but has a rival in the more advanced ARMv7 architecture used by the ARM Cortex family of processors. Software developed for ARMv7, like software developed for x86, is sadly not compatible with the Raspberry Pi’s BCM2835—although developers can usually convert the software to make it suitable, a process known as porting.

That’s not to say you’re going to be restricted in your choices. As you’ll discover later in the book, plenty of software is available for the ARMv6 instruction set, and as the Raspberry Pi’s popularity continues to grow, availability will only increase. In this book, you’ll also learn how to create your own software for the Pi, even if you don’t have experience with programming.

Windows versus Linux

Another important difference between the Raspberry Pi and your desktop or laptop, other than the size and price, is the operating system—the software that allows you to control the computer.

The majority of desktop and laptop computers available today run one of two operating systems: Microsoft Windows or Apple OS X. Both platforms are closed source, created in a secretive environment using proprietary techniques.

These operating systems are known as closed source because of the nature of their source code, the computer-language recipe that tells the system what to do. In closed-source software, this recipe is a closely guarded secret. Users are able to obtain the finished software but never to see how it’s made.

The Raspberry Pi, by contrast, is designed to run an operating system called GNU/Linux—hereafter referred to simply as Linux. Unlike Windows or OS X, Linux is open source, so you can download the source code for the entire operating system and make whatever changes you desire. Nothing is hidden, and all changes are made in full view of the public. This open source development ethos has allowed Linux to be altered quickly to run on the Raspberry Pi. At the time of this writing, several versions of Linux—known as distributions—have been ported to the Raspberry Pi’s BCM2835 chip, including Raspbian, Pidora and Arch Linux.

The different distributions cater to different needs, but they all have something in common: they’re all open source. They’re also all, by and large, compatible with each other—software written on a Debian system will usually operate perfectly well on Arch Linux, and vice versa.

Linux isn’t exclusive to the Raspberry Pi. Hundreds of different distributions are available for desktops, laptops and even mobile devices. Even Google’s popular Android platform is developed on top of a Linux core. If you find that you enjoy using Linux on the Raspberry Pi, you may want to consider adding it to other computing devices you use as well. It will happily coexist with your current operating system, allowing you to enjoy the benefits of both while giving you a familiar environment when your Pi is unavailable.

As with the difference between ARM and x86, there’s a key point to make about the practical difference between Windows and OS X and Linux: software written specifically for Windows or OS X won’t run on Linux. Thankfully, there are plenty of compatible alternatives for the overwhelming majority of common software products. Better still, the majority are free to use and as open source as the operating system itself, and can even be installed on both Windows and OS X to provide a familiar experience across all three platforms.