Draft
Conversation
Comprehensive analysis of integration options including: - Architecture options (Add-on + Integration, MQTT Discovery, Pure Native) - Recommended phased approach from MQTT discovery to full integration - Entity platforms, services, and config flow designs - Deep integration features (camera streams, automations, dashboard cards) - Configuration sync strategies and HACS distribution https://claude.ai/code/session_019LEwJ9ARyfpJqZMqTPpZxn
Comprehensive implementation guide covering: - Phase 1: MQTT Discovery enhancement with HA auto-entity creation - Phase 2: REST API for remote configuration (FastAPI) - Phase 3: Home Assistant Add-on for HA OS/Supervised - Phase 4: Native HA integration with config flow, coordinator, entities - Phase 5: Advanced features (camera streams, Lovelace cards) Includes complete code examples, file structures, testing strategy, migration guides, and acceptance criteria for each phase. https://claude.ai/code/session_019LEwJ9ARyfpJqZMqTPpZxn
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #19 +/- ##
==========================================
+ Coverage 81.53% 82.10% +0.57%
==========================================
Files 64 74 +10
Lines 5247 5919 +672
==========================================
+ Hits 4278 4860 +582
- Misses 969 1059 +90 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
- Switch from MQTT to HA Events API for real-time event push - Add-on users get zero-config via SUPERVISOR_TOKEN - Standalone users provide HA URL + long-lived access token - Bundle PostgreSQL in add-on using s6-overlay for zero-config - Add Phase 2.5: HomeAssistantNotifier plugin implementation - Document s6-overlay service structure (postgres-init, postgres, homesec) - Add features list with P0/P1 priorities - Add user onboarding flows (add-on vs standalone) - Add add-on architecture diagram with bundled PostgreSQL - Document storage layout (/data/postgres, /media/homesec/clips) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Key improvements: - Add complete repository structure under homeassistant/ folder - Add __init__.py with async_setup_entry/async_unload_entry - Add entity.py base class with device_info and helper methods - Add switch.py for camera enable/disable (stops RTSP connection) - Add motion sensor 30s auto-reset timer in coordinator - Add config_version tracking for optimistic concurrency - Add add-on auto-discovery in config flow with fallback - Add stats endpoint (/api/v1/stats) for hub entities - Add health endpoint with response schema - Fix timeline table duplicate entry - Update all file paths to use homeassistant/ folder structure Decisions documented: - Motion sensor: HA integration timer (30s configurable) - Switch behavior: stops RTSP connection when disabled - Add-on discovery: auto-detect + fallback to manual Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Move repository.json to repo root (required for HA add-on discovery) - Fix Add-on Store URL from invalid path to proper repo URL - Update directory tree in section 4.1 to show full path - Ensure consistency between brainstorm and implementation plan Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…ome-assistant-integration-6Kzkl
Update config examples and API models to match the new backend + config pattern from the plugin config boundary cleanup refactor (#18): - Notifiers: type → backend + config - Storage: type → backend + config - Camera: type → source_backend, config → source_config - State store: removed type field (just dsn_env) - Alert policy: per-camera overrides now in alert_policy.config.overrides - Services: updated field names to match new schema Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Critical fixes: - Add prerequisites section for core HomeSec changes needed (enabled field, health monitoring, stats methods) - Fix switch implementation: add error handling, correct field path - Remove unimplemented platforms from v1 (camera, image, select) - Remove services requiring new API endpoints (set_alert_policy, test_camera) Simplifications: - Mark Phase 1 (MQTT Discovery) as out-of-scope for v1 with warning - Simplify services to just add_camera and remove_camera - Update acceptance criteria to reflect v1 scope - Add v1 scope column to brainstorm entity platforms table Code quality: - Add HomeAssistantError import and _LOGGER to switch.py - Add try/catch with proper error messages in switch methods - Add docstring prerequisite note in switch.py Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Restructure the implementation plan for better LLM implementability: - Split monolithic plan into 6 separate phase documents - Add Phase 0 (Prerequisites) for core HomeSec changes - Replace full code implementations with interfaces + constraints - Add clear test expectations with fixture names - Add verification commands and Definition of Done per phase - Clarify list merge semantics as union (not replace) Each phase document is self-contained with: - Goal and dependencies - Interfaces/protocols (not full implementation) - Constraints and file changes - Test expectations (behavioral, Given/When/Then) - Verification steps - Definition of Done checklist Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 0 fixes: - Fix method name: notify() → send() (matches actual interface) - Remove phantom start() method from interface - Move stats methods to Phase 1 (ClipRepository already exists) - Add HealthMonitorConfig for configurable health check interval - Use default no-op pattern so existing notifiers don't break - Add accurate file paths Phase 1 additions: - Add ClipRepository extensions section (list, count, delete methods) - Add ClipRepository test cases Brainstorm doc: - Fix all "lists replace" → "lists merge (union)" for consistency Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Existing notifiers automatically inherit the default no-op implementation of publish_camera_health(), so no changes are needed to MQTT/SendGrid. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
no push based health notification
Simplify API design by using last-write-wins semantics instead of optimistic concurrency. This is acceptable for v1 given the single HA instance assumption and restart-required model. Changes: - Remove config_version from ConfigManager interface - Remove config_version from API request/response models - Remove ConfigVersionConflict exception - Remove 409 Conflict handling - Update constraints and test cases Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove in-memory recent_alerts storage from HA Integration: - HA's built-in logbook already records homesec_alert events - In-memory storage lost on restart - Complex attributes hard to use in dashboards Instead, enhance GET /api/v1/clips with filters: - alerted: bool - only clips that triggered notifications - risk_level: filter by risk level - activity_type: filter by activity type This allows v2 Lovelace cards to query the API directly. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Consolidations:
- Merge Phase 0 into Phase 1 (just CameraConfig.enabled field)
- Remove /api/v1/events endpoint (defer to v2)
- Remove /api/v1/clips/{id}/reprocess (defer to v2)
- Remove homesec_clip_recorded event (defer to v2)
- Remove HA Integration services (defer to v2)
- Simplify options flow (just scan_interval, motion_reset_seconds)
v1 focus: minimal viable HA integration with:
- REST API for camera CRUD and clip queries
- Single homesec_alert event for real-time notifications
- Pull-based health monitoring
- Last-write-wins config semantics
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove POST /api/v1/cameras/{name}/test - health polling provides
the same information reactively within one poll cycle.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Replace `person` binary sensor with `online` in brainstorm to match Phase 4 - Clarify list merge semantics: lists with `name` field merge by key - Items with same name are merged (override fields win) - Items only in base are preserved - Items only in override are added - Add merge_named_lists() interface to Phase 1 https://claude.ai/code/session_019LEwJ9ARyfpJqZMqTPpZxn
- Merge /cameras/{name}/status into /cameras/{name} (returns both config + runtime)
- Rename /api/v1/system/health/detailed to /api/v1/diagnostics
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add note that existing load_config(path) stays unchanged; new multi-file functions are added alongside it. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Changes based on external review: 1. Health endpoint: Return 200 if pipeline running (even if Postgres unavailable). Include postgres status in payload. Prevents restart loops when only DB is down. 2. Remove config merge mechanics: Single config file with backup instead of base + override merge. Deletes just work. Removes deep_merge, merge_named_lists, multi-file loading complexity. 3. Clarify secret handling: Add-on maps options to env vars, config stores *_env names (existing pattern, now explicit in docs). 4. Motion sensors: Clarify they're alert-based (triggered by homesec_alert), not raw motion detection. Intentional behavior. 5. Fix delete_clip boundary: Repository only marks deleted in DB, returns clip data. API route coordinates storage deletion. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1. Remove event_prefix customization - always use "homesec" to ensure compatibility with HA integration which listens for homesec_alert 2. Update decision snapshot - /health returns 200 (degraded) when Postgres down; data endpoints return 503 3. Use Supervisor API for add-on discovery - detect_addon() now uses Supervisor API instead of probing localhost:8080 4. Clarify add-on options are bootstrap-only - options generate initial config, then API owns all changes. Avoids split-brain. 5. Sync Key Interfaces - ClipRepository methods now show ClipStateData return types Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…tation details Added response models: - StatsResponse (clips_today, alerts_today, cameras, uptime) - ConfigResponse (full config as dict) - DiagnosticsResponse (detailed component status) - ClipResponse/ClipListResponse (clip data for API) Added implementation notes: - Camera health comes from existing ClipSource.is_healthy()/last_heartbeat() - FastAPI replaces existing aiohttp HealthServer - /system/restart uses SIGTERM (existing signal handler) - API server lifecycle in Application.run() Updated file changes: - Remove src/homesec/health/ (replaced by FastAPI) - Remove aiohttp dependency if unused elsewhere Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1. StateStore extensions: New read methods (list_clips, get_clip, count_clips_since, count_alerts_since, mark_clip_deleted) added to StateStore interface. ClipRepository delegates to these. All DB access goes through StateStore for consistency. 2. Auth bypass: /health and /diagnostics are public (no auth). Allows watchdog and monitoring tools to check health without token. 3. DB-down behavior: Clear 503 rule for non-health endpoints. /health and /diagnostics return 200 with degraded status. All other endpoints return 503 with DB_UNAVAILABLE error. Updated file changes to include interfaces.py and state/postgres.py. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- ClipResponse.status: Use actual ClipStatus enum values (queued_local, uploaded, analyzed, done, error, deleted) - CameraStatus: Remove non-existent fields (frames_processed, errors_recent). Only use existing data from ClipSource. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
lan17
force-pushed
the
claude/homesec-home-assistant-integration-6Kzkl
branch
from
286272b to
dbf27fb
Compare
Implement HA Events API notifier with supervisor/standalone auth. Normalize detected_objects from filter results and pass through alerts. Add docs/examples plus high-coverage tests for notifier behavior.
- Add add-on scaffolding (manifest, repository.json, docs, translations, assets) - Add Dockerfile/build config, ingress config, and s6 services for Postgres/HomeSec - Bootstrap config generation and bundled Postgres password handling - Add shellcheck tooling and CI lint integration for add-on scripts
lan17
force-pushed
the
claude/homesec-home-assistant-integration-6Kzkl
branch
from
40a523b to
2519814
Compare
Add Home Assistant custom integration with config flow, coordinator, and entities. Add HA integration tests and harness dependencies. Wire HA lint/tests into Makefile and CI; adjust pytest settings for HA plugin isolation.
lan17
force-pushed
the
claude/homesec-home-assistant-integration-6Kzkl
branch
from
2519814 to
46e299e
Compare
lan17
changed the title
lan17
changed the title
Comprehensive onboarding documentation for running HomeSec alongside Home Assistant Docker. Covers quick start, docker-compose setup, network configurations, camera setup, and troubleshooting. https://claude.ai/code/session_019LEwJ9ARyfpJqZMqTPpZxn
…ome-assistant-integration-6Kzkl
…ome-assistant-integration-6Kzkl
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.