VisionSphere: Camera Motion Detection for Raspberry Pi

A simple camera motion detection system for Raspberry Pi. Definitely written with Aussie's in mind (although it could be modified to be used in other countries). The main motivation behind writing this was to monitor property and wildlife in a remote NSW property.

Back in 2018 (6 years ago), I wrote a simple image motion detection system to help monitor and protect a remote off-grid cabin I have on a southern NSW rural family property. First, I had to build an internet connection - which is another entire story - but in 2013, before Starlink and such were available, my brother and I built a mountain top 3/4g Wi-Fi Solar transponder to provide connectivity from a mobile tower 30km away. Once we had internet - I started to add devices.

Whilst I put some store-bought home automation systems online, when it came to photo imagery - I wanted to be in total control over that (and wanted to do that myself). The motion detection system that I built was based on a combination of Python programs running on a camera-equipped Raspberry Pi Zero that communicated with some server-side PHP. I have relied on this system for more than 6 years. It's not perfect but has worked incredibly well and has even helped save my off-grid cabin from burning down by detecting nearby fires outside in the NSW 2019 Currowan fires (which emailed me whilst I was overseas and allowed me to alert the NSW RFS after some frantic international phone calls). Now that I have recently retired, and moving on to other more complex Raspberry Pi camera projects, I have decided to clean up the code base and make it Open Source.

The main philosophy behind this motion detection application is to compare consecutive image frames from an image stream from a Raspberry Pi camera and do a simple vector-squared pixel difference comparison. Because I wanted to only use Raspberry Pi Zero - I didn't want to try to wrangle any complex imagery software. I wanted to keep things as absolutely minimalist and simple as possible. So I wrote the software based on simple image frame difference comparison.

But it was a learning curve and I did learn over the years that just checking 2 consecutive frames isn't quite adequate. In the end - I found that comparing 3 consecutive image frames all to each other was the best approach I could achieve that balanced performance and reliability. This was the most reliable detector of actual motion in front of the camera I could do whilst keeping everything very simple.

Now, the entire approach is to use a periodic client-side push (or poll) so the cameras can retrieve activity or configuration instructions and possibly impose certain limits. This means a server needs to be in the equation for the build. The reasons for this are complex and numerous. In summary, some of the major reasons are;

1. Over mobile broadband connected Pi's, it is not possible to make an inbound connection (in Australia) as these are non-addressable IP addresses and Australian Service Providers don't permit such inbound connections.
2. By having a server in the mix, I can do various things such as limit the motion detection imagery sent per day, resend a camera config to the Pi's, request imagery, and perform other system tasks (such as reboot, wifi scan, etc).
3. By having a server I can minimise network traffic (which was important to me over mobile broadband) by checking and not sending a potential email storm from a poorly configured or wind-affected camera or when there are no active subscribers.
4. Importantly, I can remotely tune the motion detection sensitivity and weather station information settings. So, whilst I cannot strictly log on (ssh) to the Pi remotely, I have a fair degree of control over them remotely.
5. By using a periodic short polling approach - my application is much more scalable than if I wrote it to use dedicated long held http streams connection and also this means I didn't need specialised client, server or router configurations. I wanted to keep things simple and scalable.

To get up and running with my code base, you will need;

• At least 1, camera equipped, Raspberry Pi. A Raspberry Pi Zero W or Raspberry Pi Zero 2 W is ideal
• A web server that can serve PHP files. Can be an intranet web server on your local network but if your Pi will be deployed to remote locations then your web server will need to be public. cPanel web hosting services are ideal.
• The complete code base can be downloaded here or from my GitHub repo.

Source: https://harrishudson.com/fires/

