motion-notify

Motion Notify Version 1.0.3

Motion Notify 1.0 is a major release which is a significant rewrite from the previous 0.3 release. The latest version provides a platform which is more stable, more configurable and more extensible. Focus has been made on providing a platform that is easily extended by allowing developers to add new Actions and Detectors. See the section at the end of the readme if you want to know more about developing additional actions and detectors.

Overview

Motion Notify is a notification system for Linux Motion providing upload to Google Drive and email notification when you're not home.

Take an event, carry out some detections to see if you're home and then carry out a series of actions.

This allows you to carry out the following:

• Send an email when a motion is detected
• Upload an image to Google Drive while an event is occuring
• Upload a video to Google Drive when the event ends
• Send an email when the event ends with a link to the video
• Make a call to a REST API or HTTP endpoint when an event starts or ends
• Detect whether you're at home by looking for certain IP addresses on your local network and not send alerts if you're home
• Allows you to specify hours when you want to receive alerts even if you're at home
• Only receive alerts when you're not home
• Specify what you want to happen when each type of event occurs

Upgrades

If you're upgrading from an older version note the following:

• The arguments used by Motion Notify have changed so you will need to update the entries in /etc/motion/motion.conf
• Additional Python libraries are required so check that you have all the libraries stated in the install / config section this page
• The config file has changed a lot
• Follow through the install guide to ensure that everything works correctly

Events, Detectors and Actions

Motion Notify works on the concept of Events, Detectors and Actions.

