Raspberry Pi PIR motion sensor for Home Assistant lighting

HC-SR501 on GPIO, MQTT occupancy to Home Assistant, automation to turn lights on and off—beginner wiring guide with glossary.

Also available in French.

Quick answer (November 2026) — A PIR (passive infrared) module such as the HC-SR501 detects body heat and sends a 3.3 V signal on a GPIO pin (general-purpose input/output: a controllable pin on the Pi header). The Pi does not switch mains: it publishes occupancy over MQTT (Message Queuing Telemetry Transport: a lightweight messaging protocol) to Home Assistant (open-source home automation), which turns your smart bulbs on and off.

This project fits the smart home hub alongside door notifications and getting started with Home Assistant.

HC-SR501 PIR module wired to a Raspberry Pi GPIO header — photo for wiring reference

Wiring diagram: VCC to 5 V, OUT to GPIO4, GND to ground — verify against your module labels before powering on.

Goal

  • Motion on GPIO4 (BCM numbering, physical pin 7).
  • MQTT occupancy binary sensor in Home Assistant.
  • Turn a light on when motion is detected; off after 2 minutes with no motion.

Time, level, parts

Time Level
~45 min Beginner
Term Meaning in one line
PIR Detects infrared from moving people (not small pets reliably).
GPIO Pin on the Pi you read as on/off.
MQTT How the Pi tells Home Assistant “someone is here”.

HC-SR501 module: Amazon UK search · Amazon US search

The module runs on 5 V; OUT is 3.3 V — safe on Pi GPIO without a level shifter.

Wiring

PIR pin Raspberry Pi (physical pin) Role
VCC 2 (5V) power
OUT 7 (GPIO4) motion signal
GND 6 (GND) ground

Set jumper H (repeat trigger): the sensor stays “on” while you keep moving. Turn the time dial minimum — Home Assistant handles how long the light stays on. Adjust the sensitivity pot if you get false triggers.

Prepare the Pi

Target Raspberry Pi OS Bookworm on Pi 4 or Pi 5. Use a venv with system packages so gpiozero and lgpio work on Pi 5 (legacy RPi.GPIO does not):

sudo apt update sudo apt install -y python3-venv python3-gpiozero python3-lgpio mkdir -p ~/capteurs && cd ~/capteurs python3 -m venv —system-site-packages venv source venv/bin/activate pip install paho-mqtt

Script

Download presence_pir_mqtt.py. It uses gpiozero MotionSensor on GPIO4 and publishes to your MQTT broker (same pattern as the French step-by-step guide).

Automation (restart mode)

alias: Hall light on motion mode: restart triggers:

  • trigger: state entity_id: binary_sensor.raspberry_pi_pir_hall_occupancy to: “on” actions:
  • action: light.turn_on target: entity_id: light.hall
  • wait_for_trigger:
    • trigger: state entity_id: binary_sensor.raspberry_pi_pir_hall_occupancy to: “off” for: “00:02:00”
  • action: light.turn_off target: entity_id: light.hall

Replace entity ids. For night dimming on a dimmable bulb:

data: brightness_pct: ”{{ 15 if now().hour >= 23 or now().hour < 6 else 100 }}”

systemd

Run the script as a service with MQTT environment variables — same pattern as the door sensor project.

FAQ

Light flickers on/off?
Use automation mode: restart so each new motion resets the off timer.

False triggers at boot?
Wait ~60 s after power-up for PIR warm-up.

Pi 5 GPIO errors?
Install python3-lgpio; use venv with --system-site-packages.

Troubleshooting

  • Heat sources: avoid aiming at radiators or sunny windows.
  • GPIO busy: change PIR_GPIO in the script if GPIO4 is used for 1-Wire.
  • No MQTT updates: check broker address, username, and firewall.

Sources: Adafruit PIR guide · gpiozero MotionSensor.

Also: Zigbee temperature sensor · Home Assistant Green vs Pi 5.

All smart-home guides

Was this page helpful?

Have a question about this guide or need advice? Ask us here

Torn between two models or stuck on a build? Drop us a line and we will get back to you by email.