Najwięcej pracy pochłania zwykle przygotowanie modelu i uporządkowanie nazw. Sam wygląd mebla nie mówi Home Assistant, którym urządzeniem ma sterować. Potrzebne jest powiązanie dwóch identyfikatorów: obiektu w scenie oraz encji w Home Assistant (HA), czyli konkretnej funkcji urządzenia.

Punktem odniesienia są Home Assistant 2026.10, floor3d-card 1.5.3 oraz nasza instalacja z własną warstwą sterowania. Wersja 1.5.3 z kwietnia 2023 to ostatnie wydanie oryginalnej karty i od tamtej pory projekt nie dostał nowej wersji. U nas działa z HA 2026.10 i 2026.11, ale po większej aktualizacji HA sprawdź, czy model nadal się wczytuje. Przełącznik pełnych ścian, filtry ikon, lista urządzeń i rozwijana lista halogenów to rozszerzenia przygotowane w tej instalacji. Nie pojawiają się po samej instalacji oryginalnej karty. Poniżej najpierw uruchamiamy podstawowy model i sterowanie, a dalej pokazujemy zastosowanie własnych dodatków oraz prostą listę urządzeń, którą można odtworzyć bez dodatkowego kodu. Instrukcja prowadzi do standardowej karty Floor3D; nie jest instalatorem naszej prywatnej nakładki.

1. Przygotuj HA, listę urządzeń i model

Potrzebujesz działającego Home Assistanta, zainstalowanego i skonfigurowanego HACS, możliwości zapisu plików w katalogu konfiguracji HA oraz komputera do modelowania. HACS (Home Assistant Community Store) służy do pobierania integracji i kart tworzonych przez społeczność. Jeśli jeszcze go nie masz, wykonaj najpierw instalację i wstępną konfigurację HACS zgodnie z jego dokumentacją. Floor3D korzysta z grafiki 3D w przeglądarce; duża liczba szczegółowych mebli i cieni może obciążać starszy tablet.

  1. Zrób kopię zapasową HA (Ustawienia → System → Kopie zapasowe) i zachowaj konfigurację panelu (dashboardu).
  2. W Ustawienia → Urządzenia oraz usługi → Rejestr encji znajdź urządzenia, które mają trafić na plan.
  3. Sprawdź ich działanie na zwykłych kartach. Zapisz identyfikatory, np. light.lampa_salon, cover.brama_garazowa i climate.ogrzewanie.
  4. Przygotuj aktualny rzut domu. Zaznacz zmiany wykonane po budowie: usunięte ściany, nowe schody i zamurowane przejścia.

W naszym modelu takie sprawdzenie ujawniło między innymi nieistniejące przejście do garażu i błędne ustawienie wyposażenia łazienki. Najpierw popraw geometrię, później wiąż urządzenia – ponowny eksport modelu może zmienić nazwy obiektów.

2. Narysuj dom w programie 3D

Autor Floor3D opisuje współpracę ze Sweet Home 3D. Możesz użyć innego programu eksportującego poprawne OBJ i MTL, ale poniższa ścieżka dotyczy komputerowej wersji Sweet Home 3D 7.5. Wersja przeglądarkowa może mieć inne menu i możliwości eksportu.

  1. Utwórz nowy projekt. W File → Preferences (Plik → Preferencje) wybierz jednostki, np. centymetry. Jeśli pracujesz na rzucie, otwórz Plan → Import background image. W kreatorze wskaż dwa końce odcinka o znanej długości i wpisz jego rzeczywisty wymiar. Ustal położenie obrazu, a dopiero potem obrysuj ściany. Bez podkładu wprowadzaj rzeczywiste wymiary ścian podczas rysowania lub w ich właściwościach.
  2. Wybierz Plan → Create walls (rysowanie ścian). Klikaj narożniki; dwuklikiem zakończ rysowanie. Autor Floor3D zaleca umieszczenie górnego lewego narożnika planu w punkcie 0,0. Odtwórz ściany zewnętrzne i podział pomieszczeń, sprawdzając wymiary.
  3. Przeciągnij drzwi i okna z katalogu po lewej na odpowiednie ściany. Dwuklikiem otwórz ich właściwości i dopasuj rozmiary. Dodaj rzeczywiste przejścia. Nie umieszczaj drzwi tam, gdzie faktycznie jest pełna ściana.
  4. Przeciągnij lampę z katalogu do pokoju. Nadaj jej czytelną nazwę we właściwościach. Dodaj uproszczone wyposażenie: lampy, kocioł, bramę, meble i elementy ogrodu.
  5. Sprawdź scenę z góry oraz pod kątem. Upewnij się, że szafa nie stoi w drzwiach, a element przeznaczony do klikania nie jest schowany za ścianą.
  6. Zapisz projekt źródłowy przed eksportem.

