modborno3/CONFIG.md

# Konfiguracja programu modb_orno3

## Parametry konfiguracyjne

Wszystkie parametry są zdefiniowane na początku pliku `modb_orno3.c` (linie 11-40):

```c
/* KONFIGURACJA PROGRAMU - EDYTUJ TU */

/* Port szeregowy */
#define USB_DEV_DEFAULT "/dev/ttyUSB0"

/* Adresy urządzeń Modbus RTU */
#define ORNO_SLAVE_ADR 2
#define SUN2000_SLAVE_ADR 3

/* Parametry timing dla ORNO (mikrosekund) */
#define ORNO_RTS_DELAY 5000          /* RTS delay: 5ms */
#define ORNO_BYTE_TIMEOUT 2500       /* Byte timeout: 2.5ms */

/* Parametry timing dla SUN2K (mikrosekund) */
#define SUN2K_RTS_DELAY 5000         /* RTS delay: 5ms */
#define SUN2K_BYTE_TIMEOUT 2500      /* Byte timeout: 2.5ms */

/* Przerwa między ORNO a SUN2K (mikrosekund) */
#define DELAY_BETWEEN_DEVICES 100000 /* 100ms */

/* MQTT - ustaw 1 aby wyłączyć MQTT */
#define DISABLE_MQTT 0               /* 0 = MQTT włączony, 1 = wyłączony */

/* Broker MQTT */
#define MQTT_BROKER "10.1.1.1"
#define MQTT_PORT 1883

/* Tryb pracy */
#define READ_LOOP false              /* false = jeden odczyt, true = pętla co 5s */
#define READ_ORNO true               /* Czy odczytywać ORNO */
#define READ_SUN2K true              /* Czy odczytywać SUN2K */
```

## Uruchomienie

### Kompilacja:
```bash
bash cc-modb_orno3.sh
```

### Uruchomienie:
```bash
./modborno3
```

Program uruchamia się **bez parametrów** i używa konfiguracji z #define.

## Sekwencja działania

1. **Odczyt ORNO** (adres Modbus: 2)
   - Napięcia L1, L2, L3
   - Prądy L1, L2, L3
   - Moc Total, L1, L2, L3
   - Energia Total, L1, L2, L3
   - Częstotliwość

2. **Przerwa 100ms**

3. **Odczyt SUN2K** (adres Modbus: 3)
   - Wszystkie rejestry falownika
   - Czasy start/shutdown
   - Statusy
   - Moce
   - Energia dzienna i całkowita

## Tematy MQTT

### ORNO:
- `/energy/orno/U` - napięcia (JSON: U1, U2, U3)
- `/energy/orno/I` - prądy (JSON: I1, I2, I3)
- `/energy/orno/P` - moc (JSON: P_Tot, P1, P2, P3)
- `/energy/orno/W` - energia (JSON: W_Tot, W1, W2, W3)
- `/energy/orno/Hz` - częstotliwość (wartość)

### SUN2K:
- `/energy/SUN2K` - wszystkie parametry (JSON dla każdego rejestru)

## Modyfikacja konfiguracji

1. Edytuj plik `modb_orno3.c`
2. Zmień wartości #define
3. Przekompiluj: `bash cc-modb_orno3.sh`
4. Uruchom: `./modborno3`

## Przykłady modyfikacji

### Wyłączenie MQTT:
```c
#define DISABLE_MQTT 1
```

### Zmiana adresu brokera:
```c
#define MQTT_BROKER "192.168.1.100"
#define MQTT_PORT 1883
```

### Tryb ciągły (pętla co 5s):
```c
#define READ_LOOP true
```

### Tylko ORNO (bez SUN2K):
```c
#define READ_SUN2K false
```

### Zmiana przerwy między odczytami (200ms):
```c
#define DELAY_BETWEEN_DEVICES 200000
```

## Walidacja danych i zabezpieczenia MQTT

### Automatyczna walidacja wartości

Program **automatycznie waliduje** wszystkie odczytane wartości przed wysłaniem do MQTT.
Dane są wysyłane do MQTT **tylko** gdy:

1. ✅ Odczyt Modbus zakończył się sukcesem (prawidłowa liczba rejestrów)
2. ✅ Wartość nie jest **NaN** (Not a Number)
3. ✅ Wartość nie jest **Inf** (Infinity)
4. ✅ Wartość mieści się w **rozsądnym zakresie**

### Zakresy walidacji dla ORNO

| Parametr | Zakres | Jednostka | Powód |
|----------|--------|-----------|-------|
| **Napięcia L1/L2/L3** | 150 - 280 | V | Typowy zakres sieci UE (230V ±20%) |
| **Prądy L1/L2/L3** | 0 - 100 | A | Zabezpieczenie instalacji domowej |
| **Moc Total/L1/L2/L3** | -25000 - +25000 | W | Pozwala na generację (wartości ujemne) |
| **Energia Total/L1/L2/L3** | 0 - 1000000 | kWh | Licznik nie może mieć ujemnej energii |
| **Częstotliwość** | 47 - 53 | Hz | Typowy zakres sieci UE (50Hz) / US (60Hz) |

### Logi walidacji

Program wyświetla szczegółowe informacje o walidacji:

**Gdy dane są prawidłowe:**
```
Voltages: L1=225.8 V, L2=221.3 V, L3=229.8 V
MQTT: Published voltages
```

**Gdy odczyt się nie powiódł:**
```
Failed to read currents: Resource temporarily unavailable
(brak komunikatu MQTT - dane nie są wysyłane)
```

**Gdy wartość jest poza zakresem:**
```
WARNING: Value 350.5 out of range [150.0, 280.0]
MQTT: Skipping voltages - invalid values
```

**Gdy wartość jest NaN lub Inf:**
```
WARNING: Value is NaN
MQTT: Skipping power - invalid values
```

### Zabezpieczenia dla SUN2K

Dla urządzenia SUN2K program:

- ❌ **NIE wysyła** danych gdy odczyt się nie powiódł
- ❌ **NIE używa** starych wartości (`buf_last_val`) po błędzie
- ✅ **Tylko** aktualne, poprawnie odczytane wartości są publikowane

**Przykład:**
```
modbus_read_registers addr=0x7D55 nb=1 -> ERR (Connection timed out)
Frequency: Failed to 11 read: Connection timed out
MQTT: Skipping Frequency - no valid data
```

### Dlaczego to ważne?

**Bez walidacji:**
- Błędne odczyty (CRC errors) mogły wysyłać śmieciowe dane do MQTT
- Wartości NaN/Inf mogły powodować błędy w systemach monitoringu
- Niemożliwe wartości (np. 10000V) mogły wywoływać fałszywe alarmy

**Z walidacją:**
- ✅ Tylko **poprawne** wartości trafiają do MQTT
- ✅ System monitoringu dostaje **wiarygodne** dane
- ✅ Brak **fałszywych alarmów** z powodu błędnych odczytów
- ✅ **Logi** pokazują dokładnie co poszło nie tak

### Kod walidacji

Funkcja walidacji znajduje się w [modb_orno3.c:237-250](modb_orno3.c#L237-L250):

```c
int is_valid_float(float value, float min_val, float max_val)
{
    if (isnan(value)) {
        printf("WARNING: Value is NaN\n");
        return 0;
    }
    if (isinf(value)) {
        printf("WARNING: Value is Inf\n");
        return 0;
    }
    if (value < min_val || value > max_val) {
        printf("WARNING: Value %.2f out of range [%.2f, %.2f]\n",
               value, min_val, max_val);
        return 0;
    }
    return 1;
}
```

Walidacja jest wywoływana dla każdego pomiaru przed wysłaniem do MQTT.

### Modyfikacja zakresów walidacji

Jeśli chcesz zmienić zakresy walidacji (np. dla instalacji przemysłowej):

1. Otwórz plik `modb_orno3.c`
2. Znajdź sekcję z walidacją (np. dla napięć około linii 370)
3. Zmień wartości w `is_valid_float()`:

**Przykład - zwiększenie zakresu prądów do 200A:**
```c
/* Przed: */
if (is_valid_float(I1, 0.0, 100.0) && ...

/* Po: */
if (is_valid_float(I1, 0.0, 200.0) && ...
```

4. Przekompiluj: `bash cc-modb_orno3.sh`