← Compilazione | Indice | Avanti: Modalità del router →
3. Struttura dell'applicazione
3.1 Panoramica dei moduli
ACRouter è basato su un'architettura modulare con una chiara gerarchia dei componenti.
Architettura dei componenti
┌─────────────────────────────────────────────────────────────┐
│ 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 Modulo acrouter_hal (livello di astrazione hardware)
Percorso: components/acrouter_hal/
Scopo: Livello di astrazione hardware per lavorare con sensori, dimmer e algoritmi di controllo.
Componenti
3.2.1 RouterController
File:
Descrizione:
Controller principale del router solare. Implementa gli algoritmi di controllo per tutte le 6 modalità operative (OFF, AUTO, ECO, OFFGRID, MANUAL, BOOST).
Funzionalità:
- Regolatore proporzionale per il bilanciamento P_grid → 0
- Controllo del dimmer in base alla modalità
- Architettura basata su callback (chiamato ogni 200 ms da PowerMeterADC)
- Limitazione del livello del dimmer (0–100 %)
- Rilevamento dello stato (IDLE, INCREASING, DECREASING, AT_MAXIMUM, AT_MINIMUM)
Parametri principali:
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
}
Modalità operative:
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%
};
Metodi pubblici:
// 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
File:
Descrizione:
Misuratore di potenza ad alte prestazioni che utilizza DMA ADC in modalità continua.
Architettura:
ADC DMA (80 kHz) → ISR callback (10 ms) → Processing Task → RMS calc (200 ms) → User Callback
Specifiche:
- Frequenza di campionamento: 10 kHz per canale (80 kHz totali per 8 canali)
- Periodo RMS: 200 ms (10 periodi AC a 50 Hz)
- Risoluzione: ADC a 12 bit (0–4095)
- Intervallo: 0–3,3 V (ADC_ATTEN_DB_12)
- Canali: Fino a 4 canali (tensione + 3× corrente)
Configurazione DMA:
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
}
Sensori supportati:
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
};
Metodi pubblici:
// 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;
Struttura dati del callback:
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
File:
Descrizione:
HAL per il controllo del dimmer AC con TRIAC e rilevatore di passaggio per lo zero.
Caratteristiche:
- Dimmer a due canali (2 carichi indipendenti)
- Rilevamento passaggio per lo zero per la sincronizzazione della forma d'onda AC
- Rilevamento automatico della frequenza di rete (50/60 Hz)
- Curva di potenza compensata RMS
- Transizioni graduali
Configurazione hardware:
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
}
Pin GPIO (predefiniti):
- Passaggio per lo zero: GPIO 18
- Dimmer canale 1: GPIO 19
- Dimmer canale 2: GPIO 23
Metodi pubblici:
// 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;
Tipi di curve:
enum class DimmerCurve : uint8_t {
LINEAR, // Linear
RMS, // RMS-compensated (recommended for heating elements)
LOGARITHMIC // Logarithmic (for LED)
};
3.2.4 PinDefinitions.h
File: include/PinDefinitions.h
Descrizione:
Definizioni centralizzate dei pin GPIO per l'intero progetto.
Pin predefiniti:
// 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
Nota: I pin possono essere riassegnati tramite HardwareConfigManager e l'interfaccia web.
3.3 Modulo utils (utilità)
Percorso: components/utils/
Scopo: Classi di supporto per configurazione, comandi e tipi di dati.
Componenti
3.3.1 ConfigManager
File:
Descrizione:
Gestore della configurazione di sistema con salvataggio automatico in NVS.
Namespace NVS: "acrouter"
Parametri memorizzati:
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)
};
Chiavi NVS:
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.
}
Metodi pubblici:
// 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();
Valori predefiniti:
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
File:
Descrizione:
Gestore della configurazione hardware per pin GPIO e tipi di sensori. Consente la configurazione completa del dispositivo senza ricompilazione.
Namespace NVS: "hw_config"
Componenti configurabili:
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
};
Canale ADC:
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
};
Metodi pubblici:
// 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;
Validazione:
- ✅ Controllo conflitti GPIO (un pin = una funzione)
- ✅ Controllo validità pin ADC (solo ADC1)
- ✅ Controllo pin solo ingresso (34, 35, 36, 39 non possono essere uscite)
- ✅ Validazione del tipo di sensore
Impostazioni di fabbrica:
// 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
File:
Descrizione:
Gestore di comandi seriali per configurazione e monitoraggio tramite terminale.
Comandi principali:
# 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)
Metodi pubblici:
// Initialization
void begin();
// Main loop (call from loop())
void update();
// Command registration
void registerCommand(const char* cmd, CommandHandler handler);
3.3.4 DataTypes.h
File: include/DataTypes.h
Descrizione:
Tipi di dati comuni utilizzati in tutto il progetto.
Strutture principali:
// 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 Modulo comm (comunicazione)
Percorso: components/comm/
Scopo: Comunicazione di rete, server web, REST API, gestione WiFi.
Componenti
3.4.1 WiFiManager
File:
Descrizione:
Gestione WiFi con supporto simultaneo AP+STA (modalità duale ESP32).
Modalità operative:
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
};
Configurazione predefinita:
AP SSID: "ACRouter_XXXXXX" // XXXXXX = last 6 digits of MAC
AP Password: "12345678"
AP IP: 192.168.4.1
STA Timeout: 15 seconds
Metodi pubblici:
// 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
File:
Descrizione:
Server web HTTP con REST API e interfaccia Material UI.
Endpoint:
Pagine web:
GET /– Dashboard (pagina principale)GET /wifi– Pagina di configurazione WiFiGET /settings/hardware– Pagina di configurazione hardware
REST API – Stato e metriche:
GET /api/status– Stato del sistemaGET /api/metrics– Metriche di potenzaGET /api/config– Configurazione del router
REST API – Controllo:
POST /api/mode– Imposta modalitàPOST /api/manual– Imposta livello manualePOST /api/calibrate– Calibrazione sensori
REST API – WiFi:
GET /api/wifi/status– Stato WiFiGET /api/wifi/scan– Scansione retiPOST /api/wifi/connect– Connetti alla retePOST /api/wifi/disconnect– DisconnettiPOST /api/wifi/forget– Dimentica rete
REST API – Configurazione hardware:
GET /api/hardware/config– Ottieni configurazionePOST /api/hardware/config– Salva configurazionePOST /api/hardware/validate– Validazione configurazione
REST API – Sistema:
POST /api/system/reboot– Riavvia
Metodi pubblici:
// Initialization
bool begin(uint16_t http_port = 80);
// Control
void start();
void stop();
bool isRunning() const;
// Processing (call from loop())
void handleClient();
Interfaccia Material UI:
- Stili CSS separati (web/styles/MaterialStyles.h)
- Layout riutilizzabile (web/components/Layout.h)
- Pagine individuali (web/pages/)
3.4.3 NTPManager
File:
Descrizione:
Gestore di sincronizzazione temporale tramite NTP (per funzionalità future: modalità SCHEDULE, registrazione eventi).
Caratteristiche:
- Sincronizzazione automatica con server NTP
- Supporto fusi orari
- Aggiornamenti periodici dell'ora
Stato: Fase 2 (non critico per la versione attuale)
3.4.4 OTAManager
File:
Descrizione:
Gestore aggiornamenti OTA (Over-The-Air) del firmware.
Caratteristiche:
- Aggiornamento tramite WiFi
- Verifica dell'integrità (MD5)
- Rollback sicuro in caso di errori
- Utilizza le partizioni app0/app1
Stato: Fase 2 (infrastruttura pronta nella tabella delle partizioni)
3.5 Modulo rbdimmer (libreria esterna)
Percorso: components/rbdimmer/
Descrizione:
Libreria esterna per il controllo del dimmer AC TRIAC con rilevatore di passaggio per lo zero.
Funzionalità principali:
- Controllo TRIAC ad angolo di fase
- Sincronizzazione tramite passaggio per lo zero
- Supporto di più curve di potenza (LINEAR, RMS, LOGARITHMIC)
- Rilevamento automatico della frequenza di rete (50/60 Hz)
Nota: DimmerHAL è un wrapper su rbdimmer per facilitarne l'utilizzo.
3.6 Modulo sensors (tipi di sensori)
Percorso: components/sensors/
File: include/SensorTypes.h
Descrizione:
Definizioni dei tipi di sensori e configurazioni dei canali ADC.
Tipi di sensori:
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
};
Configurazione dei canali:
struct ADCChannelConfig {
uint8_t gpio; // GPIO pin
SensorType type; // Sensor type
float multiplier; // Calibration multiplier
float offset; // Offset
bool enabled; // Channel active
};
3.7 Dipendenze tra moduli
Grafico delle dipendenze
main.cpp
│
├─► acrouter_hal
│ ├─► RouterController
│ │ └─► DimmerHAL → rbdimmer
│ ├─► DimmerHAL → rbdimmer
│ └─► PowerMeterADC → sensors
│
├─► comm
│ ├─► WiFiManager
│ ├─► WebServerManager
│ ├─► NTPManager
│ └─► OTAManager
│
└─► utils
├─► ConfigManager
├─► HardwareConfigManager → sensors
├─► SerialCommand
└─► DataTypes
Tabella delle dipendenze
| Modulo | Dipende da | Utilizzato 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, tutti | main.cpp |
| SerialCommand | ConfigManager, RouterController | main.cpp |
3.8 Impostazioni dei moduli
ConfigManager (NVS namespace: "acrouter")
| Parametro | Chiave NVS | Tipo | Predefinito | Intervallo |
|---|---|---|---|---|
| Modalità router | router_mode |
uint8_t | 1 (AUTO) | 0–5 |
| Coefficiente Kp | ctrl_gain |
float | 200.0 | 10.0–1000.0 |
| Soglia di bilanciamento | bal_thresh |
float | 10.0 | 0.0–100.0 |
| Livello manuale | manual_lvl |
uint8_t | 0 | 0–100 |
| Coeff. tensione | volt_coef |
float | 230.0 | – |
| Coeff. corrente | curr_coef |
float | 50.0 | – |
HardwareConfigManager (NVS namespace: "hw_config")
| Componente | Chiavi NVS | Esempio |
|---|---|---|
| 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 |
| Dimmer 1 | dim1_gpio, dim1_en |
GPIO19, true |
| Passaggio per lo zero | zc_gpio, zc_en |
GPIO18, true |
| Relè 1 | rel1_gpio, rel1_pol, rel1_en |
GPIO15, true, false |
| LED di stato | led_st_gpio |
GPIO17 |