Title: Motion Detector
Description: On-device motion detection using the onboard camera, with optional SD snapshots and Discord alerts
URL: /latest/camera/motion-detector/
Version: latest
Section: Camera
Search index: /search-index.json

# Motion Detector

> On-device motion detection using the onboard camera, with optional SD snapshots and Discord alerts

## On this page

- [Supported Boards](#supported-boards)
- [How It Works](#how-it-works)
- [Quick Start](#quick-start)
- [Basic Detection](#basic-detection)
- [Enable Discord Alerts](#enable-discord-alerts)
- [CLI Commands](#cli-commands)
- [Recommended Settings](#recommended-settings)
- [Fast Local Testing](#fast-local-testing)
- [More Sensitive Detection](#more-sensitive-detection)
- [SD and Snapshot Notes](#sd-and-snapshot-notes)
- [Troubleshooting](#troubleshooting)

---

GhostESP can use an onboard camera as a lightweight motion detector. The current implementation is tuned for small ESP32 devices and runs entirely on-device using grayscale frame comparison.
## Supported Boards
- Seeed Studio XIAO ESP32-S3 Sense (xiao_esp32s3_sense) - the only camera-enabled build currently available.
- Other boards need an enabled CONFIG_HAS_CAMERA build plus compatible camera pin mapping.
## How It Works
- Camera input uses QQVGA resolution (160x120).
- Frames are captured in grayscale.
- GhostESP keeps the previous frame in memory and compares sampled pixels against the new frame.
- If the changed-pixel percentage crosses the configured trigger threshold for consecutive frames, a motion event is raised.
- A small warmup window and hysteresis reduce repeated triggers from one burst of motion.
This design keeps RAM use low while still being fast enough for continuous monitoring on the ESP32-S3.
## Quick Start
### Basic Detection
motion start
Wave a hand or move an object in front of the camera. You should see output like:
[MOTION] #1 44.5% changed
Stop detection with:
motion stop
### Enable Discord Alerts
motion discord https://discord.com/api/webhooks/...
motion cooldown 5000
motion start
If image uploads are not needed, disable them to reduce bandwidth and processing time:
motion image off
## CLI Commands
- motion start - Start motion detection.
- motion stop - Stop motion detection.
- motion status - Show current detector state.
- motion threshold <1-255> - Set per-pixel difference threshold.
- motion interval <100-10000> - Set frame interval in milliseconds.
- motion percent <1-100> - Set trigger percentage.
- motion sample <1-32> - Compare every Nth pixel.
- motion snap <on|off> - Save motion snapshots to SD card.
- motion image <on|off> - Attach images to Discord alerts.
- motion discord <url|off> - Configure or disable the Discord webhook.
- motion webhook <url|off> - Alias for motion discord.
- motion cooldown <ms> - Minimum time between webhook alerts.
## Recommended Settings
### Fast Local Testing
motion threshold 30
motion percent 10
motion interval 500
motion sample 4
### More Sensitive Detection
motion threshold 20
motion percent 5
motion sample 2
Lower values detect smaller changes, but also increase false positives from lighting flicker, auto exposure shifts, and sensor noise.
## SD and Snapshot Notes
- Motion detection itself works without SD.
- motion snap on writes JPEG snapshots to /mnt/ghostesp/captures.
- If Discord webhook alerts are enabled and motion image on is active, images sent to Discord are also saved automatically when SD storage is available.
- Discord alerts can still work without SD because images are uploaded directly from the frame buffer.
## Troubleshooting
- Camera init failed: ESP_ERR_NOT_FOUND - Camera ribbon cable or pin mapping issue.
- Detector starts but does not trigger - Lower motion threshold or motion percent.
- Too many triggers - Raise motion percent, raise motion threshold, or increase motion cooldown for webhooks.
- Discord TLS/certificate errors - Ensure the device has Wi-Fi access and a valid time sync before the webhook attempt.
- Frame buffer overflow logs (FB-OVF) - Usually indicates the camera or processing path is under pressure; reduce extra work such as image uploads while testing.