Skip to content

Create eufy camera integration #158730

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
ptarjan wants to merge 21 commits into
base: dev
Choose a base branch
from
Open

Create eufy camera integration #158730

ptarjan wants to merge 21 commits into from

Conversation

@ptarjan
Copy link
Contributor

@ptarjan ptarjan commented Dec 11, 2025 •
edited
Loading

Add a new Eufy Security integration that allows users to view and stream their Eufy Security cameras in Home Assistant. This is basically a glorified RTSP viewer when you don't have their cloud service but it felt useful enough to have the discovery for me.

Docs PR: home-assistant/home-assistant.io#42523

Breaking change

Proposed change

  • Config flow with UI-based setup (email/password authentication)
  • CAPTCHA handling when required by Eufy's API
  • Reauthentication flow for credential updates
  • Camera entity with live streaming support
  • Prefers local RTSP streaming when credentials are configured, falls back to cloud streaming
  • Snapshot support via ffmpeg (with 60-second throttling to prevent overwhelming cameras)
  • Session persistence to avoid unnecessary re-authentication
  • ECDH encryption for secure API communication (v2 Eufy API)

Type of change

  • Dependency upgrade
  • Bugfix (non-breaking change which fixes an issue)
  • New integration (thank you!)
  • New feature (which adds functionality to an existing integration)
  • Deprecation (breaking change to happen in the future)
  • Breaking change (fix/feature causing existing functionality to break)
  • Code quality improvements to existing code or addition of tests

Additional information

  • This PR fixes or closes issue: fixes #
  • This PR is related to issue:
  • Link to documentation pull request:
  • Link to developer documentation pull request:
  • Link to frontend pull request:

Checklist

  • I understand the code I am submitting and can explain how it works.
  • The code change is tested and works locally.
  • Local tests pass. Your PR cannot be merged unless tests pass
  • There is no commented out code in this PR.
  • I have followed the development checklist
  • I have followed the perfect PR recommendations
  • The code has been formatted using Ruff (ruff format homeassistant tests)
  • Tests have been added to verify that the new code works.
  • Any generated code has been carefully reviewed for correctness and compliance with project standards.

If user exposed functionality or configuration variables are added/changed:

If the code communicates with devices, web services, or third-party tools:

  • The manifest file has all fields filled out correctly.
    Updated and included derived files by running: python3 -m script.hassfest.
  • New or updated dependencies have been added to requirements_all.txt.
    Updated by running python3 -m script.gen_requirements_all.
  • For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.

