From b2b44eb337c23282adc0390a9e2f8334bf9b2d7f Mon Sep 17 00:00:00 2001 From: Kshitij Date: Tue, 19 Nov 2024 23:45:22 +0530 Subject: [PATCH] Completely changed ABOUT.md file. Improved document structure, provided description for each file (main ones at least). --- ABOUT.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 74 insertions(+), 12 deletions(-) diff --git a/ABOUT.md b/ABOUT.md index fd4c405..e6c298a 100644 --- a/ABOUT.md +++ b/ABOUT.md @@ -1,13 +1,75 @@ # About -- Project uses Python for motion sensing using the camera - - Uses picamera, opencv, numpy libraries for processing the camera feed and motion detection - - Uses requests library for sending notification -- Docker for running 2 containers: - - ntfy for notifications and dashboard (supports PUB/SUB too!) - - wireguard for encrypted tunnel (didn't test since my router has CG-NAT) - -# Features - - Scanning the camera feed and processing all done locally, therefore no 3rd party, hence privacy and security preserved - - Docker for isolation of notifications and encrypted tunnel - - Entire setup secured using ufw firewall - + +This file contains description about this project. + +--- + +## What? + +This project utilizes Raspberry Pi with Pi Camera to detect motion in real-time. When motion is detected, the system sends a notification to a specified topic on an ntfy.sh server. The setup involves several components, including a camera interface, Docker setup for ntfy.sh and WireGuard VPN, and a Python script for motion detection. + +--- + +## Features + +- **Local Camera Feed Processing**: The entire camera feed is scanned and processed locally on the device. No third-party services are involved, ensuring privacy and security are preserved. +- **Docker-Based Isolation**: The notification system and encrypted tunnel (via WireGuard) are containerized using Docker, providing better isolation, security, and ease of deployment. +- **Enhanced Security with UFW Firewall**: The entire setup is secured using UFW (Uncomplicated Firewall), ensuring that only necessary services are accessible and protecting the system from unauthorized access. + +## Structure + +1. `setup.sh`: A shell script to install dependencies and set up the environment. +2. `docker-setup.sh`: A shell script that installs Docker and its dependencies. +3. `docker-compose.yaml`: Docker Compose configuration to run ntfy.sh and WireGuard VPN in containers. +4. `main.py`: The Python script that captures camera frames, detects motion, and sends notifications. + + +--- + +### setup.sh + +- Install `python3`, `pip`, and necessary libraries. +- Install camera libraries such as `picamera2`, `opencv`, and image processing libraries. +- Install `requests` for HTTP notifications. +- Set up Docker and start the `ntfy.sh` container using the [docker-setup.sh](https://git.kska.io/notkshitij/PiDetectify/src/branch/main/docker-setup.sh) script. + +## docker-setup.sh + +- Remove any conflicting Docker packages. +- Add Docker’s official apt repository and install Docker and Docker Compose. +- Set up the `ntfy.sh` and `wg-easy` containers using the provided [docker-compose.yaml](https://git.kska.io/notkshitij/PiDetectify/src/branch/main/docker-compose.yaml). +- Ensure Docker runs without sudo (add the current user to the Docker group). +- Test the Docker installation by running a "hello-world" container. + +> [!NOTE] +> I have referred [official Docker documentation](https://docs.docker.com/engine/install/debian/) for this. + +## docker-compose.yaml + +- `ntfy`: The container running ntfy.sh for sending notifications. + + - Exposes port 80 and uses the `binwiederhier/ntfy` Docker image. + - Configured with timezone IST and persistent storage for cache and config. + +`wg-easy`: A WireGuard VPN container that allows secure access to the Raspberry Pi. + + - Exposes ports `51820/udp` and `51821/tcp`. + - Uses environment variables for configuration and requires a password hash for login. + +> [!TIP] +> Refer official documentation for [ntfy.sh](https://docs.ntfy.sh/install/#docker) and [Wireguard](https://github.com/wg-easy/wg-easy). + +## main.py + +- Initialize the Raspberry Pi camera using the `picamera2` library. +- Capture and compare two consecutive frames to detect motion using OpenCV’s frame difference method. +- If motion is detected, the script will send a notification to the configured `ntfy.sh` topic (`motion-sensing` in this case by default). + +> [!TIP] You can customize the topic name in the `main.py` file by modifying the `ntfy_topic` variable. If you are using the local Docker instance for `ntfy.sh`, the script will use `localhost:80` by default. You can change that too by modifying the `rpi_ip` variable. + +## Customization + +- **Motion Detection Sensitivity**: The motion detection sensitivity can be adjusted by modifying the area threshold in the `cv2.contourArea(contour)` condition in `main.py`. Decrease the threshold to detect smaller movements or increase it to filter out smaller motion. +- **ntfy.sh Topic**: The topic for notifications is defined in `main.py` as `ntfy_topic`. You can change this to any unique topic name you want to receive notifications under. + +---