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.
- Zrób kopię zapasową HA (Ustawienia → System → Kopie zapasowe) i zachowaj konfigurację panelu (dashboardu).
- W Ustawienia → Urządzenia oraz usługi → Rejestr encji znajdź urządzenia, które mają trafić na plan.
- Sprawdź ich działanie na zwykłych kartach. Zapisz identyfikatory, np.
light.lampa_salon,cover.brama_garazowaiclimate.ogrzewanie. - 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.
- 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.
- 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. - 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.
- 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.
- 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ą.
- 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.
- W Sweet Home 3D wybierz 3D View → Export to OBJ format. Nazwa może być przetłumaczona w polskiej wersji programu.
- Zapisz wynik do osobnego folderu. Powstaną OBJ z geometrią, MTL z materiałami oraz ewentualne pliki tekstur.
- 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 środkudom3d. 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 katalogwwwpowstał po raz pierwszy, uruchom HA ponownie. - Zachowaj nazwy i wzajemne ścieżki plików. Dla przykładowego eksportu przyjmujemy
dom.objidom.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
- 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.
- 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.
- Odśwież przeglądarkę przez
Ctrl+F5. - 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ę.
- Wróć do edycji karty. Pozostaw
entities: []ieditModeNotifications: 'yes'. Klikaj model w podglądzie edytowanej karty. - Kliknij dwukrotnie obiekt lampy. Zapisz pokazany identyfikator modelu. Nie zakładaj, że jest taki sam jak etykieta mebla w programie do projektowania.
- 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.
- Zapisz kartę i wyjdź z edycji.
- Wykonaj pojedynczy krótki klik myszą na lampie: przy
click: 'yes'iaction: more-infopowinien otworzyć się standardowy panel dokładnie tej encji. Sprawdź nazwę przed użyciem sterowania. - 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ń
- W trybie edycji ustaw model w wygodnym położeniu.
- Dwuklik w pustym miejscu sceny pozwala odczytać ustawienie kamery zgodnie z mechanizmem karty. Skopiuj pokazane
camera_position,camera_rotateicamera_targetdo głównego poziomu konfiguracji karty, obokpathientities, a nie do wpisu lampy. Zachowaj wcięcia i wartości z własnego widoku. - Do przybliżenia pokoju dodaj na głównym poziomie karty poniższy blok. Zastąp
ID_PODLOGI_SALONUodczytanym identyfikatorem podłogi.distancepodaje 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
- 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
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.
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.
- Otwórz własny dashboard z modelem i przejdź do jego edycji.
- Dodaj nową kartę ręczną. Wklej poniższy kod do konfiguracji tej karty, nie do
configuration.yamli nie do wnętrza konfiguracji Floor3D. - Zastąp wszystkie przykładowe identyfikatory własnymi. Usuń wiersz grupy, jeżeli jej jeszcze nie utworzono.
- 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
- Zapisz konfigurację działającej karty do osobnego pliku tekstowego.
- Identyfikator bryły odczytaj na kopii karty z pustym
entities: []. Odczytaj też identyfikator jednej encji. Wpisz je w tym samym elemencie listyentities. - 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.
- Zmień stan lampy z panelu, a potem z niezależnej karty HA. Porównaj rzeczywiste światło i reakcję modelu w obu kierunkach.
- 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.
