ESPHome kompiluje minuty? Odkloňte build na výkonnější stroj

Kliknete na Install a čekáte. Minutu, dvě, někdy pět. A když máte deset zařízení a chcete je po vydání nové verze ESPHome projet všechna, je z toho odpoledne.

Většina lidí to bere jako daň za to, že jim Home Assistant běží na malé krabičce - já to tak bral roky. Přitom ESPHome má na tuhle situaci hotovou oficiální odpověď: kompilaci můžete po síti odklonit na počítač, který na to výkon má, a konfigurace zůstane tam, kde je.

Co k tomu potřebujete

Device Builder na obou stranách - aplikaci v Home Assistantovi jako slabou stranu a desktopovou aplikaci ESPHome jako rychlou. Pokud ESPHome neznáte, začněte mým úvodním článkem.

Proč je to vlastně tak pomalé

Tohle stojí za vysvětlení, protože z toho vyplývá, co pomůže a co ne.

Když kliknete na Install, nepřenáší se žádný hotový firmware. Z vašeho YAML se vygeneruje projekt v C++ a ten se přeloží celý dohromady s frameworkem - tedy s ESP-IDF, což je operační systém, síťový stack, ovladače a šifrovací knihovny. Stovky překladových jednotek, ze kterých se na konci linkuje jeden binární obraz. README Device Builderu: „Compiling ESPHome firmware is CPU-heavy, especially for ESP-IDF targets."

A přesně proto nepomůže rychlejší disk ani víc RAM. Překlad C++ je čistý výpočet: procesor přečte pár desítek kilobajtů zdrojáku a pak dlouho počítá. Disk je skoro nezaměstnaný a paměti si kompilátor vezme málo. Rozhoduje výkon jednoho jádra a kolik jader zapojíte paralelně - přesně to, co Raspberry Pi nebo ARM procesor v NASu proti desktopu nemají. Dokumentace ESPHome to pojmenovává na rovinu: „Compiling firmware is the slowest thing the Device Builder does, and on a small host such as a Home Assistant Green or a Raspberry Pi a single build can take several minutes."

Kolik to reálně ušetří

Tohle číslo jsem nikde nenašel, takže přidávám vlastní měření.

Mám ESPHome jako aplikaci v Home Assistantovi na vlastním NASu - na běžný provoz chytré domácnosti stačí, ale výkonem nikoho neurazí. Kompilace jednoho zařízení tam trvá mnoho minut. Tentýž build na Mac Mini M4 Pro je otázka sekund až desítek sekund.

Není to tedy zlepšení o třetinu, je to změna řádu. A mění to i způsob práce: když build trvá minuty, začnete šetřit pokusy. Nejvíc to poznáte na hromadné aktualizaci - deset zařízení krát pět minut je hodina čekání, deset krát dvacet sekund pauza na kávu.

Jak to funguje: kdo co dělá

README popisuje princip jednou přesnou větou: „The firmware bytes still install from the original dashboard; only the build runs elsewhere." Jinam tedy neputuje vaše konfigurace, ani zařízení, ani hlavní dashboard. Jinam jde jen ta drahá část.

Takhle to vypadá na tom rychlém stroji, který kompiluje:

Vlevo je panel Paired dashboards s jediným záznamem Home Assistant App, u něj „Paired 44 days ago" a zelený odznak CONNECTED - spárování drží samo a přežívá restarty obou stran. Vpravo je Build queue se třemi dokončenými kompilacemi a u každé řádek from Home Assistant App.

A ten řádek je celý důkaz. Zadání vzniklo v Home Assistantovi, tam jsem klikl na Install, tam žije YAML - ale kompilace proběhla tady, na Macu. Firmware se pak nahrál zpátky z Home Assistanta, jako by se nic nedělo.

Dvě role, obě v Nastavení příslušného dashboardu:

