tapo-monitoring

A lightweight, config-driven reliability and alerting stack for TP-Link Tapo PTZ cameras. It combines camera control, on-device detection events, event-aligned frame selection, optional local scoring, Telegram delivery and layered health monitoring in one tested Python daemon.

Project status: the core daemon and alert pipeline are operational and validated on the C560WS, and the hubpoll battery-camera path is validated end to end against real hub-backed hardware. The Camera Digital Twin (layered health, drift and allow-listed self-healing) and the Shadow Detection Auditor run in production behind opt-in flags; a nightly recorder scan measures camera miss candidates. Camera models and firmware differ; unsupported capabilities degrade to unknown instead of being guessed.

Tested cameras

Other Tapo models with third-party access and getEvents may work; what we learned about the local API across models is in the local API reference. Own a model not listed here? Run tapo-monitor report and share the anonymized file: see camera reports.

What's new in 0.8

• Home Assistant over MQTT — an opt-in, publish-only bridge with MQTT discovery: person and motion sensors, reachability, privacy mode, "detection off", health and the last alert per camera, for automations (MQTT and Home Assistant).
• Your camera model, supported from your report — tapo-monitor report writes an anonymized report of what your camera answers; share it through the Camera report issue form (camera reports).

What's new in 0.7

• Told when a camera stops watching — one Telegram message when privacy mode, motion or person detection is switched off or back on (privacy_notice, detection_notice), and follow_app_notifications to go quiet while the Tapo app's notifications are off (configuration).
• One visit, one message — an SD follow-up is held to the cooldown when the camera already alerted live.
• Dual-lens C545D — per-lens self-heal, the lens and the number of people in the caption, and a client-side deny-list for the calls that drop the camera's API.
• Collect-only mode — telegram_alerts: false records alerts without sending them.

What's new in 0.6

• Quality per visit, not per frame — label-stats groups frames into incidents and reports missed visits and the delay to the first alert by delivery path (incidents).
• Labelling workflow — a frame collector, a teacher model that pre-labels the easy frames and a local labelling page (labeling); a small random sample of below-threshold frames keeps possible misses in the queue.
• Opt-in alert tuning — a separate scorer.night_threshold, and a sampler.hold_expiry policy for held frames whose corroboration never came (configuration).
• Faster follow-ups — recording follow-ups are read sooner and look at the event's opening seconds first, frames are scored concurrently and while ffmpeg extracts them, and SD/recording reads run off the main loop so one camera's card no longer stalls the others.
• The photo worth sending — sd_frame_pick: largest sends the frame where the person is closest, within a blur guard.
• Disk and card health — the daily digest reports the frame logs' disk use and warns when the disk runs low; a counterfeit SD card (dilatant_suspect) is flagged by the digital twin.
• Dual-lens C545D support, and a public local API reference.

Details and upgrade notes: CHANGELOG.

Why this project exists

pytapo provides camera API operations. HomeAssistant-Tapo-Control exposes a broad Tapo feature set in Home Assistant. Frigate is a complete local AI NVR. This project occupies a narrower space:

• run on modest hardware without requiring continuous local video inference;
• use the camera's on-device AI as the primary event source;
• encode Tapo-specific reliability knowledge such as login lockouts, sequential requests, SmartTrack ordering and SD recording freshness;
• treat an alert as successful only after the notification is delivered;
• distinguish network, API, events, RTSP and storage failures;
• measure desired configuration drift and, nightly, camera detection misses.

It is not a full NVR, video-management UI or replacement for Frigate. An optional local recorder and scorer can complement the daemon, but neither is required for the basic flow.

Highlights

