Node-RED Home Assistant Websocket

https://github.com/zachowj/node-red-contrib-home-assistant-websocket
Admin
Provides various Node-RED nodes to assist in setting up automation by communicating with Home...
Tokens:57,385
Snippets:661
Trust Score:7.1
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install node-red-contrib-home-assistant-websocket via npm

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/guide/index.md

Install the node package from the command line. Navigate to the Node-RED user directory and run npm install, then restart Node-RED to load the new nodes.

```bash
$ cd ~/.node-red
$ npm install node-red-contrib-home-assistant-websocket
# Restart Node-RED
```

--------------------------------

### Enable pnpm (manual setup)

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/guide/documentation.md

Enable pnpm using corepack before installing dependencies in the manual environment.

```sh
corepack enable && corepack enable npm
```

--------------------------------

### Run setup script

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/guide/development.md

Run the provided setup script to automate environment configuration.

```bash
./scripts/setup.sh
```

--------------------------------

### Manual environment setup

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/guide/development.md

Manually create a .node-red directory and link pnpm. This is an alternative to running the setup script.

```bash
mkdir .node-red
corepack enable && corepack enable pnpm
pnpm link --dir .node-red
```

--------------------------------

### Install via npm

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/README.md

Install the node using npm from the Node-RED user directory, then restart Node-RED.

```shell
$ cd ~/.node-red
$ npm install node-red-contrib-home-assistant-websocket
# then restart node-red
```

--------------------------------

### Install via Node-RED Manage Palette

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/README.md

Install the node via the Node-RED Manage Palette by entering the package name.

```text
node-red-contrib-home-assistant-websocket
```

--------------------------------

### JSONata examples for Action node Data object and service call processing

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/cookbook/jsonata/action.md

These examples demonstrate using JSONata to set the Data object in an Action node and to process service call return data. The first example shows how to define the Data object directly in the Action node UI. The second example shows passing Service Call settings via a preceding Change node. The third example shows generating the Data object from a flow trigger node. The fourth example processes the return data from a service call.

```json
@[code](@examples/cookbook/jsonata-examples/service-call.json)
```

--------------------------------

### Start Node-RED in development mode

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/guide/development.md

Start Node-RED in development mode. After running, Node-RED will be available on ports 1880 and 3000.

```bash
pnpm dev
```

--------------------------------

### Sample array output of state objects

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/node/get-entities.md

Example JSON output when the Get Entities node output type is set to Array. Shows the structure of each state object, including entity_id, state, attributes, timestamps, context, and timeSinceChangedMs.

```json
[
  {
    "entity_id": "light.kitchen",
    "state": "on",
    "attributes": {
      "brightness": 243,
      "friendly_name": "Kitchen Light",
      "supported_features": 33,
      "icon": "mdi:light-switch"
    },
    "last_changed": "2019-12-29T05:38:53.016984+00:00",
    "last_updated": "2019-12-29T05:38:53.016984+00:00",
    "context": {
      "id": "6c16e348494c42fb8c8e8bda92b20fb2",
      "parent_id": null,
      "user_id": null
    },
    "timeSinceChangedMs": 3466747
  }
]
```

--------------------------------

### Example flow: Get state_changed events based on area

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/cookbook/get-state_changed-events-based-on-area.md

This JSON flow file configures a Node-RED flow to listen for state_changed events and filter them by area. Import this flow into Node-RED to use it.

```json
@[code](@examples/cookbook/get-state_changed-events-based-on-area/example_01.json)
```

--------------------------------

### Sentence Node Example Input

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/node/sentence.md

Example input for the Sentence node. All properties must be provided in msg.payload. The response property is used only when the Response Type is set to dynamic.

```json
{
  "response": "The light is now on"
}
```

--------------------------------

### Example output of msg: payload JSON

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/node/get-history.md

Shows the structure of the returned payload, containing an array of history objects. Each object includes attributes (friendly_name, icon, brightness), context (id, parent_id, user_id), entity_id, last_changed, last_updated, and state. The example shows two entries and uses an ellipsis (...) to indicate more entries.

