cd /home/pi
git clone https://github.com/billw2/pikrellcam.git
cd pikrellcam
./install-pikrellcam.sh

• Port number for the nginx web server to listen on. The default is 80, but an alternate non standard port number can be used in which case the PiKrellCam web page would be accessed with the URL:
       http://your_pi:port_number
• Auto start: if enabled a line will be added to /etc/rc.local so that pikrellcam will be auto started at boot. If this is not enabled, pikrellcam will need to be started from the web page or from a terminal after each boot.
• Password protection: if set a login will be required to access the PiKrellCam web pages.

First Usage

Media: Stills

Media: Loop

You can see the results of PiKrellCam's vector processing on the OSD by turning on the showing of Preset and Vectors. Watching this display will allow you to tune your configured vector limit values to your camera environment. To get a better look at the vectors, you can temporarily raise the mjpeg_divider value so the OSD will update more slowly.

Example Motion Detects

Notes:

• Image 2 fails the overall motion detect because PiKrellCam tries to be discriminating against noise. This is how it can run with very low magnitude and count limits and be good at detecting small animals. The low density distribution of vectors in region 2 that caused the failure can be typical of scenes with wind blown trees and grass.
• Image 4 shows a burst detect overriding a direction detect failure. The point to take from this is that if the burst count limit is set too low for a given camera environment, the burst detect method is likely to detect more noise than the direction detect method.
• Sparkles are camera motion vectors that have no neighbors and PiKrellCam considers them noise and excludes them from the composite vectors.
• The vector count status line will be shown if you set Setup->Config->Settings->Vector_Counts on and Show: Preset.
  Interpreting the vector count status line:
  • any:47 (17.1) This shows there was a frame total of 47 vectors excluding sparkles passing the magnitude limit test. So all of these vectors were clustered in a group of at least 2. The 17.1 count is an exponential moving average of the any count EXCLUDING any counts from a region when they were greater than the limit count. So the moving average measures background noise over sparkles. A burst count must exceed the average by the Burst_Count limit for a burst detect.
  • rej:22 There were 22 total frame vectors that passed the magnitude limit count but failed the direction compare test to their region composite vector. They were excluded from any region final motion direction detect test. They were not excluded from the burst detect count test.
  • spkl:52 (53.5) there were 52 vectors that passed the magnitude test but did not have any neighbors. So they were ecluded from any motion detect test. The sparkle moving average (53.5) is currently not used in motion detect testing.
  • confirming[4]:12 there was a direction detect but a positive confirm gap is configured so there is a count down in progress waiting for a confirm motion detect. The :12 shows the current vector count being tested for a composite vector. If there was no countdown in progress, the line would have shown counts:12. The counts on this line show when vector counts are greater than the limit count and a region composite vector is being tested for motion.
• Most medium to large sized motion events can be detected by both the direction and burst methods. To help evaluate the effect of changing configuration values, look in the log file to find out which detect method (one or both) happened for a particular motion video.

• Hardware PWM: If servos are connected to the hardware PWM GPIO pins, PiKrellCam can directly control the PWM signals and the only configuration needed is to set in pikrellcam.conf servo_pan_gpio and servo_tilt_gpio to the PWM GPIO pin numbers. So the pan/tilt or tilt/pan gpio pairs must be one of
      12,13   12,19   18,13   18,19
  Stop pikrellcam before editing ~/.pikrellcam/pikrellcam.conf to set the GPIO values. Then restart pikrellcam, reload the web page and you will have new buttons to control position presets and moving the servos.
• ServoBlaster: If your servos are connected to GPIOs that are not the hardware PWM pins you can use ServoBlaster. Set servo_pan_gpio and servo_tilt_gpio in pikrellcam.conf to the ServoBlaster servo numbers you are using and set servo_use_servoblaster to on.
  For this a separate install of ServoBlaster is required according to ServoBlaster documentation.
  Stop pikrellcam before editing ~/.pikrellcam/pikrellcam.conf to set the use servoblaster option and gpio values to ServoBlaster servo numbers. Then restart pikrellcam and reload the web page.

