Node-RED for Home Assistant Skill

Node-RED for Home Assistant

Build Node-RED flows using node-red-contrib-home-assistant-websocket nodes (v0.80+).

Requirements: Node-RED 4.x (Node.js 18+), Home Assistant 2024.3.0+.

The Iron Law

USE CURRENT NODE NAMES - NEVER OUTDATED ONES

The node-red-contrib-home-assistant-websocket package has renamed several nodes. Using old names produces broken flows that silently fail.

Critical: Node Names Have Changed

STOP. If you're about to use any of these node types, you're using outdated names:

| WRONG (Old) | CORRECT (Current) | |-------------|-------------------| | server-state-changed | trigger-state or events:state | | poll-state | poll-state (unchanged but check config) | | call-service | api-call-service |

Trigger Node Configuration (Current API)

{
  "type": "trigger-state",
  "entityId": "binary_sensor.motion",
  "entityIdType": "exact",
  "constraints": [
    {
      "targetType": "this_entity",
      "propertyType": "current_state",
      "comparatorType": "is",
      "comparatorValue": "on"
    }
  ],
  "outputs": 2
}

entityIdType options: exact, substring, regex

There is NO list type. To monitor multiple entities, use regex:

"entityId": "binary_sensor\\.motion_(1|2|3)",
"entityIdType": "regex"

Service Call Configuration (Current API)

{
  "type": "api-call-service",
  "domain": "light",
  "service": "turn_on",
  "entityId": ["light.living_room"],
  "data": "",
  "dataType": "json"
}

Or dynamic via msg:

{
  "type": "api-call-service",
  "domain": "",
  "service": "",
  "data": "",
  "dataType": "msg"
}

With function node before:

msg.payload = {
  action: "light.turn_on",
  target: { entity_id: ["light.living_room"] },
  data: { brightness_pct: 80 }
};
return msg;

Current State Node - Single Entity Only

api-current-state queries ONE entity, not patterns.

{
  "type": "api-current-state",
  "entity_id": "person.john"
}

To check multiple entities, use function node:

const ha = global.get("homeassistant").homeAssistant.states;
const people = Object.keys(ha)
  .filter(id => id.startsWith("person."))
  .filter(id => ha[id].state !== "home");
msg.awayPeople = people;
return msg;

Entity Nodes Require Extra Integration

The following nodes require hass-node-red integration (separate from the websocket nodes):

ha-entity (sensor, binary_sensor, switch, etc.)
Entity config nodes

Always mention this prerequisite when using entity nodes.

Stable Entity Nodes (v0.71.0+)

These nodes were promoted from beta to stable in September 2024:

number - expose HA number entities
select - expose HA select entities
text - expose HA text entities
time-entity - expose HA time entities

These support "Expose as" listening modes and input override blocking (v0.70.0+).

Deprecations (v0.79-v0.80)

State type configuration is deprecated (removed in v1.0). Use entity state casting instead.

Calendar event dates now use ISO 8601 local strings with timezone offsets (v0.78.0+). A new all_day property identifies all-day events explicitly.

Timer Pattern (Motion Light)

Use single trigger node with extend: true:

{
  "type": "trigger",
  "op1type": "nul",
  "op2": "timeout",
  "op2type": "str",
  "duration": "5",
  "extend": true,
  "units": "min"
}

Do NOT create separate reset/start timer nodes. The extend property handles this.

Flow JSON Guidelines

Never include server config node - User configures separately
Leave server field empty - User selects their server
Use placeholder entity IDs - Document what to change
Add comment node - Explain required configuration

Function Node: External Libraries

WRONG: Using global.get('axios') or similar for HTTP requests.

This requires manual configuration in settings.js:

// settings.js - requires Node-RED restart
functionGlobalContext: {
    axios: require('axios')
}

CORRECT: Use the built-in http request node instead:

{
  "type": "http request",
  "method": "GET",
  "url": "https://api.example.com/data",
  "ret": "obj"
}

