Wprowadzenie do pluginów#

Pluginy rozszerzają vCLU o integracje z zewnętrznymi API, urządzeniami i usługami. Każdy plugin działa w izolowanym sandboxie z dostępem do Plugin API v2.

Dostępne pluginy#

Plugin	Opis	Typ
weather	Pogoda z OpenWeatherMap — temp, wilgotność, ciśnienie, wiatr	HTTP + poller
time-sync	Synchronizacja czasu z WorldTimeAPI — timezone, drift, DST	HTTP + poller
sun-position	Pozycja słońca i księżyca — wschód/zachód, azymut, faza	Obliczenia NOAA
telegram	Bot Telegram — wysyłanie wiadomości, polling komend	HTTP + polling
salda-recuperator	Sterowanie rekuperatorem Salda — temperatury, wentylator	HTTP + Basic Auth
supla-power-meter	Licznik energii Supla 3-fazowy — moc, napięcie, prąd	HTTP + Direct Link
influx-metrics	Kolektor metryk InfluxDB — Line Protocol, batching	Factory
example	Szablon z przykładami wszystkich API	Demo/template

Szybki start#

1. Instalacja z UI#

/plugins → wybierz plugin → Install → wypełnij konfigurację → Enable.

2. Instalacja manualna#

Skopiuj plugin do plugins/vclu--weather/, dodaj wpis w .vclu.json:

{
  "plugins": {
    "installed": [
      {
        "id": "@vclu/weather",
        "version": "1.0.0",
        "enabled": true,
        "repository": "vCLU Official",
        "config": {
          "apiKey": "your-key",
          "city": "Warsaw"
        }
      }
    ]
  }
}

3. Użycie w user.lua#

local weather = Plugin.getPlugin("@vclu/weather")

if weather and weather:isReady() then
    local temp = weather:getTemperature()
    Logger:getShared():info("Temperatura: " .. temp .. "°C")
end

-- Subskrypcja eventów
EventBus:getShared():on("weather:changed", function(data)
    if data.temp < 0 then
        _:byTag("ogrzewanie"):on()
    end
end)

4. Expose do Home Assistant#

local weather = Plugin.getPlugin("@vclu/weather")
if weather then
    local tempSensor = weather:get("temperature")
    if tempSensor then
        expose(tempSensor, "temperature", {
            name = "Temperatura zewnętrzna",
            unit = "°C"
        })
    end
end

Architektura#

┌─────────────────────────────────────┐
│            .vclu.json               │  Konfiguracja + lista pluginów
├─────────────────────────────────────┤
│         Plugin Manager              │  Instalacja, load/unload
├──────────┬──────────┬───────────────┤
│ weather  │ telegram │ sun-position  │  Pluginy (init.lua)
│ sandbox  │ sandbox  │ sandbox       │  Izolacja + resource tracking
└──────────┴──────────┴───────────────┘

Każdy plugin:

Ma własny katalog z plugin.json + init.lua
Działa w izolowanym środowisku Lua
Ma dostęp tylko do swojego namespace w rejestrze
Zasoby (timery, eventy, MQTT) auto-czyszczone przy unload