violet-hass

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[0.2.0] - 2025-11-20

🎉 Semantic Versioning Adoption

This release marks the transition to clean Semantic Versioning (SemVer 2.0.0) for better version clarity and HACS compatibility.

✨ Added

• Semantic Versioning: Migrated from 0.1.0-8 to 0.2.0 (SemVer 2.0.0 compliant)
• Complete 3-State Switch Support: Enhanced state handling with State 4 (Manual Forced ON)
• PVSURPLUS Parameter Support: Full integration of PV surplus functionality
• Enhanced DMX Scene Control: Support for 12 DMX lighting scenes
• Extended Sensor Coverage: 147 API parameters fully mapped
• Complete Extension Relay Support: EXT1/EXT2 relay banks
• Multi-language support: German/English translations
• Comprehensive automation blueprints: Ready-to-use automations
• Advanced service implementations: 7+ custom services

🔧 Fixed

• STATE_MAP: Now includes State 4 (Manual Forced ON)
• PVSURPLUS: Added to SWITCH_FUNCTIONS mapping
• COVER_STATE_MAP: Supports both string and numeric states
• Thread Safety: Optimistic updates use local cache variables
• Logging Optimization: Smart failure logging prevents log spam

🚀 Improved

• Release Workflow: Updated for clean SemVer tags (v0.2.0, v0.2.1, etc.)
• Version Management: Centralized version info with automatic updates
• Documentation: Updated examples to use SemVer format

[0.1.0] - 2024-XX-XX

🎉 Initial Release

✨ Added

• Core Integration
  • Full API integration with Violet Pool Controller
  • Dynamic entity creation based on available features
  • Real-time data synchronization with configurable polling
  • Robust error handling with retry mechanisms
  • Local-only communication (no cloud required)
• Entity Support
  • Climate Entities: Pool heater and solar absorber control
  • Sensors: Temperature, pH, ORP, chlorine, pressure, water level
  • Binary Sensors: Pump status, heater state, cover position
  • Switches: Pump, lighting, dosing systems, backwash
  • Cover: Automatic pool cover control
  • Number: Target value controls for pH, ORP, chlorine
• Custom Services
  • turn_auto - Switch devices to automatic mode
  • set_pv_surplus - Activate solar surplus mode
  • manual_dosing - Manual chemical dosing control
  • set_temperature_target - Climate control service
  • set_ph_target - pH target value setting
  • set_chlorine_target - Chlorine target setting
  • trigger_backwash - Manual backwash activation
  • start_water_analysis - Water testing initiation
  • set_maintenance_mode - Maintenance mode control
• Smart Automation Blueprints
  • Temperature Control: Intelligent heating with solar priority
  • pH Management: Automated chemical balancing with safety limits
  • Cover Control: Weather-aware automatic cover operation
  • Backwash Automation: Pressure and time-based filter cleaning
• Configuration Features
  • UI-only configuration (no YAML required)
  • Multi-step setup wizard
  • Feature selection and customization
  • Advanced options for polling and timeouts
  • Pool-specific settings (size, type, disinfection method)
• Developer Features
  • Comprehensive logging and debugging
  • Data update coordinator for efficient API usage
  • Modular entity structure for easy expansion
  • Unit tests and validation
  • Python 3.11+ compatibility
  • Home Assistant 2024.6+ support

🌍 Internationalization

• Complete German (DE) translations
• English (EN) as default language
• Service descriptions and UI strings
• Error messages and notifications

🔧 Technical Implementation

• API Client: Async HTTP client with session management
• Entity Management: Dynamic creation based on controller features
• State Management: Intelligent state mapping and conversion
• Error Handling: Comprehensive exception handling with user feedback
• Performance: Optimized polling with coordinator pattern
• Security: Support for SSL/TLS and authentication

🤖 Blueprint Features

• Temperature Control:
  • Day/night temperature scheduling
  • Solar heating priority logic
  • Energy-efficient heating strategies
  • Weather-based adjustments
• pH Control:
  • Automatic pH balancing (6.8-7.8 range)
  • Safety limits for dosing
  • Pump-dependent dosing logic
  • Daily dosing counters and limits
• Cover Control:
  • Time-based open/close scheduling
  • Weather protection (rain, wind, cold)
  • Pump interlock safety features
  • Manual override capabilities
• Backwash Control:
  • Pressure-based triggering
  • Scheduled maintenance cycles
  • Runtime-based activation
  • Full wash/rinse cycle automation

📱 User Experience

• Easy installation via HACS or manual setup
• Intuitive configuration wizard
• Clear error messages and troubleshooting guides
• Comprehensive documentation with examples
• Dashboard cards and automation examples

🛡️ Safety Features

