Home Assistant Integration

Node-RED running as a Home Assistant add-on is one of the most common deployments there is, and the flight recorder pairs naturally with it: incidents become HA notifications you see on your phone, counters you dashboard, and post-mortem files you browse over Samba. This page expands the shipped Home Assistant example into a full guide, plus tips and ideas.

Everything here uses the node-red-contrib-home-assistant-websocket palette (installed by default with the HA add-on) — the flight recorder itself needs no HA-specific code, which is deliberate: the palette's call service nodes already speak HA fluently, and our job is producing incidents worth delivering.

The shipped example

Import → Examples → node-red-contrib-flight-recorder → Home Assistant. Unlike the other examples it needs two setup steps, stated in its tab info:

1. Open each of the two call service nodes and pick your HA server in the Server dropdown (the add-on usually has one preconfigured entry).
2. Create a Counter helper in HA with entity id counter.flight_recorder_incidents (Settings → Devices & services → Helpers). Skippable if you only want notifications.

Deploy, and within ~15 seconds the simulated worker errors, the tap auto-dumps, and two things happen in HA: a persistent notification appears, and the counter ticks.

How the notification path works, since it's the template for your own variants: the report node's output carries the rendered report in msg.payload and the untouched incident at msg.report.source. The "build notification" function reads the incident — trigger, error message, source node, record count — and shapes a service-call payload:

const inc = msg.report.source;
msg.payload = {
    data: {
        title: '✈ Flight Recorder: ' + inc.trigger.toUpperCase() + ' incident',
        message: /* cause, source, record count, where the full report lives */,
        notification_id: 'flight_recorder_' + inc.storeId
    }
};
return msg;

The stable notification_id per recorder matters: a repeating fault updates one notification instead of stacking fifty.

Tips

Cooldown protects your notification panel. The example uses 60 seconds; for production taps feeding notifications, treat 30–60s as the floor. Every suppressed auto-dump still emits an incidentSuppressed event, so nothing is hidden — it just isn't delivered repeatedly.

Pair notifications with the file archive. Set the report node to message + file with directory /share/flight-recorder/reports and Raw JSON on. /share persists across add-on updates and is exposed by the Samba and SSH add-ons — so the notification tells you that it happened, and the HTML report (double-clicked from your PC over the network) tells you what happened. Include the path in the notification message and the workflow is one glance, one click.

Mind the eMMC. On a Yellow or similar flash-based host, keep retention enabled (the default 100 is fine; remember Raw JSON doubles the file count) and don't enable recorder persistence on high-traffic taps without reason — the write debounce is gentle, but sustained chatty flows mean regular writes. Summary capture mode is your friend for chatty scopes.

Phone notifications instead

Change the notification call service node's domain/service from persistent_notification/create to notify/mobile_app_<your_device> (the exact service name is under HA's Developer Tools → Actions), and adjust the function — mobile notifications take message/title at the top level of data, and support extras:

msg.payload = {
    data: {
        title: '✈ Flight Recorder',
        message: cause + ' — ' + s.recordCount + ' records on the tape',
        data: { tag: 'flight_recorder', channel: 'Node-RED', importance: 'high' }
    }
};

The tag plays the same role as notification_id — repeats replace rather than stack.

Ideas

Sketches rather than recipes — each is a small automation away:

• Escalation on the counter. An HA automation on counter.flight_recorder_incidents: above N within an hour, send a high-priority phone notification or flash a light. The counter turns individual incidents into a rate signal.
• A dashboard incident card. The counter plus a Markdown card makes a minimal "system health" tile; resetting the counter (service counter.reset) from the card gives you an acknowledge button.
• TTS announcements. Route the same build-notification output to a tts.speak service call for genuinely critical watermarks — "flight recorder: temperature watermark tripped."
• HA events instead of notifications. Fire a custom event (event service / fire_event) carrying the incident summary, and let HA automations decide what to do — decouples the recorder from any particular delivery.
• Status snapshot as a sensor. A scheduled query → small function → call service updating an input_text (or a template sensor via events) with "recording · 87/100 · 0 errors today" — recorder health visible on the dashboard without opening Node-RED.

If you build one of these into something polished, it's a natural candidate for a future example flow — see the Roadmap.