In this article by Dan Nixon, the author of the book Raspberry Pi Blueprints, we will see the recording of time-lapse captures using the Raspberry Pi camera module.

(For more resources related to this topic, see here.)

One of the possible uses of the Raspberry Pi camera module is the recording of time-lapse captures, which takes a still image at a set interval over a long period of time. This can then be used to create an accelerated video of a long-term event that takes place (for example, a building being constructed).

One alteration to this is to have the camera mounted on a moving vehicle. Use the time lapse to record a journey; with the addition of GPS data, this can provide an interesting record of a reasonably long journey.

In this article, we will use the Raspberry Pi camera module board to create a location-aware time-lapse recorder that will store the GPS position with each image in the EXIF metadata.

To do this, we will use a GPS module that connects to the Pi over the serial connection on the GPIO port and a custom Python program that listens for new GPS data during the time lapse.

For this project, we will use the Raspbian distribution.

What you will need

This is a list of things that you will need to complete this project. All of these are available at most electronic components stores and online retailers:

• The Raspberry Pi
• A relatively large SD card (at least 8 GB is recommended)
• The Pi camera board
• A GPS module (http://www.adafruit.com/product/746)
• 0.1 inch female to female pin jumper wires
• A USB power bank (this is optional and is used to power the Pi when no other power is available)

Setting up the hardware

The first thing we will do is set up the two pieces of hardware and verify that they are working correctly before moving on to the software.

The camera board

The first (and the most important) piece of hardware we need is the camera board. Firstly, start by connecting the camera board to the Pi.

Connecting the camera module to the Pi

The camera is connected to the Pi via a 15-pin flat, flex ribbon cable, which can be physically connected to two connectors on the Pi. However, the connector it should be connected to is the one nearest to the Ethernet jack; the other connector is for display.

1. To connect the cable first, lift the top retention clip on the connector, as shown in the following image:

   

2. Insert the flat, flex cable with the silver contacts facing the HDMI port and the rigid, blue plastic part of the ribbon connector facing the Ethernet port on the Pi:

   

3. Finally, press down the cable retention clip to secure the cable into the connector. If this is done correctly, the cable should be perpendicular to the printed circuit board (PCB) and should remain seated in the connector if you try to use a little force to pull it out:

   

4. Next, we will move on to set up the camera driver, libraries, and software within Raspbian.

Setting up the Raspberry Pi camera

Firstly, we need to enable support for the camera in the operating system itself by performing the following steps:

1. This is done by the raspi-config utility from a terminal (either locally or over SSH). Enter the following command:

   sudo raspi-config

   This command will open the following configuration page:

   

   This will load the configuration utility. Scroll down to the Enable Camera option using the arrow keys and select it using Enter.

2. Next, highlight Enable and select it using Enter:

   

   Once this is done, you will be taken back to the main raspi-config menu. Exitraspi-config, and reboot the Pi to continue.

3. Next, we will look for any updates to the Pi kernel, as using an out-of-date kernel can sometimes cause issues with the low-level hardware, such as the camera module and GPIO. We also need to get a library that allows control of the camera from Python.
   Both of these installations can be done with the following two commands:

   sudo rpi-update
   sudo apt-get install python-picamera

4. Once this is complete, reboot the Pi using the following command:

   sudo reboot

5. Next, we will test out the camera using the python-picamera library we just installed.
   To do this, create a simple test script using nano:

   nano canera_test.py

6. The following code will capture a still image after opening the preview for 5 seconds. Having the preview open before a capture is a good idea as this gives the camera time to adjust capture parameters of the environment:

   import sys
   import time
   import picamera
   
   with picamera.PiCamera() as cam:
      cam.resolution = (1280, 1024)
      cam.start_preview()
      time.sleep(5)
      cam.capture(sys.argv[1])
      cam.stop_preview()

7. Save the script using Ctrl + X and enter Y to confirm. Now, test it by using the following command:

   python camera_test.py image.jpg

8. This will capture a single, still image and save it to image.jpg. It is worth downloading the image using SFTP to verify that the camera is working properly.

The GPS module

Before connecting the GPS module to the Pi, there are a couple of important modifications that need to be made to the way the Pi boots up.

By default, Raspbian uses the on-board serial port on the GPIO header as a serial terminal for the Pi (this allows you to connect to the Pi and run commands in a similar way to SSH). However, this is of little use to us here and can interfere with the communication between the GPS module and the Pi if the serial terminal is left enabled. This can be disabled by modifying a couple of configuration files:

1. First, start with:

   sudo nano /boot/cmdline.txt

2. Here, you will need to remove any references to ttyAMA0 (the name for the on-board serial port). In my case, there was a single entry of console=ttyAMA0,115200, which had to be removed. Once this is done, the file should look something like what is shown in the following screenshot:

   

3. Next, we need to stop the Pi by using the serial port for the TTY session. To do this, edit this file:

   sudo nano /etc/inittab

4. Here, look for the following line and comment it out:

   T0:23:respawn:/sbin/getty -L ttyAMA0 115200 vt100

   Once this is done, the file should look like what is shown in the following screenshot:

   

5. After both the files are changed, power down the Pi using the following command:

   sudo shutdown -h now

Next, we need to connect the GPS module to the Pi GPIO port. One important thing to note when you do this is that the GPS module must be able to run on 3.3 V or at least be able to use a 3.3 V logic level (such as the Adafruit module I am using here).

As with any device that connects to the Pi GPIO header, using a 5 V logic device can cause irreparable damage to the Pi.

Next, connect the GPS module to the Pi, as shown in the following diagram. If you are using the Adafruit module, then all the pins are labeled on the PCB itself. For other modules, you may need to check the data sheet to find which pins to connect:

Once this is completed, the wiring to the GPS module should look similar to what is shown in the following image:

After the GPS module is connected and the Pi is powered up, we will install, configure, and test the driver and libraries that are needed to access the data that is sent to the Pi from the GPS module:

1. Start by installing some required packages. Here, gpsd is the daemon that managed data from GPS devices connected to a system, gpsd-clients contains a client that we will use to test the GPS module, and python-gps contains the Python client for gpsd, which is used in the time-lapse capture application:

   sudo apt-get install gpsd gpsd-clients python-gps

2. Once they are installed, we need to configure gpsd to work in the way we want. To do this, use the following command:

   sudo dpkg-reconfigure gpsd

3. This will open a configuration page similar to raspi-config. First, you will be asked whether you want gpsd to start on boot. Select Yes here:

   

4. Next, it will ask whether we are using USB GPS receivers. Since we are not using one, select No here:

   

5. Next, it will ask for the device (that is, serial port) the GPS receiver is connected to. Since we are using the on-board serial port on the Pi GPIO header, enter /dev/ttyAMA0 here:

   

6. Next, it will ask for any custom parameters to pass to gpsd, when it is executed. Here, we will enter -n -G. -n, which tells gpsd to poll the GPS module even before a client has requested any data (this has been known to cause problems with some applications) and -G tells gpsd to accept connections from devices other then the Pi itself (this is not really required, but is a good debugging tool):

   

   When you start gpsd with the -G option, you can then use cgps to view the GPS data from any device by using the command where [IP] is the IP address of the Pi:

   cgps [IP]

7. Finally, you will be asked for the location of the control socket. The default value should be kept here so just select Ok:

   

8. After the configuration is done, reboot the Pi and use the following command to test the configuration:

   cgps -s

   This should give output similar to what is shown in the following screenshot, if everything works:

   

If the status indication reads NO FIX, then you may need to move the GPS module into an area with a clear view of the sky for testing. If cgps times out and exits, then gpsd has failed to communicate with your GPS module. Go back and double-check the configuration and wiring.

Setting up the capture software

Now, we need to get the capture software installed on the Pi.

1. First, copy the recorder folder onto the Pi using FileZilla and SFTP.
2. We need to install some packages and Python libraries that are used by the capture application. To do this, first install the Python setup tools that I have used to package the capture application:

   sudo apt-get install python-setuptools git

3. Next, run the following commands to download and install the pexif library, which is used to save the GPS position from which each image was taken into the image EXIF data:

   git clone https://github.com/bennoleslie/pexif.git pexif
   cd pexif
   sudo python setup.py install

4. Once this is done, SSH into the Pi can change directory to the recorder folder and run the following command:

   sudo python setup.py install

5. Now that the application is installed, we can take a look at the list of commands it accepts using:

   gpstimelapse -h

   This shows the list of commands, as shown in the following screenshot:

   

A few of the options here can be ignored; –log-file, –log-level, and –verbose were mainly added for debugging while I was writing the application. The –gps option will not need to be set, as it defaults to connect to the local gpsd instance, which if the application is running on the Pi, will always be correct.

The –width and –height options are simply used to set the resolution of the captured image. Without them, the capture software will default to capture 1248 x 1024 images.

The –interval option is used to specify how long, in seconds, to wait before it captures another time-lapse frame. It is recommended that you set this value at least 10 seconds in order to avoid filling the SD card too quickly (especially if the time lapse will run over a long period of time) and to ensure that any video created with the frames is of a reasonably length (that is, not too long).

The –distance option allows you to specify a minimum distance, in kilometers, that must be travelled since the last image was captured and before another image is captured. This can be useful to record a time lapse where, whatever holds the Pi, may stop in the same position for periods of time (for example, if the camera is in a car dashboard, this would prevent it from capturing several identical frames if the car is waiting in traffic).

This option can also be used to capture a set of images based alone on the distance travelled, disregarding the amount of time that has passed. This can be done by setting the –interval option to 1 (a value of 1 is used as data is only taken from the GPS module every second, so checking the distance travelled faster than this would be a waste of time).

The folder structure is used to store the frames. While being slightly complex at first sight, this is a good method that allows you to take multiple captures without ever having to SSH into the Pi.

Using the –folder option, you can set the folder under which all captures are saved. In this folder, the application looks for folders with a numerical name and creates a new folder that is one higher than the highest number it finds. This is where it will save the images for the current capture.

The filename for each image is given by the –filename option. This option specifies the filename of each image that will be captured. It must contain %d, which is used to indicate the frame number (for example, image_%d.jpg).

For example, if I pass –folder captures –filename image_%d.jpg to the program, the first frame will be saved as ./captures/0/image_0/jpg, and the second as ./captures/0/image_1.jpg.

Here are some examples of how the application can be used:

• gpstimelapse –folder captures –filename i_%d.jpg –interval 30: This will capture a frame in every 30 seconds
• gpstimelapse –folder captures –filename i_%d.jpg –interval 30 –distance 0.05: This will capture a frame in every 30 seconds, provided that 50 meters have been travelled
• gpstimelapse –folder captures –filename i_%d.jpg –interval 1 –distance 0.05: This will capture a frame in every 50 meters that have been travelled

Now that you are able to run the time-lapse recorder application, you are ready to configure it to start as soon as the Pi boots. Removing the need for an active network connection and the ability to interface with the Pi to start the capture.

1. To do this, we will add a command to the /etc/rc.local file. This can be edited using the following command:

   sudo nano /etc/rc.local

2. The line you will add will depend on how exactly you want the recorder to behave. In this case, I have set it to record an image at the default resolution every minute. As before, ensure that the command is placed just before the line containing exit 0:

   

Now, you can reboot the Pi and test out the recorder. A good indication that the capture is working is the red LED on the camera board that lights up constantly. This shows that the camera preview is open, which should always be the case with this application.

Also note that, the capture will not begin until the GPS module has a fix. On the Adafruit module, this is indicated by a quick blink every 15 seconds on the fix LED (no fix is indicated by a steady blink once per second).

One issue you may have with this project is the amount of power required to power the camera and GPS module on top of the Pi. To power this while on the move, I recommend that you use one of the USB power banks that have a 2 A output (such power banks are readily available on Amazon).

Using the captures

Now that we have a set of recorded time-lapse frames, where each has a GPS position attached, there are a number of things that can be done with this data. Here, we will have a quick look at a couple of instances for which we can use the captured frames.

Creating a time-lapse video

The first and probably the most obvious thing that can be done with the images is you can create a time-lapse video in which, each time-lapse image is shown as a single frame of the video, and the length (or speed) of the video is controlled by changing the number of frames per second.

One of the simplest ways to do this is by using either the ffmpeg or avconv utility (depending on your version of Linux; the parameters to each are identical in our case). This utility is available on most Linux distributions, including Raspbian. There are also precompiled executables available for Mac and Windows. However, here I will only discuss using it on Linux, but rest assured, any instructions given here will also work on the Pi itself.

To create a time lapse, form a set of images. You can use the following command:

avconv -framerate FPS -i FILENAME -c:v libx264 -r 30 -pix_fmt yuv420p OUTPUT

Here, FPS is the number of the time-lapse frames you want to display every second, FILENAME is the filename format with %d that marks the frame number, and OUTPUT is the output’s filename. This will give output similar to the following:

Exporting GPS data as CSV

We can also extract GPS data from each of the captured time-lapse images and save it as a comma-separated value (CSV) file. This will allow us to import the data into third-party applications, such as Google Maps and Google Earth.

To do this, we can use the frames_to_gps_path.py Python script. This takes the file format for the time-lapse frames and a name for the output file.

For example, to create a CSV file called gps_data.csv for images in the frame_%d.jpg format, you can use the following command:

python frames_to_gps_points.py -f frame_%d.jpg -o gps_points.csv

The output is a CSV file in the following format:

[frame number],[latitude],[longitude],[image filename]

The script also has the option to restrict the maximum number of output points. Passing the –max-points N parameter will ensure that no more than N points are in the CSV file. This can be useful for importing data into applications that limit the number of points that can be imported.

Summary

In this article, we had a look at how to use the serial interface on the GPIO port in order to interface with some external hardware. The knowledge of how to do this will allow you to interface the Pi with a much wider range of hardware in future projects.

We also took a look at the camera board and how it can be used from within Python. This camera is a very versatile device and has a very wide range of uses in portable projects and ubiquitous computing.

You are encouraged to take a deeper look at the source code for the time-lapse recorder application. This will get you on your way to understand the structure of moderately complex Python programs and the way they can be packaged and distributed.

Resources for Article:

---

Further resources on this subject:

• Central Air and Heating Thermostat [article]
• Raspberry Pi Gaming Operating Systems [article]
• The Raspberry Pi and Raspbian [article]

---