{ align=left }
A simple way to integrate CCTV cameras with built-in ANPR (Automatic Number Plate Recognition, aka ALPR or Automatic License Plate Recognition) to MQTT for Home Assistant integration, or any other MQTT consumer. Running under Docker is preferred but not necessary.
All that is needed is for the camera to be configured to upload images on plate recognition, by ftp, NAS or whatever else. ANPR2MQTT monitors the directory where the images lands and publishes plate information to MQTT. Its simple, requires no proprietary vendor APIs ( or differing ONVIF implementations ), and Home Assistant gets a copy of the actual annotated detection image to use on dashboards or to attach to notifications.
While intended for vehicle plate detection, it can be used to watch for and analyze any file, so for example uploaded face detection or line crossing images. A single anpr2mqtt instance can watch multiple paths and patterns for different cameras and events.
- Minimal configuration
- Ready configured to work with popular Hikvision ANPR camera settings
- File System Integration
- Home Assistant Integration.
- Publishes events to MQTT for Home Assistant as a MQTT Sensor Entity
- Auto-discovery configuration for Home Assistant
- Creates MQTT Image Entity on Home Assistant for image snapshot, so no web access to ftp needed
- Optionally also creates an MQTT Camera Entity
- Plate Enrichment
- OCR-based extraction of fields using tesseract-ocr
- By default direction detection (Forward/Reverse)
- Corrections by regular expression to fix OCR mis-readings
- Tracks and counts previous sightings
- Configurable to classify plates as known, to be ignored or as a potential threat
- Regular expression based corrections, for known plates that the ANPR sometimes mis-reads
- Fuzzy match corrections for known plates, based on Levenshtein algorithm
- UK Only
- DVLA Lookup if API_KEY provided, for detailed MOT and tax information
- Lookups cached for configurable time
- OCR-based extraction of fields using tesseract-ocr
- Auto clear vehicle state optionally, after configurable time
- Debug Tools built-in
Build and run with Docker, example docker-compose.yaml provided.
ANPR2MQTT uses pydantic-settings, which means configuration can happen in a variety of ways, and these can be combined - yaml configuration file, environment variables, Docker Secrets, built-in defaults, and .env file or command line arguments.
Every configuration setting can be passed as a command line argument, using dot notation for nested settings. This is the highest-priority source and overrides all other configuration.
uv run --with anpr2mqtt anpr2mqtt --mqtt.host 192.168.1.10 --mqtt.port 1884 --log_level DEBUGRun uv run --with anpr2mqtt anpr2mqtt --help to see all available flags, and find more information at Debug Tools
See Home Assistant Integration for configuration and example notification automation.
pydantic-settings needs double underscores for
environment variables in config sections. For example, MQTT__HOST means set the value host in the mqtt config section.
| Env Variable | Description | Default |
|---|---|---|
MQTT__HOST |
MQTT broker hostname | localhost |
MQTT__PORT |
MQTT broker port | 1883 |
MQTT__TOPIC_ROOT |
MQTT topic for events | anpr2mqtt |
MQTT__USER |
MQTT username | - |
MQTT__PASS |
MQTT password | - |
LOG_LEVEL |
Python logging level | INFO |
DVLA__API_KEY |
API Key for Gov API Lookup | - |
Expected format: YYYYMMDDHHMMSSmmm_PLATE_VEHICLE_DETECTION.jpg
Example: 20180502174029596_A2GEO_VEHICLE_DETECTION.jpg
A regular expression can be defined to match different file name formats.
Where cameras provide an estimated direction for the vehicle, this can be captured via OCR and included in the response. See OCR for an explanation and examples.
By default, the state will be reset back to unavailable 5 minutes after a detection, while the image will
be left present as record of last known vehicle. This behavior can be changed ( to switch off auto clear,
or change the time lag, or also clear image ) using the autoclear configuration for each event.
- camera: shed
watch_path: /ftp/shedcam
autoclear:
post_event: 360
state: True
image: FalseThe licence plate detection may mis-read or miss some of the characters of the plate. When the result is published to MQTT, both the raw original and corrected versions are provided.
Two mechanisms help with this:
The Levenshtein method is used to compare the plate against a list of known friendly or dangerous
plates in the configuration, subject to a maximum distance tolerance ( number of mismatched characters )
defined by auto_match_tolerance. If its a match for more than one, the plate with least distance is chosen.
Each known plate can be associated with a list of regular expressions and/or plain strings, and these will be checked for every discovered licence plate.
- watchdog - File system monitoring (cross-platform)
- paho-mqtt - MQTT client
- Pillow - Image processing
- pytesseract - OCR for direction detection
- structlog - Structured logging
- niquests - API Client
- requests-cache - API result caching
ANPR2MQTT is free and open sourced under the Apache 2.0 license.
- AutoArm - Automatically arm and disarm Home Assistant alarm control panels using physical buttons, presence, calendars, sun and more
- Remote Logger - OpenTelemetry (OTLP) and Syslog event capture for Home Assistant
- Supernotify - Unified notification for easy multi-channel messaging, including powerful chime and security camera integration.
- Updates2MQTT - Automatically notify via MQTT on Docker image updates, with advanced handling to extract versions and release notes from images, and option to remotely pull and restart containers from Home Assistant. Also available on PyPI