Configuration

Configuration for camguard is done in a yaml-File with a configurable path, which will be set to $HOME/.config/camguard/settings.yaml by default. The parent directory path can be changed with the cli flag -c CONFIG_PATH (see Command Line Interface).

When installing camguard by using the available Makefile, a default configuration for Raspberry Pi is automatically copied to the default path.

Settings

For further explanation about component interaction please refer to Introduction.

Components

camguard uses component based settings where each of this components can be switch on, off or set into a dummy mode for testing, without using Raspberry Pi specific dependencies.

components:
    - motion_detector
    - motion_handler
    - file_storage
    - mail_client
    - network_device_detector

Motion detector (motion_detector)

A motion detector which calls a motion handler pipeline on detection.
The following settings are available for motion_detector node:
Implementation Type (implementation)
Required enumeration type for selecting the implementation of the motion detector component, available values are:
Type: enum
Default: raspi

  • raspi

  • dummy

Implementation Settings

The settings node of the selected implementation type, available values are:

  • raspi_gpio_sensor

  • dummy_gpio_sensor

Following settings are only available for raspi_gpio_sensor.

Raspberry Pi GPIO-Pin Number (gpio_pin_number)
Required General Purpose Input-Output (GPIO) pin number on Raspberry Pi where the motion sensor is connected.
Type: integer
Notification LED GPIO-Pin Number (notification_led_gpio_pin_number)
GPIO-Pin number for optional notification LED, which will be activated when a motion is detected.
Type: integer
Queue Length (queue_length)
The length of the queue used to store values read from the motion sensor. If your motion sensor is particularly “twitchy” you may want to increase this value.
Type: integer
Default: 1 (this effectively disables the queue)
Queue Threshold (threshold)
When the average of all values in the internal queue rises above this value, the sensor will be considered active.
Type: float
Default: 0.5 (which means half of the queue has to be considered active)
Sample Rate (sample_rate)
The number of values to read from the device (and append to the internal queue) per second.
Type: float
Default: 10.0
Example configuration for Raspberry Pi
motion_detector:
    implementation: raspi

    raspi_gpio_sensor:
        gpio_pin_number: 23
        notification_led_gpio_pin_number: 0 # default
        queue_length: 1 # default
        threshold: 0.5 # default
        sample_rate: 10.0 # default
Example configuration for Dummy usage
motion_detector:
    implementation: dummy

    dummy_gpio_sensor:
        # no value available

Motion Handler (motion_handler)

A component which handles motion detection, in the current implementation this is represented either by a Raspberry Pi- or Dummy-Camera.
The following settings are available for motion_handler node:
Implementation Type (implementation)
Required enumeration type for selecting the implementation of the handler component, available values are:
Type: enum
Default: raspi

  • raspi

  • dummy

Implementation Settings

The settings node of the selected implementation type, available values are:

  • raspi_cam

  • dummy_cam

Following settings are the same for both dummy_cam and raspi_cam.

Recording root folder path (record_path)
Root folder path where recorded files from the camera will be saved. Environment variables, as well as ‘~’, will be expanded.
Type: string
Default: '$HOME/.camguard/records'
Record count (record_count)
Defines how many pictures will be taken per motion detection.
Type: integer
Default: 15
Record interval seconds (record_interval_seconds)
Interval between each taken picture in seconds.
Type: float
Default: 1.0
Record file name format (record_file_format)
File name formatting for the recorded file. counter represents the current picture count, timestamp the current date-time. Both can be combined in a formatting template.
For further information about date-time formatting, see Date-Time format.
Type: string
Default: '{counter:03d}_{timestamp:%y%m%d_%H%M%S%f}_capture.jpg'
Example configuration for Raspberry Pi
motion_handler:
    implementation: raspi

    raspi_cam:
        record_path: '$HOME/.camguard/records' # default
        record_count: 15 # default
        record_interval_seconds: 1.0 # default
        record_file_format: "{counter:03d}_{timestamp:%y%m%d_%H%M%S%f}_capture.jpg" # default
Example configuration for Dummy usage
motion_detector:
    implementation: dummy

    dummy_cam:
        record_path: '$HOME/.camguard/records' # default
        record_count: 5
        record_interval_seconds: 0.5
        record_file_format: "{counter:03d}_{timestamp:%y%m%d_%H%M%S%f}_capture.jpg" # default

File Storage (file_storage)

A component which handles file storage of the recorded files from the motion handler.
The following settings are available for file_storage node:
Implementation Type (implementation)
Required enumeration type for selecting the implementation of the file storage component, by default this is a google drive storage implementation. Available values are:
Type: enum
Default: default (google drive storage)

  • default

  • dummy (selects a dummy/offline implementation of the file storage for testing purposes)

Implementation Settings

The settings node of the selected implementation type, available values are:

  • gdrive_storage

  • dummy_gdrive_storage

Following settings are only available for ``gdrive_storage``.

