kkelomatic_home/docs/codesys/codesys.md

# CODESYS Configuration

## Overview

CODESYS is an industrial control system running on a Raspberry Pi, managing physical I/O through a Beckhoff EtherCAT IO card.

## Hardware

- **Platform**: Raspberry Pi (CODESYS Control for Raspberry Pi MC SL)
- **CODESYS Version**: 4.15.0.0
- **SDK Version**: 3.5.21.0
- **Device Name**: codesys-home
- **EtherCAT Master**: Version 4.9.0.0
- **EtherCAT Devices**:
  - **EK1100**: EtherCAT Coupler (2A E-Bus) - Beckhoff
  - **EL1809**: 16Ch. Digital Input 24V, 3ms - Beckhoff (16 input channels)
  - **Output Module**: 16 digital output channels (16#1A00 - 16#1A0F)

## Network Variables

CODESYS communicates with Node-RED using network variables. These variables are shared over the network and allow bidirectional communication.

### Variables Sent to Node-RED (NVL_Sender)

**Protocol**: UDP  
**Task**: EtherCAT_Task  
**List Identifier**: 1  
**Transmission**: Cyclic, T#50ms interval  

| Variable Name | Type | Description |
|--------------|------|-------------|
| `l_masterBedroom` | struct_lights | Master bedroom lights |
| `l_masterBathroom` | struct_lights | Master bathroom lights |
| `l_bedroom_1` | struct_lights | Bedroom 1 lights |
| `l_bedroom_2` | struct_lights | Bedroom 2 lights |
| `l_bathroom` | struct_lights | Bathroom lights |
| `l_hallway` | struct_lights | Hallway lights |
| `l_pantry` | struct_lights | Pantry lights |
| `l_kitchen` | struct_lights | Kitchen lights |
| `l_livingRoom` | struct_lights | Living room lights |
| `l_dinningRoom` | struct_lights | Dining room lights |
| `l_entrance` | struct_lights | Entrance lights |
| `l_guestWc` | struct_lights | Guest WC lights |
| `l_outVeranda` | struct_lights | Outdoor veranda lights |
| `l_outFront` | struct_lights | Outdoor front lights |
| `l_outSide` | struct_lights | Outdoor side lights |
| `l_outBack` | struct_lights | Outdoor back lights |

### Variables Received from Node-RED (NVL_Receiver)

**Protocol**: UDP  
**Task**: EtherCAT_Task  
**List Identifier**: 3  
**Transmission**: Cyclic, T#50ms interval  

| Variable Name | Type | Description |
|--------------|------|-------------|
| `masterBedroom` | struct_switches | Master bedroom switches |
| `masterBathroom` | struct_switches | Master bathroom switches |
| `bedroom_1` | struct_switches | Bedroom 1 switches |
| `bedroom_2` | struct_switches | Bedroom 2 switches |
| `bathroom` | struct_switches | Bathroom switches |
| `hallway` | struct_switches | Hallway switches |
| `pantry` | struct_switches | Pantry switches |
| `kitchen` | struct_switches | Kitchen switches |
| `livingRoom` | struct_switches | Living room switches |
| `dinningRoom` | struct_switches | Dining room switches |
| `entrance` | struct_switches | Entrance switches |
| `guestWc` | struct_switches | Guest WC switches |
| `outVeranda` | struct_switches | Outdoor veranda switches |
| `outFront` | struct_switches | Outdoor front switches |
| `outSide` | struct_switches | Outdoor side switches |
| `outBack` | struct_switches | Outdoor back switches |

## I/O Configuration

### EtherCAT IO Card

- **EK1100**: EtherCAT Coupler (Beckhoff)
- **EL1809**: 16-channel Digital Input 24V (Beckhoff)
- **Output Module**: 16 digital output channels
- **Scan Rate**: EtherCAT_Task (50ms cyclic)

### Relay Mapping

| Relay # | Device Controlled | Function | Notes |
|---------|-------------------|----------|-------|
| 1 | [To be filled] | [To be filled] | |
| 2 | [To be filled] | [To be filled] | |
| ... | | | |

### Water Boiler Control

- **Relay Assignment**: [To be filled]
- **Control Logic**: [To be filled]
- **Safety Features**: [To be filled]

## Control Logic

### Lighting Control

The lighting control is implemented using the `fb_switch` function block. Each room has one instance that processes switch inputs and generates light control outputs.

**Function Block**: `fb_switch`
- **Input**: `struct_switches` (received from Node-RED)
  - Individual switches: `sw_1` through `sw_6`
  - Global commands: `all_on`, `all_off`
- **Output**: `struct_lights` (sent to Node-RED)
  - Light outputs: `l_1` through `l_6`

**Toggle Button**: `fb_toogleButton`
- Implements toggle functionality with debouncing
- Uses timing functions (TP, TOF) and counters (CTU, CTD)
- Each switch press toggles the corresponding light state

**Per-Room Configuration**:
- Each room can control up to 6 individual lights
- Global commands allow turning all lights on/off in a room
- Switch inputs come from Zigbee switches via Node-RED/MQTT

See [fb_switch Documentation](../redesign/fb_switch-documentation.md) for detailed information.

### Water Boiler Control

[Description of water boiler control logic, schedules, safety features]

## Network Configuration

- **IP Address**: [To be filled]
- **Subnet**: [To be filled]
- **Network Variable Port**: [To be filled]
- **EtherCAT Network**: [To be filled]

## Project Structure

- **Project Location**: `Home_Automation (1).project` (binary format)
- **Program Organization Units (POUs)**:
  - **PLC_PRG**: Main program using `fb_switch` function blocks
  - **fb_toogleButton**: Toggle button function block
  - **fb_switch**: Switch control function block
- **Libraries Used**:
  - IoStandard (System)
  - SM3_Basic, SM3_CNC, SM3_CamBuilder, SM3_Robotics (3S/CODESYS)
  - Standard, CmpLog (System)

### Exporting Project Information

The binary `.project` file cannot be directly analyzed. To extract project information:

1. **Export to XML format** - See [CODESYS Export Guide](codesys-export-guide.md) for detailed instructions
2. **Use the parser script** - Run `scripts/parse-codesys-xml.py` on exported XML files
3. **Manual extraction** - Open in CODESYS IDE and document manually

**Recommended Export:**
- Export as **CODESYS XML (*.export)** for complete project information
- Export as **PLCopen XML (*.xml)** for program structure

## Troubleshooting

### Common Issues

- [Issue 1]: [Solution]
- [Issue 2]: [Solution]

### Debugging

- How to monitor network variables
- How to view I/O states
- Log file locations

---

**Status**: Template - needs configuration details