Passa al contenuto

← 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

python
┌─────────────────────────────────────────────────────────────┐
│                        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:

cpp
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:

cpp
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:

cpp
// 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:

python
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:

cpp
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:

cpp
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:

cpp
// 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:

cpp
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:

cpp
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:

cpp
// 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:

cpp
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:

cpp
// 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:

cpp
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:

cpp
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:

cpp
// 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:

cpp
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:

cpp
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:

cpp
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:

cpp
// 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:

cpp
// 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:

bash
# 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:

cpp
// 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:

cpp
// 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:

cpp
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:

cpp
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:

cpp
// 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 WiFi
  • GET /settings/hardware – Pagina di configurazione hardware

REST API – Stato e metriche:

  • GET /api/status – Stato del sistema
  • GET /api/metrics – Metriche di potenza
  • GET /api/config – Configurazione del router

REST API – Controllo:

  • POST /api/mode – Imposta modalità
  • POST /api/manual – Imposta livello manuale
  • POST /api/calibrate – Calibrazione sensori

REST API – WiFi:

  • GET /api/wifi/status – Stato WiFi
  • GET /api/wifi/scan – Scansione reti
  • POST /api/wifi/connect – Connetti alla rete
  • POST /api/wifi/disconnect – Disconnetti
  • POST /api/wifi/forget – Dimentica rete

REST API – Configurazione hardware:

  • GET /api/hardware/config – Ottieni configurazione
  • POST /api/hardware/config – Salva configurazione
  • POST /api/hardware/validate – Validazione configurazione

REST API – Sistema:

  • POST /api/system/reboot – Riavvia

Metodi pubblici:

cpp
// 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:


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:

cpp
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:

cpp
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

python
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

← Compilazione | Indice | Avanti: Modalità del router →