• One fleet daemon — multiple cameras, one validated YAML configuration and one state machine per camera.
• Low-login event polling — getEvents is polled every few seconds on an existing session while reconnect/control runs on a slower interval.
• Firmware-safe camera control — day/night policy, people-only SmartTrack, presets, rain gating, sensitivity control and optional ONVIF soft pan limits.
• Hardware-aligned optics & safety — on-sensor Lens Distortion Correction (LDC) straightens wide-angle 4K frames for sharper peripheral YOLO scoring, tamper monitoring is self-healed every control pass, and white floodlight activation duration scales down to polite 30 s pulses instead of the 5-minute firmware default.
• On-device face intelligence — learn-face CLI helper captures on-device face enrollment events, and faces.ignore_known quiets alerts for familiar household members.
• Reliable event media — live RTSP first, then an event-time SD-card or local-recorder follow-up when the first frame misses the subject; the subject zoom can be cropped from a native-resolution grab so a distant figure stays legible.
• Battery cameras on a hub — hubpoll reads a sleeping camera's detections off the hub it records to; with a scorer, the sharpest accepted frame is selected from the stored clip. A go2rtc sidecar supplies a live fallback when the clip cannot be decoded.
• Optional local scorer — a small HTTP YOLO service can gate frames and return subject boxes; Groq remains optional caption enrichment.
• Confirmed Telegram semantics — failed sends do not arm cooldowns; recovery, SD and sampler paths remain retryable.
• It tells you when it stops working — a dead-man's switch outside the main loop reports a daemon whose every tick is failing, because silence otherwise looks exactly like a quiet night.
• Event-API watchdog — separates getEvents failures from network reachability, reports recovery and can request one bounded API reboot per failure episode.
• Daily fleet heartbeat — one digest a day says the fleet is alive: cameras, tick, scorer, recorder, alert counts. It claims OK only for what it checked, and any failed check removes the headline.
• Verifiable deploys — releases ship as fingerprinted directories behind a symlink, so rollback is re-pointing the link; an opt-in localhost-first JSON status endpoint answers "how is this host doing" without log parsing.
• Camera Digital Twin — redacted safe-getter snapshots, desired/actual drift and layered health without a second login loop.
• Shadow Detection Auditor — a private, media-free SQLite ledger correlates camera events with independent scorer/recorder observations.
• One owner for the motor — preset recalls and the pan-limit guard ask one arbiter before moving, so the guard never fights a tracked subject or a lens parked by privacy mode.
• Restart-safe, traceable alerts — queued alerts and cooldowns survive a deploy; every alert carries an incident ID you can follow with tapo-monitor incident, and tapo-monitor replay checks a config change against a recorded night before it ships.
• Thresholds from your own frames, not guesswork — a collector keeps every host's sent and held frames beyond their retention, a larger teacher model labels the frames it and the scorer agree on, and a local page shows you only the disagreements. On the first pilot pass this turned 815 frames into 86 clicks, and showed that most frames held back for corroboration were real people — the kind of finding a threshold tweak by feel never produces.

See the complete capability catalog and architecture.

Quick start

Requirements: Python 3.10+, ffmpeg, a supported Tapo camera with third-party access, and camera/RTSP credentials created in the Tapo app.

Install the released package from PyPI (add extras as needed: [mqtt] for Home Assistant, [scorer] for the local scorer, [onvif] for the pan limit):

python3 -m venv ~/tapo-monitor/.venv
source ~/tapo-monitor/.venv/bin/activate
pip install tapo-monitor            # or: pip install 'tapo-monitor[mqtt]'

curl -fsSLo cameras.yaml \
  https://raw.githubusercontent.com/PeterkoCZ91/tapo-monitoring/main/cameras.example.yaml
$EDITOR cameras.yaml

For development, work from a clone instead:

git clone https://github.com/PeterkoCZ91/tapo-monitoring.git
cd tapo-monitoring

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

cp cameras.example.yaml cameras.yaml
$EDITOR cameras.yaml

Then, either way:

export TELEGRAM_TOKEN=...
export TELEGRAM_CHAT_ID=...
export CAM_USER=...
export CAM_PASSWORD=...
export CAM_RTSP_USER=...
export CAM_RTSP_PASSWORD=...

tapo-monitor check cameras.yaml
tapo-monitor run cameras.yaml

Prefer containers? docker compose with the shipped Dockerfile, docker-compose.example.yml and tapo.env.example gets the same daemon running without a local Python setup, on amd64 or a 64-bit Raspberry Pi — see Docker.

The YAML contains environment-variable names, never secret values. cameras.yaml, .env files and runtime media are git-ignored. Start from the configuration guide, not by enabling every optional feature.

Architecture at a glance