Upload folder name (upload_folder_name)
The name of the upload folder in the gdrive root.
Type: string
Default: 'Camguard'
OAuth token path (oauth_token_path)
Folder path for saving Google-OAuth token.json file.
Type: string
Default: '.'
OAuth credentials path (oauth_credentials_path)
Folder path for loading Google-OAuth credentials.json file.
Type: string
Default: '.'
Example configuration for GDrive File Storage
file_storage:
    implementation: default

    gdrive_storage:
            upload_folder_name: 'Camguard' # default
            oauth_token_path: "~/.config/camguard"
            oauth_credentials_path: "~/.config/camguard"
Example configuration for Dummy usage
file_storage:
    implementation: dummy

    dummy_gdrive_storage:
        # there are no specific settings for this node

Mail client (mail_client)

Component which enables mail notification after motion motion is detected and handled by the motion handler.
The following settings are available for mail_client node:
Implementation Type (implementation)
Required enumeration type for selecting the implementation of the mail client, by default this is a generic SMTP Mail Client implementation.
Type: enum
Default: default (SMTP mail client implementation)

  • default

  • dummy (selects a dummy/offline implementation of the mail client for testing purposes)

Implementation Settings
There is no dedicated settings node for the mail client, the settings of the selected implementation type reside inside the mail_client node.
Username (username)
SMTP username for mail server authentication.
Type: string
Password (password)
SMTP password for mail server authentication. This is currently not encrypted.
Type: string
Sender mail (sender_mail)
The sender mail address.
Type: string
Receiver mail (receiver_mail)
The address of the mail recipient.
Type: string
Hostname (hostname):
Mail server hostname
Type: string
Example configuration for SMTP Mail Client
mail_client:
    implementation: default

    username: 'my-mail-user'
    password: 'my-user-password'
    sender_mail: 'user@mail-domain.com'
    receiver_mail: 'recipient@gmail.com'
    hostname: mail-domain.com
Example configuration for Dummy usage
mail_client:
    implementation: dummy

    username: 'my-mail-user'
    password: 'my-user-password'
    sender_mail: 'user@mail-domain.com'
    receiver_mail: 'recipient@gmail.com'
    hostname: mail-domain.com

Network Device Detector (network_device_detector)

Component which checks continuously if a device can be found on the network by using the configured binary and search configuration. If any of the configured devices is found on network, motion handler will be disabled.
Implementation Type (implementation)
Required enumeration type for selecting the implementation of the network device detector component, available values are:
Type: enum
Default: default

  • default

  • dummy (selects a dummy/offline implementation of the network device detector for testing purposes)

Implementation Settings

The settings node of the selected implementation type, available values are:

  • nmap_device_detector

  • dummy_network_device_detector

Following settings are only available for ``nmap_device_detector``.

IP Addresses (ip_addr)
The IP Addresses from the network device, which should detected
Type: list[str]
Interval Seconds (interval_seconds)
The detection interval in seconds
Type: float
Example configuration for nmap Device Detector
network_device_detector:
    implementation: default

    nmap_device_detector:
        ip_addr:
            - '191.168.0.1'
            - '191.168.0.2'
        interval_seconds: 4.0
Example configuration for Dummy Device Detector
network_device_detector:
    implementation: dummy

    dummy_network_device_detector:
        # there are no specific settings for this node

Configuring Google-OAuth for Google-Drive