• An Event is triggered when motion is detected
• Detectors check whether the system is "active" (typically whether you're at home or not)
• Actions are carried out as a result of an event (eg. when an event is triggered an email notification is sent and the image upload to Google Drive

The framework and configuration is designed to allow developers to easily develop and integrate their own Detectors and Actions

Event Action Rules

Each "Event Type" has a set of Event Action Rules allowing you to specify a different series of actions to be called at the start of an event than at the end of an event.

• Motion Notify allows rules to be configured stating what Actions should occur when an Event is triggered, taking into account whether or not the detectors show that the system is "active"
• Event Action Rules are specified in the config file in the format EVENT_TYPE = ACTION_CLASS:ALWAYS_OR_IF_ACTIVE,ANOTHER_ACTION_CLASS:ALWAYS_OR_IF_ACTIVE
• An example rule would be "on_picture_save = GoogleDriveUploadAction:always,DeleteMediaFileAction:always"
• This would mean that when a "on_picture_save" event occurs the file is upload to Google Drive and the local source file is deleted afterwards. Due to the "always" rule these actions will occur regardless of the system status
• Another example would be on_event_start = SmtpEmailNotifyAction:if_active
• This would mean that an email notification would be sent only if the detectors indicate that the system is active (see Detector Rules below)

Currently support Actions are:

• DeleteMediaFileAction - deletes the input file that was generated by the event
• GoogleDriveUploadAction - uploads the input file to Google Drive
• SmtpEmailNotifyAction - Sends an email using SMTP
• UrlInvokeAction - Makes an HTTP request to a REST service or website

Currently support Event Types are passed to Motion Notify via the command which is trigger by Linux Motion (or any other event trigger)

• on_event_start
• on_picture_save
• on_movie_end

Actions may be configured to trigger:

• always (ignore any detector status)
• if_active (only trigger if the detectors indicate that the system is active)

Detection Rules

• Detection Rules state what detectors should be called in order
• Currently supported detectors are:
• ArpBasedDetector - carries out a network scan for a MAC address (the IpBasedDetector is recommended over this)
• IpBasedDetector - Checks whether you're home by taking a list of IP addresses and pinging them to see if they are active
• TimeBasedDetector - Allows times of the day to be specified stating times at which the system should be considered active

Detection rules can be specified in groups to indicate whether they all detectors should indicate that the system is active or whether an individual detector can determine that the system is active

• Example 1: detector_rules = {TimeBasedDetector},{IpBasedDetector} would require that either TimeBasedDetector or IpBasedDetector indicate that the system is active
• Example 2: detector_rules = {TimeBasedDetector,IpBasedDetector} would require that both TimeBasedDetector and IpBasedDetector indicate that the system is active
• Example 3: detector_rules = {TimeBasedDetector,IpBasedDetector},{ArpBasedDetector} would require that both TimeBasedDetector and IpBasedDetector indicate that the system is active or ArpBasedDetector indicates that the system is active

IpBasedDetector

This detector checks whether you're at home by checking the network for the presence of certain devices by IP address.

It's highly recommended to use this rather than ArpBasedDetector which looks for MAC addresses. If you choose to use ArpBasedDetector you will need to run Motion Notify (and Motion) as root as it uses ARP - this isn't recommended.

IP detection uses ping so will run as a regular user.

Specify a comma separated list of IP addresses which will be checked - if any of those addresses are active then the system assumes that you're at home.

Note that mobile phones often don't retain a constant connection to the wireless network even though they show that they are connected. They tend to sleep and then just reconnect occasionally to reduce battery life. This means that you might get a lot of false alarms if you just use a mobile phone IP address.

Adding lots of devices that are only active when you're at home will reduce false alarms - try things like your Smart TV, desktop PC etc as well as any mobile phones. It's highly recommended to configure your devices to use static IP's to prevent the IP addresses from changing.

You can specify the timeout for ping requests in the config file - this forces ping to exit and assume that the device is offline rather than wait a long time for each response. If you're on a poor wireless connection or experiencing slow ping responses this should be increased.

The switches for ping are not consistent between operating systems. If you're running on a Debian based system such as Raspbian then ping -w2 127.0.0.1 causes a timeout of 2 seconds. On a BSD based system such as OSX you need ping -t2 127.0.0.1 so set the IpBasedDetector.ping_timeout_switch in the config file to -w or -t according to your operating systems ping command.

ArpBasedDetector

This detector checks the network for the presence of certain MAC addresses. It requires the script and Linux Motion to be run as root so it's use is only recommended when the IpBasedDetector can't be used (such as when static IP addresses are not possible).

• presence_macs = XX:XX:XX:XX:XX,YY:YY:YY:YY:YY
• Configuration is carried out using a comma separated list of MAC addresses.

TimeBasedDetector

This detector allows times of the day to be specified at which the system should always be considered active.

• Example configuration - time_ranges = 01:00-07:00,12:00-13:00
• This indicates that the system is always active between 01:00 and 07:00 and 12:00 and 13:00 so Actions will always be triggered during those hours

Installation

Install Python Libraries

sudo apt-get update
sudo apt-get install python-pip
sudo pip install PyDrive
sudo pip install enum34
sudo pip install oauth2client (may already be installed)
sudo pip install google-api-python-client (may already be installed)
sudo apt-get install python-openssl (may already be installed)

Clone the Git repo into the directory

cd /etc/
sudo apt-get install git
sudo git clone https://github.com/amdean/motion-notify.git
sudo chown -R motion.motion /etc/motion-notify

Create the log file and lock file and set the permissions

sudo touch /var/tmp/motion-notify.log
sudo chown motion.motion /var/tmp/motion-notify.log
sudo chmod 664 /var/tmp/motion-notify.log
sudo touch /var/tmp/motion-notify.lock.pid
sudo chmod 664 /var/tmp/motion-notify.lock.pid
sudo chown motion.motion /var/tmp/motion-notify.lock.pid

Update Configuration (see Configuration Section)

Change the File permissions

sudo chown motion.motion /etc/motion-notify/motion-notify.py
sudo chown motion.motion /etc/motion-notify/motion-notify.cfg
sudo chmod 744 /etc/motion-notify/motion-notify.py
sudo chmod 600 /etc/motion-notify/motion-notify.cfg

Create the entry in the Motion conf file to trigger the motion-notify script when there is an alert

sudo cat /etc/motion-notify/create-motion-conf-entries.txt >> /etc/motion/motion.conf
rm /etc/motion-notify/create-motion-conf-entries.txt

Motion will now send alerts to you when you're devices aren't present on the network

Configuration

SmtpEmailNotifyAction config

Enter the following configuration for emails:

• Google account details into the GMail section of the config file
  (this is just to send emails so you could setup another Google account just for sending if you're worried about storing your account password in the clear).
• Email address to send alerts to
• The URL of the folder you created in your Google account (just copy and paste it from the browser). This will be sent in the alert emails so that you can click through to the folder

TimeBasedNotification Config

• The hours that you always want to receive email alerts even when you're home

GoogleDriveUploadAction Config

Google drive authentication is done using a service account via key authentication. The service account is given access only to the folder you specify in Google Drive.

• Login to Google Drive and create a folder where images and video will be upload to
• Enter the ID of the folder into the "folder" field in the config file.
  If the URL of the folder is https://drive.google.com/drive/folders/0Bzt4FJyYHjdYhnA3cECdTFW3RWM then the ID is 0Bzt4FJyYHjdYhnA3cECdTFW3RWM.

Next you need to get some account credentials from the Google Developers console - this will allow motion-notify to upload files to Google Drive.

• Go to https://console.developers.google.com/
• From the "Select a project" dropdown at the top of the page choose "Create a project"
• Enter "motion-notify" as the project name (or anything else that you want to call it)

Once the project is created you'll be take to the project dashboard for that project.

• Go to APIs & auth > APIs > Drive API and click "Enable API"
• Go to APIs & auth > Credentials and choose "Create new Client ID" and select "Service Account" as the application type.

You'll receive a download containing a JSON file.

• Generate a new P12 key for the service account you just created using the button underneath the details of the service account.
• Save this file in the /etc/motion-notify directory and rename it to creds.p12.

The service account has an email address associated with it which will @developer.gserviceaccount.com. Copy that email address and enter it into the "service_user_email" field in the config file.

You now need to allow the service account access to your Google Drive folder.

• Go to the Google Drive folder where you want images and videos to be uploaded
• Click on the share icon
• Enter the email address of your service account and ensure that "Can edit" is selected.

Sub Folder Config

To Create Date Level Folders update the date format config. By Default this is set to roll each day. (See Permissions)

Permissions Config

Using the Service User OAuth (p12 file) means that the files are created and owned by the service user
When using folders that means we need to set the folder permission explicitly.
By Default the gmail/user from config is set as a writer. To add any other users set the read_users and write_users values in config. These values should be the email addresses of the users you wish to permission.

Usage

Motion Notify is designed to work with Linux Motion but can be used to handle other applications.

To run Motion Notify call motion-notify.py and pass in the following arguments:

• Full address of the Motion Notify config file - typically /etc/motion-notify/motion-notify.cfg
• Full address of an image or video file relating to the event (this will be uploaded to Google Drive etc) - such as /tmp/motion/02-20151101111812-00.jpg
• Event type - this must be one of on_event_start, on_picture_save, on_movie_end. Each Event Type has its' own set of Event Action Rules allowing you to specify what happens for each type of event.
• Timestamp - the time of the event
• Event ID - a unique String ID representing the event

If you're using Motion Notify with Linux Motion motion detection software you need the following lines at the end of your /etc/motion/motion.conf file:

on_picture_save /etc/motion-notify/motion-notify.py /etc/motion-notify/motion-notify.cfg %f on_picture_save %s %v %n
on_movie_end /etc/motion-notify/motion-notify.py /etc/motion-notify/motion-notify.cfg %f on_movie_end %s %v %n
on_event_start /etc/motion-notify/motion-notify.py /etc/motion-notify/motion-notify.cfg None on_event_start %s %v None

Troubleshooting

The first three steps to troubleshooting are:

• Check the log file: tail -fn 100 /var/tmp/motion-notify.log
• Set the log level to DEBUG - in motion-notify.py change logger.setLevel(logging.INFO) to logger.setLevel(logging.DEBUG)
• Call Motion Notify using one of the commands below

Trigger an "on_event_start" event

sudo /etc/motion-notify/motion-notify.py /etc/motion-notify/motion-notify.cfg None on_event_start 123 456 None

Trigger an "on_picture_save" event

sudo /etc/motion-notify/motion-notify.py /etc/motion-notify/motion-notify.cfg /home/pi/test.jpg on_picture_save 123 456 test.jpg

Developers

Motion Notify is designed to be extended. Create your own actions or detectors. Please contribute to the project by submitting any changes to https://github.com/amdean/motion-notify

Actions

Simply create a new Python module in the actions package, add the action to the EventActionRules section of the config file and that's it - no need to modify any code in the Motion Notify core.

Rules:

• Module name and class name must be the same with the same case (this is due to the way that introspection is used to invoke Actions)
• All actions must provide the following static methods:
• def do_event_start_action(config, motion_event): (Invoked when a on_event_start action occurs)
• def do_event_end_action(config, motion_event): (Invoked when a on_movie_end action occurs)
• def do_action(config, motion_event): (Invoked when any other action occurs)
• The DeleteMediaFileAction is a good example of very simple implementation
• The GoogleDriveUploadAction is a good example of a more complex implementation

Detectors

Simply create a new Python module in the detectors package, add the detector to the detector_rules line of the config file and that's it - no need to modify any code in the Motion Notify core.

• Module name and class name must be the same with the same case (this is due to the way that introspection is used to invoke Detectors)
• All detectors must provide the following static method:
• def detect_presence(config):
• This method returns True if the system should be considered active
• This may seem counter-intuitive as the IpBasedDetector detector returns True if it fails to detect any active IP addresses and False if it finds an active IP. An active IP indicates that someone is home so the system is not active and False is returned.

TODO

• Set Owner Of Date Folders to be the real owner and not the service user (Not sure this is possible)
• Add option to put Video and Pics in seperate folders

SSDP Installation

sudo pip install requests