Role	Kdo ji má	Co dělá
Build server	rychlý stroj	Přijímá párování, kompiluje a vrací hotové obrazy. Desktopová aplikace a samostatné instalace ji mají zapnutou z výroby
Send builds	slabý stroj (Home Assistant)	Kompilaci deleguje. Aplikace v Home Assistantovi je záměrně jen v tomhle režimu, protože podle README „it doesn't accept inbound build jobs without opt-in, which is the sensible default for a typically-shared host"

Jeden dashboard může hrát obě role zároveň, nebo se dá zúžit tak, aby sloužil výhradně jako build stroj - viz režim bez rozhraní.

Funguje to i pro sériový flash

Vzdálený build pokrývá každý typ instalace - OTA i USB. U té sériové podle README „the receiver compiles the full bootloader / partitions / firmware image set and ships it back; the USB flash itself still runs on the sending host, since that's where the device is plugged in." Kompilace tedy proběhne na rychlém stroji a pískání do sériové linky tam, kde máte zařízení v USB - postup mám tady.

Párování krok za krokem

Čtyři kroky a jedna past, na kterou se dá spolehlivě naletět, takže tu dám dopředu:

Okno Pairing requests musí být otevřené předem

Přijímací strana odmítne každý požadavek, který dorazí ve chvíli, kdy obrazovku Pairing requests nemá otevřenou. Není to potvrzovací krok na konci - je to předpoklad. V dokumentaci stojí jako krok 2 uprostřed seznamu, a proto ho člověk čte jako „tady se to jen dopotvrdí". README na to naráží větou „Step 2 is the prerequisite, not the wrap-up."

Otevřete ho tedy dřív, než na druhé straně kliknete na Pair, a nechte ho otevřené až do konce.

Otevřené okno poznáte podle zeleného odznaku Open a odpočtu, kolik času vám zbývá:

Okno se po vypršení odpočtu samo zavře. Když párování nestihnete - třeba proto, že běháte mezi dvěma počítači v jiných místnostech - odpočet prodloužíte tlačítkem Extend, nemusíte začínat znovu. Panel sám popisuje, co se od vás čeká: „Senders that have asked to pair with this dashboard. Open Review to compare the fingerprint shown there with the one on the sending dashboard, then accept or reject."

Nastavení Device Builderu má v levém sloupci mimo jiné položky Build server, Pairing requests a Send builds - podle role stroje se nabídka mírně liší. První tři kroky se dějí v nich:

1. Na rychlém stroji jděte do Nastavení → Build server a zapněte přepínač Enable remote build
2. Tamtéž přepněte na Nastavení → Pairing requests a nechte tu obrazovku otevřenou (na hlavní obrazovce se k ní dostanete i tlačítkem Open pairing window v panelu Paired dashboards)
3. V Home Assistantovi jděte na Nastavení → Send builds. Příjemce na stejné podsíti se v seznamu Known dashboards objeví sám přes mDNS - najděte ho a dejte párovat. Když tam není, protože je za jinou podsítí, VLANem nebo v kontejnerové síti, použijte tlačítko Pair with a build server a zadejte jeho hostname a port ručně
4. Zpátky na rychlém stroji se v otevřené obrazovce objeví požadavek. Dejte Review, porovnejte odtisk s tím, který ukazuje odesílající strana - musí být shodné - a potvrďte Accept

Ten odtisk je hlavní bezpečnostní prvek celého párování. Příjemce ho ukazuje ve svém Nastavení → Build server v sekci THIS DASHBOARD'S BUILD SERVER IDENTITY jako Identity fingerprint (SHA-256), a to v podobě řady emoji - přesně proto, aby se dal snadno přečíst nahlas druhému člověku. Kdo si radši porovná čísla, rozbalí Show hex bytes. Aplikace u toho neztrácí čas vysvětlováním, proč na tom záleží: „Read it back to the operator pairing from the other side; it's the only way to detect a man-in-the-middle on first connection."

Příjemce si po prvním buildu drží cache, aby druhé nahrání téhož zařízení nemuselo začínat od nuly - a právě proto je opakovaný build ještě rychlejší než ten první. Jak dlouho se cache drží, řídí volba Cache retention ve stejném nastavení; z výroby je na 24 hodinách nečinnosti, po kterých se místo na disku uvolní.