Każdy element, który ma osobno reagować, powinien być odrębnym obiektem lub świadomie przygotowaną grupą. Nie łącz wszystkich lamp i mebli w jedną bryłę. Zacznij od prostego salonu: podłoga, ściany i jedna lampa wystarczą do sprawdzenia całego procesu.

3. Wyeksportuj i skopiuj komplet plików

Najpierw zdecyduj, jaki model można udostępnić. Pliki z katalogu www są dostępne pod /local/ bez logowania do HA. Dotyczy to osób, które mogą połączyć się z twoim serwerem; zewnętrzne zabezpieczenia sieci lub serwera pośredniczącego mogą ograniczać dostęp. Nie umieszczaj tam haseł, tokenów ani prywatnych dokumentów. Dokładny model domu też może ujawniać prywatne informacje. Do nauki i udostępniania wybierz prosty pokój demonstracyjny.

  1. W Sweet Home 3D wybierz 3D View → Export to OBJ format. Nazwa może być przetłumaczona w polskiej wersji programu.
  2. Zapisz wynik do osobnego folderu. Powstaną OBJ z geometrią, MTL z materiałami oraz ewentualne pliki tekstur.
  3. Otwórz katalog konfiguracji HA w używanym menedżerze plików, np. przez skonfigurowany udział Samba lub edytor plików. Utwórz w nim www, a w środku dom3d. W HA OS ścieżka wewnątrz systemu to /config/www/dom3d/; w kontenerze użyj odpowiadającego jej katalogu zamontowanego jako /config. Skopiuj cały komplet eksportu. Jeśli katalog www powstał po raz pierwszy, uruchom HA ponownie.
  4. Zachowaj nazwy i wzajemne ścieżki plików. Dla przykładowego eksportu przyjmujemy dom.obj i dom.mtl.

W adresie przeglądarki katalog www jest udostępniany jako /local/. Dlatego plik /config/www/dom3d/dom.obj karta wczyta z /local/dom3d/dom.obj. Nie wpisuj ścieżki z dysku Windows do konfiguracji karty.

Otwórz w przeglądarce adres swojego HA zakończony /local/dom3d/dom.obj, a następnie /local/dom3d/dom.mtl. Pobranie pliku lub wyświetlenie jego tekstu potwierdza ścieżkę. Błąd 404 oznacza, że trzeba sprawdzić katalog, wielkość liter i nazwy. Zasady udostępniania plików opisuje dokumentacja Home Assistant.

4. Zainstaluj kartę Floor3D

  1. W HACS wyszukaj floor3d-card projektu adizanni/floor3d-card i pobierz kartę. Nie myl jej z forkami o podobnych nazwach, np. giosci1994/floor3d-card, rozwijanym w 2026 roku. Ich ustawienia mogą się różnić od opisanych tutaj, a tego poradnika na forkach nie sprawdzaliśmy.
  2. Sprawdź zasób JavaScript w Ustawienia → Panele → menu ⋮ → Zasoby. Typ musi być ustawiony na moduł JavaScript. Nie dodawaj drugi raz zasobu, który już utworzył HACS.
  3. Odśwież przeglądarkę przez Ctrl+F5.
  4. Utwórz osobną zakładkę dashboardu, włącz edycję i dodaj kartę ręczną z konfiguracją:
type: custom:floor3d-card
name: Dom 3D
path: /local/dom3d/
objfile: dom.obj
mtlfile: dom.mtl
backgroundColor: '#e6e9ec'
globalLightPower: 0.6
shadow: 'no'
click: 'yes'
editModeNotifications: 'yes'
entities: []

