JSON Schema#

Schematy plików konfiguracyjnych vCLU — formaty JSON, YAML i txt używane przez system.

`.vclu.json` — konfiguracja główna#

Źródło prawdy dla wszystkich ustawień. Przechowywany w katalogu CLU.

Ścieżka: {cluDir}/.vclu.json

{
  "setupCompleted": true,
  "createdAt": "2026-02-17T10:30:00Z",
  "lastModified": "2026-02-17T10:30:00Z",

  "device": {
    "name": "My CLU",
    "serialNumber": 285279991,
    "hardwareType": 18,
    "hardwareVersion": 1,
    "firmwareType": 3,
    "firmwareVersion": 1000,
    "firmwareVersionStr": "1.0.0-vclu",
    "deviceTypeId": "clu",
    "category": "CLU",
    "modules": [
      {
        "id": "mod_001",
        "typeId": "dout8t",
        "serial": "3300001234",
        "name": "Moduł 1",
        "hardwareType": 30
      }
    ],
    "ioObjects": [
      {
        "id": "DOU0001",
        "moduleId": "mod_001",
        "typeId": "dout",
        "index": 0,
        "name": "Moduł 1 DOU1",
        "luaType": 4
      }
    ]
  },

  "keys": {
    "key": "base64...",
    "iv": "base64...",
    "defaultIV": "base64...",
    "pin": "base64...",
    "broadcastKey": "base64...",
    "broadcastIV": "base64...",
    "broadcastEnabled": true
  },

  "auth": {
    "username": "admin",
    "passwordHash": "sha1hash..."
  },

  "mqttBroker": {
    "enabled": true,
    "port": 1883,
    "wsPort": 8080,
    "username": "mqtt_user",
    "password": "mqtt_pass"
  },

  "homeKit": {
    "enabled": true,
    "pin": "00102003",
    "port": 5123,
    "bridgeName": "vCLU Bridge",
    "serialNumber": "VCLU-001",
    "refreshInterval": 300
  },

  "metrics": {
    "enabled": true,
    "auth": false,
    "username": "",
    "password": ""
  },

  "plugins": {
    "pluginsDir": "~/.vclu/plugins",
    "repositories": [
      {
        "name": "vCLU Official",
        "url": "https://github.com/Domktorymysli/vclu-plugins",
        "enabled": true,
        "default": true
      }
    ],
    "installed": [
      {
        "id": "weather",
        "version": "1.0.0",
        "enabled": true,
        "repository": "vCLU Official",
        "installedAt": "2026-02-17T10:30:00Z",
        "config": {}
      }
    ]
  },

  "omFiles": [
    {
      "filename": "om_285279991.lua",
      "serial": 285279991,
      "cluName": "DOM20",
      "cluIp": "192.168.0.3",
      "objectCount": 45,
      "moduleCount": 5,
      "uploadedAt": "2026-02-17T10:30:00Z"
    }
  ]
}

Opis pól#

Pole	Typ	Opis
`setupCompleted`	bool	Czy kreator konfiguracji został ukończony
`createdAt`	ISO8601	Data utworzenia
`lastModified`	ISO8601	Data ostatniej modyfikacji

`device` — konfiguracja urządzenia#

Pole	Typ	Opis
`name`	string	Nazwa urządzenia
`serialNumber`	uint64	Numer seryjny
`hardwareType`	uint8	Typ sprzętu (0x12=Gate, 0x13=CLU)
`hardwareVersion`	uint8	Wersja sprzętu
`firmwareType`	uint8	Typ firmware (zwykle 0x03)
`firmwareVersion`	uint32	Wersja firmware
`firmwareVersionStr`	string	Wersja firmware (czytelna)
`deviceTypeId`	string	`"clu"` lub `"gate"`
`category`	string	`"CLU"` lub `"GATE"`
`modules`	array	Lista modułów I/O
`ioObjects`	array	Lista obiektów I/O

`device.modules[]` — moduł I/O#

Pole	Typ	Opis
`id`	string	ID modułu (np. `"mod_001"`)
`typeId`	string	Typ: `"dout8t"`, `"relay4"`, `"din8"`
`serial`	string	Numer seryjny modułu
`name`	string	Nazwa
`hardwareType`	uint8	Typ HW: 0x1e (DOUT8T), 0x15 (RELAY4), 0x14 (DIN8)

`device.ioObjects[]` — obiekt I/O#

