camguard - home surveillance system

     

 

camguard offers a home surveillance system for Raspberry Pi while using a connected motion sensor and camera. It can be used as a cli-application as well as a unix daemon.

Full documentation is available on camguard.readthedocs.io

Requirements

You need at least Python 3.7 to use this module.

Supported Platforms

camguard has been tested on Raspberry Pi 3 Model B Plus Rev 1.3 for the Platform Raspbian GNU/Linux 10 (buster) with Kernel 5.10.60-v7+ armv7l

camguard probably can run on platforms not listed above, but I cannot provide support for unlisted platforms.

Equipment

The following additional hardware is required:

• Joy-IT SBC-PIR BIS0001 Motion Sensor
• Raspi-Cam Electreeks E-RS015
• Raspi-Cam Case Electreeks Komplex I
• 1m/2m Electreeks FFC Ribbon-Cable AWM 20624 80C 60V VW-1
• Red notification LED with current limiting resistor (optional)
• Raspi T-Cobbler (optional)

⚠️ Be careful not to use a HC-SR501 Motion Sensor, it can be really hard to adjust the re-triggering on this sensor. Make your life easy by using SBC-PIR BIS0001 or similar.

Raspi-Setup

For the complete setup guide please see camguard.readthedocs.io

Installation and Usage

For installation on Raspberry Pi there are two options:

1. Installation with pip:

   $ pip install camguard[raspi]
   

2. Installation with available Makefile:

   $ make install
   

Usage

camguard can be used via cli or unix daemon, started by the available init system.

All available cli flags can be shown with

$ camguard --help

Example usage with unix daemon and systemd user unit ~/.config/systemd/user/camguard.service

[Unit]
Description=Camguard Test-Service

[Service]
Type=simple
ExecStart=/home/pi/.local/bin/camguard -c /home/pi/.config/camguard/settings.yaml --daemonize
TimeoutStopSec=3

[Install]
WantedBy=multi-user.target

--daemonize is used here without the --detach due to the usage with systemd. camguard can also be used without the init system by combining both flags.

Project details

• Project home: https://github.com/matt-hires/camguard
• Report bugs at: https://github.com/matt-hires/camguard/issues
• Git clone: https://github.com/matt-hires/camguard.git
• Documentation: http://camguard.readthedocs.io/

Building

This project comes with a GNU-Make Makefile which can be used for building and installation. Help for the available targets can be shown with:

$ make help

Developing

For local development it is not possible to use the same dependencies as on the raspi installation, therefore camguard offers different installation environments:

• dev - contains all necessary dependencies for local development and debugging
• raspi - includes all necessary dependencies for installation on a raspberrypi
• debug - only includes (remote-)debug dependencies which can be combined with the raspi environment (the dev env already includes this)

Installing an environment can either be done directly via pip ...

# install for local dev
$ pip install -e .[dev]

# install for raspi with remote debugging
$ pip install -e .[raspi,debug]

... or via Makefile:

# clean + check + install + docs-html
$ make all

# raspi + install-systemd + raspi-settings
$ make install

# raspi with debugging + install-systemd + raspi-settings
$ make install-debug

# development + dummy-settings
$ make install-dev

The Makefile also installs a fully functioning user systemd-unit with some default settings as well.

Sync changes to remote Raspberry Pi

For syncing changes to a remote raspberry pi the script sync_watch.sh can be used.

It requires usage of the following tools:

• inotifywait - a cli file watcher
• rsync - for syncing changes to remote pi
• ssh - for network file transfers

Adaption to host and sync directory can be done via the variables remote_host and remote_dir in the script, as well as additional excludes for the watcher and rsync:

# change to your raspi hostname and sync directory
remote_host="pi@raspberrycam"
remote_dir="/home/pi/pydev/camguard"

# sync excludes
rsync_excludes=("--exclude=venv/" "--exclude=*.log" "--exclude=**/__pycache__"
    "--exclude=.tox/" "--exclude=.git/" "--exclude=.python-version"
    "--exclude=pip-wheel-metadata/" "--exclude=src/*.egg-info/" "--exclude=.vscode/"
    "--exclude=**/*.tmp" "--exclude=settings.yaml" "--exclude=.coverage" "--exclude=htmlcov/"
    "--exclude=docs/_build" "--exclude=dist/")

# watcher excludes
inotify_excludes="(\.idea)|(.*~)|(venv)|(\.python-version)|\
(__pycache__)|(\.git)|(\.vscode)|(\.tox)|(camguard-.*)|\
(.*\.egg-info)|(settings\.yaml)|(\.coverage)|(htmlcov)|(docs)|(dist)"

Static Code Analysis

This project performs static code analysis check with deepsource.

Documentation

Build html documentation with sphinx, by using makefile goal:

$ make docs-html

License

camguard is released under the GNU General Public License v3.0