codesys-home-automation/docs/integration-home-assistant-nodered.md

CODESYS ↔ Node-RED ↔ Home Assistant integration

Documented: 2026-05-24
Sources: Live config on root@10.77.50.5 (/srv/docker-volumes/…) and local codesys-tree/ mirror.

CODESYS Phase 1 project (copy, does not overwrite original):
C:\codesys-projects\Codesys_Home_Automation\Home_Automation_Boiler_Phase1\Home_Automation.project
Original remains: C:\codesys-projects\Codesys_Home_Automation\Home_Automation.project

This stack runs home automation logic on a CODESYS PLC (EtherCAT relays, room function blocks). Node-RED is the protocol bridge: it maps Home Assistant and Zigbee events into PLC Network Variables (NVL) over UDP, and mirrors PLC relay state back into HA. Home Assistant is the UI, automations, and helper entities—not the real-time I/O path to the PLC.

---

Infrastructure overview

Role	Host / container	VLAN70 IP	Notes
Docker host (mgmt)	Proxmox CT, SSH root@10.77.50.5	10.77.50.5	Runs home_infra compose; macvlan services live on VLAN70
Mosquitto	mqtt	10.77.70.6	Port 1883, auth required (allow_anonymous false)
Home Assistant	homeassistant	10.77.70.11	Config: /srv/docker-volumes/config/homeassistant/config
Node-RED	nodered	10.77.70.12	Data: /srv/docker-volumes/config/nodered/data
Zigbee2MQTT	zigbee2mqtt	10.77.70.13	MQTT mqtt://10.77.70.6, base topic zigbee2mqtt
CODESYS PLC	(device, not in this compose)	10.77.70.5	NVL UDP port 1202

Compose file: /srv/docker-volumes/stacks/home_infra/docker-compose.yml.

flowchart LR
  subgraph HA["Home Assistant 10.77.70.11"]
    UI[Dashboard / automations]
    Helpers[input_boolean helpers]
  end

  subgraph NR["Node-RED 10.77.70.12"]
    HA2NVL[HA to NVL]
    Z2NVL[Zigbee to NVL]
    NVL2HA[NVL to HA Sync]
    NVLSend[nvl-send]
    NVLRecv[nvl-receive]
  end

  subgraph MQTT["Mosquitto 10.77.70.6"]
  end

  subgraph Z2M["Zigbee2MQTT 10.77.70.13"]
  end

  subgraph PLC["CODESYS PLC 10.77.70.5"]
    RecvGVL[NVL_Receiver]
    SendGVL[NVL_Sender]
    FB[fb_light / fb_room / fb_boiler]
    IO[EtherCAT K1–K4]
  end

  UI --> Helpers
  Helpers <-->|WebSocket API| HA2NVL
  Helpers <-->|WebSocket API| NVL2HA
  Z2M --> MQTT
  MQTT --> NR
  Z2M --> Z2NVL
  HA2NVL --> NVLSend
  Z2NVL --> NVLSend
  NVLSend -->|UDP :1202| RecvGVL
  SendGVL -->|UDP :1202| NVLRecv
  NVLRecv --> NVL2HA
  RecvGVL --> FB --> IO
  IO --> SendGVL

---

CODESYS side (this repository)

Network Variable Lists (UDP)

GVL	Direction (from PLC view)	Node-RED node	Purpose
NVL_Receiver	Inbound to PLC	nvl-send → udp out	Commands: HA, Zigbee, schedules
NVL_Sender	Outbound from PLC	udp in → nvl-receive	Status: relay commands + feedback

NVL_Receiver.st is documented as received via UDP. Node-RED sends to 10.77.70.5:1202; Node-RED listens on 1202 for PLC telegrams.

Key structures

struct_room_cmds (in NVL_Receiver as cmd_* rooms)—one instance per room, e.g. cmd_livingRoom:

Field group	Members	Used by
HA pulses	ha_l1_on … ha_l6_on, ha_l1_off … ha_l6_off	fb_light via R_TRIG (rising edge only)
Zigbee pulses	zigbee_sw1 … zigbee_sw6	fb_light toggle on edge
Room-wide	ha_all_on, ha_all_off	fb_room: R_TRIG + all_on_latch (rising edge only; see below)

struct_room_outs (in NVL_Sender as light_* rooms)—per-room outputs:

Field	Meaning
l_1 … l_6	Commanded relay state (written to NVL before EtherCAT mapping)
l_1_status … l_6_status	Actual relay feedback

Physical mapping: see codesys-tree/_io.md (EtherCAT %QX* → Application.NVL_Sender.light_*).

Legacy / parallel structs in NVL_Sender / NVL_Receiver: struct_lights (l_* rooms) and struct_switches (sw_*, all_on/all_off)—still present in GVLs; the active redesign path for rooms is cmd_* + light_* + fb_light.

