Integracja Loxone: Wysyłanie danych do EnergyPal

Kompletny przewodnik konfiguracji Loxone Miniserver do wysyłania metryk PV i magazynu energii do EnergyPal przez HTTP POST. Cała konfiguracja odbywa się wizualnie w Loxone Config — bez programowania.

Wymagania

• Sterownik: Loxone Miniserver Gen 2 (wymagana obsługa HTTPS)
• Oprogramowanie: Loxone Config 14.0 lub nowszy
• Sieć: Miniserver musi mieć dostęp do internetu (port 443/HTTPS)
• Klucz API: Twój energy_connection_key od administratora EnergyPal
• Skonfigurowane urządzenia: kody urządzeń (np. PV-1, BESS-1) muszą być zarejestrowane w EnergyPal. Zweryfikuj za pomocą GET /v1/devices.

Miniserver Gen 1

Miniserver Gen 1 nie obsługuje wychodzących połączeń HTTPS. Jeśli używasz Gen 1, potrzebujesz lokalnego reverse proxy (np. nginx na Raspberry Pi lub NAS), które przekierowuje HTTP z Miniservera na HTTPS do api.energypal.ai. Zobacz obejście dla Gen 1 na dole tej strony.

Przegląd

Miniserver wysyła JSON z aktualnymi wartościami metryk do POST /v1/ingest co 15 minut. Generator Impulsów wyzwala Wirtualne Wyjście HTTP, a blok Status buduje treść JSON z wejść czujników.

Modbus / Wejścia analogowe
        │
        ▼
  ┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
  │ Blok Status  │────►│ Wirtualne Wyj.   │────►│ EnergyPal API   │
  │ (buduje JSON)│     │ HTTP POST        │     │ api.energypal.ai│
  └─────────────┘     └──────────────────┘     └─────────────────┘
        ▲
        │
  Generator Impulsów
  (co 15 min)

Krok 1: Utwórz Wirtualne Wyjście HTTP

1. W Loxone Config, w drzewie peryferiów kliknij prawym przyciskiem Virtual Outputs → Add Virtual Output.
2. Nazwij je EnergyPal Sender.
3. Ustaw Address na:

   https://api.energypal.ai

Dodaj komendę wyjścia

1. Kliknij prawym przyciskiem na Virtual Output → Add Virtual Output Command.
2. Nazwij je Send Metrics.
3. Skonfiguruj komendę:

Pole	Wartość
Command for ON	/v1/ingest
HTTP Method	POST
HTTP POST command	(patrz treść JSON poniżej)
HTTP Extensions for ON	X-API-Key: twoj-klucz-api\r\nContent-Type: application/json

Zamień twoj-klucz-api na swój klucz API w polu HTTP Extensions.

Krok 2: Zbuduj treść JSON

W polu HTTP POST command komendy Virtual Output wpisz:

{"metrics":{"PV-1":{"energy_generated_meter":<v1>},"PV-2":{"energy_generated_meter":<v2>},"BESS-1":{"soc":<v3>,"energy_exported_meter":<v4>,"energy_imported_meter":<v5>},"LOAD-0":{"energy_consumed_meter":<v6>}}}

Placeholdery <v1> do <v6> zostaną zastąpione rzeczywistymi wartościami z bloku Status:

Placeholder	Metryka	Jednostka
<v1>	Licznik produkcji PV-1	kWh
<v2>	Licznik produkcji PV-2	kWh
<v3>	Stan naładowania magazynu	%
<v4>	Licznik rozładowania magazynu	kWh
<v5>	Licznik ładowania magazynu	kWh
<v6>	Licznik zużycia energii	kWh

Własne urządzenia

Jeśli masz inną liczbę inwerterów lub magazynów, dostosuj szablon JSON i placeholdery <v>. Kody urządzeń muszą odpowiadać konfiguracji w EnergyPal — zweryfikuj za pomocą GET /v1/devices.

Krok 3: Podłącz wejścia czujników

1. Dodaj blok Status na stronie programu.
2. Podłącz wartości z czujników (z rozszerzeń Modbus, wejść analogowych lub innych bloków funkcyjnych) do wejść bloku Status:
   • AI1 → Licznik produkcji PV-1 (kWh) → mapuje na <v1>
   • AI2 → Licznik produkcji PV-2 (kWh) → mapuje na <v2>
   • AI3 → SOC magazynu (%) → mapuje na <v3>
   • AI4 → Licznik rozładowania (kWh) → mapuje na <v4>
   • AI5 → Licznik ładowania (kWh) → mapuje na <v5>
   • AI6 → Licznik zużycia energii (kWh) → mapuje na <v6>