Zapisz i sprawdź, czy model się wczytał. Na tym etapie powinien dać się oglądać i obracać, ale nie steruje żadnym urządzeniem. Jeżeli obraz jest pusty, najpierw napraw wczytywanie plików. Dodawanie encji nie rozwiąże błędnej ścieżki.

5. Odczytaj identyfikator obiektu i podepnij lampę

Identyfikatory odczytuj najpierw na modelu z pustym entities: []. W oryginalnej karcie 1.5.3 dwuklik i dotyk uruchamiają inną obsługę niż pojedynczy klik myszą. Przy już powiązanej lampie mogą wywołać przełączenie światła mimo action: more-info. To wynika z kodu tego wydania; nie przenoś automatycznie działania naszej nakładki na standardową kartę.

  1. Wróć do edycji karty. Pozostaw entities: [] i editModeNotifications: 'yes'. Klikaj model w podglądzie edytowanej karty.
  2. Kliknij dwukrotnie obiekt lampy. Zapisz pokazany identyfikator modelu. Nie zakładaj, że jest taki sam jak etykieta mebla w programie do projektowania.
  3. W edytorze kodu zastąp entities: [] poniższym wpisem, podstawiając oba własne identyfikatory:
entities:
  - entity: light.lampa_salon
    object_id: lampa_salon
    type3d: light
    action: more-info
    light:
      lumens: 800

light.lampa_salon to encja w HA, a lampa_salon to przykładowa nazwa obiektu w OBJ. Wartość lumens wpływa na wizualizację i powinna być dopasowana do sceny; nie jest pomiarem rzeczywistego oświetlenia. Encje wpisuj w edytorze kodu: użytkownicy zgłaszają, że w nowszych wersjach HA wybór encji w edytorze wizualnym karty nie działa.

  1. Zapisz kartę i wyjdź z edycji.
  2. Wykonaj pojedynczy krótki klik myszą na lampie: przy click: 'yes' i action: more-info powinien otworzyć się standardowy panel dokładnie tej encji. Sprawdź nazwę przed użyciem sterowania.
  3. Przełącz światło w panelu i obserwuj urządzenie oraz stan modelu. Jasność i kolor są dostępne tylko wtedy, gdy obsługuje je właściwa integracja.

Przed użyciem telefonu lub tabletu sprawdź jego gesty osobno. Ustawienie more-info nie gwarantuje, że dotknięcie modelu zachowa się jak kliknięcie myszą. Do pierwszego uruchomienia i obsługi urządzeń, których nie chcesz uruchomić niechcący, użyj standardowych kontrolek HA obok modelu.

6. Dodaj bramę i ogrzewanie

Dla pojedynczego kliknięcia myszą można wskazać panel encji przez type3d: gesture i action: more-info. Poniższe wpisy dotyczą tej ścieżki obsługi w wersji 1.5.3, przy click: 'yes'. Dopisz je do istniejącej listy entities:

  - entity: cover.brama_garazowa
    object_id: brama_garazowa
    type3d: gesture
    action: more-info
  - entity: climate.ogrzewanie
    object_id: kociol
    type3d: gesture
    action: more-info

Nie traktuj tego przykładu jako gotowej konfiguracji wszystkich gestów. Osobna obsługa dwukliku i dotyku dla gesture oczekuje również parametrów wywoływanej usługi, których powyższe wpisy nie definiują. Mogą więc nie zachować się jak pojedynczy klik. Na pierwszy pulpit, szczególnie dotykowy, wybierz zwykłą kartę Encje z bramą i ogrzewaniem obok modelu; dodaje się ją tak samo jak listę halogenów w kroku 8. Przed próbą ruchu sprawdź otoczenie bramy. Jej rysunek ani kontaktron nie zastępują encji napędu.

Panel pieca powinien prowadzić do encji climate, jeżeli chcesz regulować temperaturę ogrzewania. Ciepła woda może być oddzielną encją water_heater. Dla kilku funkcji jednego urządzenia użyj osobnej listy kontrolek obok modelu albo własnego okna wyboru; nie wiąż wszystkich działań z jednym nieopisanym kliknięciem.