Vedle odtisku najdete i Dashboard ID, Pairing address (hostname a port 6055) a tlačítko Rotate identity, kterým odtisk zneplatníte - to se hodí, když si nejste jistý, komu jste ho kdy ukázal. Komunikace je po spárování šifrovaná protokolem Noise.

Komu to zapnete, ten u vás může spustit cokoli

Tohle si přečtěte, než si roli build serveru zapnete kdekoli jinde než doma na svém stroji. Přepínač Enable remote build to říká na rovinu: „Lets other dashboards on your network compile their YAML here. A paired peer can run arbitrary code on this machine; only pair with dashboards you'd give ssh access to."

Kompilace ESPHome totiž není jen překlad - konfigurace může sahat na externí komponenty a build skripty. Spárovaný odesílatel má tedy na build stroji faktickou moc spustit libovolný kód. Párujte jen dashboardy, kterým byste dal přístup přes SSH, a roli build serveru nezapínejte na stroji, který sdílíte s někým dalším. Právě proto se aplikace v Home Assistantovi z výroby chová jen jako odesílatel a příjem si musíte zapnout ručně.

Od té chvíle se Install jakéhokoli zařízení automaticky přesměruje na spárovaný stroj, jakmile je online, a v dialogu uvidíte podřádek Building on {jméno}. Když je příjemce zaneprázdněný, Device Builder podle README „queues the install behind the in-flight work rather than silently building locally" - počká tedy, místo aby vás potichu hodil na lokální kompilaci. Jednorázově pomůže odkaz Build locally instead, vypnout se to dá v Nastavení → Send builds → Auto-route installs to remote build.

Režim bez rozhraní: --remote-build-only

Když má stroj sloužit jen jako procesor k půjčení, nemusí vůbec nabízet dashboard:

esphome-device-builder --remote-build-only /var/lib/esphome-builder

Ten adresář si nechte - drží identitu serveru a stav buildů, takže po smazání přijdete i o spárování. Při prvním spuštění vypíše do konzole odtisk a jednorázový párovací klíč.

Párování je pak jiné: v Home Assistantovi jdete na Nastavení → Send builds → Pair with a build server, zadáte hostname a peer-link port (výchozí 6055) a pokračujete. Dialog sám pozná, že jde o headless server, a nabídne pole na párovací klíč - opíšete ho z konzole a odešlete. Když se do vypršení okna nespárujete, server spusťte znovu. Parametrem --allow-pairing-source <IP> jde navíc omezit, ze které adresy se smí párovat.

Shoda verzí: co se stane při rozdílu

Musí mít oba stroje stejnou verzi ESPHome? Nemusí, a je to vyřešené elegantněji, než by člověk čekal. U spárovaného build serveru vám rozhraní samo napíše, jak to je - u mého Macu tam stojí „Build server runs ESPHome 2026.8.0; your builds use 2026.8.2 automatically". Rozhoduje tedy verze na vaší straně, ne ta, kterou má nainstalovaný build server.

Chování se dá nastavit v Nastavení → Send builds volbou ESPHome version match. Z výroby je na hodnotě Allow any release-line mismatch (default) s vysvětlením „Route to any paired build server regardless of its ESPHome version." - tedy posílat build kamkoli bez ohledu na verzi. V nabídce jsou i striktnější volby; dokumentace projektu je popisuje jako čtyři politiky any, release, exact a exact_required, kde ta poslední radši build odmítne, než aby spadl zpátky na lokální kompilaci. To se hodí, když vyloženě nechcete, aby se kompilace potichu vrátila na slabý server.

Když se verze liší, ESPHome při dalším překladu vypíše Core config or version changed, cleaning build files... a build adresář si sám vyčistí. Ztratíte tedy inkrementální build a zaplatíte plnou kompilací - a to je všechno. Balíčky toolchainu se nemažou, takže se znovu nestahují.

Kompilovat můžou obě strany současně

