nearxos/kkelomatic_home
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update PLC algorithm documentation with new naming conventions and structure

Browse Source 
- 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.
This commit is contained in:
nearxos
2026-02-07 22:31:39 +02:00
parent 1b72e15980
commit 86ed249e4c
1 changed files with 128 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

237
docs/codesys/plc-algorithm-design.md
View File

@@ -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.