← Modalità del router | Indice | Avanti: Applicazione principale →

5. API dei moduli e strutture dati

5.1 API RouterController

File:
- components/acrouter_hal/include/RouterController.h
- components/acrouter_hal/src/RouterController.cpp

Pattern di progettazione: Singleton

Ottenere l'istanza

cpp

RouterController& router = RouterController::getInstance();

Inizializzazione

begin()

cpp

bool begin(DimmerHAL* dimmer, DimmerChannel channel = DimmerChannel::CHANNEL_1);

Descrizione: Inizializzare il controller con associazione al dimmer.

Parameters:
- dimmer - pointer to initialized DimmerHAL
- channel - dimmer channel (CHANNEL_1 or CHANNEL_2)

Ritorna: true in caso di successo, false in caso di errore

Esempio:

cpp

DimmerHAL& dimmer = DimmerHAL::getInstance();
RouterController& router = RouterController::getInstance();

dimmer.begin();
if (router.begin(&dimmer, DimmerChannel::CHANNEL_1)) {
    Serial.println("RouterController initialized");
} else {
    Serial.println("RouterController init failed");
}

Gestione delle modalità

setMode()

cpp

void setMode(RouterMode mode);

Descrizione: Impostare la modalità operativa del controller.

Parameters:
- mode - one of 6 modes (OFF=0, AUTO=1, ECO=2, OFFGRID=3, MANUAL=4, BOOST=5)

Esempio:

cpp

router.setMode(RouterMode::AUTO);    // Automatic mode
router.setMode(RouterMode::MANUAL);  // Manual mode

getMode()

cpp

RouterMode getMode() const;

Descrizione: Ottenere la modalità operativa corrente.

Ritorna: RouterMode corrente

Esempio:

cpp

RouterMode current = router.getMode();
if (current == RouterMode::AUTO) {
    Serial.println("Running in AUTO mode");
}

Parametri di controllo

setControlGain()

cpp

void setControlGain(float gain);

Descrizione: Impostare il coefficiente proporzionale del regolatore (Kp).

Parameters:
- gain - gain coefficient (10.0 - 1000.0)

Effect:
- Lower Kp � faster response, possible oscillations
- Higher Kp � slower response, more stable

Esempio:

cpp

router.setControlGain(200.0f);  // Standard value
router.setControlGain(100.0f);  // Faster response
router.setControlGain(400.0f);  // Slower, more stable

getControlGain()

cpp

float getControlGain() const;

Ritorna: Valore Kp corrente

setBalanceThreshold()

cpp

void setBalanceThreshold(float threshold);

Descrizione: Impostare la soglia di bilanciamento in Watt.

Parameters:
- threshold - threshold in W (typically 5.0 - 50.0)

Effect:
- If |P_grid| < threshold, system is considered balanced
- Lower threshold � more accurate balance, more switching
- Higher threshold � less switching, less accurate balance

Esempio:

cpp

router.setBalanceThreshold(10.0f);  // �10 W considered balanced
router.setBalanceThreshold(20.0f);  // �20 W for larger loads

getBalanceThreshold()

cpp

float getBalanceThreshold() const;

Ritorna: Soglia di bilanciamento corrente (W)

Controllo manuale (modalità MANUAL)

setManualLevel()

cpp

void setManualLevel(uint8_t percent);

Descrizione: Impostare un livello fisso del dimmer per la modalità MANUAL.

Parameters:
- percent - dimmer level 0-100%

Esempio:

cpp

router.setMode(RouterMode::MANUAL);
router.setManualLevel(75);  // Set to 75%

getManualLevel()

cpp

uint8_t getManualLevel() const;

Ritorna: Livello impostato per la modalità MANUAL

Ciclo di aggiornamento principale

update()

cpp

void update(const PowerMeterADC::Measurements& measurements);

Descrizione: Funzione di controllo principale. Chiamata automaticamente dal callback di PowerMeterADC ogni 200 ms.

Parameters:
- measurements - structure with power measurements

Nota: Generalmente chiamata automaticamente, la chiamata manuale non è necessaria.

Logica interna:

cpp

void update(const Measurements& meas) {
    switch (mode) {
        case OFF:     processOffMode();           break;
        case AUTO:    processAutoMode(P_grid);    break;
        case ECO:     processEcoMode(P_grid);     break;
        case OFFGRID: processOffgridMode(meas);   break;
        case MANUAL:  processManualMode();        break;
        case BOOST:   processBoostMode();         break;
    }
}

