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#

graph TD
    config[".vclu.json<br/><i>Konfiguracja + lista pluginów</i>"]
    manager["Plugin Manager<br/><i>Instalacja, load/unload</i>"]
    subgraph "Pluginy (init.lua)"
        w["weather<br/>sandbox"]
        t["telegram<br/>sandbox"]
        s["sun-position<br/>sandbox"]
    end

    config --> manager
    manager --> w
    manager --> t
    manager --> s

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