Jacuzzi potraktuj podobnie: oddziel temperaturę, filtr, bąbelki i lampy wokół niecki. Zasilanie całego urządzenia nie jest zamiennikiem termostatu. Jeśli encja ma stan unavailable, najpierw napraw jej integrację poza modelem.

7. Ustaw kamerę i widoczność pomieszczeń

  1. W trybie edycji ustaw model w wygodnym położeniu.
  2. Dwuklik w pustym miejscu sceny pozwala odczytać ustawienie kamery zgodnie z mechanizmem karty. Skopiuj pokazane camera_position, camera_rotate i camera_target do głównego poziomu konfiguracji karty, obok path i entities, a nie do wpisu lampy. Zachowaj wcięcia i wartości z własnego widoku.
  3. Do przybliżenia pokoju dodaj na głównym poziomie karty poniższy blok. Zastąp ID_PODLOGI_SALONU odczytanym identyfikatorem podłogi. distance podaje odległość kamery w centymetrach; 500 to przykład 5 m, nie wartość dobra dla każdego modelu.
zoom_areas:
  - zoom: Salon
    object_id: ID_PODLOGI_SALONU
    distance: 500
  1. Sprawdź widok na ekranie, na którym plan będzie używany: duży monitor i tablet mogą inaczej przycinać scenę.

Nie włączaj od razu wszystkich cieni. Najpierw uruchom model bez nich, dodaj kilka lamp i porównaj płynność. Szczegółowy model dekoracyjny nie zawsze jest wygodnym panelem sterowania.

8. Dodaj listę urządzeń obok modelu

Widok salonu z pełnymi przyciskami własnego panelu Dom 3D
Widok salonu z ikonami urządzeń. Pasek pomieszczeń i dodatkowe przyciski należą do własnego rozszerzenia instalacji. Zrzut ekranu: instalacja kocel / RadioMesh.

W używanym przez nas Domu 3D oryginalną kartę rozszerza lokalny kod JavaScript. Rozdziela on geometrię od interfejsu: ikona wskazuje obiekt modelu, ale akcja kieruje do określonej encji HA. Dzięki temu można łatwiej wybierać małe lampy i urządzenia schowane za meblami.

Rozszerzenie Jak działa własne rozszerzenie
Pełne ściany / widok wnętrza Model z oddzielonymi górnymi częściami ścian oraz kod przełączający ich widoczność
Wybór pokoju Lista pomieszczeń, ich obiektów i celów kamery
Filtry światła, czujniki i bramy Typ przypisany do każdego znacznika oraz filtrowanie ikon
Lista urządzeń Powiązania encji z pokojami i otwieranie natywnego okna HA
Rozwijane halogeny Oddzielne encje lamp oraz grup, z czytelnymi nazwami w liście
Kocioł z kilkoma panelami Wybór ogrzewania lub ciepłej wody przed otwarciem panelu

Samo dopisanie tych nazw jako pól YAML do oryginalnej karty nie zadziała. Nasza warstwa jest dopasowana do modelu i nie jest gotowym rozszerzeniem z HACS. Przeniesienie jej na inny dom wymaga dopasowania nazw obiektów, pomieszczeń i encji. Podstawowe sterowanie z poprzednich kroków działa niezależnie od tej warstwy.

Prostszy wariant listy halogenów można wykonać od razu: umieść obok modelu zwykłą kartę Encje z grupą salonu i pojedynczymi lampami. Dostaniesz sterowanie bez instalowania dodatkowego kodu. Rozwijana lista osadzona w naszym pasku narzędzi jest osobnym elementem interfejsu.

Lista grup i pojedynczych halogenów w dodatkowym panelu Domu 3D
Fragment własnego panelu halogenów. Widoczne encje miały stan „niedostępne”; to widok kontrolek, nie wynik próby fizycznego sterowania. Zrzut ekranu: instalacja kocel / RadioMesh.

Dodaj listę halogenów obok modelu