Arresto di emergenza

emergencyStop()

cpp

void emergencyStop();

Descrizione: Spegnimento immediato del dimmer (0%) e transizione alla modalità OFF.

When to use:
- System overheating
- Sensor error
- Critical situation

Esempio:

cpp

if (temperature > 80.0f) {
    router.emergencyStop();
    Serial.println("EMERGENCY STOP: Overheating!");
}

Ottenere lo stato

getStatus()

cpp

RouterStatus getStatus() const;

Descrizione: Ottenere le informazioni complete sullo stato del controller.

Ritorna: Struttura RouterStatus

Esempio:

cpp

RouterStatus status = router.getStatus();

Serial.printf("Mode: %d\n", static_cast(status.mode));
Serial.printf("State: %d\n", static_cast(status.state));
Serial.printf("Dimmer: %d%%\n", status.dimmer_percent);
Serial.printf("P_grid: %.1f W\n", status.power_grid);
Serial.printf("Kp: %.1f\n", status.control_gain);

Strutture dati

RouterStatus

cpp

struct RouterStatus {
    RouterMode mode;                    // Current mode
    RouterState state;                  // State (IDLE, INCREASING, etc.)
    uint8_t dimmer_percent;             // Dimmer level (0-100%)
    float target_level;                 // Target level (float for smoothness)
    float power_grid;                   // Current grid power (W)
    float control_gain;                 // Kp coefficient
    float balance_threshold;            // Balance threshold (W)
    uint32_t last_update_ms;            // Last update timestamp
    bool valid;                         // Status is valid
};

RouterMode

cpp

enum class RouterMode : uint8_t {
    OFF = 0,        // Disabled
    AUTO,           // Automatic Solar Router
    ECO,            // Economic (anti-export)
    OFFGRID,        // Autonomous
    MANUAL,         // Manual
    BOOST           // Forced 100%
};

RouterState

cpp

enum class RouterState : uint8_t {
    IDLE,           // No action
    INCREASING,     // Increasing dimmer (exporting)
    DECREASING,     // Decreasing dimmer (importing)
    AT_MAXIMUM,     // At maximum (100%)
    AT_MINIMUM,     // At minimum (0%)
    ERROR           // Error state
};

5.2 API PowerMeterADC

File:
- components/acrouter_hal/include/PowerMeterADC.h
- components/acrouter_hal/src/PowerMeterADC.cpp

Pattern di progettazione: Singleton

Ottenere l'istanza

cpp

PowerMeterADC& powerMeter = PowerMeterADC::getInstance();

Inizializzazione

begin()

cpp

bool begin();

Descrizione: Inizializzare DMA ADC e creare il task di elaborazione FreeRTOS.

Ritorna: true in caso di successo

Esempio:

cpp

PowerMeterADC& powerMeter = PowerMeterADC::getInstance();

if (powerMeter.begin()) {
    Serial.println("PowerMeterADC initialized");
} else {
    Serial.println("PowerMeterADC init failed");
}

Controllo delle misurazioni

start()

cpp

bool start();

Descrizione: Avviare le misurazioni DMA ADC continue.

Ritorna: true se avviato con successo

Esempio:

cpp

if (powerMeter.start()) {
    Serial.println("Measurements started");
}

stop()

cpp

void stop();

Descrizione: Interrompere le misurazioni.

Esempio:

cpp

powerMeter.stop();
Serial.println("Measurements stopped");

isRunning()

cpp

bool isRunning() const;

Descrizione: Verificare se le misurazioni sono in corso.

Ritorna: true se le misurazioni sono attive

Callback dei risultati

setCallback()

cpp

void setCallback(std::function callback);

Descrizione: Impostare la funzione callback chiamata ogni 200 ms con i risultati RMS.

Parameters:
- callback - function of type void callback(const Measurements& meas)

Esempio:

cpp

// Option 1: Lambda
powerMeter.setCallback([](const PowerMeterADC::Measurements& meas) {
    Serial.printf("V: %.1f V, I_grid: %.2f A, P_grid: %.1f W\n",
                  meas.voltage_rms,
                  meas.current_rms[PowerMeterADC::CURRENT_GRID],
                  meas.power_active[PowerMeterADC::CURRENT_GRID]);
});

// Option 2: Global function
void onMeasurements(const PowerMeterADC::Measurements& meas) {
    // Process measurements
}
powerMeter.setCallback(onMeasurements);

