Add eGauge integration#155279
Merged
Merged
Conversation
Create basic skeleton for eGauge energy monitor integration: - manifest.json with Bronze quality scale and local polling - Empty __init__.py placeholder - Constants file with domain and logger - Strings structure for config flow Part of implementation for eGauge integration supporting power and energy sensors for Home Assistant Energy Dashboard.
Implement user configuration flow for eGauge devices: - User step with host, username, password inputs - Connection validation using get_device_serial_number() - Unique ID from device serial number - Error handling for authentication and connection failures - Reauthentication flow for credential updates - Update strings.json with reauth step Uses async_get_clientsession for httpx client following Platinum quality scale best practices.
Create data structures for eGauge integration: - EgaugeData dataclass containing measurements, counters, and register info - Type alias EgaugeConfigEntry for type-safe config entry access These models support the coordinator pattern where static and dynamic data are handled separately, and allow for extensible sensor types.
Implement coordinator that manages all data fetching: - Fetches static device info (serial, hostname, registers) on first refresh - Fetches dynamic data (measurements, counters) every 30 seconds - Type-agnostic design - fetches ALL register types for extensibility - Proper exception handling for auth failures and connection errors Coordinator owns all data fetching responsibility, keeping __init__.py clean and following separation of concerns best practices.
Create shared base entity for all eGauge sensors: - Inherits from CoordinatorEntity for data management - Uses has_entity_name pattern for entity naming - Creates DeviceInfo with serial-based identifiers - Uses hostname for user-friendly device name - Generic constructor accepts register name and info for reusability This base class will be extended by all sensor types. Also fixes type hints in coordinator for serial_number and hostname to be non-optional (they're populated on first refresh before entities are created).
Implement sensor platform with extensible architecture: - Mapping-based SENSOR_TYPES for easy addition of new types - EgaugePowerSensor for instantaneous power (W) - EgaugeEnergySensor for cumulative energy (kWh) - Energy sensors support Energy Dashboard with TOTAL_INCREASING - Converts watt-seconds to kWh (divide by 3,600,000) - Gracefully ignores unsupported register types Power registers get both instantaneous and cumulative sensors. Future sensor types can be added by creating a class and adding to SENSOR_TYPES mapping - no coordinator changes needed.
Add integration entry point with clean architecture: - async_setup_entry creates EgaugeJsonClient with async_get_clientsession - Coordinator handles all data fetching (static and dynamic) - Runtime data stores coordinator for platform access - async_unload_entry cleanly unloads sensor platform - No exception handling needed - coordinator handles all errors Follows separation of concerns: __init__.py is simple orchestration, coordinator owns data fetching logic.
Create quality_scale.yaml documenting Bronze tier compliance: - config-flow: UI configuration implemented - entity-unique-id: All sensors have serial-based unique IDs - test-before-configure: Config flow validates connection - test-before-setup: Coordinator tests connection on first refresh - action-setup: Exempt (no custom actions) Integration meets all Bronze quality scale requirements.
Create test fixtures and mocks: - MockConfigEntry with realistic eGauge configuration - mock_egauge_client fixture with complete API mocking - Includes power registers (Grid, Solar) and unsupported type (Temp) - Realistic test data: measurements in W, counters in Ws - init_integration fixture for easy test setup Test data designed to verify both sensor creation and graceful handling of unsupported register types.
Comprehensive config flow test coverage: - test_user_flow: Successful device setup - test_user_flow_errors: Parametrized error handling (authentication, connection, unknown errors) - test_user_flow_already_configured: Duplicate prevention - test_reauth_flow: Credential update flow - test_reauth_flow_errors: Reauth error handling Achieves 100% config flow coverage with error recovery testing.
Add sensor platform tests with snapshot testing: - Verifies all sensor entities via snapshot_platform - Validates device creation with correct attributes - Confirms all entities assigned to device - Checks only power sensors created (temperature ignored) - Tests that 4 sensors total (2 power + 2 energy) Snapshots will be generated on first test run.
Test integration lifecycle and error handling: - test_setup_success: Verifies successful integration setup - test_setup_connection_error: Tests retry on connection failure - test_setup_auth_error: Tests auth error handling - test_unload_entry: Validates clean unload Covers coordinator initialization, error states, and proper config entry state transitions.
Update imports to use correct module paths: - EgaugeJsonClient from egauge_async.json.client - RegisterInfo, RegisterType from egauge_async.json.models - EgaugeAuthenticationError, EgaugeParsingException from egauge_async.json.client - Replace EgaugeConnectionError with httpx.ConnectError (library uses httpx exceptions) Fixes compatibility with egauge-async library structure.
Still need to add docs.
Add comprehensive functional tests beyond structural snapshots: Sensor value tests (test_sensor.py): - test_power_sensor_values: Verify power sensors show correct W values - test_energy_sensor_values: Verify energy sensors and Ws→kWh conversion Coordinator tests (test_coordinator.py): - test_coordinator_initial_refresh: Verify static/dynamic data fetch - test_coordinator_periodic_update: Test 30s interval updates - test_coordinator_auth_error: Test auth failure and reauth flow - test_coordinator_connection_error: Test connection errors and recovery Tests now verify actual sensor values, unit conversions, error handling, and data refresh behavior. Coverage improved to 99% (25 tests passing). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
zweckj
requested changes
Dec 1, 2025
zweckj
reviewed
Dec 3, 2025
zweckj
reviewed
Dec 6, 2025
Member
zweckj
left a comment
zweckj
left a comment
There was a problem hiding this comment.
two nits from my end, otherwise I'm happy
Contributor
Author
|
The test failure seems to be coming from an entirely different integration. Maybe just a flaky test. |
zweckj
approved these changes
Dec 8, 2025
Member
zweckj
left a comment
zweckj
left a comment
There was a problem hiding this comment.
I'm happy, let's see if Joost has last remarks
joostlek
approved these changes
Dec 8, 2025
| identifiers={(DOMAIN, coordinator.serial_number)}, | ||
| name=coordinator.hostname, | ||
| manufacturer=MANUFACTURER, | ||
| model=MODEL, |
Member
There was a problem hiding this comment.
Is there a way to figure out which model it is?
Member
|
@neggert mind sending me a message on Discord? |
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
3 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.
Proposed change
This PR adds an integration for eGauge energy meters. These meters are commonly installed alongside residential solar installations. They provide real-time and historical data around energy usage, but also support other types of sensors such as temperature.
This PR implements power and energy sensors only, with other sensor types left for future work.
Type of change
Additional information
This integration is intended to eventually replace the egauge custom component, which I have maintained for several years. This is a complete re-write using eGauge's newer JSON-based API which will eventually replace the XML-based API that the custom component is based on.
The integration uses the egauge-async library that I've created, since the official egauge-python library does not support async.
Checklist
ruff format homeassistant tests)If user exposed functionality or configuration variables are added/changed:
If the code communicates with devices, web services, or third-party tools:
Updated and included derived files by running:
python3 -m script.hassfest.requirements_all.txt.Updated by running
python3 -m script.gen_requirements_all.To help with the load of incoming pull requests: