Node-RED Companion Integration

https://github.com/zachowj/hass-node-red
Admin
A companion component that bridges Node-RED and Home Assistant, allowing seamless management of Home...
Tokens:12,249
Snippets:100
Trust Score:7.1
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Test Dependencies

Source: https://github.com/zachowj/hass-node-red/blob/main/tests/README.md

Install necessary testing dependencies, including Home Assistant and pytest plugins, using `uv pip install`.

```bash
uv pip install -r requirements_test.txt
```

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

### Install Node-RED Companion Integration

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Instructions for installing the Node-RED Companion Integration using HACS or manually.

```yaml
# Option 1: HACS (recommended) – search for "hass-node-red" in HACS integrations
# Option 2: Manual – copy custom_components/nodered/ to <config>/custom_components/nodered/
# Then add via UI: Settings → Devices & Services → + Add Integration → "Node-RED Companion"
```

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

### nodered/version

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Retrieves the current version of the installed Node-RED Companion Integration. This is used by Node-RED to verify compatibility.

```APIDOC
## WebSocket Command: `nodered/version`

### Description
Returns the current version string of the installed integration. Used by Node-RED on connection to verify compatibility between the Node-RED node package and the HA companion.

### Method
WebSocket Command

### Endpoint
nodered/version

### Request Example
```javascript
// Node-RED WebSocket call (JSON sent over HA WebSocket API)
const msg = { id: 1, type: "nodered/version" };
```

### Response Example
```json
// Expected response:
{ id: 1, type: "result", success: true, result: "4.2.3" }
```

### Equivalent Python Test Assertion
```python
from homeassistant.components.websocket_api.messages import result_message
assert result_message(1, "4.2.3") == {"id": 1, "type": "result", "success": True, "result": "4.2.3"}
```
```

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

### Node-RED Switch State Change Events

Source: https://context7.com/zachowj/hass-node-red/llms.txt

These examples show the JSON payloads received by Node-RED when a bidirectional switch's state is changed in Home Assistant or triggered by the `nodered.trigger` service.

```javascript
// When user toggles the switch OFF in HA, Node-RED receives:
// { "id": 40, "type": "event", "event": { "type": "state_changed", "state": false } }

// When user toggles ON:
// { "id": 40, "type": "event", "event": { "type": "state_changed", "state": true } }

// When nodered.trigger service fires (output_path "1"):
// { "id": 40, "type": "event", "event": { "type": "automation_triggered", "output_path": "1", "message": {...} } }
```

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

### Example Output Shape for Sentence Objects

Source: https://context7.com/zachowj/hass-node-red/llms.txt

This shows the expected JSON structure when sentence objects are converted for use with the integration. It includes text, entities, unmatched entities, and intent data.

```json
{
  "text": "turn on the lights",
  "entities": {},
  "unmatched_entities": {},
  "intent": {"name": "HassTurnOn", "data": {}}
}
```

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

### Create Virtual Environment and Activate

Source: https://github.com/zachowj/hass-node-red/blob/main/tests/README.md

Use `uv venv` to create a virtual environment and `source` to activate it. This isolates project dependencies.

```bash
uv venv .venv
source .venv/bin/activate
```

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

### NodeRedEntity Base Class and Device Identifiers

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Demonstrates how to use the `NodeRedEntity` base class and the `generate_device_identifiers` utility function for creating device registry identifiers in Home Assistant.

```python
from custom_components.nodered.entity import NodeRedEntity, generate_device_identifiers

# generate_device_identifiers: creates the HA device registry identifier set
identifiers = generate_device_identifiers("my-device-id")
# → {("nodered", "my-device-id")}

# Entity category mapping (used in discovery config)
entity = NodeRedEntity(hass, {
    "server_id": "srv1",
    "node_id": "node1",
    "config": {
        "name": "My Entity",
        "icon": "mdi:home",
        "entity_category": "diagnostic",   # → EntityCategory.DIAGNOSTIC
        # "entity_category": "config"      # → EntityCategory.CONFIG
        # "entity_category": None          # → None (default/main)
    }
})
# entity._attr_entity_category → EntityCategory.DIAGNOSTIC
```

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

### Run Specific Test Function

Source: https://github.com/zachowj/hass-node-red/blob/main/tests/README.md

Execute a single test function, `test_setup_unload_and_reload_entry`, within a specific test file, `tests/test_init.py`, using the `-k` flag.

```bash
pytest tests/test_init.py -k test_setup_unload_and_reload_entry
```

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

### nodered/device/action

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Executes a Home Assistant device action from Node-RED. The `action` payload must conform to the HA device automation action schema. Requires admin access.