// Option 3: Class method
powerMeter.setCallback([this](const auto& meas) {
    this->handleMeasurements(meas);
});

Calibrazione dei sensori

setVoltageCalibration()

cpp

void setVoltageCalibration(float multiplier, float offset = 0.0f);

Descrizione: Impostare i coefficienti di calibrazione per il sensore di tensione.

Parameters:
- multiplier - multiplier (V/V_adc)
- offset - offset (V)

Formula: V_real = V_adc * multiplier + offset

Esempio:

cpp

// ZMPT107: 230V � 1V (scale 1:230)
powerMeter.setVoltageCalibration(230.0f, 0.0f);

// With offset correction
powerMeter.setVoltageCalibration(235.0f, -2.5f);

setCurrentCalibration()

cpp

void setCurrentCalibration(CurrentChannel channel, float multiplier, float offset = 0.0f);

Descrizione: Impostare i coefficienti di calibrazione per il sensore di corrente.

Parameters:
- channel - channel (CURRENT_LOAD, CURRENT_GRID, CURRENT_SOLAR)
- multiplier - multiplier (A/V_adc)
- offset - offset (A)

Formula: I_real = I_adc * multiplier + offset

Esempio:

cpp

// SCT-013-030: 30A � 1V
powerMeter.setCurrentCalibration(PowerMeterADC::CURRENT_GRID, 30.0f, 0.0f);

// ACS-712-20A: 0A=2.5V, sensitivity 100mV/A
powerMeter.setCurrentCalibration(PowerMeterADC::CURRENT_LOAD, 10.0f, -25.0f);

Recupero dati

getPowerData()

cpp

Measurements getPowerData() const;

Descrizione: Ottenere le ultime misurazioni (thread-safe).

Ritorna: Struttura Measurements

Esempio:

cpp

PowerMeterADC::Measurements data = powerMeter.getPowerData();

if (data.valid) {
    Serial.printf("Voltage: %.1f V\n", data.voltage_rms);
    Serial.printf("Current Grid: %.2f A\n", data.current_rms[PowerMeterADC::CURRENT_GRID]);
    Serial.printf("Power Grid: %.1f W\n", data.power_active[PowerMeterADC::CURRENT_GRID]);
}

getVoltageRMS()

cpp

float getVoltageRMS() const;

Descrizione: Ottenere solo la tensione RMS.

Ritorna: Tensione in Volt

getCurrentRMS()

cpp

float getCurrentRMS(CurrentChannel channel) const;

Descrizione: Ottenere la corrente RMS per il canale specificato.

Parameters:
- channel - CURRENT_LOAD, CURRENT_GRID or CURRENT_SOLAR

Ritorna: Corrente in Ampere

Esempio:

cpp

float i_grid = powerMeter.getCurrentRMS(PowerMeterADC::CURRENT_GRID);
float i_solar = powerMeter.getCurrentRMS(PowerMeterADC::CURRENT_SOLAR);

Serial.printf("Grid: %.2f A, Solar: %.2f A\n", i_grid, i_solar);

getPower()

cpp

float getPower(CurrentChannel channel) const;

Descrizione: Ottenere la potenza attiva per il canale specificato.

Parameters:
- channel - CURRENT_LOAD, CURRENT_GRID or CURRENT_SOLAR

Ritorna: Potenza in Watt

Esempio:

cpp

float p_grid = powerMeter.getPower(PowerMeterADC::CURRENT_GRID);

if (p_grid < 0) {
    Serial.println("Exporting to grid");
} else {
    Serial.println("Importing from grid");
}

Strutture dati

Measurements

cpp

struct Measurements {
    float voltage_rms;                  // RMS voltage (V)
    float current_rms[3];               // RMS currents [LOAD, GRID, SOLAR] (A)
    float power_active[3];              // Active power [LOAD, GRID, SOLAR] (W)
    float power_reactive[3];            // Reactive power (VAR) - Phase 2
    float power_apparent[3];            // Apparent power (VA) - Phase 2
    float power_factor[3];              // Power factor - Phase 2
    uint32_t timestamp_ms;              // Timestamp
    bool valid;                         // Data is valid
};

CurrentChannel

cpp

enum CurrentChannel : uint8_t {
    CURRENT_LOAD = 0,    // Load current (dimmer)
    CURRENT_GRID = 1,    // Grid current (import/export)
    CURRENT_SOLAR = 2,   // Solar panel current
    CURRENT_COUNT = 3
};

