pi-guard

Home monitoring for a Raspberry Pi and a USB camera, operated through Telegram (and optionally Signal). It records continuously to local storage, notices movement, and lets you look at your home with two buttons: View photo and View video.

pi-guard is written for households where the person living there is not the person who set it up — typically an older relative. Everyday use needs no commands, no app besides the messenger, and no technical vocabulary.

Deutsche Version

What it does

• Records 24/7 to five-minute MP4 segments, using the camera's own H.264 or the Pi's hardware encoder. Old footage is deleted after a retention period or when the disk gets full; the root filesystem is protected.
• Detects motion on small low-resolution frames, with zones, schedules and filters for light switches and sensor noise.
• HOME and AWAY modes. At home, movement is logged but nobody is woken up. Away, alerts arrive with a snapshot. The mode can be set by button, command, timer, or automatically from your phone's presence in the Wi-Fi.
• Telegram first. Large buttons, German and English, a simple view for everyday users and an advanced view for administrators. Plain text works too: foto, video 30, abwesend 2h.
• Optional, off by default: Signal (via signal-cli), person detection, recognition of enrolled people, microphone clips, speaker playback, MQTT / Home Assistant.
• Nothing leaves the device except the messages you ask for. No cloud account, no open ports, no telemetry.

Requirements

• Raspberry Pi 4 (2 GB is enough) or Pi 5 with Raspberry Pi OS Lite 64-bit (Bookworm or newer); other Debian/Ubuntu ARM64 or x86_64 machines work too
• a USB (UVC) camera; a High Endurance microSD card or a USB SSD
• a Telegram account

See docs/hardware.md for tested and expected hardware.

Installation

git clone https://github.com/lytexdev/pi-guard.git
cd pi-guard
sudo ./scripts/install.sh

The installer asks for the Telegram bot token and your Telegram user ID, creates a pi-guard system user, writes /etc/pi-guard/pi-guard.env and a config.yaml for the detected camera, installs a systemd service, and runs pi-guard doctor. Details: docs/installation.md.

Docker Compose is available as an alternative: docs/docker.md.

Everyday use

Open the bot in Telegram and press Start:

pi-guard

Your camera is working.

Recording is switched on.

What would you like to do?

[ View photo ]
[ View video ]
[ Camera status ]
[ Notifications ]
[ Help ]

Administrators also see More functions (mode, events, users, invitations, sounds). Add family members with Invite someone; they receive a link and join as viewers. Command reference: docs/telegram.md.

Command line

pi-guard doctor             check camera, encoder, storage, Telegram, Signal
pi-guard status             service state, mode, recordings, recent events
pi-guard cameras            detected cameras and a config snippet
pi-guard mode away --for 3h
pi-guard presence status    one presence check, per source
pi-guard audio devices
pi-guard telegram test --send
pi-guard logs -f

Documentation

Installation	native install, update, uninstall
Configuration	.env and config.yaml reference
Telegram	bot setup, users, commands and aliases
Signal	optional, unofficial; signal-cli setup
Privacy	what is stored, what leaves the device, legal notes
Hardware	cameras, audio, storage
Docker	optional container deployment
Architecture	how the parts fit together
Performance	measurements and limits
Troubleshooting	common problems

German: Installation · Bedienung · Datenschutz

Privacy

A camera in a home records people who did not choose to be recorded: visitors, carers, neighbours, children. Read docs/privacy.md before installing. Audio recording and face recognition are switched off by default and need deliberate configuration.

License

MIT, see LICENSE.