Add remote lock status sensor and physical lock control

docs/LockControlImplementation.md

@@ -0,0 +1,147 @@
+# Remote Lock Control Implementation
+
+## Overview
+This document describes the implementation of a remote lock control feature that allows Home Assistant to control a relay connected to the wallbox's remote lock mechanism via MQTT.
+
+## Hardware Configuration
+
+### Pin Assignments
+
+#### LILYGO T-CAN485 Board
+- **Lock Relay Pin**: GPIO18
+- **Logic**: HIGH = Unlocked, LOW = Locked
+- **Default State**: Locked (LOW)
+
+#### Regular ESP32 Board
+- **Lock Relay Pin**: GPIO25
+- **Logic**: HIGH = Unlocked, LOW = Locked
+- **Default State**: Locked (LOW)
+
+### Relay Connection
+Connect a relay module to the designated GPIO pin:
+- VCC → 3.3V or 5V (depending on relay module)
+- GND → GND
+- IN → GPIO pin (GPIO18 for LILYGO, GPIO25 for ESP32)
+- NO/COM → Connected to wallbox remote lock terminals
+
+## Software Implementation
+
+### Components Added
+
+#### 1. Board Configuration Updates
+- **Board.h/Board.cpp**: Added `GetPinLockRelay()` method
+- **BoardLilygo.cpp**: Configured GPIO18 as lock relay pin
+- **BoardESP32.cpp**: Configured GPIO25 as lock relay pin
+
+#### 2. LockController Component (`src/Components/LockController/`)
+- **LockController.h**: Interface for lock control functionality
+- **LockController.cpp**: Implementation with singleton pattern
+- **Methods**:
+  - `Init()`: Initialize the lock relay pin
+  - `SetLockState(bool unlocked)`: Control relay state
+  - `GetLockState()`: Get current lock state
+
+#### 3. MQTT Integration Updates
+- **Discovery Topic**: `homeassistant/lock/{device_name}/lock_control/config`
+- **Command Topic**: `{device_name}/lock_control/command`
+- **State Topic**: `{device_name}/lock_control/state`
+- **Payloads**:
+  - Commands: "LOCK" / "UNLOCK"
+  - States: "LOCKED" / "UNLOCKED"
+
+#### 4. Main Application Updates
+- Added LockController initialization in `setup()`
+
+## Home Assistant Integration
+
+The lock control will appear in Home Assistant as:
+- **Entity Type**: Lock
+- **Entity Name**: "Lock Control"
+- **Entity ID**: `lock.{device_name}_lock_control`
+- **Device Class**: Lock
+- **Commands**: Lock/Unlock buttons
+- **State Feedback**: Shows current lock state
+
+### MQTT Topics
+
+#### Discovery Configuration Topic:
+```
+homeassistant/lock/{device_name}/lock_control/config
+```
+
+#### Command Topic (Home Assistant → HeidelBridge):
+```
+{device_name}/lock_control/command
+```
+Payloads: "LOCK" or "UNLOCK"
+
+#### State Topic (HeidelBridge → Home Assistant):
+```
+{device_name}/lock_control/state
+```
+Payloads: "LOCKED" or "UNLOCKED"
+
+## Usage Instructions
+
+### Setup
+1. Connect a relay module to the appropriate GPIO pin
+2. Wire the relay output to the wallbox remote lock terminals
+3. Deploy the firmware to the ESP32
+4. The lock control will automatically appear in Home Assistant
+
+### Operation
+1. In Home Assistant, find the "Lock Control" entity
+2. Use the lock/unlock buttons to control the relay
+3. The state will be reflected in real-time
+4. Default state is locked on boot
+
+## Technical Details
+
+### Relay Logic
+- **Active HIGH**: GPIO HIGH = Relay ON = Lock UNLOCKED
+- **Active LOW**: GPIO LOW = Relay OFF = Lock LOCKED
+- **Default**: Locked state on startup for security
+
+### Error Handling
+- If MQTT connection fails, lock state remains unchanged
+- Pin initialization occurs during board setup
+- State is maintained in memory and published periodically
+
+### Logging
+- Lock state changes are logged at INFO level
+- MQTT command reception logged at TRACE level
+- Pin initialization logged at INFO level
+
+## Safety Considerations
+
+1. **Default Locked**: System defaults to locked state for security
+2. **Power Loss**: On power loss/restart, lock returns to locked state
+3. **GPIO Selection**: Chosen pins are safe and don't conflict with existing functionality
+4. **Relay Type**: Use appropriate relay module rated for wallbox voltage/current
+
+## Testing
+
+To test the lock control feature:
+1. Monitor serial output for lock controller initialization
+2. Check Home Assistant for the new lock entity
+3. Test lock/unlock commands from Home Assistant interface
+4. Verify relay operation with multimeter
+5. Check MQTT state topic updates
+
+## Troubleshooting
+
+### Lock not appearing in Home Assistant
+- Check MQTT connection and discovery messages
+- Verify Home Assistant MQTT integration is enabled
+- Check device name configuration
+
+### Relay not switching
+- Verify GPIO pin wiring
+- Check relay module power supply
+- Monitor serial logs for state changes
+- Test GPIO pin with multimeter
+
+### Commands not working
+- Check MQTT subscription topics
+- Verify payload format (LOCK/UNLOCK)
+- Monitor MQTT logs in Home Assistant