I basically have all the build instructions documented under this recently created repo. I have written this to make the build as simple as possible and to progressively build up your server configuration and then your client side environments (Pi's).

In summary, the build steps are as follows;

Server:

• Create a directory on your web server for this application
• Copy files under the repo server directory to this directory on your web server
• Lockdown directories by way of editing .htaccess files or similar for your web server. Some directories should not be publicly accessible
• Setup the conf/config.ini file with your; application name (optional), server base URL endpoint, authentication key hash, and server email address.

Client:

• Build your Raspberry Pi using the Legacy code base. The simplest way to do this is by using the Raspberry Pi Imager. However, there may be cases where that is inadequate and a full manual headless build and burn is needed - see the documentation in that case.
• Install dependent packages such as ffmpeg and Speed Test applications on your Pi.
• Copy files under the repo client directory to your Pi.
• Setup watchdog (optional).
• Setup the config.ini file with your; server base URL endpoint, authentication key (free text), camera name (optional), and any camera-specific motion settings such as image size, orientation, frame rate, and recording duration.
• Set up the Linux crontab scheduler entries.
• Reboot.

Now; if everything is set up correctly - first, add your email as a subscriber then - fingers crossed once your Pi reboots - hopefully from out of the ether - an email will emerge with your rPi camera startup and a photo image!

If you received that email – your system is working! You can then follow the links in the email to log on to the server and modify your Pi's configuration, etc. Please refer to the server Application User Guide for help with the web portal and how to link in BOM weather station wind observations, etc.

That's the end of this project description and my story. I hope this can be of some use in your project. Thank you Core-Electronics for considering my project and your fantastic tutorials and guides. I totally depended on those guides and tutorials in the early days to get me started using a headless Raspberry Pi Zero back in 2018 - and built my systems up based on what I learned from there!

Some screenshots of from my Legacy System before rewriting it to a public repo. This is an example of the email the system sends - NOTE this has been heavily redacted;

Here is 1 email received during the 2019 fires;

From: [email protected]

Date: 13 December 2019 at 3:26:03 pm GMT-8

To: [email protected]

Subject: cabin - Motion Detected

Motion Detected

Motion DetectedSent to 2 Subscribers (max 8)

Cam Description: cabin
Cam IP Address: XXXX
Score Threshold: 200 total pixel diffs.
Score Sensitivity: 21 single pixel diff.
Delay between captures: 60 seconds.
SCORE value: 219(1,2),2432(1,3),2419(2,3)
Pi Core Temp: 54.1'C
BOM ID: IDN60801
BOM OWS: 94927
Stop when Wind/Gust Above: 13 km/h
Last Weather Poll message: Issued at 10:12 am EDT Saturday 14 December 2019
Last Weather Name: Braidwood
Last Weather Recorded at: 14/10:00am
Last Weather Wind: 6 km/h
Last Weather Gust: 11 km/h
Last Config Poll: 2019-12-13 23:21:33.196830
Uptime: 23:25:27 up 5:58

Please check - Movement Detect Photos will NOT be sent if;

1. Movement Detection is Stopped
2. Score is Below Score Threshold
3. Wind or Gust is above Wind Stop Speed, or
4. Your photo limit for today is reached (16/16)

Adjust Camera Config (Request Photo)

Todays photo limit: 6/16 Reset

Do Not Disturb for remainder of today

Unsubscribe

Here is another email from my Legacy System during the fires (NOTE this has been heavily redacted);

From: [email protected]

Date: 17 December 2019 at 3:08:03 pm GMT-8

To: [email protected]

Subject: shed - Photo Requested

Photo Requested

Sent to 2 Subscribers (max 8)

Cam Description: shed
Cam IP Address: XXXX
Score Threshold: 340 total pixel diffs.
Score Sensitivity: 21 single pixel diff.
Delay between captures: 180 seconds.
SCORE value: None
Pi Core Temp: 61.6'C
BOM ID: IDN60801
BOM OWS: 94927
Stop when Wind/Gust Above: 11 km/h
Last Weather Poll message: Issued at 10:03 am EDT Wednesday 18 December 2019
Last Weather Name: Braidwood
Last Weather Recorded at: 18/10:00am
Last Weather Wind: 7 km/h
Last Weather Gust: 13 km/h
Last Config Poll: 2019-12-17 23:07:48.455441
Uptime: 23:07:49 up 1 day

Please check - Movement Detect Photos will NOT be sent if;

1. Movement Detection is Stopped
2. Score is Below Score Threshold
3. Wind or Gust is above Wind Stop Speed, or
4. Your photo limit for today is reached (16/16)

Adjust Camera Config (Request Photo)

Todays photo limit: 5/16 Reset

Do Not Disturb for remainder of today

Unsubscribe

Screenshot from new rewrite app using a test camera called ‘Deck’ (NOTE this has been heavily redacted);

Motion Detected

Sent To 1 Subscribers (Max 8)

Cam Name

Deck

Cam IP Address

XXXX

Application

XXXX

Date Time of Recording

Fri 27 Sep 06:32:45 AEST 2024

Noise Threshold Setting

18.0

This Image Trigger Noise Value

18.17

BOM Station ID Setting

IDN60801

BOM Station WMO Setting

94926

Stop When Wind/Gust Above Setting

50.0 km/h

Weather Observations *

Refresh Message

Issued at 5:03 am EST Friday 27 September 2024

Name

Canberra

Wind Speed

13 km/h

Gust Speed

17 km/h

Air Temperature

0.5 'C

Rain Since 9am

0.4 mm

Delay Between Captures

60 seconds

Pi Core Temperature

38.6'C

Last Config Poll

2024-09-27 05:55:58.439413

Pi Uptime

06:32:54 up 2 days

Please Check - Motion Detection Imagery Will NOT Be Sent If;

1. Motion Detection Is Stopped
2. Image Trigger Noise Value Is Below Noise Threshold Setting
3. Wind Or Gust Is Above Wind Stop Speed Setting, Or
4. Your Photo Limit For Today Has Been Reached (20/20)

Actions

• Adjust Camera Config (Request Photo/Recording)
• Reset Todays Photo Limit: 3/20
• Do Not Disturb For Remainder Of Today
• Home

This email intended for original recipient only

* - Copyright Commonwealth of Australia 2024, Bureau of Meteorology. For more information see: http://www.bom.gov.au/other/copyright.shtml http://www.bom.gov.au/other/disclaimer.shtml