Ve stejném nastavení je i přepínač Include this machine in the build pool, z výroby vypnutý. Když ho zapnete, začne dashboard kompilovat i sám - ale jen ve chvíli, kdy jsou všechny spárované build servery zaneprázdněné. Jeden build tedy pořád dostane přednostně nečinný vzdálený stroj, takže se vám tím odkládání kompilace nerozbije. Smysl to dává, když aktualizujete hodně zařízení naráz.

Kde verze naopak vadí, a je to OTA

Nahrávání je jiná disciplína než kompilace: instance ESPHome starší než 2025.10, která se autentizuje heslem, nedostane firmware do zařízení na 2026.1 a novějším, bez ohledu na to, kde se kompilovalo. Rozebírám to v článku o ESPHome.

Kdy to nefunguje

Vzdálený build je záměrně funkce pro lokální síť. Když nechodí, je to skoro vždycky jedna z těchto věcí.

Přes VPN to není navržené. README je nezvykle přímý: běh peer-linku přes VPN, Tailscale nebo jakoukoli pomalou linku je „best effort: it may work, but the timing assumptions favor LAN-class throughput, slow links aren't a design target, and issues that only reproduce over a slow link won't be pursued." Chcete-li kompilovat na stroji jinde ve světě, sáhněte radši po volbě Download firmware binary - hotová binárka žádné časové předpoklady nemá. Popisuju ji v článku o flashování.

Stroje se navzájem nevidí. Objevování jede přes mDNS, takže první podezřelý je jiná podsíť bez reflektoru, kontejner bez host networkingu a firewall blokující 5353/udp. Pozor na dvě specifika:

• Peer-link port se do mDNS záznamu dostane teprve se zapnutou rolí Build server. Dokud ten přepínač nezapnete, uvidíte dashboard v Known dashboards, ale spárovat se s ním nepůjde
• Aplikace v Home Assistantovi se na síti neinzeruje vůbec, takže dvě instance v Home Assistantovi se nenajdou. Použijte tlačítko Pair with a build server v sekci Pair with another dashboard pod seznamem

Než začnete hledat chybu v rozhraní, spusťte na odesílající straně esphome-device-builder-discover - vypíše, co na síti vidí, včetně peer-link portu a odtisku. Když ho nevidí ani CLI, neprochází mDNS.

Mezi stroji stojí reverzní proxy. Peer-link je WebSocket na cestě /remote-build/peer-link po TCP portu 6055. Proxy nebo firewall na téhle cestě musí povolit WebSocket upgrade - jinak se spojení nesestaví, i když se stroje jinak vidí.

A jedna věc, která se sama nabízí a přesto je špatná: port 6055 do internetu neprotahujte. Když chcete kompilovat na stroji v práci, stáhněte si radši hotovou image.

Zhodnocení

Vzdálený build je z celého ESPHome ta funkce, o které bych si přál vědět nejdřív. Roky jsem čekal na kompilaci s tím, že se nedá nic dělat - a přitom to bylo na dvě zapnutá tlačítka a jedno porovnání emoji.

Nejdůležitější jsou na tom dvě věci: rozdíl je řádový, ne procentuální, a konfigurace zůstává jedna - rychlý stroj svou kopii YAML nemá, takže není co rozejít. Jestli vám Home Assistant běží na Raspberry Pi, na Greenu nebo na NASu a máte po ruce jakýkoli desktop, je to nejlepší poměr práce k ušetřenému času, jaký v ESPHome najdete.

Související články

• ESPHome - Chytré zařízení z ESP32 za pár minut
• Nahrání firmware ESPHome přes USB: první instalace i záchrana zamčeného zařízení
• Raspberry Pi 5 / 4 / 3
• Home Assistant Green

Zdroje

• ESPHome Device Builder: Send builds to another dashboard - role, párování, headless režim, port a shoda verzí (anglicky)
• ESPHome: Installing ESPHome - sekce Building on a Faster Machine (anglicky)
• ESPHome Desktop - vydání - balíčky pro macOS, Windows a Linux (anglicky)