docs/PhysicalLockControlBenefits.md

@@ -0,0 +1,89 @@
+# Physical Lock Control with Relay Switch
+
+## Overview
+
+The HeidelBridge firmware supports an optional physical lock control feature using a relay switch. This provides a hardware-level safety mechanism that physically controls the wallbox's lock mechanism, working alongside the existing Modbus-based current control.
+
+## What Does the Lock Control Do?
+
+The physical lock control uses a relay to control the wallbox's **physical lock mechanism**. When activated, it prevents the charging cable from being inserted or removed, and the wallbox will report this lock state via Modbus register 259.
+
+**Important**: The wallbox itself remains powered and operational - this control only affects the physical locking mechanism, not the power supply.
+
+## Key Benefits
+
+### 1. **Fail-Safe Operation** 
+**This is the main advantage**: If the ESP32 loses power, crashes, or Modbus communication fails, the relay defaults to the **locked state**.
+
+- **Modbus current limiting**: If communication fails, wallbox may continue with last known settings or default behavior
+- **Physical lock relay**: Always defaults to "locked" when ESP32 is disconnected - **guaranteed safe state**
+
+### 2. **Reliable Lock Control**
+- **Hardware-level control**: Direct relay control is more reliable than software-only Modbus commands
+- **Immediate response**: No communication delays or potential Modbus timeouts
+- **Independent of wallbox firmware**: Works regardless of wallbox software state
+
+### 3. **True Safety Backup**
+When something goes wrong with your home automation system:
+- ESP32 loses power → Relay opens → Wallbox locks → No new charging sessions can start
+- Network failure → No communication needed for lock to engage
+- Software crash → Hardware relay maintains safe state
+
+## Comparison: Software vs Hardware Control
+
+| Scenario | Modbus Current Control | Physical Lock Relay |
+|----------|----------------------|-------------------|
+| **Normal Operation** | ✅ Fast, flexible | ✅ Reliable |
+| **ESP32 Power Loss** | ⚠️ Wallbox uses defaults | ✅ **Locks automatically** |
+| **Network Failure** | ⚠️ No new commands possible | ✅ **Maintains safe state** |
+| **Modbus Timeout** | ⚠️ May retry or timeout | ✅ **Lock remains active** |
+| **Software Crash** | ⚠️ Unknown state | ✅ **Defaults to locked** |
+
+## Use Cases
+
+### **Primary Use Case: Fail-Safe Protection**
+The main benefit is having a **guaranteed safe default**: if anything goes wrong with your automation system, the wallbox automatically locks and prevents new charging sessions.
+
+### **Secondary Use Cases:**
+- **Maintenance safety**: Physically prevent charging during wallbox maintenance
+- **Emergency situations**: Immediate, reliable way to prevent charging
+- **Simple on/off control**: Clear physical state that doesn't rely on communication
+
+## Implementation Details
+
+### Hardware Connection
+- **ESP32**: Relay control on GPIO25
+- **LILYGO T-CAN485**: Relay control on GPIO18
+- **Relay Logic**: 
+  - HIGH = Unlocked (charging allowed)
+  - LOW = Locked (charging prevented) - **Default when ESP32 is off**
+
+### Wiring
+Connect the relay contacts to the wallbox's lock control input (refer to your wallbox manual for specific connection details).
+
+## Home Assistant Integration
+
+The physical lock appears as a standard lock entity:
+- **Entity**: `lock.{device_name}_lock_control`
+- **States**: 🔒 Locked / 🔓 Unlocked
+- **Default**: Locked (when ESP32 is disconnected)
+
+## Best Practice: Use Both Controls
+
+For optimal safety and flexibility:
+
+1. **Modbus current control** for normal operation:
+   - Dynamic current adjustment
+   - Fast response to changing conditions
+   - Integration with smart home systems
+
+2. **Physical lock relay** as safety backup:
+   - Guaranteed safe state if communication fails
+   - Simple emergency stop functionality
+   - Peace of mind for unattended operation
+
+## Conclusion
+
+The physical lock control provides a simple but crucial safety feature: **it defaults to the safe state when the ESP32 is disconnected**. While Modbus control offers flexibility for normal operation, the hardware relay ensures that if your home automation system fails, the wallbox will automatically lock and prevent unexpected charging sessions.
+
+This fail-safe behavior makes it an excellent complement to software-based controls, providing reliability where it matters most.