Struktura pluginu#

Katalog pluginu#

plugins/vclu--weather/
├── plugin.json          # Manifest (wymagany)
├── init.lua             # Punkt wejścia (wymagany)
└── README.md            # Dokumentacja (opcjonalny)

Konwencja nazw: {namespace}--{shortId} — np. vclu--weather dla @vclu/weather.

Minimalny plugin#

plugin.json#

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0"
}

init.lua#

local plugin = Plugin:new("my-plugin", {
    name = "My Plugin",
    version = "1.0.0"
})

plugin:onInit(function(config)
    plugin:log("info", "Plugin załadowany")
end)

return plugin

Pełna struktura init.lua#

local plugin = Plugin:new("weather", {
    name = "Weather Plugin",
    version = "2.0.0",
    description = "OpenWeatherMap integration"
})

-- 1. Stan wewnętrzny
local state = {
    ready = false,
    lastUpdate = 0,
    lastError = nil,
}

-- 2. Inicjalizacja
plugin:onInit(function(config)
    if not config.apiKey then
        plugin:log("error", "apiKey is required")
        return
    end

    -- Obiekty w rejestrze
    plugin:upsertObject("current", {ready = false})

    -- Sensory/kontrolki
    plugin:sensor("temperature", function() return state.temp end)

    -- Poller
    local poller = plugin:poller("fetch", {
        interval = (config.interval or 3600) * 1000,
        immediate = true,
        onTick = function(done)
            -- pobieranie danych...
            done()
        end
    })
    poller:start()
end)

-- 3. Cleanup
plugin:onCleanup(function()
    plugin:log("info", "Plugin stopped")
end)

-- 4. Public API
function plugin:isReady() return state.ready end
function plugin:getData() return state end
function plugin:refresh() end
function plugin:getStats() end

return plugin

Konwencje#

Standardowy state#

local state = {
    ready = false,        -- dane dostępne?
    lastUpdate = 0,       -- os.time() ostatniej aktualizacji
    lastError = nil,      -- ostatni błąd lub nil
}

Standardowe public API#

function plugin:isReady() return state.ready end
function plugin:getLastError() return state.lastError end
function plugin:getData() return state end
function plugin:refresh() if poller then poller:poll() end end
function plugin:getStats() if poller then return poller:stats() end end

Ścieżki w rejestrze#

Obiekty pluginu trafiają do namespace:

plugins.{namespace}.{shortId}.{path}

Plugin	Ścieżka	Opis
weather	`plugins.vclu.weather.current`	Dane pogodowe
time-sync	`plugins.vclu.time-sync.current`	Dane czasu
sun-position	`plugins.vclu.sun-position.sun`	Pozycja słońca
sun-position	`plugins.vclu.sun-position.moon`	Faza księżyca
salda-recuperator	`plugins.vclu.salda-recuperator.data`	Dane rekuperatora
supla-power-meter	`plugins.vclu.supla-power-meter.power`	Dane licznika

Identyfikatory pluginu#

Format	Przykład	Gdzie
Full ID	`@vclu/weather`	`.vclu.json`, Plugin.getPlugin()
Short ID	`weather`	plugin.json `id`, Plugin:new()
Dir name	`vclu--weather`	Katalog na dysku
Namespace	`vclu`	Prefix rejestrowy