Boiler (Phase 1 on PLC): NVL_Receiver.boiler_cmd → fb_boiler in Boiler_PRG; status on NVL_Sender.boiler_status; coil on boiler_status.relay_output (%QX5.4 on K4 ch 13) — not light_shower.l_6. Node-RED must use boiler_cmd / boiler_status (Phase 2); legacy cmd_shower.ha_l6_* no longer drives the heater on the PLC.

Logic priority (fb_light)

1. HA OFF (ha_off / ha_lN_off pulse)
2. HA ON (ha_on / ha_lN_on pulse)
3. Zigbee toggle (zigbee_sw pulse)
4. Hold state

Outputs feed NVL_Sender; EtherCAT maps those BOOLs to contactors.

Room-wide ALL ON / ALL OFF (fb_room)

Node-RED sends ha_all_on / ha_all_off as short rising-edge pulses (PLC Troubleshoot dashboard, same as zigbee_swN). They must not be treated as level-sensitive BOOLs.

Previous behaviour (bug): IF switches.ha_all_on THEN … forced all outputs on only while the NVL bit stayed TRUE. When Node-RED cleared the pulse (~120 ms–1 s), outputs fell back to per-light fb_light state (usually off) → “flash then all off”.

Current behaviour (fb_room.st):

1. R_TRIG on ha_all_on / ha_all_off.
2. Rising edge on ha_all_on sets internal all_on_latch := TRUE (all six outputs forced on each scan until released).
3. Rising edge on ha_all_off clears all_on_latch; per-light fb_light outputs apply again.

Node-RED alignment: room-config-lib.js uses sparse buildNvlSendPayload (only TRUE bits merged into nvl-send) and does not send a follow-up ha_all_on := FALSE frame for ALL ON. After deploying this PLC change, download the application to the controller.

---

Node-RED side

Main tabs (flows)

Tab	Role
House Lights (PLC)	Production path: NVL UDP, HA sync, Zigbee dispatch, room-config.js
Zigbee	MQTT subscription to zigbee2mqtt/# (switches; some direct light control)
Water heater	Boiler HA entities, timers, safety shutoff, bridge to cmd_shower
PLC Troubleshoot (cmd_*)	Dashboard UI to pulse any cmd_* field for testing
Flow 7	Disabled (legacy)

NVL pipeline (House Lights tab)

1. Inputs accumulate into flow.nvlInState ({ rooms: {}, boiler: {} }):

   • HA to NVL — server-state-changed on helpers matching plc_*, living_room, etc.; sets ha_lN_on or ha_lN_off for the mapped cmd_* room.
   • Zigbee to NVL — MQTT actions → zigbee_swN pulse on the bound cmd_* room.
   • Zigbee switch dispatch — routes each button to PLC, direct Zigbee2MQTT light, or HA switch.* per switchBindings in room-config.js.

2. STATE TO NVL — calls roomConfigLib.buildNvlSendPayload() with all roomNames from config.

3. nvl-send — serializes GVL matching NVL_Receiver (see node definition in flows; aligns with NVL_Receiver.st in the tree).

4. udp out → 10.77.70.5:1202.

5. Return path: udp in :1202 → nvl-receive (parses NVL_Sender) → NVL to HA Sync → Home Assistant api-call-service (turn_on / turn_off on mapped helpers).

6. Edge clearing — after ~120 ms, Clear NVL edges reset zigbee_sw* / ha_lN_* pulse bits via buildNvlClearPayload (explicit FALSE merge only for cleared keys). ha_all_on / ha_all_off are not cleared over UDP (one rising-edge frame only); the PLC latch in fb_room holds the room on until ha_all_off.

Configuration files (single source of truth)

File	Purpose
/data/room-config.js	Room list, plcRoomToCmd, lightEntityMap, switchBindings, Zigbee deviceIdToName
/data/room-config-lib.js	buildNvlSendPayload, HA slug/entity helpers, Zigbee action parsing, switch dispatch
settings.js	Loads room-config.js at startup; exposes global.roomConfig / global.roomConfigLib

roomNames in room-config.js must match CODESYS cmd_* variables in NVL_Receiver.st.

Example mapping entry:

{ room: 'light_livingRoom', light: 1, cmdRoom: 'cmd_livingRoom', entityId: 'input_boolean.living_room_new', name: 'Living Room Main' }

• room — key in NVL_Sender payload (light_*).
• cmdRoom — key in NVL_Receiver payload (cmd_*).
• entityId — HA helper updated on PLC state changes.

---

Home Assistant side

Core config

• configuration.yaml — default_config, reverse proxy trust for 10.77.70.1 / 10.77.10.1, packages.
• MQTT integration — broker 10.77.70.6:1883 (credentials in .storage, not in git).
• Node-RED custom integration (custom_components/nodered) — links HA events to Node-RED flows.
• Public URL: ha.paraskeva.net (via OPNsense Caddy).