To enable the file storage for google-drive usage (see :ref:’file-storage-label`), it’s necessary to configure google-oauth authentication for your google account following these steps:

  1. Create a Google Cloud Platform Project

  2. Enable Google-Drive API

  3. Create access credentials

    1. Configure OAuth consent screen. ⚠️ Take care to not configure a logo/icon for the project, otherwise you’ll have to verify your production state. [1]

    2. Set Application Type to Desktop

  4. Download client secret json and rename it to credentials.json

  5. Copy credentials.json to ~/.config/camguard or configure OAuth credentials path (oauth_credentials_path)

Footnotes

Example configurations

Sample configuration for Raspberry Pi (including comments and optionals)
  1components:
  2    - motion_detector # mandatory
  3    - motion_handler # mandatory
  4    - file_storage
  5    - mail_client
  6    - network_device_detector
  7
  8# motion detector settings node
  9# type: node
 10# required: yes
 11motion_detector:
 12    # implementation type for camguard equipment
 13    # type: enumeration
 14    # required: no
 15    # values: [raspi, dummy]
 16    # default: raspi
 17    implementation: raspi
 18
 19    # implementation settings node
 20    # type: node
 21    # required: yes
 22    # values: [raspi_gpio_sensor, dummy_gpio_sensor]
 23    raspi_gpio_sensor:
 24
 25        # raspi gpio pin number where motion sensor is connected
 26        # type: integer
 27        # required: yes
 28        gpio_pin_number: 23
 29
 30        # raspi gpio pin number for a optional notification led
 31        # type: integer
 32        # required: no
 33        # default: 0, which means it is disabled
 34        notification_led_gpio_pin_number: 16
 35
 36        # The length of the queue used to store values read from the sensor.
 37        # This defaults to 1 which effectively disables the queue. If your motion
 38        # sensor is particularly "twitchy" you may wish to increase this value.
 39        # type: int
 40        # required: no
 41        # default: 1, which disabled the queue
 42        #queue_length: 0
 43
 44        # When the average of all values in the internal queue rises above this value,
 45        # the sensor will be considered "active"
 46        # type: float
 47        # required: no
 48        # default: 0.5, which means half of the queue has to be considered "active"
 49        #threshold: 0.5
 50
 51        # The length of time to wait between retrieving the state
 52        # of the underlying device.
 53        # Defaults to 0.0 indicating that values are retrieved as fast as possible.
 54        # type: float
 55        # required: no
 56        # default: 0.0
 57        #sample_wait: 0.0
 58
 59# motion handler settings node
 60# type: node
 61# required: yes
 62motion_handler:
 63    # implementation type for camguard equipment
 64    # type: enumeration
 65    # required: no
 66    # values: [raspi, dummy]
 67    # default: raspi
 68    implementation: raspi
 69
 70    # implementation settings node
 71    # type: node
 72    # required: no
 73    # values: [raspi_cam, dummy_cam]
 74    raspi_cam:
 75        # path where files should be saved, '~' and env variables will be resolved
 76        # type: string
 77        # required: no
 78        # default: "$HOME/.camguard/records"
 79        # record_path: "$HOME/.camguard/records"
 80
 81        # picture count per motion detection
 82        # type: integer
 83        # required: no
 84        # default: 15
 85        record_count: 15
 86
 87        # interval between taking pictures in seconds
 88        # type: float
 89        # required: no
 90        # default: 1.0
 91        record_interval_seconds: 1.0
 92
 93        # file name format where,
 94        # counter = 3 Digit Number from 1..record_count
 95        # timestamp = current date format
 96        # type: string
 97        # required: no
 98        # default: "{counter:03d}_{timestamp:%y%m%d_%H%M%S%f}_capture.jpg"
 99        record_file_format: "{timestamp:%y%m%d_%H%M%S%f}_capture_{counter:03d}.jpg"
100
101# file storage settings node
102# type: node
103# required: yes
104file_storage:
105    # implementation settings node
106    # type: node
107    # required: yes
108    # values: [gdrive_storage, dummy_gdrive_storage]
109    gdrive_storage:
110        # name of the upload folder in gdrive root
111        # type: string
112        # required: no
113        # default: "Camguard"
114        #upload_folder_name: "Camguard"
115
116        # root folder path for saving google oauth 'token.json'
117        # type: string
118        # required: no
119        # default: "."
120        oauth_token_path: "~/.config/camguard"
121
122        # root folder path for loading google oauth 'credentials.json'
123        # type: string
124        # required: no
125        # default: "."
126        oauth_credentials_path: "~/.config/camguard"
127
128# mail notification settings node
129# type: node
130# required: yes
131mail_client:
132    # switch mail client to dummy/offline mode (simulate mail sending)
133    # type: enumeration
134    # required: no
135    # values: [dummy, default]
136    # default: default
137    #implementation: dummy
138
139    # username for smtp authentication
140    # type: string
141    # required: yes
142    username: myUser
143
144    # password for smtp authentication
145    # type: string
146    # required: yes
147    password: myPw
148
149    # sender mail address of the notification mail
150    # type: string
151    # required: yes
152    sender_mail: sender@mail.com
153
154    # receiver mail address of the notification mail
155    # type: string
156    # required: yes
157    receiver_mail: receiver@mail.com
158
159    # mail server hostname
160    # type: string
161    # required: yes
162    hostname: my.mail.com
163
164# automatically disable motion detection when configured device is found in network
165# type: dict
166# required: no
167network_device_detector:
168    # switch network device detector to dummy/mode (simulate detection)
169    # type: enumeration
170    # required: no
171    # values: [dummy, default]
172    # default: default
173    #implementation: default
174
175    # implementation settings node
176    # type: dict
177    # required: yes
178    # values: [nmap_device_detector, dummy_network_device_detector]
179    nmap_device_detector:
180        # the ip address to detect on the network
181        # type: string
182        # required: yes
183        ip_addr:
184                - '192.168.1.1'
185                - '192.168.1.2'
186
187        # the detection interval in seconds
188        # type: float
189        # required: yes
190        interval_seconds: 4.0
Sample configuration for development-/dummy-usage
 1components:
 2    - motion_handler
 3    - motion_detector
 4    - file_storage
 5    - mail_client
 6    - network_device_detector
 7
 8motion_handler:
 9    implementation: dummy
10    dummy_cam:
11        record_count: 5
12        record_interval_seconds: 0.5
13
14motion_detector:
15    implementation: dummy
16
17file_storage:
18    implementation: dummy
19
20mail_client:
21    implementation: dummy
22    username: camguard # hard-coded for dummy usage
23    password: dummy # hard-coded for dummy usage
24    receiver_mail: dummy-receiver@camguard.at # hard-coded for dummy usage
25    sender_mail: dummy-sender@camguard.at # hard-coded for dummy usage
26    hostname: localhost
27
28network_device_detector:
29    implementation: dummy