Initial commit: Home automation docs and CODESYS project
- Reorganized project: codesys/, docs/codesys|redesign|integration|reference/, scripts/ - CODESYS project and exports in codesys/ - Documentation index in docs/README.md - Redesign and light naming configuration - Water boiler control and safety design Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
30
docs/README.md
Normal file
30
docs/README.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# Documentation Index
|
||||
|
||||
## Reference (Architecture & Setup)
|
||||
- [Architecture Overview](reference/architecture.md)
|
||||
- [Hardware Inventory](reference/hardware.md)
|
||||
- [Network Topology](reference/network.md)
|
||||
- [Setup Guide](reference/setup.md)
|
||||
- [Quick Reference](reference/quick-reference.md)
|
||||
|
||||
## CODESYS
|
||||
- [CODESYS Configuration](codesys/codesys.md)
|
||||
- [CODESYS Export Guide](codesys/codesys-export-guide.md)
|
||||
- [CODESYS Project Analysis](codesys/codesys-analysis.md)
|
||||
- [CODESYS XML Analysis](codesys/codesys-xml-analysis.md)
|
||||
|
||||
## Integration (Node-RED, MQTT, HA, Zigbee)
|
||||
- [Node-RED](integration/nodered.md)
|
||||
- [MQTT Broker](integration/mqtt.md)
|
||||
- [Home Assistant](integration/homeassistant.md)
|
||||
- [Zigbee2MQTT](integration/zigbee2mqtt.md)
|
||||
|
||||
## Redesign (Structure & Implementation)
|
||||
- [Redesign Summary](redesign/redesign-summary.md) — **Start here for redesign**
|
||||
- [Light Naming Configuration](redesign/light-naming-configuration.md) — Configure lights per room
|
||||
- [Implementation Roadmap](redesign/redesign-implementation-roadmap.md)
|
||||
- [Structure Redesign Analysis](redesign/structure-redesign-analysis.md)
|
||||
- [Structure Comparison (Visual)](redesign/structure-comparison-visual.md)
|
||||
- [fb_switch Documentation](redesign/fb_switch-documentation.md)
|
||||
- [fb_switch Redesign Recommendation](redesign/fb_switch-redesign-recommendation.md)
|
||||
- [fb_switch Analysis Summary](redesign/fb_switch-analysis-summary.md)
|
||||
189
docs/codesys/codesys-analysis.md
Normal file
189
docs/codesys/codesys-analysis.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# CODESYS Project Analysis
|
||||
|
||||
## Overview
|
||||
|
||||
This document contains information extracted from the CODESYS project export file (`Home_Automation.export`).
|
||||
|
||||
## Device Information
|
||||
|
||||
- **Device Name**: `codesys-home`
|
||||
- **CODESYS Version**: 4.15.0.0
|
||||
- **Platform**: CODESYS Control for Raspberry Pi MC SL
|
||||
- **SDK Version**: 3.5.21.0
|
||||
- **Order Number**: 2302000009
|
||||
|
||||
## Hardware Configuration
|
||||
|
||||
### EtherCAT Network
|
||||
|
||||
- **EtherCAT Master**: Version 4.9.0.0
|
||||
- **EtherCAT Task**: `EtherCAT_Task`
|
||||
|
||||
### EtherCAT Devices
|
||||
|
||||
1. **EK1100** - EtherCAT Coupler (2A E-Bus)
|
||||
- Vendor: Beckhoff Automation GmbH & Co. KG
|
||||
- Order Number: EK1100
|
||||
- Function: EtherCAT coupler connecting to E-Bus modules
|
||||
|
||||
2. **EL1809** - 16Ch. Digital Input 24V, 3ms
|
||||
- Vendor: Beckhoff Automation GmbH & Co. KG
|
||||
- Order Number: EL1809
|
||||
- Function: 16-channel digital input module
|
||||
- Channels: 16 digital inputs (Channels 1-16)
|
||||
|
||||
3. **Output Module** (Likely EL2004 or similar)
|
||||
- 16 output channels configured
|
||||
- Channel addresses: 16#1A00 through 16#1A0F (Channels 1-16)
|
||||
|
||||
## Network Variables
|
||||
|
||||
CODESYS communicates with Node-RED using UDP-based network variables.
|
||||
|
||||
### Variables Sent to Node-RED (NVL_Sender)
|
||||
|
||||
**List Identifier**: 1
|
||||
**Protocol**: UDP
|
||||
**Task**: EtherCAT_Task
|
||||
**Transmission**: Cyclic
|
||||
**Interval**: T#50ms
|
||||
**Minimum Gap**: T#20ms
|
||||
|
||||
**Structure**: `struct_lights` containing light states for each room:
|
||||
|
||||
| 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)
|
||||
|
||||
**List Identifier**: 3
|
||||
**Protocol**: UDP
|
||||
**Task**: EtherCAT_Task
|
||||
**Transmission**: Cyclic
|
||||
**Interval**: T#50ms
|
||||
**Minimum Gap**: T#20ms
|
||||
**Import File**: `C:\Users\NearchosParaskeva\OneDrive - individual\Codesys_Home_Automation\NVL_Receiver.gvl`
|
||||
|
||||
**Structure**: `struct_switches` containing switch states for each room:
|
||||
|
||||
| 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 |
|
||||
|
||||
## Program Structure
|
||||
|
||||
### Main Program (PLC_PRG)
|
||||
|
||||
- **Type**: Program
|
||||
- **Language**: Structured Text (ST)
|
||||
- **Function Blocks Used**: `fb_switch`
|
||||
- **Instances**:
|
||||
- `masterBedroom: fb_switch`
|
||||
|
||||
### Function Blocks
|
||||
|
||||
- **fb_toogleButton**: Toggle button function block
|
||||
- **fb_switch**: Switch control function block
|
||||
|
||||
### Variables Used in Logic
|
||||
|
||||
From the program code, the following variables are referenced:
|
||||
- `lights.l_1`, `lights.l_2`, `lights.l_3`, `lights.l_4`, `lights.l_5`, `lights.l_6`
|
||||
- `switches.sw_1`, `switches.sw_2`, `switches.sw_3`, `switches.sw_4`, `switches.sw_5`, `switches.sw_6`
|
||||
- `switches.all_off`
|
||||
- `switches.all_on`
|
||||
|
||||
## Room Configuration
|
||||
|
||||
The system controls lighting for 15 rooms/areas:
|
||||
|
||||
1. Master Bedroom
|
||||
2. Master Bathroom
|
||||
3. Bedroom 1
|
||||
4. Bedroom 2
|
||||
5. Bathroom
|
||||
6. Hallway
|
||||
7. Pantry
|
||||
8. Kitchen
|
||||
9. Living Room
|
||||
10. Dining Room
|
||||
11. Entrance
|
||||
12. Guest WC
|
||||
13. Outdoor Veranda
|
||||
14. Outdoor Front
|
||||
15. Outdoor Side
|
||||
16. Outdoor Back
|
||||
|
||||
## I/O Mapping
|
||||
|
||||
### Inputs (EL1809)
|
||||
- 16 digital input channels
|
||||
- Likely used for local switch inputs or status feedback
|
||||
|
||||
### Outputs (16 channels, likely EL2004)
|
||||
- 16 digital output channels (16#1A00 - 16#1A0F)
|
||||
- Used to control relay outputs for lighting
|
||||
|
||||
**Note**: The exact mapping between relay outputs and rooms needs to be determined from the program logic or wiring documentation.
|
||||
|
||||
## Libraries Used
|
||||
|
||||
- **IoStandard** (System)
|
||||
- **SM3_Basic** (3S - Smart Software Solutions GmbH)
|
||||
- **SM3_CNC** (3S - Smart Software Solutions GmbH)
|
||||
- **3SLicense** (CODESYS)
|
||||
- **SM3_CamBuilder** (CODESYS)
|
||||
- **SM3_Robotics** (CODESYS)
|
||||
- **SM3_Robotics_Visu** (CODESYS)
|
||||
- **SM3_Transformation** (CODESYS)
|
||||
- **Standard** (System)
|
||||
- **CmpLog** (System)
|
||||
|
||||
## Task Configuration
|
||||
|
||||
- **EtherCAT Task**: Used for EtherCAT communication and network variable updates
|
||||
- **Update Rate**: 50ms (cyclic transmission)
|
||||
|
||||
## Notes
|
||||
|
||||
- The project uses structured data types (`struct_lights`, `struct_switches`) for organizing room data
|
||||
- Network variables are packed and transmitted via UDP
|
||||
- The system appears to support both indoor and outdoor lighting control
|
||||
- Water boiler control mentioned in documentation was not found in the export - may be in a separate module or not yet implemented
|
||||
|
||||
---
|
||||
|
||||
**Analysis Date**: January 27, 2026
|
||||
**Source File**: `Home_Automation.export`
|
||||
**Export Format**: CODESYS XML
|
||||
147
docs/codesys/codesys-export-guide.md
Normal file
147
docs/codesys/codesys-export-guide.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# CODESYS Project Export Guide
|
||||
|
||||
## Overview
|
||||
|
||||
CODESYS projects can be exported to readable XML formats that allow for better analysis, documentation, and version control. The binary `.project` file format is proprietary and not human-readable, but CODESYS provides export options that create XML files.
|
||||
|
||||
## Export Formats
|
||||
|
||||
### 1. CODESYS XML Format (*.export)
|
||||
|
||||
**Best for:** Full project export, version control, complete documentation
|
||||
|
||||
- **Format:** Fully compatible CODESYS XML format
|
||||
- **Content:** Complete project structure in machine-parsable XML
|
||||
- **Compatibility:** 100% compatible with CODESYS
|
||||
- **Use Cases:**
|
||||
- Full project backup
|
||||
- Version control systems
|
||||
- Automated analysis and documentation
|
||||
- Project migration
|
||||
|
||||
**How to Export:**
|
||||
1. Open your project in CODESYS IDE
|
||||
2. Go to **Project → Export**
|
||||
3. Select the objects you want to export (or select all)
|
||||
4. Choose **CODESYS XML Format (*.export)** as the file type
|
||||
5. Save the file (e.g., `Home_Automation.export`)
|
||||
|
||||
### 2. PLCopen XML Format (*.xml)
|
||||
|
||||
**Best for:** Interoperability, documentation tools, program structure
|
||||
|
||||
- **Format:** PLCopen XML standard
|
||||
- **Content:** Subset of CODESYS elements (programs, function blocks, variables)
|
||||
- **Compatibility:** May not include all CODESYS-specific features
|
||||
- **Use Cases:**
|
||||
- Documentation generation
|
||||
- Integration with other tools
|
||||
- Program structure analysis
|
||||
- Cross-platform compatibility
|
||||
|
||||
**How to Export:**
|
||||
1. Open your project in CODESYS IDE
|
||||
2. Go to **Project → Export PLCopenXML**
|
||||
3. Select the objects to export
|
||||
4. Save the file (e.g., `Home_Automation.xml`)
|
||||
|
||||
## What Information Can Be Extracted
|
||||
|
||||
From exported XML files, we can extract:
|
||||
|
||||
### Project Structure
|
||||
- Program Organization Units (POUs)
|
||||
- Function blocks and functions
|
||||
- Libraries and dependencies
|
||||
- Project hierarchy
|
||||
|
||||
### Network Variables
|
||||
- Variable names
|
||||
- Data types
|
||||
- Initial values
|
||||
- Network variable declarations
|
||||
- Direction (input/output)
|
||||
|
||||
### I/O Configuration
|
||||
- EtherCAT device configuration
|
||||
- I/O channel mappings
|
||||
- Device parameters
|
||||
- Scan rates
|
||||
|
||||
### Control Logic
|
||||
- Program code structure
|
||||
- Variable declarations
|
||||
- Function block instances
|
||||
- Logic flow
|
||||
|
||||
### Hardware Configuration
|
||||
- Device configurations
|
||||
- Network settings
|
||||
- Communication parameters
|
||||
|
||||
## Recommended Export Process
|
||||
|
||||
For comprehensive documentation, export both formats:
|
||||
|
||||
1. **Full Export (CODESYS XML):**
|
||||
```
|
||||
File: Home_Automation.export
|
||||
- Complete project structure
|
||||
- All configurations
|
||||
- Network variables
|
||||
- I/O mappings
|
||||
```
|
||||
|
||||
2. **Program Export (PLCopen XML):**
|
||||
```
|
||||
File: Home_Automation.xml
|
||||
- Program structure
|
||||
- Variable declarations
|
||||
- Logic organization
|
||||
```
|
||||
|
||||
## After Export
|
||||
|
||||
Once you have the exported XML files:
|
||||
|
||||
1. **Share the files** - The XML files can be analyzed and documented
|
||||
2. **Version control** - XML files are text-based and work well with Git
|
||||
3. **Documentation** - Information can be extracted and added to the docs
|
||||
4. **Analysis** - Scripts can parse the XML to extract specific information
|
||||
|
||||
## Next Steps
|
||||
|
||||
After exporting:
|
||||
|
||||
1. Place exported files in the project directory
|
||||
2. Update `.gitignore` if needed (or commit the exports)
|
||||
3. Use the exported files to:
|
||||
- Document network variables
|
||||
- Map I/O configurations
|
||||
- Understand control logic
|
||||
- Complete the documentation templates
|
||||
|
||||
## Example Export Workflow
|
||||
|
||||
```bash
|
||||
# In CODESYS IDE:
|
||||
1. File → Open → "Home_Automation (1).project"
|
||||
2. Project → Export
|
||||
- Select: All objects
|
||||
- Format: CODESYS XML (*.export)
|
||||
- Save as: "Home_Automation.export"
|
||||
3. Project → Export PLCopenXML
|
||||
- Select: Programs, POUs
|
||||
- Save as: "Home_Automation.xml"
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Export files are typically much larger than binary project files
|
||||
- XML exports are human-readable and can be opened in any text editor
|
||||
- Some CODESYS-specific features may not be fully represented in PLCopen XML
|
||||
- Exported files can be re-imported into CODESYS if needed
|
||||
|
||||
---
|
||||
|
||||
**Status:** Ready for export - follow the steps above to create readable project files
|
||||
260
docs/codesys/codesys-xml-analysis.md
Normal file
260
docs/codesys/codesys-xml-analysis.md
Normal file
@@ -0,0 +1,260 @@
|
||||
# CODESYS PLCopen XML Analysis
|
||||
|
||||
## Overview
|
||||
|
||||
This document contains detailed information extracted from the PLCopen XML export (`Home_Automation.xml`), which provides a more structured view of the project compared to the CODESYS export format.
|
||||
|
||||
## Project Information
|
||||
|
||||
- **Format**: PLCopen XML (TC6 0200)
|
||||
- **CODESYS Version**: V3.5 SP21
|
||||
- **Export Date**: 2026-01-27T14:48:52
|
||||
- **Project Name**: Home_Automation.project
|
||||
|
||||
## Task Configuration
|
||||
|
||||
### MainTask
|
||||
- **Type**: Cyclic
|
||||
- **Interval**: t#4ms (4 milliseconds)
|
||||
- **Priority**: 1
|
||||
- **Watchdog**: Disabled
|
||||
- **Program**: PLC_PRG
|
||||
|
||||
### EtherCAT_Task
|
||||
- **Type**: Cyclic
|
||||
- **Interval**: t#4ms (4 milliseconds)
|
||||
- **Priority**: 1
|
||||
- **Watchdog**: Disabled
|
||||
- **Purpose**: EtherCAT communication and network variable updates
|
||||
|
||||
## Data Structures
|
||||
|
||||
### struct_switches
|
||||
|
||||
```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
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## Function Block: fb_toogleButton
|
||||
|
||||
### Interface
|
||||
|
||||
**Inputs**:
|
||||
- `Input: BOOL` - Input signal (switch state from network)
|
||||
|
||||
**Outputs**:
|
||||
- `Output: BOOL` - Output signal (light control)
|
||||
|
||||
**Internal Variables**:
|
||||
- `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
|
||||
|
||||
### Implementation (Ladder Diagram)
|
||||
|
||||
**Network 1: Input Debouncing**
|
||||
- Input signal → TP (Pulse Timer) with PT = t#100ms
|
||||
- TP output → TOF (Timer Off Delay) with PT = t#100ms
|
||||
- TOF output → Switch (internal state)
|
||||
- **Purpose**: Debounces input signal with 100ms pulse and 100ms off delay
|
||||
|
||||
**Network 2: Flag1 Logic**
|
||||
- Switch AND (NOT Light) AND (NOT Flag2) → Flag1
|
||||
- **Purpose**: Sets Flag1 when switch is on, light is off, and Flag2 is off
|
||||
|
||||
**Network 3: Flag2 Logic**
|
||||
- Switch AND Light AND (NOT Flag1) → Flag2
|
||||
- **Purpose**: Sets Flag2 when switch is on, light is on, and Flag1 is off
|
||||
|
||||
**Network 4: Light Toggle Logic**
|
||||
- Flag1 AND (NOT Flag2) → Light (toggle)
|
||||
- **Purpose**: Toggles light state based on flag conditions
|
||||
|
||||
**Network 5: Output Assignment**
|
||||
- Light → Output
|
||||
- **Purpose**: Direct output assignment
|
||||
|
||||
### Timing Characteristics
|
||||
|
||||
- **Input Debounce**: 100ms pulse timer (TP)
|
||||
- **Output Delay**: 100ms off delay (TOF)
|
||||
- **Total Response Time**: ~200ms (debounce + delay)
|
||||
|
||||
## Function Block: fb_switch
|
||||
|
||||
### Interface
|
||||
|
||||
**Inputs**:
|
||||
- `switches: struct_switches` - Switch states from Node-RED
|
||||
|
||||
**Outputs**:
|
||||
- `lights: struct_lights` - Light control outputs to Node-RED
|
||||
|
||||
**Internal Variables**:
|
||||
- `all_off: fb_toogleButton` - Toggle button for "all off"
|
||||
- `all_on: fb_toogleButton` - Toggle button for "all on"
|
||||
- `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
|
||||
|
||||
### Implementation (Continuous Function Chart - CFC)
|
||||
|
||||
**Logic Flow for Each Light (l_1 through l_6)**:
|
||||
|
||||
1. **All Off Logic**:
|
||||
```
|
||||
all_off.Output AND lights.l_X → AND gate → (forces light off)
|
||||
```
|
||||
|
||||
2. **All On Logic**:
|
||||
```
|
||||
all_on.Output AND (NOT lights.l_X) → AND gate → (forces light on)
|
||||
```
|
||||
|
||||
3. **Individual Switch Logic**:
|
||||
```
|
||||
switches.sw_X → sw_X.Input → sw_X.Output → lights.l_X
|
||||
```
|
||||
|
||||
4. **Combined Logic (OR)**:
|
||||
```
|
||||
(all_on logic) OR (sw_X.Output) OR (other sources) → lights.l_X
|
||||
```
|
||||
|
||||
**Execution Order** (example for l_1):
|
||||
1. Execution Order 1: AND gate for all_on logic
|
||||
2. Execution Order 2: sw_2 toggle button
|
||||
3. Execution Order 3: OR gate combining sources
|
||||
4. Execution Order 4: AND gate for all_off logic
|
||||
5. Execution Order 5: Output assignment to lights.l_1
|
||||
6. Execution Order 30: sw_1 toggle button (individual control)
|
||||
|
||||
**Key Logic Patterns**:
|
||||
|
||||
- **All Off**: Uses AND gate with `all_off.Output` and current light state
|
||||
- **All On**: Uses AND gate with `all_on.Output` and inverted light state
|
||||
- **Individual Control**: Each switch has its own toggle button instance
|
||||
- **Priority**: All_off can override individual controls, all_on combines with individual
|
||||
|
||||
## Program: Lights
|
||||
|
||||
The "Lights" program contains instances of `fb_switch` for all 15 rooms:
|
||||
|
||||
1. `masterBedroom: fb_switch`
|
||||
2. `masterBathroom: fb_switch`
|
||||
3. `bedroom_1: fb_switch`
|
||||
4. `bedroom_2: fb_switch`
|
||||
5. `bathroom: fb_switch`
|
||||
6. `guest_wc: fb_switch`
|
||||
7. `kitchen: fb_switch`
|
||||
8. `pantry: fb_switch`
|
||||
9. `livingRoom: fb_switch`
|
||||
10. `diningRoom: fb_switch`
|
||||
11. `veranda: fb_switch`
|
||||
12. `entrance: fb_switch`
|
||||
13. `front: fb_switch`
|
||||
14. `back: fb_switch`
|
||||
15. `side: fb_switch`
|
||||
16. `hallway: fb_switch`
|
||||
|
||||
## Network Variables
|
||||
|
||||
### NVL_Sender (Sent to Node-RED)
|
||||
|
||||
All 15 room light structures:
|
||||
- `l_masterBedroom` through `l_outBack` (struct_lights)
|
||||
|
||||
### NVL_Receiver (Received from Node-RED)
|
||||
|
||||
All 15 room switch structures:
|
||||
- `masterBedroom` through `outBack` (struct_switches)
|
||||
|
||||
## Control Logic Summary
|
||||
|
||||
### Individual Light Control
|
||||
|
||||
1. **Switch Input** → `switches.sw_X` (from Node-RED)
|
||||
2. **Toggle Processing** → `fb_toogleButton` instance
|
||||
- 100ms debounce (TP)
|
||||
- 100ms delay (TOF)
|
||||
- Toggle logic with flags
|
||||
3. **Output** → `lights.l_X` (to Node-RED)
|
||||
|
||||
### Global Commands
|
||||
|
||||
**All Off**:
|
||||
- `switches.all_off` → `all_off` toggle button
|
||||
- Output ANDed with current light state
|
||||
- Forces all lights off
|
||||
|
||||
**All On**:
|
||||
- `switches.all_on` → `all_on` toggle button
|
||||
- Output ANDed with inverted light state
|
||||
- Forces all lights on
|
||||
- Combined with individual switches via OR logic
|
||||
|
||||
### Timing Characteristics
|
||||
|
||||
- **Task Cycle**: 4ms (MainTask and EtherCAT_Task)
|
||||
- **Input Debounce**: 100ms
|
||||
- **Output Delay**: 100ms
|
||||
- **Network Variable Update**: 50ms (from .export analysis)
|
||||
- **Total Response**: ~200ms (debounce + delay)
|
||||
|
||||
## Implementation Language
|
||||
|
||||
- **fb_toogleButton**: Ladder Diagram (LD)
|
||||
- **fb_switch**: Continuous Function Chart (CFC)
|
||||
- **Lights Program**: Continuous Function Chart (CFC)
|
||||
|
||||
## Key Insights
|
||||
|
||||
1. **Debouncing**: All switch inputs are debounced with 100ms pulse timer
|
||||
2. **Toggle Logic**: Uses flag-based state machine for reliable toggling
|
||||
3. **Priority System**: All_off has priority over individual controls
|
||||
4. **Combined Control**: All_on works in conjunction with individual switches
|
||||
5. **Fast Response**: 4ms task cycle ensures responsive control
|
||||
6. **Structured Design**: Each room is independent with its own fb_switch instance
|
||||
|
||||
---
|
||||
|
||||
**Analysis Date**: January 27, 2026
|
||||
**Source File**: `Home_Automation.xml`
|
||||
**Format**: PLCopen XML (TC6 0200)
|
||||
173
docs/codesys/codesys.md
Normal file
173
docs/codesys/codesys.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# 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
|
||||
115
docs/integration/homeassistant.md
Normal file
115
docs/integration/homeassistant.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# Home Assistant Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
Home Assistant provides the user interface (dashboard) and additional automation capabilities for the home automation system.
|
||||
|
||||
## Installation
|
||||
|
||||
- **Version**: [To be filled]
|
||||
- **Installation Type**: [HassOS, Docker, Python venv, etc.]
|
||||
- **Host**: [To be filled]
|
||||
- **Port**: [To be filled]
|
||||
- **URL**: [To be filled]
|
||||
|
||||
## Integrations
|
||||
|
||||
### MQTT Integration
|
||||
|
||||
- **Broker**: [IP/URL]
|
||||
- **Port**: [To be filled]
|
||||
- **Discovery**: [Enabled/Disabled]
|
||||
- **Topics**: [To be filled]
|
||||
|
||||
### Node-RED Integration
|
||||
|
||||
- **Integration Method**: [MQTT, HTTP, API, etc.]
|
||||
- **Configuration**: [To be filled]
|
||||
|
||||
### Zigbee Integration
|
||||
|
||||
- **Direct Zigbee**: [If Home Assistant has direct Zigbee integration]
|
||||
- **Via Zigbee2MQTT**: [Configuration]
|
||||
|
||||
## Entities
|
||||
|
||||
### Lighting Entities
|
||||
|
||||
| Entity ID | Name | Source | Control Method |
|
||||
|-----------|------|--------|----------------|
|
||||
| [ID] | [Name] | [Source] | [Method] |
|
||||
|
||||
### Water Boiler Entity
|
||||
|
||||
| Entity ID | Name | Source | Control Method |
|
||||
|-----------|------|--------|----------------|
|
||||
| [ID] | [Name] | [Source] | [Method] |
|
||||
|
||||
### Other Entities
|
||||
|
||||
[Add other entities]
|
||||
|
||||
## Dashboards
|
||||
|
||||
### Main Dashboard
|
||||
|
||||
- **Layout**: [Description or screenshot reference]
|
||||
- **Cards**: [List of cards/widgets]
|
||||
- **Views**: [Different views/pages]
|
||||
|
||||
### Mobile Dashboard
|
||||
|
||||
[If different from main]
|
||||
|
||||
## Automations
|
||||
|
||||
### Automation 1: [Name]
|
||||
|
||||
- **Trigger**: [Description]
|
||||
- **Condition**: [Description]
|
||||
- **Action**: [Description]
|
||||
|
||||
### Automation 2: [Name]
|
||||
|
||||
[Similar structure]
|
||||
|
||||
## Scripts
|
||||
|
||||
[Document any Home Assistant scripts]
|
||||
|
||||
## Scenes
|
||||
|
||||
[Document scenes if used]
|
||||
|
||||
## Custom Components
|
||||
|
||||
- **Custom Components**: [List if any]
|
||||
- **Add-ons**: [List if any]
|
||||
|
||||
## Configuration Files
|
||||
|
||||
- **Configuration Location**: [Path]
|
||||
- **Main Config File**: [Path]
|
||||
- **Automation Files**: [Path]
|
||||
- **Dashboard Files**: [Path]
|
||||
|
||||
## Access Control
|
||||
|
||||
- **Users**: [To be filled]
|
||||
- **API Tokens**: [To be filled - stored securely]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
- [Issue]: [Solution]
|
||||
|
||||
### Debugging
|
||||
|
||||
- Enable debug logging
|
||||
- Check integration status
|
||||
- Review logs
|
||||
|
||||
---
|
||||
|
||||
**Status**: Template - needs configuration details
|
||||
94
docs/integration/mqtt.md
Normal file
94
docs/integration/mqtt.md
Normal file
@@ -0,0 +1,94 @@
|
||||
# MQTT Broker Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
The MQTT broker runs in a separate LXC container and serves as the central message bus for the automation system.
|
||||
|
||||
## Installation
|
||||
|
||||
- **Software**: [Mosquitto, Eclipse, etc.]
|
||||
- **Version**: [To be filled]
|
||||
- **Host**: [LXC container name/IP]
|
||||
- **Port**: [To be filled, typically 1883/8883]
|
||||
|
||||
## LXC Container
|
||||
|
||||
- **Container Name**: [To be filled]
|
||||
- **OS**: [To be filled]
|
||||
- **Resources**: [CPU, RAM, Disk]
|
||||
- **Network**: [To be filled]
|
||||
|
||||
## Configuration
|
||||
|
||||
### Broker Settings
|
||||
|
||||
- **Port**: [To be filled]
|
||||
- **TLS/SSL**: [Enabled/Disabled]
|
||||
- **WebSocket**: [Enabled/Disabled]
|
||||
- **Persistence**: [Enabled/Disabled]
|
||||
- **Log Level**: [To be filled]
|
||||
|
||||
### Authentication
|
||||
|
||||
- **Authentication Method**: [Username/Password, Certificates, etc.]
|
||||
- **Users**: [List of users if applicable]
|
||||
- **ACLs**: [Access Control Lists]
|
||||
|
||||
## Topic Structure
|
||||
|
||||
### Topic Naming Convention
|
||||
|
||||
[Document the topic naming convention used]
|
||||
|
||||
### Main Topics
|
||||
|
||||
| Topic Pattern | Publisher | Subscriber | Description |
|
||||
|--------------|-----------|------------|-------------|
|
||||
| `zigbee2mqtt/#` | Zigbee2MQTT | Node-RED, Home Assistant | Zigbee device messages |
|
||||
| `codesys/#` | Node-RED | CODESYS | CODESYS control messages |
|
||||
| `homeassistant/#` | Home Assistant | Node-RED | Home Assistant messages |
|
||||
| `nodered/#` | Node-RED | Various | Node-RED messages |
|
||||
|
||||
## QoS Levels
|
||||
|
||||
- **Default QoS**: [To be filled]
|
||||
- **Retained Messages**: [Policy]
|
||||
|
||||
## Clients
|
||||
|
||||
### Connected Clients
|
||||
|
||||
| Client | Type | Topics Subscribed | Topics Published |
|
||||
|--------|------|-------------------|------------------|
|
||||
| Zigbee2MQTT | Bridge | [Topics] | `zigbee2mqtt/#` |
|
||||
| Node-RED | Automation | [Topics] | [Topics] |
|
||||
| Home Assistant | Dashboard | [Topics] | [Topics] |
|
||||
|
||||
## Security
|
||||
|
||||
- **Network Isolation**: [To be filled]
|
||||
- **Firewall Rules**: [To be filled]
|
||||
- **TLS Configuration**: [If applicable]
|
||||
|
||||
## Monitoring
|
||||
|
||||
- **Metrics**: [To be filled]
|
||||
- **Logging**: [To be filled]
|
||||
- **Health Checks**: [To be filled]
|
||||
|
||||
## Backup and Recovery
|
||||
|
||||
- **Configuration Backup**: [Procedure]
|
||||
- **Message Persistence**: [If enabled]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
- **Connection failures**: [Solution]
|
||||
- **Message delivery issues**: [Solution]
|
||||
- **Performance problems**: [Solution]
|
||||
|
||||
---
|
||||
|
||||
**Status**: Template - needs configuration details
|
||||
95
docs/integration/nodered.md
Normal file
95
docs/integration/nodered.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# Node-RED Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
Node-RED provides flow-based programming for automation logic and acts as a bridge between CODESYS, MQTT, and Home Assistant.
|
||||
|
||||
## Installation
|
||||
|
||||
- **Version**: [To be filled]
|
||||
- **Installation Method**: [To be filled]
|
||||
- **Host**: [To be filled]
|
||||
- **Port**: [To be filled]
|
||||
|
||||
## Main Flows
|
||||
|
||||
### Flow 1: [Name]
|
||||
|
||||
**Purpose**: [Description]
|
||||
|
||||
**Nodes Used**:
|
||||
- [Node type]: [Function]
|
||||
|
||||
**Logic**: [Description]
|
||||
|
||||
### Flow 2: [Name]
|
||||
|
||||
[Similar structure]
|
||||
|
||||
## CODESYS Integration
|
||||
|
||||
### Network Variable Nodes
|
||||
|
||||
- **Connection Method**: [To be filled]
|
||||
- **Variables Mapped**: [To be filled]
|
||||
- **Update Frequency**: [To be filled]
|
||||
|
||||
## MQTT Integration
|
||||
|
||||
### Subscribed Topics
|
||||
|
||||
| Topic | QoS | Function | Description |
|
||||
|-------|-----|----------|-------------|
|
||||
| [Topic] | [QoS] | [Function] | [Description] |
|
||||
|
||||
### Published Topics
|
||||
|
||||
| Topic | QoS | Function | Description |
|
||||
|-------|-----|----------|-------------|
|
||||
| [Topic] | [QoS] | [Function] | [Description] |
|
||||
|
||||
## Home Assistant Integration
|
||||
|
||||
- **Integration Method**: [MQTT, HTTP, API, etc.]
|
||||
- **Entities Created**: [To be filled]
|
||||
- **Automations**: [To be filled]
|
||||
|
||||
## Custom Functions
|
||||
|
||||
### JavaScript Functions
|
||||
|
||||
```javascript
|
||||
// [Function name and description]
|
||||
// [Code if available]
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
- **Error Nodes**: [To be filled]
|
||||
- **Retry Logic**: [To be filled]
|
||||
- **Fallback Behaviors**: [To be filled]
|
||||
|
||||
## Flow Export
|
||||
|
||||
[If available, include flow export or reference to flow file]
|
||||
|
||||
## Dashboard (if used)
|
||||
|
||||
- **Dashboard Nodes**: [To be filled]
|
||||
- **UI Components**: [To be filled]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
- [Issue]: [Solution]
|
||||
|
||||
### Debugging
|
||||
|
||||
- How to enable debug messages
|
||||
- Flow validation
|
||||
- Message inspection
|
||||
|
||||
---
|
||||
|
||||
**Status**: Template - needs flow details
|
||||
93
docs/integration/zigbee2mqtt.md
Normal file
93
docs/integration/zigbee2mqtt.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# Zigbee2MQTT Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
Zigbee2MQTT bridges Zigbee wireless devices to the MQTT ecosystem, allowing Zigbee switches to communicate with the rest of the automation system.
|
||||
|
||||
## Installation
|
||||
|
||||
- **Version**: [To be filled]
|
||||
- **Host**: [To be filled]
|
||||
- **Installation Method**: [Docker, native, etc.]
|
||||
- **Configuration File**: [Path to be filled]
|
||||
|
||||
## Coordinator
|
||||
|
||||
- **Model**: [To be filled]
|
||||
- **Firmware**: [To be filled]
|
||||
- **Port**: [To be filled]
|
||||
|
||||
## Zigbee Devices
|
||||
|
||||
### Light Switches
|
||||
|
||||
| Device Name | Model | IEEE Address | MQTT Topic | Functions |
|
||||
|------------|-------|--------------|------------|-----------|
|
||||
| [Name] | [Model] | [Address] | [Topic] | [Functions] |
|
||||
|
||||
### Other Devices
|
||||
|
||||
[Add other Zigbee devices if applicable]
|
||||
|
||||
## MQTT Topics
|
||||
|
||||
### Topic Structure
|
||||
|
||||
- **Base Topic**: [To be filled, typically `zigbee2mqtt`]
|
||||
- **Device Topics**: `[base_topic]/[device_name]`
|
||||
- **Bridge Topics**: `[base_topic]/bridge/*`
|
||||
|
||||
### Common Topics
|
||||
|
||||
| Topic | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `zigbee2mqtt/[device]/set` | Publish | Control device |
|
||||
| `zigbee2mqtt/[device]` | Subscribe | Device state |
|
||||
| `zigbee2mqtt/bridge/state` | Subscribe | Bridge status |
|
||||
| `zigbee2mqtt/bridge/log` | Subscribe | Bridge logs |
|
||||
|
||||
## Device Configuration
|
||||
|
||||
### Switch Configuration
|
||||
|
||||
[Configuration details for switches]
|
||||
|
||||
### Pairing Process
|
||||
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
## Network Security
|
||||
|
||||
- **Network Key**: [Stored securely - location to be documented]
|
||||
- **PAN ID**: [To be filled]
|
||||
- **Channel**: [To be filled]
|
||||
|
||||
## Integration with Node-RED
|
||||
|
||||
- **How switches trigger flows**: [To be filled]
|
||||
- **Topic mappings**: [To be filled]
|
||||
|
||||
## Integration with Home Assistant
|
||||
|
||||
- **Auto-discovery**: [Enabled/Disabled]
|
||||
- **Manual configuration**: [If applicable]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
- **Device not responding**: [Solution]
|
||||
- **Pairing failures**: [Solution]
|
||||
- **Network instability**: [Solution]
|
||||
|
||||
### Debugging
|
||||
|
||||
- Enable debug logging
|
||||
- Check MQTT messages
|
||||
- Monitor Zigbee network map
|
||||
|
||||
---
|
||||
|
||||
**Status**: Template - needs device list and configuration
|
||||
89
docs/redesign/fb_switch-analysis-summary.md
Normal file
89
docs/redesign/fb_switch-analysis-summary.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# fb_switch Analysis Summary
|
||||
|
||||
## Quick Assessment
|
||||
|
||||
**Current Approach**: ⚠️ **Needs Improvement**
|
||||
|
||||
**Main Issue**: Toggle-based control causes state desynchronization with Home Assistant.
|
||||
|
||||
## Key Problems
|
||||
|
||||
### 1. State Desynchronization
|
||||
- **Problem**: HA sends ON/OFF commands, but CODESYS toggles
|
||||
- **Result**: HA thinks light is ON, sends ON again → CODESYS toggles it OFF
|
||||
- **Impact**: Lights don't match HA state
|
||||
|
||||
### 2. No Status Feedback
|
||||
- **Problem**: Status comes from toggle button, not actual relay
|
||||
- **Result**: Can't detect relay hardware failures
|
||||
- **Impact**: HA may show wrong status
|
||||
|
||||
### 3. Mixed Control Sources
|
||||
- **Problem**: HA and Zigbee both use same toggle mechanism
|
||||
- **Result**: Conflicting behaviors
|
||||
- **Impact**: Unpredictable control
|
||||
|
||||
## What You Need
|
||||
|
||||
✅ **Control from Home Assistant** (ON/OFF switches)
|
||||
✅ **Control from Zigbee switches** (toggle behavior)
|
||||
✅ **Status feedback** (actual relay state)
|
||||
|
||||
## Recommended Solution
|
||||
|
||||
### Option 1: Full Redesign (Recommended)
|
||||
- Separate ON/OFF commands for HA
|
||||
- Edge detection for Zigbee (toggle)
|
||||
- Read actual relay status from EtherCAT
|
||||
- Clear priority system
|
||||
|
||||
**Pros**: Clean, maintainable, extensible
|
||||
**Cons**: Requires more changes
|
||||
|
||||
### Option 2: Simplified Improvement
|
||||
- Add ON/OFF commands alongside toggle
|
||||
- Keep most existing structure
|
||||
- Add status feedback
|
||||
|
||||
**Pros**: Less changes, faster to implement
|
||||
**Cons**: Less clean, still some complexity
|
||||
|
||||
## Quick Fix (Minimal Changes)
|
||||
|
||||
If you need a quick fix while planning the redesign:
|
||||
|
||||
1. **In Node-RED**: Convert HA ON/OFF to edge pulses
|
||||
```javascript
|
||||
// Only send toggle on state change
|
||||
if (currentState !== newState) {
|
||||
sendToggle = true;
|
||||
}
|
||||
```
|
||||
|
||||
2. **Add status readback**: Read actual EtherCAT output state
|
||||
```iec
|
||||
lights.l_1_status := EtherCAT_Output_Channel_1;
|
||||
```
|
||||
|
||||
3. **Update HA**: Use state topic for status feedback
|
||||
|
||||
## Decision Matrix
|
||||
|
||||
| Approach | Complexity | Time | Maintainability | Recommended For |
|
||||
|----------|-----------|------|-----------------|-----------------|
|
||||
| Full Redesign | High | 2-3 days | Excellent | Long-term solution |
|
||||
| Simplified | Medium | 1 day | Good | Quick improvement |
|
||||
| Quick Fix | Low | 2-4 hours | Fair | Temporary solution |
|
||||
|
||||
## My Recommendation
|
||||
|
||||
**Start with Quick Fix** → **Then implement Simplified** → **Plan Full Redesign**
|
||||
|
||||
This gives you:
|
||||
1. Immediate working solution
|
||||
2. Better solution in short term
|
||||
3. Best solution for long term
|
||||
|
||||
---
|
||||
|
||||
**See**: [Full Redesign Recommendation](fb_switch-redesign-recommendation.md) for detailed implementation.
|
||||
223
docs/redesign/fb_switch-documentation.md
Normal file
223
docs/redesign/fb_switch-documentation.md
Normal file
@@ -0,0 +1,223 @@
|
||||
# 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.
|
||||
451
docs/redesign/fb_switch-redesign-recommendation.md
Normal file
451
docs/redesign/fb_switch-redesign-recommendation.md
Normal file
@@ -0,0 +1,451 @@
|
||||
# fb_switch Redesign Recommendation
|
||||
|
||||
## Current Implementation Issues
|
||||
|
||||
### Problem 1: Toggle-Based Control
|
||||
**Issue**: The current `fb_toogleButton` implementation uses toggle logic, which causes state desynchronization with Home Assistant.
|
||||
|
||||
**Why this is a problem**:
|
||||
- Home Assistant sends explicit ON/OFF commands
|
||||
- CODESYS treats every input as a toggle trigger
|
||||
- If HA thinks light is ON and sends ON again, CODESYS toggles it OFF
|
||||
- State becomes out of sync between HA and actual relay state
|
||||
|
||||
**Example Scenario**:
|
||||
1. HA sends `sw_1 = TRUE` (turn ON)
|
||||
2. CODESYS toggles: OFF → ON ✓
|
||||
3. HA sends `sw_1 = TRUE` again (thinking it's already ON)
|
||||
4. CODESYS toggles: ON → OFF ✗ (wrong!)
|
||||
|
||||
### Problem 2: No Direct Set/Reset Commands
|
||||
**Issue**: Current structure only has toggle triggers, no explicit ON/OFF commands.
|
||||
|
||||
**Current Structure**:
|
||||
```iec
|
||||
struct_switches:
|
||||
sw_1: BOOL; // Treated as toggle trigger
|
||||
all_on: BOOL; // Toggle trigger
|
||||
all_off: BOOL; // Toggle trigger
|
||||
```
|
||||
|
||||
**What's needed**:
|
||||
- Separate ON and OFF commands
|
||||
- Edge detection for Zigbee switches (toggle behavior)
|
||||
- Direct set/reset for Home Assistant
|
||||
|
||||
### Problem 3: Status Feedback Limitations
|
||||
**Issue**: Current `lights.l_X` outputs represent toggle button state, not actual relay status.
|
||||
|
||||
**Problems**:
|
||||
- No direct feedback from physical relay outputs
|
||||
- Status may not match actual relay state if relay fails
|
||||
- No way to detect relay hardware failures
|
||||
|
||||
## Recommended Redesign
|
||||
|
||||
### New Data Structure
|
||||
|
||||
```iec
|
||||
TYPE struct_switches :
|
||||
STRUCT
|
||||
// Home Assistant Commands (set/reset)
|
||||
ha_l1_on: BOOL; // HA command: Light 1 ON
|
||||
ha_l1_off: BOOL; // HA command: Light 1 OFF
|
||||
ha_l2_on: BOOL;
|
||||
ha_l2_off: BOOL;
|
||||
ha_l3_on: BOOL;
|
||||
ha_l3_off: BOOL;
|
||||
ha_l4_on: BOOL;
|
||||
ha_l4_off: BOOL;
|
||||
ha_l5_on: BOOL;
|
||||
ha_l5_off: BOOL;
|
||||
ha_l6_on: BOOL;
|
||||
ha_l6_off: BOOL;
|
||||
|
||||
// Zigbee Switch Inputs (edge detection for toggle)
|
||||
zigbee_sw1: BOOL; // Zigbee switch 1 (edge detected)
|
||||
zigbee_sw2: BOOL;
|
||||
zigbee_sw3: BOOL;
|
||||
zigbee_sw4: BOOL;
|
||||
zigbee_sw5: BOOL;
|
||||
zigbee_sw6: BOOL;
|
||||
|
||||
// Global Commands
|
||||
ha_all_on: BOOL; // HA: All lights ON
|
||||
ha_all_off: BOOL; // HA: All lights OFF
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
|
||||
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
|
||||
|
||||
// Status feedback (read from actual relay outputs)
|
||||
l_1_status: BOOL; // Actual relay 1 state
|
||||
l_2_status: BOOL; // Actual relay 2 state
|
||||
l_3_status: BOOL; // Actual relay 3 state
|
||||
l_4_status: BOOL; // Actual relay 4 state
|
||||
l_5_status: BOOL; // Actual relay 5 state
|
||||
l_6_status: BOOL; // Actual relay 6 state
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
```
|
||||
|
||||
### New Function Block: fb_lightControl
|
||||
|
||||
```iec
|
||||
FUNCTION_BLOCK fb_lightControl
|
||||
VAR_INPUT
|
||||
// Home Assistant Commands
|
||||
ha_on: BOOL; // HA command: Turn ON
|
||||
ha_off: BOOL; // HA command: Turn OFF
|
||||
|
||||
// Zigbee Switch Input
|
||||
zigbee_sw: BOOL; // Zigbee switch (edge detected)
|
||||
|
||||
// Status Feedback
|
||||
relay_status: BOOL; // Actual relay state (read from EtherCAT)
|
||||
END_VAR
|
||||
VAR_OUTPUT
|
||||
light_output: BOOL; // Control output to relay
|
||||
light_status: BOOL; // Status to send back (actual relay state)
|
||||
END_VAR
|
||||
VAR
|
||||
// Edge detection for Zigbee
|
||||
zigbee_prev: BOOL;
|
||||
zigbee_edge: BOOL;
|
||||
|
||||
// Command processing
|
||||
ha_on_prev: BOOL;
|
||||
ha_off_prev: BOOL;
|
||||
ha_on_edge: BOOL;
|
||||
ha_off_edge: BOOL;
|
||||
|
||||
// Internal state
|
||||
light_state: BOOL;
|
||||
|
||||
// Edge triggers
|
||||
r_trig_ha_on: R_TRIG;
|
||||
r_trig_ha_off: R_TRIG;
|
||||
r_trig_zigbee: R_TRIG;
|
||||
END_VAR
|
||||
```
|
||||
|
||||
### Implementation Logic
|
||||
|
||||
**Priority Order** (highest to lowest):
|
||||
1. **HA OFF command** - Always turns light OFF
|
||||
2. **HA ON command** - Always turns light ON
|
||||
3. **Zigbee toggle** - Toggles current state
|
||||
4. **Maintain current state** - If no commands
|
||||
|
||||
**Logic Flow**:
|
||||
|
||||
```iec
|
||||
// Edge detection for commands
|
||||
r_trig_ha_on(CLK := ha_on);
|
||||
ha_on_edge := r_trig_ha_on.Q;
|
||||
|
||||
r_trig_ha_off(CLK := ha_off);
|
||||
ha_off_edge := r_trig_ha_off.Q;
|
||||
|
||||
r_trig_zigbee(CLK := zigbee_sw);
|
||||
zigbee_edge := r_trig_zigbee.Q;
|
||||
|
||||
// State machine
|
||||
IF ha_off_edge THEN
|
||||
light_state := FALSE;
|
||||
ELSIF ha_on_edge THEN
|
||||
light_state := TRUE;
|
||||
ELSIF zigbee_edge THEN
|
||||
light_state := NOT light_state;
|
||||
END_IF
|
||||
|
||||
// Output assignment
|
||||
light_output := light_state;
|
||||
|
||||
// Status feedback (read from actual relay)
|
||||
light_status := relay_status;
|
||||
```
|
||||
|
||||
### New fb_switch Implementation
|
||||
|
||||
```iec
|
||||
FUNCTION_BLOCK fb_switch
|
||||
VAR_INPUT
|
||||
switches: struct_switches;
|
||||
relay_status: struct_lights; // Read from EtherCAT outputs
|
||||
END_VAR
|
||||
VAR_OUTPUT
|
||||
lights: struct_lights;
|
||||
END_VAR
|
||||
VAR
|
||||
l1: fb_lightControl;
|
||||
l2: fb_lightControl;
|
||||
l3: fb_lightControl;
|
||||
l4: fb_lightControl;
|
||||
l5: fb_lightControl;
|
||||
l6: fb_lightControl;
|
||||
END_VAR
|
||||
|
||||
// Light 1 Control
|
||||
l1(
|
||||
ha_on := switches.ha_l1_on,
|
||||
ha_off := switches.ha_l1_off,
|
||||
zigbee_sw := switches.zigbee_sw1,
|
||||
relay_status := relay_status.l_1_status
|
||||
);
|
||||
lights.l_1 := l1.light_output;
|
||||
lights.l_1_status := l1.light_status;
|
||||
|
||||
// Light 2 Control
|
||||
l2(
|
||||
ha_on := switches.ha_l2_on,
|
||||
ha_off := switches.ha_l2_off,
|
||||
zigbee_sw := switches.zigbee_sw2,
|
||||
relay_status := relay_status.l_2_status
|
||||
);
|
||||
lights.l_2 := l2.light_output;
|
||||
lights.l_2_status := l2.light_status;
|
||||
|
||||
// ... (repeat for l3-l6)
|
||||
|
||||
// Global Commands
|
||||
IF switches.ha_all_off THEN
|
||||
lights.l_1 := FALSE;
|
||||
lights.l_2 := FALSE;
|
||||
lights.l_3 := FALSE;
|
||||
lights.l_4 := FALSE;
|
||||
lights.l_5 := FALSE;
|
||||
lights.l_6 := FALSE;
|
||||
ELSIF switches.ha_all_on THEN
|
||||
lights.l_1 := TRUE;
|
||||
lights.l_2 := TRUE;
|
||||
lights.l_3 := TRUE;
|
||||
lights.l_4 := TRUE;
|
||||
lights.l_5 := TRUE;
|
||||
lights.l_6 := TRUE;
|
||||
END_IF;
|
||||
```
|
||||
|
||||
## Node-RED Integration Changes
|
||||
|
||||
### Current Flow (Toggle-Based)
|
||||
```
|
||||
Zigbee Switch → MQTT → Node-RED → CODESYS (sw_1 = TRUE) → Toggle
|
||||
Home Assistant → MQTT → Node-RED → CODESYS (sw_1 = TRUE) → Toggle (WRONG!)
|
||||
```
|
||||
|
||||
### New Flow (Command-Based)
|
||||
```
|
||||
Zigbee Switch → MQTT → Node-RED → CODESYS (zigbee_sw1 = edge) → Toggle
|
||||
Home Assistant → MQTT → Node-RED → CODESYS (ha_l1_on = TRUE) → Set ON
|
||||
Home Assistant → MQTT → Node-RED → CODESYS (ha_l1_off = TRUE) → Set OFF
|
||||
```
|
||||
|
||||
### Node-RED Flow Example
|
||||
|
||||
**For Zigbee Switches**:
|
||||
```javascript
|
||||
// Detect button press (edge detection)
|
||||
if (msg.payload.action === "single") {
|
||||
// Send edge trigger to CODESYS
|
||||
msg.payload = {
|
||||
zigbee_sw1: true // Edge detected
|
||||
};
|
||||
return msg;
|
||||
}
|
||||
```
|
||||
|
||||
**For Home Assistant**:
|
||||
```javascript
|
||||
// Direct ON/OFF commands
|
||||
if (msg.payload === "ON") {
|
||||
msg.payload = {
|
||||
ha_l1_on: true,
|
||||
ha_l1_off: false
|
||||
};
|
||||
} else if (msg.payload === "OFF") {
|
||||
msg.payload = {
|
||||
ha_l1_on: false,
|
||||
ha_l1_off: true
|
||||
};
|
||||
}
|
||||
return msg;
|
||||
```
|
||||
|
||||
**Status Feedback to Home Assistant**:
|
||||
```javascript
|
||||
// Read status from CODESYS
|
||||
const status = msg.payload.l_1_status;
|
||||
// Publish to HA
|
||||
msg.topic = "homeassistant/light/room1_light1/state";
|
||||
msg.payload = status ? "ON" : "OFF";
|
||||
return msg;
|
||||
```
|
||||
|
||||
## Home Assistant Configuration
|
||||
|
||||
### MQTT Light Entity
|
||||
|
||||
```yaml
|
||||
light:
|
||||
- platform: mqtt
|
||||
name: "Room 1 Light 1"
|
||||
state_topic: "homeassistant/light/room1_light1/state"
|
||||
command_topic: "homeassistant/light/room1_light1/set"
|
||||
state_value_template: "{{ value_json.state }}"
|
||||
command_on_template: '{"state":"ON"}'
|
||||
command_off_template: '{"state":"OFF"}'
|
||||
qos: 1
|
||||
retain: true
|
||||
```
|
||||
|
||||
### Node-RED Flow for HA Integration
|
||||
|
||||
```
|
||||
[HA Command] → [Parse] → [Convert to CODESYS format] → [Network Variable]
|
||||
[CODESYS Status] → [Network Variable] → [Convert to HA format] → [HA State]
|
||||
```
|
||||
|
||||
## Benefits of Redesign
|
||||
|
||||
### 1. State Synchronization
|
||||
- ✅ HA always knows actual relay state
|
||||
- ✅ No state desynchronization
|
||||
- ✅ Reliable ON/OFF commands
|
||||
|
||||
### 2. Multiple Control Sources
|
||||
- ✅ HA uses set/reset commands
|
||||
- ✅ Zigbee switches use toggle (edge detection)
|
||||
- ✅ Both work simultaneously without conflicts
|
||||
|
||||
### 3. Status Feedback
|
||||
- ✅ Actual relay state read from EtherCAT
|
||||
- ✅ Hardware failure detection possible
|
||||
- ✅ Accurate status in Home Assistant
|
||||
|
||||
### 4. Better Debugging
|
||||
- ✅ Clear separation of commands
|
||||
- ✅ Can trace which source triggered action
|
||||
- ✅ Easier troubleshooting
|
||||
|
||||
### 5. Extensibility
|
||||
- ✅ Easy to add more control sources
|
||||
- ✅ Can add priority levels
|
||||
- ✅ Can add scheduling/automation
|
||||
|
||||
## Migration Path
|
||||
|
||||
### Step 1: Update Data Structures
|
||||
1. Modify `struct_switches` to include HA commands and Zigbee inputs
|
||||
2. Modify `struct_lights` to include status feedback
|
||||
3. Keep old structure temporarily for backward compatibility
|
||||
|
||||
### Step 2: Create New Function Blocks
|
||||
1. Implement `fb_lightControl` with new logic
|
||||
2. Update `fb_switch` to use new function blocks
|
||||
3. Test in simulation first
|
||||
|
||||
### Step 3: Update Node-RED Flows
|
||||
1. Modify flows to send HA commands (ON/OFF)
|
||||
2. Keep Zigbee flows with edge detection
|
||||
3. Add status feedback flows
|
||||
|
||||
### Step 4: Update Home Assistant
|
||||
1. Configure MQTT light entities
|
||||
2. Test control from HA
|
||||
3. Verify status updates
|
||||
|
||||
### Step 5: Testing
|
||||
1. Test HA control (ON/OFF)
|
||||
2. Test Zigbee switch control (toggle)
|
||||
3. Test status feedback
|
||||
4. Test both simultaneously
|
||||
|
||||
## Alternative: Simpler Approach (If Full Redesign Too Complex)
|
||||
|
||||
If the full redesign is too complex, here's a simpler improvement:
|
||||
|
||||
### Simplified Improvement
|
||||
|
||||
**Keep toggle logic but add state tracking**:
|
||||
|
||||
```iec
|
||||
FUNCTION_BLOCK fb_lightControl_Simple
|
||||
VAR_INPUT
|
||||
toggle: BOOL; // Toggle command (edge detected)
|
||||
set_on: BOOL; // Set ON command (edge detected)
|
||||
set_off: BOOL; // Set OFF command (edge detected)
|
||||
relay_status: BOOL; // Actual relay state
|
||||
END_VAR
|
||||
VAR_OUTPUT
|
||||
output: BOOL;
|
||||
status: BOOL;
|
||||
END_VAR
|
||||
VAR
|
||||
state: BOOL;
|
||||
r_trig_toggle: R_TRIG;
|
||||
r_trig_on: R_TRIG;
|
||||
r_trig_off: R_TRIG;
|
||||
END_VAR
|
||||
|
||||
// Edge detection
|
||||
r_trig_toggle(CLK := toggle);
|
||||
r_trig_on(CLK := set_on);
|
||||
r_trig_off(CLK := set_off);
|
||||
|
||||
// State machine
|
||||
IF r_trig_off.Q THEN
|
||||
state := FALSE;
|
||||
ELSIF r_trig_on.Q THEN
|
||||
state := TRUE;
|
||||
ELSIF r_trig_toggle.Q THEN
|
||||
state := NOT state;
|
||||
END_IF;
|
||||
|
||||
output := state;
|
||||
status := relay_status; // Read from actual relay
|
||||
```
|
||||
|
||||
**Data Structure**:
|
||||
```iec
|
||||
struct_switches:
|
||||
sw1_toggle: BOOL; // Zigbee toggle
|
||||
sw1_on: BOOL; // HA ON command
|
||||
sw1_off: BOOL; // HA OFF command
|
||||
// ... repeat for sw2-sw6
|
||||
```
|
||||
|
||||
This simpler approach:
|
||||
- ✅ Keeps existing structure mostly intact
|
||||
- ✅ Adds explicit ON/OFF commands for HA
|
||||
- ✅ Maintains toggle for Zigbee
|
||||
- ✅ Adds status feedback
|
||||
- ⚠️ Still requires data structure changes
|
||||
- ⚠️ Less clean than full redesign
|
||||
|
||||
## Recommendation
|
||||
|
||||
**I recommend the full redesign** because:
|
||||
1. Better long-term maintainability
|
||||
2. Clear separation of concerns
|
||||
3. Easier to extend and debug
|
||||
4. Proper state management
|
||||
5. Industry-standard approach
|
||||
|
||||
However, if time is limited, the **simplified approach** is a good compromise that addresses the main issues.
|
||||
|
||||
---
|
||||
|
||||
**Next Steps**:
|
||||
1. Review this recommendation
|
||||
2. Decide on full redesign vs. simplified approach
|
||||
3. Plan migration strategy
|
||||
4. Update Node-RED flows accordingly
|
||||
5. Test thoroughly before deploying
|
||||
873
docs/redesign/light-naming-configuration.md
Normal file
873
docs/redesign/light-naming-configuration.md
Normal file
@@ -0,0 +1,873 @@
|
||||
# Light Naming Configuration - Hybrid Structure
|
||||
|
||||
## Overview
|
||||
|
||||
This document defines the naming convention and structure for all lights in the home automation system using the Hybrid Structure (Option 4). This will serve as the basis for the redesign.
|
||||
|
||||
**Structure**: Room-organized in CODESYS, flattened for Home Assistant
|
||||
**Naming Convention**: `{room}_{function}` (e.g., `kitchen_main`, `master_bedroom_bedside_left`)
|
||||
|
||||
---
|
||||
|
||||
## Room-by-Room Light Configuration
|
||||
|
||||
### 1. Master Bedroom
|
||||
|
||||
**Room ID**: `master_bedroom`
|
||||
**Display Name**: "Master Bedroom"
|
||||
|
||||
**Lights**:
|
||||
- `main` - Main ceiling light
|
||||
- `bedside_left` - Left bedside lamp
|
||||
- `bedside_right` - Right bedside lamp
|
||||
- `closet` - Closet light
|
||||
- `reading` - Reading light (optional)
|
||||
- `ambient` - Ambient/atmospheric lighting (optional)
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.master_bedroom:
|
||||
main: struct_light_control;
|
||||
bedside_left: struct_light_control;
|
||||
bedside_right: struct_light_control;
|
||||
closet: struct_light_control;
|
||||
reading: struct_light_control; // Optional
|
||||
ambient: struct_light_control; // Optional
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.master_bedroom_main`
|
||||
- `light.master_bedroom_bedside_left`
|
||||
- `light.master_bedroom_bedside_right`
|
||||
- `light.master_bedroom_closet`
|
||||
- `light.master_bedroom_reading` (if used)
|
||||
- `light.master_bedroom_ambient` (if used)
|
||||
|
||||
---
|
||||
|
||||
### 2. Master Bathroom
|
||||
|
||||
**Room ID**: `master_bathroom`
|
||||
**Display Name**: "Master Bathroom"
|
||||
|
||||
**Lights**:
|
||||
- `main` - Main ceiling light
|
||||
- `mirror` - Mirror/vanity light
|
||||
- `shower` - Shower light
|
||||
- `night_light` - Night light (low brightness)
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.master_bathroom:
|
||||
main: struct_light_control;
|
||||
mirror: struct_light_control;
|
||||
shower: struct_light_control;
|
||||
night_light: struct_light_control;
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.master_bathroom_main`
|
||||
- `light.master_bathroom_mirror`
|
||||
- `light.master_bathroom_shower`
|
||||
- `light.master_bathroom_night_light`
|
||||
|
||||
---
|
||||
|
||||
### 3. Bedroom 1
|
||||
|
||||
**Room ID**: `bedroom_1`
|
||||
**Display Name**: "Bedroom 1"
|
||||
|
||||
**Lights**:
|
||||
- `main` - Main ceiling light
|
||||
- `bedside` - Bedside lamp
|
||||
- `desk` - Desk lamp (if applicable)
|
||||
- `closet` - Closet light (if applicable)
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.bedroom_1:
|
||||
main: struct_light_control;
|
||||
bedside: struct_light_control;
|
||||
desk: struct_light_control; // Optional
|
||||
closet: struct_light_control; // Optional
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.bedroom_1_main`
|
||||
- `light.bedroom_1_bedside`
|
||||
- `light.bedroom_1_desk` (if used)
|
||||
- `light.bedroom_1_closet` (if used)
|
||||
|
||||
---
|
||||
|
||||
### 4. Bedroom 2
|
||||
|
||||
**Room ID**: `bedroom_2`
|
||||
**Display Name**: "Bedroom 2"
|
||||
|
||||
**Lights**:
|
||||
- `main` - Main ceiling light
|
||||
- `bedside` - Bedside lamp
|
||||
- `desk` - Desk lamp (if applicable)
|
||||
- `closet` - Closet light (if applicable)
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.bedroom_2:
|
||||
main: struct_light_control;
|
||||
bedside: struct_light_control;
|
||||
desk: struct_light_control; // Optional
|
||||
closet: struct_light_control; // Optional
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.bedroom_2_main`
|
||||
- `light.bedroom_2_bedside`
|
||||
- `light.bedroom_2_desk` (if used)
|
||||
- `light.bedroom_2_closet` (if used)
|
||||
|
||||
---
|
||||
|
||||
### 5. Bathroom
|
||||
|
||||
**Room ID**: `bathroom`
|
||||
**Display Name**: "Bathroom"
|
||||
|
||||
**Lights**:
|
||||
- `main` - Main ceiling light
|
||||
- `mirror` - Mirror/vanity light
|
||||
- `night_light` - Night light
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.bathroom:
|
||||
main: struct_light_control;
|
||||
mirror: struct_light_control;
|
||||
night_light: struct_light_control;
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.bathroom_main`
|
||||
- `light.bathroom_mirror`
|
||||
- `light.bathroom_night_light`
|
||||
|
||||
---
|
||||
|
||||
### 6. Kitchen
|
||||
|
||||
**Room ID**: `kitchen`
|
||||
**Display Name**: "Kitchen"
|
||||
|
||||
**Lights**:
|
||||
- `main` - Main ceiling light
|
||||
- `under_cabinet` - Under cabinet task lighting
|
||||
- `island` - Island pendant light
|
||||
- `pantry` - Pantry light (if separate from pantry room)
|
||||
- `sink` - Sink area light
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.kitchen:
|
||||
main: struct_light_control;
|
||||
under_cabinet: struct_light_control;
|
||||
island: struct_light_control;
|
||||
pantry: struct_light_control; // If in kitchen
|
||||
sink: struct_light_control;
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.kitchen_main`
|
||||
- `light.kitchen_under_cabinet`
|
||||
- `light.kitchen_island`
|
||||
- `light.kitchen_pantry` (if used)
|
||||
- `light.kitchen_sink`
|
||||
|
||||
---
|
||||
|
||||
### 7. Living Room
|
||||
|
||||
**Room ID**: `living_room`
|
||||
**Display Name**: "Living Room"
|
||||
|
||||
**Lights**:
|
||||
- `main` - Main ceiling light
|
||||
- `reading` - Reading lamp
|
||||
- `tv` - TV area lighting
|
||||
- `accent` - Accent lighting
|
||||
- `fireplace` - Fireplace area lighting (if applicable)
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.living_room:
|
||||
main: struct_light_control;
|
||||
reading: struct_light_control;
|
||||
tv: struct_light_control;
|
||||
accent: struct_light_control;
|
||||
fireplace: struct_light_control; // Optional
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.living_room_main`
|
||||
- `light.living_room_reading`
|
||||
- `light.living_room_tv`
|
||||
- `light.living_room_accent`
|
||||
- `light.living_room_fireplace` (if used)
|
||||
|
||||
---
|
||||
|
||||
### 8. Dining Room
|
||||
|
||||
**Room ID**: `dining_room`
|
||||
**Display Name**: "Dining Room"
|
||||
|
||||
**Lights**:
|
||||
- `main` - Main chandelier/ceiling light
|
||||
- `ambient` - Ambient lighting
|
||||
- `buffet` - Buffet/sideboard lighting (if applicable)
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.dining_room:
|
||||
main: struct_light_control;
|
||||
ambient: struct_light_control;
|
||||
buffet: struct_light_control; // Optional
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.dining_room_main`
|
||||
- `light.dining_room_ambient`
|
||||
- `light.dining_room_buffet` (if used)
|
||||
|
||||
---
|
||||
|
||||
### 9. Hallway
|
||||
|
||||
**Room ID**: `hallway`
|
||||
**Display Name**: "Hallway"
|
||||
|
||||
**Lights**:
|
||||
- `main` - Main hallway light
|
||||
- `secondary` - Secondary hallway light (if long hallway)
|
||||
- `night_light` - Night light
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.hallway:
|
||||
main: struct_light_control;
|
||||
secondary: struct_light_control; // Optional
|
||||
night_light: struct_light_control;
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.hallway_main`
|
||||
- `light.hallway_secondary` (if used)
|
||||
- `light.hallway_night_light`
|
||||
|
||||
---
|
||||
|
||||
### 10. Pantry
|
||||
|
||||
**Room ID**: `pantry`
|
||||
**Display Name**: "Pantry"
|
||||
|
||||
**Lights**:
|
||||
- `main` - Main pantry light
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.pantry:
|
||||
main: struct_light_control;
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.pantry_main`
|
||||
|
||||
---
|
||||
|
||||
### 11. Entrance
|
||||
|
||||
**Room ID**: `entrance`
|
||||
**Display Name**: "Entrance"
|
||||
|
||||
**Lights**:
|
||||
- `main` - Main entrance light
|
||||
- `security` - Security/porch light
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.entrance:
|
||||
main: struct_light_control;
|
||||
security: struct_light_control;
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.entrance_main`
|
||||
- `light.entrance_security`
|
||||
|
||||
---
|
||||
|
||||
### 12. Guest WC
|
||||
|
||||
**Room ID**: `guest_wc`
|
||||
**Display Name**: "Guest WC"
|
||||
|
||||
**Lights**:
|
||||
- `main` - Main light
|
||||
- `night_light` - Night light
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.guest_wc:
|
||||
main: struct_light_control;
|
||||
night_light: struct_light_control;
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.guest_wc_main`
|
||||
- `light.guest_wc_night_light`
|
||||
|
||||
---
|
||||
|
||||
### 13. Outdoor Veranda
|
||||
|
||||
**Room ID**: `outdoor_veranda`
|
||||
**Display Name**: "Outdoor Veranda"
|
||||
|
||||
**Lights**:
|
||||
- `main` - Main veranda light
|
||||
- `ambient` - Ambient/atmospheric lighting
|
||||
- `security` - Security lighting
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.outdoor_veranda:
|
||||
main: struct_light_control;
|
||||
ambient: struct_light_control;
|
||||
security: struct_light_control;
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.outdoor_veranda_main`
|
||||
- `light.outdoor_veranda_ambient`
|
||||
- `light.outdoor_veranda_security`
|
||||
|
||||
---
|
||||
|
||||
### 14. Outdoor Front
|
||||
|
||||
**Room ID**: `outdoor_front`
|
||||
**Display Name**: "Outdoor Front"
|
||||
|
||||
**Lights**:
|
||||
- `porch` - Front porch light
|
||||
- `security` - Security light
|
||||
- `pathway` - Pathway lighting
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.outdoor_front:
|
||||
porch: struct_light_control;
|
||||
security: struct_light_control;
|
||||
pathway: struct_light_control;
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.outdoor_front_porch`
|
||||
- `light.outdoor_front_security`
|
||||
- `light.outdoor_front_pathway`
|
||||
|
||||
---
|
||||
|
||||
### 15. Outdoor Side
|
||||
|
||||
**Room ID**: `outdoor_side`
|
||||
**Display Name**: "Outdoor Side"
|
||||
|
||||
**Lights**:
|
||||
- `security` - Side security light
|
||||
- `pathway` - Side pathway lighting
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.outdoor_side:
|
||||
security: struct_light_control;
|
||||
pathway: struct_light_control;
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.outdoor_side_security`
|
||||
- `light.outdoor_side_pathway`
|
||||
|
||||
---
|
||||
|
||||
### 16. Outdoor Back
|
||||
|
||||
**Room ID**: `outdoor_back`
|
||||
**Display Name**: "Outdoor Back"
|
||||
|
||||
**Lights**:
|
||||
- `patio` - Patio/backyard light
|
||||
- `security` - Back security light
|
||||
- `garden` - Garden lighting (if applicable)
|
||||
|
||||
**CODESYS Structure**:
|
||||
```iec
|
||||
rooms.outdoor_back:
|
||||
patio: struct_light_control;
|
||||
security: struct_light_control;
|
||||
garden: struct_light_control; // Optional
|
||||
```
|
||||
|
||||
**Home Assistant Entities**:
|
||||
- `light.outdoor_back_patio`
|
||||
- `light.outdoor_back_security`
|
||||
- `light.outdoor_back_garden` (if used)
|
||||
|
||||
---
|
||||
|
||||
## Complete CODESYS Structure Definition
|
||||
|
||||
```iec
|
||||
TYPE struct_light_control :
|
||||
STRUCT
|
||||
// Control Commands
|
||||
ha_on: BOOL; // Home Assistant: Turn ON
|
||||
ha_off: BOOL; // Home Assistant: Turn OFF
|
||||
zigbee_toggle: BOOL; // Zigbee Switch: Toggle (edge detected)
|
||||
|
||||
// Status
|
||||
state: BOOL; // Current light state
|
||||
relay_status: BOOL; // Actual relay status (read from EtherCAT)
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
|
||||
TYPE struct_room_lights :
|
||||
STRUCT
|
||||
main: struct_light_control;
|
||||
secondary: struct_light_control;
|
||||
task: struct_light_control;
|
||||
ambient: struct_light_control;
|
||||
accent: struct_light_control;
|
||||
security: struct_light_control;
|
||||
// Room-specific lights defined per room
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
|
||||
VAR_GLOBAL
|
||||
rooms: STRUCT
|
||||
master_bedroom: STRUCT
|
||||
main: struct_light_control;
|
||||
bedside_left: struct_light_control;
|
||||
bedside_right: struct_light_control;
|
||||
closet: struct_light_control;
|
||||
reading: struct_light_control;
|
||||
ambient: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
master_bathroom: STRUCT
|
||||
main: struct_light_control;
|
||||
mirror: struct_light_control;
|
||||
shower: struct_light_control;
|
||||
night_light: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
bedroom_1: STRUCT
|
||||
main: struct_light_control;
|
||||
bedside: struct_light_control;
|
||||
desk: struct_light_control;
|
||||
closet: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
bedroom_2: STRUCT
|
||||
main: struct_light_control;
|
||||
bedside: struct_light_control;
|
||||
desk: struct_light_control;
|
||||
closet: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
bathroom: STRUCT
|
||||
main: struct_light_control;
|
||||
mirror: struct_light_control;
|
||||
night_light: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
kitchen: STRUCT
|
||||
main: struct_light_control;
|
||||
under_cabinet: struct_light_control;
|
||||
island: struct_light_control;
|
||||
pantry: struct_light_control;
|
||||
sink: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
living_room: STRUCT
|
||||
main: struct_light_control;
|
||||
reading: struct_light_control;
|
||||
tv: struct_light_control;
|
||||
accent: struct_light_control;
|
||||
fireplace: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
dining_room: STRUCT
|
||||
main: struct_light_control;
|
||||
ambient: struct_light_control;
|
||||
buffet: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
hallway: STRUCT
|
||||
main: struct_light_control;
|
||||
secondary: struct_light_control;
|
||||
night_light: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
pantry: STRUCT
|
||||
main: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
entrance: STRUCT
|
||||
main: struct_light_control;
|
||||
security: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
guest_wc: STRUCT
|
||||
main: struct_light_control;
|
||||
night_light: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
outdoor_veranda: STRUCT
|
||||
main: struct_light_control;
|
||||
ambient: struct_light_control;
|
||||
security: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
outdoor_front: STRUCT
|
||||
porch: struct_light_control;
|
||||
security: struct_light_control;
|
||||
pathway: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
outdoor_side: STRUCT
|
||||
security: struct_light_control;
|
||||
pathway: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
outdoor_back: STRUCT
|
||||
patio: struct_light_control;
|
||||
security: struct_light_control;
|
||||
garden: struct_light_control;
|
||||
END_STRUCT;
|
||||
END_STRUCT;
|
||||
END_VAR
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Light Function Types Reference
|
||||
|
||||
Use these standard function names for consistency:
|
||||
|
||||
| Function | Description | Typical Use |
|
||||
|----------|-------------|-------------|
|
||||
| `main` | Primary/ceiling light | Main illumination in room |
|
||||
| `secondary` | Secondary light | Additional main light |
|
||||
| `bedside_left` | Left bedside lamp | Bedroom bedside |
|
||||
| `bedside_right` | Right bedside lamp | Bedroom bedside |
|
||||
| `bedside` | Single bedside lamp | Single bed rooms |
|
||||
| `closet` | Closet light | Storage areas |
|
||||
| `desk` | Desk lamp | Study/work areas |
|
||||
| `reading` | Reading light | Reading areas |
|
||||
| `mirror` | Mirror/vanity light | Bathrooms |
|
||||
| `shower` | Shower light | Bathroom shower |
|
||||
| `night_light` | Night light | Low brightness |
|
||||
| `under_cabinet` | Under cabinet | Kitchen task lighting |
|
||||
| `island` | Island pendant | Kitchen island |
|
||||
| `sink` | Sink area light | Kitchen/bathroom |
|
||||
| `tv` | TV area lighting | Living room |
|
||||
| `accent` | Accent lighting | Decorative |
|
||||
| `ambient` | Ambient lighting | Atmospheric |
|
||||
| `fireplace` | Fireplace area | Living room |
|
||||
| `buffet` | Buffet/sideboard | Dining room |
|
||||
| `porch` | Porch light | Entrance |
|
||||
| `patio` | Patio light | Backyard |
|
||||
| `security` | Security light | Outdoor security |
|
||||
| `pathway` | Pathway lighting | Outdoor paths |
|
||||
| `garden` | Garden lighting | Outdoor garden |
|
||||
|
||||
---
|
||||
|
||||
## Water Boiler Control
|
||||
|
||||
### Water Boiler Structure
|
||||
|
||||
```iec
|
||||
TYPE struct_water_boiler :
|
||||
STRUCT
|
||||
// Control Commands
|
||||
ha_on: BOOL; // Home Assistant: Turn ON
|
||||
ha_off: BOOL; // Home Assistant: Turn OFF
|
||||
schedule_on: BOOL; // Scheduled ON (from automation)
|
||||
schedule_off: BOOL; // Scheduled OFF (from automation)
|
||||
|
||||
// Status
|
||||
state: BOOL; // Current boiler state (ON/OFF)
|
||||
relay_status: BOOL; // Actual relay status
|
||||
temperature: REAL; // Water temperature (if sensor available)
|
||||
|
||||
// Safety
|
||||
safety_override: BOOL; // Safety system override (read-only)
|
||||
error_state: BOOL; // Error state flag
|
||||
last_error: STRING; // Last error message
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
|
||||
VAR_GLOBAL
|
||||
water_boiler: struct_water_boiler;
|
||||
END_VAR
|
||||
```
|
||||
|
||||
### Water Boiler Function Block
|
||||
|
||||
```iec
|
||||
FUNCTION_BLOCK fb_waterBoiler
|
||||
VAR_INPUT
|
||||
// Control
|
||||
ha_on: BOOL;
|
||||
ha_off: BOOL;
|
||||
schedule_on: BOOL;
|
||||
schedule_off: BOOL;
|
||||
|
||||
// Sensors
|
||||
temperature: REAL; // Water temperature sensor
|
||||
pressure: REAL; // Water pressure (if available)
|
||||
|
||||
// Safety Inputs
|
||||
emergency_stop: BOOL; // Emergency stop button
|
||||
flow_sensor: BOOL; // Water flow sensor
|
||||
overtemp_sensor: BOOL; // Over-temperature sensor
|
||||
pressure_sensor: BOOL; // Pressure sensor (if available)
|
||||
|
||||
// Relay Output
|
||||
relay_output: BOOL; // Read actual relay state
|
||||
END_VAR
|
||||
VAR_OUTPUT
|
||||
relay_control: BOOL; // Control output to relay
|
||||
state: BOOL; // Current state
|
||||
relay_status: BOOL; // Actual relay status
|
||||
safety_override: BOOL; // Safety override active
|
||||
error_state: BOOL; // Error detected
|
||||
error_code: INT; // Error code
|
||||
error_message: STRING; // Error description
|
||||
END_VAR
|
||||
VAR
|
||||
// Internal State
|
||||
internal_state: BOOL;
|
||||
last_state: BOOL;
|
||||
|
||||
// Safety Timers
|
||||
max_on_time: TIME := T#8H; // Maximum ON time (8 hours)
|
||||
min_off_time: TIME := T#30M; // Minimum OFF time (30 minutes)
|
||||
on_timer: TON;
|
||||
off_timer: TON;
|
||||
|
||||
// Temperature Limits
|
||||
max_temp: REAL := 80.0; // Maximum temperature (°C)
|
||||
min_temp: REAL := 10.0; // Minimum temperature (°C)
|
||||
|
||||
// Safety Flags
|
||||
temp_ok: BOOL;
|
||||
pressure_ok: BOOL;
|
||||
flow_ok: BOOL;
|
||||
time_ok: BOOL;
|
||||
|
||||
// Edge Detection
|
||||
r_trig_ha_on: R_TRIG;
|
||||
r_trig_ha_off: R_TRIG;
|
||||
r_trig_schedule_on: R_TRIG;
|
||||
r_trig_schedule_off: R_TRIG;
|
||||
r_trig_emergency: R_TRIG;
|
||||
END_VAR
|
||||
```
|
||||
|
||||
### Safety Logic Implementation
|
||||
|
||||
```iec
|
||||
// Edge detection
|
||||
r_trig_ha_on(CLK := ha_on);
|
||||
r_trig_ha_off(CLK := ha_off);
|
||||
r_trig_schedule_on(CLK := schedule_on);
|
||||
r_trig_schedule_off(CLK := schedule_off);
|
||||
r_trig_emergency(CLK := emergency_stop);
|
||||
|
||||
// Safety Checks
|
||||
temp_ok := (temperature >= min_temp) AND (temperature <= max_temp);
|
||||
pressure_ok := pressure_sensor; // Assuming normally closed safety switch
|
||||
flow_ok := flow_sensor; // Water flow detected
|
||||
time_ok := NOT on_timer.Q; // Not exceeded max ON time
|
||||
|
||||
// Safety Override (highest priority)
|
||||
IF r_trig_emergency.Q OR NOT temp_ok OR NOT pressure_ok THEN
|
||||
safety_override := TRUE;
|
||||
internal_state := FALSE;
|
||||
error_state := TRUE;
|
||||
error_code := 1; // Safety override
|
||||
error_message := 'Safety override active';
|
||||
ELSIF NOT flow_ok AND internal_state THEN
|
||||
// No water flow but boiler is on - turn off after delay
|
||||
off_timer(IN := TRUE, PT := T#5M); // 5 minute delay
|
||||
IF off_timer.Q THEN
|
||||
internal_state := FALSE;
|
||||
error_state := TRUE;
|
||||
error_code := 2; // No flow
|
||||
error_message := 'No water flow detected';
|
||||
END_IF;
|
||||
ELSIF NOT time_ok THEN
|
||||
// Maximum ON time exceeded
|
||||
internal_state := FALSE;
|
||||
error_state := TRUE;
|
||||
error_code := 3; // Time exceeded
|
||||
error_message := 'Maximum ON time exceeded';
|
||||
ELSE
|
||||
safety_override := FALSE;
|
||||
error_state := FALSE;
|
||||
error_code := 0;
|
||||
error_message := '';
|
||||
END_IF;
|
||||
|
||||
// Control Logic (only if safety OK)
|
||||
IF NOT safety_override THEN
|
||||
// Priority: Emergency OFF > Manual OFF > Scheduled OFF > Manual ON > Scheduled ON
|
||||
IF r_trig_ha_off.Q OR r_trig_schedule_off.Q THEN
|
||||
internal_state := FALSE;
|
||||
ELSIF r_trig_ha_on.Q OR r_trig_schedule_on.Q THEN
|
||||
IF temp_ok AND flow_ok AND time_ok THEN
|
||||
internal_state := TRUE;
|
||||
on_timer(IN := internal_state, PT := max_on_time);
|
||||
END_IF;
|
||||
END_IF;
|
||||
END_IF;
|
||||
|
||||
// Update timers
|
||||
on_timer(IN := internal_state AND NOT safety_override, PT := max_on_time);
|
||||
off_timer(IN := NOT internal_state, PT := min_off_time);
|
||||
|
||||
// Output Assignment
|
||||
relay_control := internal_state AND NOT safety_override;
|
||||
state := internal_state;
|
||||
relay_status := relay_output; // Read from actual relay
|
||||
```
|
||||
|
||||
### Safety Measures
|
||||
|
||||
#### 1. Temperature Protection
|
||||
- **Max Temperature**: 80°C (configurable)
|
||||
- **Min Temperature**: 10°C (freeze protection)
|
||||
- **Action**: Auto-shutoff if temperature exceeds limits
|
||||
|
||||
#### 2. Time-Based Protection
|
||||
- **Max ON Time**: 8 hours (prevents continuous operation)
|
||||
- **Min OFF Time**: 30 minutes (prevents rapid cycling)
|
||||
- **Action**: Force OFF after max time, prevent ON during min OFF time
|
||||
|
||||
#### 3. Flow Detection
|
||||
- **Flow Sensor**: Monitors water flow
|
||||
- **Action**: Shut off if no flow detected for 5 minutes (dry-run protection)
|
||||
|
||||
#### 4. Emergency Stop
|
||||
- **Emergency Button**: Physical emergency stop
|
||||
- **Action**: Immediate shutdown, requires manual reset
|
||||
|
||||
#### 5. Pressure Protection
|
||||
- **Pressure Sensor**: Monitors system pressure
|
||||
- **Action**: Shut off if pressure abnormal
|
||||
|
||||
#### 6. State Monitoring
|
||||
- **Relay Status**: Read actual relay state
|
||||
- **Action**: Detect relay failures, report status
|
||||
|
||||
#### 7. Error Reporting
|
||||
- **Error Codes**:
|
||||
- 0: No error
|
||||
- 1: Safety override
|
||||
- 2: No flow
|
||||
- 3: Time exceeded
|
||||
- 4: Temperature fault
|
||||
- 5: Pressure fault
|
||||
- **Error Messages**: Human-readable descriptions
|
||||
|
||||
### Water Boiler Network Variable
|
||||
|
||||
```iec
|
||||
// Sent to Node-RED (Status)
|
||||
VAR_GLOBAL
|
||||
boiler_status: struct_water_boiler;
|
||||
END_VAR
|
||||
|
||||
// Received from Node-RED (Commands)
|
||||
VAR_GLOBAL
|
||||
boiler_commands: STRUCT
|
||||
ha_on: BOOL;
|
||||
ha_off: BOOL;
|
||||
schedule_on: BOOL;
|
||||
schedule_off: BOOL;
|
||||
END_STRUCT;
|
||||
END_VAR
|
||||
```
|
||||
|
||||
### Home Assistant Integration
|
||||
|
||||
**Entity Type**: `switch` or `water_heater`
|
||||
|
||||
```yaml
|
||||
switch:
|
||||
- platform: mqtt
|
||||
name: "Water Boiler"
|
||||
unique_id: "water_boiler"
|
||||
state_topic: "homeassistant/water_boiler/state"
|
||||
command_topic: "homeassistant/water_boiler/set"
|
||||
state_value_template: "{{ value_json.state }}"
|
||||
command_on_template: '{"ha_on":true}'
|
||||
command_off_template: '{"ha_off":true}'
|
||||
qos: 1
|
||||
retain: true
|
||||
|
||||
sensor:
|
||||
- platform: mqtt
|
||||
name: "Water Boiler Temperature"
|
||||
state_topic: "homeassistant/water_boiler/state"
|
||||
value_template: "{{ value_json.temperature }}"
|
||||
unit_of_measurement: "°C"
|
||||
|
||||
- platform: mqtt
|
||||
name: "Water Boiler Error"
|
||||
state_topic: "homeassistant/water_boiler/state"
|
||||
value_template: "{{ value_json.error_message }}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
### Light Configuration
|
||||
- **Total Rooms**: 16 (15 indoor + outdoor areas)
|
||||
- **Total Lights**: ~60-70 lights (varies by room)
|
||||
- **Structure**: Hybrid (room-organized in CODESYS, flat in HA)
|
||||
- **Naming**: `{room}_{function}` format
|
||||
|
||||
### Water Boiler
|
||||
- **Control**: ON/OFF with scheduling
|
||||
- **Safety**: 7 safety measures implemented
|
||||
- **Monitoring**: Temperature, flow, pressure, time
|
||||
- **Error Reporting**: Comprehensive error codes and messages
|
||||
|
||||
### Next Steps
|
||||
1. Review and modify light names per room based on actual installation
|
||||
2. Map lights to relay outputs
|
||||
3. Implement new structure in CODESYS
|
||||
4. Update Node-RED flows
|
||||
5. Configure Home Assistant entities
|
||||
6. Test all safety measures for water boiler
|
||||
|
||||
---
|
||||
|
||||
**Document Status**: Template - Modify with actual light configuration
|
||||
**Last Updated**: January 27, 2026
|
||||
239
docs/redesign/redesign-implementation-roadmap.md
Normal file
239
docs/redesign/redesign-implementation-roadmap.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# Redesign Implementation Roadmap
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a step-by-step roadmap for implementing the redesigned structure based on the light naming configuration.
|
||||
|
||||
## Phase 1: Configuration & Planning
|
||||
|
||||
### Step 1.1: Review Light Naming Configuration
|
||||
- [ ] Review `light-naming-configuration.md`
|
||||
- [ ] Modify light names per room based on actual installation
|
||||
- [ ] Remove unused lights from structure
|
||||
- [ ] Add any missing lights
|
||||
- [ ] Document relay-to-light mapping
|
||||
|
||||
### Step 1.2: Map Relays to Lights
|
||||
- [ ] Create mapping table: Relay # → Room → Light Name
|
||||
- [ ] Document in `relay-mapping.md`
|
||||
- [ ] Verify all relays are accounted for
|
||||
|
||||
**Example Mapping**:
|
||||
```
|
||||
Relay 1 → kitchen → main
|
||||
Relay 2 → kitchen → under_cabinet
|
||||
Relay 3 → kitchen → island
|
||||
Relay 4 → master_bedroom → main
|
||||
Relay 5 → master_bedroom → bedside_left
|
||||
...
|
||||
```
|
||||
|
||||
### Step 1.3: Water Boiler Configuration
|
||||
- [ ] Review water boiler safety requirements
|
||||
- [ ] Configure temperature limits
|
||||
- [ ] Configure time limits (max ON, min OFF)
|
||||
- [ ] Identify sensor inputs (temperature, flow, pressure)
|
||||
- [ ] Map boiler relay output
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: CODESYS Structure Implementation
|
||||
|
||||
### Step 2.1: Create New Data Structures
|
||||
- [ ] Create `struct_light_control` type
|
||||
- [ ] Create `struct_water_boiler` type
|
||||
- [ ] Create room-specific structures
|
||||
- [ ] Create global `rooms` structure
|
||||
|
||||
### Step 2.2: Create Function Blocks
|
||||
- [ ] Create `fb_lightControl` function block
|
||||
- [ ] Create `fb_waterBoiler` function block
|
||||
- [ ] Test function blocks in simulation
|
||||
|
||||
### Step 2.3: Update Network Variables
|
||||
- [ ] Update `NVL_Sender` with new structure
|
||||
- [ ] Update `NVL_Receiver` with new structure
|
||||
- [ ] Add water boiler network variables
|
||||
- [ ] Configure network variable properties
|
||||
|
||||
### Step 2.4: Implement Control Logic
|
||||
- [ ] Replace `fb_switch` with new structure
|
||||
- [ ] Implement light control per room
|
||||
- [ ] Implement water boiler control
|
||||
- [ ] Add relay output mapping
|
||||
- [ ] Add relay status readback
|
||||
|
||||
### Step 2.5: Testing
|
||||
- [ ] Test in simulation
|
||||
- [ ] Test individual light control
|
||||
- [ ] Test water boiler control
|
||||
- [ ] Test safety measures
|
||||
- [ ] Verify network variable transmission
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Node-RED Integration
|
||||
|
||||
### Step 3.1: Update Network Variable Nodes
|
||||
- [ ] Update CODESYS network variable nodes
|
||||
- [ ] Configure new variable structure
|
||||
- [ ] Test bidirectional communication
|
||||
|
||||
### Step 3.2: Create Transformation Functions
|
||||
- [ ] Create function to flatten room structure for HA
|
||||
- [ ] Create function to convert HA commands to CODESYS format
|
||||
- [ ] Create function for Zigbee edge detection
|
||||
- [ ] Test transformations
|
||||
|
||||
### Step 3.3: Update MQTT Flows
|
||||
- [ ] Update MQTT topics to new naming convention
|
||||
- [ ] Configure Home Assistant auto-discovery
|
||||
- [ ] Update Zigbee switch flows
|
||||
- [ ] Add water boiler MQTT flows
|
||||
|
||||
### Step 3.4: Testing
|
||||
- [ ] Test HA → CODESYS commands
|
||||
- [ ] Test Zigbee → CODESYS commands
|
||||
- [ ] Test CODESYS → HA status updates
|
||||
- [ ] Test water boiler control
|
||||
- [ ] Verify MQTT message flow
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Home Assistant Configuration
|
||||
|
||||
### Step 4.1: Entity Configuration
|
||||
- [ ] Create light entities for all lights
|
||||
- [ ] Configure entity names and icons
|
||||
- [ ] Set up areas/rooms in HA
|
||||
- [ ] Create water boiler entity
|
||||
|
||||
### Step 4.2: Dashboard Setup
|
||||
- [ ] Create lighting dashboard
|
||||
- [ ] Group lights by room
|
||||
- [ ] Add water boiler control
|
||||
- [ ] Add status indicators
|
||||
|
||||
### Step 4.3: Automations
|
||||
- [ ] Update existing automations
|
||||
- [ ] Create new automations if needed
|
||||
- [ ] Test automations
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Migration & Deployment
|
||||
|
||||
### Step 5.1: Backup Current System
|
||||
- [ ] Backup CODESYS project
|
||||
- [ ] Export Node-RED flows
|
||||
- [ ] Backup Home Assistant configuration
|
||||
- [ ] Document current state
|
||||
|
||||
### Step 5.2: Parallel Testing
|
||||
- [ ] Deploy new structure in test mode
|
||||
- [ ] Run parallel with old system
|
||||
- [ ] Compare behavior
|
||||
- [ ] Fix any issues
|
||||
|
||||
### Step 5.3: Gradual Migration
|
||||
- [ ] Migrate one room at a time
|
||||
- [ ] Test each room thoroughly
|
||||
- [ ] Migrate water boiler
|
||||
- [ ] Complete migration
|
||||
|
||||
### Step 5.4: Validation
|
||||
- [ ] Test all lights from HA
|
||||
- [ ] Test all lights from Zigbee switches
|
||||
- [ ] Verify status feedback
|
||||
- [ ] Test water boiler control
|
||||
- [ ] Test all safety measures
|
||||
- [ ] Verify no regressions
|
||||
|
||||
---
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
### CODESYS
|
||||
- [ ] New data structures defined
|
||||
- [ ] Function blocks created and tested
|
||||
- [ ] Network variables updated
|
||||
- [ ] Control logic implemented
|
||||
- [ ] Relay mapping configured
|
||||
- [ ] Status readback implemented
|
||||
- [ ] Water boiler safety measures implemented
|
||||
- [ ] Code tested in simulation
|
||||
|
||||
### Node-RED
|
||||
- [ ] Network variable nodes updated
|
||||
- [ ] Transformation functions created
|
||||
- [ ] MQTT flows updated
|
||||
- [ ] HA auto-discovery configured
|
||||
- [ ] Zigbee integration updated
|
||||
- [ ] Water boiler flows added
|
||||
- [ ] All flows tested
|
||||
|
||||
### Home Assistant
|
||||
- [ ] All light entities created
|
||||
- [ ] Water boiler entity created
|
||||
- [ ] Areas/rooms configured
|
||||
- [ ] Dashboard updated
|
||||
- [ ] Automations updated
|
||||
- [ ] All entities tested
|
||||
|
||||
### Documentation
|
||||
- [ ] Light naming configuration finalized
|
||||
- [ ] Relay mapping documented
|
||||
- [ ] Network variable structure documented
|
||||
- [ ] MQTT topics documented
|
||||
- [ ] Safety measures documented
|
||||
- [ ] Troubleshooting guide updated
|
||||
|
||||
---
|
||||
|
||||
## Key Files Reference
|
||||
|
||||
1. **Light Configuration**: `light-naming-configuration.md`
|
||||
2. **Structure Analysis**: `structure-redesign-analysis.md`
|
||||
3. **Visual Comparison**: `structure-comparison-visual.md`
|
||||
4. **Function Block Redesign**: `fb_switch-redesign-recommendation.md`
|
||||
5. **This Roadmap**: `redesign-implementation-roadmap.md`
|
||||
|
||||
---
|
||||
|
||||
## Estimated Timeline
|
||||
|
||||
- **Phase 1** (Planning): 1-2 days
|
||||
- **Phase 2** (CODESYS): 2-3 days
|
||||
- **Phase 3** (Node-RED): 1-2 days
|
||||
- **Phase 4** (Home Assistant): 1 day
|
||||
- **Phase 5** (Migration): 2-3 days
|
||||
|
||||
**Total**: ~7-11 days (depending on complexity and testing)
|
||||
|
||||
---
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
### Risks
|
||||
1. **Network Variable Changes**: May break existing Node-RED flows
|
||||
- **Mitigation**: Test thoroughly, have rollback plan
|
||||
|
||||
2. **State Synchronization**: During migration, states may be inconsistent
|
||||
- **Mitigation**: Migrate during low-usage period, verify all states
|
||||
|
||||
3. **Water Boiler Safety**: Critical system, must work correctly
|
||||
- **Mitigation**: Extensive testing, manual override available
|
||||
|
||||
4. **Home Assistant Entities**: May need to recreate entities
|
||||
- **Mitigation**: Use unique_id to preserve entity history
|
||||
|
||||
### Rollback Plan
|
||||
- Keep old CODESYS project as backup
|
||||
- Keep old Node-RED flows as backup
|
||||
- Document rollback procedure
|
||||
- Test rollback procedure
|
||||
|
||||
---
|
||||
|
||||
**Status**: Planning Phase
|
||||
**Next Step**: Review and modify `light-naming-configuration.md` with actual light configuration
|
||||
101
docs/redesign/redesign-summary.md
Normal file
101
docs/redesign/redesign-summary.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# Redesign Summary - Quick Reference
|
||||
|
||||
## What We're Changing
|
||||
|
||||
### Current Structure → New Structure
|
||||
|
||||
**Before**:
|
||||
- Room-based with generic `l_1`, `l_2` names
|
||||
- Fixed 6 lights per room
|
||||
- Toggle-based control
|
||||
- No status feedback from relays
|
||||
|
||||
**After**:
|
||||
- Room-based in CODESYS, flat in Home Assistant
|
||||
- Descriptive names: `kitchen_main`, `master_bedroom_bedside_left`
|
||||
- Command-based control (ON/OFF for HA, toggle for Zigbee)
|
||||
- Actual relay status feedback
|
||||
- Water boiler with comprehensive safety
|
||||
|
||||
---
|
||||
|
||||
## Key Documents
|
||||
|
||||
1. **`light-naming-configuration.md`** ⭐ **START HERE**
|
||||
- Complete light naming for all 16 rooms
|
||||
- Water boiler control structure
|
||||
- Safety measures
|
||||
- **Action**: Review and modify with your actual lights
|
||||
|
||||
2. **`redesign-implementation-roadmap.md`**
|
||||
- Step-by-step implementation guide
|
||||
- Phase-by-phase checklist
|
||||
- Timeline estimates
|
||||
|
||||
3. **`structure-redesign-analysis.md`**
|
||||
- Detailed analysis of structure options
|
||||
- Why Option 4 (Hybrid) was chosen
|
||||
|
||||
4. **`fb_switch-redesign-recommendation.md`**
|
||||
- Function block redesign details
|
||||
- Control logic improvements
|
||||
|
||||
---
|
||||
|
||||
## Quick Structure Reference
|
||||
|
||||
### Light Naming Convention
|
||||
```
|
||||
Format: {room}_{function}
|
||||
|
||||
Examples:
|
||||
- kitchen_main
|
||||
- master_bedroom_bedside_left
|
||||
- outdoor_front_security
|
||||
```
|
||||
|
||||
### Function Types
|
||||
- `main` - Primary light
|
||||
- `bedside_left/right` - Bedside lamps
|
||||
- `under_cabinet` - Task lighting
|
||||
- `security` - Security lighting
|
||||
- `ambient` - Atmospheric lighting
|
||||
- etc.
|
||||
|
||||
### CODESYS Access
|
||||
```iec
|
||||
rooms.kitchen.main.ha_on := TRUE;
|
||||
rooms.master_bedroom.bedside_left.state;
|
||||
```
|
||||
|
||||
### Home Assistant Entity
|
||||
```
|
||||
light.kitchen_main
|
||||
light.master_bedroom_bedside_left
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Water Boiler Safety Features
|
||||
|
||||
1. ✅ **Temperature Protection** (max 80°C, min 10°C)
|
||||
2. ✅ **Time Limits** (max 8h ON, min 30m OFF)
|
||||
3. ✅ **Flow Detection** (shut off if no flow)
|
||||
4. ✅ **Emergency Stop** (immediate shutdown)
|
||||
5. ✅ **Pressure Protection** (if sensor available)
|
||||
6. ✅ **State Monitoring** (relay status readback)
|
||||
7. ✅ **Error Reporting** (comprehensive error codes)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Review** `light-naming-configuration.md`
|
||||
2. **Modify** light names per room based on actual installation
|
||||
3. **Map** relays to lights
|
||||
4. **Start** Phase 1 of implementation roadmap
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready for configuration review
|
||||
**Priority**: Review and customize light names first
|
||||
362
docs/redesign/structure-comparison-visual.md
Normal file
362
docs/redesign/structure-comparison-visual.md
Normal file
@@ -0,0 +1,362 @@
|
||||
# Structure Comparison - Visual Guide
|
||||
|
||||
## Current Structure (Room-Centric)
|
||||
|
||||
```
|
||||
CODESYS:
|
||||
┌─────────────────────────────────────┐
|
||||
│ masterBedroom: fb_switch │
|
||||
│ ├─ l_1 (Light 1) │
|
||||
│ ├─ l_2 (Light 2) │
|
||||
│ ├─ l_3 (Light 3) │
|
||||
│ ├─ l_4 (Light 4) │
|
||||
│ ├─ l_5 (Light 5) │
|
||||
│ └─ l_6 (Light 6) │
|
||||
└─────────────────────────────────────┘
|
||||
|
||||
Network Variable:
|
||||
l_masterBedroom.l_1
|
||||
l_masterBedroom.l_2
|
||||
...
|
||||
|
||||
Home Assistant:
|
||||
light.master_bedroom_l1
|
||||
light.master_bedroom_l2
|
||||
light.master_bedroom_l3
|
||||
...
|
||||
```
|
||||
|
||||
**Problems**:
|
||||
- ❌ Generic names (l_1, l_2)
|
||||
- ❌ Fixed 6 lights per room
|
||||
- ❌ Wasted space (most rooms don't use all 6)
|
||||
- ❌ Hard to identify which light is which
|
||||
|
||||
---
|
||||
|
||||
## Option 1: Flat Light-Centric
|
||||
|
||||
```
|
||||
CODESYS:
|
||||
┌─────────────────────────────────────┐
|
||||
│ lights: struct_all_lights │
|
||||
│ ├─ kitchen_main │
|
||||
│ ├─ kitchen_under_cabinet │
|
||||
│ ├─ master_bedroom_main │
|
||||
│ ├─ master_bedroom_bedside_left │
|
||||
│ ├─ master_bedroom_bedside_right │
|
||||
│ └─ ... (all lights flat) │
|
||||
└─────────────────────────────────────┘
|
||||
|
||||
Network Variable:
|
||||
lights.kitchen_main.on
|
||||
lights.kitchen_main.state
|
||||
lights.master_bedroom_main.on
|
||||
...
|
||||
|
||||
Home Assistant:
|
||||
light.kitchen_main
|
||||
light.kitchen_under_cabinet
|
||||
light.master_bedroom_main
|
||||
light.master_bedroom_bedside_left
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Clear, descriptive names
|
||||
- ✅ Easy to find lights
|
||||
- ✅ No wasted space
|
||||
- ✅ Perfect for HA organization
|
||||
|
||||
---
|
||||
|
||||
## Option 4: Hybrid (Recommended)
|
||||
|
||||
```
|
||||
CODESYS (Room-organized):
|
||||
┌─────────────────────────────────────┐
|
||||
│ rooms: struct_rooms │
|
||||
│ ├─ kitchen │
|
||||
│ │ ├─ main │
|
||||
│ │ ├─ under_cabinet │
|
||||
│ │ └─ island │
|
||||
│ ├─ master_bedroom │
|
||||
│ │ ├─ main │
|
||||
│ │ ├─ bedside_left │
|
||||
│ │ └─ bedside_right │
|
||||
│ └─ ... │
|
||||
└─────────────────────────────────────┘
|
||||
|
||||
Network Variable:
|
||||
rooms.kitchen.main.on
|
||||
rooms.kitchen.main.state
|
||||
rooms.master_bedroom.main.on
|
||||
...
|
||||
|
||||
Node-RED (Flattened):
|
||||
kitchen_main → HA
|
||||
kitchen_under_cabinet → HA
|
||||
master_bedroom_main → HA
|
||||
master_bedroom_bedside_left → HA
|
||||
|
||||
Home Assistant:
|
||||
light.kitchen_main
|
||||
light.kitchen_under_cabinet
|
||||
light.master_bedroom_main
|
||||
light.master_bedroom_bedside_left
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Organized in CODESYS (by room)
|
||||
- ✅ Flat in Home Assistant (by light)
|
||||
- ✅ Descriptive names
|
||||
- ✅ Easy to add lights
|
||||
- ✅ Best of both worlds
|
||||
|
||||
---
|
||||
|
||||
## Real-World Example Comparison
|
||||
|
||||
### Scenario: Kitchen with 3 lights
|
||||
|
||||
**Current Structure**:
|
||||
```iec
|
||||
kitchen: fb_switch
|
||||
l_1 = ??? (which light?)
|
||||
l_2 = ??? (which light?)
|
||||
l_3 = ??? (which light?)
|
||||
l_4 = unused
|
||||
l_5 = unused
|
||||
l_6 = unused
|
||||
```
|
||||
|
||||
**Hybrid Structure**:
|
||||
```iec
|
||||
rooms.kitchen:
|
||||
main = Main ceiling light
|
||||
under_cabinet = Under cabinet lights
|
||||
island = Island pendant
|
||||
(no unused slots)
|
||||
```
|
||||
|
||||
**Home Assistant**:
|
||||
```
|
||||
Current:
|
||||
light.kitchen_l1 ← What is this?
|
||||
light.kitchen_l2 ← What is this?
|
||||
light.kitchen_l3 ← What is this?
|
||||
|
||||
Hybrid:
|
||||
light.kitchen_main ← Clear!
|
||||
light.kitchen_under_cabinet ← Clear!
|
||||
light.kitchen_island ← Clear!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MQTT Topic Comparison
|
||||
|
||||
### Current
|
||||
```
|
||||
homeassistant/light/master_bedroom_l1/state
|
||||
homeassistant/light/master_bedroom_l2/state
|
||||
homeassistant/light/kitchen_l1/state
|
||||
```
|
||||
|
||||
**Problems**: Generic, hard to identify
|
||||
|
||||
### Hybrid
|
||||
```
|
||||
homeassistant/light/kitchen_main/state
|
||||
homeassistant/light/kitchen_under_cabinet/state
|
||||
homeassistant/light/master_bedroom_main/state
|
||||
homeassistant/light/master_bedroom_bedside_left/state
|
||||
```
|
||||
|
||||
**Benefits**: Self-documenting, clear purpose
|
||||
|
||||
---
|
||||
|
||||
## Home Assistant Dashboard Comparison
|
||||
|
||||
### Current
|
||||
```
|
||||
Kitchen
|
||||
├─ Light 1 ← What is this?
|
||||
├─ Light 2 ← What is this?
|
||||
└─ Light 3 ← What is this?
|
||||
|
||||
Master Bedroom
|
||||
├─ Light 1 ← What is this?
|
||||
├─ Light 2 ← What is this?
|
||||
└─ Light 3 ← What is this?
|
||||
```
|
||||
|
||||
### Hybrid
|
||||
```
|
||||
Kitchen
|
||||
├─ Main Light
|
||||
├─ Under Cabinet
|
||||
└─ Island
|
||||
|
||||
Master Bedroom
|
||||
├─ Main Light
|
||||
├─ Bedside Left
|
||||
└─ Bedside Right
|
||||
```
|
||||
|
||||
**Much clearer!**
|
||||
|
||||
---
|
||||
|
||||
## Network Variable Efficiency
|
||||
|
||||
### Current
|
||||
- 15 rooms × 6 lights = 90 potential lights
|
||||
- Most rooms use 2-3 lights
|
||||
- **Waste**: ~60 unused light slots
|
||||
- **Network traffic**: Sends all 90 values every 50ms
|
||||
|
||||
### Hybrid
|
||||
- Only define lights that exist
|
||||
- Kitchen: 3 lights (not 6)
|
||||
- Master Bedroom: 3 lights (not 6)
|
||||
- **Efficiency**: ~50% less network traffic
|
||||
- **Clarity**: Only relevant data
|
||||
|
||||
---
|
||||
|
||||
## Scalability Comparison
|
||||
|
||||
### Adding a New Light
|
||||
|
||||
**Current**:
|
||||
1. Find unused `l_X` slot in room
|
||||
2. Hope it's available
|
||||
3. Update documentation
|
||||
4. Update HA manually
|
||||
|
||||
**Hybrid**:
|
||||
1. Add `new_light: struct_light_control` to room
|
||||
2. Done! Auto-discovered in HA
|
||||
|
||||
### Adding a New Room
|
||||
|
||||
**Current**:
|
||||
1. Add new room structure
|
||||
2. Add all 6 light slots (even if unused)
|
||||
3. Update network variables
|
||||
4. Update HA manually
|
||||
|
||||
**Hybrid**:
|
||||
1. Add room with only needed lights
|
||||
2. Done! Auto-discovered in HA
|
||||
|
||||
---
|
||||
|
||||
## Implementation Example
|
||||
|
||||
### Hybrid Structure in CODESYS
|
||||
|
||||
```iec
|
||||
TYPE struct_light_control :
|
||||
STRUCT
|
||||
on: BOOL;
|
||||
off: BOOL;
|
||||
toggle: BOOL;
|
||||
state: BOOL;
|
||||
relay_status: BOOL;
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
|
||||
TYPE struct_room_lights :
|
||||
STRUCT
|
||||
main: struct_light_control;
|
||||
secondary: struct_light_control;
|
||||
task: struct_light_control;
|
||||
ambient: struct_light_control;
|
||||
accent: struct_light_control;
|
||||
security: struct_light_control;
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
|
||||
VAR_GLOBAL
|
||||
rooms: STRUCT
|
||||
kitchen: STRUCT
|
||||
main: struct_light_control;
|
||||
under_cabinet: struct_light_control;
|
||||
island: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
master_bedroom: STRUCT
|
||||
main: struct_light_control;
|
||||
bedside_left: struct_light_control;
|
||||
bedside_right: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
// ... other rooms
|
||||
END_STRUCT;
|
||||
END_VAR
|
||||
```
|
||||
|
||||
### Node-RED Transformation
|
||||
|
||||
```javascript
|
||||
// Transform room-based to flat structure for HA
|
||||
function transformToHA(msg) {
|
||||
const rooms = msg.payload.rooms;
|
||||
const result = {};
|
||||
|
||||
for (const [roomName, roomLights] of Object.entries(rooms)) {
|
||||
for (const [lightName, lightControl] of Object.entries(roomLights)) {
|
||||
const lightId = `${roomName}_${lightName}`;
|
||||
result[lightId] = {
|
||||
on: lightControl.on,
|
||||
off: lightControl.off,
|
||||
state: lightControl.state,
|
||||
status: lightControl.relay_status
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
return { payload: result };
|
||||
}
|
||||
```
|
||||
|
||||
### Home Assistant Auto-Discovery
|
||||
|
||||
```yaml
|
||||
# Node-RED publishes this automatically
|
||||
homeassistant/light/kitchen_main/config:
|
||||
name: "Kitchen Main"
|
||||
unique_id: "kitchen_main"
|
||||
state_topic: "homeassistant/light/kitchen_main/state"
|
||||
command_topic: "homeassistant/light/kitchen_main/set"
|
||||
state_value_template: "{{ value_json.state }}"
|
||||
command_on_template: '{"on":true}'
|
||||
command_off_template: '{"off":true}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recommendation Summary
|
||||
|
||||
**Use Hybrid Structure (Option 4)** because:
|
||||
|
||||
1. ✅ **Best Organization**: Room-based in CODESYS, flat in HA
|
||||
2. ✅ **Clear Naming**: `kitchen_main` vs `l_1`
|
||||
3. ✅ **Efficiency**: Only define existing lights
|
||||
4. ✅ **Scalability**: Easy to add lights/rooms
|
||||
5. ✅ **Maintainability**: Self-documenting structure
|
||||
6. ✅ **HA Integration**: Perfect for Home Assistant
|
||||
7. ✅ **Future-Proof**: Easy to extend
|
||||
|
||||
**Key Changes**:
|
||||
- Replace `l_1`, `l_2` with descriptive names
|
||||
- Use function-based naming: `main`, `secondary`, `task`, etc.
|
||||
- Flatten structure in Node-RED for HA
|
||||
- Only define lights that exist
|
||||
- Add metadata for better organization
|
||||
|
||||
---
|
||||
|
||||
**See**: [Full Structure Redesign Analysis](structure-redesign-analysis.md) for complete details.
|
||||
538
docs/redesign/structure-redesign-analysis.md
Normal file
538
docs/redesign/structure-redesign-analysis.md
Normal file
@@ -0,0 +1,538 @@
|
||||
# Room/Light Structure Redesign Analysis
|
||||
|
||||
## Current Structure Analysis
|
||||
|
||||
### Current Organization
|
||||
|
||||
**Room-Centric Approach**:
|
||||
- 15 rooms, each with 1 `fb_switch` instance
|
||||
- Each room controls up to 6 lights
|
||||
- Network variables organized by room name
|
||||
- Structure: `l_masterBedroom.l_1`, `l_masterBedroom.l_2`, etc.
|
||||
|
||||
**Current Data Flow**:
|
||||
```
|
||||
Room → fb_switch → 6 lights
|
||||
Network Variable: l_masterBedroom (struct_lights with l_1 to l_6)
|
||||
```
|
||||
|
||||
### Current Issues
|
||||
|
||||
1. **Limited Scalability**
|
||||
- Fixed 6 lights per room
|
||||
- Adding a 7th light requires structure changes
|
||||
- Some rooms may only need 1-2 lights (waste)
|
||||
|
||||
2. **Home Assistant Organization**
|
||||
- HA entities: `light.master_bedroom_l1`, `light.master_bedroom_l2`
|
||||
- Not intuitive - hard to find lights
|
||||
- No grouping by function or zone
|
||||
|
||||
3. **Network Variable Efficiency**
|
||||
- 15 room structures × 6 lights = 90 potential lights
|
||||
- Most rooms don't use all 6 lights
|
||||
- Wasted network bandwidth
|
||||
|
||||
4. **Maintenance Complexity**
|
||||
- Changes require updating room structures
|
||||
- Hard to add new rooms
|
||||
- No clear naming convention
|
||||
|
||||
5. **MQTT Topic Structure**
|
||||
- Topics like: `homeassistant/light/master_bedroom_l1`
|
||||
- Not standardized
|
||||
- Hard to discover and manage
|
||||
|
||||
## Alternative Structures
|
||||
|
||||
### Option 1: Flat Light-Centric Structure (Recommended)
|
||||
|
||||
**Concept**: All lights in a single flat structure, organized by unique IDs.
|
||||
|
||||
**Data Structure**:
|
||||
```iec
|
||||
TYPE struct_light :
|
||||
STRUCT
|
||||
// Control
|
||||
on: BOOL; // Turn ON command
|
||||
off: BOOL; // Turn OFF command
|
||||
toggle: BOOL; // Toggle command (for Zigbee)
|
||||
|
||||
// Status
|
||||
state: BOOL; // Current state
|
||||
relay_status: BOOL; // Actual relay status
|
||||
|
||||
// Metadata (for reference, not in network var)
|
||||
room: STRING; // Room name
|
||||
name: STRING; // Light name
|
||||
zone: STRING; // Zone (indoor/outdoor)
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
|
||||
TYPE struct_all_lights :
|
||||
STRUCT
|
||||
// Master Bedroom
|
||||
master_bedroom_main: struct_light;
|
||||
master_bedroom_bedside: struct_light;
|
||||
master_bedroom_closet: struct_light;
|
||||
|
||||
// Kitchen
|
||||
kitchen_ceiling: struct_light;
|
||||
kitchen_under_cabinet: struct_light;
|
||||
kitchen_island: struct_light;
|
||||
|
||||
// Living Room
|
||||
living_room_main: struct_light;
|
||||
living_room_reading: struct_light;
|
||||
living_room_tv: struct_light;
|
||||
|
||||
// Outdoor
|
||||
outdoor_front_porch: struct_light;
|
||||
outdoor_back_patio: struct_light;
|
||||
outdoor_side: struct_light;
|
||||
|
||||
// ... all other lights
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
```
|
||||
|
||||
**Network Variable**:
|
||||
```iec
|
||||
VAR_GLOBAL
|
||||
lights: struct_all_lights; // All lights in one structure
|
||||
END_VAR
|
||||
```
|
||||
|
||||
**Function Block**:
|
||||
```iec
|
||||
FUNCTION_BLOCK fb_lightControl
|
||||
VAR_INPUT
|
||||
light: struct_light;
|
||||
relay_output: BOOL; // Direct relay output
|
||||
END_VAR
|
||||
VAR_OUTPUT
|
||||
relay_control: BOOL;
|
||||
light_status: struct_light;
|
||||
END_VAR
|
||||
// Implementation...
|
||||
END_FUNCTION_BLOCK
|
||||
```
|
||||
|
||||
**Pros**:
|
||||
- ✅ Each light is independent
|
||||
- ✅ Easy to add/remove lights
|
||||
- ✅ Clear naming: `lights.kitchen_ceiling.on`
|
||||
- ✅ Better for Home Assistant (one entity per light)
|
||||
- ✅ No wasted space
|
||||
- ✅ Easy to group in HA by room/zone
|
||||
|
||||
**Cons**:
|
||||
- ⚠️ Larger structure (but more efficient overall)
|
||||
- ⚠️ Need to update structure when adding lights
|
||||
|
||||
**Home Assistant Organization**:
|
||||
```
|
||||
light.kitchen_ceiling
|
||||
light.kitchen_under_cabinet
|
||||
light.master_bedroom_main
|
||||
light.master_bedroom_bedside
|
||||
```
|
||||
|
||||
**MQTT Topics**:
|
||||
```
|
||||
homeassistant/light/kitchen_ceiling/state
|
||||
homeassistant/light/kitchen_ceiling/set
|
||||
homeassistant/light/master_bedroom_main/state
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Option 2: Hierarchical Room → Light Structure
|
||||
|
||||
**Concept**: Keep room structure but make it more flexible.
|
||||
|
||||
**Data Structure**:
|
||||
```iec
|
||||
TYPE struct_room :
|
||||
STRUCT
|
||||
room_id: STRING; // "master_bedroom"
|
||||
room_name: STRING; // "Master Bedroom"
|
||||
zone: STRING; // "indoor", "outdoor"
|
||||
|
||||
// Flexible light array (up to 10 lights)
|
||||
lights: ARRAY[1..10] OF struct_light;
|
||||
light_count: INT; // Actual number of lights
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
|
||||
TYPE struct_home :
|
||||
STRUCT
|
||||
rooms: ARRAY[1..20] OF struct_room;
|
||||
room_count: INT;
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
```
|
||||
|
||||
**Pros**:
|
||||
- ✅ Maintains room grouping
|
||||
- ✅ Flexible number of lights per room
|
||||
- ✅ Can add rooms easily
|
||||
|
||||
**Cons**:
|
||||
- ⚠️ More complex array handling
|
||||
- ⚠️ CODESYS arrays less efficient for network vars
|
||||
- ⚠️ Harder to access specific lights
|
||||
|
||||
---
|
||||
|
||||
### Option 3: Zone-Based Structure
|
||||
|
||||
**Concept**: Organize by functional zones rather than rooms.
|
||||
|
||||
**Data Structure**:
|
||||
```iec
|
||||
TYPE struct_zone :
|
||||
STRUCT
|
||||
zone_id: STRING; // "indoor_main", "outdoor_security"
|
||||
zone_name: STRING; // "Indoor Main", "Outdoor Security"
|
||||
|
||||
// Lights in this zone
|
||||
lights: ARRAY[1..20] OF struct_light;
|
||||
light_count: INT;
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
|
||||
TYPE struct_home_zones :
|
||||
STRUCT
|
||||
indoor_main: struct_zone;
|
||||
indoor_bedrooms: struct_zone;
|
||||
indoor_bathrooms: struct_zone;
|
||||
outdoor_security: struct_zone;
|
||||
outdoor_ambient: struct_zone;
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
```
|
||||
|
||||
**Zones**:
|
||||
- **Indoor Main**: Kitchen, Living Room, Dining Room, Hallway
|
||||
- **Indoor Bedrooms**: All bedrooms
|
||||
- **Indoor Bathrooms**: All bathrooms
|
||||
- **Outdoor Security**: Front, Back, Side (security-focused)
|
||||
- **Outdoor Ambient**: Veranda, Patio (ambient lighting)
|
||||
|
||||
**Pros**:
|
||||
- ✅ Logical grouping for automation
|
||||
- ✅ Easy to control all security lights
|
||||
- ✅ Better for scheduling (indoor vs outdoor)
|
||||
|
||||
**Cons**:
|
||||
- ⚠️ Less intuitive for room-based control
|
||||
- ⚠️ Lights may belong to multiple zones conceptually
|
||||
|
||||
---
|
||||
|
||||
### Option 4: Hybrid: Room + Light ID Structure (Best Balance)
|
||||
|
||||
**Concept**: Combine room organization with individual light control.
|
||||
|
||||
**Data Structure**:
|
||||
```iec
|
||||
TYPE struct_light_control :
|
||||
STRUCT
|
||||
// Control
|
||||
on: BOOL;
|
||||
off: BOOL;
|
||||
toggle: BOOL;
|
||||
|
||||
// Status
|
||||
state: BOOL;
|
||||
relay_status: BOOL;
|
||||
|
||||
// Metadata (for HA, not in network var)
|
||||
light_id: STRING; // Unique ID: "mb_main", "kit_ceiling"
|
||||
light_name: STRING; // Display name: "Main Light", "Ceiling Light"
|
||||
room: STRING; // Room: "master_bedroom", "kitchen"
|
||||
zone: STRING; // Zone: "indoor", "outdoor"
|
||||
function: STRING; // Function: "main", "task", "ambient", "security"
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
|
||||
// Organized by room for CODESYS, but flat for HA
|
||||
TYPE struct_rooms :
|
||||
STRUCT
|
||||
// Master Bedroom
|
||||
master_bedroom: STRUCT
|
||||
main: struct_light_control;
|
||||
bedside_left: struct_light_control;
|
||||
bedside_right: struct_light_control;
|
||||
closet: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
// Kitchen
|
||||
kitchen: STRUCT
|
||||
ceiling: struct_light_control;
|
||||
under_cabinet: struct_light_control;
|
||||
island: struct_light_control;
|
||||
END_STRUCT;
|
||||
|
||||
// ... other rooms
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
```
|
||||
|
||||
**Network Variable**:
|
||||
```iec
|
||||
VAR_GLOBAL
|
||||
rooms: struct_rooms; // Organized by room
|
||||
END_VAR
|
||||
```
|
||||
|
||||
**Access Pattern**:
|
||||
- CODESYS: `rooms.kitchen.ceiling.on`
|
||||
- Node-RED: Flatten to `kitchen_ceiling` for HA
|
||||
- Home Assistant: `light.kitchen_ceiling`
|
||||
|
||||
**Pros**:
|
||||
- ✅ Best of both worlds
|
||||
- ✅ Organized in CODESYS (by room)
|
||||
- ✅ Flat in Home Assistant (by light)
|
||||
- ✅ Easy to add lights to rooms
|
||||
- ✅ Clear naming convention
|
||||
|
||||
**Cons**:
|
||||
- ⚠️ Requires Node-RED transformation
|
||||
- ⚠️ Slightly more complex
|
||||
|
||||
---
|
||||
|
||||
## Recommended Structure: Option 4 (Hybrid)
|
||||
|
||||
### Implementation
|
||||
|
||||
**1. CODESYS Structure** (Room-organized):
|
||||
```iec
|
||||
TYPE struct_light_control :
|
||||
STRUCT
|
||||
on: BOOL;
|
||||
off: BOOL;
|
||||
toggle: BOOL;
|
||||
state: BOOL;
|
||||
relay_status: BOOL;
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
|
||||
TYPE struct_room_lights :
|
||||
STRUCT
|
||||
main: struct_light_control;
|
||||
secondary: struct_light_control;
|
||||
task: struct_light_control;
|
||||
ambient: struct_light_control;
|
||||
accent: struct_light_control;
|
||||
security: struct_light_control;
|
||||
END_STRUCT
|
||||
END_TYPE
|
||||
|
||||
VAR_GLOBAL
|
||||
rooms: STRUCT
|
||||
master_bedroom: struct_room_lights;
|
||||
master_bathroom: struct_room_lights;
|
||||
bedroom_1: struct_room_lights;
|
||||
bedroom_2: struct_room_lights;
|
||||
bathroom: struct_room_lights;
|
||||
kitchen: struct_room_lights;
|
||||
living_room: struct_room_lights;
|
||||
dining_room: struct_room_lights;
|
||||
hallway: struct_room_lights;
|
||||
pantry: struct_room_lights;
|
||||
entrance: struct_room_lights;
|
||||
guest_wc: struct_room_lights;
|
||||
outdoor_veranda: struct_room_lights;
|
||||
outdoor_front: struct_room_lights;
|
||||
outdoor_side: struct_room_lights;
|
||||
outdoor_back: struct_room_lights;
|
||||
END_STRUCT;
|
||||
END_VAR
|
||||
```
|
||||
|
||||
**2. Node-RED Transformation** (Flatten for HA):
|
||||
```javascript
|
||||
// Transform CODESYS structure to flat HA structure
|
||||
function transformToHA(msg) {
|
||||
const rooms = msg.payload.rooms;
|
||||
const haLights = {};
|
||||
|
||||
// Flatten structure
|
||||
for (const [roomName, roomLights] of Object.entries(rooms)) {
|
||||
for (const [lightName, lightControl] of Object.entries(roomLights)) {
|
||||
const lightId = `${roomName}_${lightName}`;
|
||||
haLights[lightId] = {
|
||||
on: lightControl.on,
|
||||
off: lightControl.off,
|
||||
state: lightControl.state,
|
||||
status: lightControl.relay_status,
|
||||
room: roomName,
|
||||
light: lightName
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
return { payload: haLights };
|
||||
}
|
||||
```
|
||||
|
||||
**3. Home Assistant Configuration**:
|
||||
```yaml
|
||||
# Auto-discovery via MQTT
|
||||
light:
|
||||
- platform: mqtt
|
||||
name: "Kitchen Main"
|
||||
unique_id: "kitchen_main"
|
||||
state_topic: "homeassistant/light/kitchen_main/state"
|
||||
command_topic: "homeassistant/light/kitchen_main/set"
|
||||
# ... config
|
||||
```
|
||||
|
||||
**4. MQTT Topic Structure**:
|
||||
```
|
||||
homeassistant/light/{room}_{light}/state
|
||||
homeassistant/light/{room}_{light}/set
|
||||
|
||||
Examples:
|
||||
homeassistant/light/kitchen_main/state
|
||||
homeassistant/light/master_bedroom_main/state
|
||||
homeassistant/light/outdoor_front_security/state
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comparison Matrix
|
||||
|
||||
| Aspect | Current | Option 1 (Flat) | Option 2 (Hierarchical) | Option 3 (Zone) | Option 4 (Hybrid) |
|
||||
|--------|---------|-----------------|-------------------------|------------------|-------------------|
|
||||
| **CODESYS Organization** | Room-based | Flat | Array-based | Zone-based | Room-based |
|
||||
| **HA Organization** | Room-based | Flat | Complex | Zone-based | Flat (transformed) |
|
||||
| **Scalability** | Poor | Excellent | Good | Good | Excellent |
|
||||
| **Maintainability** | Medium | Excellent | Medium | Medium | Excellent |
|
||||
| **Network Efficiency** | Poor | Good | Medium | Medium | Good |
|
||||
| **Naming Clarity** | Medium | Excellent | Medium | Good | Excellent |
|
||||
| **Implementation Complexity** | Low | Medium | High | Medium | Medium |
|
||||
| **Flexibility** | Low | High | High | Medium | High |
|
||||
|
||||
---
|
||||
|
||||
## Optimization Recommendations
|
||||
|
||||
### 1. Network Variable Optimization
|
||||
|
||||
**Current**: 15 rooms × 6 lights = 90 potential lights
|
||||
**Optimized**: Only include lights that exist
|
||||
|
||||
**Example**:
|
||||
```iec
|
||||
// Only define lights that exist
|
||||
master_bedroom: STRUCT
|
||||
main: struct_light_control;
|
||||
bedside: struct_light_control;
|
||||
// No closet light if it doesn't exist
|
||||
END_STRUCT;
|
||||
```
|
||||
|
||||
### 2. Function-Based Naming
|
||||
|
||||
Instead of `l_1`, `l_2`, use descriptive names:
|
||||
- `main` - Main/primary light
|
||||
- `secondary` - Secondary light
|
||||
- `task` - Task lighting
|
||||
- `ambient` - Ambient/atmospheric
|
||||
- `accent` - Accent lighting
|
||||
- `security` - Security/outdoor
|
||||
|
||||
### 3. Metadata for Home Assistant
|
||||
|
||||
Add metadata structure (not in network var, but in Node-RED):
|
||||
```javascript
|
||||
const lightMetadata = {
|
||||
"kitchen_main": {
|
||||
name: "Kitchen Main Light",
|
||||
room: "Kitchen",
|
||||
zone: "indoor",
|
||||
function: "main",
|
||||
icon: "mdi:ceiling-light"
|
||||
},
|
||||
// ... more lights
|
||||
};
|
||||
```
|
||||
|
||||
### 4. Grouping in Home Assistant
|
||||
|
||||
Use HA groups and areas:
|
||||
```yaml
|
||||
# Automatically group by room
|
||||
light:
|
||||
- platform: group
|
||||
name: "Kitchen Lights"
|
||||
entities:
|
||||
- light.kitchen_main
|
||||
- light.kitchen_under_cabinet
|
||||
- light.kitchen_island
|
||||
|
||||
# Use areas for room organization
|
||||
areas:
|
||||
- name: "Kitchen"
|
||||
entities:
|
||||
- light.kitchen_main
|
||||
- light.kitchen_under_cabinet
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
### Phase 1: Structure Redesign
|
||||
1. Define new data structures
|
||||
2. Create mapping from old to new
|
||||
3. Update function blocks
|
||||
|
||||
### Phase 2: Node-RED Update
|
||||
1. Update network variable mapping
|
||||
2. Add transformation functions
|
||||
3. Update MQTT topics
|
||||
|
||||
### Phase 3: Home Assistant Migration
|
||||
1. Create new entities with new structure
|
||||
2. Migrate automations
|
||||
3. Update dashboards
|
||||
|
||||
### Phase 4: Testing & Validation
|
||||
1. Test all control paths
|
||||
2. Verify status feedback
|
||||
3. Test HA integration
|
||||
|
||||
---
|
||||
|
||||
## Final Recommendation
|
||||
|
||||
**Use Option 4 (Hybrid Structure)** because:
|
||||
|
||||
1. ✅ **Best Organization**: Room-based in CODESYS, flat in HA
|
||||
2. ✅ **Scalability**: Easy to add lights to any room
|
||||
3. ✅ **Clarity**: Descriptive names (`kitchen_main` vs `l_1`)
|
||||
4. ✅ **Flexibility**: Can group by room, zone, or function
|
||||
5. ✅ **Efficiency**: Only define lights that exist
|
||||
6. ✅ **Maintainability**: Clear structure, easy to understand
|
||||
|
||||
**Key Improvements**:
|
||||
- Replace `l_1`, `l_2` with `main`, `secondary`, `task`, etc.
|
||||
- Use descriptive light IDs: `kitchen_main`, `master_bedroom_bedside`
|
||||
- Flatten structure in Node-RED for Home Assistant
|
||||
- Add metadata for better HA organization
|
||||
- Optimize network variables (only existing lights)
|
||||
|
||||
---
|
||||
|
||||
**Next Steps**:
|
||||
1. Review this analysis
|
||||
2. Choose structure option
|
||||
3. Plan migration
|
||||
4. Implement new structure
|
||||
5. Update Node-RED and HA
|
||||
108
docs/reference/architecture.md
Normal file
108
docs/reference/architecture.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# System Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
The home automation system uses a distributed architecture with multiple components communicating over network protocols.
|
||||
|
||||
## Component Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Physical Layer │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Zigbee Switches │ Relays │ Water Boiler │ Lights │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Control Layer │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ CODESYS │◄────►│ Node-RED │ │
|
||||
│ │ (Raspberry │ │ │ │
|
||||
│ │ Pi) │ │ │ │
|
||||
│ └──────┬───────┘ └──────┬───────┘ │
|
||||
│ │ │ │
|
||||
│ │ │ │
|
||||
│ ┌──────▼───────┐ ┌──────▼───────┐ │
|
||||
│ │ EtherCAT │ │ MQTT │ │
|
||||
│ │ IO Card │ │ Broker │ │
|
||||
│ └──────────────┘ │ (LXC) │ │
|
||||
│ └──────┬───────┘ │
|
||||
│ │ │
|
||||
│ ┌──────▼───────┐ │
|
||||
│ │ Zigbee2MQTT │ │
|
||||
│ └──────┬───────┘ │
|
||||
│ │ │
|
||||
│ ┌──────▼───────┐ │
|
||||
│ │ Home │ │
|
||||
│ │ Assistant │ │
|
||||
│ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Communication Flow
|
||||
|
||||
### Light Switch Control Flow
|
||||
|
||||
1. **User Action**: Physical Zigbee switch is pressed
|
||||
2. **Zigbee2MQTT**: Receives Zigbee message, converts to MQTT
|
||||
3. **MQTT Broker**: Routes message to subscribers
|
||||
4. **Node-RED**: Receives MQTT message, processes automation logic
|
||||
5. **CODESYS**: Node-RED sends network variable to CODESYS
|
||||
6. **EtherCAT IO**: CODESYS activates relay via EtherCAT
|
||||
7. **Physical Device**: Relay controls light
|
||||
|
||||
### Water Boiler Control Flow
|
||||
|
||||
1. **Trigger**: Time-based, sensor-based, or manual trigger
|
||||
2. **Node-RED/Home Assistant**: Processes automation logic
|
||||
3. **CODESYS**: Receives control command via network variable
|
||||
4. **EtherCAT IO**: CODESYS activates relay for boiler
|
||||
5. **Water Boiler**: Receives control signal
|
||||
|
||||
## Protocols Used
|
||||
|
||||
- **EtherCAT**: Industrial communication between CODESYS and IO card
|
||||
- **MQTT**: Message queuing for device communication
|
||||
- **Zigbee**: Wireless mesh network for switches
|
||||
- **Network Variables**: CODESYS to Node-RED communication
|
||||
- **HTTP/REST**: Home Assistant API and Node-RED HTTP nodes
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Inputs
|
||||
- Zigbee switch states
|
||||
- Sensor data (if applicable)
|
||||
- Time-based triggers
|
||||
- Manual commands from Home Assistant
|
||||
|
||||
### Processing
|
||||
- Node-RED flows for automation logic
|
||||
- CODESYS control logic
|
||||
- Home Assistant automations
|
||||
|
||||
### Outputs
|
||||
- Relay control signals
|
||||
- Light states
|
||||
- Water boiler control
|
||||
- Dashboard updates
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- MQTT authentication (to be documented)
|
||||
- Network isolation (to be documented)
|
||||
- CODESYS access control (to be documented)
|
||||
- Zigbee network security (to be documented)
|
||||
|
||||
## Redundancy and Reliability
|
||||
|
||||
- [ ] Backup procedures
|
||||
- [ ] Failover mechanisms
|
||||
- [ ] Error recovery
|
||||
- [ ] Monitoring and alerting
|
||||
|
||||
---
|
||||
|
||||
**Status**: Initial structure - needs detailed information to complete
|
||||
124
docs/reference/hardware.md
Normal file
124
docs/reference/hardware.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# Hardware Inventory
|
||||
|
||||
## Overview
|
||||
|
||||
Complete inventory of physical hardware components in the home automation system.
|
||||
|
||||
## Control Hardware
|
||||
|
||||
### Raspberry Pi
|
||||
|
||||
- **Model**: [To be filled, e.g., Raspberry Pi 4 Model B]
|
||||
- **RAM**: [To be filled]
|
||||
- **Storage**: [To be filled]
|
||||
- **OS**: [To be filled]
|
||||
- **Purpose**: CODESYS Runtime
|
||||
- **Location**: [Physical location]
|
||||
- **Power Supply**: [To be filled]
|
||||
|
||||
### Beckhoff EtherCAT IO Card
|
||||
|
||||
- **Model**: [To be filled]
|
||||
- **Part Number**: [To be filled]
|
||||
- **I/O Channels**: [To be filled]
|
||||
- **Specifications**: [To be filled]
|
||||
- **Connection**: [EtherCAT connection details]
|
||||
|
||||
### Relay Module
|
||||
|
||||
- **Model**: [To be filled]
|
||||
- **Number of Channels**: [To be filled]
|
||||
- **Voltage/Current Ratings**: [To be filled]
|
||||
- **Connection**: [How it connects to EtherCAT card]
|
||||
|
||||
## Zigbee Hardware
|
||||
|
||||
### Coordinator
|
||||
|
||||
- **Model**: [To be filled, e.g., CC2531, CC2652, etc.]
|
||||
- **Firmware**: [To be filled]
|
||||
- **Connection**: [USB, Ethernet, etc.]
|
||||
- **Location**: [Physical location for optimal coverage]
|
||||
|
||||
### Zigbee Switches
|
||||
|
||||
| Switch # | Model | Location | Functions | Notes |
|
||||
|----------|-------|----------|------------|-------|
|
||||
| 1 | [Model] | [Location] | [Functions] | |
|
||||
| 2 | [Model] | [Location] | [Functions] | |
|
||||
| ... | | | | |
|
||||
|
||||
## Controlled Devices
|
||||
|
||||
### Lighting
|
||||
|
||||
| Light # | Type | Location | Controlled By | Relay # |
|
||||
|---------|------|----------|---------------|---------|
|
||||
| 1 | [Type] | [Location] | [Switch/Relay] | [Relay #] |
|
||||
| 2 | [Type] | [Location] | [Switch/Relay] | [Relay #] |
|
||||
| ... | | | | |
|
||||
|
||||
### Water Boiler
|
||||
|
||||
- **Model**: [To be filled]
|
||||
- **Type**: [To be filled]
|
||||
- **Control Interface**: [To be filled]
|
||||
- **Relay Assignment**: [To be filled]
|
||||
- **Safety Features**: [To be filled]
|
||||
|
||||
## Network Hardware
|
||||
|
||||
### Switches
|
||||
|
||||
- **Model**: [To be filled]
|
||||
- **Ports**: [To be filled]
|
||||
- **Features**: [VLAN support, PoE, etc.]
|
||||
|
||||
### Routers/Gateways
|
||||
|
||||
- **Model**: [To be filled]
|
||||
- **Configuration**: [To be filled]
|
||||
|
||||
## Host Systems
|
||||
|
||||
### LXC Host
|
||||
|
||||
- **Hardware**: [To be filled]
|
||||
- **OS**: [To be filled]
|
||||
- **Containers**: [List containers]
|
||||
|
||||
### Other Hosts
|
||||
|
||||
[Document other physical or virtual hosts]
|
||||
|
||||
## Wiring
|
||||
|
||||
### Power Distribution
|
||||
|
||||
[Document power distribution if relevant]
|
||||
|
||||
### Low Voltage Wiring
|
||||
|
||||
[Document low voltage wiring for relays, sensors, etc.]
|
||||
|
||||
### Network Cabling
|
||||
|
||||
[Document network cable runs if relevant]
|
||||
|
||||
## Physical Layout
|
||||
|
||||
[Describe or diagram the physical layout of hardware]
|
||||
|
||||
## Spare Parts
|
||||
|
||||
- **Spare Components**: [List]
|
||||
- **Replacement Parts**: [List]
|
||||
|
||||
## Maintenance Schedule
|
||||
|
||||
- **Regular Maintenance**: [Schedule]
|
||||
- **Component Lifespan**: [Expected lifespan of components]
|
||||
|
||||
---
|
||||
|
||||
**Status**: Template - needs hardware details
|
||||
89
docs/reference/network.md
Normal file
89
docs/reference/network.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# Network Topology
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes the network configuration and topology of the home automation system.
|
||||
|
||||
## Network Diagram
|
||||
|
||||
```
|
||||
[To be created with actual IP addresses]
|
||||
```
|
||||
|
||||
## IP Address Assignments
|
||||
|
||||
| Device/Service | IP Address | MAC Address | Hostname | Notes |
|
||||
|----------------|------------|-------------|----------|-------|
|
||||
| Raspberry Pi (CODESYS) | [To be filled] | [To be filled] | [To be filled] | |
|
||||
| Node-RED Host | [To be filled] | [To be filled] | [To be filled] | |
|
||||
| MQTT Broker (LXC) | [To be filled] | [To be filled] | [To be filled] | |
|
||||
| Zigbee2MQTT Host | [To be filled] | [To be filled] | [To be filled] | |
|
||||
| Home Assistant | [To be filled] | [To be filled] | [To be filled] | |
|
||||
|
||||
## Network Segments
|
||||
|
||||
### Subnets
|
||||
|
||||
- **Main Network**: [Subnet/CIDR]
|
||||
- **IoT Network**: [If separate VLAN/subnet]
|
||||
- **Management Network**: [If separate]
|
||||
|
||||
### VLANs
|
||||
|
||||
[If VLANs are used]
|
||||
|
||||
## Port Assignments
|
||||
|
||||
| Service | Protocol | Port | Access | Notes |
|
||||
|---------|----------|------|--------|-------|
|
||||
| MQTT | TCP | 1883 | Internal | |
|
||||
| MQTT TLS | TCP | 8883 | Internal | If enabled |
|
||||
| Node-RED | HTTP | [Port] | [Access] | |
|
||||
| Home Assistant | HTTP | [Port] | [Access] | |
|
||||
| CODESYS | [Protocol] | [Port] | [Access] | |
|
||||
| Zigbee2MQTT | HTTP | [Port] | [Access] | |
|
||||
|
||||
## Firewall Rules
|
||||
|
||||
[Document firewall rules if applicable]
|
||||
|
||||
## DNS
|
||||
|
||||
- **Internal DNS**: [If used]
|
||||
- **Hostname Resolution**: [How devices find each other]
|
||||
|
||||
## Routing
|
||||
|
||||
[If complex routing is involved]
|
||||
|
||||
## Network Services
|
||||
|
||||
### DHCP
|
||||
|
||||
- **DHCP Server**: [To be filled]
|
||||
- **Reserved IPs**: [List if static IPs are reserved]
|
||||
|
||||
### DNS
|
||||
|
||||
- **DNS Servers**: [To be filled]
|
||||
|
||||
## Security
|
||||
|
||||
- **Network Isolation**: [To be filled]
|
||||
- **VPN Access**: [If applicable]
|
||||
- **Remote Access**: [How remote access is configured]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Network Connectivity
|
||||
|
||||
- **Ping Tests**: [How to test connectivity]
|
||||
- **Port Checks**: [How to verify ports are open]
|
||||
|
||||
### Common Issues
|
||||
|
||||
- [Issue]: [Solution]
|
||||
|
||||
---
|
||||
|
||||
**Status**: Template - needs IP addresses and network details
|
||||
125
docs/reference/quick-reference.md
Normal file
125
docs/reference/quick-reference.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# Quick Reference Guide
|
||||
|
||||
## System Overview
|
||||
|
||||
- **Control System**: CODESYS on Raspberry Pi
|
||||
- **Automation**: Node-RED
|
||||
- **Message Bus**: MQTT (LXC container)
|
||||
- **Zigbee Bridge**: Zigbee2MQTT
|
||||
- **Dashboard**: Home Assistant
|
||||
|
||||
## Quick Access
|
||||
|
||||
### Service URLs
|
||||
|
||||
- **Home Assistant**: [To be filled]
|
||||
- **Node-RED**: [To be filled]
|
||||
- **Zigbee2MQTT**: [To be filled]
|
||||
- **MQTT Broker**: [To be filled]
|
||||
|
||||
### Important IPs
|
||||
|
||||
- **Raspberry Pi (CODESYS)**: [To be filled]
|
||||
- **MQTT Broker**: [To be filled]
|
||||
|
||||
### Important Ports
|
||||
|
||||
- **MQTT**: 1883 (or 8883 for TLS)
|
||||
- **Node-RED**: [To be filled]
|
||||
- **Home Assistant**: [To be filled]
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Restart Services
|
||||
|
||||
```bash
|
||||
# MQTT Broker (LXC)
|
||||
lxc restart [container-name]
|
||||
|
||||
# Node-RED
|
||||
systemctl restart nodered
|
||||
|
||||
# Home Assistant
|
||||
[Command to restart]
|
||||
|
||||
# Zigbee2MQTT
|
||||
[Command to restart]
|
||||
```
|
||||
|
||||
### Check Service Status
|
||||
|
||||
```bash
|
||||
# MQTT
|
||||
mosquitto_sub -h [broker-ip] -t '#' -v
|
||||
|
||||
# Node-RED
|
||||
[Command]
|
||||
|
||||
# Home Assistant
|
||||
[Command]
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
- **Node-RED**: [Location]
|
||||
- **Home Assistant**: [Location]
|
||||
- **Zigbee2MQTT**: [Location]
|
||||
- **MQTT**: [Location]
|
||||
|
||||
## MQTT Topics
|
||||
|
||||
### Key Topics
|
||||
|
||||
- `zigbee2mqtt/[device]/set` - Control Zigbee device
|
||||
- `zigbee2mqtt/[device]` - Device state
|
||||
- `codesys/[variable]` - CODESYS variables
|
||||
- `homeassistant/[entity]` - Home Assistant entities
|
||||
|
||||
## Device Control
|
||||
|
||||
### Control Light via MQTT
|
||||
|
||||
```bash
|
||||
mosquitto_pub -h [broker-ip] -t "zigbee2mqtt/[switch-name]/set" -m '{"state": "ON"}'
|
||||
```
|
||||
|
||||
### Control Relay via CODESYS
|
||||
|
||||
[Instructions]
|
||||
|
||||
## Troubleshooting Quick Fixes
|
||||
|
||||
### Light Not Responding
|
||||
|
||||
1. Check Zigbee device status in Zigbee2MQTT
|
||||
2. Verify MQTT message flow
|
||||
3. Check Node-RED flow
|
||||
4. Verify CODESYS network variable
|
||||
5. Check relay state
|
||||
|
||||
### MQTT Connection Issues
|
||||
|
||||
1. Verify broker is running
|
||||
2. Check network connectivity
|
||||
3. Verify credentials
|
||||
4. Check firewall rules
|
||||
|
||||
### CODESYS Not Communicating
|
||||
|
||||
1. Check network variables configuration
|
||||
2. Verify Node-RED connection
|
||||
3. Check CODESYS runtime status
|
||||
|
||||
## Emergency Procedures
|
||||
|
||||
### Manual Override
|
||||
|
||||
[How to manually control devices if automation fails]
|
||||
|
||||
### System Reset
|
||||
|
||||
[Procedure for resetting the system]
|
||||
|
||||
---
|
||||
|
||||
**Status**: Template - needs actual values and commands
|
||||
76
docs/reference/setup.md
Normal file
76
docs/reference/setup.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# Setup Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide provides step-by-step instructions for setting up the home automation system from scratch.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [ ] Hardware components assembled
|
||||
- [ ] Network infrastructure in place
|
||||
- [ ] Access to all devices
|
||||
- [ ] Required software licenses (CODESYS)
|
||||
|
||||
## Installation Order
|
||||
|
||||
1. Network Configuration
|
||||
2. MQTT Broker Setup
|
||||
3. CODESYS Installation
|
||||
4. Node-RED Installation
|
||||
5. Zigbee2MQTT Setup
|
||||
6. Home Assistant Installation
|
||||
7. Integration Configuration
|
||||
|
||||
## Step-by-Step Setup
|
||||
|
||||
### 1. Network Configuration
|
||||
|
||||
[Detailed network setup instructions]
|
||||
|
||||
### 2. MQTT Broker (LXC)
|
||||
|
||||
[Instructions for setting up MQTT broker in LXC container]
|
||||
|
||||
### 3. CODESYS on Raspberry Pi
|
||||
|
||||
[Instructions for installing and configuring CODESYS]
|
||||
|
||||
### 4. Node-RED
|
||||
|
||||
[Instructions for installing and configuring Node-RED]
|
||||
|
||||
### 5. Zigbee2MQTT
|
||||
|
||||
[Instructions for setting up Zigbee2MQTT]
|
||||
|
||||
### 6. Home Assistant
|
||||
|
||||
[Instructions for installing and configuring Home Assistant]
|
||||
|
||||
### 7. Integration
|
||||
|
||||
[Instructions for connecting all components]
|
||||
|
||||
## Configuration Files
|
||||
|
||||
[Links to or locations of configuration files]
|
||||
|
||||
## Verification
|
||||
|
||||
### Testing Checklist
|
||||
|
||||
- [ ] MQTT broker is accessible
|
||||
- [ ] CODESYS can communicate with Node-RED
|
||||
- [ ] Zigbee devices are paired
|
||||
- [ ] Node-RED flows are working
|
||||
- [ ] Home Assistant can see all entities
|
||||
- [ ] Switches control lights correctly
|
||||
- [ ] Water boiler control works
|
||||
|
||||
## Troubleshooting Setup Issues
|
||||
|
||||
[Common setup problems and solutions]
|
||||
|
||||
---
|
||||
|
||||
**Status**: Template - needs detailed setup instructions
|
||||
Reference in New Issue
Block a user