PLC light helpers

Package packages/lights_by_room.yaml defines input_boolean helpers; naming convention <room>_<light_num>. The active House Lights flow also uses helpers like input_boolean.living_room_new and auto-provisioned input_boolean.plc_<room>_lN from lightEntityMap (via Create HA helper nodes on boot).

Helpers are mirrors of PLC state, not the authority for relay coils—the PLC is.

Echo suppression

When Node-RED writes a helper from NVL→HA, it sets a short haEchoSuppress window so the resulting HA state-change event does not loop back through HA→NVL.

---

Zigbee path

1. Switches publish to zigbee2mqtt/<friendly_name>/action (and related topics).
2. Node-RED zigbee2mqtt-in nodes receive events.
3. Zigbee switch dispatch looks up switchBindings[device][button]:
   • PLC: { room: 'cmd_hallway', light: 2 } → zigbee_sw2 pulse.
   • Direct Z2M light: { z2m: { device: 'Master Bedroom Spots', command: 'state', payload: 'toggle' } }.
   • HA switch: { ha: { entity_id: 'switch.xxx', service: 'toggle' } }.

Coordinator: SLZB-06 (10.77.70.60) — separate from the PLC path.

---

Water heater / boiler

Layer	Mechanism
HA	Water_boiler entities, timer remaining sensor, automations in Water heater tab
Node-RED	Boiler → boiler_cmd pulse → NVL; feedback from boiler_status → input_boolean.water_boiler
PLC	fb_boiler / struct_boiler_cmd (full boiler FB exists; shower light channel used as integration shortcut)
Safety	Startup Safety Check turns boiler off if PLC reports ON; 3-Hour Safety Timer in Node-RED

Boiler command fields in struct_boiler_cmd (ha_on, ha_off, schedule_*, emergency_stop, max_on_time_minutes) are also packed in legacy Build NVL_In buffer logic for older flows; the current Water heater tab primarily uses the cmd_shower / light_shower.l_6 bridge.

---

MQTT vs UDP (when each is used)

Transport	Between	Data
UDP :1202	Node-RED ↔ PLC	Binary NVL (GVL mirror)—time-critical I/O
MQTT	Zigbee2MQTT ↔ Node-RED; HA ↔ MQTT devices	Zigbee events; non-PLC devices; optional HA entities
HA WebSocket	Node-RED ↔ Home Assistant	Helper state, services, entity registry

The PLC does not speak MQTT in this architecture.

---

Adding a new PLC-controlled light

1. CODESYS: Ensure cmd_<room> and light_<room> exist in NVL_Receiver / NVL_Sender; wire fb_light / fb_room; map NVL_Sender.light_* .l_N in device IO (_io.md / write_io_mapping).
2. Node-RED: Add entry to lightEntityMap and, if needed, switchBindings in room-config.js; confirm cmd_<room> is in roomNames.
3. Home Assistant: Deploy helper (manual YAML package or let Node-RED Create HA helper on boot).
4. Test: Use PLC Troubleshoot tab to pulse ha_l1_on, then confirm NVL→HA sync updates the helper.

---

Operational notes

• Re-sync local tree: After CODESYS changes on the Windows VM, run read_project_inventory and refresh codesys-tree/ (see codesys-tree/README.md).
• Node-RED backups: Multiple flows.json.bak-* files exist under /data; production tab is House Lights (PLC).
• Known IO issue: light_livingRoom.l_1 is mapped to two EtherCAT outputs (K2 ch 10 and K4 ch 16)—see _io.md.
• Secrets: MQTT and HA tokens live in Docker volumes / HA .storage; do not commit them to this repo.

---

Quick reference: variable name alignment

Concept	CODESYS (NVL_Receiver)	CODESYS (NVL_Sender)	Node-RED nvl-send / nvl-receive
Living room commands	cmd_livingRoom : struct_room_cmds	—	payload.cmd_livingRoom
Living room outputs	—	light_livingRoom : struct_room_outs	payload.light_livingRoom
Hallway switch → PLC	cmd_hallway.zigbee_sw*	—	Via switchBindings
HA toggle living room 1	cmd_livingRoom.ha_l1_on/off	—	From input_boolean.living_room_new

---

Related files in this repo

Path	Content
codesys-tree/Device/.../NVL_Receiver.st	Inbound GVL (commands)
codesys-tree/Device/.../NVL_Sender.st	Outbound GVL (status + coil image)
codesys-tree/Device/.../struct_room_cmds.st	HA/Zigbee command struct
codesys-tree/Device/.../struct_room_outs.st	Per-light outputs + status
codesys-tree/Device/.../fb_light.st	Single-light logic
codesys-tree/_io.md	EtherCAT ↔ NVL_Sender mapping