```APIDOC
## WebSocket Command: `nodered/device/action`

### Description
Executes a Home Assistant device action from Node-RED. The `action` payload must conform to the HA device automation action schema. Requires admin access.

### Request Example (Execute device action)
```json
{
  "id": 10,
  "type": "nodered/device/action",
  "action": {
    "device_id": "abc123deviceid",
    "domain": "light",
    "entity_id": "light.living_room",
    "type": "turn_on"
  }
}
```

### Response Example (Success)
```json
{ "id": 10, "type": "result", "success": true, "result": null }
```

### Response Example (Error)
```json
{ "id": 10, "type": "result", "success": false,
  "error": { "code": "entity_not_found", "message": "Entity 'light.living_room' not found" } }
```
```

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

### Node-RED WebSocket Command: nodered/discovery (Create)

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Registers a new Home Assistant entity driven by a Node-RED node. Subsequent calls update the entity. Requires server_id and node_id.

```javascript
// Create a new sensor entity from Node-RED
{
  "id": 2,
  "type": "nodered/discovery",
  "component": "sensor",          // one of: binary_sensor|button|number|select|sensor|switch|text|time
  "server_id": "home-assistant-server-1",
  "node_id": "abc123def456",
  "state": 21.5,
  "attributes": { "friendly_name": "Living Room Temp" },
  "config": {
    "name": "Living Room Temperature",
    "device_class": "temperature",
    "unit_of_measurement": "°C",
    "state_class": "measurement",
    "icon": "mdi:thermometer",
    "entity_category": null
  },
  "device_info": {
    "id": "my-node-red-device",
    "name": "Node-RED Climate Hub",
    "manufacturer": "DIY",
    "model": "v1",
    "sw_version": "1.0.0"
  }
}
// Response: { "id": 2, "type": "result", "success": true, "result": null }
```

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

### Run Tests with Code Coverage

Source: https://github.com/zachowj/hass-node-red/blob/main/tests/README.md

Run tests and generate a code coverage report for the `custom_components.nodered` module. This command shows the percentage of code executed and highlights missed lines.

```bash
pytest --durations=10 --cov-report term-missing --cov=custom_components.nodered tests
```

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

### Discover Node-RED Binary Sensor

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Discover and create a read-only binary sensor. The 'is_on' state is determined by string values received from Node-RED. Supports various truthy string representations.

```javascript
{
  "id": 20,
  "type": "nodered/discovery",
  "component": "binary_sensor",
  "server_id": "srv1",
  "node_id": "motion_001",
  "state": true,
  "config": { "name": "Front Door Motion", "device_class": "motion" }
}
```

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

### Discover Node-RED Select Entity

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Create a dropdown select entity for choosing options. The `options` array defines the available choices. The state is the currently selected option.

```javascript
// Discovery: create a mode selector
{
  "id": 60,
  "type": "nodered/discovery",
  "component": "select",
  "server_id": "srv1",
  "node_id": "hvac_mode",
  "state": "eco",
  "config": {
    "name": "HVAC Mode",
    "options": ["off", "eco", "comfort", "boost"],
    "icon": "mdi:thermostat"
  }
}
```

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

### Create Node-RED Sensor with State Class

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Use this for sensors that track cumulative values like energy. The `last_reset` field is important for accurate `total_increasing` state class tracking.

```javascript
{
  "id": 30,
  "type": "nodered/discovery",
  "component": "sensor",
  "server_id": "srv1",
  "node_id": "energy_kwh",
  "state": 123.45,
  "config": {
    "name": "Energy Today",
    "device_class": "energy",
    "unit_of_measurement": "kWh",
    "state_class": "total_increasing",
    "last_reset": "2024-06-01T00:00:00+00:00"
  }
}
```

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

### Node-RED Companion Integration manifest.json

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Metadata for the Node-RED Companion integration, including domain, name, version, and dependencies.

```json
{
  "domain": "nodered",
  "name": "Node-RED Companion",
  "version": "4.2.3",
  "config_flow": true,
  "iot_class": "local_push",
  "after_dependencies": ["conversation", "mqtt"],
  "documentation": "https://zachowj.github.io/node-red-contrib-home-assistant-websocket/guide/custom_integration/"
}
```

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

### nodered/discovery

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Registers or removes a Home Assistant entity driven by a Node-RED node. This command manages the entity lifecycle.

