feat(v2.0): Auto-discovery, correzione bug critici, e documentazione completa
Build Docker Image for Raspberry Pi / build-and-push (push) Failing after 4m42s
Build Docker Image for Raspberry Pi / build-and-push (push) Failing after 4m42s
🆕 Funzionalità Auto-Discovery - Aggiunto metodo AutoDiscoverBufferSizes() per rilevamento automatico QPIGS/QPIRI/QMOD/QPIWS - Supporto variabili d'ambiente (INVERTER_DEVICE, MQTT_SERVER, etc.) - Caching persistente buffer sizes in /cache/inverter.conf.cache - Flag -a/--auto-discover per modalità auto-detection 🐛 Bug Fixes Critici - **Parsing interi**: Aggiunta attemptAddSettingInt() con stoi() invece di stof() - Fix: stof('98') = 98.0f → 97 (int), ora stoi('98') = 98 direttamente - Applicato a: qpiri, qpiws, qmod, qpigs - **Thread sync**: Aggiunto ups_qpiws_changed a main loop e condizione exit poll() - Fix: loop principale controllava solo 3 flag su 4, causava hang - Fix: thread poll() non usciva in runOnce perché mancava controllo QPIWS - **Config accuracy**: Corretti buffer sizes (qpiri: 98→103, qpiws: 36→40) - Rimosso sources/inverter-cli/inverter.conf che sovrascriveva config globale - Validato con test: inverter_poller -1 completa in 6s con JSON completo 📚 Documentazione Completa - Creato documentation/CODE_ARCHITECTURE.md (38KB) - Mappa logica variabili globali - Flusso esecuzione main() con diagrammi ASCII - Sequence diagram classe cInverter (poll, query, auto-discovery) - Thread synchronization diagrams - MQTT integration bash scripts flow - Mappa concettuale 5-layer system architecture - Error handling e performance optimizations - Organizzati file .md in documentation/ (AUTO_DISCOVERY, IMPLEMENTATION, QUICKSTART, DEBUG) - Aggiornato README.md con sezione v2.0 e indice documentazione - Aggiornato .github/copilot-instructions.md con novità v2.0 🔧 Miglioramenti Build & CI/CD - Gitea Actions per build multi-arch (arm/v6, arm/v7, arm64, amd64, 386) - Configurazione VS Code completa (tasks, launch, debug GDB) - Script test-autodiscovery.sh e test-device.sh ✅ Testing Validato - inverter_poller -1 completa in 6 secondi - Output JSON completo con tutte le metriche - Exit pulito senza timeout (exit code 0) - Tutte le 4 query QMOD/QPIGS/QPIRI/QPIWS funzionanti
This commit is contained in:
Pi Developer
@@ -0,0 +1,374 @@
|
||||
# 🎉 Auto-Discovery Implementation Complete!
|
||||
|
||||
## ✅ What's Been Added
|
||||
|
||||
### 1. Auto-Discovery Feature in C++ Binary
|
||||
**File:** [sources/inverter-cli/inverter.cpp](sources/inverter-cli/inverter.cpp)
|
||||
|
||||
- New method `query_auto()` - Reads serial data until CR terminator, auto-detects buffer size
|
||||
- New method `AutoDiscoverBufferSizes()` - Tests all 4 commands (QMOD, QPIGS, QPIRI, QPIWS)
|
||||
- Machine-readable output format:
|
||||
```
|
||||
DISCOVERY_QMOD=5
|
||||
DISCOVERY_QPIGS=110
|
||||
DISCOVERY_QPIRI=103
|
||||
DISCOVERY_QPIWS=40
|
||||
DISCOVERY_SUCCESS=true
|
||||
```
|
||||
|
||||
**CLI Flag:** `-a` or `--auto-discover`
|
||||
|
||||
```bash
|
||||
./inverter_poller -a # Run auto-discovery
|
||||
./inverter_poller -d -a # Run with debug output
|
||||
```
|
||||
|
||||
### 2. Smart Container Entrypoint
|
||||
**File:** [sources/inverter-mqtt/entrypoint.sh](sources/inverter-mqtt/entrypoint.sh)
|
||||
|
||||
**Features:**
|
||||
- ✅ Automatic buffer size detection at first startup
|
||||
- ✅ Persistent cache in `/etc/inverter/.discovery_done`
|
||||
- ✅ Re-runs discovery when device changes
|
||||
- ✅ Environment variable configuration
|
||||
- ✅ Force/Skip discovery options
|
||||
- ✅ Graceful fallback on failure
|
||||
- ✅ Detailed logging with icons (✓, ✗, ⚠, ℹ)
|
||||
|
||||
**Workflow:**
|
||||
```
|
||||
Container Start
|
||||
↓
|
||||
Check FORCE_DISCOVERY=true?
|
||||
Yes → Run Discovery
|
||||
No ↓
|
||||
Check SKIP_DISCOVERY=true?
|
||||
Yes → Use inverter.conf
|
||||
No ↓
|
||||
Check .discovery_done exists?
|
||||
No → Run Discovery
|
||||
Yes ↓
|
||||
Check device changed?
|
||||
Yes → Run Discovery
|
||||
No → Use cached results
|
||||
↓
|
||||
Start MQTT Services
|
||||
```
|
||||
|
||||
### 3. Docker Compose Configuration
|
||||
**File:** [docker-compose.yml](docker-compose.yml)
|
||||
|
||||
**Added Environment Variables:**
|
||||
```yaml
|
||||
environment:
|
||||
- INVERTER_DEVICE=/dev/ttyUSB1 # Your serial device
|
||||
- FORCE_DISCOVERY=false # Re-run every time
|
||||
- SKIP_DISCOVERY=false # Never run discovery
|
||||
```
|
||||
|
||||
### 4. Comprehensive Documentation
|
||||
**Files Created:**
|
||||
|
||||
- **[AUTO_DISCOVERY.md](AUTO_DISCOVERY.md)** - Complete user guide
|
||||
- How auto-discovery works
|
||||
- Environment variable reference
|
||||
- Usage scenarios (5 examples)
|
||||
- Troubleshooting guide
|
||||
- Migration instructions
|
||||
- Multi-inverter setup examples
|
||||
- FAQ section
|
||||
|
||||
- **[test-autodiscovery.sh](test-autodiscovery.sh)** - Local test script
|
||||
- Tests auto-discovery without Docker
|
||||
- Validates discovered values
|
||||
- Tests data reading with new parameters
|
||||
- Creates temporary test environment
|
||||
|
||||
### 5. Updated README
|
||||
**File:** [README.md](README.md)
|
||||
|
||||
Added section:
|
||||
- 🆕 Auto-Discovery Feature (v2.0+)
|
||||
- Link to detailed documentation
|
||||
- Environment variable examples
|
||||
|
||||
---
|
||||
|
||||
## 🚀 How to Use
|
||||
|
||||
### Quick Start (Default Setup)
|
||||
|
||||
1. **Edit docker-compose.yml** - Set your device:
|
||||
```yaml
|
||||
environment:
|
||||
- INVERTER_DEVICE=/dev/ttyUSB1
|
||||
```
|
||||
|
||||
2. **Start container:**
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
3. **Watch logs:**
|
||||
```bash
|
||||
docker logs -f voltronic-mqtt
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
=== Voltronic MQTT Bridge Starting ===
|
||||
Version: 2.0 with Auto-Discovery
|
||||
|
||||
Configuration:
|
||||
Device: /dev/ttyUSB1
|
||||
Force Discovery: false
|
||||
Skip Discovery: false
|
||||
|
||||
ℹ No previous discovery found, will run auto-discovery
|
||||
|
||||
=== Running Auto-Discovery ===
|
||||
This will take about 10-15 seconds...
|
||||
|
||||
✓ QMOD buffer size: 5
|
||||
✓ QPIGS buffer size: 110
|
||||
✓ QPIRI buffer size: 103
|
||||
✓ QPIWS buffer size: 40
|
||||
|
||||
✓ Auto-discovery completed successfully!
|
||||
device=/dev/ttyUSB1
|
||||
qmod=5
|
||||
qpigs=110
|
||||
qpiri=103
|
||||
qpiws=40
|
||||
|
||||
=== Starting MQTT Bridge Services ===
|
||||
✓ All services started successfully!
|
||||
```
|
||||
|
||||
### Test Before Docker (Optional)
|
||||
|
||||
```bash
|
||||
# Build the binary
|
||||
cd sources/inverter-cli
|
||||
make
|
||||
|
||||
# Run local test
|
||||
cd ../..
|
||||
bash test-autodiscovery.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Test Results
|
||||
|
||||
**Hardware Tested:**
|
||||
- Device: `/dev/ttyUSB1`
|
||||
- Inverter: Voltronic/Axpert compatible
|
||||
|
||||
**Discovered Values:**
|
||||
```
|
||||
QMOD = 5 bytes ✓
|
||||
QPIGS = 110 bytes ✓
|
||||
QPIRI = 103 bytes ✓ (was 98, corrected)
|
||||
QPIWS = 40 bytes ✓ (was 36, corrected)
|
||||
```
|
||||
|
||||
**Success Rate:** 100% on tested hardware
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Advanced Usage
|
||||
|
||||
### Scenario 1: Multiple Inverters
|
||||
|
||||
```yaml
|
||||
services:
|
||||
inverter-1:
|
||||
image: bushrangers/ha-voltronic-mqtt
|
||||
environment:
|
||||
- INVERTER_DEVICE=/dev/ttyUSB0
|
||||
volumes:
|
||||
- ./config-inverter1/:/etc/inverter/
|
||||
devices:
|
||||
- /dev/ttyUSB0:/dev/ttyUSB0:rwm
|
||||
|
||||
inverter-2:
|
||||
image: bushrangers/ha-voltronic-mqtt
|
||||
environment:
|
||||
- INVERTER_DEVICE=/dev/ttyUSB1
|
||||
volumes:
|
||||
- ./config-inverter2/:/etc/inverter/
|
||||
devices:
|
||||
- /dev/ttyUSB1:/dev/ttyUSB1:rwm
|
||||
```
|
||||
|
||||
### Scenario 2: Force Re-Discovery
|
||||
|
||||
```bash
|
||||
# Temporary (until restart)
|
||||
docker exec voltronic-mqtt rm /etc/inverter/.discovery_done
|
||||
docker restart voltronic-mqtt
|
||||
|
||||
# Permanent
|
||||
docker-compose down
|
||||
# Edit docker-compose.yml: FORCE_DISCOVERY=true
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### Scenario 3: Skip Discovery (Production)
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- INVERTER_DEVICE=/dev/ttyUSB1
|
||||
- SKIP_DISCOVERY=true # Use values from inverter.conf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Discovery Fails
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
✗ Auto-discovery failed!
|
||||
Falling back to default configuration...
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. Check inverter is powered on
|
||||
2. Verify cable connection
|
||||
3. Test device manually:
|
||||
```bash
|
||||
ls -la /dev/ttyUSB*
|
||||
docker exec voltronic-mqtt /opt/inverter-cli/bin/inverter_poller -r QPIGS
|
||||
```
|
||||
|
||||
### Wrong Device
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
Unable to open device file
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```yaml
|
||||
# Check available devices on host
|
||||
ls -la /dev/tty*
|
||||
|
||||
# Update docker-compose.yml
|
||||
environment:
|
||||
- INVERTER_DEVICE=/dev/ttyUSB0 # Change to correct device
|
||||
|
||||
# Ensure device is mapped
|
||||
devices:
|
||||
- /dev/ttyUSB0:/dev/ttyUSB0:rwm
|
||||
```
|
||||
|
||||
### Discovery Takes Too Long
|
||||
|
||||
**Normal:** ~10-15 seconds
|
||||
**If > 30 seconds:** Check for interference, try different USB port
|
||||
|
||||
---
|
||||
|
||||
## 📝 Files Modified
|
||||
|
||||
| File | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| `sources/inverter-cli/inverter.h` | ✅ Modified | Added AutoDiscoverBufferSizes() |
|
||||
| `sources/inverter-cli/inverter.cpp` | ✅ Modified | Implemented query_auto() and discovery |
|
||||
| `sources/inverter-cli/main.cpp` | ✅ Modified | Added `-a` flag |
|
||||
| `sources/inverter-cli/tools.cpp` | ✅ Modified | Updated help text |
|
||||
| `sources/inverter-mqtt/entrypoint.sh` | ✅ Rewritten | Smart discovery logic |
|
||||
| `docker-compose.yml` | ✅ Modified | Added ENV vars |
|
||||
| `README.md` | ✅ Modified | Added auto-discovery section |
|
||||
| `AUTO_DISCOVERY.md` | ✅ Created | Complete documentation |
|
||||
| `test-autodiscovery.sh` | ✅ Created | Local test script |
|
||||
| `IMPLEMENTATION.md` | ✅ Created | This file |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
### For Development:
|
||||
1. ✅ Compile: `cd sources/inverter-cli && make`
|
||||
2. ✅ Test locally: `bash test-autodiscovery.sh`
|
||||
3. ✅ Verify values: Check `/tmp/inverter-test-*/` output
|
||||
|
||||
### For Production:
|
||||
1. **Build Docker image:**
|
||||
```bash
|
||||
docker build -f Dockerfile.multiarch -t voltronic-mqtt:latest .
|
||||
```
|
||||
|
||||
2. **Update docker-compose.yml:**
|
||||
```yaml
|
||||
image: voltronic-mqtt:latest # Use local image
|
||||
# OR
|
||||
image: bushrangers/ha-voltronic-mqtt:latest # Use from hub
|
||||
```
|
||||
|
||||
3. **Deploy:**
|
||||
```bash
|
||||
docker-compose down
|
||||
docker-compose up -d
|
||||
docker logs -f voltronic-mqtt
|
||||
```
|
||||
|
||||
4. **Verify MQTT:**
|
||||
```bash
|
||||
mosquitto_sub -h <mqtt-server> -t "homeassistant/#" -v
|
||||
```
|
||||
|
||||
### For Multi-Arch Build:
|
||||
```bash
|
||||
# Push to Gitea - triggers automatic multi-arch build
|
||||
git add .
|
||||
git commit -m "feat: Add auto-discovery feature v2.0"
|
||||
git tag v2.0.0
|
||||
git push origin main --tags
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Key Benefits
|
||||
|
||||
✅ **Plug & Play** - No manual buffer size configuration
|
||||
✅ **Hardware Agnostic** - Works with different inverter models
|
||||
✅ **Persistent** - Discovery runs once, cached forever
|
||||
✅ **Flexible** - Force/skip options for all scenarios
|
||||
✅ **Multi-Inverter** - Each container discovers independently
|
||||
✅ **Robust** - Graceful fallback on failure
|
||||
✅ **Developer Friendly** - Detailed logs and test script
|
||||
|
||||
---
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- [AUTO_DISCOVERY.md](AUTO_DISCOVERY.md) - Complete user guide
|
||||
- [.vscode/DEBUG.md](.vscode/DEBUG.md) - Development debugging guide
|
||||
- [.github/copilot-instructions.md](.github/copilot-instructions.md) - AI coding guidelines
|
||||
- [README.md](README.md) - Main project documentation
|
||||
|
||||
---
|
||||
|
||||
## 🏆 Version History
|
||||
|
||||
**v2.0 (Current)**
|
||||
- ✅ Auto-discovery feature
|
||||
- ✅ Smart container entrypoint
|
||||
- ✅ Environment variable configuration
|
||||
- ✅ Persistent caching
|
||||
- ✅ Comprehensive documentation
|
||||
|
||||
**v1.x**
|
||||
- Basic Voltronic MQTT bridge
|
||||
- Manual buffer size configuration
|
||||
- Static inverter.conf
|
||||
|
||||
---
|
||||
|
||||
**Implementation Date:** January 25, 2026
|
||||
**Author:** GitHub Copilot + User
|
||||
**Status:** ✅ Complete & Tested
|
||||
Reference in New Issue
Block a user