Pole	Typ	Opis
`id`	string	ID obiektu (np. `"DOU0001"`)
`moduleId`	string	ID rodzica modułu
`typeId`	string	Typ: `"dout"`, `"din"`, `"analog_in"`
`index`	int	Indeks w module
`name`	string	Nazwa
`luaType`	int	Typ Lua: 4 (DOUT), 3 (DIN), 12 (Analog)

`keys` — klucze szyfrowania#

Pole	Typ	Opis
`key`	string (base64)	16-bajtowy klucz projektu
`iv`	string (base64)	16-bajtowy wektor IV
`defaultIV`	string (base64)	Domyślny IV
`pin`	string (base64)	8-bajtowy PIN (np. “00000000”)
`broadcastKey`	string (base64)	Klucz broadcast (opcjonalny)
`broadcastIV`	string (base64)	IV broadcast (opcjonalny)
`broadcastEnabled`	bool	Czy broadcast jest skonfigurowany

Klucze generowane automatycznie przez crypto/rand jeśli brak.

`auth` — uwierzytelnianie GUI#

Pole	Typ	Opis
`username`	string	Login
`passwordHash`	string	Hasz SHA1 hasła

`mqttBroker` — wbudowany broker MQTT#

Pole	Typ	Opis
`enabled`	bool	Aktywny
`port`	int	Port TCP (domyślnie 1883)
`wsPort`	int	Port WebSocket (domyślnie 8080)
`username`	string	Użytkownik brokera
`password`	string	Hasło brokera

`homeKit` — integracja Apple HomeKit#

Pole	Typ	Opis
`enabled`	bool	Aktywna
`pin`	string	Kod PIN parowania (np. “00102003”)
`port`	int	Port serwera
`bridgeName`	string	Nazwa bridge
`serialNumber`	string	Numer seryjny bridge
`refreshInterval`	int	Interwał odświeżania (s)

`metrics` — metryki Prometheus#

Pole	Typ	Opis
`enabled`	bool	Aktywne
`auth`	bool	Wymagaj uwierzytelnienia
`username`	string	Login (jeśli auth=true)
`password`	string	Hasło (jeśli auth=true)

`plugins` — system pluginów#

Pole	Typ	Opis
`pluginsDir`	string	Katalog pluginów
`repositories`	array	Repozytoria pluginów
`installed`	array	Zainstalowane pluginy

`keys.json` — klucze szyfrowania (TFTP)#

Plik kluczy w katalogu TFTP. Tworzony podczas wizarda.

Ścieżka: {cluDir}/a/keys.json

{
  "key": "dNmYo86Mw26WzlnCSrMMhw==",
  "iv": "ssxjISodN4B9F1+JdI+8ug==",
  "defaultIV": "ssxjISodN4B9F1+JdI+8ug==",
  "pin": "MDAwMDAwMDA=",
  "broadcastKey": "hd5SHpxl0N5+WEXTXlPQmw==",
  "broadcastIV": "BwYFBAMCAQAEAgkDBAEFBw==",
  "broadcastEnabled": true
}

Format identyczny z sekcją keys w .vclu.json. Wszystkie wartości base64-encoded, 16 bajtów (PIN: 8 bajtów).

`CONFIG.JSON` — format Object Manager#

Konfiguracja urządzenia w formacie OM. Serwowana przez TFTP, parsowana przez Object Manager.

Ścieżka: {cluDir}/a/CONFIG.JSON

{
  "sn": 3684849295,
  "mac": "46:0b:d4:48:0a:ec",
  "hwType": 18,
  "hwVer": 1,
  "fwType": 3,
  "fwApiVer": 1000,
  "fwVer": "0.3.232",
  "tfbusDevices": [
    "33000001:1e:02:01",
    "20100002:15:02:01"
  ],
  "zwaveDevices": []
}

Pole	Typ	Opis
`sn`	uint64	Numer seryjny (32-bit)
`mac`	string	Adres MAC
`hwType`	uint8	Typ sprzętu
`hwVer`	uint8	Wersja sprzętu
`fwType`	uint8	Typ firmware
`fwApiVer`	uint32	Wersja API firmware
`fwVer`	string	Wersja firmware (czytelna)
`tfbusDevices`	array	Moduły TFBus
`zwaveDevices`	array	Urządzenia Z-Wave (puste w vCLU)

Format TFBus#

{serialHex}:{hwTypeHex}:02:01