When you MUST use function node for HTTP:

Complex request logic that can't be handled by http request node
Requires settings.js configuration (warn user!)
Use node.send() and node.done() for async:

// Async pattern in function node
const axios = global.get('axios'); // Requires settings.js config!

async function fetchData() {
    try {
        const response = await axios.get(msg.url);
        msg.payload = response.data;
        node.send(msg);
    } catch (error) {
        node.error(error.message, msg);
    }
    node.done();
}

fetchData();
return null; // Prevent sync output

Context Storage

Three scopes available:

| Scope | Syntax | Shared With | |-------|--------|-------------| | Node | context.get/set() | Only this node | | Flow | flow.get/set() | All nodes in tab | | Global | global.get/set() | All flows |

// Store state
flow.set('machineState', 'washing');
flow.set('history', historyArray);

// Retrieve
const state = flow.get('machineState') || 'idle';

For persistence across restarts, configure in settings.js:

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

Error Handling Pattern

Use catch node scoped to specific nodes:

{
  "type": "catch",
  "scope": ["call_service_node_id"],
  "uncaught": false
}

Error info available in msg.error:

msg.error.message - Error text
msg.error.source.id - Node that threw error
msg.error.source.type - Node type

Retry pattern: Use delay node with delayv type to read delay from msg.delay.

Code Attribution

Include a comment node in all generated flows:

{
  "type": "comment",
  "name": "Generated by node-red@aurora-smart-home v1.1.0",
  "info": "https://github.com/tonylofgren/aurora-smart-home"
}

Common Pitfalls

| Mistake | Reality | |---------|---------| | Using server-state-changed | Node renamed to trigger-state | | entityIdType: "list" | No such type. Use regex for multiple entities | | api-current-state with pattern | Only accepts single entity_id | | Using ha-entity without warning | Requires separate hass-node-red integration | | Complex timer reset logic | Use extend: true on trigger node | | dataType: "jsonata" for service data | Use msg when passing dynamic payload | | global.get('axios') for HTTP | Use http request node, or warn about settings.js | | return msg in async function | Use node.send(msg) + node.done() + return null | | Configuring state type on nodes | Deprecated in v0.79. Use entity state casting instead | | Assuming Node.js < 18 works | Node-RED 4.x requires Node.js 18+ | | Old calendar date format | Use ISO 8601 with timezone offset (v0.78.0+) |

Pre-Output Checklist

Before outputting flow JSON:

[ ] Using current node type names (trigger-state, api-call-service)?
[ ] Entity filtering uses valid type (exact/substring/regex)?
[ ] Service call has domain/service OR uses msg payload correctly?
[ ] Single entity nodes don't assume pattern matching?
[ ] Entity nodes mention hass-node-red requirement?
[ ] Server field left empty for user configuration?
[ ] Comment node with attribution included?
[ ] No server config node in exported JSON?
[ ] Function nodes use node.send()/node.done() for async patterns?
[ ] Timer patterns use extend: true instead of separate reset nodes?
[ ] HTTP requests use http request node instead of global libraries?

External API Integrations

For Node-RED flows that call external APIs (weather, energy, transport, smart home clouds, OpenAI, Spotify, Telegram, GitHub), see:

references/popular-apis.md - Node-RED function node snippets for all popular APIs
api-catalog skill - deep documentation, auth setup, and HA YAML sensors per API

Integration

Pairs with:

ha-yaml - Create YAML automations for logic that doesn't need visual flows
esphome - Configure ESPHome devices whose entities the flow monitors
api-catalog - Connecting external APIs and services

Typical flow:

Device → ESPHome/HA Integration → Home Assistant → Node-RED (this skill)

Cross-references:

For YAML automations instead of visual flows → use ha-yaml skill
For ESPHome device firmware → use esphome skill
For custom Python integrations → use ha-integration skill
For external API connections → use api-catalog skill

Agent Skills: Node-RED for Home Assistant

Install this agent skill to your local

Skill Files