Making it more production ready

2026-01-19 10:57:25 +02:00
parent 3266ef8a52
commit 5513601c40
18 changed files with 954 additions and 12 deletions
@@ -0,0 +1,132 @@
+# RDZ Thermostats Monitor - Development Repository
+
+## Overview
+
+This repository contains the **RDZ Thermostats Monitor** custom integration for Home Assistant, along with a complete development environment for local testing.
+
+**Integration Purpose**: Passive monitoring of Modbus RTU communication over TCP, enabling Home Assistant control of RDZ thermostats in a PLC-based heating system without disrupting existing automation.
+
+## Repository Structure
+
+```
+modbus_rtu_monitor/                      # This repository
+├── .devcontainer/
+│   └── devcontainer.json               # Dev container for local HA testing
+├── config/                             # HA configuration for dev environment
+│   ├── configuration.yaml              # Minimal HA config
+│   └── custom_components/              # Mount point during development
+├── custom_components/
+│   └── rdz_thermostats_monitor/       # THE INTEGRATION (publish this folder)
+│       ├── claude.md                  # 📋 DETAILED INTEGRATION DOCS HERE
+│       ├── __init__.py
+│       ├── hub.py
+│       ├── coordinator.py
+│       ├── climate.py
+│       ├── sensor.py
+│       ├── binary_sensor.py
+│       ├── config_flow.py
+│       ├── const.py
+│       ├── manifest.json
+│       └── strings.json
+└── claude.md                          # This file (repo overview)
+```
+
+## Quick Start (Development)
+
+### Using Dev Container
+
+1. **Open in IDE with dev container support** (VS Code or IntelliJ IDEA)
+2. **Container builds automatically** and installs Home Assistant
+3. **Start HA**:
+   ```bash
+   hass -c /config --debug
+   ```
+4. **Access UI** at http://localhost:8123
+5. **Edit code** in `custom_components/rdz_thermostats_monitor/`
+6. **Restart HA** to test changes (Ctrl+C, then rerun `hass`)
+
+### Dev Container Details
+
+The `.devcontainer/devcontainer.json` provides:
+- Python 3.12 environment
+- Auto-installed Home Assistant
+- Live code mounting (no rebuild needed)
+- Port 8123 forwarded to host
+- IntelliJ IDEA integration
+
+## Documentation
+
+### 📋 Integration Documentation
+
+**For detailed integration documentation, implementation details, and development guides, see:**
+
+**[`custom_components/rdz_thermostats_monitor/claude.md`](custom_components/rdz_thermostats_monitor/claude.md)**
+
+That file contains:
+- Integration architecture and design patterns
+- Critical implementation details (reconnection logic, passive monitoring)
+- Modbus protocol specifics
+- Development tasks and testing procedures
+- Code patterns and conventions
+- Known issues and solutions
+
+### Repository vs Integration
+
+This repository serves two purposes:
+
+1. **Development Environment** (root level)
+   - Dev container configuration
+   - Local HA instance for testing
+   - This file documents the dev setup
+
+2. **Home Assistant Integration** (`custom_components/rdz_thermostats_monitor/`)
+   - The actual integration code
+   - Published/installed to HA's `custom_components/` folder
+   - See nested `claude.md` for integration details
+
+## Installation (Production)
+
+To install this integration in a production Home Assistant instance:
+
+1. Copy the **entire** `custom_components/rdz_thermostats_monitor/` folder to your HA's `custom_components/` directory
+2. Restart Home Assistant
+3. Add the integration via UI: Settings → Devices & Services → Add Integration → "RDZ Thermostats Monitor"
+
+## Key Features
+
+- **Passive Monitoring**: Observes existing Modbus traffic without interfering
+- **No Polling**: Completely non-intrusive to PLC communication
+- **Auto-Discovery**: Automatically creates entities for discovered slaves
+- **Robust Reconnection**: Handles extended server outages gracefully
+- **Selective Writing**: Only writes setpoint when user changes temperature
+- **Climate Entity**: Full thermostat control with HVAC action display
+- **Configurable**: Enable only the sensors you need
+
+## Technology Stack
+
+- **Home Assistant**: Smart home automation platform
+- **Modbus RTU over TCP**: Industrial communication protocol
+- **Python 3.12**: Integration implementation language
+- **Dev Containers**: Isolated development environment
+
+## Use Case
+
+This integration enables remote monitoring and control of RDZ thermostats in a PLC-based heating system, providing a migration path from PLC automation to Home Assistant without disrupting existing critical infrastructure.
+
+For full background and use case details, see the [integration documentation](custom_components/rdz_thermostats_monitor/claude.md#use-case--background).
+
+## Support & Contribution
+
+When working on this integration:
+- Always consult `custom_components/rdz_thermostats_monitor/claude.md` for implementation details
+- Test with the dev container before deploying to production
+- Maintain passive monitoring approach (no active polling)
+- Test reconnection logic with extended outages
+
+## File Organization
+
+- **Root `claude.md`** (this file): Repository overview, dev environment setup
+- **Integration `claude.md`**: Detailed implementation docs, architecture, protocols
+- **`.devcontainer/`**: Development environment configuration
+- **`config/`**: HA configuration for local testing
+- **`custom_components/rdz_thermostats_monitor/`**: The integration itself (publishable)