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 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) 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 ## 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) │ │ │ │ (from Node-RED)│ │ (4ms cycle) │ │ (to Node-RED) │ │
│ └────────┬────────┘ └────────┬────────┘ └──────────┬──────────┘ │ │ └────────┬────────┘ └────────┬────────┘ └──────────┬──────────┘ │
│ │ │ │ │ │ │ │ │ │
│ ▼ ▼ ▲ │ │ ▼ ▼ ▲ │
│ ┌─────────────────────────────────────────────────────────────────┐ │ │ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ PLC_PRG │ │ │ │ PLC_App │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │
│ │ │ Lights │ │ Boiler │ │ Safety_Monitor │ │ │ │ │ │ Lights │ │ Boiler │ │ Safety_Monitor │ │ │
│ │ │ Program │ │ Program │ │ (future) │ │ │ │ │ │ (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 ## 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 ### 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) ### 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 ```iec
TYPE struct_switches : TYPE struct_room_cmds :
STRUCT STRUCT
// Home Assistant Commands (set/reset) // Home Assistant Commands (set/reset)
ha_l1_on: BOOL; // HA command: Light 1 ON ha_l1_on: BOOL; // HA command: Light 1 ON
@@ -120,10 +139,10 @@ END_STRUCT
END_TYPE END_TYPE
``` ```
#### Output: struct_lights (flat, control + status feedback) #### Output: struct_room_outs (flat, control + status feedback)
```iec ```iec
TYPE struct_lights : TYPE struct_room_outs :
STRUCT STRUCT
l_1: BOOL; // Light 1 control output l_1: BOOL; // Light 1 control output
l_2: BOOL; // Light 2 control output l_2: BOOL; // Light 2 control output
@@ -143,12 +162,12 @@ END_STRUCT
END_TYPE 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. Individual light control: HA ON/OFF + Zigbee toggle only. No all_on/all_off inside this FB.
```iec ```iec
FUNCTION_BLOCK fb_lightControl FUNCTION_BLOCK fb_light
VAR_INPUT VAR_INPUT
// Home Assistant Commands // Home Assistant Commands
ha_on: BOOL; // HA command: Turn ON ha_on: BOOL; // HA command: Turn ON
@@ -179,7 +198,7 @@ END_VAR
```iec ```iec
// ===================================================== // =====================================================
// fb_lightControl - Implementation (per redesign) // fb_light - Implementation (per redesign)
// ===================================================== // =====================================================
// Priority (highest to lowest): // Priority (highest to lowest):
// 1. HA OFF command - Always turns light OFF // 1. HA OFF command - Always turns light OFF
@@ -209,26 +228,26 @@ light_output := light_state;
light_status := relay_status; 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 ```iec
FUNCTION_BLOCK fb_switch FUNCTION_BLOCK fb_room
VAR_INPUT VAR_INPUT
switches: struct_switches; switches: struct_room_cmds;
relay_status: struct_lights; // Read from EtherCAT outputs (actual relay states) relay_status: struct_room_outs; // Read from EtherCAT outputs (actual relay states)
END_VAR END_VAR
VAR_OUTPUT VAR_OUTPUT
lights: struct_lights; lights: struct_room_outs;
END_VAR END_VAR
VAR VAR
l1: fb_lightControl; l1: fb_light;
l2: fb_lightControl; l2: fb_light;
l3: fb_lightControl; l3: fb_light;
l4: fb_lightControl; l4: fb_light;
l5: fb_lightControl; l5: fb_light;
l6: fb_lightControl; l6: fb_light;
END_VAR END_VAR
``` ```
@@ -236,7 +255,7 @@ END_VAR
```iec ```iec
// ===================================================== // =====================================================
// fb_switch - Implementation (per redesign) // fb_room - Implementation (per redesign)
// ===================================================== // =====================================================
// Light 1 Control // Light 1 Control
@@ -334,7 +353,7 @@ Based on your requirements:
#### Boiler Commands (from Node-RED/Home Assistant) #### Boiler Commands (from Node-RED/Home Assistant)
```iec ```iec
TYPE struct_boiler_commands : TYPE struct_boiler_cmd :
STRUCT STRUCT
// Control Commands // Control Commands
ha_on: BOOL; // Home Assistant: Turn ON ha_on: BOOL; // Home Assistant: Turn ON
@@ -375,12 +394,12 @@ END_STRUCT
END_TYPE 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. Simple ON/OFF boiler control with time limit and emergency stop.
```iec ```iec
FUNCTION_BLOCK fb_waterBoiler FUNCTION_BLOCK fb_boiler
VAR_INPUT VAR_INPUT
// Control Commands // Control Commands
ha_on: BOOL; // Home Assistant ON command ha_on: BOOL; // Home Assistant ON command
@@ -434,7 +453,7 @@ END_VAR
```iec ```iec
// ===================================================== // =====================================================
// fb_waterBoiler - Implementation // fb_boiler - Implementation
// ===================================================== // =====================================================
// Priority (highest to lowest): // Priority (highest to lowest):
// 1. Emergency Stop - Immediate shutdown // 1. Emergency Stop - Immediate shutdown
@@ -575,36 +594,36 @@ state := internal_state;
## Part 3: Main Program Integration ## Part 3: Main Program Integration
### 3.1 PLC_PRG Structure ### 3.1 PLC_App structure
```iec ```iec
PROGRAM PLC_PRG PROGRAM PLC_App
VAR VAR
// ===================================================== // =====================================================
// LIGHTING CONTROL // LIGHTING CONTROL
// ===================================================== // =====================================================
// Room instances (fb_switch per redesign) // Room instances (fb_room)
masterBedroom: fb_switch; masterBedroom: fb_room;
masterBathroom: fb_switch; masterBathroom: fb_room;
bedroom_1: fb_switch; bedroom_1: fb_room;
bedroom_2: fb_switch; bedroom_2: fb_room;
bathroom: fb_switch; bathroom: fb_room;
guest_wc: fb_switch; guest_wc: fb_room;
kitchen: fb_switch; kitchen: fb_room;
pantry: fb_switch; pantry: fb_room;
livingRoom: fb_switch; livingRoom: fb_room;
diningRoom: fb_switch; diningRoom: fb_room;
entrance: fb_switch; entrance: fb_room;
hallway: fb_switch; hallway: fb_room;
veranda: fb_switch; veranda: fb_room;
front: fb_switch; front: fb_room;
back: fb_switch; back: fb_room;
side: fb_switch; side: fb_room;
// ===================================================== // =====================================================
// WATER BOILER CONTROL // WATER BOILER CONTROL
// ===================================================== // =====================================================
waterBoiler: fb_waterBoiler; boiler: fb_boiler;
// ===================================================== // =====================================================
// GLOBAL COMMANDS // GLOBAL COMMANDS
@@ -618,19 +637,19 @@ END_VAR
```iec ```iec
// ===================================================== // =====================================================
// PLC_PRG - Main Program Implementation // PLC_App - Main Program Implementation
// ===================================================== // =====================================================
// ===================================================== // =====================================================
// SECTION 1: LIGHTING CONTROL // 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( masterBedroom(
switches := NVL_Receiver.masterBedroom, switches := NVL_In.masterBedroom,
relay_status := EtherCAT_RelayFeedback.masterBedroom // Actual relay states from I/O 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_l1 := masterBedroom.lights.l_1;
EtherCAT_Outputs.masterBedroom_l2 := masterBedroom.lights.l_2; EtherCAT_Outputs.masterBedroom_l2 := masterBedroom.lights.l_2;
// ... l_3..l_6 and repeat for all rooms // ... 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 // SECTION 2: WATER BOILER CONTROL
// ===================================================== // =====================================================
waterBoiler( boiler(
ha_on := NVL_Receiver.boiler.ha_on, ha_on := NVL_In.boiler.ha_on,
ha_off := NVL_Receiver.boiler.ha_off, ha_off := NVL_In.boiler.ha_off,
schedule_on := NVL_Receiver.boiler.schedule_on, schedule_on := NVL_In.boiler.schedule_on,
schedule_off := NVL_Receiver.boiler.schedule_off, schedule_off := NVL_In.boiler.schedule_off,
emergency_stop := NVL_Receiver.boiler.emergency_stop emergency_stop := NVL_In.boiler.emergency_stop
OR DI_Emergency_Stop, // Physical button OR remote OR DI_Emergency_Stop, // Physical button OR remote
max_on_time := T#8H max_on_time := T#8H
); );
// Map outputs // Map outputs
EtherCAT_Outputs.boiler_relay := waterBoiler.relay_control; EtherCAT_Outputs.boiler_relay := boiler.relay_control;
// Status to Node-RED // Status to Node-RED
NVL_Sender.boiler_status.state := waterBoiler.state; NVL_Out.boiler_status.state := boiler.state;
NVL_Sender.boiler_status.relay_output := waterBoiler.relay_control; NVL_Out.boiler_status.relay_output := boiler.relay_control;
NVL_Sender.boiler_status.on_time_minutes := DINT_TO_INT(waterBoiler.on_time_seconds / 60); NVL_Out.boiler_status.on_time_minutes := DINT_TO_INT(boiler.on_time_seconds / 60);
NVL_Sender.boiler_status.remaining_minutes := DINT_TO_INT(waterBoiler.remaining_seconds / 60); NVL_Out.boiler_status.remaining_minutes := DINT_TO_INT(boiler.remaining_seconds / 60);
NVL_Sender.boiler_status.emergency_active := waterBoiler.emergency_active; NVL_Out.boiler_status.emergency_active := boiler.emergency_active;
NVL_Sender.boiler_status.time_limit_reached := waterBoiler.time_limit_reached; NVL_Out.boiler_status.time_limit_reached := boiler.time_limit_reached;
NVL_Sender.boiler_status.error_state := waterBoiler.error_state; NVL_Out.boiler_status.error_state := boiler.error_state;
NVL_Sender.boiler_status.error_code := waterBoiler.error_code; 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 ## Part 5: Network Variables
### 5.1 NVL_Sender (PLC → Node-RED) ### 5.1 NVL_Out (PLC → Node-RED)
```iec ```iec
VAR_GLOBAL VAR_GLOBAL
// Lighting status (struct_lights per room, per redesign) // Lighting status (struct_room_outs per room)
l_masterBedroom: struct_lights; l_masterBedroom: struct_room_outs;
l_masterBathroom: struct_lights; l_masterBathroom: struct_room_outs;
l_bedroom_1: struct_lights; l_bedroom_1: struct_room_outs;
l_bedroom_2: struct_lights; l_bedroom_2: struct_room_outs;
l_bathroom: struct_lights; l_bathroom: struct_room_outs;
l_guestWc: struct_lights; l_guestWc: struct_room_outs;
l_kitchen: struct_lights; l_kitchen: struct_room_outs;
l_pantry: struct_lights; l_pantry: struct_room_outs;
l_livingRoom: struct_lights; l_livingRoom: struct_room_outs;
l_dinningRoom: struct_lights; l_dinningRoom: struct_room_outs;
l_entrance: struct_lights; l_entrance: struct_room_outs;
l_hallway: struct_lights; l_hallway: struct_room_outs;
l_outVeranda: struct_lights; l_outVeranda: struct_room_outs;
l_outFront: struct_lights; l_outFront: struct_room_outs;
l_outBack: struct_lights; l_outBack: struct_room_outs;
l_outSide: struct_lights; l_outSide: struct_room_outs;
// Boiler status (NEW) // Boiler status
boiler_status: struct_boiler_status; boiler_status: struct_boiler_status;
END_VAR END_VAR
``` ```
### 5.2 NVL_Receiver (Node-RED → PLC) ### 5.2 NVL_In (Node-RED → PLC)
```iec ```iec
VAR_GLOBAL VAR_GLOBAL
// Lighting commands (struct_switches per room, per redesign) // Lighting commands (struct_room_cmds per room)
masterBedroom: struct_switches; masterBedroom: struct_room_cmds;
masterBathroom: struct_switches; masterBathroom: struct_room_cmds;
bedroom_1: struct_switches; bedroom_1: struct_room_cmds;
bedroom_2: struct_switches; bedroom_2: struct_room_cmds;
bathroom: struct_switches; bathroom: struct_room_cmds;
guestWc: struct_switches; guestWc: struct_room_cmds;
kitchen: struct_switches; kitchen: struct_room_cmds;
pantry: struct_switches; pantry: struct_room_cmds;
livingRoom: struct_switches; livingRoom: struct_room_cmds;
dinningRoom: struct_switches; dinningRoom: struct_room_cmds;
entrance: struct_switches; entrance: struct_room_cmds;
hallway: struct_switches; hallway: struct_room_cmds;
outVeranda: struct_switches; outVeranda: struct_room_cmds;
outFront: struct_switches; outFront: struct_room_cmds;
outBack: struct_switches; outBack: struct_room_cmds;
outSide: struct_switches; outSide: struct_room_cmds;
// Boiler commands (NEW) // Boiler commands
boiler: struct_boiler_commands; boiler: struct_boiler_cmd;
END_VAR END_VAR
``` ```
@@ -784,7 +803,7 @@ END_VAR
## Implementation Notes ## 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. 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.