Fragment	Opis
`serialHex`	Hex numeru seryjnego modułu (np. `33000001`)
`hwTypeHex`	Hex typu HW: `1e`=DOUT8T, `15`=RELAY4, `14`=DIN8
`02:01`	Stałe identyfikatory protokołu

`config.txt` — konfiguracja TFTP (tekstowa)#

Format legacy dla konfiguracji TFTP. 7 linii + opcjonalne moduły.

Ścieżka: {cluDir}/a/config.txt

00000000
dba2568f
46:0b:d4:48:0a:ec
00000003
000003e8
00000012
00000001
33000001:1e:02:01
20100002:15:02:01

Linia	Pole	Format	Opis
1	PIN	8 znaków	Kod PIN (np. “00000000”)
2	Serial	8-znakowy hex	Numer seryjny (skrócony, ostatnie 4 bajty)
3	MAC	`xx:xx:xx:xx:xx:xx`	Adres MAC
4	Firmware Type	8-znakowy hex	Typ firmware
5	Firmware Version	8-znakowy hex	Wersja firmware
6	Hardware Type	8-znakowy hex	Typ sprzętu
7	Hardware Version	8-znakowy hex	Wersja sprzętu
8+	TFBus modules	`serial:type:02:01`	Po jednym module na linię

`config.json` — konfiguracja runtime#

Konfiguracja urządzenia do użytku wewnętrznego. Generowana automatycznie.

Ścieżka: {cluDir}/a/config.json

{
  "serialNumber": 2852799910974750602,
  "macAddress": "72:b5:79:eb:92:5c",
  "hardwareType": 19,
  "hardwareVersion": 1,
  "firmwareType": 3,
  "firmwareVersion": 11163050,
  "firmwareVersionString": "00aa55aa-0000",
  "status": "OK",
  "tfBusDevices": [
    "33000001:1e:02:01",
    "20100002:15:02:01"
  ]
}

`access_control.yaml` — kontrola dostępu#

Ustawienia widoczności obiektów per integracja.

Ścieżka: {cluDir}/access_control.yaml

objects:
  CLU221000290.DOU0001:
    mqtt: full
    homekit: hidden
  CLU221000290.DIMM0001:
    mqtt: readonly
    homekit: full
  CLU221000290.ROLLER0001:
    mqtt: hidden
    homekit: hidden

Poziomy dostępu#

Poziom	Opis
`full`	Widoczny i kontrolowalny (domyślny)
`readonly`	Stan widoczny, ale bez sterowania
`hidden`	Obiekt nie eksponowany do integracji

Priorytet#

Ręczne expose() w user.lua — najwyższy
AccessControl (ten plik) — stosowany przez autoExposeRegistry
autoExposeRegistry() — eksponuje resztę z domyślnymi ustawieniami

Zmiany w MQTT obowiązują natychmiast. HomeKit wymaga restartu bridge.

Typy urządzeń#

ID	Kategoria	Prefix SN	HW Type	Moduły
`gate`	GATE	5200	0x12	Nie
`clu`	CLU	2210	0x13	Tak

Typy modułów#

ID	HW Type	Prefix SN	Wyjścia	Wejścia	Analog
`dout8t`	0x1e	3300	8x DOUT	8x DIN	1x ANA
`relay4`	0x15	2010	4x DOUT	—	1x ANA
`din8`	0x14	1810	—	8x DIN	1x ANA

Przepływ konfiguracji#

ReadMasterConfig()
  → .vclu.json

PropagateConfig()
  → a/CONFIG.JSON    (format Object Manager)
  → a/config.txt     (format TFTP)
  → a/config.json    (format runtime)
  → a/main.lua       (jeśli nie istnieje)
  → a/om.lua         (jeśli nie istnieje)
  → a/user.lua       (jeśli nie istnieje)

ReadMasterConfig() zwraca (nil, nil) gdy plik nie istnieje — zawsze sprawdzaj oba warunki: err != nil || config == nil.

JSON Schema#

.vclu.json — konfiguracja główna#

Opis pól#

device — konfiguracja urządzenia#

device.modules[] — moduł I/O#

device.ioObjects[] — obiekt I/O#

keys — klucze szyfrowania#

auth — uwierzytelnianie GUI#

mqttBroker — wbudowany broker MQTT#

homeKit — integracja Apple HomeKit#

metrics — metryki Prometheus#

plugins — system pluginów#

keys.json — klucze szyfrowania (TFTP)#

CONFIG.JSON — format Object Manager#