5.3 API DimmerHAL

File:
- components/acrouter_hal/include/DimmerHAL.h
- components/acrouter_hal/src/DimmerHAL.cpp

Pattern di progettazione: Singleton

Ottenere l'istanza

cpp

DimmerHAL& dimmer = DimmerHAL::getInstance();

Inizializzazione

begin()

cpp

bool begin();

Descrizione: Inizializzare il dimmer con rilevatore di passaggio per lo zero.

Ritorna: true in caso di successo

Esempio:

cpp

DimmerHAL& dimmer = DimmerHAL::getInstance();

if (dimmer.begin()) {
    Serial.println("DimmerHAL initialized");
} else {
    Serial.println("DimmerHAL init failed");
}

Controllo della potenza

setPower()

cpp

void setPower(DimmerChannel channel, uint8_t percent);

Descrizione: Impostare la potenza del dimmer istantaneamente.

Parameters:
- channel - CHANNEL_1 or CHANNEL_2
- percent - power 0-100%

Esempio:

cpp

dimmer.setPower(DimmerChannel::CHANNEL_1, 75);  // 75%
dimmer.setPower(DimmerChannel::CHANNEL_2, 50);  // 50% on second channel

setPowerSmooth()

cpp

void setPowerSmooth(DimmerChannel channel, uint8_t percent, uint32_t transition_ms);

Descrizione: Impostare la potenza con transizione graduale.

Parameters:
- channel - CHANNEL_1 or CHANNEL_2
- percent - target power 0-100%
- transition_ms - transition time in milliseconds

Esempio:

cpp

// Smoothly transition to 80% over 2 seconds
dimmer.setPowerSmooth(DimmerChannel::CHANNEL_1, 80, 2000);

// Smooth shutdown over 1 second
dimmer.setPowerSmooth(DimmerChannel::CHANNEL_1, 0, 1000);

getPower()

cpp

uint8_t getPower(DimmerChannel channel) const;

Descrizione: Ottenere la potenza corrente del canale.

Ritorna: Potenza 0-100%

Esempio:

cpp

uint8_t current_power = dimmer.getPower(DimmerChannel::CHANNEL_1);
Serial.printf("Dimmer 1: %d%%\n", current_power);

Controllo rapido

turnOff()

cpp

void turnOff(DimmerChannel channel);

Descrizione: Spegnere rapidamente un canale (0%).

Esempio:

cpp

dimmer.turnOff(DimmerChannel::CHANNEL_1);

turnOffAll()

cpp

void turnOffAll();

Descrizione: Spegnere tutti i canali.

Esempio:

cpp

dimmer.turnOffAll();  // Emergency shutdown

Curva di potenza

setCurve()

cpp

void setCurve(DimmerChannel channel, DimmerCurve curve);

Descrizione: Impostare il tipo di curva di potenza.

Parameters:
- channel - CHANNEL_1 or CHANNEL_2
- curve - LINEAR, RMS or LOGARITHMIC

Recommendations:
- RMS - for resistive loads (heaters, water heaters) - recommended
- LINEAR - linear dependency
- LOGARITHMIC - for LED lamps

Esempio:

cpp

// RMS curve for heater (recommended)
dimmer.setCurve(DimmerChannel::CHANNEL_1, DimmerCurve::RMS);

// Linear curve
dimmer.setCurve(DimmerChannel::CHANNEL_1, DimmerCurve::LINEAR);

Stato e informazioni

getStatus()

cpp

DimmerStatus getStatus(DimmerChannel channel) const;

Descrizione: Ottenere lo stato dettagliato del canale.

Ritorna: Struttura DimmerStatus

Esempio:

cpp

DimmerStatus status = dimmer.getStatus(DimmerChannel::CHANNEL_1);

Serial.printf("Initialized: %s\n", status.initialized ? "Yes" : "No");
Serial.printf("Active: %s\n", status.active ? "Yes" : "No");
Serial.printf("Power: %d%%\n", status.power_percent);
Serial.printf("Target: %d%%\n", status.target_percent);

isInitialized()

cpp

bool isInitialized() const;

Descrizione: Verificare se il dimmer è inizializzato.

Ritorna: true se inizializzato

Strutture dati

DimmerChannel

cpp

enum class DimmerChannel : uint8_t {
    CHANNEL_1 = 0,      // First channel (GPIO 19)
    CHANNEL_2 = 1       // Second channel (GPIO 23)
};

DimmerCurve

cpp