flowchart LR
    CAM["Tapo camera"] -->|"getEvents"| DAEMON["tapo-monitor daemon"]
    CAM -->|"RTSP / SD recording"| MEDIA["frame selection"]
    DAEMON --> MEDIA
    MEDIA -->|"optional HTTP"| SCORE["local scorer"]
    SCORE --> DECIDE["alert decision"]
    MEDIA --> DECIDE
    DECIDE -->|"optional caption"| GROQ["Groq"]
    DECIDE --> TG["Telegram"]

    DAEMON --> HEALTH["uptime + layered health"]
    DAEMON --> TWIN["Digital Twin + drift"]
    DAEMON --> LEDGER["Shadow audit ledger"]
    REC["independent recorder/scorer"] --> LEDGER

The fast event path and slower control/reconnect path are intentionally separate. A camera that is pingable can still have a broken API, stale events or failed RTSP, so those layers are observed independently. See Architecture for timing, failure containment and persistence.

Event decision flow

1. Poll getEvents and decode the firmware's events_1 bitmask.
2. Treat a camera-confirmed person differently from bare motion.
3. Capture a live RTSP frame and optionally score it locally.
4. If a confirmed event's frame is empty, queue an event-aligned SD/recorder follow-up.
5. Optionally crop and caption the chosen frame.
6. Send Telegram and advance cooldown state only after confirmed delivery.
7. Record the branch in the structured audit stream and optional private ledger.

This separation matters: a camera event says that something happened, not that the first available frame contains the subject.

CLI

Optional local scorer

Install scorer dependencies and run the stateless HTTP service on the same host or a stronger machine:

pip install 'tapo-monitor[scorer]'   # from a clone: pip install -e ".[scorer]"
python -m tapo_monitor.scorer_service --model /path/to/model.onnx --port 8766

Then set the camera's scorer.url. If the scorer is unavailable, the alert pipeline degrades to unfiltered passthrough rather than silently dropping camera-confirmed people. The configured threshold gates on person confidence; animal confidence never sends an alert by itself, but a confident animal score marks the caption with a paw so a dog walker is not indistinguishable from a lone figure. Tiled inference and optional subject cropping help with distant subjects in wide views. The scorer also exposes aggregate-only runtime counters at /metrics for operational monitoring.

Two opt-in calibration aids help tune thresholds by frame rather than by guesswork: an archive of every photo sent to Telegram (TAPO_SENT_LOG_DIR, self-pruning) and python -m tapo_monitor.scene_probe, which scores a live frame internally without alerting. See Operations. To calibrate from ground truth, tools/collect_frames.sh gathers every host's frames into one dataset, tapo-monitor autolabel pre-labels the easy ones with a larger teacher model and tapo-monitor label serves the rest on a local page; label-stats then reports the false-alarm rate, the misses and the best-separating threshold, by day and night with --config, and per incident how many visits with a person got no alert and how late the first alert came on each delivery path (Labeling).

Home Assistant (MQTT)

An opt-in, publish-only MQTT bridge announces every camera to Home Assistant through MQTT discovery: person and motion binary sensors, reachability, privacy mode, "detection off", twin health and the last alert's time and score, plus the daemon's own availability. Alert photos are published only with publish_images: true. Install the extra and add the block:

pip install 'tapo-monitor[mqtt]'

mqtt:
  host: broker.example.org
  user_env: MQTT_USER
  password_env: MQTT_PASSWORD

The bridge runs on its own thread with a bounded queue, so a slow or unreachable broker never delays an alert. Entities, topics and an example automation: docs/mqtt.md.

Safety and privacy

• No credentials, coordinates, camera addresses or face mappings belong in the repository.
• Runtime state is stored under the XDG state directory with private file permissions.
• Digital Twin snapshots are recursively redacted and use a fixed safe-getter allow-list.
• The Shadow ledger stores timestamps and normalized metadata, never frames or stream URLs.
• Siren, floodlight and speaker actuators are intentionally not implemented.
• Repeated authentication failures use backoff because affected firmware can lock out the source address.

Do not run multiple camera-control integrations against the same device unless you understand the session and sequential-request limitations.

Documentation

Development

pytest -q
ruff check .

Pure planning, classification, drift, matching and persistence logic is tested without camera hardware; I/O collaborators are injected in tests. CI runs tests and Ruff on Python 3.12 and 3.13 (the versions the fleet runs; requires-python stays 3.10+) for every push to main and every pull request.

See Contributing, Security, the changelog and the MIT license.