- System Configuration
- Bill of Materials
- Set of Instructions
- More Details
- Using the Camera
- Trouble Shooting
- Appendix A - The Software
- Appendix B - Python Pi-Camera API
- About this Document
This Project is about the use of the Pi-Camera with the Raspberry Pi (R-Pi) and enabling a user to quickly, within a couple of hours of effort, and easily obtain, and store, still images and video. This project is aimed at people who have limited experience of using the R-Pi and programming. The key learning objectives of this project are for a novice developer to:
- Learn how the R-Pi and Pi-Camera can be connected and configured using the standard Raspbian drivers and applications;
- Learn how to access and control the Pi-Camera from a Python program. A user will be able to take still images and video clips and to store them on the SD Card of the R-Pi.
The associated Bill of Materials describes the set of components, hardware and software, required to complete this project.
The system configuration is shown in Figure 1.1. The basic configuration is:
- R-Pi (Model A/B) - this project can make use of either Model. In the case of Model A, it is recommended that a WiPi is used to provide network connectivity (wireless, IEEE 802.11, via the USB2 port on the R-Pi). Network connectivity makes it easier to download and install the necessary software updates required by the Pi-Camera. A USB2 hub is recommended to enable more than two USB devices to be linked to the R-Pi (the R-Pi has two USB ports). It is assumed that the keyboard and mouse are linked via the USB Hub and, if required, the WiPi. The monitor can be linked either via the HDMI interface or the yellow RCA phono connector for composite video output. In this project a PiView connector is used to enable a monitor with a VGA connector to be connected to the R-Pi via the HDMI interface;
- Pi-Camera - the PiCamera is attached to the R-Pi via the CSI bus (see later for instructions on how to make the connection). The camera sensor has a native resolution of 5 megapixel, and has a fixed focus lens onboard. In terms of still images, the camera is capable of 2592 x 1944 pixel static images, and also supports 1080p30, 720p60 and 640x480p60/90 video.
|Figure 1.1 System Configuration.|
When the complete system is built it will look as shown in Figure 1.2.
|Figure 1.2 The completed system.|
The architecture is based upon the use of an R-Pi to drive a Pi-Camera. The configuration is shown in Figure 2.1 and the key to the alphanumeric labels is provided in Tables 2.1 and 2.2.
|Figure 2.1 - System configuration for the 'Bill of Materials'|
The associated bill of materials for the system shown in Figure 2.1 is listed in Table 2.1.
Table 2.1 - the Bill of Materials.
|1 (a)||R-Pi Model A|
Either Model can be used (includes 4GB SD Card). Use a Multicomp enclosure to protect the R-Pi base.
|1 (b)||R-Pi Model B|
Include a Cat 5 Ethernet cable. Use a Multicomp enclosure to protect the R-Pi base.
|1 (c)||R-Pi Enclosure||Multicomp enclosure to protect the R-Pi base.||1|
|1 (d)||SD Card||Storage medium (8GB) for the R-Pi (with NOOBS pre-installed).||1|
|2||Pi-Camera||This includes the 15-way flat-flex cable for connection to the R-Pi via the CSI bus.||1|
|3||Keyboard||Include a USB cable. Get as part of an Accessory Bundle (see 4 below).||1|
|4||Mouse||Include a USB cable. Get as part of an Accessory Bundle (see 3 above).||1|
|5||WiPi||Wireless access via USB. Required to provide network access if a R-Pi Model A is used.||1|
|6||PiView||HDMI/VGA adapter to provide connection to a non-HDMI enabled monitor.||1|
|7||Monitor||A suitable colour monitor (VGA or HDMI connectivity recommended).||1||N/A|
|8||USB2 Hub||Includes the power supply and USB2 cables.||1|
|9||Power Supply||R-Pi power supply with 5V/1A output. Micro USB connector.||1|
|10||Power Supply||USB2 power supply (5V/1A with 2.1mm x 5.5mm Barrel Plug connector). |
Included with the USB2 Hub (see 8 above).
(Cat5/6 - twisted pair)
|To provide network access when using a R-Pi Model B. Should be connected to the appropriate network access box e.g. broadband router. Get as part of an Accessory Bundle (see 3 above).||1||See 3/4 above.|
The hardware connectivity is detailed in Table 2.2.
Table 2.2 - Hardware connectivity.
|A||VGA (PiView)||Monitor/R-Pi||Part of the Monitor cable to the R-Pi.|
|B||HDMI (PiView)||R-Pi/Monitor||Part of the Monitor cable to the R-Pi.|
|C||Power Cable||R-Pi Micro USB/Mains||Power supply for the R-Pi.|
|D||Ethernet (Cat5/6)||R-Pi/Switch or Router||Cable-based network access. Wireless access via the WiPi is an alternative.|
|E||15-way Flat-Flex Cable||R-Pi/PiCamera||Camera Serial Interface (CSI) bus between the R-Pi and PiCamera. Supplied as part of the PiCamera.|
|F||Power Cable||USB2 Hub/Mouse + Keyboard|
|Power for the USB2 hub - the hub supports seven ports.|
USB2 Hub/Mouse + Keyboard
USB cable connection for the Mouse and Keyboard.
The WiPi will be plugged directly into the USB2 hub.
|H||USB Cable||USB2 Hub/R-Pi||USB cable to connect the USB hub to the R-Pi. The R-Pi can also draw power using this cable.|
The software required to support this project that must be installed on the R-Pi is:
- R-Pi Operating System (Raspbian) - this is installed using the NOOBS that comes pre-installed on the R-Pi SD cards. If NOOBS is not preinstalled it is available at Downloads;
- Integrated Development Environment - IDLE with Python 3.x support with the 'tkinter' modules installed (normally installed as part of Raspbian);
- Raspistill and Raspivid applications - these are still image and video capture operating system applications (normally installed as part of Raspbian);
- Omxplayer - an application to enable the H.264 encoded video to be played back on the monitor from the R-Pi (normally installed as part of Raspbian);
- Pure Python interface to the R-Pi PiCamera (Python 2.7 and above and Python 3.2 and above) by Dave Hughes - the documentation is available at: http://picamera.readthedocs.org/en/release-0.8/index.html.
NOTE: This project has been tested using v0.7 and v0.8 of the Python Pi-Camera interface. There MAY be problems with other versions. Please inform us if you have problems with other versions of the Python Pi-Camera API.
The set of instructions for using the Pi-Camera are:
- Configure the R-Pi system in preparation for the connection of the Pi-Camera and usage of the software i.e. the monitor, USB2 Hub, keyboard and mouse and the network connection (using either a WiPi for wireless access or using the wired Ethernet port) - see More Detail;
- The Pi-Camera must now be connected to the R-Pi. The Pi-Camera is connected to the R-Pi using the CSI bus located between the Ethernet and HDMI connectors. The 15-way flat-flex connector cable, supplied with the Pi-Camera, is inserted into the CSI connector with the metallic connectors facing the HDMI connector. The system software must now be installed - see More Detail;
- The connection and configuration of the Pi-Camera is tested using the 'raspistill and 'raspivid' applications. These two applications are supplied as part of the Raspbian operating system. The 'raspistill' image is used to capture one or more still images (the default format is JPEG but other formats can be used) and the 'raspivid' application is used to capture and store a video (it is saved in H.264 format) - see More Detail;
- The Pure Python Pi-Camera API must now be installed. This API is used to enable the Pi-Camera to be controlled using a Python program i.e. a developer can write a program that can control the Pi-Camera to take still images and video clips - see More Detail;
- Download and run the Python Pi-Camera software. Download the LED chooser software file 'CamInterfacev1p*.py', written in Python 3, to control the Pi-Camera. This software provides a GUI that allows a user to take a single still image, a sequence of still images and a video clip - see More Detail.
The layout of the R-Pi (Model B) is shown in Figure 4.1. Once the various cables have been connected to the R-Pi, the configuration is as shown in Figure 4.2 (the alphanumeric annotations refer to the identifier entries in Tables 2.1 and 2.2).
|Figure 4.1 - R-Pi Model B board layout.||Figure 4.2 - The R-Pi with the set of connected cables.|
The front and rear views of the Pi-Camera are shown in Figure 4.3. The Pi-Camera should be handled carefully as it is susceptible to electrostatic damage. Before handling the Pi-Camera discharge yourself by touching an earthed object e.g. a radiator. When handling the camera unit itself grip the PCB surround and not the electronics or the camera lens.
|Figure 4.3 - The Pi-Camera.|
(a) Front View
(b) Rear View
|Figure 4.4a Close-up of the CSI cable connection for the Pi-Camera||Figure 4.4b Pi-Camera connected to the R-Pi.|
As shown in Figure 4.4a, the Pi-Camera cable is placed into the CSI Bus Connector (E). The top plate of the connector must be raised to allow the cable to be inserted. The cable is inserted with the metallic connections pointing to the left i.e. towards the HDMI connector. Make sure the cable is pushed well down. Now push the connector plate down (note in Figure 4.4a the plate has not been pushed fully down yet). When connected the system now looks as shown in Figure 4.4b.
The next step is to update the Raspian operating system and to make sure that the Pi-Camera is configured correctly. An excellent set of detailed instructions on the software configuration is available at: Camera | Raspberry Pi. The steps to be taken to configure the Pi-Camera software require the use of the LX Terminal application on the R-Pi. Start the LX Terminal and then type:-
sudo apt-get update
sudo apt-get upgrade
These update the R-Pi firmware and ensure the latest versions of the Raspbian operating system is installed. The next step is to make sure that the Pi-Camera is enabled. Type:-
Use the cursor key to move to the camera option and select enable. On exiting raspi-config it will ask to reboot. The enable option will ensure that on reboot the correct GPU firmware will be running for the use of the Pi-Camera. Use the instructions at: Camera | Raspberry Pi for more details on how enable the Camera. Make sure you reboot the R-Pi once the P-Camera has been enabled.
The correct installation of the PiCamera can be checked by using the 'raspistill' and raspivid' applications that are supplied as part of the Raspbian O/S. An extensive set of documentation about these two applications is available at: https://github.com/raspberrypi/userland/blob/master/host_applications/linux/apps/raspicam/RaspiCamDocs.odt. Still images can be taken by launching the LX Terminal and typing:
raspistill -o image.jpg
A JPEG image will now be taken and stored in the file 'image.jpg' in the directory from which the terminal emulator was run. The image is captured after a 5s preview period and the image about to be taken is displayed on the desk-top. The 5s period can be altered by using the '-timeout' instruction on the command line. The image can be viewed by clicking on the file under the Raspbian file manager. A video (in format H.264) can be captured by typing:
raspivid -o video.h264
This will capture a 5s duration video (again the duration can be changed using the '-timeout' instruction). The video can be viewed by using the 'omxplayer' application (see bullet 3 in Section 5).
Now that it has been confirmed that the Pi-Camera is correctly installed and configured, the next step is to install the Python Pi-Camera API. Download the documentation at: http://picamera.readthedocs.org/en/release-0.8/index.html. It is recommended that the Python API is installed so that it is available to ALL users i.e. a System Installation. The 'CamInterfacev1p0p0.py' software that has been written for this project uses Python 3 so the Python 3 version of the Pi-Camera API is required. The relevant set of instructions are given in Section 1.2.2 (page 5) of the API documentation. Thefollowing instruction are entered into the LX Terminal:-
sudo apt-get install python3-setuptools
sudo easy_install3 picamera
Upgrades should be installed using the instruction:
sudo easy_install3 -U picamera
The next and final stage is to download the user GUI i.e. the 'CamInterfacev1p0p0.py' software (see Section 5).
The user camera software is started by running the Python 3 file 'CamInterfacev1p0p0.py' (it should be possible to start the file by just clicking on it otherwise open the file using the IDLE 3 application). When the software starts the window shown in Figure 5.1 is displayed. The user can now:
- Take a Single Photo - click on the left most radio button labelled 'Take a Single Photo'. Now enter the name of the file, in which the image is to be stored, in the text box labelled 'Photo Filename'. Now press the button 'Camera, Lights, ACTION'. The image that the Pi-Camera will take is now shown in a window in the bottom left of the screen. The image is taken after a one second delay and stored in the named file (this user software always creates a JPEG version - this can be changed by altering line 307 in the CamInterface file i.e. in the method 'action_single'). The image is stored in the same directory as that in which the CamInterfacev1p0p0.py file is stored. If this file is now clicked then it will be displayed on the desk-top. All of the user actions are reported in the message window (below the 'Camera, Lights, ACTION' and 'QUIT' buttons) and if an attempt is made to take the image without providing the file name then an error message is displayed;
- Take a Sequence of Multiple Photos - click on the right most radio button labelled 'Take multiple Photos'. Now enter the name of the directory, in which the set of images is to be stored, in the text box labelled 'Directory name'. Next enter the number of images to be taken and the delay between each image in the text boxes 'Number of images' and 'Seconds between images' respectively. Now press the button 'Camera, Lights, ACTION'. Each image that the Pi-Camera will take is now shown in a window in the bottom left of the screen. The set of images are now taken sequentially and stored in the named directory (this directory is in the same directory as that in which the CamInterfacev1p0p0.py file is stored). These images can now be viewed by clicking on them. Again, all of the user actions are reported in the message window (below the 'Camera, Lights, ACTION' and 'QUIT' buttons) and if an attempt is made to take the images without providing the full set of information then an error message is displayed;
- Shoot a Video - enter the name of the file, in which the video is to be stored, in the text box labelled 'Video Filename'. Now press the button 'Start Video'. The video that the Pi-Camera will take is now shown in a window in the bottom left of the screen. To stop the video capture press the 'Stop Video' button. The video is stored in the same directory as that in which the CamInterfacev1p0p0.py file is stored. The video is stored as a H.264 format and this cannot be easily viewed on a Raspbian desktop. Viewing this video requires the use of an application such as 'omxplayer'. The instructions to view the new video are to use the LX Terminal set for the directory containing the video and to type (shown in bold):
omxplayer <filename>.h264 - used if the display is connected to the composite output (the yellow connector)
omxplayer -o hdmi <filename>.h264 - used if the display is connected to the HDMI output
The video will now be played on the display. Again, all of the user actions are reported in the message window (below the 'Camera, Lights, ACTION' and 'QUIT' buttons) and if an attempt is made to take the video without providing the file name then an error message is displayed.
When the 'QUIT' button is pressed, the Pi-Camera is stopped and the program must be restarted before further images and/or videos can be captured.
|Figure 5.1 - The startup display for the software.|
A video, 7 minutes long, demonstrating the use of the Python camera software is shown in Video 1. This video is available in low resolution (a) and high resolution (b) - the high resolution will require at least a 3.5Mbps broadband data rate to view.
|Video 1 - The Python Pi-Camera GUI software.|
Once the video has been captured and stored, the video cannot be replayed on the display. When the video file, produced by the camera, is 'clicked' the operating system asks which application should be used to open the file.
The CamInterface program stores the video in H.264 format. Viewing this video requires the use of an application such as 'omxplayer'. See bullet 3 in Section 5, Using the Camera, for instructions on how to use the 'omxplayer'.
The software quits prematurely with the statement that the 'picamera' library is not available.
The Python Pi-Camera API has not been installed or is not available. To install the API follow the instructions in sub-section 4.4 (Install the Python Pi-Camera API). If the API Documentation has been used as the source of the installation then make sure that the 'System Installation' instructions have been used as opposed to the 'User Installation' and that the Python 3 version instructions are followed. A 'User Installation' will require all of the software to be in the same user directory.
The software quits prematurely with the statement that the 'tkinter' library is not available.
Make sure that you are using the Python 3 shell. While the Python Pi-Camera API supports both Python 2.* and 3.* the GUI-based software uses the 'tkinter' library and so the program must be run using the Python 3 shell.
The raspistill and raspivid applications do not work.
Check that the Pi-Camera has been enabled and that the latest version of the Raspbian operating system has been installed. Follow the instructions in Section 4.2.
The 'CamInterfacev1p0p0.py' software written for this project is available in the Element14 GitHub at: https://github.com/element14/pi_project/tree/master/Pi_Camera. A clone of this software should be established using an appropriate software versioning application. The clone can be established at: https://github.com/element14/pi_project.git.
The CamInterface software consist of one class (Application). The design of the Application class is shown in Figure A1. The software design is based upon four classes:
- Tk - this is core class for the Tkinter GUI library. The list of operations are those that are used by the Application class. This class is contained in the library 'tkinter' (this is only available to Python 3 programs);
- PiCamera - this is the pure Python Pi-Camera API and is used to provide the control over the Pi-Camera. The list of operations are those that are used by the Application class. The class is contained in the library 'picamera' (see Appendix B for more details on this class);
- Frame - the parent class for the Application. The Frame class provides the GUI framework, from the 'tkinter' library, on which the Application GUI is based;
- Application - the class that provides the user with the features to control the Pi-Camera directly from the Python program. It is this class that has been written for this project and which is downloaded from the GitHub.
|Figure A1 - The class structure of the CamInterface software.|
This class has no attributes and eleven methods. The functionality of the eleven methods is:
- __init__ () - defines all the initialisation states for the GUI (this function is called when the 'app' object is instantiated using the statement app = Application (root));
- action_camera () - controls whether or not a single or set of still images are taken by the Pi-Camera;
- action_multiple () - controls the Pi-Camera to take a sequence of still images;
- action_single () - controls the Pi-Camera to take a single still image;
- choose_multiple_photos () - directs the input of the information required to take a sequence of still images;
- choose_single_photo () - directs the input of the information required to take a single still image;
- create_widgets () - creates the set of instructions, buttons and the text area as shown in Figure 5.1. Defines the actions to be invoked when the state of the GUI is changed;
- exit_camera () - provides the controlled close-down of the Pi-Camera;
- setup_camera () - instantiates the Pi-Camera object and defines the operational configuration for the Pi-Camera;
- start_video () - starts the video capture using the Pi-Camera;
- stop_video () - stops the video capture using the Pi-Camera.
The relationships between the class Application and the other libraries is defined by the header instructions of:
from tkinter import * # Load the full set tkinter library
from tkinter import messagebox
from time import sleep
import picamera # The Python Pi-Camera API
import os # Raspian Operating system functions
The main program instructions are:
root = Tk () # Create the GUI root object
root.title ("Image Capture V1.0") # Give the application window a title
app = Application (root) # Create the root application object frame
root.mainloop () # Establish the operational loop
The pure Python interface to the R-Pi Pi-Camera (Python 2.7 and above and Python 3.2 and above) was created by Dave Hughes and the excellent documentation is available at: http://picamera.readthedocs.org/en/release-0.8/index.html. This provides an extensive amount of information about how to use the API to control the Pi-Camera. As shown in Figure A1, the set of PiCamera API methods that are used by the 'CamInterface software' is (the page references are with respect to the v0.8 release of the Python Pi-Camera API documentation):
- capture () - to capture an image from the Pi-Camera and to store it in the defined output stream (page 24);
- capture_continuous () - capture images continuously from the Pi-Camera as an infinite iterator (page 25);
- close () - finalises the state of the Pi-Camera (page 27);
- preview_fullscreen () - retrieves or sets full-screen for the preview window (page 32);
- preview_window () - retrieves or sets the size of the preview window (page 32);
- recording () - returns 'True' if the 'start_recording()' method has been called and no 'stop_recording()' call has been made yet (page 33);
- resolution () - retrieves or sets the resolution at which image captures, video recordings and previews will be captured (page 33);
- start-preview () - displays the preview window (page 27);
- start-recording () - start recording video from the Pi-Camera and store in the defined output stream (page 27);
- stop _preview () - close the preview window display (page 28);
- stop_recording () - stop recording from the Pi-Camera (page 28).
In the CamInterface program the Python Pi-Camera API is instantiated in the method 'setup_camera ()' using the code (line 408):
self.camera = picamera.PiCamera ()
The Camera Serial Interface (CSI) Bus is used to enable the R-Pi processor to use an external digital camera. Connection to the CSI bus is via a 15-way 'flat-flex' connector on the R-Pi that provides a MIPI CSI-2 hardware interface for a digital camera (used for stills or video).
High Definition Multimedia Interface. This is one of the interfaces to the monitor. The PiView is connected to this interface.
Integrated Development Environment for Python. It is completely written in Python and the Tkinter Graphical User Interface (GUI) toolkit (wrapper functions for Tcl/Tk). This is the development environment used for producing the software in this project.
New Out Of Box Software. NOOBS is used to install the appropriate version of Operating System (O/S) onto the R-Pi SD card. The Raspbian O/S is used for this project. In many cases, NOOBS is now pre-installed on SD cards that are sold for use with the R-Pi. The latest version of NOOBS is available from the Raspberry Pi Foundation downloads.
|Omxplayer||An application that converts the H.264 video format into a format that can be displayed using a display connected using the composite or HDMI interfaces to the R-Pi.|
The Raspberry Pi Camera Module is a custom designed add-on for R-Pi. It attaches to R-Pi by way of one of the two small sockets on the board upper surface. This interface uses the dedicated CSI bus, which was designed especially for interfacing to cameras. The CSI bus is capable of extremely high data rates, and it exclusively carries pixel data. The board itself is tiny, at around 25mm x 20mm x 9mm. It also weighs just over 3g, making it perfect for mobile or other applications where size and weight are important. It connects to R-Pi by way of a short ribbon cable. The camera is connected to the BCM2835 processor on the R-Pi via the CSI bus, a higher bandwidth link that carries pixel data from the camera back to the processor. This bus travels along the ribbon cable that attaches the camera board to the R-Pi. The sensor itself has a native resolution of 5 megapixel, and has a fixed focus lens onboard. In terms of still images, the camera is capable of 2592 x 1944 pixel static images, and also supports 1080p30, 720p60 and 640x480p60/90 video.
The software in this project is written using Python 3. IDLE is used to support the development of the Python code. Note that the game playing software will not work using a Python 2 shell because Python 2 does not support the Tkinter GUI libraries.
The R-Pi is the single board computer at the heart of this project. This project will work on both Model A and B versions.
The R-Pi application, available as part of the latest Raspbian O/S, that can be used to obtain still images from a Pi-Camera connected to the R-Pi via the CSI bus.
The R-Pi application, available as part of the latest Raspbian O/S, that can be used to obtain videos from an external Pi-Camera connected to the R-Pi via the CSI bus..
|SD||Secure Digital (SD) is a non-volatile memory card format for use in portable devices. This is the storage medium for the R-Pi.|
Universal Serial Bus.
A Video Graphics Array (VGA) connector is a three-row 15-pin DE-15 connector. The 15-pin VGA connector is found on many video cards, computer monitors, and high definition television sets. In this project a PiView was used to connect the VGA monitor to the HDMI on the R-Pi.
Colin Smythe (Dunelm Services Limited)
13th January, 2014