3. Podłącz wyjście bloku Status (AQ) do wejścia komendy Virtual Output.

Krok 4: Dodaj timer

1. Dodaj blok Pulse Generator (Generator Impulsów) na stronie programu.
2. Skonfiguruj:
   • Czas impulsu (ON): 1 sekunda
   • Czas pauzy (OFF): 899 sekund
3. Podłącz wyjście Generatora Impulsów (Q) do wyzwalacza bloku Status (TI).

Wyzwala to wysyłanie danych co 15 minut (1 + 899 = 900 sekund).

Alternatywa: Pulse At

Aby wysyłać o stałych porach zegara, użyj bloku Pulse At. Ustaw wyzwalanie co 15 minut (np. o :00, :15, :30, :45 każdej godziny).

Krok 5: Weryfikacja

1. Zapisz i wyślij konfigurację do Miniservera.
2. Otwórz stronę Status w Loxone Config i obserwuj wyzwalanie wyjścia HTTP.
3. Sprawdź odpowiedź API — Miniserver nie wyświetla kodów HTTP natywnie, ale możesz zweryfikować czy dane dotarły:

# Sprawdź czy urządzenia są zarejestrowane i dane przychodzą
curl -H "X-API-Key: twoj-klucz-api" https://api.energypal.ai/v1/devices

Uwagi konfiguracyjne

• Interwał wysyłania: 15 minut odpowiada interwałowi agregacji systemu. Częstsze wysyłanie jest niepotrzebne; rzadsze grozi lukami w danych.
• Liczniki kumulatywne: wartości energy_*_meter muszą być zawsze rosnące. Nigdy nie resetuj — system automatycznie oblicza przyrost energii.
• Obsługa błędów: jeśli zapytanie się nie powiedzie, Miniserver automatycznie ponowi próbę przy następnym cyklu timera. API jest idempotentne — duplikaty w 15-minutowym oknie są pomijane.
• Kody urządzeń: muszą dokładnie odpowiadać konfiguracji w EnergyPal.
• Charset w Content-Type: Loxone może dołączyć ; charset=utf-8 do nagłówka Content-Type. Jest to nieszkodliwe — API to akceptuje.
• Diagnostyka: strona statusu w Loxone Config oraz log Miniservera (dostępny przez interfejs webowy) pokazują wyniki zapytań HTTP.

Odczyt cen energii

Aby pobierać prognozy cen energii na Miniserverze (do optymalizacji magazynu), zobacz dedykowany przewodnik: Odczyt cen energii (Loxone).

Testowanie za pomocą curl

Przed konfiguracją Miniservera przetestuj połączenie z API:

# Wysłanie testowych danych
curl -X POST https://api.energypal.ai/v1/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: twoj-klucz-api" \
  -d '{
    "metrics": {
      "PV-1": {"energy_generated_meter": 12345.0},
      "BESS-1": {"soc": 85.5, "energy_exported_meter": 500.0, "energy_imported_meter": 450.0},
      "LOAD-0": {"energy_consumed_meter": 98765.0}
    }
  }'

# Weryfikacja kodów urządzeń
curl -H "X-API-Key: twoj-klucz-api" https://api.energypal.ai/v1/devices

Obejście dla Gen 1

Jeśli posiadasz Miniserver Gen 1, skonfiguruj lokalne proxy HTTP-do-HTTPS:

1. Zainstaluj nginx na Raspberry Pi, NAS lub innym urządzeniu w sieci LAN, które jest zawsze włączone.
2. Skonfiguruj nginx do przekierowywania zapytań HTTP do API EnergyPal:

server {
    listen 8080;
    server_name _;

    location /v1/ {
        proxy_pass https://api.energypal.ai/v1/;
        proxy_set_header Host api.energypal.ai;
        proxy_set_header X-API-Key twoj-klucz-api;
        proxy_ssl_server_name on;
    }
}

3. W Loxone Config ustaw adres Virtual Output na http://192.168.x.x:8080 (IP proxy w sieci LAN).
4. Usuń X-API-Key z HTTP Extensions (nginx dodaje go automatycznie).

uwaga

Proxy musi być zawsze dostępne w sieci LAN. Jeśli przestanie działać, wysyłanie danych się zatrzyma. Rozważ upgrade do Miniserver Gen 2 dla bardziej niezawodnej konfiguracji.