Ultra-fast, lightweight person detection add-ons for Home Assistant using the FastestDetV2 model. Perfect for edge devices like Orange Pi, Raspberry Pi, and other ARM-based systems.
This repository provides two Home Assistant add-ons for real-time person detection via MQTT:
| Add-on | Runtime | Best For | Performance |
|---|---|---|---|
| FastestDet ONNX | ONNX Runtime | Universal compatibility, easy setup | Good (50-150ms per frame) |
| FastestDet NCNN | NCNN (Tencent) | ARM devices, maximum performance | Excellent (20-50ms per frame) |
Both add-ons:
- ✅ Detect persons from any Home Assistant camera
- ✅ Create motion sensors via MQTT Discovery
- ✅ Provide annotated images (first/last detection frames)
- ✅ Monitor processing time and loop performance
- ✅ Work on ARM64 (aarch64) and x86_64 architectures
- ✅ Ultra-lightweight (~300MB Docker image)
- ✅ No GPU required - optimized for CPU inference
Screenshots
- Binary sensor with
motiondevice class - Debounced detection (configurable consecutive frames)
- Automatic MQTT Discovery - no YAML configuration needed
- Annotated First Detection: Shows the first frame when motion is detected
- Annotated Last Detection: Shows the last frame before motion ends
- Bounding boxes with confidence scores
- Processing Time: AI inference + post-processing (ms)
- Loop Time: Total cycle time including network I/O (ms)
- Diagnostic entities hidden from main UI
- Fixed-rate loop (consistent FPS)
- Configurable detection threshold
- Adjustable check interval
- Letterbox preprocessing (preserves aspect ratio)
- In Home Assistant, go to Settings → Add-ons → Add-on Store
- Click the three dots (⋮) in the top right → Repositories
- Add the repository URL: https://github.com/Splinterjke/FastestDet-HASS-Addon
- Click Add → Close
- Refresh the page (F5)
You'll now see two new add-ons in the store:
- FastestDet Person Detector (ONNX) - Universal compatibility
- FastestDet Person Detector (NCNN) - ARM optimized
Choose based on your hardware:
| Device | Recommended Add-on |
|---|---|
| Orange Pi Zero 3, Raspberry Pi 4/5 | NCNN (2-3x faster) |
| x86_64 server, Intel NUC | ONNX (easier setup) |
| Any ARM device with limited RAM | NCNN (lower memory) |
- Click on the add-on → Configuration tab
- Fill in required fields:
- Home Assistant URL:
http://homeassistant.local:8123(or your HA IP) - Long-Lived Access Token: Generate in HA Profile → Security → Create Token
- Camera Entity: Your camera entity ID (e.g.,
camera.front_door) - MQTT Broker: Your MQTT broker address (e.g.,
core-mosquittoorhomeassistant.local) - MQTT Port: Usually
1883 - MQTT Credentials: Leave empty if not required
- Home Assistant URL:
- Click Save
- Go to Info tab
- Click Start
- Check logs for any errors
After a few seconds, you'll see new entities:
binary_sensor.fastestdet_person_motion- Motion sensorsensor.fastestdet_person_processing_time- AI inference timesensor.fastestdet_person_loop_time- Total loop timecamera.fastestdet_person_annotated_first- First detection imagecamera.fastestdet_person_annotated_last- Last detection image
Note
Loop time is highly dependent on the latency of the camera API call.
The endpoint {HA_URL}/api/camera_proxy/{CAMERA_ENTITY}?width={width}&height={height} can vary significantly based on:
- Camera hardware and encoding
- Network latency between HA and the camera
- Snapshot resolution (larger = slower)
Tips:
- Configure snapshot dimensions via
snapshot_widthandsnapshot_heightto reduce bandwidth - Decrease
check_intervalfor more responsive detection (but higher CPU/network usage) - Frequent API calls (e.g., 0.5s interval) may actually have lower per-call latency than infrequent calls due to connection keep-alive and caching effects. Feel free to go below 1.0s interval to get higher FPS, but set higher
consecutive_detections_requiredandconsecutive_non_detections_requiredcorrespondigly. I personally use 0.5s interval and 2 frames for ON and 6 frames for OFF.
| Option | Description | Default | Example |
|---|---|---|---|
log_level |
Logging verbosity | info |
debug, warning |
ha_url |
Home Assistant URL | http://homeassistant.local:8123 |
http://192.168.1.100:8123 |
ha_token |
Long-lived access token | (required) | eyJ0eXAi... |
camera_entity |
Camera to monitor | (required) | camera.front_door |
mqtt_broker |
MQTT broker address | core-mosquitto |
homeassistant.local |
mqtt_port |
MQTT broker port | 1883 |
1883 |
mqtt_user |
MQTT username | (empty) | mqtt_user |
mqtt_pass |
MQTT password | (empty) | mqtt_password |
mqtt_base_topic |
Base MQTT topic | fastestdet |
person_detection |
check_interval |
Loop interval (seconds) | 1.0 |
0.5 (2 FPS), 2.0 (0.5 FPS) |
detection_threshold |
Confidence threshold | 0.55 |
0.65 (stricter), 0.45 (more sensitive) |
consecutive_detections_required |
Frames needed to trigger ON | 2 |
3 (less sensitive), 1 (instant) |
consecutive_non_detections_required |
Frames needed to trigger OFF | 3 |
5 (longer presence), 1 (instant) |
snapshot_width |
Camera snapshot width (px) | 1280 |
1920 (higher quality), 352 (lower bandwidth) |
snapshot_height |
Camera snapshot height (px) | 720 |
1080 (higher quality), 197 (lower bandwidth) |
The debouncing parameters help prevent false positives and flickering:
-
consecutive_detections_required: The model must detect a person in this many consecutive frames before triggering the motion sensor ON. Increase this value for noisy cameras or environments with brief false detections. -
consecutive_non_detections_required: The model must NOT detect a person in this many consecutive frames before triggering the motion sensor OFF. Increase this value to keep the sensor ON longer when a person is present (to get delayed OFF state to catch more ending frames), even if they temporarily move out of frame.
After changing the add-on configuration, you must restart the add-on for changes to take effect:
- Go to Settings → Add-ons → [Your Add-on]
- Click the Info tab
- Click Restart
The add-on will reload all configuration values and restart the detection process.
- NCNN: 60-120ms processing time, ~64MB RAM
- ONNX: 90-180ms processing time, ~64MB RAM
Note: Actual performance depends on camera resolution, network speed, and system load.
- Check logs in the Log tab
- Verify MQTT broker is accessible
- Ensure camera entity exists in Home Assistant
- Lower
detection_thresholdto0.45 - Check camera is actually streaming (view in HA)
- Verify
camera_entityis correct (e.g.,camera.front_doornotcamera.front door)
- Try NCNN add-on instead of ONNX
- Reduce camera resolution in HA camera settings
- Increase
check_intervalto reduce load
- Ensure MQTT integration is set up in Home Assistant
- Check MQTT broker logs for connection issues
- Verify
mqtt_base_topicdoesn't conflict with other devices
┌─────────────────┐
│ Home Assistant │
│ Camera Entity │
└────────┬────────┘
│ HTTP API (snapshot)
↓
┌─────────────────┐
│ FastestDet │
│ Add-on │
│ - Fetch image │
│ - Preprocess │
│ - AI inference │
│ - Postprocess │
└────────┬────────┘
│ MQTT
↓
┌─────────────────┐
│ MQTT Broker │
│ (Mosquitto) │
└────────┬────────┘
│ MQTT Discovery
↓
┌─────────────────┐
│ Home Assistant │
│ - Motion sensor│
│ - Cameras │
│ - Diagnostics │
└─────────────────┘
Both add-ons use FastestDetV2 by Pairman:
- Ultra-lightweight: ~1MB model size
- Anchor-free detection
- Trained on COCO dataset (80 classes, but only "person" class is used)
- Input: 352×352 RGB image
- Output: Bounding boxes with confidence scores
- FastestDetV2: Pairman - Optimized fork
- FastestDet Original: dog-qiuqiu - Original architecture
- NCNN: Tencent - High-performance inference framework
- ONNX Runtime: Microsoft - Universal inference engine
This project is provided as-is for personal and commercial use. The FastestDetV2 model is subject to its own license terms.
Made with ❤️ for the Home Assistant community