{"id":13910812,"url":"https://github.com/FutureSharks/rpi-security","last_synced_at":"2025-07-18T10:31:02.606Z","repository":{"id":52503289,"uuid":"48331907","full_name":"FutureSharks/rpi-security","owner":"FutureSharks","description":"A security system written in python to run on a Raspberry Pi with motion detection and mobile notifications","archived":false,"fork":false,"pushed_at":"2024-04-26T16:48:12.000Z","size":3959,"stargazers_count":215,"open_issues_count":5,"forks_count":71,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-10-10T22:45:28.195Z","etag":null,"topics":["mobile-notifications","mobile-phones","raspberry-pi","security","telegram-bot","wifi"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FutureSharks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-20T18:12:09.000Z","updated_at":"2024-08-27T23:34:24.000Z","dependencies_parsed_at":"2024-10-25T17:07:24.258Z","dependency_job_id":"99cd90dc-80e1-4a81-8359-2cb9f61abc89","html_url":"https://github.com/FutureSharks/rpi-security","commit_stats":{"total_commits":65,"total_committers":5,"mean_commits":13.0,"dds":0.09230769230769231,"last_synced_commit":"a2951940e59408fcd98d83d450c86f9165de4e37"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FutureSharks%2Frpi-security","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FutureSharks%2Frpi-security/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FutureSharks%2Frpi-security/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FutureSharks%2Frpi-security/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FutureSharks","download_url":"https://codeload.github.com/FutureSharks/rpi-security/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226178437,"owners_count":17585959,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mobile-notifications","mobile-phones","raspberry-pi","security","telegram-bot","wifi"],"created_at":"2024-08-07T00:01:46.653Z","updated_at":"2024-11-25T19:32:03.049Z","avatar_url":"https://github.com/FutureSharks.png","language":"Python","funding_links":[],"categories":["Python","security"],"sub_categories":["USB GADGET"],"readme":"# Raspberry Pi Security System\n\nA simple security system to run on a [Raspberry Pi](https://www.raspberrypi.org/).\n\nFeatures:\n\n  - Motion detection and photo capture using the camera\n  - Mobile notifications with photos\n  - Detects when you are home and arms or disarms automatically\n  - Can be remotely controlled using [Telegram](https://telegram.org/)\n\n\u003ca href=\"#\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/FutureSharks/rpi-security/master/images/rpi-security-1.jpg\" width=\"600\"\u003e\u003c/a\u003e\n\n\u003ca href=\"#\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/FutureSharks/rpi-security/master/images/rpi-security-2.jpg\" width=\"600\"\u003e\u003c/a\u003e\n\n## Requirements\n\nYou will need this hardware:\n\n  - Raspberry Pi with camera interface.\n  - Raspberry Pi camera module.\n  - A Wi-Fi adapter that supports monitor mode (see [note](#WiFi-adapter-arrangement))\n\nSoftware requirements:\n\n  - A [Telegram bot](https://core.telegram.org/bots). It's free and easy to setup.\n  - Raspbian Stretch Lite distribution installed.\n  - Python 3.\n\n## How it works\n\n### Automatic presence detection\n\nOne of my main goals was to have the system completely automatic. I didn't want to have to arm or disarm it when leaving or arriving home. I figured the easiest way to achieve this was to try and detect the mobile phones of the home occupants. Conceptually this was quite simple but in practice it was the most challenging part because:\n\n  - Capturing all packets on a Wi-Fi interface is too resource intensive.\n  - Mobile phones are not always online and sending packets over Wi-Fi. Sometimes they stay unconnected for 15 minutes or longer.\n  - Even with 99% accuracy, false alarms are annoying.\n\nAfter much testing I used an approach that mixes active (ARP ping) and passive (packet capture) detection over the Wi-Fi adapter based on knowing the MAC addresses of the mobile phones. The mobile phone MAC addresses are set in the configuration and rpi-security captures packets on a monitor mode interface with the following filter:\n\n1. Wi-Fi probe requests from any of the configured MACs.\n2. Any packets sent from the configured MACs to the host running rpi-security.\n\nThe application resets a counter when packets are detected and if the counter goes longer than ~10 minutes the system is armed. To eliminate the many false alarms, when transitioning between an armed/disarmed state, the application performs an ARP scan directed at each of the configured MAC addresses to be sure they are definitely online or offline. Both iOS and Android will respond to this ARP scan 99% of the time where a ICMP ping is quite unreliable. By combining the capture of Wi-Fi probe requests and using ARP scanning, the Wi-Fi frequency doesn't matter because mobile phones send probe requests on both frequencies and ARP scan works across both frequencies too.\n\n#### Motion detection\n\nMotion detection is done using [OpenCV](https://opencv.org/). Each motion detection will save 4 pictures in `/tmp`:\n\n - frame.jpg: The picture with rectangles surrounding the motion\n - gray.jpg: The picture with grayscale and blur (which will be use to detect motion between the current frame and the previous one)\n - abs_diff.jpg: The absolute difference between they grays frames (current and previous)\n - thresh.jpg: A threshold has been applied to be sure the motion is important enough to be detected.\n\n#### Notifications\n\nA [Telegram](https://core.telegram.org/bots) bot is used to send notifications with the captured images. They have good mobile applications and a nice API. You can also view the messages in a browser and messages are synced across devices. If the system is in an armed state and motion is detected then a message with the captured image is sent to you from the Telegram bot. Notifications are also sent on any alarm state change.\n\n\u003ca href=\"#\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/FutureSharks/rpi-security/master/images/rpi-security-notification.png\" width=\"600\"\u003e\u003c/a\u003e\n\n#### Remote control\n\nYou can send the Telegram bot commands that trigger certain actions.\n\n  - */disable*: Disables the service until re-enabled.\n  - */enable*: Enables the service after it being disabled.\n  - */status*: Sends a status report.\n  - */photo*: Captures and sends a photo.\n  - */gif*: Captures and sends a gif.\n\n#### Python\n\nThe application is written in python 3 and large parts of the functionality are provided by the following pip packages:\n\n  - [picamera](https://github.com/waveform80/picamera)\n  - [kamene](https://github.com/phaethon/kamene)\n  - [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot)\n  - [opencv-python](https://github.com/skvark/opencv-python)\n\nThe application uses multithreading in order to process events asynchronously. There are 4 threads:\n\n  - telegram_bot: Responds to commands.\n  - monitor_alarm_state: Arms and disarms the system.\n  - capture_packets: Captures packets from the mobile devices.\n  - process_photos: Sends captured images via Telegram messages.\n\n## Installation, configuration and Running\n\nFirst ensure your WiFi is [set up correctly](#WiFi-adapter-arrangement)\n\nEnsure your GPU/memory split gives 128MB to the GPU. You can see or set this value with `raspi-config`.\n\nInstall required packages for python:\n\n```console\nsudo apt update\nsudo apt install -y tcpdump iw python3-dev python3-pip python3-numpy\n```\n\nInstall required packages for OpenCV:\n\n```console\nsudo apt install -y libhdf5-103 libharfbuzz0b libwebp6 libjasper1 libopenexr23 libgstreamer1.0-0 libatlas-base-dev libgtk-3-0 libqtgui4 libqt4-test libilmbase23 libavcodec-extra58 libavformat58 libswscale5  libjpeg8-dev zlib1g-dev libffi-dev libopenjp2-7-dev libtiff5\n```\n\nInstall OpenCV and rpi-security:\n\n```console\nsudo pip3 install opencv-contrib-python==3.4.6.27 opencv-contrib-python-headless==3.4.6.27\nsudo pip3 install --no-binary :all: https://github.com/FutureSharks/rpi-security/archive/1.5.zip\n```\n\nReload systemd configuration and enable the service:\n\n```console\nsudo systemctl daemon-reload\nsudo systemctl enable rpi-security.service\n```\n\nAdd your MAC address or addresses, Telegram bot API key and any other changes to `/etc/rpi-security.conf`.\n\nEnsure you have enabled the camera module using `raspi-config`.\n\nAnd start the service:\n\n```console\nsudo systemctl start rpi-security.service\n```\n\nYou need to send at least one message to the Telegram bot otherwise it won't be able to send you messages. This is so the service can save the telegram chat_id. So just send the `/status` command.\n\nIt runs as a service and logs to syslog. To see the logs check `/var/log/syslog`.\n\n## Debug and troubleshooting\n\nYou can start `rpi-security.py` manually with debug output. First add the monitor mode interface:\n\n```console\nroot@raspberrypi:~# iw phy phy1 interface add mon0 type monitor\nroot@raspberrypi:~# ifconfig mon0 up\n```\n\nThen start with debug output:\n\n```console\nroot@raspberrypi:~# rpi-security.py -d\n2016-05-28 14:43:30 DEBUG   rpi-security.py:73  MainThread          State file read: /var/lib/rpi-security/state.yaml\n2016-05-28 14:43:30 DEBUG   rpi-security.py:44  MainThread          Calculated network: 192.168.178.0/24\n2016-05-28 14:43:41 INFO    rpi-security.py:214 monitor_alarm_state thread running\n2016-05-28 14:43:41 INFO    rpi-security.py:196 capture_packets     thread running\n2016-05-28 14:43:41 INFO    rpi-security.py:259 telegram_bot        thread running\n2016-05-28 14:43:41 INFO    rpi-security.py:154 process_photos      thread running\n2016-05-28 14:43:43 INFO    rpi-security.py:392 MainThread          rpi-security running\n2016-05-28 14:43:43 INFO    rpi-security.py:112 MainThread          Telegram message Sent: \"rpi-security running\"\n2016-05-28 14:44:29 DEBUG   rpi-security.py:191 capture_packets     Packet detected from aa:aa:aa:bb:bb:bb\n2016-05-28 14:44:29 DEBUG   rpi-security.py:191 capture_packets     Packet detected from aa:aa:aa:bb:bb:bb\n2016-05-28 14:44:48 DEBUG   rpi-security.py:280 Dummy-1             Motion detected but current_state is: disarmed\n```\n\nAnd then delete the interface when complete:\n\n```console\niw dev mon0 del\n```\n\n## WiFi adapter arrangement\n\nYour WiFi adapter must support monitor mode. The Raspberry Pi built-in wireless LAN adapters do **not** currently support monitor mode by default. Currently the only way to get monitor mode working for the built-in WiFi adapters is to use [nexmon](https://github.com/seemoo-lab/nexmon) and this is not simple.\n\nThe easiest way to get a monitor mode WiFi adapter is to just buy a USB adapter that supports it. Currently the best options are:\n\n- RT5370: very cheap, easy to find but only supports 2.4Ghz\n- RT3572: more expensive, hard to find but supports both 2.4Ghz and 5Ghz\n\nMost modern phones and routers use 5Ghz now so results could be unreliable if your adapter only supports 2.4Ghz.\n\nThe interface used to connect to your WiFi network must be the same interface that supports monitor mode. And this must be the same WiFi network that the mobile phones connect to. This is because there is a packet capture running to listen for mobile phone ARP replies and Wi-Fi probe requests.\n\nThe default configuration of this application assumes you are using a USB adapter as `phy#1`/`mon0`/`wlan1`.\n\nIf you are not using the on-board WiFi adapter then you can stop it connecting to your WiFi network by running this command:\n\n```console\necho -e \"interface wlan0\\nnohook wpa_supplicant\" \u003e\u003e /etc/dhcpcd.conf\n```\n\nThis shows a working WiFi adapter arrangement:\n\n```console\nroot@raspberrypi:~ # iw dev\nphy#1\n\tInterface mon0\n\t\tifindex 4\n\t\twdev 0x100000002\n\t\taddr 00:0e:8e:58:d6:af\n\t\ttype monitor\n\t\ttxpower 26.00 dBm\n\tInterface wlan1\n\t\tifindex 3\n\t\twdev 0x100000001\n\t\taddr 00:0e:8e:58:d6:af\n\t\tssid Connecting...\n\t\ttype managed\n\t\tchannel 124 (5620 MHz), width: 40 MHz, center1: 5630 MHz\n\t\ttxpower 26.00 dBm\nphy#0\n\tInterface wlan0\n\t\tifindex 2\n\t\twdev 0x1\n\t\taddr b8:27:eb:cb:b6:5d\n\t\ttype managed\n\t\tchannel 34 (5170 MHz), width: 20 MHz, center1: 5170 MHz\n\t\ttxpower 31.00 dBm\n```\n\nYou could have interfaces with different names, just be sure to change the parameters in `/etc/rpi-security-environment`.\n\n## Older version with PIR sensor motion detection\n\nCurrently the camera is used for motion detection. If you want to use the old version with support for a PIR sensor then look at version [0.7](https://github.com/FutureSharks/rpi-security/tree/0.7)\n\n## Reboot on connectivity loss\n\nAbout once every month or two my Raspberry Pi loses the WLAN connection. I created a cron job to check connectivity and reboot if the check fails.\n\n```console\nwget https://raw.githubusercontent.com/FutureSharks/rpi-security/master/bin/check-telegram-connectivity.sh -O /usr/local/bin/check-telegram-connectivity.sh\nchmod 0755 /usr/local/bin/check-telegram-connectivity.sh\necho '*/20 * * * * root /usr/local/bin/check-telegram-connectivity.sh' \u003e /etc/cron.d/reboot-on-connection-failure\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFutureSharks%2Frpi-security","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFutureSharks%2Frpi-security","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFutureSharks%2Frpi-security/lists"}