The Raspberry Pi camera - part 1 - James Hughe
The Raspberry Pi camera - part 1 - James Hughes, Mag Pi 2013 July
http://www.themagpi.com/en/issue/14
A few weeks ago, the Raspberry Pi Foundation launched their first peripheral, a 5MP camera. Priced at $25, the same price as the model A, it’s a very small PCB on which is an Omnivision OV5647 camera module. It connects to either the Model A or Model B Raspberry Pi using a 15cm 15 way ribbon connector.
Over the course of this series I will take you through initial connection of the camera to your Raspberry Pi and will show you some of the basic commands used to take both still and video imagery. At the end, some of the more sophisticated features will also be explained. Not every option will be covered (new options are being added all the time so it’s difficult to keep up) but hopefully this article will give enough information for you to be able to cover most image taking tasks. Firstly though, a description of how the camera module came to be...
History
From its first launch the Raspberry Pi has had a connector on it to attach a camera to the GPU (the VideoCore 4 Graphics Processing Unit on the Raspberry Pi). This connection uses the CSI -2 electrical protocol and is a standard used in most mobile phones. It is an extremely fast connection, which on the Raspberry Pi is capable of sending 1080p sized images (1920x 1080 x10bpp) at 30 frames per second,or lower resolution at even higher frame rates. It had always been intended at some point to release a camera module that could use this connection, as the ability to stream high speed video data through the GPU without any interaction with the ARM processor would always make the camera much more efficient than any USB attached webcam. It would also enable the use of the GPU’s ability to encode H264 video,or JPEG images in hardware.
It turns out that productising a tiny PCB like the camera board is not a quick task! The prototype was re-designed to remove some unnecessary components, but more importantly, to move the camera crystal, used for timing, to the PCB itself.
Electromagnetic compatibility (EMC) testing had shown that the 25Mhz clock provided by the GPU caused too much interference as it passed up the ribbon cable to the PCB. Adding a crystal to the PCB itself stopped this interference. A couple more board designs later, to help with production line manufacture and testing, and eventually, about a year after the first prototypes, the production board was ready.
Meanwhile, work had been ongoing to write a couple of applications to make use of the camera, to update the GPU firmware to support the camera, and to improve the camera tuning as the basic tuning already in place had a number of obvious defects.
Camera tuning is a complex task, which has been covered on the Raspberry Pi website, so I won’t repeat it here. Suffice it to say, the end results are well worth the extra effort put in by David Plowman while at Broadcom. Thanks David.
So, with the history out of the way, let’s take a look at getting your camera going.
Setting up
Firstly, it’s important to start with a warning.
Cameras like these are static sensitive. You should earth yourself prior to handling the PCB (a sink tap/faucet or similar should suffice if you don’t have an earthing strap).
There are only two connections to make, the ribbon cable needs to be attached to the camera PCB and the Raspberry Pi itself. You need to get it the right way round or the camera will not work. On the camera PCB, the blue backing on the cable should be away from the PCB, and on the Raspberry Pi it should be towards the ethernet connection (or where the ethernet connector would be if you are using a model A).
Although the connectors on the PCB and the Pi are different, they work in a similar way. On the Raspberry Pi, you need to pull up the tabs on each end of the connector.
It should slide up easily, and be able to pivot around slightly. Fully insert the ribbon cable into the slot, ensuring it is straight, then gently press down the tabs to clip it into place. The camera PCB itself also requires you to pull the tabs away from the board, gently insert the cable, then push the tabs back. [not necessary, because this end is already connected before delivery.]
The PCB connector is a little more awkward than the one on the Pi itself. There is a video at http://youtu.be/GImeVqHQzsE which shows the connections being made.
So, we now have the hardware all attached, we now need to make sure we have the correct software installed. As explained above, there are
some command line apps to install, and a firmware upgrade with the camera driver and tuning to install. This process may not be necessary in future as newer distro’s are released which already contain the required files.
To update the firmware, libraries and applications, execute the following instructions on the command line.
sudo apt-get update
sudo apt-get upgrade
Now you need to enable camera support using the raspi-config program you will have used when you first set up your Raspberry Pi.
sudo raspi-config
Use the cursor keys to move to the camera option and select enable. When you exit raspiconfig it will ask to reboot. The enable option will ensure that on reboot the correct GPU firmware will be running (with the camera driver and tuning), and the GPU memory split is sufficient to allow the camera to acquire enough memory to run correctly. Running a camera and associated encoder does take up a big chunk of memory, as the images are large, and there needs to be at
least two of them in memory at any time in order to provide a double (in some cases triple) buffer which prevents 'tearing' of images during display.
Checking it works
OK, we have connected the hardware, and installed the software. Now we need to see if it is all working correctly! The quickest way is just to type in
raspistill -t 5000
This runs the stills capture program for 5 seconds (or 5000 milliseconds. Note that all times used are in milliseconds). You should see the whole display replaced with a moving image of whatever the camera is looking at. [not for ssh mode using for example PuTTY]
If you don’t see the preview appear, or there are error messages displayed, go straight to the Troubleshooting section at the end of the article!
So, what can it do?
As with any camera, it can work in two ways. We can capture still images, just like a camera, or we can capture video, like a camcorder.
The two demo applications provided handle these tasks separately. Although it would be quite possible to combine them into one application, that makes the code more complicated, and as demo code a
lot of effort was put in to make it as easy to understand as possible.
As an aside, the C language source code for the applications is
publicly available from the Foundation's github repository. Anyone is welcome to play around with it and alter it for their particular purposes.
The code is well commented and uses the Doxygen commenting scheme so you can produce HTML documentation directly from the source code.
So, on to the apps themselves. They are command line applications, and do not need to be run from a desktop environment since the preview output from the apps is superimposed over the top of any desktop or console being used. Typing just the name of the application, or
adding --help or -?
to the command line will produce a list of all the available options. The list is quite long, so you may want to pipe the output into ‘less’ so you can scroll up and down to read it.
raspistill | less
raspivid | less
Basic options
Both applications use the -t option to specify the length of time in milliseconds they should continue running.
So “raspistill -t 3000” will run the camera for 3 seconds.
In the stills case, and if a filename is specified, the capture of the still will take place at the end of the time period.
In the video case, and again if a filename is specified, the capture starts straight away and will be as long as the time period.
To specify the filename of the output file, you use the -o option. The following command runs the camera for 2 seconds and at the end of the
period will take a still image, saving it to the file image.jpg.
raspistill -o image.jpg -t 2000
This command will do the same but will save a 2 second H264 video file called video.h264
raspivid -o video.h264 -t 2000
You don’t need to specify a filename for the output - if you don’t then no capture is done, but the preview will still be run for the specified time.
If you don’t specify a time, then 5 seconds is used as a default.
The following will take a picture after 5 seconds.
raspistill -o image.jpg
So we have made some files, but how do we see what they look like?
Well, to view JPG images, the FBI program is quite useful. You can install it quickly using:
sudo apt-get install fbi
Then you can easily display your JPG images, zoom in and out (use - and +) etc.
fbi image.jpg
To view video, you can use the already installed omxplayer.
omxplayer video.h264
Preview options
You can specify whether you want the preview disabled (-n), or whether it is to appear full screen (-f) or in a window (-p). You can also
specify what opacity (-op) the preview window is to have (so you can see the desktop underneath if necessary).
To display the preview in a window at position 1 00,1 00, width 500, height 400 and at 50% opacity (0-transparent to 255 -opaque), enter:
raspistill -p 100,100,500,400 -op 128 -o image.jpg
To disable preview completely, enter:
raspistill -n -o image.jpg
Join us in issue 1 5 of The MagPi where some of the more advanced features will be discussed!
Troubleshooting
If your camera is not working, there are a number of things to check to ensure it is set up correctly.
1) Are the ribbon connectors all firmly seated and the right way round?
2) Is the camera module connector firmly attached to the camera PCB?
3) Have you run sudo apt-get update, sudo aptget upgrade? 4) Have you run raspi-config and enabled the camera?
So, if things are still not working, try the following:
Error : raspistill/raspivid not found. This probably means your update/upgrade failed in some way. Try it again.
Error : ENOMEM displayed. Camera is not starting up. Check all connections again.
Error : ENOSPC displayed. Camera is probably running out of GPU memory. Check config.txt in the /boot/ folder. The gpu_mem
option should be at least 128.
http://www.themagpi.com/en/issue/14
A few weeks ago, the Raspberry Pi Foundation launched their first peripheral, a 5MP camera. Priced at $25, the same price as the model A, it’s a very small PCB on which is an Omnivision OV5647 camera module. It connects to either the Model A or Model B Raspberry Pi using a 15cm 15 way ribbon connector.
Over the course of this series I will take you through initial connection of the camera to your Raspberry Pi and will show you some of the basic commands used to take both still and video imagery. At the end, some of the more sophisticated features will also be explained. Not every option will be covered (new options are being added all the time so it’s difficult to keep up) but hopefully this article will give enough information for you to be able to cover most image taking tasks. Firstly though, a description of how the camera module came to be...
History
From its first launch the Raspberry Pi has had a connector on it to attach a camera to the GPU (the VideoCore 4 Graphics Processing Unit on the Raspberry Pi). This connection uses the CSI -2 electrical protocol and is a standard used in most mobile phones. It is an extremely fast connection, which on the Raspberry Pi is capable of sending 1080p sized images (1920x 1080 x10bpp) at 30 frames per second,or lower resolution at even higher frame rates. It had always been intended at some point to release a camera module that could use this connection, as the ability to stream high speed video data through the GPU without any interaction with the ARM processor would always make the camera much more efficient than any USB attached webcam. It would also enable the use of the GPU’s ability to encode H264 video,or JPEG images in hardware.
It turns out that productising a tiny PCB like the camera board is not a quick task! The prototype was re-designed to remove some unnecessary components, but more importantly, to move the camera crystal, used for timing, to the PCB itself.
Electromagnetic compatibility (EMC) testing had shown that the 25Mhz clock provided by the GPU caused too much interference as it passed up the ribbon cable to the PCB. Adding a crystal to the PCB itself stopped this interference. A couple more board designs later, to help with production line manufacture and testing, and eventually, about a year after the first prototypes, the production board was ready.
Meanwhile, work had been ongoing to write a couple of applications to make use of the camera, to update the GPU firmware to support the camera, and to improve the camera tuning as the basic tuning already in place had a number of obvious defects.
Camera tuning is a complex task, which has been covered on the Raspberry Pi website, so I won’t repeat it here. Suffice it to say, the end results are well worth the extra effort put in by David Plowman while at Broadcom. Thanks David.
So, with the history out of the way, let’s take a look at getting your camera going.
Setting up
Firstly, it’s important to start with a warning.
Cameras like these are static sensitive. You should earth yourself prior to handling the PCB (a sink tap/faucet or similar should suffice if you don’t have an earthing strap).
There are only two connections to make, the ribbon cable needs to be attached to the camera PCB and the Raspberry Pi itself. You need to get it the right way round or the camera will not work. On the camera PCB, the blue backing on the cable should be away from the PCB, and on the Raspberry Pi it should be towards the ethernet connection (or where the ethernet connector would be if you are using a model A).
Although the connectors on the PCB and the Pi are different, they work in a similar way. On the Raspberry Pi, you need to pull up the tabs on each end of the connector.
It should slide up easily, and be able to pivot around slightly. Fully insert the ribbon cable into the slot, ensuring it is straight, then gently press down the tabs to clip it into place. The camera PCB itself also requires you to pull the tabs away from the board, gently insert the cable, then push the tabs back. [not necessary, because this end is already connected before delivery.]
The PCB connector is a little more awkward than the one on the Pi itself. There is a video at http://youtu.be/GImeVqHQzsE which shows the connections being made.
So, we now have the hardware all attached, we now need to make sure we have the correct software installed. As explained above, there are
some command line apps to install, and a firmware upgrade with the camera driver and tuning to install. This process may not be necessary in future as newer distro’s are released which already contain the required files.
To update the firmware, libraries and applications, execute the following instructions on the command line.
sudo apt-get update
sudo apt-get upgrade
Now you need to enable camera support using the raspi-config program you will have used when you first set up your Raspberry Pi.
sudo raspi-config
Use the cursor keys to move to the camera option and select enable. When you exit raspiconfig it will ask to reboot. The enable option will ensure that on reboot the correct GPU firmware will be running (with the camera driver and tuning), and the GPU memory split is sufficient to allow the camera to acquire enough memory to run correctly. Running a camera and associated encoder does take up a big chunk of memory, as the images are large, and there needs to be at
least two of them in memory at any time in order to provide a double (in some cases triple) buffer which prevents 'tearing' of images during display.
Checking it works
OK, we have connected the hardware, and installed the software. Now we need to see if it is all working correctly! The quickest way is just to type in
raspistill -t 5000
This runs the stills capture program for 5 seconds (or 5000 milliseconds. Note that all times used are in milliseconds). You should see the whole display replaced with a moving image of whatever the camera is looking at. [not for ssh mode using for example PuTTY]
If you don’t see the preview appear, or there are error messages displayed, go straight to the Troubleshooting section at the end of the article!
So, what can it do?
As with any camera, it can work in two ways. We can capture still images, just like a camera, or we can capture video, like a camcorder.
The two demo applications provided handle these tasks separately. Although it would be quite possible to combine them into one application, that makes the code more complicated, and as demo code a
lot of effort was put in to make it as easy to understand as possible.
As an aside, the C language source code for the applications is
publicly available from the Foundation's github repository. Anyone is welcome to play around with it and alter it for their particular purposes.
The code is well commented and uses the Doxygen commenting scheme so you can produce HTML documentation directly from the source code.
So, on to the apps themselves. They are command line applications, and do not need to be run from a desktop environment since the preview output from the apps is superimposed over the top of any desktop or console being used. Typing just the name of the application, or
adding --help or -?
to the command line will produce a list of all the available options. The list is quite long, so you may want to pipe the output into ‘less’ so you can scroll up and down to read it.
raspistill | less
raspivid | less
Basic options
Both applications use the -t option to specify the length of time in milliseconds they should continue running.
So “raspistill -t 3000” will run the camera for 3 seconds.
In the stills case, and if a filename is specified, the capture of the still will take place at the end of the time period.
In the video case, and again if a filename is specified, the capture starts straight away and will be as long as the time period.
To specify the filename of the output file, you use the -o option. The following command runs the camera for 2 seconds and at the end of the
period will take a still image, saving it to the file image.jpg.
raspistill -o image.jpg -t 2000
This command will do the same but will save a 2 second H264 video file called video.h264
raspivid -o video.h264 -t 2000
You don’t need to specify a filename for the output - if you don’t then no capture is done, but the preview will still be run for the specified time.
If you don’t specify a time, then 5 seconds is used as a default.
The following will take a picture after 5 seconds.
raspistill -o image.jpg
So we have made some files, but how do we see what they look like?
Well, to view JPG images, the FBI program is quite useful. You can install it quickly using:
sudo apt-get install fbi
Then you can easily display your JPG images, zoom in and out (use - and +) etc.
fbi image.jpg
To view video, you can use the already installed omxplayer.
omxplayer video.h264
Preview options
You can specify whether you want the preview disabled (-n), or whether it is to appear full screen (-f) or in a window (-p). You can also
specify what opacity (-op) the preview window is to have (so you can see the desktop underneath if necessary).
To display the preview in a window at position 1 00,1 00, width 500, height 400 and at 50% opacity (0-transparent to 255 -opaque), enter:
raspistill -p 100,100,500,400 -op 128 -o image.jpg
To disable preview completely, enter:
raspistill -n -o image.jpg
Join us in issue 1 5 of The MagPi where some of the more advanced features will be discussed!
Troubleshooting
If your camera is not working, there are a number of things to check to ensure it is set up correctly.
1) Are the ribbon connectors all firmly seated and the right way round?
2) Is the camera module connector firmly attached to the camera PCB?
3) Have you run sudo apt-get update, sudo aptget upgrade? 4) Have you run raspi-config and enabled the camera?
So, if things are still not working, try the following:
Error : raspistill/raspivid not found. This probably means your update/upgrade failed in some way. Try it again.
Error : ENOMEM displayed. Camera is not starting up. Check all connections again.
Error : ENOSPC displayed. Camera is probably running out of GPU memory. Check config.txt in the /boot/ folder. The gpu_mem
option should be at least 128.
.END
No comments:
Post a Comment