Motion Guide

A user guide written for "normal" people. Nerds are welcome, too.

Editor: Kenneth Lavrsen
Original URL for this document. http://www.lavrsen.dk/sources/webcam/motion_guide.htm
Version: 1.47 (for motion 3.0.7 and 3.1.10), 2003 November 12, 00:30

This guide is updated AFTER each new release. Normally expect some days after each release before the updated version is available.
From version 3.0.1 of motion this guide is now part of the distribution. The jpg files however are not included. Go to the URL above if you want to see the guide with pictures.
1.5 Added a detailed description about using the video4linux loopback device with Motion.
1.6 Corrected some details about module loading order in the video loopback section that was added in 1.5.
1.7 Added fix for filename bug in the mpeg_encode feature. Added note that ffmpeg sources are currently no longer available at the ffmpeg site.
1.8 Added a reference to the URL of the original document in case someone gets a copy in a package or paper copy and wants to see the latest online.
1.9 Updated for rev 3.0.1. Removed the bugfixes that are now all fixed in 3.0.1. Added a section describing the new make file options.
1.10 Added method for downloading ffmpeg from the CVS
1.11 Corrected the feature description of ffmpeg.
1.12 Added a fix for using ffmpeg version 0.4.5. Also added a link to locations of the ffmpeg-0.4.5.tar.gz file (no guarantee that it will always be valid). Updated version of motion to 3.0.2. This version does not yet cover the experimental 3.1.0 version.
1.13 Added even more ffmpeg 0.4.5 download URLs. One of them must work.
1.14 Added note about ffmpeg and processor type in the ffmpeg section.
1.15 Updated to version 3.0.3. ffmpeg now fixed. Added the new 3 usertext options and a section to describe these.
1.16 Updated so that examples shows 3.0.3.
1.17 Clarified that the timelaps function of ffmpeg generated mpegs is fixed to one shot per minute.
1.18 Updated to version 3.0.4. No changes in this guide except the version.
1.19 Added the new options for experimental version 3.1.2. Added new section with sub-sections at the end of the document describing the 3.1.2 experimental version.
1.20 Minor cosmetics and removal of two dead ffmpeg links.
1.21 Updated for version 3.1.3.. The following options descriptions were added or improved: debug_parameter, ffmpeg_cap_motion, ffmpeg_timelaps, mpeg_encode, netcam_url, netcam_userpass, onmpeg, realconfig (removed), thread, track_speed, track_stepsize, -U, -A (removed). The following special sections have been improved: ffmpeg, mask file, webcam server, and experimental version 3.1.2 has become 3.1.3 with many changes and important bug fix notes. Options in tables have been better alphabetized. Misc typos corrected.
1.22 Minor clarification of the install commands (/path/to) based on user feedback.
1.23 Added information in the config file options section about parameters that are not allowed in the config file without having the matching software installed (cURL, MySQL, PostgreSQL and ffmpeg).
1.24 Updated the guide for versions 3.0.5 (no changes) and 3.1.4 (less errors to correct when installing - also NEW errors). ffmpeg section updated.
1.25. Modified ffmpeg section to only refer to the latest cvs version (which now works great with Motion). Changed the yes|no to on|off for all boolean type config parameters to match the autogerated motion.conf files that motion 3.1.4 can create using xml-rpc commands. Yes|no are still valid values. So are 1 and 0. Corrected some errors in the drawtext parameter description.
1.26. Updated for motion 3.1.5. Workarounds and code tweaking is no longer needed to install 3.1.5. xml-rpc section for 3.1.5 is improved. New 'motion-control action quit' command added. Commands are now placed in a nice table.
1.27 Corrected mistake in the mask file section (missing important '-' in djpeg command line)
1.28 Clarified the licensing description so that it is clear that Motion is a Generel Public License project.
1.29 Added new parameter "output_all" for version 3.1.6. The editor cannot understand what it is used for other than filling up the harddisk with pictures in no time. Updated links to ffmpeg released version 0.4.6 and the ffmpeg latest CVS release.
1.30 Extended the description of the new output_all feature in the table of options and added a small section in the end of the document.
1.31 Added a fix for how to compile Motion without xml-rpc in version 3.1.6 (from Motion mailing list posting from Emilio Paulini).
1.32 Added "Known Problems" section with link to patches - will be removed again when/if they (or similar fixes) are included with next release. Added a reference to all those nice people on the mailing list in the "How do I get.." section.
1.33 Small improvement in the explanation of the webcam_motion option.
1.34 Updated for versions 3.0.6 and 3.1.7. Important changes are - roundrobing option has been corrected to the correct spelling roundrobin in the 3.1.7 version only. This impacts your old motion.conf files. Kenneth Lavrsen's patches are no longer needed as they are now included in both releases. Workaround needed for 3.1.X when not having xml-rpc installed has removed. It is no longer needed in 3.1.7.
1.35 Do not try 3.1.7 yet. There is an error in picture.c that prevents you from compiling it. Fix should be ready any time.
1.36 Fix for 3.1.7 added. See Known Problems section. Added information about the fact that the webcam feature and ppm on is not compatible.
1.37 Improved the description of the 'input' config paramerer (-i command line parameter).
1.38 Updated for version 3.1.8. This fixes the compiler error that 3.1.7 had.
1.39 Fix for wrong version in 3.1.7 simplified by using autoconf if available.
1.40 Added fix for the often reported 'ioctl (VIDIOCGCHAN): Invalid argument'. See known problems section.
1.41 Corrected a typo in the known problems section: 'inout' -> 'input'. Patch file was and is OK.
1.42 As a result of good feedback from users I have a updated the guide to better explain the config files (thanks Peter)
1.43 Corrected the order in which Motion looks for its config file and also correct the path name for the $HOME/.motion directory. Improved the language in the 'How to Install Motion' section.
1.44 Updated the "Known Problems" section and added new patch that addresses both the 'ioctl (VIDIOCGCHAN): Invalid argument' and segmentation fault when saving motion type mpegs using ffmpeg. Hopefully this patch will no longer be needed when next versions of Motion are released.
1.45 Extended the Known Problems section with fix for compatibility with ffmpeg 0.4.8. Current stable version is now 3.0.7. Installation of XMLRPC-C library used for 3.1.8 is extended per request from users.
1.46 Updated for release 3.0.7 which is a clean bugfix release that clears out the "known problem". MySQL section simplyfied as some old warnings are not really relevant anymore.
1.47 Updated for release 3.1.10. New features for 3.1.10 only! The error logging now happens into the syslog. This means that you can see the errors than happened when running in daemon mode also. The other new feature is that the cpu_low option is no longer an on/off option but a parameter than can have value 0 = off and integers larger than 0 is the framerate that Motion runs when not detecting motion. This value should be lower than the framerate set for the camera to make sense.. Additionally improvements of performance in file creations, optimized rgb conversion, and differences search, improved memory handling and removal of memory leak.

