PiKrellCam - OSD Motion Detect Program
Raspberry Pi Audio/Video Recording
PiKrellCam Image


PiKrellCam is an audio/video recording motion detect program with an OSD web interface that detects motion using the Raspberry Pi camera motion vectors. Audio can be optionally recorded if a USB sound card + microphone is connected. PiKrellCam's architecture is built around full featured internal motion detection without any dependence on an external motion detect program and it centralizes built in functionality for simplified web page interaction.


The pikrellcam program, source, scripts, and www web files are all installed under /home/pi in the pikrellcam sub directory and the program runs as the user pi. The goal is that the install be as localized as possible, however, the media directory may optionally be relocated to some other convenient location.

This video shows the PiKrellCam OSD:

And this is a motion detect video PiKrellCam recorded. It demonstrates the pre capture and post capture times which are both set to 5 seconds. Roadrunners don't really fly, but they can hop "fly" into a tree and then glide down from a tree branch which is what this roadrunner did:

Motion Detection

The Pi camera gives us vectors, so PiKrellCam processes vectors and does not treat them as if they were scalars. The interesting result is that detecting motion gets reduced to object position and movement detection.

The program makes a few passes over the vector array. First, as a noise filter for what I call sparkles, it removes vectors which pass the magnitude limit test but have no adjacent passing vectors. Then it builds composite motion region vectors and uses dot product to filter vectors for direction to get better final composite vectors. The direction filtering requires individual vectors to have the same direction as the overall composite vector to within a few degree spread. Failing vectors are rejects which are effective in identifying noisy frames. Final vector density tests must be passed before a motion event is considered valid and the end result is that motion detection can be sensitive and yet have good noise immunity. PiKrellCam can run with really low composite vector magnitude/count limits and a setting of 5/4 is reasonable.

However, to run with low settings there should be good placement of motion regions to avoid detecting wind blown trees or tall grass. With PiKrellCam this is a quick real time graphical motion region edit from the web page that can be done in minutes.

Motion detection is a tradeoff of distance, size and speed of an object, but to give you an idea of PiKrellCam's sensitivity, the roadrunner in the above emailed jpeg was about 40 feet away and has been detected farther away.. A slow walking animal like a cat might need to be a bit closer and human detection, depending on walking speed and angle across the field of view, can be over 120 feet with a 5/4 setting. This is with the camera resolution at 1080p narrow field of view. I think the immunity to sun/cloud light level changes is pretty good.


The install uses nginx as the web server because for it there is no special setup required for a web site outside of /var/www.

PiKrellCam is installed from a github git repository using the command line. The install is cloning the repository in the /home/pi directory and running the install script (an install for a user other than pi is possible):

cd /home/pi
git clone https://github.com/billw2/pikrellcam.git
cd pikrellcam
The install-pikrellcam.sh script installs needed packages and prompts for three things to configure: Any time you want to change how you configured these three configurations, just rerun the install script.

First Usage

Go to the PiKrellCam web page in your browser (omit the port number if it was left at default 80):


After the initial command line git clone to install the PiKrellCam distribution, subsequent upgrades to the latest version are a simple one button click and the OSD will inform you if there was anything upgraded.

Expand the front page System panel and click the Upgrade button.
After an upgrade to a new version PiKrellCam should be stopped and restarted from the System panel and the web pages should be reloaded to pick up any possible web page changes.


Read the Help web page in the System panel, the configuration files in ~/.pikrellcam and the files in the scripts directory to get an idea of what can be configured.

Configuration files in ~/.pikrellcam

Configuration Notes:

Building From Source

To build pikrellcam, a git clone of raspberrypi/userland is not required. If you modify the source, building a new pikrellcam binary is:
   $ cd ~/pikrellcam/src
   $ make

or if on a Pi 2,

   $ make -j4

and the resulting binary will be up one directory:

However, be aware that if you modify the web or C code source, you are effectively creating a git branch of the PiKrellCam repository and you will need to know about git so that you can manage that. You need to at least be aware that if you do the one button click upgrade from the web page any edits you have made to the source will be lost. But edits you have made to user configuration or script files will not be lost.

Internal Commands

Internal commands you put in the at-commands.conf file should be preceded by an '@' character but if echoed to the FIFO port, do not use the '@'. For example, here's some commands to put into the at-commands.conf if you wanted to timelapse something that goes on only in the mornings and evenings on weekdays:

Mon  7:30  "@tl_start 30"
Mon-Fri 7:30 "@tl_hold off"
Mon-Fri 9:00 "@tl_hold on"
Mon-Fri 17:00 "@tl_hold off"
Mon-Fri 18:00 "@tl_hold on"
Fri 18:00 "@tl_end"
So with that you will have a timelapse running off and on all week and will have a video produced in the videos directory Friday night (or Saturday morning if you are on a B+).

Many commands are for interaction with the web page, but some commands likely to be useful in at-command.conf are:

record [on|off]
tl_start period
motion_enable [on|off|toggle]
motion load_regions NAME
motion limits magnitude_limit count_limit
Scripts can also write commands to the FIFO and some commands are specific to a script. For example the timelapse-end script sends inform status that it is converting a mp4 to the FIFO. Later I intend to add a generalized inform interface so scripts can send information to display on the OSD.

PiKrellCam Files

The git clone should be done in /home/pi and creates the pikrellcam distribution directory:

    /home/pi/pikrellcam/                    # pikrellcam install root
                        pikrellcam          # pikrellcam executable
                        src/                # pikrellcam source directory
                        www/                # Web root in /etc/nginx/sites-available/pikrellcam
                        www/media           # Link to media_dir configured in pikrellcam.conf
                        scripts/            # User scripts for pikrellcam events or at commands
                        scripts-dist/       # Git managed scripts. Seeds the scripts dir
                        libkrellm/          # Local libraries needed for compiling pikrellcam

Running the install-pikrellcam.sh script creates or alters files:

    /etc/rc.local                           # Line optionally added to autostart pikrellcam
    /etc/nginx/nginx.conf                   # Line edited to disable access_log
    /etc/nginx/sites-available/pikrellcam   # Custom config installed for pikrellcam
    /etc/nginx/sites-enabled/pikrellcam     # link to sites-available/pikrellcam
    /etc/sudoers.d/pikrellcam               # Gives permission for pikrellcam to be run as
                                            #   user pi by the web server (user www-data).
    /usr/local/bin/pikrellcam               # Link to /home/pi/pikrellcam/pikrellcam

    /home/pi/.pikrellcam/                   # pikrellcam configuration files are created if
                        pikrellcam.conf     #   they don't already exist
                        at-commands.conf    # 
                        motion-regions.conf #

Running pikrellcam uses/creates these:
(mjpeg_dir and media_dir can be changed in pikrellcam.conf)

    /run/pikrellcam/                        # Directory for the mjpeg.jpg stream
                        mjpeg.jpg           # The stream jpeg file
    /home/pi/pikrellcam/media/              # Default directory: media_dir for media files
                        videos              # Fixed videos directory under media_dir
                        stills              # Fixed stills directory under media_dir
                        timelapse           # Fixed timelapse directory under media_dir