homebridge-sense-energy-monitor/CHANGELOG.md

Enhanced Homebridge plugin for Sense Home Energy Monitor with comprehensive API integration and real-time monitoring

# Changelog

All notable changes to the Homebridge Sense Energy Monitor plugin will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).


## [3.0.1] - 2026-08-03

### Fixed
- HomeKit "Serial Number supplied illegal value: number instead of string" warning when the monitor ID was loaded from a v2.x-written auth cache (v2 stored it as a number; it is now always coerced to a string).

## [3.0.0] - 2026-08-03

### Breaking Changes
- **Node.js >= 20.18.0 required** (plugin is now ESM/TypeScript; Homebridge 1.8+ or 2.x)
- **Verbose logging now defaults to off.** Set `verbose: true` to surface detailed logging at info level, or run `homebridge -D` for debug output.
- Removed non-functional config options: `includeSolar`, `includeDevices`, `maxDevices` (they had no effect in v2.x; old configs still load fine — the keys are simply ignored)

### Fixed
- **Accessories now persist across restarts.** The v2.x "nuclear option" unregistered and recreated all accessories on every Homebridge restart, wiping HomeKit room assignments, scenes, and automations each time. The accessory is now restored from the Homebridge cache (the accessory UUID is unchanged, so existing installs keep their accessory on first boot of 3.0.0).
- **Authentication no longer churns every 15 minutes.** The plugin now trusts its cached session, uses Sense's token renew endpoint with the (previously discarded) refresh token on HTTP 401, and only falls back to a full re-authentication — with a fresh TOTP code when MFA is on — if renewal fails.
- **Trend data actually works.** Daily consumption/production now comes from the real trends endpoint; v2.x polled the status endpoint for fields it never contained (and polled it redundantly alongside the WebSocket).
- **Resource leaks closed.** All timers are cleared on shutdown; the WebSocket now has stale-connection detection (heartbeat + ping/pong) and can no longer reconnect forever with an expired token.
- Fixed device/polling interval config values being applied with wrong units in periodic logging.

### Added
- **Eve app live power readings**: Consumption (W), Voltage (V), Electric Current (A), and Total Consumption (kWh) custom characteristics on the outlet service. Total Consumption is a monotonic lifetime counter that survives restarts.
- Unit tests (`npm test`): RFC 6238 TOTP vectors and a mocked-API suite that pins the two-step MFA flow and the 401 → renew → re-authenticate lifecycle.
- `scripts/smoke-api.mjs` for manual end-to-end API verification with real credentials (via environment variables).

### Changed
- Complete migration from a single-file CommonJS `index.js` to TypeScript (`src/`, ESM, strict mode) following the official Homebridge plugin template; ESLint 9 flat config.
- Hardening: the auth cache (`sense_auth.json`) is written with owner-only permissions (0600); TOTP codes and tokens are never logged; npm package now ships only `dist/` and `config.schema.json`.
- Realtime WebSocket updates are throttled to one HomeKit/history update per 5 seconds.

## [2.4.1] - 2025-10-03
-**Homebridge v2 Compatibility**: Corrected Warning with 2.0 compatibility

## [2.4.0] - 2025-08-10

### Fixed
- **MFA Persistence Issue**: Fixed TOTP authentication failing on re-authentication
  - Changed from static 6-digit code to TOTP secret key configuration
  - Implemented dynamic TOTP code generation using secret key
  - Plugin now generates fresh codes automatically for each authentication
  - Updated configuration from `mfaCode` to `mfaSecret`

### Changed
- **Verbose Logging**: Now enabled by default for better troubleshooting
- **Configuration Cleanup**: 
  - Removed `individualDevices` option (feature was causing callback conflicts)
  - Kept `includeDevices` and `maxDevices` for future use
  - Simplified configuration options to focus on working features
- **Code Cleanup**:
  - Removed disabled individual device accessories code
  - Cleaned up unused functions and handlers
  - Improved code maintainability