```json
{
  "payload": [
    {
      "attributes": {
        "friendly_name": "Kitchen Light",
        "icon": "mdi:light-switch",
      },
      "context": {
        "id": "850e510e36fb494c9abc79e01e897d54",
        "parent_id": null,
        "user_id": null
      },
      "entity_id": "light.kitchen_light",
      "last_changed": "2019-12-28T06:47:28.618000+00:00",
      "last_updated": "2019-12-28T06:47:28.618000+00:00",
      "state": "off"
    },
    {
      "attributes": {
        "brightness": 28,
        "friendly_name": "Kitchen Light",
        "icon": "mdi:light-switch",
      },
      "context": {
        "id": "4d4abe29f2bc43dab39101193f1fefe4",
        "parent_id": null,
        "user_id": null
      },
      "entity_id": "light.kitchen_light",
      "last_changed": "2019-12-28T07:48:11.514137+00:00",
      "last_updated": "2019-12-28T07:48:11.514137+00:00",
      "state": "on"
    },
    ...
  ]
}
```

--------------------------------

### Example flow using WebSocket JSONata functions

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/cookbook/jsonata/functions.md

This example demonstrates the basic use of some of these functions. The code is a Node-RED flow JSON that uses WebSocket nodes with JSONata expressions.

```json
@[code](@examples/cookbook/jsonata-examples/ws-functions.json)
```

--------------------------------

### Time node: offset and on/off switch

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/cookbook/using-date-and-time-entities-to-trigger-flows.md

Example flow using the time node with an offset and an on/off switch by exposing the node to Home Assistant via the custom component.

```json
{
  "id": "1b1",
  "type": "time",
  "z": "flow",
  "name": "next alarm with offset",
  "entity_id": "sensor.next_alarm",
  "property": "",
  "offset": 0,
  "offset_input": "input_number.offset",
  "offset_entity": true,
  "x": 240,
  "y": 120,
  "wires": [["1b2"]]
}

```

--------------------------------

### Access Home Assistant global context

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/node/config-server.md

Example of accessing Home Assistant connection data, states, and services from the Node-RED global context when the 'Enable Global Context Store' setting is enabled.

```javascript
const haCtx = global.get("homeassistant");
const configCtx = haCtx.homeAssistant;
const entityState = configCtx.states["switch.my_switch"];
return entityState.state === "on";
```

--------------------------------

### Navigate to project directory

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/guide/development.md

Change to the project's root directory.

```bash
cd node-red-contrib-home-assistant-websocket
```

--------------------------------

### Enable Shopping List integration in configuration.yaml

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/cookbook/expiration-date-monitor.md

Activates the Home Assistant Shopping List integration in configuration.yaml. Required before the expiration date monitor can use the shopping list as input.

```yaml
# Example configuration.yaml entry
shopping_list:
```

--------------------------------

### Next alarm sensor: basic example

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/cookbook/using-date-and-time-entities-to-trigger-flows.md

Basic flow using the Home Assistant Companion app next alarm sensor. Note: the entity name may be localized (e.g., 'prossimo_allarme' in Italian).

```json
[
  {
    "id": "a1",
    "type": "server",
    "z": "",
    "name": "Home Assistant",
    "version": "1.0.0",
    "addon": false,
    "rejectUnauthorizedCerts": true,
    "ha_global": false,
    "x": 100,
    "y": 80,
    "wires": []
  },
  {
    "id": "a2",
    "type": "api-current-state",
    "z": "flow",
    "name": "next alarm",
    "server": "a1",
    "entity_id": "sensor.next_alarm",
    "state_type": "trigger",
    "halt_if": "",
    "halt_if_type": "str",
    "halt_if_compare": "is",
    "outputs": 1,
    "x": 240,
    "y": 120,
    "wires": [["a3"]]
  },
  {
    "id": "a3",
    "type": "debug",
    "z": "flow",
    "name": "",
    "active": true,
    "console": "false",
    "complete": "payload",
    "x": 400,
    "y": 120,
    "wires": []
  }
]

```