To help with the load of incoming pull requests:
ptarjan and others added 13 commits December 11, 2025 08:47
@ptarjan
Add Eufy Security camera integration
feb4d8c 
This adds a new integration for Eufy Security cameras using the python-eufy-security library. The integration provides: - Config flow with email/password authentication - Reauthentication support - Camera entity with RTSP streaming support - Still image capture from last camera image - Device information including serial, model, and software version - Data update coordinator for periodic refresh Note: Users should create a separate guest account for Home Assistant as the Eufy API does not support concurrent sessions.
@ptarjan
Register eufy_security in generated files
95f98cd 
Add eufy_security to config_flows.py and integrations.json so the integration appears in the Home Assistant UI integration list.
@ptarjan
Replace external library with built-in API client
55fdd82 
The python-eufy-security library has incompatible dependencies (requires aiohttp==3.6.1 while HA uses 3.13.x). This replaces the external library with an internal API client that directly calls the Eufy Security cloud API endpoints. The built-in client provides: - Authentication via /passport/login - Device listing via /app/get_devs_list and /app/get_hub_list - Stream start/stop via /web/equipment/start_stream and stop_stream
@ptarjan
Improve API error handling and add better error messages
51673ca 
- Add proper HTTP headers (User-Agent, Content-Type, Accept) - Handle non-JSON responses (403 blocked) gracefully - Improve error messages to suggest eufy-security-ws add-on - Wrap ClientError exceptions properly
@ptarjan
Use email instead of username in Eufy Security config flow
3c0a6a7 
Changed the config flow to use CONF_EMAIL instead of CONF_USERNAME since Eufy Security accounts use email addresses for authentication. Updated strings.json, config_flow.py, __init__.py and corresponding tests.
@ptarjan
Rewrite Eufy Security to use eufy-security-ws add-on
fcea814 
Changed the integration to connect to the eufy-security-ws WebSocket add-on instead of directly calling the Eufy API. This follows the same approach used by the popular HACS integration. Key changes: - New WebSocket API client that communicates with eufy-security-ws - Config flow now asks for host/port instead of email/password - Integration connects to the add-on which handles Eufy authentication - Supports both RTSP and P2P livestreaming through the add-on - Removed direct API authentication (handled by add-on) The eufy-security-ws add-on must be installed separately from: https://github.com/bropat/hassio-eufy-security-ws
@ptarjan
Revert to direct Eufy API (no add-on required)
e2aa635 
Reverted to the direct Eufy Security cloud API approach instead of requiring the eufy-security-ws add-on. Key changes: - Uses email/password login directly with Eufy's cloud API - Password is MD5 hashed as expected by the API - User-Agent mimics the mobile app to reduce blocking - Supports reauth flow for credential updates - Includes proper error handling for API blocks Note: Eufy may still block some API requests. If you experience connection issues, you may need to use the eufy-security-ws add-on from HACS instead.
@ptarjan
Inline python-eufy-security library for better API handling
f001a00 
Inlined and adapted the python-eufy-security library (by keshavdv/FuzzyMistborn) directly into the integration. This provides: - Token expiration tracking with automatic refresh - Domain switching when Eufy returns an alternative API endpoint - Retry logic on 401 errors (re-authenticates automatically) - Error code mapping (e.g., 26006 = InvalidCredentialsError) - Camera dataclass with properties from camera_info dict - Cleaner request handling with skip_auth option This approach maintains the library ourselves rather than depending on an archived external package.
@ptarjan @claude
Fix lint issues and add RTSP snapshot throttling for Eufy Security
8617c0d 
- Add 60-second throttling for RTSP snapshot captures to prevent overwhelming cameras with connections - Add asyncio.Lock() to prevent concurrent snapshot captures - Add ffmpeg timeout and process cleanup on timeout - Fix lint issues: import ordering, type annotations, logger messages - Move inline imports to top-level for ruff PLC0415 compliance - Use contextlib.suppress for cleaner exception handling 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ptarjan @claude
Align Eufy Security integration with camera integration patterns
11e1568 
- Set _attr_name = None for main camera entity (use device name only) - Add attribute constants (ATTR_*) for state attributes - Prefer local RTSP streaming over cloud when credentials configured - Remove duplicate RTSP constant definitions from config_flow - Remove unused camera entity translation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ptarjan @claude
Fix Eufy Security tests for updated API mocking
9bd6cad 
- Fix conftest.py to mock EufySecurityAPI class instead of non-existent async_login function in __init__ - Add separate mock_config_flow_api fixture for config flow tests - Update test_config_flow.py to use real exception classes from api module - Update test_init.py to mock EufySecurityAPI properly - Fix test_camera.py entity_id (now camera.front_door_camera without suffix since _attr_name = None) - Add ip_address and rtsp_credentials to mock_camera fixture - Update mock_config_entry to include all required data fields 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ptarjan @claude
Add codeowner and expand test coverage for Eufy Security
488c84e 
- Add @ptarjan as codeowner in manifest.json - Add data_description for CAPTCHA steps in strings.json - Expand test_config_flow.py with CAPTCHA, reauth, and options flow tests - Expand test_camera.py with streaming, snapshot, and cleanup tests - Expand test_init.py with session restoration and error handling tests 54 tests passing, covering: - __init__.py: 100% - config_flow.py: 90% - camera.py: 89% - coordinator.py: 87% 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ptarjan @claude
Code review cleanup for Eufy Security integration
9474043 
- Add CaptchaRequiredError handling to coordinator to trigger reauth flow when CAPTCHA is required during data refresh - Remove unused refresh_after decorator from entity.py - Update quality_scale.yaml to mark completed items: - config-flow-test-coverage: done - integration-owner: done - test-coverage: done 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
ptarjan pushed a commit to ptarjan/home-assistant.io that referenced this pull request Dec 11, 2025
@claude
Add Eufy Security integration documentation
e0cb0f9 
Add documentation for the new Eufy Security camera integration which allows users to view and stream their Eufy Security cameras in Home Assistant. Supports config flow setup, RTSP local streaming with cloud fallback, and snapshot support. For home-assistant/core#158730
ptarjan pushed a commit to ptarjan/home-assistant.io that referenced this pull request Dec 11, 2025
@claude
Add Eufy Security integration documentation
a07f95d 
Add documentation for the new Eufy Security camera integration which allows users to view and stream their Eufy Security cameras in Home Assistant. Supports config flow setup, RTSP local streaming with cloud fallback, and snapshot support. For home-assistant/core#158730
ptarjan added a commit to ptarjan/home-assistant.io that referenced this pull request Dec 11, 2025
@ptarjan @claude
Add Eufy Security integration documentation
5218547 
Add documentation for the new Eufy Security camera integration which allows users to view and stream their Eufy Security cameras in Home Assistant. Supports config flow setup, RTSP local streaming with cloud fallback, and snapshot support. For home-assistant/core#158730
@ptarjan @claude
Mark Bronze docs requirements as done for Eufy Security
3a35e1b 
New integrations require Bronze tier which mandates documentation. Marking docs as done - documentation PR to be submitted to home-assistant.io repository. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ptarjan ptarjan mentioned this pull request Dec 11, 2025
Open
8 tasks
@ptarjan @claude
Upgrade Eufy Security to Silver quality scale
0b6f93d 
- Add log-when-unavailable: Log once when API becomes unavailable, log again when connection is restored - Add missing Silver quality scale rules (action-exceptions exempt, docs-configuration-parameters, docs-installation-parameters) - Update manifest to quality_scale: silver 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
ptarjan added a commit to ptarjan/home-assistant.io that referenced this pull request Dec 11, 2025
@ptarjan @claude
Add Eufy Security integration documentation
37b651b 
Add documentation for the new Eufy Security camera integration which allows users to view and stream their Eufy Security cameras in Home Assistant. Supports config flow setup, RTSP local streaming with cloud fallback, and snapshot support. For home-assistant/core#158730
@ptarjan @claude
Add eufy_security to CODEOWNERS
fa76f0f 
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ptarjan ptarjan force-pushed the claude/eufy-cameras-integration-01Fs8qN19PcAcJarnqDUrT7y branch from 370f225 to fa76f0f Compare December 11, 2025 17:47
ptarjan and others added 3 commits December 11, 2025 10:59
@ptarjan @claude
Add comprehensive test coverage for Eufy Security integration
20f6203 
- Add test_coordinator.py with error handling and recovery logging tests - Add camera tests for exception_wrap decorator, snapshot lock, and ffmpeg errors - Add config_flow tests for CAPTCHA step error handling paths - Achieve 100% coverage on coordinator.py, entity.py, camera.py, config_flow.py 73 tests passing with full coverage on all integration files. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ptarjan @claude
Implement Gold-level features for Eufy Security integration
454431e 
- Add diagnostics module for debug data collection with sensitive data redaction - Add reconfigure flow for updating credentials without removing device - Add dynamic device detection when coordinator detects new cameras - Add stale device removal support via async_remove_config_entry_device - Add comprehensive API tests (37 new tests) improving coverage from 25% to 56% - Update quality_scale.yaml with Gold rule status 128 tests passing, 84% overall coverage 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ptarjan @claude
Add comprehensive API tests for Eufy Security integration
b3be226 
- Add 70 tests covering EufySecurityAPI, Camera, Station classes - Test authentication flows: success, CAPTCHA, invalid credentials - Test crypto state save/restore for session persistence - Test async_request with token expiration, 401 retry, custom headers - Test async_update_device_info with encrypted/unencrypted responses - Test async_get_latest_events with various response formats - Test async_login helper function - Test edge cases: encrypted null/dict/string responses, missing device_sn Coverage improved from 25% to 99% for api.py Total integration coverage: 99% (161 tests) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
ptarjan and others added 2 commits December 11, 2025 13:49
@ptarjan @claude
Upgrade Eufy Security integration to Platinum quality scale
f809b41 
- Add eufy_security to strict typing in .strict-typing - Fix positional-only parameter in entity.py exception wrapper - Use typed EufySecurityConfigEntry in config_flow.py - Update manifest.json quality_scale to platinum - Mark all quality scale rules as done/exempt - Add mypy.ini configuration for eufy_security Platinum requirements met: - async-dependency: Uses aiohttp (async) - inject-websession: Uses async_get_clientsession - strict-typing: Full type hints with mypy --strict passing 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ptarjan @claude
Fix mypy strict typing errors in Eufy Security API
8fb3d0e 
Cast dict.get() return values to str to satisfy strict mypy checking for return type annotations. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cla-signed has-tests integration: eufy_security new-integration quality-scale

1 participant

@ptarjan