← Kompilierung | Inhaltsverzeichnis | Weiter: Router-Modi →
3. Anwendungsstruktur
3.1 Modulübersicht
ACRouter basiert auf einer modularen Architektur mit einer klaren Komponentenhierarchie.
Komponentenarchitektur
┌─────────────────────────────────────────────────────────────┐
│ main.cpp │
│ (Application Entry) │
└────────────┬────────────────────────────────────────────────┘
│
├─────────────────────────────────────────────────┐
│ │
┌───────▼──────┐ ┌─────────▼─────────┐
│ acrouter │ │ comm │
│ _hal │◄───────────────────────────────│ (Communication) │
│ (Hardware) │ └─────────┬─────────┘
└───────┬──────┘ │
│ │
│ ┌──────────────────┐ │
├──► RouterController│ │
│ └──────────────────┘ │
│ │
│ ┌──────────────────┐ │
├──► DimmerHAL │ │
│ └──────────────────┘ │
│ │
│ ┌──────────────────┐ │
└──► PowerMeterADC │ │
└──────────────────┘ │
│
┌──────────────────┐ ┌────────▼────────┐
│ utils │◄────────────────────────────│ WiFiManager │
│ (Utilities) │ ├─────────────────┤
└───────┬──────────┘ │ WebServerManager│
│ ├─────────────────┤
├──► ConfigManager │ NTPManager │
│ ├─────────────────┤
├──► HardwareConfigManager │ OTAManager │
│ └─────────────────┘
└──► SerialCommand
┌──────────────────┐
│ rbdimmer │
│ (External lib) │
└──────────────────┘
┌──────────────────┐
│ sensors │
│ (Sensor Types) │
└──────────────────┘
3.2 Modul acrouter_hal (Hardware Abstraction Layer)
Pfad: components/acrouter_hal/
Zweck: Hardware-Abstraktionsschicht für die Arbeit mit Sensoren, Dimmer und Steuerungsalgorithmen.
Komponenten
3.2.1 RouterController
Dateien:
Beschreibung:
Haupt-Controller des Solar-Routers. Implementiert Steuerungsalgorithmen für alle 6 Betriebsmodi (OFF, AUTO, ECO, OFFGRID, MANUAL, BOOST).
Funktionen:
- Proportionalregler zum Ausgleich P_grid → 0
- Dimmer-Steuerung je nach Modus
- Callback-gesteuerte Architektur (alle 200 ms von PowerMeterADC aufgerufen)
- Dimmer-Pegelbegrenzung (0–100 %)
- Zustandserkennung (IDLE, INCREASING, DECREASING, AT_MAXIMUM, AT_MINIMUM)
Hauptparameter:
namespace RouterConfig {
constexpr float DEFAULT_CONTROL_GAIN = 200.0f; // Kp coefficient
constexpr float DEFAULT_BALANCE_THRESHOLD = 10.0f; // Balance threshold (W)
constexpr uint8_t MIN_DIMMER_PERCENT = 0;
constexpr uint8_t MAX_DIMMER_PERCENT = 100;
constexpr uint32_t UPDATE_INTERVAL_MS = 200; // Update frequency
}
Betriebsmodi:
enum class RouterMode : uint8_t {
OFF = 0, // Dimmer disabled
AUTO, // Solar Router (P_grid → 0)
ECO, // Export prevention
OFFGRID, // Off-grid mode
MANUAL, // Fixed level
BOOST // Forced 100%
};
Öffentliche Methoden:
// Initialization
bool begin(DimmerHAL* dimmer);
// Mode control
void setMode(RouterMode mode);
RouterMode getMode() const;
// Control parameters
void setControlGain(float gain); // Set Kp
void setBalanceThreshold(float threshold); // Set balance threshold
void setManualLevel(uint8_t percent); // For MANUAL mode
// Main loop (called from PowerMeterADC callback)
void updateControl(const PowerData& data);
// Emergency stop
void emergencyStop();
// Status information
RouterStatus getStatus() const;
3.2.2 PowerMeterADC
Dateien:
Beschreibung:
Hochleistungs-Leistungsmesser mit DMA ADC im kontinuierlichen Modus.
Architektur:
ADC DMA (80 kHz) → ISR callback (10 ms) → Processing Task → RMS calc (200 ms) → User Callback
Spezifikationen:
- Abtastfrequenz: 10 kHz pro Kanal (80 kHz gesamt für 8 Kanäle)
- RMS-Periode: 200 ms (10 AC-Perioden bei 50 Hz)
- Auflösung: 12-Bit ADC (0–4095)
- Bereich: 0–3,3 V (ADC_ATTEN_DB_12)
- Kanäle: Bis zu 4 Kanäle (Spannung + 3× Strom)
DMA-Konfiguration:
namespace PowerMeterConfig {
constexpr uint32_t SAMPLING_FREQ_HZ = 20000; // 20 kHz on ADC1, 5 kHz per channel for 4 channels
constexpr uint8_t MAX_CHANNELS = 4;
constexpr uint32_t FRAME_TIME_MS = 10; // DMA callback every 10 ms
constexpr uint32_t SAMPLES_PER_FRAME = 200; // 200 samples/channel/frame
constexpr uint16_t RMS_FRAMES_COUNT = 20; // 20 frames = 200 ms
constexpr uint32_t RMS_UPDATE_INTERVAL_MS = 200; // RMS update
}
Unterstützte Sensoren:
enum class SensorType : uint8_t {
NONE = 0, // Channel not used
VOLTAGE_AC, // ZMPT107 (voltage)
CURRENT_LOAD, // ACS-712 (load current, dimmer current sensor)
CURRENT_GRID, // SCT-013 (grid current)
CURRENT_SOLAR, // SCT-013 (solar panel current)
CURRENT_AUX1, // Additional channel 1
CURRENT_AUX2 // Additional channel 2
};
Öffentliche Methoden:
// Initialization
bool begin();
void setCallback(std::function callback);
// Control
bool start();
void stop();
bool isRunning() const;
// Calibration
void setVoltageCalibration(float multiplier, float offset = 0.0f);
void setCurrentCalibration(uint8_t channel, float multiplier, float offset = 0.0f);
// Data retrieval
PowerData getPowerData() const;
float getVoltageRMS() const;
float getCurrentRMS(CurrentChannel channel) const;
float getPower(CurrentChannel channel) const;
Callback-Datenstruktur:
struct PowerData {
float voltage_rms; // RMS voltage (V)
float current_rms[3]; // RMS currents [LOAD, GRID, SOLAR] (A)
float power[3]; // Power [LOAD, GRID, SOLAR] (W)
float power_dimmer; // Dimmer power (W)
uint32_t timestamp_ms; // Timestamp
bool valid; // Data is valid
};
3.2.3 DimmerHAL
Dateien:
Beschreibung:
HAL zur Steuerung des AC-Dimmers mit TRIAC und Nulldurchgangsdetektor.
Funktionen:
- Zweikanal-Dimmer (2 unabhängige Lasten)
- Nulldurchgangserkennung zur AC-Wellenform-Synchronisation
- Automatische Netzfrequenzerkennung (50/60 Hz)
- RMS-kompensierte Leistungskurve
- Sanfte Übergänge
Hardware-Konfiguration:
namespace DimmerConfig {
constexpr uint8_t PHASE_NUM = 0; // Single phase
constexpr uint16_t MAINS_FREQUENCY = 0; // 0 = auto-detect
constexpr uint8_t MAX_CHANNELS = 2; // 2 channels
constexpr uint32_t DEFAULT_TRANSITION_MS = 500; // Transition time
}
GPIO-Pins (Standard):
- Nulldurchgang: GPIO 18
- Dimmer Kanal 1: GPIO 19
- Dimmer Kanal 2: GPIO 23
Öffentliche Methoden:
// Initialization
bool begin();
// Channel control
void setPower(DimmerChannel channel, uint8_t percent);
void setPowerSmooth(DimmerChannel channel, uint8_t percent, uint32_t transition_ms);
uint8_t getPower(DimmerChannel channel) const;
// Quick turn off
void turnOff(DimmerChannel channel);
void turnOffAll();
// Power curve
void setCurve(DimmerChannel channel, DimmerCurve curve);
// Information
DimmerStatus getStatus(DimmerChannel channel) const;
bool isInitialized() const;
Kurventypen:
enum class DimmerCurve : uint8_t {
LINEAR, // Linear
RMS, // RMS-compensated (recommended for heating elements)
LOGARITHMIC // Logarithmic (for LED)
};
3.2.4 PinDefinitions.h
Datei: include/PinDefinitions.h
Beschreibung:
Zentrale GPIO-Pin-Definitionen für das gesamte Projekt.
Standard-Pins:
// ADC pins (ADC1 only!)
constexpr uint8_t ADC_VOLTAGE_PIN = 35; // ZMPT107 voltage sensor
constexpr uint8_t ADC_CURRENT_LOAD_PIN = 39; // SCT-013 load current
constexpr uint8_t ADC_CURRENT_GRID_PIN = 36; // SCT-013 grid current
constexpr uint8_t ADC_CURRENT_SOLAR_PIN = 34;// SCT-013 solar current
// Dimmer pins
constexpr uint8_t DIMMER_ZEROCROSS_PIN = 18; // Zero-cross detector
constexpr uint8_t DIMMER_CH1_PIN = 19; // Dimmer channel 1
constexpr uint8_t DIMMER_CH2_PIN = 23; // Dimmer channel 2 (Phase 2)
// LED indicators
constexpr uint8_t LED_STATUS_PIN = 17; // Status LED
constexpr uint8_t LED_LOAD_PIN = 5; // Load indicator LED
// Relays (Phase 2)
constexpr uint8_t RELAY_CH1_PIN = 15; // Relay 1
constexpr uint8_t RELAY_CH2_PIN = 2; // Relay 2
Hinweis: Pins können über den HardwareConfigManager und die Weboberfläche neu zugewiesen werden.
3.3 Modul utils (Hilfsdienste)
Pfad: components/utils/
Zweck: Hilfsklassen für Konfiguration, Befehle und Datentypen.
Komponenten
3.3.1 ConfigManager
Dateien:
Beschreibung:
Systemkonfigurationsmanager mit automatischer Speicherung in NVS.
NVS-Namespace: "acrouter"
Gespeicherte Parameter:
struct SystemConfig {
// Router parameters
uint8_t router_mode; // RouterMode (0-5)
float control_gain; // Kp coefficient (10-1000)
float balance_threshold; // Balance threshold (W)
uint8_t manual_level; // Level for MANUAL mode (0-100%)
// Sensor calibration
float voltage_coef; // Voltage coefficient
float current_coef; // Current coefficient (A/V)
float current_threshold; // Minimum current (A)
float power_threshold; // Minimum power (W)
};
NVS-Schlüssel:
namespace ConfigKeys {
constexpr const char* ROUTER_MODE = "router_mode";
constexpr const char* CONTROL_GAIN = "ctrl_gain";
constexpr const char* BALANCE_THRESHOLD = "bal_thresh";
constexpr const char* MANUAL_LEVEL = "manual_lvl";
constexpr const char* VOLTAGE_COEF = "volt_coef";
constexpr const char* CURRENT_COEF = "curr_coef";
// ... etc.
}
Öffentliche Methoden:
// Initialization
bool begin();
// Get configuration
const SystemConfig& getConfig() const;
// Set parameters (automatically saved to NVS)
bool setRouterMode(uint8_t mode);
bool setControlGain(float gain);
bool setBalanceThreshold(float threshold);
bool setManualLevel(uint8_t level);
bool setVoltageCoefficient(float coef);
bool setCurrentCoefficient(float coef);
// Bulk operations
bool saveAll();
bool loadAll();
bool resetToDefaults();
Standardwerte:
namespace ConfigDefaults {
constexpr uint8_t ROUTER_MODE = 1; // AUTO
constexpr float CONTROL_GAIN = 200.0f;
constexpr float BALANCE_THRESHOLD = 10.0f;
constexpr uint8_t MANUAL_LEVEL = 0;
constexpr float VOLTAGE_COEF = 230.0f;
constexpr float CURRENT_COEF = 50.0f; // SCT-013 50A/1V
}
3.3.2 HardwareConfigManager
Dateien:
Beschreibung:
Hardware-Konfigurationsmanager für GPIO-Pins und Sensortypen. Ermöglicht die vollständige Gerätekonfiguration ohne Neukompilierung.
NVS-Namespace: "hw_config"
Konfigurierbare Komponenten:
struct HardwareConfig {
ADCChannelConfig adc_channels[4]; // 4 ADC channels
DimmerChannelConfig dimmer_ch1; // Dimmer 1
DimmerChannelConfig dimmer_ch2; // Dimmer 2
uint8_t zerocross_gpio; // Zero-cross pin
bool zerocross_enabled;
RelayChannelConfig relay_ch1; // Relay 1
RelayChannelConfig relay_ch2; // Relay 2
uint8_t led_status_gpio; // Status LED
uint8_t led_load_gpio; // Load LED
};
ADC-Kanal:
struct ADCChannelConfig {
uint8_t gpio; // GPIO pin (ADC1 only: 32,33,34,35,36,39)
SensorType type; // Sensor type
float multiplier; // Calibration multiplier
float offset; // Calibration offset
bool enabled; // Channel enabled
};
Öffentliche Methoden:
// Initialization
bool begin();
// ADC channel configuration
bool setADCChannel(uint8_t channel, const ADCChannelConfig& config);
ADCChannelConfig getADCChannel(uint8_t channel) const;
// Dimmer configuration
bool setDimmerChannel(uint8_t channel, const DimmerChannelConfig& config);
// Relay configuration
bool setRelayChannel(uint8_t channel, const RelayChannelConfig& config);
// Zero-cross
bool setZeroCross(uint8_t gpio, bool enabled = true);
// LED
bool setStatusLED(uint8_t gpio);
bool setLoadLED(uint8_t gpio);
// Validation
bool validate(String* error_msg = nullptr) const;
// Bulk operations
bool saveAll();
bool loadAll();
bool resetToDefaults();
void printConfig() const;
Validierung:
- ✅ GPIO-Konfliktprüfung (ein Pin = eine Funktion)
- ✅ ADC-Pin-Gültigkeitsprüfung (nur ADC1)
- ✅ Nur-Eingang-Pin-Prüfung (34, 35, 36, 39 können keine Ausgänge sein)
- ✅ Sensortyp-Validierung
Werkseinstellungen:
// ADC channels
ADC0: GPIO35, VOLTAGE_AC, mult=230.0, offset=0.0, ENABLED
ADC1: GPIO39, CURRENT_LOAD, mult=30.0, offset=0.0, ENABLED
ADC2: GPIO36, CURRENT_GRID, mult=30.0, offset=0.0, ENABLED
ADC3: GPIO34, CURRENT_SOLAR, mult=30.0, offset=0.0, ENABLED
// Dimmer
Ch1: GPIO19, ENABLED
Ch2: GPIO23, DISABLED
// Zero-Cross
GPIO18, ENABLED
3.3.3 SerialCommand
Dateien:
Beschreibung:
Serieller Befehlshandler für Konfiguration und Überwachung über Terminal.
Hauptbefehle:
# Information
help # Show all commands
status # Current state
metrics # Power metrics
config-show # Show configuration
hw-config-show # Show hardware configuration
# Mode control
set-mode <0-5> # Set mode (0=OFF, 1=AUTO, ...)
set-manual <0-100> # Set level for MANUAL
# Parameters
set-kp # Set Kp coefficient
set-threshold # Set balance threshold
# Calibration
calibrate-voltage [offset]
calibrate-current [offset]
# Configuration
config-save # Save configuration
config-reset # Reset to factory defaults
hw-config-reset # Reset hardware configuration
# System
reboot # Reboot
factory-reset # Full reset (all settings)
Öffentliche Methoden:
// Initialization
void begin();
// Main loop (call from loop())
void update();
// Command registration
void registerCommand(const char* cmd, CommandHandler handler);
3.3.4 DataTypes.h
Datei: include/DataTypes.h
Beschreibung:
Gemeinsame Datentypen, die im gesamten Projekt verwendet werden.
Hauptstrukturen:
// Power data
struct PowerData {
float voltage_rms;
float current_rms[3]; // [LOAD, GRID, SOLAR]
float power[3]; // [LOAD, GRID, SOLAR]
float power_dimmer;
uint32_t timestamp_ms;
bool valid;
};
// System metrics
struct SystemMetrics {
PowerData power;
uint8_t dimmer_percent;
RouterMode mode;
RouterState state;
uint32_t uptime_ms;
uint32_t free_heap;
};
3.4 Modul comm (Kommunikation)
Pfad: components/comm/
Zweck: Netzwerkkommunikation, Webserver, REST API, WiFi-Verwaltung.
Komponenten
3.4.1 WiFiManager
Dateien:
Beschreibung:
WiFi-Verwaltung mit gleichzeitiger AP+STA-Unterstützung (ESP32 Dual-Modus).
Betriebsmodi:
enum class WiFiState : uint8_t {
IDLE, // Not initialized
AP_ONLY, // AP only (no STA credentials)
STA_CONNECTING, // Connecting to STA
STA_CONNECTED, // Connected to STA
AP_STA, // Both modes active
STA_FAILED // STA failed, AP active
};
Standardkonfiguration:
AP SSID: "ACRouter_XXXXXX" // XXXXXX = last 6 digits of MAC
AP Password: "12345678"
AP IP: 192.168.4.1
STA Timeout: 15 seconds
Öffentliche Methoden:
// Initialization
bool begin();
// AP mode
bool startAP(const char* ssid = nullptr, const char* password = nullptr);
void stopAP();
bool isAPActive() const;
// STA mode
bool connectSTA(const char* ssid, const char* password);
void disconnectSTA();
bool isSTAConnected() const;
// WiFi scan
std::vector scanNetworks();
// Status
WiFiStatus getStatus() const;
3.4.2 WebServerManager
Dateien:
Beschreibung:
HTTP-Webserver mit REST API und Material-UI-Oberfläche.
Endpunkte:
Webseiten:
GET /– Dashboard (Hauptseite)GET /wifi– WiFi-KonfigurationsseiteGET /settings/hardware– Hardware-Konfigurationsseite
REST API – Status und Metriken:
GET /api/status– SystemstatusGET /api/metrics– LeistungsmetrikenGET /api/config– Router-Konfiguration
REST API – Steuerung:
POST /api/mode– Modus setzenPOST /api/manual– Manuellen Pegel setzenPOST /api/calibrate– Sensorkalibrierung
REST API – WiFi:
GET /api/wifi/status– WiFi-StatusGET /api/wifi/scan– Netzwerk-ScanPOST /api/wifi/connect– Mit Netzwerk verbindenPOST /api/wifi/disconnect– TrennenPOST /api/wifi/forget– Netzwerk vergessen
REST API – Hardware-Konfiguration:
GET /api/hardware/config– Konfiguration abrufenPOST /api/hardware/config– Konfiguration speichernPOST /api/hardware/validate– Konfigurationsvalidierung
REST API – System:
POST /api/system/reboot– Neustart
Öffentliche Methoden:
// Initialization
bool begin(uint16_t http_port = 80);
// Control
void start();
void stop();
bool isRunning() const;
// Processing (call from loop())
void handleClient();
Material-UI-Oberfläche:
- Separate CSS-Stile (web/styles/MaterialStyles.h)
- Wiederverwendbares Layout (web/components/Layout.h)
- Einzelne Seiten (web/pages/)
3.4.3 NTPManager
Dateien:
Beschreibung:
Zeitsynchronisations-Manager über NTP (für zukünftige Funktionen: SCHEDULE-Modus, Protokollierung).
Funktionen:
- Automatische Synchronisation mit NTP-Servern
- Zeitzonen-Unterstützung
- Periodische Zeitaktualisierungen
Status: Phase 2 (nicht kritisch für aktuelle Version)
3.4.4 OTAManager
Dateien:
Beschreibung:
OTA (Over-The-Air) Firmware-Update-Manager.
Funktionen:
- Update über WiFi
- Integritätsprüfung (MD5)
- Sicheres Rollback bei Fehlern
- Verwendet app0/app1-Partitionen
Status: Phase 2 (Infrastruktur in Partitionstabelle bereit)
3.5 Modul rbdimmer (Externe Bibliothek)
Pfad: components/rbdimmer/
Beschreibung:
Externe Bibliothek zur Steuerung des AC TRIAC-Dimmers mit Nulldurchgangsdetektor.
Hauptfunktionen:
- Phasenanschnitt-TRIAC-Steuerung
- Nulldurchgangs-Synchronisation
- Mehrere Leistungskurven (LINEAR, RMS, LOGARITHMIC)
- Automatische Netzfrequenzerkennung (50/60 Hz)
Hinweis: DimmerHAL ist ein Wrapper über rbdimmer zur einfacheren Nutzung.
3.6 Modul sensors (Sensortypen)
Pfad: components/sensors/
Datei: include/SensorTypes.h
Beschreibung:
Sensortyp-Definitionen und ADC-Kanalkonfigurationen.
Sensortypen:
enum class SensorType : uint8_t {
NONE = 0, // Channel not used
VOLTAGE_AC, // ZMPT107 (AC voltage)
CURRENT_LOAD, // SCT-013 (load current)
CURRENT_GRID, // SCT-013 (grid current, import/export)
CURRENT_SOLAR, // SCT-013 (solar panel current)
CURRENT_AUX1, // Additional sensor 1
CURRENT_AUX2 // Additional sensor 2
};
Kanalkonfiguration:
struct ADCChannelConfig {
uint8_t gpio; // GPIO pin
SensorType type; // Sensor type
float multiplier; // Calibration multiplier
float offset; // Offset
bool enabled; // Channel active
};
3.7 Modulabhängigkeiten
Abhängigkeitsgraph
main.cpp
│
├─► acrouter_hal
│ ├─► RouterController
│ │ └─► DimmerHAL → rbdimmer
│ ├─► DimmerHAL → rbdimmer
│ └─► PowerMeterADC → sensors
│
├─► comm
│ ├─► WiFiManager
│ ├─► WebServerManager
│ ├─► NTPManager
│ └─► OTAManager
│
└─► utils
├─► ConfigManager
├─► HardwareConfigManager → sensors
├─► SerialCommand
└─► DataTypes
Abhängigkeitstabelle
| Modul | Abhängig von | Verwendet in |
|---|---|---|
| RouterController | DimmerHAL, PowerMeterADC | main.cpp |
| DimmerHAL | rbdimmer, PinDefinitions | RouterController |
| PowerMeterADC | SensorTypes, DataTypes | RouterController, WebServerManager |
| ConfigManager | NVS | main.cpp, WebServerManager |
| HardwareConfigManager | SensorTypes, NVS | main.cpp, WebServerManager |
| WiFiManager | ESP32 WiFi | main.cpp, WebServerManager |
| WebServerManager | WiFiManager, alle | main.cpp |
| SerialCommand | ConfigManager, RouterController | main.cpp |
3.8 Moduleinstellungen
ConfigManager (NVS namespace: "acrouter")
| Parameter | NVS-Schlüssel | Typ | Standard | Bereich |
|---|---|---|---|---|
| Router-Modus | router_mode |
uint8_t | 1 (AUTO) | 0–5 |
| Kp-Koeffizient | ctrl_gain |
float | 200.0 | 10.0–1000.0 |
| Ausgleichsschwelle | bal_thresh |
float | 10.0 | 0.0–100.0 |
| Manueller Pegel | manual_lvl |
uint8_t | 0 | 0–100 |
| Spannungskoeff. | volt_coef |
float | 230.0 | – |
| Stromkoeff. | curr_coef |
float | 50.0 | – |
HardwareConfigManager (NVS namespace: "hw_config")
| Komponente | NVS-Schlüssel | Beispiel |
|---|---|---|
| ADC0 | adc0_gpio, adc0_type, adc0_mult, adc0_offset, adc0_en |
GPIO35, VOLTAGE_AC, 230.0, 0.0, true |
| ADC1 | adc1_gpio, adc1_type, adc1_mult, adc1_offset, adc1_en |
GPIO39, CURRENT_LOAD, 30.0, 0.0, true |
| Dimmer1 | dim1_gpio, dim1_en |
GPIO19, true |
| Nulldurchgang | zc_gpio, zc_en |
GPIO18, true |
| Relais 1 | rel1_gpio, rel1_pol, rel1_en |
GPIO15, true, false |
| Status-LED | led_st_gpio |
GPIO17 |