From 86ed249e4cd249222ba89496a787ef83839bc187 Mon Sep 17 00:00:00 2001 From: nearxos Date: Sat, 7 Feb 2026 22:31:39 +0200 Subject: [PATCH] Update PLC algorithm documentation with new naming conventions and structure - Introduced new naming conventions for data types and function blocks to align with the redesign - Updated references in the documentation to reflect changes from `fb_switch` to `fb_room` and `fb_lightControl` to `fb_light` - Enhanced clarity in the mapping of existing to new names for better understanding of the redesign This update improves consistency and readability in the documentation for future development. --- docs/codesys/plc-algorithm-design.md | 237 +++++++++++++++------------ 1 file changed, 128 insertions(+), 109 deletions(-) diff --git a/docs/codesys/plc-algorithm-design.md b/docs/codesys/plc-algorithm-design.md index a0d9d19..7f39b63 100644 --- a/docs/codesys/plc-algorithm-design.md +++ b/docs/codesys/plc-algorithm-design.md @@ -6,6 +6,25 @@ This document defines the PLC algorithms for the home automation system: 1. **Lighting Control** - Improved logic with command-based control for Home Assistant and toggle-based for Zigbee switches 2. **Water Boiler Control** - Simple ON/OFF with safety features (time limit, emergency stop) +> **Naming convention**: New types, FBs, program, and NVLs use **different names** (no suffix) so the +> redesign can run alongside the existing project. Existing names (`struct_switches`, `fb_switch`, `PLC_PRG`, etc.) are left unchanged. + +### Name Mapping (existing → new, no suffix) + +| Existing name (do not touch) | New name | Kind | +|------------------------------|----------|------| +| `struct_switches` | `struct_room_cmds` | DUT (type) | +| `struct_lights` | `struct_room_outs` | DUT (type) | +| `fb_toogleButton` | `fb_light` | Function Block | +| `fb_switch` | `fb_room` | Function Block | +| — (new) | `fb_boiler` | Function Block | +| — (new) | `struct_boiler_cmd` | DUT (type) | +| — (new) | `struct_boiler_status` | DUT (type) | +| `PLC_PRG` | `PLC_App` | Program | +| `Lights` | (merged into `PLC_App`) | Program | +| `NVL_Sender` | `NVL_Out` | NVL | +| `NVL_Receiver` | `NVL_In` | NVL | + ## System Architecture ``` @@ -14,16 +33,16 @@ This document defines the PLC algorithms for the home automation system: ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ -│ │ NVL_Receiver │ │ MainTask │ │ NVL_Sender │ │ +│ │ NVL_In │ │ MainTask │ │ NVL_Out │ │ │ │ (from Node-RED)│ │ (4ms cycle) │ │ (to Node-RED) │ │ │ └────────┬────────┘ └────────┬────────┘ └──────────┬──────────┘ │ │ │ │ │ │ │ ▼ ▼ ▲ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ -│ │ PLC_PRG │ │ +│ │ PLC_App │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ -│ │ │ Lights │ │ Boiler │ │ Safety_Monitor │ │ │ -│ │ │ Program │ │ Program │ │ (future) │ │ │ +│ │ │ Lights │ │ Boiler │ │ Safety_Monitor │ │ │ +│ │ │ (section) │ │ (section) │ │ (future) │ │ │ │ │ └──────┬──────┘ └──────┬──────┘ └─────────────────────────┘ │ │ │ └─────────┼────────────────┼──────────────────────────────────────┘ │ │ │ │ │ @@ -75,7 +94,7 @@ So: you don’t *need* 6 predefined; you need a *maximum* per room. Organizing b ## Part 1: Lighting Control Algorithm -**Alignment**: This section follows the structures and logic from **`docs/redesign/fb_switch-redesign-recommendation.md`**: flat `struct_switches` / `struct_lights`, `fb_lightControl` with HA ON/OFF + Zigbee toggle only, and `fb_switch` applying global commands by overwriting outputs. +**Alignment**: This section follows the structures and logic from **`docs/redesign/fb_switch-redesign-recommendation.md`**: flat `struct_room_cmds` / `struct_room_outs`, `fb_light` with HA ON/OFF + Zigbee toggle only, and `fb_room` applying global commands by overwriting outputs. ### 1.1 Design Goals @@ -86,10 +105,10 @@ So: you don’t *need* 6 predefined; you need a *maximum* per room. Organizing b ### 1.2 Data Structures (per Redesign Recommendation) -#### Input: struct_switches (flat, for Node-RED/JSON compatibility) +#### Input: struct_room_cmds (flat, for Node-RED/JSON compatibility) ```iec -TYPE struct_switches : +TYPE struct_room_cmds : STRUCT // Home Assistant Commands (set/reset) ha_l1_on: BOOL; // HA command: Light 1 ON @@ -120,10 +139,10 @@ END_STRUCT END_TYPE ``` -#### Output: struct_lights (flat, control + status feedback) +#### Output: struct_room_outs (flat, control + status feedback) ```iec -TYPE struct_lights : +TYPE struct_room_outs : STRUCT l_1: BOOL; // Light 1 control output l_2: BOOL; // Light 2 control output @@ -143,12 +162,12 @@ END_STRUCT END_TYPE ``` -### 1.3 Function Block: fb_lightControl (per Redesign) +### 1.3 Function Block: fb_light (per Redesign) Individual light control: HA ON/OFF + Zigbee toggle only. No all_on/all_off inside this FB. ```iec -FUNCTION_BLOCK fb_lightControl +FUNCTION_BLOCK fb_light VAR_INPUT // Home Assistant Commands ha_on: BOOL; // HA command: Turn ON @@ -179,7 +198,7 @@ END_VAR ```iec // ===================================================== -// fb_lightControl - Implementation (per redesign) +// fb_light - Implementation (per redesign) // ===================================================== // Priority (highest to lowest): // 1. HA OFF command - Always turns light OFF @@ -209,26 +228,26 @@ light_output := light_state; light_status := relay_status; ``` -### 1.4 Function Block: fb_switch (per Redesign) +### 1.4 Function Block: fb_room (per Redesign) -Room-level block: 6× fb_lightControl; global commands applied by overwriting outputs. +Room-level block: 6× fb_light; global commands applied by overwriting outputs. ```iec -FUNCTION_BLOCK fb_switch +FUNCTION_BLOCK fb_room VAR_INPUT - switches: struct_switches; - relay_status: struct_lights; // Read from EtherCAT outputs (actual relay states) + switches: struct_room_cmds; + relay_status: struct_room_outs; // Read from EtherCAT outputs (actual relay states) END_VAR VAR_OUTPUT - lights: struct_lights; + lights: struct_room_outs; END_VAR VAR - l1: fb_lightControl; - l2: fb_lightControl; - l3: fb_lightControl; - l4: fb_lightControl; - l5: fb_lightControl; - l6: fb_lightControl; + l1: fb_light; + l2: fb_light; + l3: fb_light; + l4: fb_light; + l5: fb_light; + l6: fb_light; END_VAR ``` @@ -236,7 +255,7 @@ END_VAR ```iec // ===================================================== -// fb_switch - Implementation (per redesign) +// fb_room - Implementation (per redesign) // ===================================================== // Light 1 Control @@ -334,7 +353,7 @@ Based on your requirements: #### Boiler Commands (from Node-RED/Home Assistant) ```iec -TYPE struct_boiler_commands : +TYPE struct_boiler_cmd : STRUCT // Control Commands ha_on: BOOL; // Home Assistant: Turn ON @@ -375,12 +394,12 @@ END_STRUCT END_TYPE ``` -### 2.3 Function Block: fb_waterBoiler +### 2.3 Function Block: fb_boiler Simple ON/OFF boiler control with time limit and emergency stop. ```iec -FUNCTION_BLOCK fb_waterBoiler +FUNCTION_BLOCK fb_boiler VAR_INPUT // Control Commands ha_on: BOOL; // Home Assistant ON command @@ -434,7 +453,7 @@ END_VAR ```iec // ===================================================== -// fb_waterBoiler - Implementation +// fb_boiler - Implementation // ===================================================== // Priority (highest to lowest): // 1. Emergency Stop - Immediate shutdown @@ -575,36 +594,36 @@ state := internal_state; ## Part 3: Main Program Integration -### 3.1 PLC_PRG Structure +### 3.1 PLC_App structure ```iec -PROGRAM PLC_PRG +PROGRAM PLC_App VAR // ===================================================== // LIGHTING CONTROL // ===================================================== - // Room instances (fb_switch per redesign) - masterBedroom: fb_switch; - masterBathroom: fb_switch; - bedroom_1: fb_switch; - bedroom_2: fb_switch; - bathroom: fb_switch; - guest_wc: fb_switch; - kitchen: fb_switch; - pantry: fb_switch; - livingRoom: fb_switch; - diningRoom: fb_switch; - entrance: fb_switch; - hallway: fb_switch; - veranda: fb_switch; - front: fb_switch; - back: fb_switch; - side: fb_switch; + // Room instances (fb_room) + masterBedroom: fb_room; + masterBathroom: fb_room; + bedroom_1: fb_room; + bedroom_2: fb_room; + bathroom: fb_room; + guest_wc: fb_room; + kitchen: fb_room; + pantry: fb_room; + livingRoom: fb_room; + diningRoom: fb_room; + entrance: fb_room; + hallway: fb_room; + veranda: fb_room; + front: fb_room; + back: fb_room; + side: fb_room; // ===================================================== // WATER BOILER CONTROL // ===================================================== - waterBoiler: fb_waterBoiler; + boiler: fb_boiler; // ===================================================== // GLOBAL COMMANDS @@ -618,19 +637,19 @@ END_VAR ```iec // ===================================================== -// PLC_PRG - Main Program Implementation +// PLC_App - Main Program Implementation // ===================================================== // ===================================================== // SECTION 1: LIGHTING CONTROL // ===================================================== -// Master Bedroom (fb_switch: switches + relay_status in, lights out) +// Master Bedroom (fb_room: switches + relay_status in, lights out) masterBedroom( - switches := NVL_Receiver.masterBedroom, + switches := NVL_In.masterBedroom, relay_status := EtherCAT_RelayFeedback.masterBedroom // Actual relay states from I/O ); -NVL_Sender.l_masterBedroom := masterBedroom.lights; +NVL_Out.l_masterBedroom := masterBedroom.lights; EtherCAT_Outputs.masterBedroom_l1 := masterBedroom.lights.l_1; EtherCAT_Outputs.masterBedroom_l2 := masterBedroom.lights.l_2; // ... l_3..l_6 and repeat for all rooms @@ -639,28 +658,28 @@ EtherCAT_Outputs.masterBedroom_l2 := masterBedroom.lights.l_2; // SECTION 2: WATER BOILER CONTROL // ===================================================== -waterBoiler( - ha_on := NVL_Receiver.boiler.ha_on, - ha_off := NVL_Receiver.boiler.ha_off, - schedule_on := NVL_Receiver.boiler.schedule_on, - schedule_off := NVL_Receiver.boiler.schedule_off, - emergency_stop := NVL_Receiver.boiler.emergency_stop - OR DI_Emergency_Stop, // Physical button OR remote +boiler( + ha_on := NVL_In.boiler.ha_on, + ha_off := NVL_In.boiler.ha_off, + schedule_on := NVL_In.boiler.schedule_on, + schedule_off := NVL_In.boiler.schedule_off, + emergency_stop := NVL_In.boiler.emergency_stop + OR DI_Emergency_Stop, // Physical button OR remote max_on_time := T#8H ); // Map outputs -EtherCAT_Outputs.boiler_relay := waterBoiler.relay_control; +EtherCAT_Outputs.boiler_relay := boiler.relay_control; // Status to Node-RED -NVL_Sender.boiler_status.state := waterBoiler.state; -NVL_Sender.boiler_status.relay_output := waterBoiler.relay_control; -NVL_Sender.boiler_status.on_time_minutes := DINT_TO_INT(waterBoiler.on_time_seconds / 60); -NVL_Sender.boiler_status.remaining_minutes := DINT_TO_INT(waterBoiler.remaining_seconds / 60); -NVL_Sender.boiler_status.emergency_active := waterBoiler.emergency_active; -NVL_Sender.boiler_status.time_limit_reached := waterBoiler.time_limit_reached; -NVL_Sender.boiler_status.error_state := waterBoiler.error_state; -NVL_Sender.boiler_status.error_code := waterBoiler.error_code; +NVL_Out.boiler_status.state := boiler.state; +NVL_Out.boiler_status.relay_output := boiler.relay_control; +NVL_Out.boiler_status.on_time_minutes := DINT_TO_INT(boiler.on_time_seconds / 60); +NVL_Out.boiler_status.remaining_minutes := DINT_TO_INT(boiler.remaining_seconds / 60); +NVL_Out.boiler_status.emergency_active := boiler.emergency_active; +NVL_Out.boiler_status.time_limit_reached := boiler.time_limit_reached; +NVL_Out.boiler_status.error_state := boiler.error_state; +NVL_Out.boiler_status.error_code := boiler.error_code; ``` --- @@ -685,57 +704,57 @@ NVL_Sender.boiler_status.error_code := waterBoiler.error_code; ## Part 5: Network Variables -### 5.1 NVL_Sender (PLC → Node-RED) +### 5.1 NVL_Out (PLC → Node-RED) ```iec VAR_GLOBAL - // Lighting status (struct_lights per room, per redesign) - l_masterBedroom: struct_lights; - l_masterBathroom: struct_lights; - l_bedroom_1: struct_lights; - l_bedroom_2: struct_lights; - l_bathroom: struct_lights; - l_guestWc: struct_lights; - l_kitchen: struct_lights; - l_pantry: struct_lights; - l_livingRoom: struct_lights; - l_dinningRoom: struct_lights; - l_entrance: struct_lights; - l_hallway: struct_lights; - l_outVeranda: struct_lights; - l_outFront: struct_lights; - l_outBack: struct_lights; - l_outSide: struct_lights; + // Lighting status (struct_room_outs per room) + l_masterBedroom: struct_room_outs; + l_masterBathroom: struct_room_outs; + l_bedroom_1: struct_room_outs; + l_bedroom_2: struct_room_outs; + l_bathroom: struct_room_outs; + l_guestWc: struct_room_outs; + l_kitchen: struct_room_outs; + l_pantry: struct_room_outs; + l_livingRoom: struct_room_outs; + l_dinningRoom: struct_room_outs; + l_entrance: struct_room_outs; + l_hallway: struct_room_outs; + l_outVeranda: struct_room_outs; + l_outFront: struct_room_outs; + l_outBack: struct_room_outs; + l_outSide: struct_room_outs; - // Boiler status (NEW) + // Boiler status boiler_status: struct_boiler_status; END_VAR ``` -### 5.2 NVL_Receiver (Node-RED → PLC) +### 5.2 NVL_In (Node-RED → PLC) ```iec VAR_GLOBAL - // Lighting commands (struct_switches per room, per redesign) - masterBedroom: struct_switches; - masterBathroom: struct_switches; - bedroom_1: struct_switches; - bedroom_2: struct_switches; - bathroom: struct_switches; - guestWc: struct_switches; - kitchen: struct_switches; - pantry: struct_switches; - livingRoom: struct_switches; - dinningRoom: struct_switches; - entrance: struct_switches; - hallway: struct_switches; - outVeranda: struct_switches; - outFront: struct_switches; - outBack: struct_switches; - outSide: struct_switches; + // Lighting commands (struct_room_cmds per room) + masterBedroom: struct_room_cmds; + masterBathroom: struct_room_cmds; + bedroom_1: struct_room_cmds; + bedroom_2: struct_room_cmds; + bathroom: struct_room_cmds; + guestWc: struct_room_cmds; + kitchen: struct_room_cmds; + pantry: struct_room_cmds; + livingRoom: struct_room_cmds; + dinningRoom: struct_room_cmds; + entrance: struct_room_cmds; + hallway: struct_room_cmds; + outVeranda: struct_room_cmds; + outFront: struct_room_cmds; + outBack: struct_room_cmds; + outSide: struct_room_cmds; - // Boiler commands (NEW) - boiler: struct_boiler_commands; + // Boiler commands + boiler: struct_boiler_cmd; END_VAR ``` @@ -784,7 +803,7 @@ END_VAR ## Implementation Notes -1. **Redesign alignment**: Lighting control (Part 1) follows **`docs/redesign/fb_switch-redesign-recommendation.md`**: flat `struct_switches` / `struct_lights`, `fb_lightControl` (HA ON/OFF + Zigbee toggle, no all_on/all_off), `fb_switch` with global commands applied by overwriting outputs. Node-RED should send `ha_l1_on`/`ha_l1_off` and `zigbee_sw1` (edge) per the redesign. +1. **Redesign alignment**: Lighting control (Part 1) follows **`docs/redesign/fb_switch-redesign-recommendation.md`**: flat `struct_room_cmds` / `struct_room_outs`, `fb_light` (HA ON/OFF + Zigbee toggle), `fb_room` with global commands applied by overwriting outputs. Node-RED should send `ha_l1_on`/`ha_l1_off` and `zigbee_sw1` (edge) per the redesign. 2. **Backward Compatibility**: The new lighting structure replaces the old toggle-only logic; Node-RED and HA need to be updated to the new command format.