Build a Raspberry Pi 4 Security Camera with Picamera2 & PIR

Setting up a reliable raspberry pi 4 security camera requires moving past outdated tutorials that rely on deprecated software. If you are building this in 2026, the legacy picamera library is dead on modern Raspberry Pi OS. This guide targets the Raspberry Pi 4 Model B (4GB RAM) running Raspberry Pi OS Bookworm (64-bit), utilizing the modern libcamera stack via the picamera2 Python library.

We will pair the Pi 4 with the 12MP Camera Module 3 (IMX708 sensor) and an AM312 mini PIR motion sensor. Unlike older tutorials that use the HC-SR501 PIR, the AM312 operates natively at 3.3V logic, eliminating the risk of frying your Pi's GPIO pins with 5V return signals. Below is the exact hardware, wiring, and fault-tolerant Python code to get your node capturing motion events.

Hardware Spec Sheet & Bill of Materials

Before ordering parts, verify your power supply. The Pi 4 with the Camera Module 3 and an active USB Wi-Fi dongle can spike past 2.5A during image processing. Use the official 27W USB-C power supply to prevent brownout throttling.

GPIO Pin Mapping & Physical Wiring

The physical wiring for this raspberry pi 4 security camera build is minimal, but the CSI ribbon cable orientation is the number one cause of initialization failures. The AM312 PIR requires only three connections.

Wiring Steps

1. De-energize the board: Unplug the USB-C power supply before touching the GPIO header or CSI port.
2. Seat the CSI cable: Lift the black plastic collar on the CAM1 port. Insert the ribbon cable with the blue insulating tape facing away from the Ethernet port (metal contacts facing the Ethernet port). Push the collar down firmly.
3. Wire the AM312: Connect VCC to Pin 1 (3.3V), OUT to Pin 11 (GPIO 17), and GND to Pin 9. Use Dupont connectors or solder directly for a permanent enclosure install.
4. Verify: Before booting, use a multimeter in continuity mode to ensure your GND wire does not short against the 3V3 or GPIO 17 pins.

Python Motion-Capture Script (picamera2)

This script uses the picamera2 library to initialize the camera pipeline and gpiozero to monitor the PIR sensor. When motion is detected, it captures a full-resolution JPEG and saves it with a timestamp. Error handling is built in to catch camera lockups and I/O failures.

import os
import time
from datetime import datetime
from picamera2 import Picamera2, MmapRequest
from gpiozero import MotionSensor
import signal
import sys

# --- PIN & PATH DEFINITIONS ---
PIR_GPIO_PIN = 17
CAPTURE_DIR = "/home/pi/security_captures/"

# Ensure capture directory exists
os.makedirs(CAPTURE_DIR, exist_ok=True)

# Initialize PIR Sensor on GPIO 17
# queue_len=1 ensures we trigger immediately on the first motion pulse
pir = MotionSensor(PIR_GPIO_PIN, queue_len=1, pull_up=False)

def graceful_exit(signum, frame):
    print("\n[INFO] Shutdown signal received. Closing camera pipeline...")
    sys.exit(0)

signal.signal(signal.SIGINT, graceful_exit)
signal.signal(signal.SIGTERM, graceful_exit)

def capture_image():
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    file_path = os.path.join(CAPTURE_DIR, f"motion_{timestamp}.jpg")
    
    try:
        # switch_mode captures a high-res still without stopping the preview pipeline
        picam2.switch_mode_and_capture_file("still", file_path)
        print(f"[SUCCESS] Captured: {file_path}")
    except OSError as e:
        print(f"[ERROR] File write failed: {e}")
    except Exception as e:
        print(f"[ERROR] Capture pipeline failed: {e}")

if __name__ == "__main__":
    picam2 = None
    try:
        print("[INFO] Initializing picamera2 pipeline...")
        picam2 = Picamera2()
        
        # Configure a low-res preview stream and a high-res still stream
        config = picam2.create_preview_configuration()
        still_config = picam2.create_still_configuration()
        picam2.configure(config)
        
        # Create the still configuration in the background for fast switching
        picam2.start()
        picam2.pre_callback = None # Disable preview callback to save CPU
        
        print(f"[INFO] Camera active. Monitoring GPIO {PIR_GPIO_PIN} for motion...")
        
        # Attach the motion detection event
        pir.when_motion = capture_image
        
        # Keep the script alive
        while True:
            time.sleep(1)
            
    except RuntimeError as e:
        # Catches the exact libcamera initialization failures
        print(f"[FATAL] Camera initialization failed: {e}")
        print("Check CSI cable seating and ensure no other process is using the camera.")
        sys.exit(1)
    except Exception as e:
        print(f"[FATAL] Unexpected error: {e}")
        sys.exit(1)
    finally:
        if picam2 is not None:
            picam2.stop()
            print("[INFO] Camera pipeline closed.")

Debugging: Camera & GPIO Failures

When your raspberry pi 4 security camera fails to trigger or initialize, the terminal output will usually point to one of three specific bottlenecks. Here are the exact error strings and how to resolve them.

Exact Error String: RuntimeError: No cameras available!

This occurs when the libcamera stack cannot probe the IMX708 sensor over the I2C bus.

• Cause 1 (Most Likely): The CSI ribbon cable is inserted backward or not fully seated. The metal contacts must face the Ethernet port.
• Cause 2: The camera interface is disabled in the bootloader. Run sudo raspi-config, navigate to Interface Options, and ensure Legacy Camera is disabled (libcamera requires the modern DRM/KMS stack).
• Cause 3: Hardware fault on the CSI port's I2C pins. Test with a known-good ribbon cable.

Exact Error String: OSError: [Errno 16] Device or resource busy

This happens when the camera pipeline is locked by another process.

• Cause 1: You have a terminal window open running libcamera-hello or rpicam-hello. Kill it with pkill rpicam.
• Cause 2: A previous run of your Python script crashed without executing the finally block, leaving the camera handle open. Reboot the Pi to clear the hardware lock.

Extending or Simplifying the Build

A standalone Python script is excellent for a single-node trigger, but scaling a security system requires architectural decisions. Below is a framework for deciding how to adapt this raspberry pi 4 security camera build based on your deployment goals.

Transitioning to Frigate NVR

If you want to move from simple PIR-triggered snapshots to continuous AI object detection, you will need to abandon the PIR sensor and the picamera2 Python script entirely. Instead, configure the Pi 4 to output an RTSP stream using go2rtc, and ingest that stream into Frigate NVR running on a more powerful host (like an Intel NUC or a Pi 5 with a Hailo AI kit). The Pi 4's hardware video encoder (H.264) is perfectly capable of pushing a 1080p30 RTSP stream, but its CPU will bottleneck if you attempt to run YOLO object detection locally without a Coral USB Accelerator.

For comprehensive documentation on the modern camera stack, refer to the official Raspberry Pi Camera Software Guide and the Picamera2 Manual. For GPIO pin logic and sensor integration, the gpiozero MotionSensor documentation provides excellent baseline parameters for debouncing PIR triggers.