Refine PLC algorithm documentation for lighting control and EtherCAT integration

- Updated the output structure for `struct_room_outs` to focus solely on light states, removing unnecessary status feedback fields.
- Simplified the control logic for lights 1 to 6, aligning with the new design approach for Option C.
- Added detailed instructions for declaring `EtherCAT_RelayFeedback` and `EtherCAT_Outputs` in the Global Variable List, enhancing clarity for integration with the EL2809 module.

This update improves the documentation's accuracy and usability for developers working on the home automation system.

codesys/src/NVL/README.md

@@ -0,0 +1,82 @@
+# Network Variables (NVL) for Node-RED
+
+This folder describes the **network variable** setup used for CODESYS ↔ Node-RED communication. The PLC sends light/boiler **status** to Node-RED and receives **commands** from Node-RED over UDP.
+
+## Overview
+
+| Direction | CODESYS name | Node-RED role | Content |
+|-----------|--------------|---------------|---------|
+| **PLC → Node-RED** | **NVL_Out** (Sender) | Receive UDP | Light states + boiler status |
+| **Node-RED → PLC** | **NVL_In** (Receiver) | Send UDP | Light commands + boiler commands |
+
+- **Protocol**: UDP  
+- **Typical interval**: 50 ms cyclic (configurable in CODESYS)  
+- **Payload**: Binary (struct layout) or see [Payload layout for Node-RED](nodered-payload.md) for parsing.
+
+---
+
+## 1. NVL_Out (PLC → Node-RED)
+
+**Purpose:** PLC sends current light outputs and boiler status so Node-RED can forward them to Home Assistant / MQTT.
+
+**Variables sent (in order):**
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `l_masterBedroom` | struct_room_outs | 12 BOOLs (l_1..l_6, l_1_status..l_6_status) |
+| `l_masterBathroom` | struct_room_outs | same |
+| `l_bedroom_1` .. `l_bedroom_2` | struct_room_outs | same |
+| `l_bathroom`, `l_guestWc`, `l_kitchen`, `l_pantry` | struct_room_outs | same |
+| `l_livingRoom`, `l_dinningRoom`, `l_entrance`, `l_hallway` | struct_room_outs | same |
+| `l_outVeranda`, `l_outFront`, `l_outBack`, `l_outSide` | struct_room_outs | same |
+| `boiler_status` | struct_boiler_status | state, relay_output, on_time_minutes, remaining_minutes, emergency_active, time_limit_reached, error_state, error_code |
+
+**In CODESYS:** Create an **NVL Sender** (Network Variable List), bind it to the **NVL_Out** structure (the same struct as in `GVL_NVL_placeholders.gvl` → `NVL_Out`). Set protocol to UDP, destination IP/port to your Node-RED host, task and interval (e.g. EtherCAT_Task, 50 ms).
+
+---
+
+## 2. NVL_In (Node-RED → PLC)
+
+**Purpose:** Node-RED sends commands (HA ON/OFF, Zigbee toggle edges, boiler on/off, etc.) so the PLC can drive lights and the boiler.
+
+**Variables received (in order):**
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `masterBedroom` .. `side` (15 rooms) | struct_room_cmds | ha_l1_on, ha_l1_off, ... ha_l6_on, ha_l6_off, zigbee_sw1..6, ha_all_on, ha_all_off |
+| `boiler` | struct_boiler_cmd | ha_on, ha_off, schedule_on, schedule_off, emergency_stop, max_on_time_minutes |
+
+**In CODESYS:** Create an **NVL Receiver**, bind it to the **NVL_In** structure. Set protocol to UDP, listen port, task and interval. The PLC will overwrite `NVL_In` with received data each cycle.
+
+**In Node-RED:** Send one UDP packet per update (or cyclic) with the same binary layout as `NVL_In` so CODESYS can unpack it into the receiver struct.
+
+---
+
+## 3. CODESYS configuration steps
+
+1. **Add NVL Sender**  
+   - Device tree → Add Object → Network Variable List (Sender).  
+   - Set protocol to **UDP**, destination IP = Node-RED host, port = e.g. **5555** (receive port on Node-RED).  
+   - Add variables: add the **entire NVL_Out** struct (or add each member; see CODESYS help).  
+   - Set task (e.g. EtherCAT_Task) and interval (e.g. T#50ms).
+
+2. **Add NVL Receiver**  
+   - Add Object → Network Variable List (Receiver).  
+   - Set protocol to **UDP**, listen port = e.g. **5556**.  
+   - Add variables: add the **entire NVL_In** struct.  
+   - Set task and interval.
+
+3. **Bind to GVL**  
+   - Either the NVL Sender/Receiver **are** the GVL variables (you map the NVL to the symbols `NVL_Out` and `NVL_In`), or you copy NVL → GVL in the program. Typically you bind the NVL list to a GVL so that `NVL_Out` and `NVL_In` in your code are the same memory the NVL driver sends/receives.
+
+4. **Ports and IP**  
+   - Fill in your PLC IP and Node-RED IP. Node-RED **receives** on the port you set as “destination port” in the NVL Sender. Node-RED **sends** to the PLC IP and the port you set as “listen port” in the NVL Receiver.
+
+---
+
+## 4. Node-RED usage
+
+- **Receive (PLC → Node-RED):** Use a **UDP in** node listening on the port configured in the CODESYS NVL Sender (e.g. 5555). The payload is binary; see [nodered-payload.md](nodered-payload.md) for struct layout and how to parse it to JSON for MQTT/HA.
+- **Send (Node-RED → PLC):** Use a **UDP out** node targeting the PLC IP and the NVL Receiver port (e.g. 5556). Build the payload buffer from your command (e.g. from MQTT/HA) using the same layout as [nodered-payload.md](nodered-payload.md).
+
+See **nodered-payload.md** in this folder for byte layout and example parsing/building.