enum class DimmerCurve : uint8_t {
    LINEAR,         // Linear
    RMS,            // RMS-compensated (recommended)
    LOGARITHMIC     // Logarithmic
};

DimmerStatus

cpp

struct DimmerStatus {
    bool initialized;           // Initialized
    bool active;                // Active
    uint8_t power_percent;      // Current power (0-100%)
    uint8_t target_percent;     // Target power (during transition)
    DimmerCurve curve;          // Curve type
    uint32_t last_update_ms;    // Last update time
};

5.4 API ConfigManager

File:
- components/utils/include/ConfigManager.h
- components/utils/src/ConfigManager.cpp

Pattern di progettazione: Singleton

Namespace NVS: "acrouter"

Ottenere l'istanza

cpp

ConfigManager& config = ConfigManager::getInstance();

Inizializzazione

begin()

cpp

bool begin();

Descrizione: Inizializzare NVS e caricare la configurazione.

Ritorna: true in caso di successo

Esempio:

cpp

ConfigManager& config = ConfigManager::getInstance();

if (config.begin()) {
    Serial.println("ConfigManager initialized");
    Serial.printf("Router mode: %d\n", config.getConfig().router_mode);
}

Ottenere la configurazione

getConfig()

cpp

const SystemConfig& getConfig() const;

Descrizione: Ottenere il riferimento alla configurazione corrente.

Ritorna: Riferimento const a SystemConfig

Esempio:

cpp

const SystemConfig& cfg = config.getConfig();

Serial.printf("Mode: %d\n", cfg.router_mode);
Serial.printf("Kp: %.1f\n", cfg.control_gain);
Serial.printf("Threshold: %.1f W\n", cfg.balance_threshold);

Impostare i parametri

setRouterMode()

cpp

bool setRouterMode(uint8_t mode);

Descrizione: Impostare la modalità del router (salvata automaticamente in NVS).

Parameters:
- mode - mode 0-5

Ritorna: true se salvato con successo

Esempio:

cpp

config.setRouterMode(1);  // AUTO mode

setControlGain()

cpp

bool setControlGain(float gain);

Descrizione: Impostare il coefficiente Kp.

Parameters:
- gain - coefficient (10.0 - 1000.0)

Esempio:

cpp

config.setControlGain(200.0f);

setBalanceThreshold()

cpp

bool setBalanceThreshold(float threshold);

Descrizione: Impostare la soglia di bilanciamento.

Parameters:
- threshold - threshold in Watts (0.0 - 100.0)

Esempio:

cpp

config.setBalanceThreshold(10.0f);

setManualLevel()

cpp

bool setManualLevel(uint8_t level);

Descrizione: Impostare il livello per la modalità MANUAL.

Parameters:
- level - level 0-100%

Esempio:

cpp

config.setManualLevel(75);

setVoltageCoefficient()

cpp

bool setVoltageCoefficient(float coef);

Descrizione: Impostare il coefficiente di calibrazione della tensione.

Esempio:

cpp

config.setVoltageCoefficient(230.0f);

setCurrentCoefficient()

cpp

bool setCurrentCoefficient(float coef);

Descrizione: Impostare il coefficiente di calibrazione della corrente.

Esempio:

cpp

config.setCurrentCoefficient(30.0f);  // SCT-013-030

Operazioni batch

saveAll()

cpp

bool saveAll();

Descrizione: Salvare tutti i parametri in NVS.

Nota: Generalmente non necessario poiché ogni metodo set*() salva automaticamente.

loadAll()

cpp

bool loadAll();

Descrizione: Ricaricare la configurazione da NVS.

resetToDefaults()

cpp

bool resetToDefaults();

Descrizione: Ripristinare tutte le impostazioni ai valori di fabbrica e salvare in NVS.

Esempio:

cpp

if (config.resetToDefaults()) {
    Serial.println("Config reset to defaults");
}

Strutture dati

SystemConfig

cpp

struct SystemConfig {
    // Router parameters
    uint8_t router_mode;        // RouterMode (0-5)
    float control_gain;         // Kp (10.0 - 1000.0)
    float balance_threshold;    // Balance threshold (W)
    uint8_t manual_level;       // MANUAL level (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)
};

5.5 API HardwareConfigManager

File:
- components/utils/include/HardwareConfigManager.h
- components/utils/src/HardwareConfigManager.cpp

Pattern di progettazione: Singleton

Namespace NVS: "hw_config"

Ottenere l'istanza

