kkelomatic_home/docs/redesign/fb_switch-documentation.md

# fb_switch Function Block Documentation

## Overview

The `fb_switch` function block is the core control logic for managing lighting in each room. It processes switch inputs from Node-RED and generates light control outputs.

## Function Block Structure

```iec
FUNCTION_BLOCK fb_switch
VAR_INPUT
    switches: struct_switches;  // Switch states received from Node-RED
END_VAR
VAR_OUTPUT
    lights: struct_lights;      // Light control outputs sent to Node-RED
END_VAR
VAR
    all_off: fb_toogleButton;   // Toggle button for "all off" command
    all_on: fb_toogleButton;    // Toggle button for "all on" command
    sw_1: fb_toogleButton;      // Toggle button for switch 1
    sw_2: fb_toogleButton;      // Toggle button for switch 2
    sw_3: fb_toogleButton;      // Toggle button for switch 3
    sw_4: fb_toogleButton;      // Toggle button for switch 4
    sw_5: fb_toogleButton;      // Toggle button for switch 5
    sw_6: fb_toogleButton;      // Toggle button for switch 6
END_VAR
```

## Data Structures

### struct_switches (Input)

```iec
TYPE struct_switches :
STRUCT
    all_off: BOOL;  // Command to turn all lights off
    all_on: BOOL;   // Command to turn all lights on
    sw_1: BOOL;     // Switch 1 state
    sw_2: BOOL;     // Switch 2 state
    sw_3: BOOL;     // Switch 3 state
    sw_4: BOOL;     // Switch 4 state
    sw_5: BOOL;     // Switch 5 state
    sw_6: BOOL;     // Switch 6 state
END_STRUCT
END_TYPE
```

### struct_lights (Output)

```iec
TYPE struct_lights:
STRUCT
    l_1: BOOL;  // Light 1 control output
    l_2: BOOL;  // Light 2 control output
    l_3: BOOL;  // Light 3 control output
    l_4: BOOL;  // Light 4 control output
    l_5: BOOL;  // Light 5 control output
    l_6: BOOL;  // Light 6 control output
END_STRUCT
END_TYPE
```

## Functionality

### Individual Switch Control

Each switch (`sw_1` through `sw_6`) is processed by a `fb_toogleButton` instance:
- **Input**: Switch state from `switches.sw_X` (received from Node-RED)
- **Output**: Light control to `lights.l_X` (sent to Node-RED)
- **Behavior**: Toggle functionality - each switch press toggles the corresponding light state

### Global Commands

1. **All Off (`switches.all_off`)**:
   - When activated, turns off all lights (l_1 through l_6)
   - Uses `fb_toogleButton` instance `all_off`

2. **All On (`switches.all_on`)**:
   - When activated, turns on all lights (l_1 through l_6)
   - Uses `fb_toogleButton` instance `all_on`
   - Logic uses AND gates to combine with individual switch states

### Logic Flow

1. **Switch Input Processing**:
   - Each `sw_X` input is fed to its corresponding `fb_toogleButton` instance
   - The toggle button processes the input and generates an output

2. **Light Output Generation**:
   - Individual switch outputs directly control their corresponding lights
   - `all_off` command can override individual controls
   - `all_on` command combines with individual switch states using AND logic

3. **Output Assignment**:
   - `sw_1` → `lights.l_1`
   - `sw_2` → `lights.l_2`
   - `sw_3` → `lights.l_3`
   - `sw_4` → `lights.l_4`
   - `sw_5` → `lights.l_5`
   - `sw_6` → `lights.l_6`

## fb_toogleButton Function Block

The `fb_toogleButton` is a toggle button implementation with debouncing and timing features.

### Structure

```iec
FUNCTION_BLOCK fb_toogleButton
VAR_INPUT
    Input: BOOL;  // Input signal (switch state)
END_VAR
VAR_OUTPUT
    Output: BOOL; // Output signal (light control)
END_VAR
VAR
    Switch: BOOL;      // Internal switch state
    Light: BOOL;       // Internal light state
    Flag1: BOOL;       // Internal flag 1
    Flag2: BOOL;       // Internal flag 2
    RT: R_TRIG;        // Rising edge trigger
    Pulse: TP;         // Pulse timer
    CTU_0: CTU;        // Counter up 0
    CTD_0: CTD;        // Counter down 0
    CTU_1: CTU;        // Counter up 1
    CTU_2: CTU;        // Counter up 2
    TOF_0: TOF;        // Timer off delay 0
END_VAR
```

### Features

- **Rising Edge Detection**: Uses `R_TRIG` to detect switch press events
- **Pulse Generation**: Uses `TP` (pulse timer) for debouncing or pulse generation
- **Timing Control**: Uses `TOF` (timer off delay) for delayed turn-off
- **Counters**: Uses `CTU` and `CTD` counters for state management
- **Toggle Logic**: Implements toggle behavior - each press changes state

### Behavior

1. **Input Processing**:
   - Detects rising edge of input signal
   - Generates a pulse for processing
   - Applies timing delays for debouncing

2. **State Management**:
   - Maintains internal switch and light states
   - Toggles output on each valid input pulse
   - Uses flags for state tracking

3. **Output Generation**:
   - Output reflects the toggled state
   - May include timing delays (TOF) for smooth operation

## Usage in System

### Per-Room Instance

Each room has an instance of `fb_switch`:
- `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`
- `veranda: fb_switch`
- `entrance: fb_switch`
- `front: fb_switch`
- `back: fb_switch`
- `side: fb_switch`
- `hallway: fb_switch`

### Network Variable Integration

- **Input**: Receives `struct_switches` from Node-RED via network variable `NVL_Receiver`
- **Output**: Sends `struct_lights` to Node-RED via network variable `NVL_Sender`

### Control Flow

```
Node-RED (Zigbee Switch) 
    ↓
MQTT Message
    ↓
Node-RED Processing
    ↓
Network Variable (struct_switches)
    ↓
fb_switch (CODESYS)
    ↓
fb_toogleButton Processing
    ↓
Light Control Output (struct_lights)
    ↓
Network Variable (NVL_Sender)
    ↓
Node-RED
    ↓
EtherCAT Relay Output
    ↓
Physical Light
```

## Notes

- Each room can control up to 6 individual lights
- Global commands (`all_on`, `all_off`) provide room-level control
- Toggle button implementation includes debouncing to prevent rapid switching
- Timing functions ensure smooth operation and prevent electrical issues
- The system supports both individual light control and group control per room

---

**Documentation Date**: January 27, 2026  
**Sources**: 
- `Home_Automation.export` (CODESYS XML)
- `Home_Automation.xml` (PLCopen XML)

**Additional Details**: See [CODESYS XML Analysis](../codesys/codesys-xml-analysis.md) for timing characteristics and detailed logic flow extracted from the PLCopen XML format.