Poniższy przykład tworzy zwykłą, stale widoczną listę. Rozwijane menu z naszej instalacji wymaga osobnego kodu; tutaj odtwarzamy funkcję sterowania za pomocą standardowej karty HA.

  1. Otwórz własny dashboard z modelem i przejdź do jego edycji.
  2. Dodaj nową kartę ręczną. Wklej poniższy kod do konfiguracji tej karty, nie do configuration.yaml i nie do wnętrza konfiguracji Floor3D.
  3. Zastąp wszystkie przykładowe identyfikatory własnymi. Usuń wiersz grupy, jeżeli jej jeszcze nie utworzono.
  4. Zapisz kartę. Sprawdź osobno każdą lampę, a następnie całą grupę.
type: entities
title: Halogeny salonu
show_header_toggle: false
entities:
  - entity: light.halogeny_salonu
    name: Wszystkie halogeny
  - entity: light.halogen_1
    name: Halogen przy oknie
  - entity: light.halogen_2
    name: Halogen przy wejściu
  - entity: light.stol
    name: Lampa nad stołem

show_header_toggle: false ukrywa zbiorczy przełącznik nagłówka. Dzięki temu wiersz „Wszystkie halogeny” steruje tylko zdefiniowaną grupą, a lampa nad stołem pozostaje oddzielnie. Więcej opcji zawiera dokumentacja karty Encje.

Sprawdź parę obiekt–encja przed dodaniem następnej lampy

  1. Zapisz konfigurację działającej karty do osobnego pliku tekstowego.
  2. Identyfikator bryły odczytaj na kopii karty z pustym entities: []. Odczytaj też identyfikator jednej encji. Wpisz je w tym samym elemencie listy entities.
  3. Wyjdź z edycji, wykonaj pojedynczy klik myszą na tej bryle i przeczytaj nazwę w otwartym panelu. Jeśli jest niewłaściwa, popraw powiązanie przed próbą sterowania.
  4. Zmień stan lampy z panelu, a potem z niezależnej karty HA. Porównaj rzeczywiste światło i reakcję modelu w obu kierunkach.
  5. Dopiero po udanej próbie dodaj kolejny element. Nie dodawaj drugiego klucza entities: do tej samej karty; kolejne wpisy zaczynają się od - entity: pod istniejącą listą.

Jeżeli nowy eksport modelu zmieni nazwy brył, trzeba ponownie sprawdzić ich identyfikatory. Zachowanie nazwy pliku OBJ nie gwarantuje zachowania nazw obiektów wewnątrz pliku.

9. Sprawdź każde powiązanie i zachowaj wersję działającą

Przygotuj tabelę: pomieszczenie, nazwa obiektu, encja, oczekiwana akcja, wynik próby. Sprawdzaj oddzielnie poprawność otwieranego panelu i reakcję fizycznego urządzenia. To dwa różne testy.

W naszej instalacji zweryfikowaliśmy rozmieszczenie i otwieranie paneli; część halogenów i funkcji jacuzzi była niedostępna. Nie przedstawiamy tego jako potwierdzenia fizycznego działania wszystkich urządzeń.

Objaw Najpierw sprawdź
Nieznany typ karty Zasób Floor3D, typ module i odświeżenie pamięci przeglądarki
Brak modelu path, nazwy OBJ/MTL, komplet plików i komunikaty przeglądarki
Białe powierzchnie MTL i ścieżki do tekstur
Kliknięcie trafia w inne urządzenie Parę object_id i entity
Po nowym eksporcie zniknęło sterowanie Czy eksport nie zmienił identyfikatorów obiektów
Panel działa, sprzęt nie reaguje Integrację urządzenia i jego dostępność poza Floor3D
Pokój jest ucięty Cel i odległość kamery oraz proporcje ekranu
Pełna ściana zasłania urządzenie Ustawienie kamery, uproszczony model lub dodatkową listę urządzeń

Przechowuj razem projekt źródłowy, komplet eksportu i konfigurację karty. Przed kolejną przebudową utwórz nową wersję folderu. Dzięki temu po błędnym eksporcie można wrócić do działającego modelu bez odtwarzania wszystkich powiązań.

Poradnik wideo

Pierwsze kroki, od narysowania pokoju do podpięcia lampy, pokazuje film na kanale RadioMesh.