cpp

HardwareConfigManager& hwConfig = HardwareConfigManager::getInstance();

Inizializzazione

begin()

cpp

bool begin();

Descrizione: Inizializzare e caricare la configurazione hardware da NVS.

Esempio:

cpp

HardwareConfigManager& hwConfig = HardwareConfigManager::getInstance();

if (hwConfig.begin()) {
    Serial.println("HardwareConfigManager initialized");
}

Configurazione dei canali ADC

setADCChannel()

cpp

bool setADCChannel(uint8_t channel, const ADCChannelConfig& config);

Descrizione: Configurare un canale ADC.

Parameters:
- channel - channel number (0-3)
- config - channel configuration

Ritorna: true in caso di successo

Esempio:

cpp

ADCChannelConfig voltage_cfg;
voltage_cfg.gpio = 35;
voltage_cfg.type = SensorType::VOLTAGE_AC;
voltage_cfg.multiplier = 230.0f;
voltage_cfg.offset = 0.0f;
voltage_cfg.enabled = true;

hwConfig.setADCChannel(0, voltage_cfg);

getADCChannel()

cpp

ADCChannelConfig getADCChannel(uint8_t channel) const;

Descrizione: Ottenere la configurazione di un canale ADC.

Esempio:

cpp

ADCChannelConfig cfg = hwConfig.getADCChannel(0);
Serial.printf("ADC0: GPIO%d, Type=%d, Mult=%.1f\n",
              cfg.gpio, static_cast(cfg.type), cfg.multiplier);

Configurazione del dimmer

setDimmerChannel()

cpp

bool setDimmerChannel(uint8_t channel, const DimmerChannelConfig& config);

Descrizione: Configurare un canale del dimmer.

Parameters:
- channel - 0 (Channel 1) or 1 (Channel 2)
- config - configuration

Esempio:

cpp

DimmerChannelConfig dim_cfg;
dim_cfg.gpio = 19;
dim_cfg.enabled = true;

hwConfig.setDimmerChannel(0, dim_cfg);

Configurazione del passaggio per lo zero

setZeroCross()

cpp

bool setZeroCross(uint8_t gpio, bool enabled = true);

Descrizione: Configurare il pin del rilevatore di passaggio per lo zero.

Esempio:

cpp

hwConfig.setZeroCross(18, true);  // GPIO18, enabled

Configurazione dei relè

setRelayChannel()

cpp

bool setRelayChannel(uint8_t channel, const RelayChannelConfig& config);

Descrizione: Configurare un canale relè.

Parameters:
- channel - 0 or 1
- config - relay configuration

Esempio:

cpp

RelayChannelConfig relay_cfg;
relay_cfg.gpio = 15;
relay_cfg.active_high = true;  // Active HIGH
relay_cfg.enabled = true;

hwConfig.setRelayChannel(0, relay_cfg);

Configurazione dei LED

setStatusLED()

cpp

bool setStatusLED(uint8_t gpio);

Descrizione: Configurare il GPIO per il LED di stato.

Esempio:

cpp

hwConfig.setStatusLED(17);

setLoadLED()

cpp

bool setLoadLED(uint8_t gpio);

Descrizione: Configurare il GPIO per il LED indicatore di carico.

Validazione

validate()

cpp

bool validate(String* error_msg = nullptr) const;

Descrizione: Validare la configurazione per individuare errori.

Parameters:
- error_msg - pointer to String for error message (optional)

Ritorna: true se la configurazione è valida

Checks:
- GPIO conflicts (one pin = one function)
- Pin validity for ADC (ADC1 only: 32-39)
- Input-only pins (34,35,36,39 cannot be outputs)

Esempio:

cpp

String error;
if (!hwConfig.validate(&error)) {
    Serial.printf("Validation failed: %s\n", error.c_str());
} else {
    Serial.println("Configuration is valid");
}

Operazioni batch

saveAll()

cpp

bool saveAll();

Descrizione: Salvare l'intera configurazione in NVS.

loadAll()

cpp

bool loadAll();

Descrizione: Caricare la configurazione da NVS.

resetToDefaults()

cpp

bool resetToDefaults();

Descrizione: Ripristinare ai valori di fabbrica.

printConfig()

cpp

void printConfig() const;

Descrizione: Stampare la configurazione su Serial.

Esempio:

cpp

hwConfig.printConfig();
// Output:
// === Hardware Configuration ===
// ADC0: GPIO35, VOLTAGE_AC, mult=230.0, enabled
// ADC1: GPIO39, CURRENT_LOAD, mult=30.0, enabled
// ...