--------------------------------

### JSONata Expression to Get Friendly Names of All Lights and Switches in On State

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/guide/action.md

JSONata expression to get friendly names of all lights and switches that are on, using $entities() and $join().

```json
{
     "message": "The " & $join($entities().*[state = "on" and entity_id ~> /^light|^switch/].attributes.friendly_name, ", ") & " are on.",
     "title": "Left On"
}
```

--------------------------------

### YAML for input_select.holiday_lights_demo_mode

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/cookbook/holiday-lights-scheduler-and-demo-mode-for-wled.md

Defines the input_select helper for the demo mode with options off, cycle effects, and cycle presets. Initial value is off.

```yaml
input_select:
  holiday_lights_demo_mode:
    name: Mode
    options:
      - off
      - cycle effects
      - cycle presets
    initial: off
    icon: "mdi:animation"
```

--------------------------------

### Create Home Assistant automation to turn on input boolean on restart

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/cookbook/starting-flow-after-home-assistant-restart.md

YAML automation that triggers on the 'homeassistant' start event and turns on the 'input_boolean.home_assistant_restarted' entity. This automation runs when Home Assistant restarts, setting the flag for Node-RED to detect.

```yaml
alias: Home Assistant Restart
description: ""
trigger:
  - platform: homeassistant
    event: start
condition: []
action:
  - service: input_boolean.turn_on
    data: {}
    entity_id: input_boolean.home_assistant_restarted
mode: single
```

--------------------------------

### Run tests with pnpm test

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/guide/development.md

Run the project's tests.

```sh
pnpm test
```

--------------------------------

### Mustache Template Example (JSON flow)

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/guide/action.md

Example flow using Mustache templates in the action node to set the service based on msg.payload. The code is a JSON flow definition.

```json
@[code](@examples/guides/action_node/mustache_templates_01.json)
```

--------------------------------

### Sample input for Action node

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/node/action.md

Shows the expected msg.payload structure for the Action node, including action, target arrays for floor, area, device, entity, and label, and optional data.

```JSON
{
    "action": "light.turn_on",
    "target": {
        "floor_id": ["first_floor"],
        "area_id": ["kitchen"],
        "device_id": ["8932894082930482903"],
        "entity_id": ["light.kitchen", "switch.garage_light"],
        "label_id": ["outdoor_lights"]
    }
    "data": {
        "brightness_pct": 50
    }
}
```

--------------------------------

### Set temperature with calculation

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/cookbook/jsonata/action.md

Reads a sensor state, converts it to a number, and adds 3. States from Home Assistant are always strings, so $number() is required before arithmetic.

```jsonata
{
  "temperature": $number($entities("sensor.living_room_temperature").state) + 3
}
```

--------------------------------

### Wait Until node: Override with several entities

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/node/wait-until.md

Provides a payload example that overrides the entities configuration with an array of entity IDs.

```json
{
  "entities": ["light.living_room", "light.bedroom"]
}
```

--------------------------------

### Wait Until node: Override with a single entity

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/node/wait-until.md

Provides a payload example that overrides the entities configuration with a single entity ID string.

```json
{
  "entities": "light.living_room"
}
```

--------------------------------

### Example msg.payload for Update Config

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/node/update-config.md

Shows the structure of the msg.payload object that can override the Entity Config node. All properties are optional and must be under msg.payload.

```json
{
  "id": "d9d27ac6b4ebf78f",
  "icon": "mdi:lightbulb",
  "name": "My Light",
  "entityPicture": "/local/images/my_light.png"
}
```

--------------------------------

### Entity ID List Flow (JSON)

Source: https://github.com/zachowj/node-red-contrib-home-assistant-websocket/blob/main/docs/guide/action.md

Flow definition for the entity ID list example, using the JSONata expression from the previous snippet.

```json
@[code](@examples/guides/action_node/entity_id_list.json)
```
Tokens:
Raw