### Added
- **TOTP Test Utility**: New `test-totp.js` script to verify TOTP code generation

## [2.3.4] - 2025-08-09

### Fixed
- Minor bug fixes and improvements

## [2.3.3] - 2025-08-09

### Fixed
- Authentication improvements

## [2.3.2] - 2025-08-08

### Fixed
- **MFA Authentication Flow**: Implemented correct two-step MFA authentication
  - Fixed API parameter name (`totp` instead of `totp_code`)
  - Implemented proper two-step flow: initial auth → MFA token → TOTP validation
  - Added support for `/authenticate/mfa` endpoint
  - Enhanced error handling to extract MFA tokens from error responses
- **Updated test-mfa.js**: Now demonstrates correct two-step MFA flow

## [2.3.0] - 2025-08-08

### Added
- **Multi-Factor Authentication (MFA/2FA) support**
  - New `mfaEnabled` configuration option
  - New `mfaCode` configuration field for TOTP codes
  - Enhanced error messages for MFA-related authentication failures
  - Test script (`test-mfa.js`) for validating MFA authentication
- **Documentation improvements**
  - This CHANGELOG file for better version tracking
  - Accurate feature descriptions reflecting real HomeKit capabilities
  - Clear warnings about HomeKit energy monitoring limitations

### Changed
- **Authentication system enhancements**
  - Updated SenseAPI constructor to accept MFA parameters
  - Modified authentication flow to include TOTP codes when MFA is enabled
  - Enhanced configuration schema with MFA options and validation
- **Documentation cleanup**
  - Removed misleading claims about "comprehensive HomeKit energy monitoring"
  - Updated feature descriptions to reflect actual capabilities
  - Clarified that detailed power data requires Eve app, not Apple Home
  - Honest comparison table showing real limitations vs competitors

### Fixed
- Improved error handling for authentication failures
- Better user guidance when MFA configuration is required

## [2.1.1] - 2024

### Fixed
- Nuclear reset system to eliminate callback conflicts
- Prevented "callback already called" errors
- Improved cached accessory management

### Changed
- Automatically removes problematic cached accessories on startup
- Creates fresh accessories every time to prevent conflicts
- Enhanced characteristic handlers with proper error handling

## [2.1.0] - 2024

### Added
- Verification-ready architecture meeting all Homebridge requirements
- Dynamic platform architecture (required for verification)
- Node.js v20+ support (latest LTS requirement)
- Comprehensive error handling with no unhandled exceptions
- Storage directory compliance for all cached data
- Smart authentication caching with automatic token refresh
- Robust WebSocket management with exponential backoff reconnection
- Comprehensive data validation preventing undefined characteristic values
- Memory leak prevention with proper cleanup on shutdown

### Changed
- Major architectural shift from accessory to platform plugin
- Complete rewrite of core functionality
- Enhanced reliability and stability

## [2.0.0] - 2024

### Breaking Changes
- Changed from accessory to platform plugin type
- New configuration format required
- Accessories will be recreated (may need re-adding to HomeKit rooms/scenes)

### Added
- Dynamic platform support
- Automatic device discovery
- Enhanced WebSocket real-time monitoring
- Solar power monitoring support
- Individual device tracking (50+ devices)
- Daily, weekly, monthly, and yearly consumption tracking
- Eve App support with historical data
- FakeGato history integration

### Changed
- Complete plugin rewrite
- Improved API integration
- Better error handling and recovery
- Enhanced performance optimization

## [1.0.0] - Initial Release

### Added
- Basic Sense Energy Monitor integration
- Real-time power monitoring
- HomeKit compatibility
- Basic authentication support
- Simple polling mechanism

---

## Version Naming Convention

- **Major** (X.0.0): Breaking changes requiring configuration updates
- **Minor** (0.X.0): New features, backwards compatible
- **Patch** (0.0.X): Bug fixes and minor improvements

## Support

For issues, feature requests, or questions, please visit:
https://github.com/seeloesix/homebridge-sense-energy-monitor/issues