Strutture dati

ADCChannelConfig

cpp

struct ADCChannelConfig {
    uint8_t gpio;               // GPIO pin (32-39 for ADC1)
    SensorType type;            // Sensor type
    float multiplier;           // Calibration multiplier
    float offset;               // Offset
    bool enabled;               // Channel enabled
};

DimmerChannelConfig

cpp

struct DimmerChannelConfig {
    uint8_t gpio;               // GPIO pin
    bool enabled;               // Channel enabled
};

RelayChannelConfig

cpp

struct RelayChannelConfig {
    uint8_t gpio;               // GPIO pin
    bool active_high;           // true=Active HIGH, false=Active LOW
    bool enabled;               // Channel enabled
};

SensorType

cpp

enum class SensorType : uint8_t {
    NONE = 0,           // Not used
    VOLTAGE_AC,         // ZMPT107 (AC voltage)
    CURRENT_LOAD,       // ACS-712 (dimmer load current)
    CURRENT_GRID,       // SCT-013 (grid current)
    CURRENT_SOLAR,      // SCT-013 (solar current)
    CURRENT_AUX1,       // Auxiliary channel 1
    CURRENT_AUX2        // Auxiliary channel 2
};

5.6 API WiFiManager

File:
- components/comm/include/WiFiManager.h
- components/comm/src/WiFiManager.cpp

Pattern di progettazione: Singleton

Ottenere l'istanza

cpp

WiFiManager& wifi = WiFiManager::getInstance();

Inizializzazione

begin()

cpp

bool begin();

Descrizione: Inizializzare il WiFi. Avvia automaticamente l'AP se non sono presenti credenziali STA.

Ritorna: true in caso di successo

Esempio:

cpp

WiFiManager& wifi = WiFiManager::getInstance();

if (wifi.begin()) {
    Serial.println("WiFiManager initialized");

    WiFiStatus status = wifi.getStatus();
    Serial.printf("AP IP: %s\n", status.ap_ip.toString().c_str());
}

Modalità AP

startAP()

cpp

bool startAP(const char* ssid = nullptr, const char* password = nullptr);

Descrizione: Avviare il punto di accesso.

Parameters:
- ssid - network SSID (nullptr = auto: "ACRouter_XXXXXX")
- password - password (nullptr = "12345678")

Esempio:

cpp

// With auto-generated SSID
wifi.startAP();

// With custom SSID
wifi.startAP("MyACRouter", "mypassword123");

stopAP()

cpp

void stopAP();

Descrizione: Arrestare il punto di accesso.

isAPActive()

cpp

bool isAPActive() const;

Ritorna: true se l'AP è attivo

Modalità STA

connectSTA()

cpp

bool connectSTA(const char* ssid, const char* password);

Descrizione: Connettersi a una rete WiFi.

Parameters:
- ssid - network SSID
- password - password

Ritorna: true se connesso

Esempio:

cpp

if (wifi.connectSTA("HomeNetwork", "password123")) {
    Serial.println("Connected to WiFi");

    WiFiStatus status = wifi.getStatus();
    Serial.printf("STA IP: %s\n", status.sta_ip.toString().c_str());
}

disconnectSTA()

cpp

void disconnectSTA();

Descrizione: Disconnettersi dalla rete STA.

isSTAConnected()

cpp

bool isSTAConnected() const;

Ritorna: true se connesso a STA

Scansione delle reti

scanNetworks()

cpp

std::vector scanNetworks();

Descrizione: Scansionare le reti WiFi disponibili.

Ritorna: Vettore di strutture WiFiNetwork

Esempio:

cpp

std::vector networks = wifi.scanNetworks();

Serial.printf("Found %d networks:\n", networks.size());
for (const auto& net : networks) {
    Serial.printf("  %s (RSSI: %d, Encrypted: %s)\n",
                  net.ssid.c_str(),
                  net.rssi,
                  net.encrypted ? "Yes" : "No");
}

Stato

getStatus()

cpp

WiFiStatus getStatus() const;

Descrizione: Ottenere lo stato WiFi completo.

Esempio:

cpp

WiFiStatus status = wifi.getStatus();

Serial.printf("State: %d\n", static_cast(status.state));
Serial.printf("STA connected: %s\n", status.sta_connected ? "Yes" : "No");
Serial.printf("AP active: %s\n", status.ap_active ? "Yes" : "No");

