Aktualizováno: 2026-10-05 · Platí pro: node-red 5.0.x (Node.js >=22.9); node-red-contrib-home-assistant-websocket 0.81; home-assistant >=2024.3

Node-RED

Co to je: Open-source nástroj pro „low-code“ programování aplikací řízených událostmi. Logiku skládáš v prohlížeči z nodů propojených dráty a mezi nimi tečou zprávy (msg). dok. Node-RED Ve smarthome slouží hlavně jako druhý automatizační engine vedle Home Assistant: s HA mluví přes WebSocket API a umí i MQTT, HTTP a stovky dalších integrací z palety. dok. HA nodů Aktuální je Node-RED 5.0.7 (09/2026) a vyžaduje Node.js 22.9+. dok. Node-RED

Kdy Node-RED a kdy HA automatizace

Syntéza (nezdrojováno, praktická zkušenost komunity):

Situace	Spíš HA automatizace	Spíš Node-RED
Jednoduché „když X, udělej Y“	✓
Větvení, čekání, časovače, víc podmínek		✓, logika je vidět v grafu
Práce s daty (JSON, HTTP API, transformace)		✓
Integrace mimo HA (MQTT, HTTP endpointy, DB)		✓
Má fungovat i bez dalšího procesu	✓

Node-RED je další proces, který je potřeba aktualizovat, zálohovat a zabezpečit (viz níže).

Základní pojmy

Anatomie flow v Node-RED
Flow, nody, zpráva msg a context na příkladu „světlo podle slunce“. Vlastní schéma (Syntéza) podle dok. Node-RED a dok. HA nodů.

Node: stavební kámen. Spouští ho zpráva od předchozího nodu nebo externí událost (HTTP, časovač…). Má nejvýš 1 vstup a libovolný počet výstupů. dok. Node-RED
Flow: záložka v editoru. Neformálně i jedna sada propojených nodů. dok. Node-RED
Message (msg): obyčejný JavaScript objekt. Hlavní data jsou podle konvence v msg.payload, Node-RED přidává msg._msgid. dok. Node-RED
Config node: sdílená konfigurace, např. připojení k HA serveru nebo MQTT brokeru. V workspace není vidět, je v sidebaru Configuration nodes. dok. Node-RED
Context: stav mimo zprávy, scope node, flow nebo global. dok. Node-RED
Subflow: skupina nodů zabalená do jednoho opakovaně použitelného nodu. dok. Node-RED
Deploy: změny v editoru se projeví až po nasazení.

Editor

Editor Node-RED 5: vlevo Explorer (flows, subflows, config nody) a Palette s nody, uprostřed workspace, vpravo Information a Debug messages, nahoře Deploy. Zdroj: dok. Node-RED (screenshot z dokumentace, 2026-06).

Nové nody se instalují přes Palette Manager (menu → Manage palette) nebo npm install v adresáři Node-RED. dok. Node-RED dok. HA nodů
Debug node a sidebar ukážou celou strukturu zprávy. Tlačítkem lze zkopírovat cestu k vlastnosti (např. payload.Phone[2].type) a vložit ji do Change nodu. dok. Node-RED

Napojení na Home Assistant

Node-RED a Home Assistant
Jak spolu Node-RED a HA mluví. Vlastní schéma (Syntéza) podle dok. HA nodů.