• Connection timeout and retry handling
• Chemical dosing safety limits
• Equipment interlock protections
• Maintenance mode support
• Error logging and reporting

🔧 Technical Details

• Minimum Requirements:
  • Home Assistant 2024.6.0+
  • Python 3.11+
  • Violet Pool Controller with API access
• Dependencies:
  • aiohttp >= 3.8.0
  • voluptuous (included with HA)
  • Standard Home Assistant libraries
• Supported Features:
  • All standard Violet controller functions
  • Extension modules and digital inputs
  • DMX lighting control
  • PV surplus integration
  • Multi-zone temperature control

📊 Statistics

• Code: 3000+ lines of Python code
• Entities: 50+ dynamic entity types
• Services: 9 custom services
• Blueprints: 4 automation templates
• Languages: 2 complete translations
• Tests: Comprehensive test coverage

🙏 Acknowledgments

• Home Assistant development team
• PoolDigital for excellent hardware
• Community beta testers
• Integration blueprint template by @Ludeeus

---

[Future Releases]

🔮 Planned Features (v0.2.0)

• Enhanced Analytics:
  • Historical data tracking
  • Energy consumption monitoring
  • Chemical usage statistics
  • Maintenance predictions
• Advanced Automation:
  • AI-powered optimization
  • Weather forecast integration
  • Energy price optimization
  • Vacation mode automation
• Mobile Experience:
  • Custom Lovelace cards
  • Mobile app shortcuts
  • Push notifications
  • Quick action tiles
• Integration Expansion:
  • MQTT discovery
  • Grafana dashboards
  • Node-RED nodes
  • REST API expansion

🚀 Long-term Vision (v1.0+)

• Machine Learning Integration:
  • Predictive maintenance scheduling
  • Automated chemical optimization
  • Energy usage prediction
  • Seasonal adaptation learning
• Multi-Controller Support:
  • Pool + Spa dual control
  • Multiple pool management
  • Centralized monitoring
  • Synchronized operations
• Professional Features:
  • Commercial pool support
  • Multi-tenant management
  • Advanced reporting
  • API rate limiting
• Cloud Integration (Optional):
  • Remote monitoring
  • Cloud backups
  • Mobile alerts
  • Professional dashboards

---

🐛 Bug Fixes

Known Issues (v0.1.0)

• None reported yet (initial release)

Fixed in Development

• Python 3.13 syntax compatibility issues
• State mapping for binary sensors
• Service parameter validation
• Blueprint template variables
• Translation string completeness

---

🔄 Migration Guide

From Manual API Usage

If you were previously using manual REST sensors or shell commands to interact with your Violet controller:

1. Remove old configuration:
   • Delete manual REST sensors from configuration.yaml
   • Remove shell command integrations
   • Clean up old automation triggers
2. Install integration:
   • Follow installation guide in README
   • Use same IP address and credentials
   • Select equivalent features
3. Update automations:
   • Replace REST calls with service calls
   • Update entity names (old: sensor.pool_temp → new: sensor.violet_pool_temperature)
   • Use new blueprints for common scenarios

From Beta Versions

Beta testers should:

1. Remove beta installation completely
2. Install stable release via HACS
3. Reconfigure with same settings
4. Update any custom automations

---

🏷️ Version Numbering

This project follows Semantic Versioning:

• MAJOR version (1.0.0): Incompatible API changes
• MINOR version (0.1.0): Backwards-compatible functionality additions
• PATCH version (0.1.1): Backwards-compatible bug fixes

Release Cycle

• Major releases: Yearly (significant new features)
• Minor releases: Quarterly (new features, blueprints)
• Patch releases: As needed (bug fixes, security)

---

📋 Changelog Categories

🎉 Added

New features, entities, services, or capabilities

⚡ Changed

Changes in existing functionality (non-breaking)

🔧 Fixed

Bug fixes and error corrections

🚨 Deprecated

Soon-to-be removed features (with migration path)

❌ Removed

Features removed in this version

🛡️ Security

Security improvements and vulnerability fixes

---

🔗 Related Links

• GitHub Releases: Latest versions and downloads
• GitHub Issues: Bug reports and feature requests
• HACS: Home Assistant Community Store listing
• Documentation: Full integration guide
• Blueprints: Automation templates

---

📞 Support & Feedback

Found an issue or have a suggestion? We’d love to hear from you:

• 🐛 Bug Reports: Open an issue on GitHub
• 💡 Feature Requests: Request new features
• 💬 Community Discussion: Home Assistant Community Forum
• 📧 Direct Contact: Email the developer

---

Made with ❤️ for the Home Assistant and Pool Automation Community

Keep your pool smart, your water perfect, and your maintenance minimal! 🏊‍♀️🤖

This site is open source. Improve this page.