if (status.sta_connected) {
    Serial.printf("STA IP: %s\n", status.sta_ip.toString().c_str());
    Serial.printf("RSSI: %d dBm\n", status.rssi);
}

if (status.ap_active) {
    Serial.printf("AP IP: %s\n", status.ap_ip.toString().c_str());
    Serial.printf("Clients: %d\n", status.sta_clients);
}

Strutture dati

WiFiState

cpp

enum class WiFiState : uint8_t {
    IDLE,               // Not initialized
    AP_ONLY,            // AP only
    STA_CONNECTING,     // Connecting to STA
    STA_CONNECTED,      // Connected to STA
    AP_STA,             // Both modes
    STA_FAILED          // STA failed
};

WiFiStatus

cpp

struct WiFiStatus {
    WiFiState state;
    bool sta_connected;
    bool ap_active;
    IPAddress sta_ip;
    IPAddress ap_ip;
    String sta_ssid;
    String ap_ssid;
    int8_t rssi;
    uint8_t sta_clients;        // Clients on AP
};

WiFiNetwork

cpp

struct WiFiNetwork {
    String ssid;
    int8_t rssi;
    bool encrypted;
};

5.7 API WebServerManager

File:
- components/comm/include/WebServerManager.h
- components/comm/src/WebServerManager.cpp

Pattern di progettazione: Singleton

Ottenere l'istanza

cpp

WebServerManager& webServer = WebServerManager::getInstance();

Inizializzazione

begin()

cpp

bool begin(uint16_t http_port = 80);

Descrizione: Inizializzare il server HTTP.

Parameters:
- http_port - HTTP port (default 80)

Esempio:

cpp

WebServerManager& webServer = WebServerManager::getInstance();

if (webServer.begin(80)) {
    Serial.println("WebServer started on port 80");
}

Controllo

start()

cpp

void start();

Descrizione: Avviare il server web.

stop()

cpp

void stop();

Descrizione: Arrestare il server web.

isRunning()

cpp

bool isRunning() const;

Ritorna: true se il server è in esecuzione

Gestione delle richieste

handleClient()

cpp

void handleClient();

Descrizione: Gestire le richieste HTTP in arrivo. Chiamare da loop().

Esempio:

cpp

void loop() {
    webServer.handleClient();
    // ... rest of code
}

Endpoint REST API

Per l'elenco completo degli endpoint vedere Sezione 8: Endpoint GET e Sezione 9: Endpoint POST.

Gruppi principali:

Pagine web: /, /wifi, /settings/hardware
Stato: /api/status, /api/metrics, /api/config
Controllo: /api/mode, /api/manual, /api/calibrate
WiFi: /api/wifi/*
Hardware: /api/hardware/*
Sistema: /api/system/reboot

← Modalità del router | Indice | Avanti: Applicazione principale →

Prodotti

In Evidenza

Inizia

Integrazioni

Guide e Articoli

ACRouter

Vetrina Progetti

Iniziare

Integrazioni

Dimmer AC

DimmerLink

ACRouter

GitHub

5. API dei moduli e strutture dati

5.1 API RouterController

Ottenere l'istanza

Inizializzazione

begin()

Gestione delle modalità

setMode()

getMode()

Parametri di controllo

setControlGain()

getControlGain()

setBalanceThreshold()

getBalanceThreshold()

Controllo manuale (modalità MANUAL)

setManualLevel()

getManualLevel()

Ciclo di aggiornamento principale

update()

Arresto di emergenza

emergencyStop()

Ottenere lo stato

getStatus()

Strutture dati

RouterStatus

RouterMode

RouterState

5.2 API PowerMeterADC

Ottenere l'istanza

Inizializzazione

begin()

Controllo delle misurazioni

start()

stop()

isRunning()

Callback dei risultati

setCallback()

Calibrazione dei sensori

setVoltageCalibration()

setCurrentCalibration()

Recupero dati

getPowerData()

getVoltageRMS()

getCurrentRMS()

getPower()

Strutture dati

Measurements

CurrentChannel

5.3 API DimmerHAL

Ottenere l'istanza

Inizializzazione

begin()

Controllo della potenza

setPower()

setPowerSmooth()

getPower()

Controllo rapido

turnOff()

turnOffAll()

Curva di potenza

setCurve()

Stato e informazioni

getStatus()

isInitialized()

Strutture dati

DimmerChannel

DimmerCurve

DimmerStatus