What is Motion?

Motion is a program that monitors the video signal from one or more cameras and is able to detect if a significant part of the picture has changed. Or in other words, it can detect motion.
The program is written in C and is made for the Linux operating system.
Motion is a command line based tool. It has absolutely no graphical user interface. Everything is setup either via the command line or via a set of configuration files (simple ASCII files that can be edited by any ASCII editor).
The output from motion can be:

• jpg files
• ppm format files
• mpeg video sequences

How do I get Motion and what does it cost?

Motion is an open source type of project. It does not cost anything. Motion is published under the GNU GENEREL PUBLIC LICENSE (GPL) version 2 or later. It may be a bit difficult to understand all the details of the license text (especially if your first language is not English). It means that you can get the program, install it and use it freely. You do not have to pay anything and you do not have to register anywhere or ask the author or publisher for permission. The GPL gives you both rights and some very reasonable dutys when it comes to copying, distribution and modification of the program. So in very general terms you do not have to worry about licensing as a normal hobby user. If you want to use Motion in a commercial product, if you want to distribute either modified or original versions of Motion - for free or for a fee, you should read the license carefully. For more information about free software and the GPL, I encourage you to study the very interesting documents about the subjust available the of the Free Software Foundation pages about the Philosophy of the GNU Project.

Both Motion and the Motion Guide are written by people that do all this as a hobby and without asking for any payments or donations. We have a life other than developing Motion and its documentation. This means that bugfixes and updates to this guide are done as our time and families allow it. You are however encouraged to participate and contribute in a very active mailing list. It is a list with a very "positive attitude" and with many contributors that propose features, post patches, discuss problems and patiently answer newbie questions with a very positive spirit. Expect 1-10 emails per day.

To get motion direct your browser to the Motion Homepage.

Under the download page you will find a series of stable versions and a series of development versions.

The latest stable versions is 3.0.7.
There is an experimental version 3.1.10 which is actually quite stabil also but with some new features that are not fully refined.

What features does Motion have?

See more description at the Motion Homepage.

• Taking snapshots of movement
• Watch multiple video devices at the same time
• Watch multiple inputs on one capture card at the same time
• Live streaming webcam (using multipart/x-mixed-replace)
• Real time creation of mpeg movies using libavcodec from ffmpeg
• Create mpeg movies from snapshots after events using mpeg_encode
• Take automated snapshots on regular intervals
• Take automated snapshots at irregular intervals using cron
• Sending an e-mail when detecting movement
• Sending a SMS message when detecting movement
• Execute external commands when detecting movement
• Motion tracking
• Feed events to an MySQL or PostgreSQL database.
• Feed video back to a video4linux loopback for real time viewing
• Web interface using motion.cgi
• User configurable and user defined on screen display.
• Control via xml-rpc - small control binary to control motion while running (version 3.1.10 only)
• Ability to recognise certain types of motion (prediction feature - not refined to anything useful yet - version 3.1.10 only)
• Automatic noise and thredhold control (version 3.1.10 only - need som improvement to work optimally)

You can find more information and links at the Motion Homepage.

Known Problems

Version 3.0.7 and 3.1.10 currently have no known problems.

How do I install Motion?

Motion is distributed as source files that you must compile yourself. (There exists an old RPM file but it is completely out of date.)
You may run into some small problems when compiling with either MySQL or PostgreSQL support. No worries. See the speciel sections about the two later in this document.

For the experimental versions 3.1.10... read the speciel section about that at the end of this document as a supplement to this.

The short story is:

• Download the motion source files (distributed as tar'ed and compressed files). Place the file in a place of your own choice.
• Untar and uncompress the file to the place you want the program installed. Editor recommends placing the motion source file directory in /usr/local. If you do not have write access to the /usr/local directory (you are under the mercy of an ignorant system administrator with a severe case of paranoia) - you can install the program in a directory in your home directory. You will then need to read the next section about how to configure before you compile the program. Below is shown the exact commands using version 3.0.7 installed in /usr/local as an example.
  cd /usr/local
  tar -xvzf /path/to/motion-3.0.7.tar.gz   (replace /path/to with the actual placement of the tar.gz file)
  
• You will now have created a directory called motion-3.0.7. You can rename it to motion (mv motion-3.0.7 motion). I recommend creating a symbolic link to the current version. This way you can more easily experiment with different version simply by changing the link.
  ln -s motion-3.0.7 motion
• Now change to the new directory
  cd motion
• Run configure. You can start with the defaults. If you need to modify the installation parameters you can read the next section.
  ./configure
• Build the code
  make
• Install the code, manual page, etc
  make install
• Run the program. You may need to either modify the config file or add command line options. You will not get too far with the defaults. The command line is nice for quick experiments. But for normal use I recommend using the config file.
  motion

The configure script

Configure is script that you run to setup the build environment for the C-compiler. It generates the "Makefile" which the program "make" uses to compile and install the software.

To run configure your current directory must be the motion directory. You type
./configure
You can add the parameter ./configure --help to get help on the different switches.

This is walk through of the options. The configure script used is based on another configure scripts and contains some not very interesting switches.

Make

Not much to say about this. When you run make, all the C-source files are automatically compiled and linked. Just look out for error messages.
Make uses a file called "Makefile" which is generated by the "configure" script you just ran. If you have special needs you can manually edit this file. Next time you run configure a new Makefile will be generated and your changes are lost.

If you have run make before, you should run a "make clean" before running make again. This cleans out all the output files that were generated the previous time you ran make. On other words:
First time you build motion run configure, make, make install. If you need to build it again (to run with different configure options) run configure, make clean, make, make install.

Make Install

"Make install" simply copies all the nice files that were generated during the compilation/linking that make did.
In version 3.0.7 the following is done by make install.

Makes the directories (if they do not already exist): /usr/local/bin, usr/local/man/man1, /usr/local/etc, /usr/local/doc/motion-3.0.7, /usr/local/doc/motion-3.0.7, and /usr/local/examples/motion-3.0.7.

Copies the following files from the base motion directory (assuming the default PREFIX /usr/local was used when running configure - otherwise adjust to the actuals you chose)

• Executable binary "motion" to /usr/local/bin
• Manual page "motion.1" to /usr/local/man/man1
• Document files "CHANGELOG, COPYING, CREDITS, INSTALL, and README to /usr/local/doc/motion-3.0.7
• Example configuration files "motion.conf*" to /usr/local/examples/motion-3.0.7
• Configuration file "motion.conf" to /usr/local/etc

Note that the any existing files are overwritten. Pay attention to your configuration file motion.conf. You may not want this overwritten. Keep a copy in a safe place before you run "make install". Editor recommend renaming the motion.conf in the source code directory after the very first installation. This way you will not accidently overwrite the real motion.conf file.

Un-install

From the motion base installation directory you simply run make uninstall

And delete the base installation directory in /usr/local and any link pointing to it. If you have forgotten where you installed it or someone else did it for you, simply search for the files and directories starting with motion. If the filenames and the directories match the names described in the "Make Install" section of this document, you can safely delete them.

Additional Make Options

The make command can be run with severel options. make, make install and make uninstall has already been described above.

make clean deletes all the binary files (object files) and the motion binary generated by make. It also deletes temporary files and any jpg files that motion has saved in the motion source directory.
make distclean deletes the files: config.status, config.log, config.cache, Makefile, and motion.spec.
make updateguide fetches a frech new copy of this guide and place it in your motion source directory. Note that the pictures are not downloaded.
make dist performs make clean, make distclean and make updateguide in one single operation. 

Documentation

You have the following sources of information:
This document (you are lucky to have found it).
The author of the program has written a description of the technology behind motion.
The man page. After installation simply write man motion
The default motion.conf file that comes with the package.
Misc. document that comes with the package gives a few hints. When this is written the FAQ describes the wrong information about where motion searches for the motion.conf file.

Supported Hardware

Input devices: Here we are thinking about the cameras.
Motion supports video input from two kinds of sources.

Standard video4linux devices (e.g. /dev/video0). Motion has no drivers for cameras. Installing the camera itself is outside the scope of this document. But here are some nice links.

• Driver for USB Philips cameras (and more)
• BTTV Driver (capture cards). Part of many distributions now.
• OV511 based USB cameras are supported as standard by newer Kernels.

Network cameras (which are actually cameras with a built in web server that can be connected directory to your network).

• Axis Communications

Running Motion

Motion is invoked from the command line. It has no GUI. Everything is controlled from the command line and from config files. The editor recommend only using the config files as this is easier in the long run and much less confusing having all options in one place.

A few important definitions.

• A snapshot is a picture taken at regular intervals independently of any movement in the picture.
• A "motion" image or "realmotion image" shows the pixels that have actually changed during the last frames. These pictures are not very useful for normal presentation to the public but they are quite useful for testing and tuning and making mask files as you can see exactly where motion sees something moving.
• A normal image is the entire image taken by the camera.

The Config Files

The name of the config file must be 'motion.conf'. When you invoke Motion it will search for the configuration file called 'motion.conf' in the following order:

1. Current directory from where motion was invoked
2. Then in a directory called '.motion' in the current users home directory (shell environment variable $HOME). E.g. /home/goofy/.motion/motion.conf
3. The directory defined by the --sysconfdir=DIR when running .configure during installation of Motion
   (If this option was not defined the default is /usr/local/etc/)

If you have write access to /usr/local/etc then the editor recommends having only one motion.conf file in the default /usr/local/etc/ directory. Be careful if you run "make install" again. This will overwrite the motion.conf file that you have edited and experimented with for hours. Make sure to keep a copy in a safe place. Alternatively, copy the working file to the motion base install directory. Then make install will simply copy the same file back again.

Remember that motions looks for motion.conf in the working directory before $HOME/.motion and /usr/local/etc.
So if your current directory is the motion source directory then remember to 'cd' away from the motion directory before you start motion when you have your config files in $HOME/.motion or /usr/local/etc. Editor always renames the motion.conf file that comes with a new version to something else so that he does not fall into this trap.

If you have more than one camera you should not try and invoke Motion more times. Motion is made to work with more than one camera in a very elegant way and the way to do it is to create a number of thread config files. Motion will then create an extra tread of itself for each camera.
An option that is common to all cameras can be placed in motion.conf. (You can also put all parameters in the thread files but that makes a lot of editing when you change a common thing).

An option that is unique to a camera must be defined in each thread file.
For the 3.0 series of Motion the first camera is defined in motion.conf and the 2nd camera is the first thread file called from the motion.conf file.
For the 3.1 series of Motion the first camera is defined in the first thread file called from motion.conf. The 2nd camera is defined in the 2nd thread file called from motion.conf etc.

Any option defined in motion.conf will be valid for all cameras UNLESS they are defined in the thread config file for any camera.

If you want to enable a feature for one camera but not the other then it depends on the version of Motion.
In 3.0.X the motion.conf describes the first camera AND it is also the default values for the rest. So if you have 3 cameras and only camera 2 needs a specific option on, you must set it to off in motion.conf, ON on the first thread config file and OFF in the 2nd file.
In 3.1.X it is more simple and logical. Here you set the default value in motion.conf. And then you only need to define the opposite in each thread file where it is needed.

Motion reads its configuration parameters in the following sequence. If the same parameter exists more than one place the last one read wins.

1. Motion reads the configuration file motion.conf from the beginning of the file going down line by line.
2. If the option "thread" is defined in motion.conf, the thread configuration file(s) is/(are) read.
3. Motion continues reading the rest of the motion.conf file. Any options from here will overrule the same option previously defines in a thread config file.
   
4. Motion reads the command line option again overruling any previously defined options.

So always call the thread config files in the end of the motion.conf file. If you define options in motion.conf  AFTER the thread file calls, the same options in the thread files will never be used. So always put the thread file call at the end of motion.conf.

If motion is built without specific features such as ffmpeg, mysql etc then remove or comment out the options that belongs to these missing features. Do not set them to off. If you define options that are not compiled into the motion executable, it can give error messages.

Command Line Options

SYNOPSIS

motion [ -BCDhlmNpQw] [ -a seconds] [ -c changes] [ -d device] [ -E command]
[ -F file] [ -f nr] [ -G seconds] [ -g seconds] [ -i input] [ -L noise] [ -M address] [ -n norm]
[ -O command] [ -P device] [ -q quality] [ -S nr] [ -s widthxheight] [ -t target dir]
[ -u user:pass ] [ -U webcam_path ] [ -V device]

Config File Options

These are the options that can be used in the config file.  They are overridden by the command line!
All number values are integer numbers (no decimals allowed). Boolean options can be on or off (values "1", "yes" and "on" all means true and any other value means false).

Some configuration options may only be used if Motion is built on a system that has the matching software installed (cURL, MySQL, PostgreSQL and FFMPEG). If you do not have this software installed you should not have the matching parameters in the config file. Either remove the config option or comment it out with a leading "#".

These are the software packages and the matching config options to watch out for.

cURL (libcurl)
netcam_url, netcam_userpass

MySQL
mysql_db, mysql_host, mysql_user, mysql_password

PostgreSQL
pgsql_db, pgsql_host, pgsql_user, pgsql_password, pgsql_port

FFMPEG
ffmpeg_cap_new, ffmpeg_cap_motion, ffmpeg_timelaps, ffmpeg_bps

Signals (sent with e.g. kill command)

A signal can be sent from the command line by typing e.g. kill -s SIGHUP pid, where the last parameter is the process ID which you get by typing ps -ef | grep motion. The PID is the first on the list which is the parent process for the threads. (If you use a version of motion 2.6.3 or earlier, you must kill each individual process and start motion again).
Motion responds to the following signals:

Generating MPEG films Berkeley mpeg_encode

To use this feature you need to install the Berkeley mpeg_encode program.
The program is pretty old (1995) and there has been some problems with compiling the source code. There is a guy doing an exciting project called AMIDE. This project includes the mpeg_encode program and it seems that the author of AMIDE has polished the old mpeg_encode a little bit calling it 1.5c. The author has placed 2 versions. A binary only RPM for the Intel 386 platform and two RPMs with full source. I installed just the binary RPM from the AMIDE site and it worked fine. The binary RPM contains only two files: mpeg_encode itself which it installs in /usr/bin and a manual page. Motion looks for the mpeg_encode in the directory /usr/local/bin. So either move the binary to this place, or place a link to it OR use the "secret" config file option mpeg_encode_bin. Ie. to enable the feature you need the following entries in the motion.conf file.

# Use the Berkeley mpeg encoder 'mpeg_encode'
# Default: off
mpeg_encode on
mpeg_encode_bin /usr/bin/mpeg_encode

The last line is not included in the default config file. The default value is '/usr/local/bin/mpeg_encode' so if this is where your mpeg_encode is, you do not need to add it to your config file.

Important! Your target_dir option should be an absolute path (starting with /) when using mpeg_encode.

The feature itself works like this:

Everytime motion detects motion a jpg picture is stored. This happens at the framerate you have specified with the 'framerate' option (or at the interval set by the 'minimum_gap' option if different from zero). When the event is over (time defined by the 'gap' option) motion generates a small mpg film using mpeg_encode. This is important to notice when you test the feature the first time. You will have to wait the period defined by 'gap' before you see the mpg file on your disk. If you have used a small framerate or used the minimum_gap option the film is going to be over in a split second. For this feature to be useful you should let motion store pictures almost real time. To generate better films you can play with options like 'post_capture' which will take extra picture after a motion is detected to create better floating films and 'adjust_rate' which will try to generate a 25 fps film. To avoid your harddisk from getting full because a bird is hopping around on the lawn, there are two parameters you can use. 'jpg_cleanup' will delete all the jpg files once the mpeg has been generated. 'max_mpeg_time' limits the duration of an mpeg film to the number of seconds you specify.

Generating MPEG films with ffmpeg

The ffmpeg option can generate mpeg films very fast and "on the fly". This means that the mpeg film is growing each time motion is detected. With the Berkeley mpeg_encode feature the film is generated based on the saved jpg pictures. With ffmpeg the film is generated directly by motion. Note that when you build motion with ffmpeg (configure using --with-libavcodec=DIR) DIR must be the path to the directory containing libavcodec.a. If you install ffmpeg in /usr/local/ffmpeg then the directory is /usr/local/ffmpeg/libavcodec.
Some people on the Motion maling list have had trouble building the ffmpeg package because they did not have the NASM assembler package installed. So pay attention to this if you run into problems.

The ffmpeg_cap_new option generates a new film at the beginning of each new 'event' and appends to the film for each motion detected within the same event. The current 'event' ends when the time defined by the 'gap' option has passed with no motion detected. At the next detection of motion a new mpeg film is started.

The ffmpeg_cap_motion works like ffmpeg_cap_new but outputs motion pictures instead.

The ffmpeg_timelaps generates a picture at a constant framerate of 1 frame per minute. Gives your viewer the chance to watch the day pass by. Nice effect to film flowers etc closeup during the day. Note that this rate cannot be configured. Options like frame_rate, snapshot, gap etc has no impact on the ffmpeg timelaps function.
NOTE: In version 3.1.3 and forward this parameter is changed from a boolean (on/off) to an integer value that defines the timelap interval in seconds. Setting it to 0 disables it.

There is an option ffmpeg_bps. This sets the bits per seconds of the generated film. The higher value - the better quality - the bigger file. Experiment to get the desired quality/file sizes.

If you want to use this feature you can read about the FFmpeg Streaming Multimedia System

Since Motion versions 3.0.7 and 3.1.10, Motion now works with the current version 0.4.8 of ffmpeg which is the time of this document is the latest released version available at the ffmpeg website. Earlier you had to use an older version 0.4.6 of ffmpeg together with Motion but this is no longer the case.

Just download the ffmpeg and untar it to /usr/local/ffmpeg. Then it should be a simple matter of entering the ffmpeg directory and run the commands

./configure
make
make install

This creates the libavcodec library under /usr/local/ffmpeg/libavcodec and this is really all we need for Motion.

Mask file

In versions up to 2.6.3 the mask file must be in the ppm format (portable pixel map). Note that you must choose the BINARY format.
From version 2.9.9 the feature is changed to use a pgm format mask file (portable gray map). Note that you must choose the BINARY format.
The feature is simple. Create an image of exact the same size as the ones you get from your video device (camera). Make a purely white picture and paint the areas that you want to mask out black. You can also make gray areas where you want to lower the sensitivity to motion. Normally you will stick to pure black and white.
One easy method for generating the mask file is as follows.
You can just take a motion captured picture, edit it with black and white for the mask and save it as a pgm file.
If you cannot save in this format save as a grayscale jpg and then you can convert it to pgm format with

djpeg -grayscale -pnm [inputfile] > mask.pgm

(assuming you have djpeg installed - part of the jpeg lib package).

Note that the mask file option masks off the detection of motion. The entire picture is still shown on the picture. This means that you cannot use the feature to mask off an area that you do not want people to see.

Below are an example of a webcam picture and a mask file to prevent the detection cars in the street.

Normal picture. Notice the street is visible through the hedge.

Mask file (converted to png format so it can be shown by your web browser)

Using MySQL

You can use the MySQL database to register each file that is stored by motion. What is stored is the filename (full path), and the time.
You need to generate a new database with a name of your own choice. You must enter this name in the config file (mysql_db option). Select the new database in MySQL and create a new table "security" with the following fields:

• filename (char60) - Filename (full path)
• year (int) - year in the YYYY format
• month (int) - month as a number
• day (int) - day as a number
• hour (int) - hour as a number
• minute (int) - minute as a number
• type (int) - Type as a number. (I still need to find a complete list of all possible types. Saving normal motion pictures in jpg format is type 1).

You can create the table using the following SQL statement.

CREATE TABLE 
security (filename char(60) not null, minute int, hour int, day int, month int, 
year int, type int);

Remember to update grant table to give access to the mysql username you choose for motion.
Note that motion does not store the seconds so you have have many files saved with the same time stamp. To get the exact time you will need to extract that from the file name.

If you are having trouble when installing motion with MySQL support you may have the same problem as the editor of this document had on his first Linux machine.

Versions from 2.9.9 works with no problems when mysql installed as a Red Hat RPM where mysql is installed in the standard directories
Data files in /var/lib/mysql
Binary program files in /usr/bin
Libraries in /usr/lib/mysql
Daemon in /usr/sbin
Misc shared stuff in /usr/share/mysql
Headers in /usr/include/mysql
Manual pages in /usr/man/man1

When installing the generic binary from www.mysql.com the directory structure is different.

The structure of mysql is then (assuming installing undet /usr/local).
Base dir is /usr/local/mysql
Data files in /usr/local/mysql/data
Binary program files in /usr/local/mysql/bin/
Libraries in /usr/local/mysql/lib
Daemon in /usr/local/mysql/bin/
Misc shared stuff in /usr/local/mysql/share
Headers in /usr/local/mysql/include
Manual pages in /usr/local/mysql/man (though I believe the install script does copy them to a standard location)

The workaround for 3.0.7 is:

• Create a link 'mysql' in the directory /usr/local/include pointing to /usr/local/mysql/include

The Author recommends using an RPM when possible.

It would be too much to go into detail about how to setup and use MySQL. After all this is a guide about Motion. However here are some hints and links.

Setting Up a MySQL Based Website  A beginners guide from Linux Planet.
Webmonkey PHP/MySQL tutorial  Entertaining and easy to read.
The phpMyAdmin homepage. The best and simplest tool to use MySQL (editors opinion). Requires Apache/PHP.

Using PostgreSQL

Same/similar as for MySQL above.

There are the same potential installation as for MySQL. The workaround is the same.
Motion is looking for a header file called xxx/postgresql/libpq-fe.h where xxx is the path that gcc is searching for headers. Often PostgreSQL header files are installed either in a directory called pgsql or directly in /usr/include.
You can either change the motion source or create a symbolic link. Editor recommends the link method because then you do not have to think about it when you try new versions of Motion.

• First locate your file called libpq-fe.h (use the command 'locate libpq-fe.h)
• Create a symbolic link in the normal 'include' directory path called postgresql that points to the directory in which you found the libpq-fe.h file.
  Examples:
  libpq-fe.h is found in /usr/include: Create a link with the command ln -s /usr/include /usr/include/postgresql.
  libpq-fe.h is found in /usr/include/pgsql. Create a link with the command ln -s /usr/include/pgsql /usr/include/postgresql
• Run configure with ./configure --with-pgsql

Using the Webcam server

Motion has a mini (very very mini) http server built in. Each thread can have its own webserver. If you enable the webcam server (option webcam_port to a number different from 0) and you have threads you must make sure to include webcam_port to different ports or zero (disable) in each thread config file. Otherwise motion will crash because each webcam server will use the setting from the motion.conf file and try to bind to the same port.

Note: The webcam server feature requires that the option 'ppm' is set to off. (I.e. saved images are jpeg images).

These are the special webcam parameters.

• webcam_port - tcp port on which motion will listen for incoming connects with its http server.
• webcam_quality - quality setting for the jpeg files transferred over this connection (usually very low)
• webcam_motion - if set to 'on' Motion only sends pictures to the client when motion is detected. When 'off' Motion sends frames continuously
• webcam_maxrate - limit the framerate of the webcam.
• webcam_localhost (version 3.1.10 only). - limit the webcam access to localhost

The webserver generates a stream in "multipart jpeg" format. You cannot watch the stream with most browsers. Editor has tried Internet Explorer 6, Netscape 6.2 (windows) and Konquerer. Only Netscape on Linux can show the stream. For public viewing this is not very useful. There exists a java applet called Cambozola. Same tool is also used in the motion.cgi program that is available from the motion homepage. To enable the feature to a broad audience you should use this applet or similar.

To use the webcam feature with Cambozola is actually very simple.

1. Create a html page in which you will want the streamed picture.

2. In the html page include this code

<applet code=com.charliemouse.cambozola.Viewer
    archive=cambozola.jar width=400 height=300>
    <param name=url value=http://www.myurl.com:8081>
</applet> 

Where the width and height is the area of the applet. Adjust it to the same size or a little larger than your streamed image.
Replade www.myurl.com:8081 by the real url and port number of your choice.

3. In the same directory you place the cambozola.jar file. No need to build the java applet from source. Simply use the applet in the package. Or copy it from motion.cgi package. It is the same version.

4. Enable the feature in motion with these config lines.

############################################################
# Webcam:
############################################################
# Supply a live stream using multipart jpegs with a mini
# http deamon.
# Default: not set 
webcam_port 8081
webcam_quality 30
webcam_motion off
webcam_maxrate 4

Naturally adjust the settings to your preference. Maxrate and quality are important to limit the load on your server and link. Don't set them too high.

Using video capture cards with more inputs

Motion supports capture cards with more than more input. The inputs are controlled through the Video4Linux interface and are simply numbered. To find out which number means what you can experiment with a program such as Camstream. Here you can see which input has which number easily.
Some capture cards are specially made for surveillance with for example 4 inputs. Others have a TV tuner, a composite input (phono socket) and perhaps also a S-VHS input. For all these cards the inputs are numbered. The numbering varies from card to card so the easiest is to experiment for 5 minutes with a program that can show the videostream.
You set the input number with the config file option 'input' or the command line switch -i. The value must be an integer number. The default value is 8 and must normally be chosen for USB cameras that have no input channels.

Using the Round Robin feature

This feature is automatically activated where multiple threads are sharing the same video device. Each thread can then set different input channels or frequencies to change camera. These are the special Round Robin options:
- If multiple threads use the same video device, they each can capture roundrobin_frames number of frames before having to share the device with the other threads.
- When another thread wants to watch another input or frequency or size the first roundrobin_skip number of frames are skipped to allow the device to settle.
Note that in version 3.0.7 the two options are spelled roundrobing_frames and roundrobing_skib. From version 3.1.8 the spelling has been corrected to roundrobin_frames and roundrobin_skib. If you upgrade from 3.1.6 or earlier, remember to update your config files to the right spelling for these two features.

Using TV tuner card

TV tuner cards are used the same way as video capture cards except one of the inputs have one extra parameter which is the 'frequency' for the TV tuner. The value is the value that the bttv driver sends to the capture card. Use a program such as Camstream or xawtv to experiment with the values.

Using Tracing Control.

This is still at the experimental stage. Read more about it motion tracking page.

Using Drawtext

Drawtext is a new feature added to motion version 3.0.3. It enables you to taylor the on-screen display (OSD) to your taste and to add your own user defined text.

Motion has the following on screen display.

USERTEXT is a user defined text defined by the 'drawtext_user' option. If the option is not defined no text is displayed at this position.
CHANGES is the number of pixels that changed compared to the reference frame. Good for calibration and test. Maybe not so interesting for a greater public. The feature can be turned on or off by setting the 'drawtext_changes' option to on or off.
YYYY-MM-DD is the date in international date format - year four digits - month two digits - date. This cannot be changed.
HH:MM:SS is the time - hour : minute : second. This cannot be changed either.
FM is the frame number. If you save pictures faster than once per second or you generate mpegs with ffmpeg - it can be quite nice to identify each picture frame by a unique time stamp. Setting the option 'drawtext_shots' to on or off adds the frame number as '- two digits' after the time stamp.

The 3 options 'drawtext_user', 'drawtext_changes' and 'drawtext_shots' can be entered both in the motion.conf file and in each thread.conf file. E.g. you can set the 'drawtext_changes' and 'drawtext_shots' only in motion.conf setting the format of the display the same way for all cameras and then add unique 'drawtext_user" options in each thread.conf file. This way you can display "FRONT DOOR", "BACK DOOR" and "GARAGE" on 3 different cameras.

The user defined text can be the english alphabet - UPPERCASE letters only, the digits 0-9 and the characters "-" and ":". Use the underscore "_" as a space.

Using Video4Linux Loopback Device

The video4linux device is a Kernel module which installs itself as a video pipe. It has an input and an output. The module simply takes anything that comes on its input and send it out at the output. The purpose of this is to create a standard video4linux type video device that other programs can then use. You may now ask: "What do I need that for?".
Only one program can access a video device at a time. When motion is using a camera - no other program can access the same camera. But motion is made to be able to feed a video signal to the video loopback device. This way an additional program such as Camstream, Xawtv, a video stream server etc can watch the signal from a camera that motion uses already. What you see is not the live camera stream but the exact same picture that motion uses for detecting motion and the same pictures that are saved/streamed. You can also choose to see the "motion" type images where you see the pixels that are changing - live. Originally the video4linux pipe was used as an interface between Motion and a Webcam server. Since version 2.9 Motion has had its own webserver so this usage is no longer very relevant.

When you install the video loopback device it will create an input - for example /dev/video5 and an output - for example /dev/video6. You can then tell motion to "pipe" the video signal to the /dev/video5 and look at the pictures live using e.g. Camstream on /dev/video6. Camstream is "fooled" to think it is looking at a real camera.

Installing the video loopback device is not difficult. At least not when you have this document available.

First you must prepare your system for more video devices. You will need two extra devices for each video pipe that you want.
For example if you have 4 cameras they will probably run at /dev/video0, /dev/video1, /dev/video2, and /dev/video3. So you will need additional 8 video devices. This is easy to do.

mknod /dev/video4 c 81 4
mknod /dev/video5 c 81 5
mknod /dev/video6 c 81 6
mknod /dev/video7 c 81 7
mknod /dev/video8 c 81 8
mknod /dev/video9 c 81 9
mknod /dev/video10 c 81 10
mknod /dev/video11 c 81 11
Note that the video device number is the same as the last parameter given on each line.

You may need to set the ownership and permissions (chown and chmod) to be the same as the video devices that were already there.

Now you need to install the video loopback device.

• Download the latest video4linux loopback device (version 0.90 at the time of this document - distributed as tar'ed and compressed files). Place the file in a place of your own choice.
• Untar and uncompress the file to the place you want the program installed. Editor recommends /usr/local/vloopback.
  cd /usr/local
  tar -xvzf /path/to/vloopback-0.90.tar.gz
  
• You now have a directory called vloopback-0.90. You can rename it to vloopback (mv vloopback-0.90 vloopback). I recommend creating a symbolic link to the current version. This way you can more easily experiment with different versions simply by changing the link.
  ln -s vloopback-0.90 vloopback
• Now change to the new directory
  cd vloopback
• Build the code
  make
  There is a good chance that the make will not work and give you a long list of errors. To run make the following must be available on you machine.
• The kernel source files must be installed.
• The source files must be available at /usr/src/linux.
  E.g. the new Red Hat 7.3 does not have a link to the sources called linux. Instead there is a link called linux-2.4. This is easy to fix. Just create a link to the real source tree. Do not rename! Add a link using this command (replacing the kernel version number with the one you have on your machine)
  ln -s /usr/src/linux-2.4.18-4 /usr/src/linux
• Alternatively you can change the vloopback makefile so that the "LINUXSRC=/usr/src/linux" line is changed to the actual path. I recommend the link solution since this may solve other similar problems that you can get when installing other software.

When compiling on a newer Linux distribution you may get a warning about a header file malloc.h. To remove this warning simply change the header reference as suggested by the warning.
In vloopback.c you replace the line
#include <linux/malloc.h>
with the line
#include <linux/slab.h>

• Install the code you built as a Kernel module. There are two options: pipes should be set to the number of video loopbacks that you want. Probably one for each camera. The dev_offset defines which video device number will be the first. If dev_offset is not defined the vloopback module will install itself from the first available video device. If you want the cameras to be assigned to the lower video device numbers you must either load vloopback after loading the video device modules OR use the dev_offset option when loading vloopback. Vloopback then installs itself in the sequence input 0, output 0, input 1, output 1, input 2, output 2 etc. Here is shown the command for our example of 4 cameras and 4 loopback devices and the first loopback device offset to /dev/video4.
  /sbin/insmod /usr/local/vloopback/vloopback.o pipes=4 dev_offset=4
  When you run the command you may get a warning about tainting the Kernel. Just ignore this.
  You can choose to copy the vloopback.o file into a directory in the /lib/modules tree where the insmod/modprobe programs are already looking for modules. Then the command gets simpler (/sbin/insmod vloopback pipes=.....).
  If you want the loopback device to load during boot, you can place the call in one of the bootup scripts such as /etc/rc.d/rc.local. Vloopback should be loaded before you start motion.
• To activate the vloopback device in motion set the 'video_pipe' option in the motion.conf file. You can also view the special motion pictures where you see the changed pixels by setting the option 'motion_video_pipe' in motion.conf. When setting the video_pipe and/or motion_video_pipe options either specify the input device as e.g. /dev/video4. You can also set the parameter to '-' which means that motion will find the first vacant video loopback device input. If you have more than one camera you may want to control which loopback device each thread uses. Then you need to define the specific device name in motion.conf for the first camera and in each thread config file for the other cameras. If you set the video_pipe parameter to '-' in the motion.conf file and not setting it in the thread config files, motion automatically assign video devices in the same sequence as the threads are loaded. You can combine both video_pipe and motion_video_pipe but then naturally you will need twice as many pipes.
• Un-installing should be done with this command
  /sbin/modprobe -r vloopback 

Tuning Motion

Motion contains a number of features that helps you tune the settings of motion to the optimal. They are all described in the config file table above but this section will try to illustrate them a bit more and give some guides to how to tune.
The settings that are difficult to set are the settings that decides or influence when to detect motion. These are

• auto_brightness
• light_switch
• mask_file
• night_compensate
• noise_level
• switch_filter
• threshold

Special tuning options

• daemon off
  Setting daemon to off enables you to see the debugging texts and error messages that motion creates during operation. Motion writes every time it saves a file and you can see the motion detection value. Setting "always_changes" to on gives you even further information which will help you setting the noise_level/night_compensate/threshold parameters.
• always_changes
  You need to run motion in non-daemon mode so that you can see the text output on the terminal. This is very useful to see how many changes motion sees AFTER the noise_level filter has been used.
• locate
  Locate can be used as a normal feature showing you where in the picture the motion was detected. Even if you do not want this feature e.g. on a public webcam it is still useful as a debugging/tuning tool to set the parameters such as noise_level/night_compensate/threshold/mask_file parameters
• motion_video_pipe/video_pipe
  These feature enables you to see live what motion sees. Being a command line only program makes motion difficult to setup but also enables the program to run in the background using very few resources and it can easily be started up automatically when booting. The motion_video_pipe shows you the motion images that are generated when motion is detected. The video_pipe shows the normal picture.
• output_motion
  This feature help you to see exactly what the motion sees as motion in the picture. What you get is a green image that shows the pixels that changed. Motion has an simple but brilliant algorithm to detect motion where the previous pictures taken are used to create a reference picture. Motion detected are differences between the latest picture and the reference picture. The reference frame is generated from the past picture frames. For each new frame the older frames gets less and less 'weight'. This is why you see motion as a bright images and weaker ghost or shadow images.
• realmotion
  This option modifies the way that "output_motion" works. Normally output_motion shows only the pixels that were detected as changes in the latest picture frame. By setting 'real_motion on' the pictures shown contains all the pixels that were changed in the image. The pictures below illustrate the difference much better than words.

Normal picture frame

Motion type picture frame with realmotion set to 'off'

Motion type picture frame with realmotion set to 'on'
Note the dark area in the upper left corner which is the area masked off by the mask_file option.

In version 3.1.10 there are two new options 'noise_tune' and 'threshold_tune'. See special section below on version 3.1.10.

Experimental Version 3.1.10

The version 3.1 series are experimental version that are used to introduce and test new features. The 3.1 releases will not be as stable as the 3.0 series but this where the exciting new stuff is happening.
When it is written that 3.1.10 introduces a new feature it is meant compared to 3.0.X. It may actually have been in an earlier 3.1.X version. This guide always assumes that you use the latest stable or experimental version.

Installation of version 3.1.10

Known problems.
None at the moment.

The Makefile now has a very nice new feature: remote control by XML-RPC. The normal make and make install works as in version 3.0. There is now a new option make motion-control. This build the extra motion-control application that can control motion while it runs using the xml-rpc protocol.

To install and use motion-control and to be able to use xml-rpc you will need to install xmlrpc-c first. This is a library containing the xmlrpc functions to be used in C programs.

First, the xmlrpc stuff we need to install is located here: http://xmlrpc-c.sourceforge.net/downloading.php

Latest XMLRPC-C version is 0.9.10 (not 0.9.9 as their homepage suggests)
At Sourceforge you find the latest files.

http://sourceforge.net/project/showfiles.php?group_id=16847

XMLRPC-C from RPMs

If you use a distribution using RPM like Red Hat and many other all you need is to download and installed RPMs.
The two RPMs you need are here
http://prdownloads.sourceforge.net/xmlrpc-c/xmlrpc-c-0.9.10-1.i386.rpm?download
http://prdownloads.sourceforge.net/xmlrpc-c/xmlrpc-c-devel-0.9.10-1.i386.rpm?download
Additionally the two RPMs above need w3c-libwww installed. The RPMs for w3c-libwww comes with RedHat but are not installed per default.
For RedHat 9.0 they are on CD number 3. There are 3 RPMs: w3c-libwww-5.4.0-4.i386.rpm, w3c-libwww-apps-5.4.0-4.i386.rpm and w3c-libwww-devel-5.4.0-4.i386.rpm.
Previous versions of RedHat also have the 3 RPMs on the CDs but in earlier versions. They are probably also OK. The version should not be very critical.

XMLRPC-C from Source Files

For those that do not use distribution based on RPM the source tar.gz is here
http://prdownloads.sourceforge.net/xmlrpc-c/xmlrpc-c-0.9.10.tar.gz?download
And the Libwww can be downloaded from here
http://www.w3c.org/Library/

Follow the installation instructions from the websites of the XML-RPC-C and Libwww libraries.

After installation of xmlrpc-c you need to re-install motion going throught all the steps configure, make and make install

Additionally you need to build the motion-control application by simply running make motion-control

And then manually copy it to your /usr/local/bin directory or where ever you want the binary executable.

Motion.conf and thread.conf files.

Version 3.1.10 changes the concept of how thread files are read to something new and easier to use.
In version 3.0 the main thread controlled by motion.conf was always running the first camera.
For version 3.1.10 this has changed changed. Now the motion.conf file is still a global settings file which defines all options that are common to all cameras. If you only have one camera you can still just have the motion.conf file OR you can place the camera specific options in a thread config file. If you have more than one camera ALL cameras must now each their own thread config file.
The motion.conf file will still contain setting that are global to all cameras, but the minute you add 'thread' options to your motion.conf file you will need one thread file per camera.

Prediction Feature

The Motion Guide author has only very little experience with the feature. At the moment all Motion can do is report recognition as a "Best Guess: Prediction_name value" on the console. Ie. it cannot do anything in Daemon mode. Prediction is controlled by the new 'predict_enable', predict_description' and 'predict_threshold' config file options. This is really experimental code that needs some further work. Once the prediction is working there are many funny features it can be used for where motion can take actions/run scripts/save pictures depending on the kind of motion detected.

These are Jeroen own words for the feature.

prediction is a little experiment I have been doing over the past days...
Using 'description files' that describe a movement. Motion tries to predict what it was that triggered it. At the moment motion can distinguish between me sitting at the computer, me walking out of the room and me walking into the room.
A description is outputted for each event (.desc files). Motion will load files mentioned with 'predict_description' in the config file. These files have three lines: a line with the title, a line with the minimum values and a line with the maximum values. The current version is very rude..... try it, but don't expect to much

HOWTO make a description file:

1. wait for an event to create a .desc file e.g.:
   - walk in front of the camera
   - /2002/07/02/232300.desc is created
   - copy it to walk.desc
   - edit it: prepend a line with title 'walk
   - copy the existing line to get two identical lines
   - add 'predict_description walk.desc' to the config file
   - start motion
2. wait for some more events.
3. If you have similar events combine them:
   - ./combine walk.desc /2002/07/02/235500.desc
   - restart motion again.
   - Do this several times to get a description that matches better with new events.

The combine program that Jeroen talks about is included in the Motion 3.1.10 distribution both as a Intel-386 binary and as source. To build this little application from source simply run this command.

gcc -o combine combine.c

This creates the combine binary in the Motion directory.

Controlling Motion via xml-rpc

Motion version 3.1.10 has got a new exciting feature which is the ability to control Motion while it is running. Motion now has a built in http server called xmlrpc-httpd. This listens on a port specified by the new 'control_port' config file option. The control protocol is called xml-rpc. With Motion there is a small program that can be built and which can be used to control all the new control features of Motion. The installation of xml-rpc and the motion-control program is described above in the 'Installation of version 3.1.10 section'.

The motion-control program is easy to use. Run it without any parameters and it displays the help.

The command are shown below. Note the following. If you choose to set configuration parameters for thread 0, all threads will be changed. The individual camera threads are numbered 1,2,3....
Configuration parameters are simply named the same as in the motion.conf file. Parameters that are global and not set in a thread config file can only be read from thread 0. Trying to read a global only value from a camera thread will give no value back (same reply as if you ask for a non-existing value). Once you set a value for a thread other than 0 you can read it again from that thread.
The detection pause feature disables the saving of pictures, snapshots etc but does not stop the webcam server. The motion-control action and detection features do not work globally. I.e. 'motion-control action snapshot 0' does not generate snapshots for all cameras. One exception is 'motion-control action quit' which simply makes motion stop running (all processes quit).
The conf write feature overwrites both the motion.conf and the thread config files in a shorter format with less comments. If you like to keep your config files make sure to save copies of them before you run this control command. If you have changed parameters using the conf set command it is the changed values that get saved to the config files. Global (thread 0) parameters to motion.conf and individual thread values to the thread config files. Files are saved at the same location as they were read from overwriting the existing files.

The 'conf set [threadnr] [parameter] [value]' feature is very smart for trying tuning setting and for changing the user defined on screen display.

In motion.conf there is now a new option called 'control_localhost'. By setting this to "on" or "on" Motion can only be controlled via xml-rpc from the same machine on which Motion is running. If you need more refined access control use your firewall such as ipchains or iptables for it.

As mentioned above there is a config file option called 'control_port'. You should normally set this to 8080. If you need to set it to another port you will also need to change the port number defined in the motion-control source file. Look for the line #define MOTION_URL "http://localhost:8080". Same line can be changed to a real URL so that you can control Motion from a remote machine.

Automatic Threshold and Noise Tuning

Version 3.1.10 introduces two new features. Automatic threshold tuning and automatic noise tuning. These can be activated or deactivated by the config file options 'threshold_tune' and 'noise_tune'.
Both algorithms are new and may not yet be optimal. Try them and if they do not work, use the good old manual setting. We on the Motion mailing list are always interested in hearing your experience and especially any improvement you may have made to the source.

Webcam Localhost

A new option called 'webcam_localhost' has been introduced in 3.1.10. This is a security feature. When enabled you can only access the webserver on the same machine as Motion is running on. If you want to present a live webcam on your web site this feature must be disabled.

The "output_all" option

This new feature is not meant to be the normal mode of operation. Especially not if you have the output_normal or output_motion features enabled since it will keep on saving pictures on the disk and you will soon run out of disk space. All features are triggered like it was detecting motion all the time. It does all the normal actions that are done when motion is detected. It saves pictures on the harddisk, runs scripts, sends emails etc as fast as the frame rate of the camera. So it is probably a good idea to run with a low framerate when using this feature and to not use activate all the features that saves files on the disk. This parameter is default off and not included in the default motion.conf file that comes with 3.1.10.
The idea of this feature is that you can turn the feature on and off for a short period of time to test or to generate continuous mpeg films when needed. You can then use the motion-control program to turn the feature on a off. 

Improved Error Logging

From version 3.1.10 the error logging has been improved so that errors during daemon (background) mode are logged in the syslog.
The syslog is in most Linux systems the file /var/log/messages.

Improved Low CPU (low_cpu) Mode

From version 3.1.10 the 'low_cpu' mode is improved. Instead of being a fixed one frame per second mode the 'low_cpu' option is now an integer value giving the number of frames per second that motion captures from the camera when motion is not detected. A value of zero means that the low_cpu option is disabled.