Nainstaluj nody node-red-contrib-home-assistant-websocket (Node.js 20+, Node-RED 3.1.1+, HA 2024.3+). Komunitní HA add-on Node-RED je má předinstalované. dok. HA nodů V HA 2026 se add-ony jmenují Apps (Settings > Apps). dok. ZBT-2
Vytvoř token: v HA profilu → Create Token (long-lived access token). Uživatel musí být ve skupině administrátorů. Doporučeno mít pro Node-RED samostatného HA uživatele, aby bylo vidět, co mění. dok. HA nodů
Server config node: Base URL (např. http://<ha>:8123) a token. U add-onu stačí zaškrtnout „I use the Home Assistant Add-on“. dok. HA nodů
Ověř připojení nodem Events: all (zelený status „connected“), pak ho kvůli výkonu smaž a používej konkrétní nody. dok. HA nodů

Nejpoužívanější nody dok. HA nodů:

Events: state / Trigger: state: spustí flow při změně stavu entity. Entita jde zadat i jako regex nebo podřetězec, „If State“ rozdělí výstup na true/false, „For“ určí, jak dlouho musí stav trvat.
Current State: zjistí aktuální stav entity uprostřed flow.
Action: zavolá akci v HA (dříve „call service“), např. light.turn_on.
Get History, Fire Event, Wait Until, Webhook, API: pokročilé věci.
Entity nody (Sensor, Switch, Button…) vytvoří entitu v HA. Potřebují v HA custom integraci hass-node-red (HACS). Vyplň friendly name před prvním deployem, jinak vznikne sensor.nodered_<id>.

Příklad první automatizace dok. HA nodů: Events: state na sun.sun s If State above_horizon. Výstup true → Action light.turn_off, výstup false → Action light.turn_on. Odpovídá schématu „Anatomie flow“ výše.

HomeKit: node-red-contrib-homekit-bridged (NRCHKB)

Balíček, kterým Node-RED vystavuje zařízení do Apple Home (HomeKit) a ovládá je i přes Siri.

Nody v Node-RED napodobují HomeKit zařízení. Zpráva do nodu nastaví stav v aplikaci Home, příkaz z Home nebo Siri přijde do flow jako zpráva. NRCHKB
Nody: Bridge (jeden most s víc zařízeními), Standalone (samostatné příslušenství), Service / Service 2 (konkrétní služba, např. světlo nebo senzor), Status. NRCHKB
Syntéza: HomeKit hledá zařízení přes mDNS v lokální síti. Na Umbrelu proto funguje aplikace Node-RED s network_mode: host. zdroje Umbrel

Kompatibilita s Node-RED 5 / Node.js 24

Image Node-RED 5.0.7 (i ten na Umbrelu) běží na Node.js 24. Stabilní NRCHKB 1.7.3 (01/2025) podporu Node.js 24 oficiálně nemá, issue je otevřené. Verze 2.0.0, určená pro Node-RED 5, je zatím jen release candidate (2.0.0-dev.12) a má otevřenou chybu se Service nody v subflows. NRCHKB
Syntéza: dokud HomeKit funguje, NRCHKB neaktualizuj naslepo. Před aktualizací Node-RED nebo NRCHKB zálohuj /data a sleduj vydání stabilní 2.0.0. Pozor na její breaking changes (konec custom mDNS, CameraControl).

Práce se zprávami

Change node: Set, Change (hledat a nahradit), Delete, Move. Umí číst a zapisovat i flow a global context a počítat přes JSONata. Na většinu úprav stačí bez kódu. dok. Node-RED
Function node: JavaScript nad msg pro složitější logiku. dok. Node-RED

// víc výstupů: vrať pole (null = na daný výstup nic)
if (msg.topic === "banana") {
    return [null, msg];
}
return [msg, null];

Příklad z dok. Node-RED.

return null flow ukončí. Funkce musí vracet objekt zprávy, ne číslo nebo řetězec. dok. Node-RED
Nový objekt místo msg zahodí původní vlastnosti. Např. HTTP In/Response potřebuje zachovat msg.req a msg.res. dok. Node-RED
Asynchronní kód posílá zprávy přes node.send(). dok. Node-RED
Logování node.log(), node.warn(), node.error() (warn a error se ukáží i v Debug). node.error("…", msg) spustí Catch node na stejné záložce. dok. Node-RED

Context a stav

Výchozí context je jen v paměti a po restartu zmizí. Pro trvalé hodnoty nastav v settings.js dok. Node-RED:

contextStorage: {
    default: { module: "localfilesystem" }
}

Data jsou pak v ~/.node-red/context/ a zapisují se každých 30 s. Jde kombinovat paměťové i souborové úložiště. dok. Node-RED
Stav potřebný jen v jedné záložce dej do flow, ne global. Alternativou je držet stav mimo Node-RED (retained MQTT, databáze). dok. Node-RED

Instalace

HA app (add-on): nejjednodušší cesta pro HA OS, HA nody jsou předinstalované. dok. HA nodů
Umbrel: aplikace Node-RED (node-red-standalone, port 1881). Pozor na záměnu s „Node-RED (Bitcoin)“. zdroje Umbrel
Docker dok. Node-RED:

docker run -it -p 1880:1880 -v node_red_data:/data --name mynodered nodered/node-red

Všechna data (flows, settings.js, doinstalované nody) jsou v /data, takže vždy mapuj volume.
Proces v kontejneru běží jako uid 1000. U bind mountu musí adresář na hostu patřit 1000:1000.
Image je na Alpine. Pro nody s nativními moduly existuje od 3.1.0 Debian varianta.
Syntéza: v praxi to patří do docker-compose.yml s restart: unless-stopped a pevným tagem verze místo latest.
npm: sudo npm install -g node-red. Node-RED 5 potřebuje Node.js 22.9+, doporučený je 24. dok. Node-RED

Zabezpečení

Editor je ve výchozím stavu bez přihlášení. Kdo se dostane na port 1880, může měnit a nasazovat flows. dok. Node-RED

Přihlášení: v settings.js odkomentuj adminAuth a zadej uživatele s bcrypt hashem hesla. Hash vytvoří node-red admin hash-pw. Oprávnění jsou * (vše) nebo read. Jde i OAuth/OpenID. dok. Node-RED

adminAuth: {
    type: "credentials",
    users: [{ username: "admin", password: "<bcrypt-hash>", permissions: "*" }]
}

HTTPS: volba https s klíčem a certifikátem v PEM. Od Node-RED 5 jde certifikáty načíst i z proměnných prostředí. dok. Node-RED
HTTP In nody a dashboard chrání httpNodeAuth. dok. Node-RED
credentialSecret: credentials ve flows jsou šifrované. Bez vlastního klíče se použije systémový a při jeho ztrátě jsou credentials nenávratně pryč. dok. Node-RED
Syntéza: port 1880 nevystavuj do internetu. Vzdálený přístup řeš přes VPN nebo reverse proxy s autentizací. HA token v Node-RED je admin token, chraň ho stejně jako HA.

Zálohy a verzování

Zálohuj celý /data (Docker) nebo ~/.node-red. Za běhu jde docker cp mynodered:/data <cíl>. dok. Node-RED
Projects: flows jako Git repozitář s historií. Zapíná se v settings.js (editorTheme.projects.enabled: true). dok. Node-RED
Syntéza: bez zálohovaného credentialSecret po obnově nefungují uložené credentials (HA token, MQTT heslo).

Tipy pro strukturu flows

Jedna záložka = jeden logický celek. U domácnosti podle místností nebo funkcí (světla, topení). dok. Node-RED
Opakované části řeš přes Link nody (skok mezi záložkami, jen na začátku nebo konci flow) nebo Subflows (vlastní node, každá instance má vlastní context). Subflow properties fungují jako proměnné prostředí, např. ${MY_TOPIC}. dok. Node-RED
Nasazuj jen změny: Deploy → Modified Flows nebo Modified Nodes, ať se nerestartují všechny flows. dok. HA nodů

Gotchas

Upgrade na 5.x: nejdřív ověř verzi Node.js (22.9+). Řada 4.1.x dál dostává opravy, takže upgrade nespěchá. dok. Node-RED
Node-RED 5 výrazně změnil editor. Starší návody a screenshoty vypadají jinak. dok. Node-RED
Context v paměti se po restartu nebo aktualizaci ztratí. dok. Node-RED
Volba „State Type“ v Events: state je deprecated a zmizí v balíčku 1.0.0. Používej output properties. dok. HA nodů
Když se v autocomplete neobjevují nové entity, vypni „Cache Autocomplete Results“ v server config a restartuj Node-RED. dok. HA nodů

Integrace

Home Assistant přes WebSocket API a custom integraci hass-node-red
MQTT: MQTT in/out nody s config nodem brokeru
Zigbee2MQTT: Zigbee zařízení přes MQTT
PostgreSQL: dlouhodobé ukládání dat

Souvislosti

Home Assistant, MQTT, Zigbee2MQTT

Zdroje

dok. Node-RED: oficiální dokumentace Node-RED a release notes (verze 5.0.7).
dok. HA nodů: dokumentace HA nodů (v0.81.0).
dok. ZBT-2: přejmenování HA add-onů na Apps.