```APIDOC
## WebSocket Command: `nodered/discovery`

### Description
Registers or removes a Home Assistant entity driven by a Node-RED node. The first call with a given `server_id` + `node_id` pair creates the entity; subsequent calls update it. Including `"remove": true` removes it. This is the primary mechanism for entity lifecycle management.

### Method
WebSocket Command

### Endpoint
nodered/discovery

### Parameters
#### Request Body
- **id** (integer) - Required - Unique identifier for the command.
- **type** (string) - Required - Must be `"nodered/discovery"`.
- **component** (string) - Required - The type of entity to register (e.g., `binary_sensor`, `sensor`, `switch`).
- **server_id** (string) - Required - Identifier for the Home Assistant server.
- **node_id** (string) - Required - Unique identifier for the Node-RED node.
- **state** (any) - Optional - The initial state of the entity (used during creation).
- **attributes** (object) - Optional - Initial attributes for the entity.
- **config** (object) - Optional - Configuration options for the entity (e.g., `name`, `unit_of_measurement`).
- **device_info** (object) - Optional - Information about the device the entity belongs to.
- **remove** (boolean) - Optional - Set to `true` to remove the entity.

### Request Example (Create Entity)
```javascript
{
  "id": 2,
  "type": "nodered/discovery",
  "component": "sensor",          // one of: binary_sensor|button|number|select|sensor|switch|text|time
  "server_id": "home-assistant-server-1",
  "node_id": "abc123def456",
  "state": 21.5,
  "attributes": { "friendly_name": "Living Room Temp" },
  "config": {
    "name": "Living Room Temperature",
    "device_class": "temperature",
    "unit_of_measurement": "°C",
    "state_class": "measurement",
    "icon": "mdi:thermometer",
    "entity_category": null
  },
  "device_info": {
    "id": "my-node-red-device",
    "name": "Node-RED Climate Hub",
    "manufacturer": "DIY",
    "model": "v1",
    "sw_version": "1.0.0"
  }
}
```

### Request Example (Remove Entity)
```javascript
{
  "id": 3,
  "type": "nodered/discovery",
  "component": "sensor",
  "server_id": "home-assistant-server-1",
  "node_id": "abc123def456",
  "remove": true
}
```

### Response Example
```json
// Response: { "id": 2, "type": "result", "success": true, "result": null }
```
```

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

### Run All Tests

Source: https://github.com/zachowj/hass-node-red/blob/main/tests/README.md

Execute all tests located within the `tests/` directory using the `pytest` command.

```bash
pytest tests/
```

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

### nodered/entity

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Pushes real-time state and/or attribute updates to an existing entity. This command only affects the live state, not the entity's configuration.

```APIDOC
## WebSocket Command: `nodered/entity`

### Description
Pushes a real-time state and/or attribute update to an already-discovered entity identified by `server_id` + `node_id`. Does not alter the entity's configuration—only its live state.

### Method
WebSocket Command

### Endpoint
nodered/entity

### Parameters
#### Request Body
- **id** (integer) - Required - Unique identifier for the command.
- **type** (string) - Required - Must be `"nodered/entity"`.
- **server_id** (string) - Required - Identifier for the Home Assistant server.
- **node_id** (string) - Required - Unique identifier for the Node-RED node.
- **state** (any) - Optional - The new state of the entity.
- **attributes** (object) - Optional - New or updated attributes for the entity.

### Request Example (Update State + Attributes)
```javascript
{
  "id": 4,
  "type": "nodered/entity",
  "server_id": "home-assistant-server-1",
  "node_id": "abc123def456",
  "state": 23.1,
  "attributes": {
    "last_updated_by": "nodered",
    "battery": 95
  }
}
```

### Request Example (Set Binary Sensor State)
```javascript
// Set binary sensor to ON using any truthy string
{
  "id": 5,
  "type": "nodered/entity",
  "server_id": "home-assistant-server-1",
  "node_id": "motion_sensor_node",
  "state": "on",   // also accepts: true, 1, "true", "yes", "enable", "open", "home", "unlocked"
  "attributes": { "occupancy": true }
}
```

### Response Example
```json
// Response: { "id": 4, "type": "result", "success": true, "result": null }
```
```

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

### Discover Node-RED Bidirectional Switch

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Register a switch that can be controlled from Home Assistant and send state changes back to Node-RED. The `server_id` and `node_id` link the entity to the Node-RED instance and flow.

```javascript
// Discovery: register a switch (Node-RED maintains bidirectional WebSocket)
{
  "id": 40,
  "type": "nodered/discovery",
  "component": "switch",
  "server_id": "srv1",
  "node_id": "flow_enable_switch",
  "state": true,
  "config": { "name": "Night Mode Flow", "icon": "mdi:weather-night" }
}
```

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

### nodered/webhook

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Registers a Home Assistant webhook and subscribes the WebSocket connection to its events. When an HTTP request hits the webhook URL, the payload, headers, and query parameters are forwarded as WebSocket events to the Node-RED node. Closing the subscription unregisters the webhook automatically.

```APIDOC
## WebSocket Command: `nodered/webhook`

### Description
Registers a Home Assistant webhook and subscribes the WebSocket connection to its events. When an HTTP request hits the webhook URL, the payload, headers, and query parameters are forwarded as WebSocket events to the Node-RED node. Closing the subscription unregisters the webhook automatically.

### Request Example (Register webhook)
```json
{
  "id": 8,
  "type": "nodered/webhook",
  "server_id": "home-assistant-server-1",
  "name": "My NR Webhook",
  "webhook_id": "secret-webhook-id-xyz",
  "allowed_methods": ["POST", "PUT"]   // optional; default = all SUPPORTED_METHODS
}
```

### Response Example (Success)
```json
{ "id": 8, "type": "result", "success": true, "result": null }
```

### Event Example (HTTP POST to webhook)
```json
{
  "id": 8,
  "type": "event",
  "event": {
    "data": {
      "payload": { "temperature": 22.5 },
      "headers": { "Content-Type": "application/json", "X-Custom": "value" },
      "params": { "source": "sensor_a" }
    }
  }
}
```

### Request Example (Unsubscribe)
```json
{ "id": 9, "type": "unsubscribe_events", "subscription": 8 }
```
```

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

### WebSocket Command: nodered/sentence

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Registers voice/conversation trigger sentences with Home Assistant. When a sentence is recognized, it fires a trigger and streams an event to Node-RED. Supports both fixed and dynamic responses.

```APIDOC
## WebSocket Command: `nodered/sentence`

Registers one or more voice/conversation trigger sentences with the Home Assistant conversation integration. When a matching sentence is recognized (e.g., via Assist), the trigger fires and streams an event to Node-RED. Supports both fixed and dynamic response types.

### Fixed Response Example:
```json
{
  "id": 13,
  "type": "nodered/sentence",
  "server_id": "home-assistant-server-1",
  "sentences": ["turn on the lights", "lights on please"],
  "response": "Turning the lights on now!",
  "response_type": "fixed"       // default
}
```

### Dynamic Response Example:
```json
{
  "id": 14,
  "type": "nodered/sentence",
  "server_id": "home-assistant-server-1",
  "sentences": ["set temperature to {temp}"],
  "response_type": "dynamic",
  "response_timeout": 2.5   // seconds to wait for Node-RED's reply before fallback
}
```

### Event Fired on Match:
```json
{
  "id": 13, "type": "event",
  "event": {
    "data": {
      "sentence": "turn on the lights",
      "result": { "text": "turn on the lights", ... },
      "deviceId": "assist_satellite_device_id",
      "responseId": 13
    }
  }
}
```
```

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

### Discover Node-RED Number Input Slider

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Create a number input entity that functions as a slider in Home Assistant. Configure `min_value`, `max_value`, `step_value`, and `mode` to customize its behavior.

```javascript
// Discovery: create a number slider (0–100, step 5)
{
  "id": 50,
  "type": "nodered/discovery",
  "component": "number",
  "server_id": "srv1",
  "node_id": "brightness_slider",
  "state": 75,
  "config": {
    "name": "Brightness Level",
    "min_value": 0,
    "max_value": 100,
    "step_value": 5,
    "mode": "slider",
    "unit_of_measurement": "%",
    "icon": "mdi:brightness-6"
  }
}
```

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

### Execute Home Assistant Device Action

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Executes a device action defined in Home Assistant. The action payload must match the HA device automation action schema. Requires admin access.

```javascript
// Execute a device action (e.g., turn on a light via device automation)
{
  "id": 10,
  "type": "nodered/device/action",
  "action": {
    "device_id": "abc123deviceid",
    "domain": "light",
    "entity_id": "light.living_room",
    "type": "turn_on"
  }
}
```

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

### Node-RED WebSocket Command: nodered/version

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Verifies compatibility between Node-RED and the HA companion by checking the integration version. Used on connection.

```javascript
// Node-RED WebSocket call (JSON sent over HA WebSocket API)
const msg = { id: 1, type: "nodered/version" };
// Expected response:
// { id: 1, type: "result", success: true, result: "4.2.3" }
```

```python
// Equivalent Python test assertion
from homeassistant.components.websocket_api.messages import result_message
assert result_message(1, "4.2.3") == {"id": 1, "type": "result", "success": True, "result": "4.2.3"}
```

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

### Node-RED WebSocket Command: nodered/discovery (Remove)

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Removes a previously registered Home Assistant entity. Requires server_id, node_id, and 'remove: true'.

```javascript
// Remove the same entity
{
  "id": 3,
  "type": "nodered/discovery",
  "component": "sensor",
  "server_id": "home-assistant-server-1",
  "node_id": "abc123def456",
  "remove": true
}
```

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

### Update Entity Configuration Dynamically

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Use this command to change an entity's name, icon, or entity picture at runtime. It can also update the available options for select entities.

```javascript
// Rename entity and change icon at runtime
{
  "id": 6,
  "type": "nodered/entity/update_config",
  "server_id": "home-assistant-server-1",
  "node_id": "abc123def456",
  "config": {
    "name": "Bedroom Temperature",
    "icon": "mdi:bed-temperature",
    "entity_picture": "/local/bedroom.png"
  }
}
```

```javascript
// Update the available options of a select entity
{
  "id": 7,
  "type": "nodered/entity/update_config",
  "server_id": "home-assistant-server-1",
  "node_id": "mode_select_node",
  "config": {
    "options": ["eco", "comfort", "boost", "off"]
  }
}
```

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

### WebSocket Command: nodered/sentence_response

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Sends a dynamic response back to a pending sentence trigger. This command must be called within the `response_timeout` window defined in the `nodered/sentence` command.

```APIDOC
## WebSocket Command: `nodered/sentence_response`

Sends a dynamic response back to a pending sentence trigger. Must be called within the `response_timeout` window defined in `nodered/sentence`.

### Request Example:
```json
{
  "id": 15,
  "type": "nodered/sentence_response",
  "response_id": 14,            // must match the id of the nodered/sentence subscription
  "response": "Temperature set to 22 degrees."
}
```

### Response Example (Success):
```json
{ "id": 15, "type": "result", "success": true, "result": null }
```

### Response Example (Error):
```json
{
  "id": 15, "type": "result", "success": false,
  "error": { "code": "sentence_response_not_found", "message": "Sentence response not found for id: 14" }
}
```
```

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

### Register Home Assistant Webhook

Source: https://context7.com/zachowj/hass-node-red/llms.txt

This command registers a webhook and forwards HTTP requests to it as WebSocket events. Closing the subscription automatically unregisters the webhook.

```javascript
// Register a webhook; Node-RED will receive events on this subscription
{
  "id": 8,
  "type": "nodered/webhook",
  "server_id": "home-assistant-server-1",
  "name": "My NR Webhook",
  "webhook_id": "secret-webhook-id-xyz",
  "allowed_methods": ["POST", "PUT"]   // optional; default = all SUPPORTED_METHODS
}
```

```javascript
// Unsubscribe (from Node-RED side) to automatically unregister the webhook:
{ "id": 9, "type": "unsubscribe_events", "subscription": 8 }
```

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

### Node-RED WebSocket Command: nodered/entity (Update)

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Pushes a real-time state and/or attribute update to an existing entity. Does not alter configuration. Requires server_id and node_id.

```javascript
// Update state + attributes of an existing entity
{
  "id": 4,
  "type": "nodered/entity",
  "server_id": "home-assistant-server-1",
  "node_id": "abc123def456",
  "state": 23.1,
  "attributes": {
    "last_updated_by": "nodered",
    "battery": 95
  }
}
// Response: { "id": 4, "type": "result", "success": true, "result": null }
```

```javascript
// Set binary sensor to ON using any truthy string
{
  "id": 5,
  "type": "nodered/entity",
  "server_id": "home-assistant-server-1",
  "node_id": "motion_sensor_node",
  "state": "on",   // also accepts: true, 1, "true", "yes", "enable", "open", "home", "unlocked"
  "attributes": { "occupancy": true }
}
```

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

### Trigger Node-RED Flow via Python Service Call

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Trigger a Node-RED switch node using a Python service call within Home Assistant. This allows programmatic control of Node-RED flows.

```python
await hass.services.async_call(
    "nodered",
    "trigger",
    {
        "entity_id": "switch.nodered_my_switch_node",
        "output_path": "1",
        "message": {"source": "ha_automation", "value": 42},
    },
    blocking=True,
)
```

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

### nodered/device/trigger

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Subscribes to a Home Assistant device trigger and streams matching trigger events back to Node-RED as WebSocket events. Closing the subscription removes the trigger listener.

```APIDOC
## WebSocket Command: `nodered/device/trigger`

### Description
Subscribes to a Home Assistant device trigger and streams matching trigger events back to Node-RED as WebSocket events. Closing the subscription removes the trigger listener.

### Request Example (Subscribe to device trigger)
```json
{
  "id": 11,
  "type": "nodered/device/trigger",
  "node_id": "zigbee_remote_node",
  "device_trigger": {
    "platform": "device",
    "domain": "zha",
    "device_id": "remote_device_id_xyz",
    "type": "remote_button_short_press",
    "subtype": "turn_on"
  }
}
```

### Response Example (Success)
```json
{ "id": 11, "type": "result", "success": true, "result": null }
```

### Event Example (Trigger event)
```json
{
  "id": 11,
  "type": "event",
  "event": {
    "type": "device_trigger",
    "data": {
      "platform": "device",
      "type": "remote_button_short_press",
      "subtype": "turn_on",
      "device_id": "remote_device_id_xyz"
    }
  }
}
```
```

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

### Entity Platform: NodeRedBinarySensor

Source: https://context7.com/zachowj/hass-node-red/llms.txt

A read-only binary sensor whose `is_on` state is determined by a string received from Node-RED. It recognizes a broad set of truthy strings, mapping them to `is_on=True`.

```APIDOC
## Entity Platform: `NodeRedBinarySensor`

A read-only binary sensor whose `is_on` value is determined by the state string received from Node-RED. A broad set of truthy strings are recognized so that Node-RED JavaScript booleans, HA state strings, and numeric values all map correctly.

### Discovery Example (Create Binary Sensor):
```json
{
  "id": 20,
  "type": "nodered/discovery",
  "component": "binary_sensor",
  "server_id": "srv1",
  "node_id": "motion_001",
  "state": true,
  "config": { "name": "Front Door Motion", "device_class": "motion" }
}
```

### Truthy State Values (all evaluate to `is_on=True`):
`true` (bool), `1` (number), `"1"`, `"true"`, `"yes"`, `"enable"`, `"on"`, `"open"`, `"home"`, `"unlocked"`

All other values map to `is_on=False`.

### Live Update Example (via `nodered/entity`):
```json
{
  "id": 21,
  "type": "nodered/entity",
  "server_id": "srv1",
  "node_id": "motion_001",
  "state": false,
  "attributes": { "last_triggered": "2024-06-01T12:00:00" }
}
```
```

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

### nodered/entity/update_config

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Dynamically updates the configuration of an already-registered entity at runtime without re-running discovery. This includes changing the name, icon, entity picture, or options list.

```APIDOC
## WebSocket Command: `nodered/entity/update_config`

### Description
Dynamically updates the configuration (name, icon, entity picture, options list) of an already-registered entity at runtime without re-running discovery.

### Request Example (Rename entity and change icon)
```json
{
  "id": 6,
  "type": "nodered/entity/update_config",
  "server_id": "home-assistant-server-1",
  "node_id": "abc123def456",
  "config": {
    "name": "Bedroom Temperature",
    "icon": "mdi:bed-temperature",
    "entity_picture": "/local/bedroom.png"
  }
}
```

### Response Example (Success)
```json
{ "id": 6, "type": "result", "success": true, "result": null }
```

### Request Example (Update options)
```json
{
  "id": 7,
  "type": "nodered/entity/update_config",
  "server_id": "home-assistant-server-1",
  "node_id": "mode_select_node",
  "config": {
    "options": ["eco", "comfort", "boost", "off"]
  }
}
```
```

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

### Create Timestamp Sensor

Source: https://context7.com/zachowj/hass-node-red/llms.txt

This sensor automatically converts various time formats (ISO strings, Unix seconds, milliseconds) into a datetime state. Ensure the `node_id` is unique for each sensor.

```javascript
// Timestamp sensor: Node-RED sends JS Date.now() (milliseconds)
{
  "id": 31,
  "type": "nodered/entity",
  "server_id": "srv1",
  "node_id": "last_seen_sensor",
  "state": 1717200000000    // ms since epoch → converted to UTC datetime
}
// Also accepted: "2024-06-01T12:00:00+00:00" (ISO string)
// Also accepted: 1717200000 (Unix seconds, detected by value < 1e11)
```

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

### HA Service: nodered.trigger

Source: https://context7.com/zachowj/hass-node-red/llms.txt

The `trigger` service allows Home Assistant automations or scripts to trigger a Node-RED switch node at a specified output path with an optional message payload. This facilitates HA to Node-RED flow control.

```APIDOC
## HA Service: `nodered.trigger`

The `trigger` service is registered on the `switch` platform and allows Home Assistant automations (or scripts) to trigger a Node-RED switch node at a specified output path with an optional message payload. This is the primary way HA → Node-RED flow control works.

### Automation Example (YAML):
```yaml
automation:
  - alias: "Button Press → Node-RED"
    trigger:
      platform: state
      entity_id: input_button.my_button
    action:
      service: nodered.trigger
      target:
        entity_id: switch.nodered_my_switch_node
      data:
        output_path: "1"          # which output port to trigger (default "0")
        message:                  # arbitrary payload sent to the Node-RED node
          source: "ha_automation"
          timestamp: "{{ now().isoformat() }}"
```

### Service Call Example (Python):
```python
# Equivalent Python call via hass.services.async_call
await hass.services.async_call(
    "nodered",
    "trigger",
    {
        "entity_id": "switch.nodered_my_switch_node",
        "output_path": "1",
        "message": {"source": "ha_automation", "value": 42},
    },
    blocking=True,
)
```
```

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

### Register Voice Trigger with Dynamic Response

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Register a voice command with a dynamic response. Node-RED will provide the response text via 'nodered/sentence_response'. A timeout is specified for waiting for Node-RED's reply.

```javascript
{
  "id": 14,
  "type": "nodered/sentence",
  "server_id": "home-assistant-server-1",
  "sentences": ["set temperature to {temp}"],
  "response_type": "dynamic",
  "response_timeout": 2.5   // seconds to wait for Node-RED's reply before fallback
}
```

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

### Discover NodeRedText Entity

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Use this to create a text input entity with configurable constraints like minimum/maximum length, mode, and regex pattern validation. Values exceeding the maximum length are truncated.

```json
// Discovery: create a text input with constraints
{
  "id": 70,
  "type": "nodered/discovery",
  "component": "text",
  "server_id": "srv1",
  "node_id": "user_message",
  "state": "Hello World",
  "config": {
    "name": "User Message",
    "min_length": 1,
    "max_length": 100,
    "mode": "text",
    "pattern": "^[A-Za-z0-9 ]+$",
    "icon": "mdi:message-text"
  }
}

// User types "Good morning" in HA → Node-RED receives:
// { "id": 70, "type": "event", "event": { "type": "value_change", "value": "Good morning" } }
// Values longer than max_length (or 255) are silently truncated with a warning log.
```

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

### Subscribe to Home Assistant Device Trigger

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Streams Home Assistant device trigger events back to Node-RED. Closing the subscription removes the trigger listener.

```javascript
// Subscribe to a Zigbee remote button press device trigger
{
  "id": 11,
  "type": "nodered/device/trigger",
  "node_id": "zigbee_remote_node",
  "device_trigger": {
    "platform": "device",
    "domain": "zha",
    "device_id": "remote_device_id_xyz",
    "type": "remote_button_short_press",
    "subtype": "turn_on"
  }
}
```

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

### Discover NodeRedTime Entity

Source: https://context7.com/zachowj/hass-node-red/llms.txt

This configuration is used to create a time picker entity. Node-RED sends ISO time strings, and HA sends back HH:MM:SS format when the user changes the time.

```json
// Discovery: create a time entity
{
  "id": 80,
  "type": "nodered/discovery",
  "component": "time",
  "server_id": "srv1",
  "node_id": "alarm_time",
  "state": "07:30:00",
  "config": { "name": "Morning Alarm", "icon": "mdi:alarm" }
}

// User sets time to 08:00 in HA → Node-RED receives:
// { "id": 80, "type": "event", "event": { "type": "value_change", "value": "08:00:00" } }

// Node-RED updates the displayed time:
{
  "id": 81,
  "type": "nodered/entity",
  "server_id": "srv1",
  "node_id": "alarm_time",
  "state": "06:45:00"
}
```

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

### Update Node-RED Select Entity Options

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Dynamically update the available options for a select entity without re-discovery. This allows for changing choices based on runtime conditions.

```javascript
// Dynamically update options:
{
  "id": 61,
  "type": "nodered/entity/update_config",
  "server_id": "srv1",
  "node_id": "hvac_mode",
  "config": { "options": ["off", "eco", "comfort", "boost", "turbo"] }
}
```

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

### Discover NodeRedButton Entity

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Use this to create a button entity. Pressing the button in the HA UI sends an `automation_triggered` event to Node-RED, including the entity's current state snapshot.

```json
// Discovery: create a button
{
  "id": 90,
  "type": "nodered/discovery",
  "component": "button",
  "server_id": "srv1",
  "node_id": "reboot_button",
  "config": { "name": "Restart Server", "icon": "mdi:restart" }
}

// User presses button in HA → Node-RED receives:
// {
//   "id": 90, "type": "event",
//   "event": {
//     "type": "automation_triggered",
//     "data": {
//       "entity": {
//         "entity_id": "button.restart_server",
//         "state": "unknown",
//         "attributes": { ... },
//         "last_changed": "...",
//         "last_updated": "..."
//       }
//     }
//   }
// }
```

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

### Update Node-RED Binary Sensor State

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Update the state and attributes of a Node-RED binary sensor. The 'is_on' value maps truthy strings from Node-RED to 'true' and others to 'false'.

```javascript
{
  "id": 21,
  "type": "nodered/entity",
  "server_id": "srv1",
  "node_id": "motion_001",
  "state": false,
  "attributes": { "last_triggered": "2024-06-01T12:00:00" }
}
```

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

### Update Node-RED Number Entity Configuration

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Modify the configuration of an existing number entity (e.g., min/max values, step) without requiring re-discovery. This is useful for dynamic adjustments.

```javascript
// Runtime update of min/max/step without re-discovery:
{
  "id": 51,
  "type": "nodered/entity/update_config",
  "server_id": "srv1",
  "node_id": "brightness_slider",
  "config": { "min_value": 10, "max_value": 90, "step_value": 10 }
}
```

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

### Convert RecognizeResult to Dictionary

Source: https://context7.com/zachowj/hass-node-red/llms.txt

This function recursively serializes a `RecognizeResult` object into a JSON-serializable dictionary, addressing issues with non-serializable types in Home Assistant 2024.12.

```python
from custom_components.nodered.sentence import convert_recognize_result_to_dict

# With a real RecognizeResult from hassil:
result_dict = convert_recognize_result_to_dict(recognize_result)
# Primitive types (int, float, str, None) pass through unchanged.
# Objects with __dict__ are converted to {key: serialized_value} dicts.
# Lists are recursively converted.
```

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

### Register Voice Trigger with Fixed Response

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Register a voice command with a fixed text response. The trigger fires an event to Node-RED when the sentence is recognized.

```javascript
{
  "id": 13,
  "type": "nodered/sentence",
  "server_id": "home-assistant-server-1",
  "sentences": ["turn on the lights", "lights on please"],
  "response": "Turning the lights on now!",
  "response_type": "fixed"       // default
}
```

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

### NodeRedJSONEncoder for Timedelta Serialization

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Illustrates the use of `NodeRedJSONEncoder` to serialize JSON payloads, specifically handling `timedelta` objects by converting them to their total seconds representation.

```python
import json
from datetime import timedelta
from custom_components.nodered.utils import NodeRedJSONEncoder

payload = {
    "duration": timedelta(minutes=5, seconds=30),
    "label": "cooldown",
    "value": 42
}
result = json.dumps(payload, cls=NodeRedJSONEncoder)
# → '{"duration": 330.0, "label": "cooldown", "value": 42}'
```

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

### Trigger Node-RED Flow from HA Automation

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Trigger a Node-RED switch node from a Home Assistant automation. Specify the output path and an optional message payload to send to the Node-RED node.

```yaml
automation:
  - alias: "Button Press → Node-RED"
    trigger:
      platform: state
      entity_id: input_button.my_button
    action:
      service: nodered.trigger
      target:
        entity_id: switch.nodered_my_switch_node
      data:
        output_path: "1"          # which output port to trigger (default "0")
        message:                  # arbitrary payload sent to the Node-RED node
          source: "ha_automation"
          timestamp: "{{ now().isoformat() }}"
```

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

### Send Dynamic Response to Sentence Trigger

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Send a dynamic voice response back to a pending sentence trigger. This must be called within the 'response_timeout' window defined in the 'nodered/sentence' command.

```javascript
{
  "id": 15,
  "type": "nodered/sentence_response",
  "response_id": 14,            // must match the id of the nodered/sentence subscription
  "response": "Temperature set to 22 degrees."
}
```

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

### Node-RED Select Value Change Event

Source: https://context7.com/zachowj/hass-node-red/llms.txt

This payload is sent to Node-RED when a user selects a new option from a bidirectional select entity in Home Assistant.

```javascript
// User selects "comfort" in HA → Node-RED receives:
// { "id": 60, "type": "event", "event": { "type": "value_change", "value": "comfort" } }
```

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

### Node-RED Number Input Value Change Event

Source: https://context7.com/zachowj/hass-node-red/llms.txt

This payload is sent to Node-RED when a user adjusts the value of a bidirectional number input entity in Home Assistant.

```javascript
// When user drags slider to 50, Node-RED receives:
// { "id": 50, "type": "event", "event": { "type": "value_change", "value": 50 } }
```

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

### Remove Node-RED Managed Device

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Removes a device managed by Node-RED from the Home Assistant device registry. Associated entities are dissociated but not deleted.

```javascript
{
  "id": 12,
  "type": "nodered/device/remove",
  "node_id": "my-node-red-device",  // must match the device identifier used at discovery
  "config": {}                       // optional metadata, default {}
}
```

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

### nodered/device/remove

Source: https://context7.com/zachowj/hass-node-red/llms.txt

Removes a Node-RED-managed device from the HA device registry. Before removal, all entities associated with the device are dissociated (not deleted) so they persist as unassigned entities.

```APIDOC
## WebSocket Command: `nodered/device/remove`

### Description
Removes a Node-RED-managed device from the HA device registry. Before removal, all entities associated with the device are dissociated (not deleted) so they persist as unassigned entities.

### Request Example
```json
{
  "id": 12,
  "type": "nodered/device/remove",
  "node_id": "my-node-red-device",  // must match the device identifier used at discovery
  "config": {}                       // optional metadata, default {}
}
```

### Response Example (Success)
```json
{ "id": 12, "type": "result", "success": true, "result": null }
```
```
Tokens:
Raw