A preset is a camera position with a group of motion detect settings (vector magnitude / count and burst count / frames) and a set of motion regions. Clicking the preset up/down arrows moves to a new settings preset which single click loads a completely new set of motion detect settings and motion regions. So presets can be configured with motion detect sensitivities and motion regions appropriate for different weather or other conditions and quickly selected with single clicks.

Preset left/right arrow buttons are shown only if servos are configured and move the servos to configured position presets.

The Servo button and arrows are shown only if servos are enabled. Click the Servo button to cycle the servo arrow direction buttons through three modes: step by one, step by Move_Steps, and scan. When arrow buttons are in scan mode, clicking an arrow will step the servo continuously at Move_Step_msec rate until the arrow button is clicked again or the servo reaches a pan/tilt limit.

Preset behavior without servos:

• PiKrellCam considers the camera at a single fixed position and will never be off a preset. There will be only preset up/down arrows and no preset left/right or servo arrows. The pan/tilt graphics in the above image will not be shown.
• Any motion settings or regions edits will immediately apply to the currently selected settings preset (Preset up/down arrows).
• To create a new settings preset, click Setup->Preset->New and a new settings preset will be created with the existing motion settings and regions which can then be edited.

• If Setup->Config->Servo->Motion_Off_Preset is OFF, motion detection applies only if the servos are on a preset and if the servos are moved off a position preset with the servo arrow buttons then motion detection is put on hold. Set this option to ON if you want to have motion detected even if a servo position is off a preset.
• Presets cannot be created with different tilt positions at the same pan position.
• When the servos are on a position preset, a new settings for the position is created with Setup->Preset->New
• To create a preset at a new position:
  • Move the servos to the desired position and click
       Setup->Preset->New
    and you can then edit the settings and motion regions for the preset.
    Or you may move the servos off a preset and edit the settings or regions before creating the new preset and the OSD will warn you that you will need to create a new preset or else your edits will not be saved. If you move the servos back to an existing preset before creating a new one, your edits will be replaced with the preset settings.
  • Copy an existing set of settings from a position preset to a new preset at a new position.
    To do this, first move the servos to the existing preset you want to copy the settings from. Then, use the Servo arrows to move the camera to the new position (don't let the servo position fall on any other preset), and click
       Setup->Preset->Copy
    

Motion regions outline areas of the camera view that will be sensitive to motion and provides for excluding from motion detection areas such as wind blown vegetation. Motion regions may be added, deleted, resized or moved at each preset. Motion regions may also be saved by name and this provides a way to maintain a set of motion regions as a backup or a temporary. For example, a backup motion region by name can be loaded as an initial condition after creating a new preset. Or temporary motion regions by name can be loaded if you have a set of different motion regions you want to load to a preset on demand for evaluation. If a motion region is loaded by name it is automatically saved to the current preset unless you have servos and are off a preset.

The increment of a region resize or move can be coarse or fine by selecting/deselecting the Coarse Move select button. When the increment is fine, the adjustment units are single motion vectors. Motion vectors are 16x16 pixel areas of the video so the motion vector array overlayed on the preview display for a 1080p video setting will be 120x68.

A single region can be expanded to cover any motion area of interest, but if the area is large relative to the total frame size, there is one advantage to splitting the area into more than one region. Each region is independently checked for direction motion and there is one composite vector per region. If there are two smaller separated objects moving in the region the composite vector for the region will have a center away from the two objects and the motion test can fail the density check. However, in practice this might not be an issue because the motions may be sporadic or otherwise not synchronous so motion is likely to be detected regardless. But if in doubt, go ahead and split areas into multiple regions. This is why the default motion regions configuration has four regions spanning the width of the motion frame.

This should usually not be an issue, but the size of a motion region should not be so small that it cannot hold the number of vectors that is set for the vector limit count. For example, if the limit count is set to 20 a small region of 10x6 size out of a total frame size of 120x68 will hold three times this limit and should be fine. A safe rule of thumb when limit counts are set higher would be to keep dimensions of motion regions not much smaller than 1/8 of the total frame dimensions.

Motion burst detection considers the total frame composite vector so the total area of all motion regions compared to the burst limit count is the factor to consider.

If servos are not configured, there will be no Move or Copy buttons in the Preset group and there will be no Servo button in the Config group.

Preset

• Settings
  These values are part of a preset and editing them applies to the currently selected preset. If you have servos and are off a preset, editing these values can be done in anticipation of creating a new preset.
  • Vector_Magnitude - sets the minimum magnitude of a motion vector. Individual motion vector and region composite vector magnitudes less than this value will not be considered valid motion. Set the value lower to increase sensitivity to slower moving objects. Slow walking cats or people at a distance will probably require low settings of 7 or less while faster objects like cars or closer people can detect with higher settings. This value applies to composite vectors used for both direction and burst detects.
  • Vector_Count - sets the minimum count of individual motion vectors required for a region composite vector. Set the value lower for increased sensitivity to direction detects of smaller moving objects. A value of 4 or 5 can detect small animals at moderate distances. A very low setting of 2 or 3 can detect small animals at greater distances, but with increased risk of false detects. For detecting people at medium distances or cars, the value can be set from 10 on up. Burst detects of larger objects have a separate count requirement.
  • Burst_Count - sets the minimum count of individual motion vectors required for a frame composite vector burst detect. For a range of object sizes, burst detection will overlap direction detection and it may be difficult to observe the effect as this value is changed. If the camera view is noisy, the value probably should be adjusted higher, but if the view is normally quiet with well placed motion regions, the value can probably be left at a low value. For a detect, the total frame vector count must exceed the background count exponential moving average by the Burst_Count, and at least one motion region must pass a density test.
  • Burst_Frames - sets the minimum number of frames of sustained burst counts required for a burst motion detect. Frames are checked at a video_fps/mjpeg_divider rate. The Pi camera will occasionally produce "glitches" of motion vectors which would generate many false detects if Burst_Frames was 1, so the minimum is 2. A value of 3 should filter out most glitches, but setting the value to 2 gives the fastest detects of large objects which may pass quickly through the camera field of view. Set the value higher to decrease detection of large objects passing quickly through the field of view.
  • Zoom_Percent - is the percent width and height of the camera sensor used for imaging. Set the percent lower to digitally zoom in for videos and stills. Moderate zooming can tune the camera field of view at the expense of some resolution as fewer pixels may be used to convert to stills or videos. While viewing the web page preview, a larger zoom (lower percent value) magnifies the pixels and is useful for camera focusing.
    If a zoom value is selected, it is saved as part of the current preset along with the motion limit and motion region settings.
• Move: One
  You will have this button only if servos are configured.
  If the servos are moved off a preset, click this if you want to move the preset you were on to the current servo position.
• Move: All
  You will have this button only if servos are configured.
  If the servos are moved off a preset, click this if you want to move the preset you were on to the current servo position and move all the other preset positions by the same amount. If the camera installation is disturbed or serviced, this allows a quick adjustment for restoring position presets. The other presets may still need small adjustments if servo positioning is non linear. All presets cannot be moved if the move would move any preset past a servo position limit.
• Del
  If servos are not configured or if the servo position is on an existing preset, delete the current Settings. If servos are configured and the servo position is on a preset and the Settings are the last Settings for the preset, then delete the position preset unless it is the only existing position preset. There must always be at least one preset and you cannot delete down to zero presets.
• Copy
  You will have this button only if servos are configured.
  If the pan servo is moved off a preset, click this to create a new preset at the servo position which is initiallized by copying all of the preset settings (motion detect limits and regions) from the preset you were on into the new preset.
• New
  Creates a new preset. If servos are not configured or if the servo position is on an existing position preset, this will create a new Settings preset which can then be edited. If servos are configured and the servo position is not on an existing preset, then a new position preset is created with an initial single Settings.

Config

• Motion
  • Startup_Motion - set to ON for motion detection to be enabled each time PiKrellCam starts. Motion detection can be enabled from the web page or a script.
  • Confirm_Gap - for motion direction detects, require a second motion detect within this period of seconds before triggering a motion record event. This adds a level of noise rejection to motion direction detecting but may be set to zero to disable a second detect requirement if fast detection is desired. This setting does not apply to motion burst detects because the Burst_Frames setting provides a confirm time for that method.
  • Pre_Capture - seconds of video to record prior to the first motion detect event. This value should be greater than or equal to the Confirm_Gap. Pre capture does not apply when motion stills recording.
  • Event_Gap - number of seconds that must pass since the last motion detect before a motion event recording can end. When an Event_Gap period does expire without a new motion detect occurring, videos will end with an end time of the last motion detect time plus the Post_Capture time (but see Post_Capture). Set this higher for animals or walking people that may pause for periods of time before resuming motion. Set lower for active scenes where events are frequent and you want to bias towards shorter videos that capture more events separately.
  • Post_Capture - seconds of video that will be recorded after the last occurring motion event. This time must be less than or equal to the Event_Gap time because post capture time is accumulated in the circular buffer while the video is recording. An expiring Event_Gap time ends the video immediately and no more Post_Capture time can be accumulated. Post_Capture time does not apply when motion stills recording is enabled, so the last motion still captured will be for the last motion detect that extended the event gap and satisfied the Max_Motion_Stills_per_Minute constraint.
  • Video_Time_Limit - range is 0 - 1800 seconds (30 minutes) and is the maximum seconds of motion video that will be recorded after the first occurring motion detect. So the total video length max will be the Pre_Capture time + the Time_Limit. If this is set to zero, there will be no time limit enforced. This limit does not apply to manual recordings - see FIFO examples for that.
  • Motion_Stills_(no_videos) - set to ON to capture still images during a motion record event and a motion video will not be recorded.
  • Max_Motion_Stills_per_Minute - can be 1 to 60 stills per minute which sets a max still capture rate of 1 per minute to 1 per second. During motion record events, stills are taken at motion detects separated by at least this rate. So stills will not be taken at motion detects more frequently than the max still capture rate. However, all motion detects during the motion record event are written to the /run/pikrellcam/motion-events file.
  Note: Videos can be started only on key frame boundaries. When waiting for a motion event to start, PiKrellCam requests key frames from the camera once per second, so a Pre_Capture time setting of T will actually record somewhere between T and T+1 seconds. Also, if there is a new motion event immediately following a previous motion video end, there may not be the configured Pre_Capture time accumulated in the circular buffer and so the actual pre capture time will be less than what is configured.
• Video Res - selects the video resolution for motion and manual videos. Different resolutions may have different fields of view. So one reason for selecting 720p over 1080p would be to get a wider field of view. Resolutions will have either 16:9 or 4:3 aspect ratio.
• Still Res - selecting different resolutions gives different fields of view and aspect ratios.
• Settings
  • Check_Media_Diskfree - if set ON, when new motion or manual videos or stills/timelapse are recorded, delete oldest videos or jpegs so that the configured minimum Diskfree_Percent will be maintained on the media file system.
  • Check_Archive_Diskfree - if set ON, when media motion or manual videos are archived, delete oldest archived videos so that the configured minimum Diskfree_Percent will be maintained on the archive file system. This is useful when the archive is on a file system separate from the media videos. But if the archive and media directories are on the same file system, checking the archive has no or negligible effect since an archive operation is simply moving media videos and except for some directory structure overhead is not increasing disk usage.
  • Diskfree_Percent - maintain this minimum free percent on media and archive file systems when checking is enabled for those file systems by deleting oldest videos or stills/timelapse. This is always enabled for loop videos and overrides Diskusage_Percent.
  • video_bitrate - determines the size of a video and its quality. Adjust up if it improves video quality. Adjust down if you want to reduce the size of the videos.
  • video_fps - if set higher than 24 the motion detecting preview camera stream can drop frames depending on Pi model (GPU clock speed).
  • video_mp4box_fps - when zero, the mp4 boxing fps will track video_fps which is normally what you want. Set this to a non zero value different from video_fps for fast or slow motion videos. Or set to fractional values slightly different from video_fps to tune possible audio/video drift for longer videos.
  • mjpeg_divider - this value is divided into the video_fps value to get the preview jpeg rate. The preview is updated at this rate and it is the rate that motion vector frames are checked for motion.
  • still_quality - adjust up if it improves still jpeg quality. Adjust down if you want to reduce the size of still jpegs.
  • Vector_Counts - enable showing of vector count statistics when showing a Preset. This information may help when setting motion detect limits.
  • Vector_Dimming - sets a percentage dimming of the preview jpeg image when the Vectors display is enabled. This is to improve the contrast of the drawn motion vectors.
  • Preview_Clean - if set to OFF, whatever text or graphics that happen to be drawn on the preview jpeg at the time a motion preview save or thumb save occurs will also appear on the saved preview or thumb. This might help with some debugging, but is normally not desirable, so the option should be set ON.
  • Preview_Stall_Warning - default is ON. Enable showing a warning on the web preview if the preview jpeg encoder stalls when hitting GPU performance limits which cause preview frames to be lost. The solution is to lower video_fps until the stalls stop or at least become infrequent. This strangely seems more an issue (at least with current firmware) with the HQ camera on the Pi 4. With an HQ camera on a Pi 4 I needed to lower video_fps to 20 to avoid stalls, but on a P2 the HQ camera ran without stalls at video_fps 24. I've not seen this issue with V1 or V2 cameras.
    If this option is OFF, the warning is still enabled when showing preset information with the Show: Preset button.
• Loop
  
  • Startup_Loop - set to ON for loop recordings to be enabled each time PiKrellCam starts. Loop recording can be enabled from the web page or a script or an at-command.
  • Time_Limit - loop video length in seconds.
  • Diskusage_Percent - Limit disk space used by loop videos to this percent by deleting oldest loop videos as new ones are recorded. Loop diskusage checks cannot be disabled. If the free space on on the loop videos filesystem falls to the configured Diskfree_Percent then that will override this disk usage percent and allowed loop video disk usage can shrink below this value.
• Audio
  
  • Audio_Trigger_Video - set to ON to enable audio detects to be treated as motion detects to trigger motion videos.
  • Audio_Trigger_Level - sets the audio level to be met or exceeded for triggering a motion video.
  • Box_MP3_Only - if set ON and there are only audio triggers (no motion vector detects or external triggers) during a video recording, then do not include the h264 video in the MP4 boxing. The resulting recording will be a .mp4 boxed file containing only MP3 data and no video. Use this option if you want to save disk space for recordings that have audio but may not have interesting video.
• Servo
  The Servo menu is shown only if servos have been configured.
  • Motion_Off_Preset - if OFF, do not detect motion when the servo postion is off a preset. If configured motion regions are suitable for any servo position, this can be set ON if you do not want motion detection to be put on hold when a servo is manually moved off a preset.
  • Move_Step_msec - delay in milliseconds between servo steps when a servo is moved using the Servo arrow buttons. A servo step changes the pulse width of the servo control line by 1/100 of a millisecond (10 usec).
  • Preset_Step_msec - delay in milliseconds between servo steps when a servo is moved using the Preset left/right arrow buttons.
  • Servo_Settle_msec - delay in milliseconds before motion detection is taken out of its hold state after servos stop moving.
  • Move_Steps - number of steps to move when the Servo arrow buttons are cycled to the second step mode. The other step modes are single step and scan and are selected by clicking the Servo button. When in scan mode, the scan can be stopped by clicking the double arrow button again.
  • Pan_Left_Limit
    Pan_Right_Limit
    Tilt_Up_Limit
    Tilt_Down_Limit - Sets the servo limits.
  • Servo_Pan_Invert
    Servo_Tilt_Invert - Set these to ON or OFF to change the direction servos move when the direction arrows are clicked.

pi@rpi2: ~$ ls -lt pikrellcam/www
total 116
lrwxrwxrwx 1 pi       www-data    33 Nov 16 09:07 archive -> /home/pi/pikrellcam/media/archive/
lrwxrwxrwx 1 pi       www-data    25 Nov 16 09:07 media -> /home/pi/pikrellcam/media/

~/pikrellcam/media/videos
                  /stills
                  /thumbs
                  /timelapse
                  /archive

media_dir media
archive_dir archive

MOUNT_DISK=sda1

media_dir /media/mountdir

sudo mount -t vfat /dev/sda1 /media/mountdir -o rw,user,umask=0002

/dev/sda1   /media/mountdir    vfat    rw,user,umask=0002   0   0

If mounting a large CIFS filesystem the nounix,noserverino options may be needed in fstab so pikrellcam can make directories. Look at the example fstab entry forum raspberry pi forum